@detiq/crawler 0.1.3

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,16 @@
+import type { Page } from 'playwright';
+/**
+ * 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: Page): Promise<RawElement[]>;

package/dist/screen-reader.js

@@ -0,0 +1,46 @@
+async function readScreen(page) {
+  return page.evaluate(() => {
+    const out = [];
+    const seen = /* @__PURE__ */ new Set();
+    const noiseLabel = /^(cookie|consent|privacy policy|terms of use|copyright|©|\bv\d+\.\d+|accept|decline|got it|dismiss|close|skip to|powered by|copy|copied|\s*$)/i;
+    const nodes = document.querySelectorAll(
+      "input:not([type=hidden]), select, textarea, button, a[href]"
+    );
+    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();
+      if (rect.width === 0 && rect.height === 0) 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: Page): Promise<RawElement[]> {\n  return page.evaluate(() => {\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 junk, marketing copy buttons, version strings\n    const noiseLabel =\n      /^(cookie|consent|privacy policy|terms of use|copyright|\u00A9|\\bv\\d+\\.\\d+|accept|decline|got it|dismiss|close|skip to|powered by|copy|copied|\\s*$)/i;\n\n    // Select only truly interactive elements (not generic [role] containers)\n    const nodes = document.querySelectorAll(\n      'input:not([type=hidden]), select, textarea, button, a[href]'\n    );\n\n    nodes.forEach((el) => {\n      const htmlEl = el as HTMLElement;\n\n      // Skip invisible or zero-size 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      if (rect.width === 0 && rect.height === 0) 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,MAAmC;AAClE,SAAO,KAAK,SAAS,MAAM;AACzB,UAAM,MAAsF,CAAC;AAC7F,UAAM,OAAO,oBAAI,IAAY;AAG7B,UAAM,aACJ;AAGF,UAAM,QAAQ,SAAS;AAAA,MACrB;AAAA,IACF;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;AACtC,UAAI,KAAK,UAAU,KAAK,KAAK,WAAW,EAAG;AAG3C,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

package/dist/screenshot-masker.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/screenshot-masker.ts"],
+  "sourcesContent": ["/**\n * Screenshot masker \u2014 blur or black-box PII regions in captured screenshots.\n *\n * Strategy: inject a CSS overlay into the page before screenshot capture that\n * covers detected PII-likely elements (input[type=email], input[type=password],\n * elements with PII-containing text) with a blur or solid black mask.\n *\n * This is a CSS-based approach (no image processing library needed):\n * 1. Identify likely-PII DOM elements via selectors\n * 2. Add an overlaid <div> with blur/black filter at each element's bounding box\n * 3. Take screenshot\n * 4. Remove overlays\n *\n * Falls back gracefully if elements are not found or overlay injection fails.\n */\n\nimport type { Page } from 'playwright';\n\nexport interface MaskingOpts {\n  /** Additional CSS selectors to mask (in addition to defaults) */\n  extraSelectors?: string[];\n  /** Masking style: 'blur' or 'blackout' */\n  style?: 'blur' | 'blackout';\n  /** Blur strength in px (default 8) */\n  blurPx?: number;\n}\n\n// Default PII-sensitive selectors\nconst DEFAULT_PII_SELECTORS = [\n  'input[type=\"email\"]',\n  'input[type=\"password\"]',\n  'input[type=\"tel\"]',\n  'input[autocomplete=\"cc-number\"]',\n  'input[autocomplete=\"cc-csc\"]',\n  'input[autocomplete=\"ssn\"]',\n  '[data-pii=\"true\"]',\n  '[data-sensitive=\"true\"]',\n];\n\nexport async function maskScreenshot(\n  page: Page,\n  opts: MaskingOpts = {},\n): Promise<{ maskedCount: number; screenshot: Buffer }> {\n  const { extraSelectors = [], style = 'blur', blurPx = 8 } = opts;\n  const selectors = [...DEFAULT_PII_SELECTORS, ...extraSelectors];\n\n  let maskedCount = 0;\n  const overlayIds: string[] = [];\n\n  // Inject CSS overlays\n  try {\n    const result = await page.evaluate(({ selectors, style, blurPx }) => {\n      const ids: string[] = [];\n      for (const sel of selectors) {\n        try {\n          const elements = Array.from(document.querySelectorAll(sel));\n          for (const el of elements) {\n            const rect = el.getBoundingClientRect();\n            if (rect.width === 0 || rect.height === 0) continue;\n            const overlay = document.createElement('div');\n            const id = `__zeta_mask_${Math.random().toString(36).slice(2)}`;\n            overlay.id = id;\n            overlay.style.cssText = [\n              'position: fixed',\n              `top: ${rect.top + window.scrollY}px`,\n              `left: ${rect.left + window.scrollX}px`,\n              `width: ${rect.width}px`,\n              `height: ${rect.height}px`,\n              'z-index: 2147483647',\n              style === 'blur'\n                ? `backdrop-filter: blur(${blurPx}px); -webkit-backdrop-filter: blur(${blurPx}px); background: rgba(0,0,0,0.1);`\n                : 'background: #000000;',\n              'pointer-events: none',\n            ].join('; ');\n            document.body.appendChild(overlay);\n            ids.push(id);\n          }\n        } catch { /* selector error */ }\n      }\n      return ids;\n    }, { selectors, style, blurPx });\n\n    overlayIds.push(...result);\n    maskedCount = result.length;\n  } catch { /* non-fatal */ }\n\n  // Take screenshot with overlays active\n  const screenshot = await page.screenshot({ type: 'png', fullPage: false });\n\n  // Remove overlays\n  if (overlayIds.length > 0) {\n    await page.evaluate((ids) => {\n      for (const id of ids) document.getElementById(id)?.remove();\n    }, overlayIds).catch(() => {});\n  }\n\n  return { maskedCount, screenshot };\n}\n"],
+  "mappings": "AA4BA,MAAM,wBAAwB;AAAA,EAC5B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAEA,eAAsB,eACpB,MACA,OAAoB,CAAC,GACiC;AACtD,QAAM,EAAE,iBAAiB,CAAC,GAAG,QAAQ,QAAQ,SAAS,EAAE,IAAI;AAC5D,QAAM,YAAY,CAAC,GAAG,uBAAuB,GAAG,cAAc;AAE9D,MAAI,cAAc;AAClB,QAAM,aAAuB,CAAC;AAG9B,MAAI;AACF,UAAM,SAAS,MAAM,KAAK,SAAS,CAAC,EAAE,WAAAA,YAAW,OAAAC,QAAO,QAAAC,QAAO,MAAM;AACnE,YAAM,MAAgB,CAAC;AACvB,iBAAW,OAAOF,YAAW;AAC3B,YAAI;AACF,gBAAM,WAAW,MAAM,KAAK,SAAS,iBAAiB,GAAG,CAAC;AAC1D,qBAAW,MAAM,UAAU;AACzB,kBAAM,OAAO,GAAG,sBAAsB;AACtC,gBAAI,KAAK,UAAU,KAAK,KAAK,WAAW,EAAG;AAC3C,kBAAM,UAAU,SAAS,cAAc,KAAK;AAC5C,kBAAM,KAAK,eAAe,KAAK,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,CAAC,CAAC;AAC7D,oBAAQ,KAAK;AACb,oBAAQ,MAAM,UAAU;AAAA,cACtB;AAAA,cACA,QAAQ,KAAK,MAAM,OAAO,OAAO;AAAA,cACjC,SAAS,KAAK,OAAO,OAAO,OAAO;AAAA,cACnC,UAAU,KAAK,KAAK;AAAA,cACpB,WAAW,KAAK,MAAM;AAAA,cACtB;AAAA,cACAC,WAAU,SACN,yBAAyBC,OAAM,sCAAsCA,OAAM,sCAC3E;AAAA,cACJ;AAAA,YACF,EAAE,KAAK,IAAI;AACX,qBAAS,KAAK,YAAY,OAAO;AACjC,gBAAI,KAAK,EAAE;AAAA,UACb;AAAA,QACF,QAAQ;AAAA,QAAuB;AAAA,MACjC;AACA,aAAO;AAAA,IACT,GAAG,EAAE,WAAW,OAAO,OAAO,CAAC;AAE/B,eAAW,KAAK,GAAG,MAAM;AACzB,kBAAc,OAAO;AAAA,EACvB,QAAQ;AAAA,EAAkB;AAG1B,QAAM,aAAa,MAAM,KAAK,WAAW,EAAE,MAAM,OAAO,UAAU,MAAM,CAAC;AAGzE,MAAI,WAAW,SAAS,GAAG;AACzB,UAAM,KAAK,SAAS,CAAC,QAAQ;AAC3B,iBAAW,MAAM,IAAK,UAAS,eAAe,EAAE,GAAG,OAAO;AAAA,IAC5D,GAAG,UAAU,EAAE,MAAM,MAAM;AAAA,IAAC,CAAC;AAAA,EAC/B;AAEA,SAAO,EAAE,aAAa,WAAW;AACnC;",
+  "names": ["selectors", "style", "blurPx"]
+}

package/dist/seo-checker.d.ts

@@ -0,0 +1,33 @@
+/**
+ * SEO indexability checker — determines if a page is crawlable and indexable.
+ *
+ * Checks:
+ * 1. X-Robots-Tag response header (noindex, nofollow, noarchive)
+ * 2. <meta name="robots"> tag (noindex, nofollow)
+ * 3. Canonical URL (self-canonical vs cross-canonical)
+ * 4. rel="nofollow" on outbound links
+ * 5. hreflang tags (multilingual)
+ * 6. Open Graph completeness (og:title, og:description, og:image)
+ * 7. Structured data presence (JSON-LD)
+ * 8. Meta description
+ * 9. Title tag length (< 60 chars recommended)
+ * 10. URL structure (query params, fragments, excessive depth)
+ */
+import type { Page } from 'playwright';
+export interface SeoIssue {
+    rule: string;
+    severity: 'critical' | 'warning' | 'info';
+    message: string;
+    value?: string;
+}
+export interface SeoCheckResult {
+    url: string;
+    isIndexable: boolean;
+    canonicalUrl?: string;
+    isSelfCanonical?: boolean;
+    hreflang: Record<string, string>;
+    issues: SeoIssue[];
+    score: number;
+    checkedAt: string;
+}
+export declare function checkSeo(page: Page, url: string, responseHeaders?: Record<string, string>): Promise<SeoCheckResult>;

package/dist/seo-checker.js

@@ -0,0 +1,91 @@
+async function checkSeo(page, url, responseHeaders = {}) {
+  const issues = [];
+  const checkedAt = (/* @__PURE__ */ new Date()).toISOString();
+  let isIndexable = true;
+  const robotsHeader = responseHeaders["x-robots-tag"] ?? "";
+  if (/noindex/i.test(robotsHeader)) {
+    isIndexable = false;
+    issues.push({ rule: "x-robots-noindex", severity: "critical", message: "X-Robots-Tag: noindex found in response header", value: robotsHeader });
+  }
+  const pageData = await page.evaluate(() => {
+    const meta = (name) => document.querySelector(`meta[name="${name}"]`)?.getAttribute("content") ?? "";
+    const og = (prop) => document.querySelector(`meta[property="og:${prop}"]`)?.getAttribute("content") ?? "";
+    const canonical = document.querySelector('link[rel="canonical"]')?.getAttribute("href") ?? "";
+    const hreflang = {};
+    document.querySelectorAll('link[rel="alternate"][hreflang]').forEach((el) => {
+      hreflang[el.getAttribute("hreflang")] = el.getAttribute("href") ?? "";
+    });
+    const jsonLd = Array.from(document.querySelectorAll('script[type="application/ld+json"]')).map((s) => s.textContent ?? "");
+    return {
+      robotsMeta: meta("robots"),
+      description: meta("description"),
+      title: document.title ?? "",
+      canonical,
+      hreflang,
+      ogTitle: og("title"),
+      ogDescription: og("description"),
+      ogImage: og("image"),
+      hasJsonLd: jsonLd.length > 0,
+      jsonLd
+    };
+  }).catch(() => ({
+    robotsMeta: "",
+    description: "",
+    title: "",
+    canonical: "",
+    hreflang: {},
+    ogTitle: "",
+    ogDescription: "",
+    ogImage: "",
+    hasJsonLd: false,
+    jsonLd: []
+  }));
+  if (/noindex/i.test(pageData.robotsMeta)) {
+    isIndexable = false;
+    issues.push({ rule: "meta-robots-noindex", severity: "critical", message: "Meta robots noindex found", value: pageData.robotsMeta });
+  }
+  let isSelfCanonical;
+  if (pageData.canonical) {
+    isSelfCanonical = pageData.canonical === url || pageData.canonical.replace(/\/$/, "") === url.replace(/\/$/, "");
+    if (!isSelfCanonical) {
+      issues.push({ rule: "cross-canonical", severity: "warning", message: "Cross-canonical points elsewhere", value: pageData.canonical });
+    }
+  } else {
+    issues.push({ rule: "missing-canonical", severity: "warning", message: "No canonical link tag" });
+  }
+  if (!pageData.title) {
+    issues.push({ rule: "missing-title", severity: "critical", message: "Page has no title tag" });
+  } else if (pageData.title.length > 60) {
+    issues.push({ rule: "title-too-long", severity: "warning", message: `Title ${pageData.title.length} chars (>60)`, value: pageData.title });
+  }
+  if (!pageData.description) {
+    issues.push({ rule: "missing-description", severity: "warning", message: "Missing meta description" });
+  } else if (pageData.description.length > 160) {
+    issues.push({ rule: "description-too-long", severity: "info", message: `Description ${pageData.description.length} chars (>160)` });
+  }
+  if (!pageData.ogTitle) issues.push({ rule: "missing-og-title", severity: "info", message: "Missing og:title" });
+  if (!pageData.ogImage) issues.push({ rule: "missing-og-image", severity: "info", message: "Missing og:image" });
+  if (!pageData.hasJsonLd) issues.push({ rule: "no-structured-data", severity: "info", message: "No JSON-LD structured data found" });
+  try {
+    const depth = new URL(url).pathname.split("/").filter(Boolean).length;
+    if (depth > 5) issues.push({ rule: "deep-url", severity: "info", message: `URL depth ${depth} (>5 levels)`, value: url });
+  } catch {
+  }
+  const criticals = issues.filter((i) => i.severity === "critical").length;
+  const warnings = issues.filter((i) => i.severity === "warning").length;
+  const score = Math.max(0, 100 - criticals * 20 - warnings * 5 - issues.filter((i) => i.severity === "info").length * 2);
+  return {
+    url,
+    isIndexable,
+    canonicalUrl: pageData.canonical || void 0,
+    isSelfCanonical,
+    hreflang: pageData.hreflang,
+    issues,
+    score,
+    checkedAt
+  };
+}
+export {
+  checkSeo
+};
+//# sourceMappingURL=seo-checker.js.map

package/dist/seo-checker.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/seo-checker.ts"],
+  "sourcesContent": ["/**\n * SEO indexability checker \u2014 determines if a page is crawlable and indexable.\n *\n * Checks:\n * 1. X-Robots-Tag response header (noindex, nofollow, noarchive)\n * 2. <meta name=\"robots\"> tag (noindex, nofollow)\n * 3. Canonical URL (self-canonical vs cross-canonical)\n * 4. rel=\"nofollow\" on outbound links\n * 5. hreflang tags (multilingual)\n * 6. Open Graph completeness (og:title, og:description, og:image)\n * 7. Structured data presence (JSON-LD)\n * 8. Meta description\n * 9. Title tag length (< 60 chars recommended)\n * 10. URL structure (query params, fragments, excessive depth)\n */\n\nimport type { Page } from 'playwright';\n\nexport interface SeoIssue {\n  rule: string;\n  severity: 'critical' | 'warning' | 'info';\n  message: string;\n  value?: string;\n}\n\nexport interface SeoCheckResult {\n  url: string;\n  isIndexable: boolean;\n  canonicalUrl?: string;\n  isSelfCanonical?: boolean;\n  hreflang: Record<string, string>; // lang \u2192 url\n  issues: SeoIssue[];\n  score: number; // 0-100\n  checkedAt: string;\n}\n\nexport async function checkSeo(page: Page, url: string, responseHeaders: Record<string, string> = {}): Promise<SeoCheckResult> {\n  const issues: SeoIssue[] = [];\n  const checkedAt = new Date().toISOString();\n  let isIndexable = true;\n\n  // 1. X-Robots-Tag\n  const robotsHeader = responseHeaders['x-robots-tag'] ?? '';\n  if (/noindex/i.test(robotsHeader)) {\n    isIndexable = false;\n    issues.push({ rule: 'x-robots-noindex', severity: 'critical', message: 'X-Robots-Tag: noindex found in response header', value: robotsHeader });\n  }\n\n  // 2-9. Page-level checks\n  const pageData = await page.evaluate(() => {\n    const meta = (name: string) => document.querySelector(`meta[name=\"${name}\"]`)?.getAttribute('content') ?? '';\n    const og = (prop: string) => document.querySelector(`meta[property=\"og:${prop}\"]`)?.getAttribute('content') ?? '';\n    const canonical = document.querySelector('link[rel=\"canonical\"]')?.getAttribute('href') ?? '';\n    const hreflang: Record<string, string> = {};\n    document.querySelectorAll('link[rel=\"alternate\"][hreflang]').forEach((el: any) => {\n      hreflang[el.getAttribute('hreflang')] = el.getAttribute('href') ?? '';\n    });\n    const jsonLd = Array.from(document.querySelectorAll('script[type=\"application/ld+json\"]')).map((s: any) => s.textContent ?? '');\n    return {\n      robotsMeta: meta('robots'),\n      description: meta('description'),\n      title: document.title ?? '',\n      canonical,\n      hreflang,\n      ogTitle: og('title'),\n      ogDescription: og('description'),\n      ogImage: og('image'),\n      hasJsonLd: jsonLd.length > 0,\n      jsonLd,\n    };\n  }).catch(() => ({\n    robotsMeta: '', description: '', title: '', canonical: '', hreflang: {},\n    ogTitle: '', ogDescription: '', ogImage: '', hasJsonLd: false, jsonLd: [],\n  }));\n\n  // 2. Meta robots\n  if (/noindex/i.test(pageData.robotsMeta)) {\n    isIndexable = false;\n    issues.push({ rule: 'meta-robots-noindex', severity: 'critical', message: 'Meta robots noindex found', value: pageData.robotsMeta });\n  }\n\n  // 3. Canonical\n  let isSelfCanonical: boolean | undefined;\n  if (pageData.canonical) {\n    isSelfCanonical = pageData.canonical === url || pageData.canonical.replace(/\\/$/, '') === url.replace(/\\/$/, '');\n    if (!isSelfCanonical) {\n      issues.push({ rule: 'cross-canonical', severity: 'warning', message: 'Cross-canonical points elsewhere', value: pageData.canonical });\n    }\n  } else {\n    issues.push({ rule: 'missing-canonical', severity: 'warning', message: 'No canonical link tag' });\n  }\n\n  // 4. Title\n  if (!pageData.title) {\n    issues.push({ rule: 'missing-title', severity: 'critical', message: 'Page has no title tag' });\n  } else if (pageData.title.length > 60) {\n    issues.push({ rule: 'title-too-long', severity: 'warning', message: `Title ${pageData.title.length} chars (>60)`, value: pageData.title });\n  }\n\n  // 5. Meta description\n  if (!pageData.description) {\n    issues.push({ rule: 'missing-description', severity: 'warning', message: 'Missing meta description' });\n  } else if (pageData.description.length > 160) {\n    issues.push({ rule: 'description-too-long', severity: 'info', message: `Description ${pageData.description.length} chars (>160)` });\n  }\n\n  // 6. OG tags\n  if (!pageData.ogTitle) issues.push({ rule: 'missing-og-title', severity: 'info', message: 'Missing og:title' });\n  if (!pageData.ogImage) issues.push({ rule: 'missing-og-image', severity: 'info', message: 'Missing og:image' });\n\n  // 7. Structured data\n  if (!pageData.hasJsonLd) issues.push({ rule: 'no-structured-data', severity: 'info', message: 'No JSON-LD structured data found' });\n\n  // 8. URL depth\n  try {\n    const depth = new URL(url).pathname.split('/').filter(Boolean).length;\n    if (depth > 5) issues.push({ rule: 'deep-url', severity: 'info', message: `URL depth ${depth} (>5 levels)`, value: url });\n  } catch {}\n\n  const criticals = issues.filter(i => i.severity === 'critical').length;\n  const warnings = issues.filter(i => i.severity === 'warning').length;\n  const score = Math.max(0, 100 - criticals * 20 - warnings * 5 - issues.filter(i => i.severity === 'info').length * 2);\n\n  return {\n    url,\n    isIndexable,\n    canonicalUrl: pageData.canonical || undefined,\n    isSelfCanonical,\n    hreflang: pageData.hreflang,\n    issues,\n    score,\n    checkedAt,\n  };\n}\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/session-capture.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Opens a headed (visible) browser at appUrl and returns a captureId.
+ * The user logs in manually, then calls completeSessionCapture() to harvest storageState.
+ * Sessions expire after 10 minutes if not completed.
+ *
+ * Throws 'HEADLESS_ENV' if running in Docker/Linux without a display server.
+ * The API route surfaces this as a 503 so the frontend can switch to manual JSON paste.
+ */
+export declare function startSessionCapture(appUrl: string): Promise<string>;
+/** Captures storageState from the open browser, closes it, and returns the JSON string. */
+export declare function completeSessionCapture(captureId: string): Promise<string>;
+/** Closes the browser without capturing — called on Cancel. */
+export declare function cancelSessionCapture(captureId: string): Promise<void>;
+/**
+ * Headless login + session capture — works on Docker/cloud (no display needed).
+ * Tries DOM-based login first (fast, free). If it fails and llmConfig is provided,
+ * falls back to Stagehand AI-guided login (handles modals, multi-step, marketing pages).
+ *
+ * Returns { storageState, cookies, localStorage } on success.
+ * Throws a human-readable error on failure.
+ */
+export declare function validateAndCaptureSession(appUrl: string, creds: {
+    username: string;
+    password: string;
+    totpSecret?: string;
+    httpBasicUsername?: string;
+    httpBasicPassword?: string;
+}, llmConfig?: {
+    modelName: string;
+    apiKey: string;
+}): Promise<{
+    storageState: string;
+    cookies: number;
+    localStorage: number;
+}>;