@taodigital/crawler 0.0.0-stage → 1.2.0

package/dist/response-cache.js

@@ -0,0 +1,140 @@
+import { createHash } from "node:crypto";
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+class ResponseCache {
+  dir;
+  totalHits = 0;
+  totalRequests = 0;
+  constructor(cacheDir) {
+    this.dir = cacheDir;
+    if (!existsSync(cacheDir)) mkdirSync(cacheDir, { recursive: true });
+  }
+  key(url) {
+    return createHash("sha256").update(url).digest("hex").slice(0, 16);
+  }
+  path(url) {
+    return join(this.dir, `${this.key(url)}.json`);
+  }
+  get(url) {
+    this.totalRequests++;
+    try {
+      const p = this.path(url);
+      if (!existsSync(p)) return null;
+      const entry = JSON.parse(readFileSync(p, "utf-8"));
+      this.totalHits++;
+      return entry;
+    } catch {
+      return null;
+    }
+  }
+  read(url) {
+    try {
+      const p = this.path(url);
+      if (!existsSync(p)) return null;
+      return JSON.parse(readFileSync(p, "utf-8"));
+    } catch {
+      return null;
+    }
+  }
+  isFresh(url) {
+    const entry = this.read(url);
+    if (!entry?.cacheControl) return false;
+    const m = /max-age=(\d+)/i.exec(entry.cacheControl);
+    if (!m) return false;
+    const maxAgeMs = parseInt(m[1], 10) * 1e3;
+    return entry.cachedAt + maxAgeMs > Date.now();
+  }
+  staleIfError(url) {
+    const entry = this.read(url);
+    if (!entry?.cacheControl) return false;
+    const m = /stale-if-error=(\d+)/i.exec(entry.cacheControl);
+    if (!m) return false;
+    const staleIfErrorMs = parseInt(m[1], 10) * 1e3;
+    return entry.cachedAt + staleIfErrorMs >= Date.now();
+  }
+  set(url, entry) {
+    try {
+      const full = { ...entry, cachedAt: Date.now(), hitCount: 0 };
+      writeFileSync(this.path(url), JSON.stringify(full), "utf-8");
+    } catch {
+    }
+  }
+  getValidationHeaders(url) {
+    const entry = this.get(url);
+    if (!entry) return {};
+    const headers = {};
+    if (entry.etag) headers["If-None-Match"] = entry.etag;
+    if (entry.lastModified) headers["If-Modified-Since"] = entry.lastModified;
+    return headers;
+  }
+  markHit(url) {
+    try {
+      const p = this.path(url);
+      if (!existsSync(p)) return;
+      const entry = JSON.parse(readFileSync(p, "utf-8"));
+      entry.hitCount++;
+      writeFileSync(p, JSON.stringify(entry), "utf-8");
+    } catch {
+    }
+  }
+  invalidate(url) {
+    try {
+      const p = this.path(url);
+      if (existsSync(p)) unlinkSync(p);
+    } catch {
+    }
+  }
+  clear() {
+    try {
+      for (const f of readdirSync(this.dir)) {
+        if (f.endsWith(".json")) unlinkSync(join(this.dir, f));
+      }
+    } catch {
+    }
+  }
+  stats() {
+    let entries = 0;
+    let totalSizeBytes = 0;
+    try {
+      for (const f of readdirSync(this.dir)) {
+        if (!f.endsWith(".json")) continue;
+        entries++;
+        try {
+          totalSizeBytes += statSync(join(this.dir, f)).size;
+        } catch {
+        }
+      }
+    } catch {
+    }
+    return {
+      entries,
+      totalSizeBytes,
+      hitRate: this.totalRequests > 0 ? this.totalHits / this.totalRequests : 0,
+      totalHits: this.totalHits
+    };
+  }
+  prune(maxAgeMs) {
+    let deleted = 0;
+    const cutoff = Date.now() - maxAgeMs;
+    try {
+      for (const f of readdirSync(this.dir)) {
+        if (!f.endsWith(".json")) continue;
+        try {
+          const p = join(this.dir, f);
+          const entry = JSON.parse(readFileSync(p, "utf-8"));
+          if (entry.cachedAt < cutoff) {
+            unlinkSync(p);
+            deleted++;
+          }
+        } catch {
+        }
+      }
+    } catch {
+    }
+    return deleted;
+  }
+}
+export {
+  ResponseCache
+};
+//# sourceMappingURL=response-cache.js.map

package/dist/response-cache.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/response-cache.ts"],
+  "sourcesContent": ["import { createHash } from 'node:crypto';\nimport { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync, unlinkSync } from 'node:fs';\nimport { join } from 'node:path';\n\nexport interface ResponseCacheEntry {\n  url: string;\n  etag?: string;\n  lastModified?: string;\n  cacheControl?: string;\n  body: string;\n  contentType: string;\n  statusCode: number;\n  cachedAt: number;\n  hitCount: number;\n}\n\nexport class ResponseCache {\n  private readonly dir: string;\n  private totalHits = 0;\n  private totalRequests = 0;\n\n  constructor(cacheDir: string) {\n    this.dir = cacheDir;\n    if (!existsSync(cacheDir)) mkdirSync(cacheDir, { recursive: true });\n  }\n\n  private key(url: string): string {\n    return createHash('sha256').update(url).digest('hex').slice(0, 16);\n  }\n\n  private path(url: string): string {\n    return join(this.dir, `${this.key(url)}.json`);\n  }\n\n  get(url: string): ResponseCacheEntry | null {\n    this.totalRequests++;\n    try {\n      const p = this.path(url);\n      if (!existsSync(p)) return null;\n      const entry: ResponseCacheEntry = JSON.parse(readFileSync(p, 'utf-8'));\n      this.totalHits++;\n      return entry;\n    } catch {\n      return null;\n    }\n  }\n\n  private read(url: string): ResponseCacheEntry | null {\n    try {\n      const p = this.path(url);\n      if (!existsSync(p)) return null;\n      return JSON.parse(readFileSync(p, 'utf-8')) as ResponseCacheEntry;\n    } catch {\n      return null;\n    }\n  }\n\n  isFresh(url: string): boolean {\n    const entry = this.read(url);\n    if (!entry?.cacheControl) return false;\n    const m = /max-age=(\\d+)/i.exec(entry.cacheControl);\n    if (!m) return false;\n    const maxAgeMs = parseInt(m[1], 10) * 1000;\n    return entry.cachedAt + maxAgeMs > Date.now();\n  }\n\n  staleIfError(url: string): boolean {\n    const entry = this.read(url);\n    if (!entry?.cacheControl) return false;\n    const m = /stale-if-error=(\\d+)/i.exec(entry.cacheControl);\n    if (!m) return false;\n    const staleIfErrorMs = parseInt(m[1], 10) * 1000;\n    return entry.cachedAt + staleIfErrorMs >= Date.now();\n  }\n\n  set(url: string, entry: Omit<ResponseCacheEntry, 'cachedAt' | 'hitCount'>): void {\n    try {\n      const full: ResponseCacheEntry = { ...entry, cachedAt: Date.now(), hitCount: 0 };\n      writeFileSync(this.path(url), JSON.stringify(full), 'utf-8');\n    } catch { /* non-fatal */ }\n  }\n\n  getValidationHeaders(url: string): { 'If-None-Match'?: string; 'If-Modified-Since'?: string } {\n    const entry = this.get(url);\n    if (!entry) return {};\n    const headers: { 'If-None-Match'?: string; 'If-Modified-Since'?: string } = {};\n    if (entry.etag) headers['If-None-Match'] = entry.etag;\n    if (entry.lastModified) headers['If-Modified-Since'] = entry.lastModified;\n    return headers;\n  }\n\n  markHit(url: string): void {\n    try {\n      const p = this.path(url);\n      if (!existsSync(p)) return;\n      const entry: ResponseCacheEntry = JSON.parse(readFileSync(p, 'utf-8'));\n      entry.hitCount++;\n      writeFileSync(p, JSON.stringify(entry), 'utf-8');\n    } catch { /* non-fatal */ }\n  }\n\n  invalidate(url: string): void {\n    try {\n      const p = this.path(url);\n      if (existsSync(p)) unlinkSync(p);\n    } catch { /* non-fatal */ }\n  }\n\n  clear(): void {\n    try {\n      for (const f of readdirSync(this.dir)) {\n        if (f.endsWith('.json')) unlinkSync(join(this.dir, f));\n      }\n    } catch { /* non-fatal */ }\n  }\n\n  stats(): { entries: number; totalSizeBytes: number; hitRate: number; totalHits: number } {\n    let entries = 0;\n    let totalSizeBytes = 0;\n    try {\n      for (const f of readdirSync(this.dir)) {\n        if (!f.endsWith('.json')) continue;\n        entries++;\n        try { totalSizeBytes += statSync(join(this.dir, f)).size; } catch { /* skip */ }\n      }\n    } catch { /* non-fatal */ }\n    return {\n      entries,\n      totalSizeBytes,\n      hitRate: this.totalRequests > 0 ? this.totalHits / this.totalRequests : 0,\n      totalHits: this.totalHits,\n    };\n  }\n\n  prune(maxAgeMs: number): number {\n    let deleted = 0;\n    const cutoff = Date.now() - maxAgeMs;\n    try {\n      for (const f of readdirSync(this.dir)) {\n        if (!f.endsWith('.json')) continue;\n        try {\n          const p = join(this.dir, f);\n          const entry: ResponseCacheEntry = JSON.parse(readFileSync(p, 'utf-8'));\n          if (entry.cachedAt < cutoff) { unlinkSync(p); deleted++; }\n        } catch { /* skip */ }\n      }\n    } catch { /* non-fatal */ }\n    return deleted;\n  }\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/responsive-detector.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Responsive design detector — captures page at multiple breakpoints
+ * and detects layout differences between desktop and mobile viewports.
+ *
+ * Breakpoints: mobile(375), tablet(768), desktop(1280), wide(1920)
+ * Detects: viewport-specific content visibility, menu collapse state,
+ * font size changes, hidden/shown elements.
+ */
+import type { Page } from 'playwright';
+export interface ViewportCapture {
+    width: number;
+    height: number;
+    label: 'mobile' | 'tablet' | 'desktop' | 'wide';
+    screenshotBuffer?: Buffer;
+    visibleTextLength: number;
+    hasHamburgerMenu: boolean;
+    hiddenElements: number;
+    scrollHeight: number;
+}
+export interface ResponsiveReport {
+    url: string;
+    captures: ViewportCapture[];
+    isResponsive: boolean;
+    hasMobileMenu: boolean;
+    issues: string[];
+}
+export declare function detectResponsive(page: Page, url: string, opts?: {
+    captureScreenshots?: boolean;
+}): Promise<ResponsiveReport>;

package/dist/responsive-detector.js

@@ -0,0 +1,46 @@
+const BREAKPOINTS = [
+  { width: 375, height: 812, label: "mobile" },
+  { width: 768, height: 1024, label: "tablet" },
+  { width: 1280, height: 800, label: "desktop" }
+];
+async function detectResponsive(page, url, opts = {}) {
+  const captures = [];
+  const issues = [];
+  for (const bp of BREAKPOINTS) {
+    try {
+      await page.setViewportSize({ width: bp.width, height: bp.height });
+      await page.waitForTimeout(500);
+      const data = await page.evaluate(() => ({
+        visibleTextLength: (document.body.innerText ?? "").length,
+        hasHamburgerMenu: !!document.querySelector('[class*="hamburger"],[class*="menu-toggle"],[class*="nav-toggle"],[aria-label*="menu"],[aria-label*="Menu"]'),
+        hiddenElements: Array.from(document.querySelectorAll("*")).filter(
+          (el) => window.getComputedStyle(el).display === "none"
+        ).length,
+        scrollHeight: document.body.scrollHeight
+      })).catch(() => ({ visibleTextLength: 0, hasHamburgerMenu: false, hiddenElements: 0, scrollHeight: 0 }));
+      let screenshotBuffer;
+      if (opts.captureScreenshots) {
+        screenshotBuffer = await page.screenshot({ type: "jpeg", quality: 60 }).catch(() => void 0);
+      }
+      captures.push({ ...bp, ...data, screenshotBuffer });
+    } catch {
+    }
+  }
+  await page.setViewportSize({ width: 1280, height: 800 }).catch(() => {
+  });
+  const mobile = captures.find((c) => c.label === "mobile");
+  const desktop = captures.find((c) => c.label === "desktop");
+  const isResponsive = !!(mobile && desktop && (mobile.hiddenElements !== desktop.hiddenElements || mobile.scrollHeight !== desktop.scrollHeight || mobile.hasHamburgerMenu));
+  const hasMobileMenu = captures.some((c) => c.label === "mobile" && c.hasHamburgerMenu);
+  if (mobile && desktop && mobile.visibleTextLength > desktop.visibleTextLength * 1.3) {
+    issues.push("Mobile shows significantly more text than desktop \u2014 possible responsive issue");
+  }
+  if (!isResponsive && captures.length > 1) {
+    issues.push("Layout appears identical across breakpoints \u2014 may not be responsive");
+  }
+  return { url, captures, isResponsive, hasMobileMenu, issues };
+}
+export {
+  detectResponsive
+};
+//# sourceMappingURL=responsive-detector.js.map

package/dist/responsive-detector.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/responsive-detector.ts"],
+  "sourcesContent": ["/**\n * Responsive design detector \u2014 captures page at multiple breakpoints\n * and detects layout differences between desktop and mobile viewports.\n *\n * Breakpoints: mobile(375), tablet(768), desktop(1280), wide(1920)\n * Detects: viewport-specific content visibility, menu collapse state,\n * font size changes, hidden/shown elements.\n */\n\nimport type { Page } from 'playwright';\n\nexport interface ViewportCapture {\n  width: number;\n  height: number;\n  label: 'mobile' | 'tablet' | 'desktop' | 'wide';\n  screenshotBuffer?: Buffer;\n  visibleTextLength: number;\n  hasHamburgerMenu: boolean;\n  hiddenElements: number; // display:none element count\n  scrollHeight: number;\n}\n\nexport interface ResponsiveReport {\n  url: string;\n  captures: ViewportCapture[];\n  isResponsive: boolean; // true if layout changes between viewports\n  hasMobileMenu: boolean;\n  issues: string[];\n}\n\nconst BREAKPOINTS: Array<{ width: number; height: number; label: ViewportCapture['label'] }> = [\n  { width: 375, height: 812, label: 'mobile' },\n  { width: 768, height: 1024, label: 'tablet' },\n  { width: 1280, height: 800, label: 'desktop' },\n];\n\nexport async function detectResponsive(\n  page: Page,\n  url: string,\n  opts: { captureScreenshots?: boolean } = {},\n): Promise<ResponsiveReport> {\n  const captures: ViewportCapture[] = [];\n  const issues: string[] = [];\n\n  for (const bp of BREAKPOINTS) {\n    try {\n      await page.setViewportSize({ width: bp.width, height: bp.height });\n      await page.waitForTimeout(500); // allow CSS reflow\n\n      const data = await page.evaluate(() => ({\n        visibleTextLength: (document.body.innerText ?? '').length,\n        hasHamburgerMenu: !!(\n          document.querySelector('[class*=\"hamburger\"],[class*=\"menu-toggle\"],[class*=\"nav-toggle\"],[aria-label*=\"menu\"],[aria-label*=\"Menu\"]')\n        ),\n        hiddenElements: Array.from(document.querySelectorAll('*')).filter(\n          (el: any) => window.getComputedStyle(el).display === 'none'\n        ).length,\n        scrollHeight: document.body.scrollHeight,\n      })).catch(() => ({ visibleTextLength: 0, hasHamburgerMenu: false, hiddenElements: 0, scrollHeight: 0 }));\n\n      let screenshotBuffer: Buffer | undefined;\n      if (opts.captureScreenshots) {\n        screenshotBuffer = await page.screenshot({ type: 'jpeg', quality: 60 }).catch(() => undefined);\n      }\n\n      captures.push({ ...bp, ...data, screenshotBuffer });\n    } catch { /* viewport failed \u2014 skip */ }\n  }\n\n  // Restore to desktop\n  await page.setViewportSize({ width: 1280, height: 800 }).catch(() => {});\n\n  const mobile = captures.find(c => c.label === 'mobile');\n  const desktop = captures.find(c => c.label === 'desktop');\n\n  const isResponsive = !!(mobile && desktop && (\n    mobile.hiddenElements !== desktop.hiddenElements ||\n    mobile.scrollHeight !== desktop.scrollHeight ||\n    mobile.hasHamburgerMenu\n  ));\n\n  const hasMobileMenu = captures.some(c => c.label === 'mobile' && c.hasHamburgerMenu);\n\n  if (mobile && desktop && mobile.visibleTextLength > desktop.visibleTextLength * 1.3) {\n    issues.push('Mobile shows significantly more text than desktop \u2014 possible responsive issue');\n  }\n  if (!isResponsive && captures.length > 1) {\n    issues.push('Layout appears identical across breakpoints \u2014 may not be responsive');\n  }\n\n  return { url, captures, isResponsive, hasMobileMenu, issues };\n}\n"],
+  "mappings": "AA8BA,MAAM,cAAyF;AAAA,EAC7F,EAAE,OAAO,KAAK,QAAQ,KAAK,OAAO,SAAS;AAAA,EAC3C,EAAE,OAAO,KAAK,QAAQ,MAAM,OAAO,SAAS;AAAA,EAC5C,EAAE,OAAO,MAAM,QAAQ,KAAK,OAAO,UAAU;AAC/C;AAEA,eAAsB,iBACpB,MACA,KACA,OAAyC,CAAC,GACf;AAC3B,QAAM,WAA8B,CAAC;AACrC,QAAM,SAAmB,CAAC;AAE1B,aAAW,MAAM,aAAa;AAC5B,QAAI;AACF,YAAM,KAAK,gBAAgB,EAAE,OAAO,GAAG,OAAO,QAAQ,GAAG,OAAO,CAAC;AACjE,YAAM,KAAK,eAAe,GAAG;AAE7B,YAAM,OAAO,MAAM,KAAK,SAAS,OAAO;AAAA,QACtC,oBAAoB,SAAS,KAAK,aAAa,IAAI;AAAA,QACnD,kBAAkB,CAAC,CACjB,SAAS,cAAc,6GAA6G;AAAA,QAEtI,gBAAgB,MAAM,KAAK,SAAS,iBAAiB,GAAG,CAAC,EAAE;AAAA,UACzD,CAAC,OAAY,OAAO,iBAAiB,EAAE,EAAE,YAAY;AAAA,QACvD,EAAE;AAAA,QACF,cAAc,SAAS,KAAK;AAAA,MAC9B,EAAE,EAAE,MAAM,OAAO,EAAE,mBAAmB,GAAG,kBAAkB,OAAO,gBAAgB,GAAG,cAAc,EAAE,EAAE;AAEvG,UAAI;AACJ,UAAI,KAAK,oBAAoB;AAC3B,2BAAmB,MAAM,KAAK,WAAW,EAAE,MAAM,QAAQ,SAAS,GAAG,CAAC,EAAE,MAAM,MAAM,MAAS;AAAA,MAC/F;AAEA,eAAS,KAAK,EAAE,GAAG,IAAI,GAAG,MAAM,iBAAiB,CAAC;AAAA,IACpD,QAAQ;AAAA,IAA+B;AAAA,EACzC;AAGA,QAAM,KAAK,gBAAgB,EAAE,OAAO,MAAM,QAAQ,IAAI,CAAC,EAAE,MAAM,MAAM;AAAA,EAAC,CAAC;AAEvE,QAAM,SAAS,SAAS,KAAK,OAAK,EAAE,UAAU,QAAQ;AACtD,QAAM,UAAU,SAAS,KAAK,OAAK,EAAE,UAAU,SAAS;AAExD,QAAM,eAAe,CAAC,EAAE,UAAU,YAChC,OAAO,mBAAmB,QAAQ,kBAClC,OAAO,iBAAiB,QAAQ,gBAChC,OAAO;AAGT,QAAM,gBAAgB,SAAS,KAAK,OAAK,EAAE,UAAU,YAAY,EAAE,gBAAgB;AAEnF,MAAI,UAAU,WAAW,OAAO,oBAAoB,QAAQ,oBAAoB,KAAK;AACnF,WAAO,KAAK,oFAA+E;AAAA,EAC7F;AACA,MAAI,CAAC,gBAAgB,SAAS,SAAS,GAAG;AACxC,WAAO,KAAK,0EAAqE;AAAA,EACnF;AAEA,SAAO,EAAE,KAAK,UAAU,cAAc,eAAe,OAAO;AAC9D;",
+  "names": []
+}

package/dist/retry-policy.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Retry policy — configurable exponential backoff with jitter.
+ * Covers: 5xx server errors, network timeouts, ECONNREFUSED, ECONNRESET.
+ * NOT retried: 4xx client errors (except 429 — handled separately), redirects.
+ */
+export interface RetryPolicyOpts {
+    maxRetries?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    jitterMs?: number;
+    retryOn?: number[];
+}
+export interface RetryResult<T> {
+    value: T;
+    attempts: number;
+    totalDelayMs: number;
+}
+export declare function withRetry<T>(fn: (attempt: number) => Promise<T>, opts?: RetryPolicyOpts): Promise<RetryResult<T>>;
+/** Wraps fetch() with retry policy */
+export declare function fetchWithRetry(url: string, init?: RequestInit, retryOpts?: RetryPolicyOpts): Promise<Response>;

package/dist/retry-policy.js

@@ -0,0 +1,54 @@
+const DEFAULT_RETRY_STATUSES = [429, 500, 502, 503, 504];
+function shouldRetry(error, retryOn) {
+  if (error?.code && ["ECONNRESET", "ECONNREFUSED", "ETIMEDOUT", "ENOTFOUND", "EPIPE"].includes(error.code)) return true;
+  if (error?.message && /timeout|net::ERR_/i.test(error.message)) return true;
+  if (typeof error?.status === "number") return retryOn.includes(error.status);
+  return false;
+}
+function delay(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}
+async function withRetry(fn, opts = {}) {
+  const {
+    maxRetries = 3,
+    baseDelayMs = 1e3,
+    maxDelayMs = 3e4,
+    jitterMs = 500,
+    retryOn = DEFAULT_RETRY_STATUSES
+  } = opts;
+  let lastError;
+  let totalDelayMs = 0;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      const value = await fn(attempt);
+      return { value, attempts: attempt + 1, totalDelayMs };
+    } catch (err) {
+      lastError = err;
+      if (attempt === maxRetries) break;
+      if (!shouldRetry(err, retryOn)) throw err;
+      const backoff = Math.min(maxDelayMs, baseDelayMs * Math.pow(2, attempt));
+      const jitter = Math.random() * jitterMs;
+      const waitMs = Math.round(backoff + jitter);
+      totalDelayMs += waitMs;
+      await delay(waitMs);
+    }
+  }
+  throw lastError;
+}
+async function fetchWithRetry(url, init = {}, retryOpts = {}) {
+  const result = await withRetry(async () => {
+    const res = await fetch(url, init);
+    if (retryOpts.retryOn?.includes(res.status) ?? DEFAULT_RETRY_STATUSES.includes(res.status)) {
+      const err = new Error(`HTTP ${res.status}`);
+      err.status = res.status;
+      throw err;
+    }
+    return res;
+  }, retryOpts);
+  return result.value;
+}
+export {
+  fetchWithRetry,
+  withRetry
+};
+//# sourceMappingURL=retry-policy.js.map

package/dist/retry-policy.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/retry-policy.ts"],
+  "sourcesContent": ["/**\n * Retry policy \u2014 configurable exponential backoff with jitter.\n * Covers: 5xx server errors, network timeouts, ECONNREFUSED, ECONNRESET.\n * NOT retried: 4xx client errors (except 429 \u2014 handled separately), redirects.\n */\n\nexport interface RetryPolicyOpts {\n  maxRetries?: number;       // default 3\n  baseDelayMs?: number;      // default 1000\n  maxDelayMs?: number;       // default 30000\n  jitterMs?: number;         // default 500\n  retryOn?: number[];        // HTTP status codes to retry (default: [429, 500, 502, 503, 504])\n}\n\nexport interface RetryResult<T> {\n  value: T;\n  attempts: number;\n  totalDelayMs: number;\n}\n\nconst DEFAULT_RETRY_STATUSES = [429, 500, 502, 503, 504];\n\nfunction shouldRetry(error: any, retryOn: number[]): boolean {\n  // Network-level errors\n  if (error?.code && ['ECONNRESET', 'ECONNREFUSED', 'ETIMEDOUT', 'ENOTFOUND', 'EPIPE'].includes(error.code)) return true;\n  // Playwright navigation timeout\n  if (error?.message && /timeout|net::ERR_/i.test(error.message)) return true;\n  // HTTP status errors\n  if (typeof error?.status === 'number') return retryOn.includes(error.status);\n  return false;\n}\n\nfunction delay(ms: number): Promise<void> {\n  return new Promise(r => setTimeout(r, ms));\n}\n\nexport async function withRetry<T>(\n  fn: (attempt: number) => Promise<T>,\n  opts: RetryPolicyOpts = {},\n): Promise<RetryResult<T>> {\n  const {\n    maxRetries = 3,\n    baseDelayMs = 1_000,\n    maxDelayMs = 30_000,\n    jitterMs = 500,\n    retryOn = DEFAULT_RETRY_STATUSES,\n  } = opts;\n\n  let lastError: any;\n  let totalDelayMs = 0;\n\n  for (let attempt = 0; attempt <= maxRetries; attempt++) {\n    try {\n      const value = await fn(attempt);\n      return { value, attempts: attempt + 1, totalDelayMs };\n    } catch (err) {\n      lastError = err;\n      if (attempt === maxRetries) break;\n      if (!shouldRetry(err, retryOn)) throw err; // non-retryable \u2014 fail fast\n\n      const backoff = Math.min(maxDelayMs, baseDelayMs * Math.pow(2, attempt));\n      const jitter = Math.random() * jitterMs;\n      const waitMs = Math.round(backoff + jitter);\n      totalDelayMs += waitMs;\n      await delay(waitMs);\n    }\n  }\n  throw lastError;\n}\n\n/** Wraps fetch() with retry policy */\nexport async function fetchWithRetry(\n  url: string,\n  init: RequestInit = {},\n  retryOpts: RetryPolicyOpts = {},\n): Promise<Response> {\n  const result = await withRetry(async () => {\n    const res = await fetch(url, init);\n    if (retryOpts.retryOn?.includes(res.status) ?? DEFAULT_RETRY_STATUSES.includes(res.status)) {\n      const err: any = new Error(`HTTP ${res.status}`);\n      err.status = res.status;\n      throw err;\n    }\n    return res;\n  }, retryOpts);\n  return result.value;\n}\n"],
+  "mappings": "AAoBA,MAAM,yBAAyB,CAAC,KAAK,KAAK,KAAK,KAAK,GAAG;AAEvD,SAAS,YAAY,OAAY,SAA4B;AAE3D,MAAI,OAAO,QAAQ,CAAC,cAAc,gBAAgB,aAAa,aAAa,OAAO,EAAE,SAAS,MAAM,IAAI,EAAG,QAAO;AAElH,MAAI,OAAO,WAAW,qBAAqB,KAAK,MAAM,OAAO,EAAG,QAAO;AAEvE,MAAI,OAAO,OAAO,WAAW,SAAU,QAAO,QAAQ,SAAS,MAAM,MAAM;AAC3E,SAAO;AACT;AAEA,SAAS,MAAM,IAA2B;AACxC,SAAO,IAAI,QAAQ,OAAK,WAAW,GAAG,EAAE,CAAC;AAC3C;AAEA,eAAsB,UACpB,IACA,OAAwB,CAAC,GACA;AACzB,QAAM;AAAA,IACJ,aAAa;AAAA,IACb,cAAc;AAAA,IACd,aAAa;AAAA,IACb,WAAW;AAAA,IACX,UAAU;AAAA,EACZ,IAAI;AAEJ,MAAI;AACJ,MAAI,eAAe;AAEnB,WAAS,UAAU,GAAG,WAAW,YAAY,WAAW;AACtD,QAAI;AACF,YAAM,QAAQ,MAAM,GAAG,OAAO;AAC9B,aAAO,EAAE,OAAO,UAAU,UAAU,GAAG,aAAa;AAAA,IACtD,SAAS,KAAK;AACZ,kBAAY;AACZ,UAAI,YAAY,WAAY;AAC5B,UAAI,CAAC,YAAY,KAAK,OAAO,EAAG,OAAM;AAEtC,YAAM,UAAU,KAAK,IAAI,YAAY,cAAc,KAAK,IAAI,GAAG,OAAO,CAAC;AACvE,YAAM,SAAS,KAAK,OAAO,IAAI;AAC/B,YAAM,SAAS,KAAK,MAAM,UAAU,MAAM;AAC1C,sBAAgB;AAChB,YAAM,MAAM,MAAM;AAAA,IACpB;AAAA,EACF;AACA,QAAM;AACR;AAGA,eAAsB,eACpB,KACA,OAAoB,CAAC,GACrB,YAA6B,CAAC,GACX;AACnB,QAAM,SAAS,MAAM,UAAU,YAAY;AACzC,UAAM,MAAM,MAAM,MAAM,KAAK,IAAI;AACjC,QAAI,UAAU,SAAS,SAAS,IAAI,MAAM,KAAK,uBAAuB,SAAS,IAAI,MAAM,GAAG;AAC1F,YAAM,MAAW,IAAI,MAAM,QAAQ,IAAI,MAAM,EAAE;AAC/C,UAAI,SAAS,IAAI;AACjB,YAAM;AAAA,IACR;AACA,WAAO;AAAA,EACT,GAAG,SAAS;AACZ,SAAO,OAAO;AAChB;",
+  "names": []
+}

package/dist/robots-txt.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Minimal robots.txt fetcher + parser. No external deps. Caches per origin.
+ * Implements the subset of robots.txt spec used in practice:
+ *   User-agent, Disallow, Allow — longest match wins (RFC 9309).
+ */
+export declare class RobotsCache {
+    private readonly cache;
+    isAllowed(url: string, userAgent?: string): Promise<boolean>;
+}

package/dist/robots-txt.js

@@ -0,0 +1,77 @@
+function parseRobots(text) {
+  const rules = [];
+  let current = null;
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.split("#")[0].trim();
+    if (!line) {
+      current = null;
+      continue;
+    }
+    const colonIdx = line.indexOf(":");
+    if (colonIdx === -1) continue;
+    const key = line.slice(0, colonIdx).trim().toLowerCase();
+    const value = line.slice(colonIdx + 1).trim();
+    if (key === "user-agent") {
+      if (!current || current.disallow.length > 0 || current.allow.length > 0) {
+        current = { userAgent: value.toLowerCase(), disallow: [], allow: [] };
+        rules.push(current);
+      } else {
+        current.userAgent = value.toLowerCase();
+      }
+    } else if (key === "disallow" && current && value) {
+      current.disallow.push(value);
+    } else if (key === "allow" && current && value) {
+      current.allow.push(value);
+    }
+  }
+  return rules;
+}
+function isAllowedByRules(rules, userAgent, pathname) {
+  const ua = userAgent.toLowerCase();
+  const exactRules = rules.filter((r) => r.userAgent === ua);
+  const wildcardRules = rules.filter((r) => r.userAgent === "*");
+  const applicable = exactRules.length > 0 ? exactRules : wildcardRules;
+  if (applicable.length === 0) return true;
+  const matched = [];
+  for (const rule of applicable) {
+    for (const p of rule.allow) {
+      if (pathname.startsWith(p)) matched.push({ path: p, allow: true });
+    }
+    for (const p of rule.disallow) {
+      if (pathname.startsWith(p)) matched.push({ path: p, allow: false });
+    }
+  }
+  if (matched.length === 0) return true;
+  matched.sort((a, b) => b.path.length - a.path.length);
+  return matched[0].allow;
+}
+class RobotsCache {
+  cache = /* @__PURE__ */ new Map();
+  async isAllowed(url, userAgent = "ZeTa-Crawler") {
+    let origin;
+    let pathname;
+    try {
+      const u = new URL(url);
+      origin = u.origin;
+      pathname = u.pathname || "/";
+    } catch {
+      return true;
+    }
+    if (!this.cache.has(origin)) {
+      try {
+        const res = await fetch(`${origin}/robots.txt`, {
+          headers: { "User-Agent": userAgent },
+          signal: AbortSignal.timeout(5e3)
+        });
+        this.cache.set(origin, res.ok ? parseRobots(await res.text()) : []);
+      } catch {
+        this.cache.set(origin, []);
+      }
+    }
+    return isAllowedByRules(this.cache.get(origin), userAgent, pathname);
+  }
+}
+export {
+  RobotsCache
+};
+//# sourceMappingURL=robots-txt.js.map

package/dist/robots-txt.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/robots-txt.ts"],
+  "sourcesContent": ["/**\n * Minimal robots.txt fetcher + parser. No external deps. Caches per origin.\n * Implements the subset of robots.txt spec used in practice:\n *   User-agent, Disallow, Allow \u2014 longest match wins (RFC 9309).\n */\n\ninterface RobotsRule {\n  userAgent: string;\n  disallow: string[];\n  allow: string[];\n}\n\nfunction parseRobots(text: string): RobotsRule[] {\n  const rules: RobotsRule[] = [];\n  let current: RobotsRule | null = null;\n\n  for (const rawLine of text.split('\\n')) {\n    const line = rawLine.split('#')[0].trim();\n    if (!line) { current = null; continue; }\n    const colonIdx = line.indexOf(':');\n    if (colonIdx === -1) continue;\n    const key = line.slice(0, colonIdx).trim().toLowerCase();\n    const value = line.slice(colonIdx + 1).trim();\n\n    if (key === 'user-agent') {\n      // Start new block only when current block already has rules, otherwise\n      // accumulate multiple User-agent lines into one block.\n      if (!current || current.disallow.length > 0 || current.allow.length > 0) {\n        current = { userAgent: value.toLowerCase(), disallow: [], allow: [] };\n        rules.push(current);\n      } else {\n        current.userAgent = value.toLowerCase();\n      }\n    } else if (key === 'disallow' && current && value) {\n      current.disallow.push(value);\n    } else if (key === 'allow' && current && value) {\n      current.allow.push(value);\n    }\n  }\n\n  return rules;\n}\n\nfunction isAllowedByRules(rules: RobotsRule[], userAgent: string, pathname: string): boolean {\n  const ua = userAgent.toLowerCase();\n  const exactRules = rules.filter(r => r.userAgent === ua);\n  const wildcardRules = rules.filter(r => r.userAgent === '*');\n  const applicable = exactRules.length > 0 ? exactRules : wildcardRules;\n\n  if (applicable.length === 0) return true;\n\n  // Collect all matched allow/disallow directives; longest path wins.\n  const matched: Array<{ path: string; allow: boolean }> = [];\n  for (const rule of applicable) {\n    for (const p of rule.allow) {\n      if (pathname.startsWith(p)) matched.push({ path: p, allow: true });\n    }\n    for (const p of rule.disallow) {\n      if (pathname.startsWith(p)) matched.push({ path: p, allow: false });\n    }\n  }\n\n  if (matched.length === 0) return true;\n  matched.sort((a, b) => b.path.length - a.path.length);\n  return matched[0].allow;\n}\n\nexport class RobotsCache {\n  private readonly cache = new Map<string, RobotsRule[]>();\n\n  async isAllowed(url: string, userAgent = 'ZeTa-Crawler'): Promise<boolean> {\n    let origin: string;\n    let pathname: string;\n    try {\n      const u = new URL(url);\n      origin = u.origin;\n      pathname = u.pathname || '/';\n    } catch {\n      return true;\n    }\n\n    if (!this.cache.has(origin)) {\n      try {\n        const res = await fetch(`${origin}/robots.txt`, {\n          headers: { 'User-Agent': userAgent },\n          signal: AbortSignal.timeout(5_000),\n        });\n        this.cache.set(origin, res.ok ? parseRobots(await res.text()) : []);\n      } catch {\n        this.cache.set(origin, []); // network error or timeout = no restrictions\n      }\n    }\n\n    return isAllowedByRules(this.cache.get(origin)!, userAgent, pathname);\n  }\n}\n"],
+  "mappings": "AAYA,SAAS,YAAY,MAA4B;AAC/C,QAAM,QAAsB,CAAC;AAC7B,MAAI,UAA6B;AAEjC,aAAW,WAAW,KAAK,MAAM,IAAI,GAAG;AACtC,UAAM,OAAO,QAAQ,MAAM,GAAG,EAAE,CAAC,EAAE,KAAK;AACxC,QAAI,CAAC,MAAM;AAAE,gBAAU;AAAM;AAAA,IAAU;AACvC,UAAM,WAAW,KAAK,QAAQ,GAAG;AACjC,QAAI,aAAa,GAAI;AACrB,UAAM,MAAM,KAAK,MAAM,GAAG,QAAQ,EAAE,KAAK,EAAE,YAAY;AACvD,UAAM,QAAQ,KAAK,MAAM,WAAW,CAAC,EAAE,KAAK;AAE5C,QAAI,QAAQ,cAAc;AAGxB,UAAI,CAAC,WAAW,QAAQ,SAAS,SAAS,KAAK,QAAQ,MAAM,SAAS,GAAG;AACvE,kBAAU,EAAE,WAAW,MAAM,YAAY,GAAG,UAAU,CAAC,GAAG,OAAO,CAAC,EAAE;AACpE,cAAM,KAAK,OAAO;AAAA,MACpB,OAAO;AACL,gBAAQ,YAAY,MAAM,YAAY;AAAA,MACxC;AAAA,IACF,WAAW,QAAQ,cAAc,WAAW,OAAO;AACjD,cAAQ,SAAS,KAAK,KAAK;AAAA,IAC7B,WAAW,QAAQ,WAAW,WAAW,OAAO;AAC9C,cAAQ,MAAM,KAAK,KAAK;AAAA,IAC1B;AAAA,EACF;AAEA,SAAO;AACT;AAEA,SAAS,iBAAiB,OAAqB,WAAmB,UAA2B;AAC3F,QAAM,KAAK,UAAU,YAAY;AACjC,QAAM,aAAa,MAAM,OAAO,OAAK,EAAE,cAAc,EAAE;AACvD,QAAM,gBAAgB,MAAM,OAAO,OAAK,EAAE,cAAc,GAAG;AAC3D,QAAM,aAAa,WAAW,SAAS,IAAI,aAAa;AAExD,MAAI,WAAW,WAAW,EAAG,QAAO;AAGpC,QAAM,UAAmD,CAAC;AAC1D,aAAW,QAAQ,YAAY;AAC7B,eAAW,KAAK,KAAK,OAAO;AAC1B,UAAI,SAAS,WAAW,CAAC,EAAG,SAAQ,KAAK,EAAE,MAAM,GAAG,OAAO,KAAK,CAAC;AAAA,IACnE;AACA,eAAW,KAAK,KAAK,UAAU;AAC7B,UAAI,SAAS,WAAW,CAAC,EAAG,SAAQ,KAAK,EAAE,MAAM,GAAG,OAAO,MAAM,CAAC;AAAA,IACpE;AAAA,EACF;AAEA,MAAI,QAAQ,WAAW,EAAG,QAAO;AACjC,UAAQ,KAAK,CAAC,GAAG,MAAM,EAAE,KAAK,SAAS,EAAE,KAAK,MAAM;AACpD,SAAO,QAAQ,CAAC,EAAE;AACpB;AAEO,MAAM,YAAY;AAAA,EACN,QAAQ,oBAAI,IAA0B;AAAA,EAEvD,MAAM,UAAU,KAAa,YAAY,gBAAkC;AACzE,QAAI;AACJ,QAAI;AACJ,QAAI;AACF,YAAM,IAAI,IAAI,IAAI,GAAG;AACrB,eAAS,EAAE;AACX,iBAAW,EAAE,YAAY;AAAA,IAC3B,QAAQ;AACN,aAAO;AAAA,IACT;AAEA,QAAI,CAAC,KAAK,MAAM,IAAI,MAAM,GAAG;AAC3B,UAAI;AACF,cAAM,MAAM,MAAM,MAAM,GAAG,MAAM,eAAe;AAAA,UAC9C,SAAS,EAAE,cAAc,UAAU;AAAA,UACnC,QAAQ,YAAY,QAAQ,GAAK;AAAA,QACnC,CAAC;AACD,aAAK,MAAM,IAAI,QAAQ,IAAI,KAAK,YAAY,MAAM,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC;AAAA,MACpE,QAAQ;AACN,aAAK,MAAM,IAAI,QAAQ,CAAC,CAAC;AAAA,MAC3B;AAAA,IACF;AAEA,WAAO,iBAAiB,KAAK,MAAM,IAAI,MAAM,GAAI,WAAW,QAAQ;AAAA,EACtE;AACF;",
+  "names": []
+}

package/dist/screen-reader.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Reads a page as a structured outline (cheap + reliable), the way
+ * Playwright MCP / the accessibility tree works — NOT by sending pixels to a
+ * vision model. Vision is a fallback for image-only pages (added later).
+ *
+ * Returns the interactive elements found, which the Screen Reader Agent then
+ * enriches with MEANING and saves to the Zeta Core.
+ */
+export interface RawElement {
+    role: string;
+    label: string;
+    selectorHint: string;
+    expectedData?: string;
+}
+export declare function readScreen(page: any): Promise<RawElement[]>;

package/dist/screen-reader.js

@@ -0,0 +1,48 @@
+async function readScreen(page) {
+  return page.evaluate(() => {
+    if (typeof globalThis.__name === "undefined") globalThis.__name = (fn) => fn;
+    const out = [];
+    const seen = /* @__PURE__ */ new Set();
+    const noiseLabel = /^(cookie|consent|privacy policy|terms of use|copyright|©|\bv\d+\.\d+|got it|dismiss|skip to|powered by|copied|\s*$)/i;
+    const nodes = document.querySelectorAll(
+      'input:not([type=hidden]), select, textarea, button, a[href], [role="button"], [role="combobox"], [role="slider"], [role="switch"], [role="tab"], [role="menuitem"], [role="searchbox"], [role="spinbutton"]'
+    );
+    nodes.forEach((el) => {
+      const htmlEl = el;
+      const style = window.getComputedStyle(htmlEl);
+      if (style.display === "none" || style.visibility === "hidden" || style.opacity === "0") return;
+      const rect = el.getBoundingClientRect();
+      const hasAccessibleLabel = !!(el.getAttribute("aria-label") || el.getAttribute("aria-labelledby"));
+      if (rect.width === 0 && rect.height === 0 && !hasAccessibleLabel) return;
+      const tag = el.tagName.toLowerCase();
+      const role = el.getAttribute("role") || (tag === "input" ? el.type || "text" : tag);
+      const raw = (el.getAttribute("aria-label") || el.getAttribute("placeholder") || (el.getAttribute("title") ?? "") || htmlEl.innerText?.replace(/\s+/g, " ").trim() || el.getAttribute("name") || "").substring(0, 80);
+      if (!raw || noiseLabel.test(raw) || raw.length > 70) return;
+      const key = `${role}:${raw.toLowerCase()}`;
+      if (seen.has(key)) return;
+      seen.add(key);
+      let expectedData;
+      if (tag === "input") {
+        const input = el;
+        if (input.type === "email" || /email/i.test(raw)) expectedData = "valid_email";
+        else if (input.type === "password" || /password/i.test(raw)) expectedData = "password";
+        else if (input.type === "tel" || /phone|mobile/i.test(raw)) expectedData = "phone";
+        else if (input.type === "date" || /\bdate\b/i.test(raw)) expectedData = "date";
+        else if (/\b(code|otp|token)\b/i.test(raw)) expectedData = "one_time_code";
+        else if (/\b(search|query)\b/i.test(raw)) expectedData = "search_term";
+      }
+      out.push({ role, label: raw, selectorHint: tag, expectedData });
+    });
+    const priority = (e) => {
+      if (["email", "password", "text", "tel", "date", "number", "select", "textarea"].includes(e.role)) return 0;
+      if (e.role === "button" || e.role === "submit") return 1;
+      return 2;
+    };
+    out.sort((a, b) => priority(a) - priority(b));
+    return out.slice(0, 25);
+  });
+}
+export {
+  readScreen
+};
+//# sourceMappingURL=screen-reader.js.map

package/dist/screen-reader.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/screen-reader.ts"],
+  "sourcesContent": ["import type { Page } from 'playwright';\n\n/**\n * Reads a page as a structured outline (cheap + reliable), the way\n * Playwright MCP / the accessibility tree works \u2014 NOT by sending pixels to a\n * vision model. Vision is a fallback for image-only pages (added later).\n *\n * Returns the interactive elements found, which the Screen Reader Agent then\n * enriches with MEANING and saves to the Zeta Core.\n */\nexport interface RawElement {\n  role: string;\n  label: string;\n  selectorHint: string;\n  expectedData?: string;\n}\n\nexport async function readScreen(page: any): Promise<RawElement[]> {\n  return page.evaluate(() => {\n    // esbuild injects __name() for named arrow-function constants (e.g. `const priority = ...`).\n    // Polyfill prevents ReferenceError when the serialized callback runs in the browser.\n    if (typeof (globalThis as any).__name === 'undefined') (globalThis as any).__name = (fn: any) => fn;\n    const out: { role: string; label: string; selectorHint: string; expectedData?: string }[] = [];\n    const seen = new Set<string>();\n\n    // Noise patterns to skip \u2014 cookie banners, footer chrome, version strings\n    // Intentionally excludes standalone \"close\" and \"copy\" \u2014 too many false positives\n    // (Close account, Close preview, Copy link, Copy to clipboard are all valid test targets)\n    const noiseLabel =\n      /^(cookie|consent|privacy policy|terms of use|copyright|\u00A9|\\bv\\d+\\.\\d+|got it|dismiss|skip to|powered by|copied|\\s*$)/i;\n\n    // Include ARIA-role elements \u2014 Headless UI, Radix, Ant Design, Shadcn all use these instead of native tags\n    const nodes = document.querySelectorAll(\n      'input:not([type=hidden]), select, textarea, button, a[href], ' +\n      '[role=\"button\"], [role=\"combobox\"], [role=\"slider\"], [role=\"switch\"], ' +\n      '[role=\"tab\"], [role=\"menuitem\"], [role=\"searchbox\"], [role=\"spinbutton\"]'\n    );\n\n    nodes.forEach((el) => {\n      const htmlEl = el as HTMLElement;\n\n      // Skip invisible elements\n      const style = window.getComputedStyle(htmlEl);\n      if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') return;\n      const rect = el.getBoundingClientRect();\n      // Allow zero-size elements that carry an accessible label (sr-only icon buttons, skip-nav links)\n      const hasAccessibleLabel = !!(el.getAttribute('aria-label') || el.getAttribute('aria-labelledby'));\n      if (rect.width === 0 && rect.height === 0 && !hasAccessibleLabel) return;\n\n      // Derive role\n      const tag = el.tagName.toLowerCase();\n      const role =\n        el.getAttribute('role') ||\n        (tag === 'input' ? ((el as HTMLInputElement).type || 'text') : tag);\n\n      // Derive the best human-readable label (prefer aria > placeholder > inner text)\n      const raw = (\n        el.getAttribute('aria-label') ||\n        el.getAttribute('placeholder') ||\n        (el.getAttribute('title') ?? '') ||\n        htmlEl.innerText?.replace(/\\s+/g, ' ').trim() ||\n        el.getAttribute('name') ||\n        ''\n      ).substring(0, 80);\n\n      // Skip empty, noise patterns, or very long labels (likely container text)\n      if (!raw || noiseLabel.test(raw) || raw.length > 70) return;\n\n      // Deduplicate by role+normalised label\n      const key = `${role}:${raw.toLowerCase()}`;\n      if (seen.has(key)) return;\n      seen.add(key);\n\n      let expectedData: string | undefined;\n      if (tag === 'input') {\n        const input = el as HTMLInputElement;\n        if (input.type === 'email' || /email/i.test(raw)) expectedData = 'valid_email';\n        else if (input.type === 'password' || /password/i.test(raw)) expectedData = 'password';\n        else if (input.type === 'tel' || /phone|mobile/i.test(raw)) expectedData = 'phone';\n        else if (input.type === 'date' || /\\bdate\\b/i.test(raw)) expectedData = 'date';\n        else if (/\\b(code|otp|token)\\b/i.test(raw)) expectedData = 'one_time_code';\n        else if (/\\b(search|query)\\b/i.test(raw)) expectedData = 'search_term';\n      }\n\n      out.push({ role, label: raw, selectorHint: tag, expectedData });\n    });\n\n    // Prioritise: form fields > buttons > links; within each group keep order\n    const priority = (e: typeof out[0]) => {\n      if (['email', 'password', 'text', 'tel', 'date', 'number', 'select', 'textarea'].includes(e.role)) return 0;\n      if (e.role === 'button' || e.role === 'submit') return 1;\n      return 2;\n    };\n    out.sort((a, b) => priority(a) - priority(b));\n\n    return out.slice(0, 25); // cap at 25 \u2014 enough context, not overwhelming\n  });\n}\n"],
+  "mappings": "AAiBA,eAAsB,WAAW,MAAkC;AACjE,SAAO,KAAK,SAAS,MAAM;AAGzB,QAAI,OAAQ,WAAmB,WAAW,YAAa,CAAC,WAAmB,SAAS,CAAC,OAAY;AACjG,UAAM,MAAsF,CAAC;AAC7F,UAAM,OAAO,oBAAI,IAAY;AAK7B,UAAM,aACJ;AAGF,UAAM,QAAQ,SAAS;AAAA,MACrB;AAAA,IAGF;AAEA,UAAM,QAAQ,CAAC,OAAO;AACpB,YAAM,SAAS;AAGf,YAAM,QAAQ,OAAO,iBAAiB,MAAM;AAC5C,UAAI,MAAM,YAAY,UAAU,MAAM,eAAe,YAAY,MAAM,YAAY,IAAK;AACxF,YAAM,OAAO,GAAG,sBAAsB;AAEtC,YAAM,qBAAqB,CAAC,EAAE,GAAG,aAAa,YAAY,KAAK,GAAG,aAAa,iBAAiB;AAChG,UAAI,KAAK,UAAU,KAAK,KAAK,WAAW,KAAK,CAAC,mBAAoB;AAGlE,YAAM,MAAM,GAAG,QAAQ,YAAY;AACnC,YAAM,OACJ,GAAG,aAAa,MAAM,MACrB,QAAQ,UAAY,GAAwB,QAAQ,SAAU;AAGjE,YAAM,OACJ,GAAG,aAAa,YAAY,KAC5B,GAAG,aAAa,aAAa,MAC5B,GAAG,aAAa,OAAO,KAAK,OAC7B,OAAO,WAAW,QAAQ,QAAQ,GAAG,EAAE,KAAK,KAC5C,GAAG,aAAa,MAAM,KACtB,IACA,UAAU,GAAG,EAAE;AAGjB,UAAI,CAAC,OAAO,WAAW,KAAK,GAAG,KAAK,IAAI,SAAS,GAAI;AAGrD,YAAM,MAAM,GAAG,IAAI,IAAI,IAAI,YAAY,CAAC;AACxC,UAAI,KAAK,IAAI,GAAG,EAAG;AACnB,WAAK,IAAI,GAAG;AAEZ,UAAI;AACJ,UAAI,QAAQ,SAAS;AACnB,cAAM,QAAQ;AACd,YAAI,MAAM,SAAS,WAAW,SAAS,KAAK,GAAG,EAAG,gBAAe;AAAA,iBACxD,MAAM,SAAS,cAAc,YAAY,KAAK,GAAG,EAAG,gBAAe;AAAA,iBACnE,MAAM,SAAS,SAAS,gBAAgB,KAAK,GAAG,EAAG,gBAAe;AAAA,iBAClE,MAAM,SAAS,UAAU,YAAY,KAAK,GAAG,EAAG,gBAAe;AAAA,iBAC/D,wBAAwB,KAAK,GAAG,EAAG,gBAAe;AAAA,iBAClD,sBAAsB,KAAK,GAAG,EAAG,gBAAe;AAAA,MAC3D;AAEA,UAAI,KAAK,EAAE,MAAM,OAAO,KAAK,cAAc,KAAK,aAAa,CAAC;AAAA,IAChE,CAAC;AAGD,UAAM,WAAW,CAAC,MAAqB;AACrC,UAAI,CAAC,SAAS,YAAY,QAAQ,OAAO,QAAQ,UAAU,UAAU,UAAU,EAAE,SAAS,EAAE,IAAI,EAAG,QAAO;AAC1G,UAAI,EAAE,SAAS,YAAY,EAAE,SAAS,SAAU,QAAO;AACvD,aAAO;AAAA,IACT;AACA,QAAI,KAAK,CAAC,GAAG,MAAM,SAAS,CAAC,IAAI,SAAS,CAAC,CAAC;AAE5C,WAAO,IAAI,MAAM,GAAG,EAAE;AAAA,EACxB,CAAC;AACH;",
+  "names": []
+}

package/dist/screenshot-masker.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Screenshot masker — blur or black-box PII regions in captured screenshots.
+ *
+ * Strategy: inject a CSS overlay into the page before screenshot capture that
+ * covers detected PII-likely elements (input[type=email], input[type=password],
+ * elements with PII-containing text) with a blur or solid black mask.
+ *
+ * This is a CSS-based approach (no image processing library needed):
+ * 1. Identify likely-PII DOM elements via selectors
+ * 2. Add an overlaid <div> with blur/black filter at each element's bounding box
+ * 3. Take screenshot
+ * 4. Remove overlays
+ *
+ * Falls back gracefully if elements are not found or overlay injection fails.
+ */
+import type { Page } from 'playwright';
+export interface MaskingOpts {
+    /** Additional CSS selectors to mask (in addition to defaults) */
+    extraSelectors?: string[];
+    /** Masking style: 'blur' or 'blackout' */
+    style?: 'blur' | 'blackout';
+    /** Blur strength in px (default 8) */
+    blurPx?: number;
+}
+export declare function maskScreenshot(page: Page, opts?: MaskingOpts): Promise<{
+    maskedCount: number;
+    screenshot: Buffer;
+}>;

package/dist/screenshot-masker.js

@@ -0,0 +1,62 @@
+const DEFAULT_PII_SELECTORS = [
+  'input[type="email"]',
+  'input[type="password"]',
+  'input[type="tel"]',
+  'input[autocomplete="cc-number"]',
+  'input[autocomplete="cc-csc"]',
+  'input[autocomplete="ssn"]',
+  '[data-pii="true"]',
+  '[data-sensitive="true"]'
+];
+async function maskScreenshot(page, opts = {}) {
+  const { extraSelectors = [], style = "blur", blurPx = 8 } = opts;
+  const selectors = [...DEFAULT_PII_SELECTORS, ...extraSelectors];
+  let maskedCount = 0;
+  const overlayIds = [];
+  try {
+    const result = await page.evaluate(({ selectors: selectors2, style: style2, blurPx: blurPx2 }) => {
+      const ids = [];
+      for (const sel of selectors2) {
+        try {
+          const elements = Array.from(document.querySelectorAll(sel));
+          for (const el of elements) {
+            const rect = el.getBoundingClientRect();
+            if (rect.width === 0 || rect.height === 0) continue;
+            const overlay = document.createElement("div");
+            const id = `__zeta_mask_${Math.random().toString(36).slice(2)}`;
+            overlay.id = id;
+            overlay.style.cssText = [
+              "position: fixed",
+              `top: ${rect.top + window.scrollY}px`,
+              `left: ${rect.left + window.scrollX}px`,
+              `width: ${rect.width}px`,
+              `height: ${rect.height}px`,
+              "z-index: 2147483647",
+              style2 === "blur" ? `backdrop-filter: blur(${blurPx2}px); -webkit-backdrop-filter: blur(${blurPx2}px); background: rgba(0,0,0,0.1);` : "background: #000000;",
+              "pointer-events: none"
+            ].join("; ");
+            document.body.appendChild(overlay);
+            ids.push(id);
+          }
+        } catch {
+        }
+      }
+      return ids;
+    }, { selectors, style, blurPx });
+    overlayIds.push(...result);
+    maskedCount = result.length;
+  } catch {
+  }
+  const screenshot = await page.screenshot({ type: "png", fullPage: false });
+  if (overlayIds.length > 0) {
+    await page.evaluate((ids) => {
+      for (const id of ids) document.getElementById(id)?.remove();
+    }, overlayIds).catch(() => {
+    });
+  }
+  return { maskedCount, screenshot };
+}
+export {
+  maskScreenshot
+};
+//# sourceMappingURL=screenshot-masker.js.map