mcp-scraper 0.1.0 → 0.1.1

package/dist/chunk-HERFK7W6.js

@@ -0,0 +1,2781 @@
+// src/schemas.ts
+import { z } from "zod";
+var HarvestOptionsSchema = z.object({
+  query: z.string().min(1),
+  location: z.string().optional(),
+  gl: z.string().length(2).default("us"),
+  hl: z.string().length(2).default("en"),
+  device: z.enum(["desktop", "mobile"]).default("desktop"),
+  proxyMode: z.enum(["location", "configured", "none"]).default("location"),
+  proxyZip: z.string().regex(/^\d{5}$/).optional(),
+  debug: z.boolean().default(false),
+  depth: z.number().int().min(1).max(30).default(3),
+  maxQuestions: z.number().int().min(1).max(1e3).default(100),
+  headless: z.boolean().default(false),
+  profileDir: z.string().optional(),
+  proxy: z.string().url().optional(),
+  kernelApiKey: z.string().optional(),
+  kernelProxyId: z.string().optional(),
+  kernelProxyResolution: z.unknown().optional(),
+  outputDir: z.string().default("./paa-output"),
+  format: z.enum(["json", "csv", "both"]).default("both"),
+  serpOnly: z.boolean().default(false),
+  pages: z.number().int().min(1).max(2).default(1)
+});
+var MapsPlaceOptionsSchema = z.object({
+  businessName: z.string().min(1),
+  location: z.string().min(1),
+  gl: z.string().length(2).default("us"),
+  hl: z.string().length(2).default("en"),
+  includeReviews: z.boolean().default(false),
+  maxReviews: z.number().int().min(1).max(500).default(50),
+  kernelApiKey: z.string().optional(),
+  kernelProxyId: z.string().optional(),
+  headless: z.boolean().default(true)
+});
+var RawPAAItemSchema = z.object({
+  question: z.string().min(1),
+  answer: z.string().optional(),
+  sourceTitle: z.string().optional(),
+  sourceSite: z.string().optional(),
+  sourceCite: z.string().optional()
+});
+var RawMapsOverviewSchema = z.object({
+  name: z.string().nullable(),
+  rating: z.string().nullable(),
+  reviewCount: z.string().nullable(),
+  category: z.string().nullable(),
+  address: z.string().nullable(),
+  hoursSummary: z.string().nullable(),
+  phone: z.string().nullable(),
+  phoneDisplay: z.string().nullable(),
+  website: z.string().nullable(),
+  plusCode: z.string().nullable(),
+  bookingUrl: z.string().nullable()
+});
+var RawMapsHoursRowSchema = z.object({
+  day: z.string(),
+  hours: z.string()
+});
+var RawMapsReviewStatsSchema = z.object({
+  reviewHistogram: z.array(z.object({
+    stars: z.number(),
+    count: z.string()
+  })),
+  reviewTopics: z.array(z.object({
+    label: z.string(),
+    count: z.string()
+  }))
+});
+var RawMapsReviewCardSchema = z.object({
+  reviewId: z.string(),
+  author: z.string().nullable(),
+  stars: z.string().nullable(),
+  date: z.string().nullable(),
+  text: z.string().nullable(),
+  ownerResponse: z.string().nullable()
+});
+var RawMapsAboutAttributeSchema = z.object({
+  section: z.string(),
+  attribute: z.string()
+});
+
+// src/driver/BrowserDriver.ts
+import { chromium } from "playwright-extra";
+import StealthPlugin from "puppeteer-extra-plugin-stealth";
+import { chromium as playwrightChromium } from "playwright";
+import Kernel from "@onkernel/sdk";
+
+// src/selectors.ts
+var PAASelectors = {
+  container: ".eJH8qe.adDDi",
+  dataInitq: "[data-initq]",
+  item: ".related-question-pair",
+  itemDataQ: "data-q",
+  itemDataInitQ: "data-initq",
+  itemQuestionEl: ".JlqpRe",
+  answerContainer: ".bCOlv, .hgKElc, .wDYxhc, .LGOjhe, .fo7IQd, .fmW3u",
+  sourceTitle: "h3",
+  sourceSite: ".VuuXrf",
+  sourceCite: "cite",
+  clickTarget: ".JlqpRe",
+  expandedClass: "aoRk1c",
+  captchaMarker: '#captcha-form, #recaptcha, form[action*="/sorry/"], .g-recaptcha, [data-sitekey]'
+};
+var VideoSelectors = {
+  container: 'div[jscontroller="HWk0Gf"]',
+  sectionHeading: '.mgAbYb[role="heading"]',
+  item: "a.rIRoqf"
+};
+var ShortVideoSelectors = {
+  udm: "39",
+  item: "a.rIRoqf",
+  durationPattern: /^\d+:\d+$/,
+  platforms: ["YouTube", "TikTok", "Instagram", "Facebook", "X"]
+};
+var ForumSelectors = {
+  section: ".ULSxyf",
+  item: "a.KYg7td.INpicf",
+  title: ".hyYc0c",
+  source: ".K4ETW"
+};
+var WhatPeopleSayingSelectors = {
+  sectionTag: "g-section-with-header",
+  sectionHeadingText: "What people are saying",
+  card: '.dRzkFf[role="listitem"]',
+  cardLink: 'a.WlydOe[jsname="YKoRaf"]',
+  titleH1: "h1.WQWxe",
+  titleDiv: ".eAaXgc",
+  popularCommentLabel: ".qgdis",
+  source: ".sTl1Td",
+  platformBadge: ".appd0, .KrMNbf",
+  ytChannel: ".sjVJQd",
+  ytDate: ".PLq9Je",
+  authorNote: ".nDgy9d"
+};
+var AIOverviewSelectors = {
+  root: "[data-lhcontainer][data-streaming-container][eid]",
+  legacyRoot: '[data-hveid="CBMQAA"]',
+  wrapper: ".Fgyi2e",
+  controller: '[jscontroller="AkrxPe"]',
+  contentSubtree: '[data-subtree="mfc"]',
+  header: ".heWuVc",
+  heading: ".Fzsovc.cwYVJe.RJPOee",
+  showMoreButton: '[aria-label="Show more AI Overview"]',
+  sourcesPanel: ".OZ9ddf.WAUd4",
+  disclaimer: ".DuQANe.MSJHRb"
+};
+var AIModeSelectors = {
+  root: '[data-hveid="CAUQAA"]',
+  wrapper: ".Fgyi2e",
+  citations: '.Fgyi2e [data-hveid] a[jsname="pxBnId"]'
+};
+var OrganicSelectors = {
+  result: ".wHYlTd.tF2Cxc",
+  title: "h3.LC20lb",
+  siteName: ".VuuXrf",
+  cite: "cite.tjvcx",
+  snippet: ".VwiC3b",
+  redditCite: "cite.qLRx3b",
+  ratingWrap: ".Y0A0hc",
+  ratingValue: ".yi40Hd",
+  reviewCount: ".RDApEe"
+};
+var LocalPackSelectors = {
+  headingText: "Businesses",
+  card: ".w7Dbne",
+  name: ".OSrXXb",
+  ratingValue: ".yi40Hd",
+  reviewCount: ".RDApEe"
+};
+var MapsSelectors = {
+  ratingAndCount: "div.F7nice",
+  hoursTable: "table.eK4R0e",
+  reviewScrollPane: 'div.m6QErb[tabindex="-1"]',
+  reviewScrollPaneFallback: '[role="main"] div[tabindex="-1"]',
+  reviewCardAuthor: "div.d4r55, span.d4r55, span.RPZfBb",
+  reviewCardDate: "span.rsqaWe",
+  reviewCardText: "span.wiI7pd",
+  reviewCardOwnerBlock: "div.CDe7pd",
+  hoursTableAlt: 'table[aria-label*="Hour"]',
+  reviewCard: "[data-review-id]",
+  reviewStars: '[role="img"][aria-label*="star"]',
+  reviewTab: 'button[role="tab"][aria-label*="Review"]',
+  aboutTab: 'button[role="tab"][aria-label*="About"]',
+  expandReview: '[data-review-id] button[aria-label*="See more"], [data-review-id] button.w8nwRe'
+};
+
+// src/errors.ts
+var RECAPTCHA_INSTRUCTIONS = "Google returned a CAPTCHA. Run with --headless=false to re-warm the browser profile, then retry.";
+function sanitizeVendorName(message) {
+  return message.replace(/kernel\.sh\s+sessions?/gi, "sessions").replace(/kernel\.sh\s+session/gi, "this session").replace(/kernel\.sh/gi, "the service").replace(/kernel\s+sessions?/gi, "sessions").replace(/kernel\s+session/gi, "this session").replace(/\bkernel\b/gi, "the service").replace(/  +/g, " ").trim();
+}
+var CaptchaError = class extends Error {
+  constructor(instructions) {
+    super(`CAPTCHA detected. ${instructions}`);
+    this.instructions = instructions;
+  }
+  instructions;
+  name = "CaptchaError";
+};
+var ExtractionError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+  }
+  cause;
+  name = "ExtractionError";
+};
+var RequestAbortedError = class extends Error {
+  name = "RequestAbortedError";
+  constructor(message = "Request aborted before harvest completed") {
+    super(message);
+  }
+};
+
+// src/driver/BrowserDriver.ts
+chromium.use(StealthPlugin());
+var DESKTOP_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36";
+var MOBILE_USER_AGENT = "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1";
+var DEFAULT_KERNEL_BROWSER_TIMEOUT_SECONDS = 180;
+var KERNEL_BROWSER_CLOSE_TIMEOUT_MS = 3e3;
+var KERNEL_SESSION_DELETE_TIMEOUT_MS = 5e3;
+function positiveIntFromEnv(name, fallback) {
+  const raw = process.env[name];
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  return Number.isInteger(parsed) && parsed > 0 ? parsed : fallback;
+}
+function proxyIdSuffix(proxyId) {
+  return proxyId ? proxyId.slice(-6) : null;
+}
+function errorText(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function rankCheckContextOptions(config) {
+  return {
+    viewport: config.viewport,
+    locale: config.locale,
+    userAgent: config.userAgent ?? (config.isMobile ? MOBILE_USER_AGENT : DESKTOP_USER_AGENT),
+    ...config.deviceScaleFactor ? { deviceScaleFactor: config.deviceScaleFactor } : {},
+    ...config.isMobile !== void 0 ? { isMobile: config.isMobile } : {},
+    ...config.hasTouch !== void 0 ? { hasTouch: config.hasTouch } : {}
+  };
+}
+async function withTimeout(promise, timeoutMs, label) {
+  let timeout;
+  try {
+    return await Promise.race([
+      promise,
+      new Promise((_, reject) => {
+        timeout = setTimeout(() => reject(new Error(`${label} timed out after ${timeoutMs}ms`)), timeoutMs);
+      })
+    ]);
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+function buildYouTubeChannelVideosUrl(channelInput) {
+  const raw = channelInput.trim();
+  if (!raw) throw new Error("channelHandle is required");
+  const urlLike = /^https?:\/\//i.test(raw) || /^(www\.|m\.)?youtube\.com\//i.test(raw);
+  if (urlLike) {
+    const parsed = new URL(/^https?:\/\//i.test(raw) ? raw : `https://${raw}`);
+    const host = parsed.hostname.replace(/^www\./, "").replace(/^m\./, "").toLowerCase();
+    if (host !== "youtube.com") throw new Error("channel URL must be on youtube.com");
+    const segments = parsed.pathname.split("/").filter(Boolean);
+    const first = segments[0] ?? "";
+    const second = segments[1] ?? "";
+    if (first.startsWith("@")) return `https://www.youtube.com/${first}/videos`;
+    if (first === "channel" && second) return `https://www.youtube.com/channel/${second}/videos`;
+    if ((first === "c" || first === "user") && second) return `https://www.youtube.com/${first}/${second}/videos`;
+    throw new Error("channel URL must be a YouTube handle, /channel/UC..., /c/..., or /user/... URL");
+  }
+  const stripped = raw.replace(/^\/+/, "").replace(/\/+$/, "");
+  const withoutVideos = stripped.replace(/\/videos$/i, "");
+  if (/^UC[\w-]{20,}$/.test(withoutVideos)) {
+    return `https://www.youtube.com/channel/${withoutVideos}/videos`;
+  }
+  const handle = withoutVideos.startsWith("@") ? withoutVideos : `@${withoutVideos}`;
+  if (!/^@[\w.-]+$/.test(handle)) {
+    throw new Error("channelHandle must be an @handle, UC channel ID, or YouTube channel URL");
+  }
+  return `https://www.youtube.com/${handle}/videos`;
+}
+var BrowserDriver = class {
+  browser = null;
+  context = null;
+  page = null;
+  kernelClient = null;
+  kernelSessionId = null;
+  debugEnabled = false;
+  debugSnapshot = {
+    kernel: null,
+    context: null,
+    networkLocation: null,
+    serpNavigation: null
+  };
+  async launch(config) {
+    this.debugEnabled = config.debug === true;
+    const proxyMode = config.proxyMode ?? (config.kernelProxyId ? "configured" : "none");
+    const device = config.isMobile ? "mobile" : "desktop";
+    this.debugSnapshot = {
+      kernel: null,
+      context: {
+        viewport: config.viewport,
+        locale: config.locale,
+        device,
+        userAgent: config.userAgent ?? (config.isMobile ? MOBILE_USER_AGENT : DESKTOP_USER_AGENT),
+        deviceScaleFactor: config.deviceScaleFactor ?? null,
+        isMobile: config.isMobile === true,
+        hasTouch: config.hasTouch === true
+      },
+      networkLocation: null,
+      serpNavigation: null
+    };
+    if (config.kernelApiKey) {
+      this.kernelClient = new Kernel({ apiKey: config.kernelApiKey });
+      const timeoutSeconds = positiveIntFromEnv("KERNEL_BROWSER_TIMEOUT_SECONDS", DEFAULT_KERNEL_BROWSER_TIMEOUT_SECONDS);
+      const kernelBrowser = await this.kernelClient.browsers.create({
+        stealth: true,
+        timeout_seconds: timeoutSeconds,
+        ...config.kernelProxyId ? { proxy_id: config.kernelProxyId } : {}
+      });
+      this.kernelSessionId = kernelBrowser.session_id;
+      let defaultProxyDisabled = null;
+      let defaultProxyDisableError = null;
+      if (proxyMode === "none") {
+        try {
+          await withTimeout(
+            this.kernelClient.browsers.update(this.kernelSessionId, { disable_default_proxy: true }),
+            5e3,
+            `Kernel session ${this.kernelSessionId} disable default proxy`
+          );
+          defaultProxyDisabled = true;
+        } catch (err) {
+          defaultProxyDisabled = false;
+          defaultProxyDisableError = errorText(err);
+        }
+      }
+      const kernelDebug = {
+        sessionId: this.kernelSessionId,
+        proxyMode,
+        requestedProxyIdPresent: Boolean(config.kernelProxyId),
+        requestedProxyIdSuffix: proxyIdSuffix(config.kernelProxyId),
+        createdProxyIdPresent: typeof kernelBrowser.proxy_id === "string" ? Boolean(kernelBrowser.proxy_id) : null,
+        createdProxyIdSuffix: proxyIdSuffix(kernelBrowser.proxy_id),
+        retrievedProxyIdPresent: null,
+        retrievedProxyIdSuffix: null,
+        retrievedProxyIdMatchesRequested: null,
+        defaultProxyDisabled,
+        defaultProxyDisableError,
+        proxyResolution: config.kernelProxyResolution ?? null,
+        timeoutSeconds,
+        stealth: typeof kernelBrowser.stealth === "boolean" ? kernelBrowser.stealth : null,
+        profilePresent: null,
+        poolPresent: null,
+        retrieveError: null
+      };
+      this.debugSnapshot.kernel = kernelDebug;
+      console.info(JSON.stringify({
+        event: "kernel_browser_created",
+        kernel_session_id: this.kernelSessionId,
+        timeout_seconds: timeoutSeconds,
+        proxy_mode: proxyMode,
+        proxy_id_present: Boolean(config.kernelProxyId),
+        proxy_resolution_source: config.kernelProxyResolution?.source
+      }));
+      if (this.debugEnabled) {
+        await this.populateKernelRetrieveDebug(kernelDebug, config.kernelProxyId);
+      }
+      this.browser = await playwrightChromium.connectOverCDP(kernelBrowser.cdp_ws_url);
+      this.context = await this.browser.newContext(rankCheckContextOptions(config));
+      await this.installEsbuildHelperShims(this.context);
+      this.page = await this.context.newPage();
+      await this.page.setViewportSize(config.viewport);
+      if (this.debugEnabled) {
+        this.debugSnapshot.networkLocation = await this.captureBrowserNetworkLocation();
+      }
+      return;
+    }
+    const launchOpts = {
+      headless: config.headless,
+      proxy: config.proxy ? { server: config.proxy } : void 0
+    };
+    const ctxOpts = rankCheckContextOptions(config);
+    if (config.profileDir) {
+      this.context = await chromium.launchPersistentContext(config.profileDir, {
+        ...launchOpts,
+        ...ctxOpts
+      });
+      await this.installEsbuildHelperShims(this.context);
+      this.page = await this.context.newPage();
+    } else {
+      this.browser = await chromium.launch(launchOpts);
+      this.context = await this.browser.newContext(ctxOpts);
+      await this.installEsbuildHelperShims(this.context);
+      this.page = await this.context.newPage();
+    }
+    if (this.debugEnabled) {
+      this.debugSnapshot.networkLocation = await this.captureBrowserNetworkLocation();
+    }
+  }
+  async populateKernelRetrieveDebug(kernelDebug, requestedProxyId) {
+    if (!this.kernelClient || !this.kernelSessionId) return;
+    try {
+      const retrieved = await withTimeout(
+        this.kernelClient.browsers.retrieve(this.kernelSessionId),
+        5e3,
+        `Kernel session ${this.kernelSessionId} retrieve`
+      );
+      kernelDebug.retrievedProxyIdPresent = typeof retrieved.proxy_id === "string" ? Boolean(retrieved.proxy_id) : false;
+      kernelDebug.retrievedProxyIdSuffix = proxyIdSuffix(retrieved.proxy_id);
+      kernelDebug.retrievedProxyIdMatchesRequested = requestedProxyId ? retrieved.proxy_id === requestedProxyId : !retrieved.proxy_id;
+      kernelDebug.timeoutSeconds = typeof retrieved.timeout_seconds === "number" ? retrieved.timeout_seconds : kernelDebug.timeoutSeconds;
+      kernelDebug.stealth = typeof retrieved.stealth === "boolean" ? retrieved.stealth : kernelDebug.stealth;
+      kernelDebug.profilePresent = Boolean(retrieved.profile);
+      kernelDebug.poolPresent = Boolean(retrieved.pool);
+    } catch (err) {
+      kernelDebug.retrieveError = errorText(err);
+    }
+  }
+  async captureBrowserNetworkLocation() {
+    const fallback = (message, source = "ipapi.co") => ({
+      source,
+      ip: null,
+      city: null,
+      region: null,
+      country: null,
+      org: null,
+      timezone: null,
+      error: message
+    });
+    if (!this.context) return fallback("browser context is not available");
+    let debugPage = null;
+    try {
+      debugPage = await this.context.newPage();
+      const ipwho = await this.loadJsonInDebugPage(debugPage, "https://ipwho.is/");
+      if (ipwho) {
+        const connection = typeof ipwho.connection === "object" && ipwho.connection !== null ? ipwho.connection : {};
+        return {
+          source: "ipwho.is",
+          ip: typeof ipwho.ip === "string" ? ipwho.ip : null,
+          city: typeof ipwho.city === "string" ? ipwho.city : null,
+          region: typeof ipwho.region === "string" ? ipwho.region : null,
+          country: typeof ipwho.country === "string" ? ipwho.country : null,
+          org: typeof connection.org === "string" ? connection.org : null,
+          timezone: typeof ipwho.timezone === "object" && ipwho.timezone !== null && typeof ipwho.timezone.id === "string" ? ipwho.timezone.id : null,
+          error: null
+        };
+      }
+      const ipify = await this.loadJsonInDebugPage(debugPage, "https://api64.ipify.org?format=json");
+      if (ipify) {
+        return {
+          source: "api64.ipify.org",
+          ip: typeof ipify.ip === "string" ? ipify.ip : null,
+          city: null,
+          region: null,
+          country: null,
+          org: null,
+          timezone: null,
+          error: null
+        };
+      }
+      await withTimeout(
+        debugPage.goto("https://ipapi.co/json/", { waitUntil: "domcontentloaded", timeout: 7e3 }),
+        8e3,
+        "browser network location navigation"
+      );
+      const body = await debugPage.locator("body").innerText({ timeout: 2e3 });
+      const data = JSON.parse(body);
+      return {
+        source: "ipapi.co",
+        ip: typeof data.ip === "string" ? data.ip : null,
+        city: typeof data.city === "string" ? data.city : null,
+        region: typeof data.region === "string" ? data.region : null,
+        country: typeof data.country_name === "string" ? data.country_name : typeof data.country === "string" ? data.country : null,
+        org: typeof data.org === "string" ? data.org : null,
+        timezone: typeof data.timezone === "string" ? data.timezone : null,
+        error: null
+      };
+    } catch (err) {
+      return fallback(errorText(err));
+    } finally {
+      await debugPage?.close().catch(() => {
+      });
+    }
+  }
+  async loadJsonInDebugPage(debugPage, url) {
+    try {
+      await withTimeout(
+        debugPage.goto(url, { waitUntil: "domcontentloaded", timeout: 7e3 }),
+        8e3,
+        `browser network location navigation ${url}`
+      );
+      const body = await debugPage.locator("body").innerText({ timeout: 2e3 });
+      return JSON.parse(body);
+    } catch {
+      return null;
+    }
+  }
+  async installEsbuildHelperShims(context) {
+    await context.addInitScript(() => {
+      const g = globalThis;
+      if (typeof g.__name !== "function") g.__name = (fn) => fn;
+      if (typeof g.__publicField !== "function") g.__publicField = (obj, key, value) => {
+        obj[key] = value;
+        return value;
+      };
+    });
+  }
+  async navigateToSERP(query, uule, gl, hl, options) {
+    const params = new URLSearchParams({ q: query, gl, hl, pws: "0" });
+    if (options?.num) params.set("num", String(options.num));
+    if (uule) params.set("uule", uule);
+    const url = "https://www.google.com/search?" + params.toString();
+    const navDebug = options?.debug ? {
+      requestedUrl: url,
+      finalUrl: null,
+      title: null,
+      bodySnippet: null,
+      hasPaa: null,
+      captchaDetected: null,
+      googleSorryUrl: null,
+      redirected: null
+    } : null;
+    if (navDebug) this.debugSnapshot.serpNavigation = navDebug;
+    try {
+      await this.page.goto(url, { waitUntil: "domcontentloaded", timeout: 45e3 });
+    } catch (err) {
+      await this.updateSerpNavigationDebug(navDebug, url, { hasPaa: null, captchaDetected: null });
+      const diag = await this.captureDiagnostics(url);
+      throw new ExtractionError(`page.goto failed: ${err.message} | ${diag}`);
+    }
+    const captchaCount = await this.page.locator(PAASelectors.captchaMarker).count();
+    if (captchaCount > 0) {
+      await this.updateSerpNavigationDebug(navDebug, url, { hasPaa: false, captchaDetected: true });
+      throw new CaptchaError(this.captchaMessage());
+    }
+    const fastFound = await this.page.waitForSelector(PAASelectors.item, { timeout: 4e3 }).catch(() => null);
+    if (fastFound) {
+      await this.updateSerpNavigationDebug(navDebug, url, { hasPaa: true, captchaDetected: false });
+      return { hasPaa: true };
+    }
+    const captchaAfter = await this.page.locator(PAASelectors.captchaMarker).count();
+    if (captchaAfter > 0) {
+      await this.updateSerpNavigationDebug(navDebug, url, { hasPaa: false, captchaDetected: true });
+      throw new CaptchaError(this.captchaMessage());
+    }
+    for (let i = 1; i <= 6; i++) {
+      await this.page.evaluate((f) => {
+        window.scrollTo(0, document.body.scrollHeight * f);
+      }, i / 6);
+      await this.page.waitForTimeout(600);
+      const count = await this.page.locator(PAASelectors.item).count();
+      if (count > 0) {
+        await this.updateSerpNavigationDebug(navDebug, url, { hasPaa: true, captchaDetected: false });
+        return { hasPaa: true };
+      }
+    }
+    await this.updateSerpNavigationDebug(navDebug, url, { hasPaa: false, captchaDetected: false });
+    return { hasPaa: false };
+  }
+  async updateSerpNavigationDebug(navDebug, requestedUrl, state) {
+    if (!navDebug || !this.page) return;
+    try {
+      const finalUrl = this.page.url();
+      const title = await this.page.title().catch(() => "");
+      const bodySnippet = await this.page.evaluate(() => {
+        const text = (document.body?.innerText ?? "").replace(/\s+/g, " ").trim();
+        return text.slice(0, 500);
+      }).catch(() => "");
+      const textCaptcha = /recaptcha|unusual traffic|are you a robot/i.test(bodySnippet);
+      navDebug.finalUrl = finalUrl;
+      navDebug.title = title;
+      navDebug.bodySnippet = bodySnippet;
+      navDebug.hasPaa = state.hasPaa;
+      navDebug.captchaDetected = state.captchaDetected ?? textCaptcha;
+      navDebug.googleSorryUrl = /google\.[^/]+\/sorry\//i.test(finalUrl);
+      navDebug.redirected = finalUrl !== requestedUrl;
+    } catch (err) {
+      navDebug.bodySnippet = `debug capture failed: ${errorText(err)}`;
+    }
+  }
+  async captureDiagnostics(intendedUrl) {
+    try {
+      const finalUrl = this.page.url();
+      const title = await this.page.title().catch(() => "");
+      const bodySnippet = await this.page.evaluate(() => {
+        const t = (document.body?.innerText ?? "").replace(/\s+/g, " ").trim();
+        return t.slice(0, 400);
+      }).catch(() => "");
+      const consent = /consent\.google\./.test(finalUrl) || /before you continue/i.test(bodySnippet);
+      const recaptcha = /recaptcha|unusual traffic|are you a robot/i.test(bodySnippet);
+      const flags = [
+        consent ? "CONSENT_WALL" : "",
+        recaptcha ? "BOT_CHALLENGE" : "",
+        finalUrl !== intendedUrl ? "REDIRECTED" : ""
+      ].filter(Boolean).join(",");
+      return `intended=${intendedUrl} | final=${finalUrl} | title="${title}" | flags=[${flags}] | body="${bodySnippet}"`;
+    } catch (e) {
+      return `diagnostics-failed: ${e.message}`;
+    }
+  }
+  captchaMessage() {
+    return this.kernelClient ? "Google returned a CAPTCHA on this session \u2014 retrying with a fresh session." : RECAPTCHA_INSTRUCTIONS;
+  }
+  async navigateTo(url) {
+    try {
+      await this.page.goto(url, { waitUntil: "domcontentloaded", timeout: 45e3 });
+    } catch (err) {
+      const diag = await this.captureDiagnostics(url);
+      throw new ExtractionError(`page.goto failed: ${err.message} | ${diag}`);
+    }
+  }
+  async navigateToChannel(channelHandle) {
+    const url = buildYouTubeChannelVideosUrl(channelHandle);
+    try {
+      await this.page.goto(url, { waitUntil: "networkidle", timeout: 3e4 });
+    } catch (err) {
+      const diag = await this.captureDiagnostics(url);
+      throw new ExtractionError(`navigateToChannel failed: ${err.message} | ${diag}`);
+    }
+  }
+  async evaluate(fn, arg) {
+    return this.page.evaluate(fn, arg);
+  }
+  getPage() {
+    return this.page;
+  }
+  getKernelSessionId() {
+    return this.kernelSessionId;
+  }
+  getDebugSnapshot() {
+    return this.debugSnapshot;
+  }
+  async close() {
+    if (this.browser) {
+      const b = this.browser;
+      const sessionId = this.kernelSessionId;
+      const client = this.kernelClient;
+      this.browser = null;
+      this.context = null;
+      this.page = null;
+      this.kernelSessionId = null;
+      this.kernelClient = null;
+      if (client && sessionId) {
+        console.info(JSON.stringify({
+          event: "kernel_browser_delete_started",
+          kernel_session_id: sessionId
+        }));
+        const deleteSession = withTimeout(
+          client.browsers.deleteByID(sessionId),
+          KERNEL_SESSION_DELETE_TIMEOUT_MS,
+          `Kernel session ${sessionId} delete`
+        );
+        const closeBrowser = withTimeout(
+          b.close(),
+          KERNEL_BROWSER_CLOSE_TIMEOUT_MS,
+          `Kernel browser ${sessionId} close`
+        );
+        const [deleteResult, closeResult] = await Promise.allSettled([deleteSession, closeBrowser]);
+        const result = {
+          kernelSessionId: sessionId,
+          kernelDeleteStarted: true,
+          kernelDeleteSucceeded: deleteResult.status === "fulfilled",
+          kernelDeleteError: deleteResult.status === "rejected" ? deleteResult.reason instanceof Error ? deleteResult.reason.message : String(deleteResult.reason) : null,
+          browserCloseSucceeded: closeResult.status === "fulfilled",
+          browserCloseError: closeResult.status === "rejected" ? closeResult.reason instanceof Error ? closeResult.reason.message : String(closeResult.reason) : null
+        };
+        if (deleteResult.status === "rejected") {
+          console.warn(JSON.stringify({
+            event: "kernel_browser_delete_failed",
+            kernel_session_id: sessionId,
+            message: result.kernelDeleteError
+          }));
+          console.warn(`Kernel session cleanup failed for ${sessionId}:`, deleteResult.reason);
+        } else {
+          console.info(JSON.stringify({
+            event: "kernel_browser_delete_succeeded",
+            kernel_session_id: sessionId
+          }));
+        }
+        if (closeResult.status === "rejected") {
+          console.warn(JSON.stringify({
+            event: "kernel_browser_close_failed",
+            kernel_session_id: sessionId,
+            message: result.browserCloseError
+          }));
+          console.warn(`Kernel browser close failed for ${sessionId}:`, closeResult.reason);
+        }
+        return result;
+      }
+      await b.close();
+      return {
+        kernelSessionId: null,
+        kernelDeleteStarted: false,
+        kernelDeleteSucceeded: null,
+        kernelDeleteError: null,
+        browserCloseSucceeded: true,
+        browserCloseError: null
+      };
+    } else if (this.context) {
+      const ctx = this.context;
+      this.context = null;
+      this.page = null;
+      await ctx.close();
+      return {
+        kernelSessionId: null,
+        kernelDeleteStarted: false,
+        kernelDeleteSucceeded: null,
+        kernelDeleteError: null,
+        browserCloseSucceeded: true,
+        browserCloseError: null
+      };
+    }
+    return {
+      kernelSessionId: null,
+      kernelDeleteStarted: false,
+      kernelDeleteSucceeded: null,
+      kernelDeleteError: null,
+      browserCloseSucceeded: null,
+      browserCloseError: null
+    };
+  }
+};
+
+// src/locations.ts
+var LOCATIONS = {
+  "austin": "Austin,Texas,United States",
+  "new york": "New York,New York,United States",
+  "new york city": "New York,New York,United States",
+  "nyc": "New York,New York,United States",
+  "los angeles": "Los Angeles,California,United States",
+  "la": "Los Angeles,California,United States",
+  "chicago": "Chicago,Illinois,United States",
+  "houston": "Houston,Texas,United States",
+  "phoenix": "Phoenix,Arizona,United States",
+  "philadelphia": "Philadelphia,Pennsylvania,United States",
+  "philly": "Philadelphia,Pennsylvania,United States",
+  "san antonio": "San Antonio,Texas,United States",
+  "dallas": "Dallas,Texas,United States",
+  "miami": "Miami,Florida,United States",
+  "seattle": "Seattle,Washington,United States",
+  "denver": "Denver,Colorado,United States",
+  "loveland": "Loveland,Colorado,United States",
+  "loveland co": "Loveland,Colorado,United States",
+  "fort collins": "Fort Collins,Colorado,United States",
+  "boulder": "Boulder,Colorado,United States",
+  "colorado springs": "Colorado Springs,Colorado,United States",
+  "boston": "Boston,Massachusetts,United States",
+  "atlanta": "Atlanta,Georgia,United States",
+  "san francisco": "San Francisco,California,United States",
+  "sf": "San Francisco,California,United States",
+  "portland": "Portland,Oregon,United States",
+  "las vegas": "Las Vegas,Nevada,United States",
+  "minneapolis": "Minneapolis,Minnesota,United States",
+  "detroit": "Detroit,Michigan,United States",
+  "nashville": "Nashville,Tennessee,United States",
+  "charlotte": "Charlotte,North Carolina,United States",
+  "orlando": "Orlando,Florida,United States",
+  "san diego": "San Diego,California,United States",
+  "baltimore": "Baltimore,Maryland,United States",
+  "sacramento": "Sacramento,California,United States",
+  "columbus": "Columbus,Ohio,United States",
+  "indianapolis": "Indianapolis,Indiana,United States",
+  "san jose": "San Jose,California,United States",
+  "fort worth": "Fort Worth,Texas,United States",
+  "jacksonville": "Jacksonville,Florida,United States",
+  "memphis": "Memphis,Tennessee,United States",
+  "louisville": "Louisville,Kentucky,United States",
+  "raleigh": "Raleigh,North Carolina,United States",
+  "richmond": "Richmond,Virginia,United States",
+  "salt lake city": "Salt Lake City,Utah,United States",
+  "toronto": "Toronto,Ontario,Canada",
+  "vancouver": "Vancouver,British Columbia,Canada",
+  "montreal": "Montreal,Quebec,Canada",
+  "calgary": "Calgary,Alberta,Canada",
+  "ottawa": "Ottawa,Ontario,Canada",
+  "london": "London,England,United Kingdom",
+  "manchester": "Manchester,England,United Kingdom",
+  "birmingham": "Birmingham,England,United Kingdom",
+  "edinburgh": "Edinburgh,Scotland,United Kingdom",
+  "glasgow": "Glasgow,Scotland,United Kingdom",
+  "leeds": "Leeds,England,United Kingdom",
+  "sydney": "Sydney,New South Wales,Australia",
+  "melbourne": "Melbourne,Victoria,Australia",
+  "brisbane": "Brisbane,Queensland,Australia",
+  "perth": "Perth,Western Australia,Australia",
+  "adelaide": "Adelaide,South Australia,Australia",
+  "dublin": "Dublin,Leinster,Ireland"
+};
+
+// src/uule.ts
+function encodeVarint(value) {
+  const bytes = [];
+  let remaining = value;
+  do {
+    let byte = remaining & 127;
+    remaining >>>= 7;
+    if (remaining > 0) byte |= 128;
+    bytes.push(byte);
+  } while (remaining > 0);
+  return bytes;
+}
+function encodeUule(name) {
+  const locationBytes = Buffer.from(name, "utf8");
+  const payload = Buffer.concat([
+    Buffer.from([8, 2, 16, 32, 34]),
+    Buffer.from(encodeVarint(locationBytes.length)),
+    locationBytes
+  ]);
+  return `w+${payload.toString("base64")}`;
+}
+function normalizeLocation(input) {
+  const raw = input.toLowerCase().trim();
+  if (LOCATIONS[raw]) return LOCATIONS[raw];
+  const beforeComma = raw.split(",")[0].trim();
+  if (beforeComma !== raw && LOCATIONS[beforeComma]) return LOCATIONS[beforeComma];
+  const withoutState = raw.replace(/\s+[a-z]{2}$/, "").trim();
+  if (withoutState !== raw && LOCATIONS[withoutState]) return LOCATIONS[withoutState];
+  return input;
+}
+
+// src/serp-location-debug.ts
+var STATE_TO_CODE = {
+  alabama: "AL",
+  alaska: "AK",
+  arizona: "AZ",
+  arkansas: "AR",
+  california: "CA",
+  colorado: "CO",
+  connecticut: "CT",
+  delaware: "DE",
+  florida: "FL",
+  georgia: "GA",
+  hawaii: "HI",
+  idaho: "ID",
+  illinois: "IL",
+  indiana: "IN",
+  iowa: "IA",
+  kansas: "KS",
+  kentucky: "KY",
+  louisiana: "LA",
+  maine: "ME",
+  maryland: "MD",
+  massachusetts: "MA",
+  michigan: "MI",
+  minnesota: "MN",
+  mississippi: "MS",
+  missouri: "MO",
+  montana: "MT",
+  nebraska: "NE",
+  nevada: "NV",
+  "new hampshire": "NH",
+  "new jersey": "NJ",
+  "new mexico": "NM",
+  "new york": "NY",
+  "north carolina": "NC",
+  "north dakota": "ND",
+  ohio: "OH",
+  oklahoma: "OK",
+  oregon: "OR",
+  pennsylvania: "PA",
+  "rhode island": "RI",
+  "south carolina": "SC",
+  "south dakota": "SD",
+  tennessee: "TN",
+  texas: "TX",
+  utah: "UT",
+  vermont: "VT",
+  virginia: "VA",
+  washington: "WA",
+  "west virginia": "WV",
+  wisconsin: "WI",
+  wyoming: "WY",
+  "district of columbia": "DC"
+};
+var STATE_PATTERN = [
+  ...Object.keys(STATE_TO_CODE).map((s) => s.replace(/\s+/g, "\\s+")),
+  ...Object.values(STATE_TO_CODE)
+].join("|");
+var CITY_STATE_RE = new RegExp(`\\b([A-Z][A-Za-z]+(?:[\\s.-][A-Z][A-Za-z]+){0,4}),?\\s+(${STATE_PATTERN})\\b`, "gi");
+function normalizeRegionCode(input) {
+  if (!input) return null;
+  const trimmed = input.trim();
+  if (/^[A-Z]{2}$/i.test(trimmed)) return trimmed.toUpperCase();
+  return STATE_TO_CODE[trimmed.toLowerCase()] ?? null;
+}
+function normalizeCity(input) {
+  const cleaned = input.replace(/\s+/g, " ").trim().replace(/^.*\b(?:in|near|around|serving)\s+/i, "");
+  return cleaned.toLowerCase().replace(/\b[a-z]/g, (char) => char.toUpperCase());
+}
+function parseExpected(canonicalLocation) {
+  if (!canonicalLocation) return null;
+  const [city = "", region = ""] = canonicalLocation.split(",").map((part) => part.trim());
+  return {
+    city: normalizeCity(city),
+    regionCode: normalizeRegionCode(region),
+    canonicalLocation
+  };
+}
+function addCandidate(candidates, city, region, example) {
+  const normalizedCity = normalizeCity(city);
+  const regionCode = normalizeRegionCode(region);
+  if (!normalizedCity || !regionCode) return;
+  const key = `${normalizedCity.toLowerCase()}|${regionCode}`;
+  const existing = candidates.get(key);
+  if (existing) {
+    existing.count++;
+    if (existing.examples.length < 3 && !existing.examples.includes(example)) existing.examples.push(example);
+    return;
+  }
+  candidates.set(key, { city: normalizedCity, regionCode, count: 1, examples: [example] });
+}
+function scanText(candidates, text) {
+  const normalized = decodeURIComponent(text).replace(/[+/|_-]+/g, " ");
+  for (const match of normalized.matchAll(CITY_STATE_RE)) {
+    addCandidate(candidates, match[1] ?? "", match[2] ?? "", normalized.slice(0, 180));
+  }
+}
+function inferSerpLocationEvidence(canonicalLocation, organicResults, localPack) {
+  const expected = parseExpected(canonicalLocation);
+  const candidates = /* @__PURE__ */ new Map();
+  for (const result of organicResults) {
+    scanText(candidates, [result.title, result.snippet ?? "", result.cite ?? "", result.url].join(" "));
+  }
+  for (const business of localPack) {
+    scanText(candidates, [business.name, ...business.metadata, business.websiteUrl ?? "", business.directionsUrl ?? ""].join(" "));
+  }
+  const rankedCandidates = Array.from(candidates.values()).sort((a, b) => b.count - a.count || a.city.localeCompare(b.city)).slice(0, 8);
+  if (!expected) {
+    return { status: "not_requested", expected: null, candidates: rankedCandidates };
+  }
+  if (rankedCandidates.length === 0) {
+    return { status: "unknown", expected, candidates: [] };
+  }
+  const matched = rankedCandidates.some(
+    (candidate) => candidate.city.toLowerCase() === expected.city.toLowerCase() && (expected.regionCode == null || candidate.regionCode === expected.regionCode)
+  );
+  return {
+    status: matched ? "matched" : "mismatch",
+    expected,
+    candidates: rankedCandidates
+  };
+}
+
+// src/lib/paa-answer-cleanup.ts
+var MAX_ANSWER_LENGTH = 1200;
+var BOILERPLATE_PATTERNS = [
+  /An AI Overview is not available for this search/gi,
+  /Can't generate an AI overview right now\.?\s*Try again later\.?/gi,
+  /\bAI Overview\b/gi,
+  /\bView all\b/gi
+];
+var CUT_MARKERS = [
+  /\bRelated Links\b/i,
+  /\bAsk anything in\s*AI Mode\b/i,
+  /\bAI can make mistakes\b/i,
+  /\bThis is for informational purposes only\b/i,
+  /\bShow more\b/i,
+  /\b\d+\s+sites\b/i,
+  /\b\d{1,2}\s*[msh]\s*[A-Z][A-Za-z]/,
+  /\b(?:YouTube|Reddit|Facebook|Instagram|TikTok)·/
+];
+function normalizeWhitespace(text) {
+  return text.replace(/\u00a0/g, " ").replace(/([.!?])([A-Z])/g, "$1 $2").replace(/([:;])([A-Z])/g, "$1 $2").replace(/([a-z])([A-Z][a-z])/g, "$1 $2").replace(/(\d)([A-Z][a-z])/g, "$1 $2").replace(/([a-z])(\d)/g, "$1 $2").replace(/\s+/g, " ").trim();
+}
+function cutAtFirstMarker(text) {
+  let cutAt = -1;
+  for (const marker of CUT_MARKERS) {
+    const match = marker.exec(text);
+    marker.lastIndex = 0;
+    if (match && (cutAt === -1 || match.index < cutAt)) cutAt = match.index;
+  }
+  return cutAt === -1 ? text : text.slice(0, cutAt);
+}
+function cutAtSourceTitle(text, sourceTitle) {
+  const title = sourceTitle?.trim();
+  if (!title || title.length < 8) return text;
+  const idx = text.toLowerCase().indexOf(title.toLowerCase());
+  return idx > 40 ? text.slice(0, idx) : text;
+}
+function findAttributionCut(beforeUrl) {
+  const dateMatch = beforeUrl.match(/[•·]\s*(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\.?\s+\d{1,2},\s+\d{4}/i);
+  if (dateMatch?.index && dateMatch.index > 40) return dateMatch.index;
+  const start = Math.max(0, beforeUrl.length - 260);
+  const tail = beforeUrl.slice(start);
+  const sentenceBreaks = [...tail.matchAll(/[.!?]\s*(?=[A-Z][A-Za-z0-9"'$])/g)];
+  for (const match of sentenceBreaks) {
+    const remainder = tail.slice(match.index + 1).trim();
+    const lead = remainder.slice(0, 160);
+    const looksLikeTitle = /^(?:Best|Top|What|How|Why|When|Where|Which|Can|Should|Is|Are|Do|Does)\b/i.test(remainder);
+    if (remainder.length > 20 && looksLikeTitle && /(?:\s[-|]\s|Heating|Cooling|Company|Services|Blog|Guide|Review)/i.test(lead)) {
+      return start + match.index + 1;
+    }
+  }
+  const last = sentenceBreaks.at(-1);
+  if (last?.index !== void 0) return start + last.index + 1;
+  return beforeUrl.length;
+}
+function cutAtUrlAttribution(text) {
+  const urlMatch = text.match(/https?:\/\/\S+/i);
+  if (!urlMatch?.index) return text;
+  const beforeUrl = text.slice(0, urlMatch.index);
+  return beforeUrl.slice(0, findAttributionCut(beforeUrl));
+}
+function trimToSentenceLimit(text) {
+  if (text.length <= MAX_ANSWER_LENGTH) return text;
+  const slice = text.slice(0, MAX_ANSWER_LENGTH);
+  const lastSentence = Math.max(slice.lastIndexOf("."), slice.lastIndexOf("!"), slice.lastIndexOf("?"));
+  return (lastSentence > 240 ? slice.slice(0, lastSentence + 1) : slice).trim();
+}
+function cleanPAAAnswerText(answer, question, sourceTitle) {
+  if (!answer) return void 0;
+  let text = normalizeWhitespace(answer);
+  const normalizedQuestion = question ? normalizeWhitespace(question) : "";
+  if (normalizedQuestion && text.toLowerCase().startsWith(normalizedQuestion.toLowerCase())) {
+    text = text.slice(normalizedQuestion.length).trim();
+  }
+  if (/^An error has occurred\.?\s*Please try again later\.?/i.test(text)) {
+    return void 0;
+  }
+  for (const pattern of BOILERPLATE_PATTERNS) {
+    text = text.replace(pattern, " ");
+  }
+  text = text.replace(/\b[A-Z][A-Za-z&'\u2019 -]{2,60}\+\d+\b/g, " ").replace(/\b(?:[a-z0-9-]+\.)+[a-z]{2,}\+\d+\b/gi, " ");
+  text = normalizeWhitespace(text);
+  text = cutAtFirstMarker(text);
+  text = cutAtSourceTitle(text, sourceTitle);
+  text = cutAtUrlAttribution(text);
+  text = normalizeWhitespace(text);
+  text = text.replace(/\s+(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)[a-z]*\.?\s+\d{1,2},\s+\d{4}$/i, "").trim();
+  text = trimToSentenceLimit(text);
+  if (!text) return void 0;
+  if (/^An error has occurred\.?\s*Please try again later\.?$/i.test(text)) return void 0;
+  return text;
+}
+
+// src/extractor/ai-surfaces.ts
+async function extractAISurfacesFromDocument(config) {
+  const selectors = config ?? {
+    aio: {
+      root: "[data-lhcontainer][data-streaming-container][eid]",
+      legacyRoot: '[data-hveid="CBMQAA"]',
+      wrapper: ".Fgyi2e",
+      controller: '[jscontroller="AkrxPe"]',
+      contentSubtree: '[data-subtree="mfc"]',
+      heading: ".Fzsovc.cwYVJe.RJPOee",
+      header: ".heWuVc",
+      showMoreButton: '[aria-label="Show more AI Overview"]',
+      sourcesPanel: ".OZ9ddf.WAUd4",
+      disclaimer: ".DuQANe.MSJHRb"
+    },
+    aim: {
+      root: '[data-hveid="CAUQAA"]',
+      wrapper: ".Fgyi2e"
+    },
+    expandWaitMs: 1500
+  };
+  const sn = window.google?.sn ?? "unknown";
+  const surface = sn === "aim" ? "aim" : sn === "web" ? "web" : "unknown";
+  function textOf(el) {
+    if (!el) return "";
+    return (el.innerText ?? el.textContent ?? "").trim();
+  }
+  function hasAIOverviewLabel(el) {
+    const heading = el.querySelector(selectors.aio.heading);
+    if (textOf(heading) === "AI Overview") return true;
+    const header = el.querySelector(selectors.aio.header);
+    if (textOf(header).split(/\n|\s{2,}/).some((part) => part.trim() === "AI Overview")) return true;
+    return textOf(el).includes("AI Overview");
+  }
+  function findAIORoot() {
+    const primaryRoots = Array.from(document.querySelectorAll(selectors.aio.root));
+    const labeledPrimary = primaryRoots.find(hasAIOverviewLabel);
+    if (labeledPrimary) return labeledPrimary;
+    if (primaryRoots.length > 0) return primaryRoots[0];
+    if (selectors.aio.legacyRoot) {
+      const legacy = document.querySelector(selectors.aio.legacyRoot);
+      if (legacy) return legacy;
+    }
+    const headings = document.querySelectorAll(`${selectors.aio.heading}, h1, h2, h3, [role="heading"]`);
+    for (const h of headings) {
+      if (textOf(h) !== "AI Overview") continue;
+      let el = h.parentElement;
+      for (let i = 0; i < 8 && el; i++) {
+        if (el.matches(selectors.aio.root) || el.querySelector(selectors.aio.controller) || el.querySelector(selectors.aio.contentSubtree)) {
+          return el;
+        }
+        el = el.parentElement;
+      }
+      return h.parentElement;
+    }
+    return null;
+  }
+  function cleanText(target) {
+    if (!target) return null;
+    const clone = target.cloneNode(true);
+    clone.querySelectorAll([
+      "script",
+      "style",
+      "noscript",
+      "img",
+      "picture",
+      "video",
+      selectors.aio.header,
+      selectors.aio.showMoreButton,
+      selectors.aio.sourcesPanel,
+      selectors.aio.disclaimer,
+      '[data-subtree="dfa"]',
+      "[data-src-id]",
+      '[role="dialog"]',
+      ".HWMcu",
+      ".bTFeG",
+      ".CyMdWb",
+      ".MFrAxb",
+      ".F0OfWd.hfWAgb",
+      ".x2qcTc.fZavHb",
+      ".SvjEff",
+      ".sR2MY",
+      ".lKuDef",
+      ".GSPQcc",
+      "a[href]",
+      "button",
+      '[role="button"]'
+    ].join(",")).forEach((el) => el.remove());
+    const holder = document.createElement("div");
+    holder.style.position = "fixed";
+    holder.style.left = "-10000px";
+    holder.style.top = "0";
+    holder.style.width = `${Math.max(320, Math.round(target.getBoundingClientRect?.().width || 960))}px`;
+    holder.style.opacity = "0";
+    holder.style.pointerEvents = "none";
+    holder.append(clone);
+    document.body.append(holder);
+    const rendered = clone.innerText || clone.textContent || "";
+    holder.remove();
+    const lines = rendered.replace(/\r/g, "").replace(/[ \t]+\n/g, "\n").replace(/\n[ \t]+/g, "\n").replace(/\n{3,}/g, "\n\n").replace(/[ \t]{2,}/g, " ").trim().split("\n").map((line) => line.replace(/\u00a0/g, " ").trim()).filter(Boolean);
+    const filteredLines = [];
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const next = lines[i + 1] ?? "";
+      if (line === "AI Overview") continue;
+      if (line === "Show more") continue;
+      if (/^AI can make mistakes/i.test(line)) continue;
+      if (/^Thank you\b/i.test(line)) continue;
+      if (/^Your feedback helps Google improve/i.test(line)) continue;
+      if (/^\+?\d+$/.test(line)) continue;
+      if (/^\+\d+$/.test(next) && line.length <= 80) {
+        i++;
+        continue;
+      }
+      filteredLines.push(line);
+    }
+    const raw = filteredLines.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+    if (!raw || /not available|try again|can't generate/i.test(raw)) return null;
+    return raw;
+  }
+  function normalizeHref(rawHref) {
+    if (!rawHref || rawHref.startsWith("javascript:")) return null;
+    let href = rawHref;
+    try {
+      const absolute = new URL(rawHref, window.location.href);
+      const q = absolute.searchParams.get("q") ?? absolute.searchParams.get("url");
+      if (/(\.|^)google\./i.test(absolute.hostname) && q?.startsWith("http")) {
+        href = q;
+      } else {
+        href = absolute.href;
+      }
+    } catch {
+      return null;
+    }
+    if (!/^https?:\/\//i.test(href)) return null;
+    try {
+      const url = new URL(href);
+      const isGoogleInternal = /(\.|^)google\./i.test(url.hostname);
+      if (isGoogleInternal) return null;
+      return url.href;
+    } catch {
+      return null;
+    }
+  }
+  function extractCitations(root) {
+    if (!root) return [];
+    const seen = /* @__PURE__ */ new Set();
+    const citations = [];
+    for (const a of Array.from(root.querySelectorAll("a[href]"))) {
+      const href = normalizeHref(a.getAttribute("href") ?? "");
+      if (!href || seen.has(href)) continue;
+      seen.add(href);
+      let fallbackHost = "";
+      try {
+        fallbackHost = new URL(href).hostname.replace(/^www\./, "");
+      } catch {
+      }
+      citations.push({
+        text: textOf(a) || fallbackHost || href,
+        href
+      });
+    }
+    return citations;
+  }
+  async function maybeExpand(root) {
+    const button = root.querySelector(selectors.aio.showMoreButton);
+    if (!button || button.getAttribute("aria-expanded") !== "false") return false;
+    button.click();
+    const waitMs = selectors.expandWaitMs ?? 1500;
+    if (waitMs > 0) await new Promise((resolve) => setTimeout(resolve, waitMs));
+    return true;
+  }
+  const aioRoot = findAIORoot();
+  let aioText = null;
+  let aioCitations = [];
+  let aioExpanded = false;
+  let aioFullyExpanded = false;
+  let aioSections = [];
+  if (aioRoot) {
+    aioExpanded = await maybeExpand(aioRoot);
+    const controller = aioRoot.querySelector(selectors.aio.controller);
+    const contentSubtree = aioRoot.querySelector(selectors.aio.contentSubtree);
+    const showMore = aioRoot.querySelector(selectors.aio.showMoreButton);
+    aioFullyExpanded = controller?.getAttribute("data-trnct") === "false" || showMore?.getAttribute("aria-expanded") === "true" || !showMore;
+    aioText = cleanText(contentSubtree ?? controller ?? aioRoot);
+    aioSections = (aioText ?? "").split("\n").map((line) => line.trim()).filter((line) => /^\d+\.\s+.+/.test(line));
+    aioCitations = extractCitations(aioRoot);
+  }
+  const aimRoot = document.querySelector(selectors.aim.root);
+  const aimDetected = surface === "aim" && !!aimRoot;
+  const aimContainer = aimRoot?.closest(selectors.aim.wrapper) ?? aimRoot;
+  const aimText = cleanText(aimContainer);
+  const aimCitations = aimDetected ? extractCitations(aimContainer) : [];
+  return {
+    surface,
+    aiOverview: {
+      detected: !!aioRoot && aioText !== null,
+      text: aioText,
+      citations: aioCitations,
+      expanded: aioExpanded,
+      fullyExpanded: aioFullyExpanded,
+      sections: aioSections
+    },
+    aiMode: {
+      detected: aimDetected && aimText !== null,
+      text: aimText,
+      citations: aimCitations
+    }
+  };
+}
+
+// src/extractor/PAAExtractor.ts
+var DESKTOP_USER_AGENT2 = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36";
+var MOBILE_USER_AGENT2 = "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.5 Mobile/15E148 Safari/604.1";
+var PAAExtractor = class {
+  constructor(driver, reporter) {
+    this.driver = driver;
+    this.reporter = reporter;
+  }
+  driver;
+  reporter;
+  normalizeQuestion(q) {
+    return q.toLowerCase().replace(/[^\w\s]/g, "").replace(/\s+/g, " ").trim();
+  }
+  throwIfAborted(signal) {
+    if (!signal?.aborted) return;
+    if (signal.reason instanceof DOMException && signal.reason.name === "TimeoutError") throw signal.reason;
+    throw new RequestAbortedError();
+  }
+  async throwIfCaptcha(page, context) {
+    const captchaCount = await page.locator(PAASelectors.captchaMarker).count().catch(() => 0);
+    if (captchaCount > 0) {
+      throw new CaptchaError(`${context} returned a CAPTCHA \u2014 retrying with a fresh session.`);
+    }
+  }
+  async extractVisibleItems(page) {
+    const sels = PAASelectors;
+    const raw = await page.evaluate((selectors) => {
+      function cleanText(el) {
+        if (!el) return "";
+        const parts = [];
+        for (const n of el.childNodes) {
+          if (n.nodeType === Node.TEXT_NODE) {
+            const text = n.textContent?.trim();
+            if (text) parts.push(text);
+          } else if (n.tagName === "STYLE" || n.tagName === "SCRIPT") {
+            continue;
+          } else {
+            const text = cleanText(n);
+            if (text) parts.push(text);
+          }
+        }
+        return parts.join(" ").replace(/\s+/g, " ").trim();
+      }
+      return Array.from(document.querySelectorAll(selectors.item)).map((pair) => ({
+        question: pair.getAttribute(selectors.itemDataQ) || pair.getAttribute(selectors.itemDataInitQ) || "",
+        answer: cleanText(pair.querySelector(selectors.answerContainer)) || void 0,
+        sourceTitle: pair.querySelector(selectors.sourceTitle)?.innerText?.trim() || void 0,
+        sourceSite: pair.querySelector(selectors.sourceSite)?.innerText?.trim() || void 0,
+        sourceCite: pair.querySelector(selectors.sourceCite)?.innerText?.trim() || void 0
+      }));
+    }, sels);
+    return raw.flatMap((item) => {
+      const cleaned = {
+        ...item,
+        answer: cleanPAAAnswerText(item.answer, item.question, item.sourceTitle)
+      };
+      const result = RawPAAItemSchema.safeParse(cleaned);
+      if (!result.success) {
+        console.warn("[PAAExtractor] item parse failed:", item.question, result.error.issues[0]?.message);
+        return [];
+      }
+      return [result.data];
+    });
+  }
+  async clickItem(page, questionText) {
+    try {
+      const pairLocator = page.locator(
+        `${PAASelectors.item}[data-q="${questionText}"], ${PAASelectors.item}[data-initq="${questionText}"]`
+      ).first();
+      await pairLocator.click();
+    } catch {
+    }
+  }
+  toFlatRow(item, depth, parentQuestion, seed) {
+    return {
+      seed_query: seed,
+      question: item.question,
+      answer: item.answer ?? "",
+      source_title: item.sourceTitle ?? "",
+      source_site: item.sourceSite ?? "",
+      source_cite: item.sourceCite ?? "",
+      depth,
+      parent_question: parentQuestion ?? "",
+      extracted_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  async runBFS(page, options, signal) {
+    const seenKeys = /* @__PURE__ */ new Set();
+    const seenQs = /* @__PURE__ */ new Set();
+    const orderedQs = [];
+    const results = [];
+    const readAllQs = () => page.evaluate(
+      ({ sel, dataQ, dataInitQ, questionEl }) => Array.from(document.querySelectorAll(sel)).map(
+        (el) => el.getAttribute(dataQ) || el.getAttribute(dataInitQ) || el.querySelector(questionEl)?.innerText?.trim() || ""
+      ).filter(Boolean),
+      { sel: PAASelectors.item, dataQ: PAASelectors.itemDataQ, dataInitQ: PAASelectors.itemDataInitQ, questionEl: PAASelectors.itemQuestionEl }
+    );
+    let round = 0;
+    while (seenQs.size < options.maxQuestions) {
+      this.throwIfAborted(signal);
+      await this.throwIfCaptcha(page, "Google PAA expansion");
+      const beforeQs = await readAllQs();
+      if (beforeQs.length >= options.maxQuestions) break;
+      const unexpandedSel = `${PAASelectors.item}:not(.${PAASelectors.expandedClass}) ${PAASelectors.clickTarget}`;
+      const unexpandedCount = await page.locator(unexpandedSel).count();
+      if (unexpandedCount === 0) break;
+      this.reporter.onDepth(++round);
+      for (let ci = 0; ci < unexpandedCount; ci++) {
+        this.throwIfAborted(signal);
+        try {
+          const btn = page.locator(unexpandedSel).first();
+          await btn.scrollIntoViewIfNeeded();
+          await btn.hover({ force: true });
+          await page.waitForTimeout(100);
+          await btn.click({ force: true });
+          await page.waitForTimeout(500);
+        } catch {
+        }
+      }
+      await page.waitForFunction(
+        ({ sel, min }) => document.querySelectorAll(sel).length > min,
+        { sel: PAASelectors.item, min: beforeQs.length },
+        { timeout: 5e3 }
+      ).catch(() => {
+      });
+      await this.throwIfCaptcha(page, "Google PAA expansion");
+      const afterQs = await readAllQs();
+      if (afterQs.length === beforeQs.length) break;
+      for (const q of afterQs) {
+        if (!seenQs.has(q)) {
+          seenQs.add(q);
+          orderedQs.push(q);
+        }
+      }
+    }
+    const itemMap = new Map((await this.extractVisibleItems(page)).map((i) => [i.question, i]));
+    for (const q of orderedQs) {
+      if (results.length >= options.maxQuestions) break;
+      const key = this.normalizeQuestion(q);
+      if (seenKeys.has(key)) continue;
+      seenKeys.add(key);
+      const item = itemMap.get(q);
+      if (item) {
+        results.push(this.toFlatRow(item, 1, null, options.query));
+        this.reporter.onQuestion({ question: item.question, answer: item.answer ?? null, sourceTitle: item.sourceTitle ?? null, sourceSite: item.sourceSite ?? null, sourceCite: item.sourceCite ?? null, depth: 1, parentQuestion: null, children: [] });
+      } else {
+        results.push(this.toFlatRow({ question: q, answer: void 0, sourceTitle: void 0, sourceSite: void 0, sourceCite: void 0 }, 1, null, options.query));
+      }
+    }
+    return results;
+  }
+  async extractVideos(page) {
+    const vsels = VideoSelectors;
+    return page.evaluate((sels) => {
+      const results = [];
+      const containers = Array.from(document.querySelectorAll(sels.container));
+      for (const container of containers) {
+        const headingEl = container.querySelector(sels.sectionHeading);
+        const headingText = headingEl?.textContent?.trim() ?? "";
+        const type = headingText.toLowerCase().includes("short") ? "short_video" : "video";
+        const items = Array.from(container.querySelectorAll(sels.item));
+        for (const a of items) {
+          const href = a.href;
+          if (!href || !href.includes("youtube") && !href.includes("youtu.be")) continue;
+          const raw = a.textContent?.trim() ?? "";
+          const ytIdx = raw.indexOf("YouTube");
+          if (ytIdx === -1) continue;
+          const title = raw.slice(0, ytIdx).trim();
+          const remainder = raw.slice(ytIdx + 7).replace(/^[·\s·]+/, "");
+          const channelMatch = remainder.match(/^([^·\n]+)/);
+          const channel = channelMatch ? channelMatch[1].trim() : "";
+          if (title) results.push({ type, title, channel, platform: "YouTube", duration: "", url: href });
+        }
+      }
+      return results;
+    }, vsels);
+  }
+  async extractForums(page) {
+    const fsels = ForumSelectors;
+    return page.evaluate((sels) => {
+      const results = [];
+      const sections = Array.from(document.querySelectorAll(sels.section));
+      const forumSection = sections.find((s) => s.textContent?.includes("Discussions"));
+      if (!forumSection) return results;
+      const items = Array.from(forumSection.querySelectorAll(sels.item));
+      for (const a of items) {
+        const href = a.href;
+        if (!href) continue;
+        const titleEl = a.querySelector(sels.title);
+        const sourceEl = a.querySelector(sels.source);
+        const title = titleEl?.textContent?.trim() ?? "";
+        const source = sourceEl?.textContent?.trim() ?? "";
+        if (title) results.push({ title, source, url: href });
+      }
+      return results;
+    }, fsels);
+  }
+  async extractShortVideos(page, shortUrl) {
+    try {
+      await page.goto(shortUrl, { waitUntil: "domcontentloaded" });
+      await page.waitForTimeout(1500);
+    } catch {
+      return [];
+    }
+    await this.throwIfCaptcha(page, "Google short video search");
+    const svSels = {
+      item: ShortVideoSelectors.item,
+      platforms: [...ShortVideoSelectors.platforms]
+    };
+    const raw = await page.evaluate((sels) => {
+      const seen = /* @__PURE__ */ new Set();
+      const results = [];
+      const items = Array.from(document.querySelectorAll(sels.item));
+      const videoHosts = ["youtube.com", "youtu.be", "tiktok.com", "instagram.com", "facebook.com", "fb.watch"];
+      const byHref = /* @__PURE__ */ new Map();
+      for (const a of items) {
+        const href = a.href;
+        if (!href) continue;
+        if (!videoHosts.some((h) => href.includes(h))) continue;
+        const text = a.textContent?.trim() ?? "";
+        if (!byHref.has(href)) byHref.set(href, []);
+        byHref.get(href).push(text);
+      }
+      for (const [href, texts] of byHref.entries()) {
+        if (seen.has(href)) continue;
+        seen.add(href);
+        const duration = texts.find((t) => /^\d+:\d+$/.test(t)) ?? "";
+        const titleText = texts.find((t) => !/^\d+:\d+$/.test(t) && t.length > 5) ?? "";
+        if (!titleText) continue;
+        let title = titleText;
+        let platform = "";
+        let channel = "";
+        for (const p of sels.platforms) {
+          let lastIdx = -1;
+          let search = 0;
+          while (true) {
+            const found = titleText.indexOf(p, search);
+            if (found === -1) break;
+            lastIdx = found;
+            search = found + 1;
+          }
+          if (lastIdx === -1) continue;
+          const after = titleText.slice(lastIdx + p.length);
+          const isSourceTag = /^[\s·]/.test(after) || after.trim() === "";
+          if (!isSourceTag) continue;
+          title = titleText.slice(0, lastIdx).trim();
+          platform = p;
+          const stripped = after.replace(/^[\s·]+/, "");
+          const dotIdx = stripped.indexOf("\xB7");
+          channel = (dotIdx === -1 ? stripped : stripped.slice(0, dotIdx)).trim();
+          break;
+        }
+        if (title) results.push({ title, channel, platform, duration, url: href });
+      }
+      return results;
+    }, svSels);
+    return raw.map((r) => ({ type: "short_video", ...r }));
+  }
+  async extractWhatPeopleSaying(page) {
+    const sels = WhatPeopleSayingSelectors;
+    return page.evaluate((s) => {
+      const section = Array.from(document.querySelectorAll(s.sectionTag)).find((el) => el.textContent?.includes(s.sectionHeadingText)) ?? document.querySelector(".yG4QQe.TBC9ub.NbhJ1c");
+      if (!section) return [];
+      return Array.from(section.querySelectorAll(s.card)).map((card) => {
+        const link = card.querySelector(s.cardLink);
+        const url = link?.href ?? "";
+        const titleH1 = card.querySelector(s.titleH1)?.textContent?.trim();
+        const titleDiv = card.querySelector(s.titleDiv)?.textContent?.trim();
+        const title = titleH1 ?? titleDiv ?? "";
+        const sourceText = card.querySelector(s.source)?.textContent?.trim() ?? "";
+        const platformEl = card.querySelector(s.platformBadge);
+        const platformText = platformEl?.textContent?.trim() ?? "";
+        const ytChannel = card.querySelector(s.ytChannel)?.textContent?.trim() ?? "";
+        const ytDate = card.querySelector(s.ytDate)?.textContent?.trim() ?? "";
+        const authorNote = card.querySelector(s.authorNote)?.textContent?.trim() ?? null;
+        const commentLabelEl = card.querySelector(s.popularCommentLabel);
+        let popularComment = null;
+        if (commentLabelEl) {
+          let next = commentLabelEl.nextSibling;
+          while (next) {
+            const t = next.textContent?.trim();
+            if (t) {
+              popularComment = t;
+              break;
+            }
+            next = next.nextSibling;
+          }
+        }
+        const allSpans = Array.from(card.querySelectorAll("span"));
+        const duration = allSpans.find((s2) => /^\d+:\d+$/.test(s2.textContent?.trim() ?? ""))?.textContent?.trim() ?? null;
+        const engagementParts = allSpans.map((s2) => s2.textContent?.trim() ?? "").filter(
+          (t) => /\d/.test(t) && (t.includes("comment") || t.includes("reaction") || t.includes("view") || t.includes("like") || t.includes("share"))
+        );
+        const engagement = engagementParts[0] ?? "";
+        const dateCandidates = allSpans.map((s2) => s2.textContent?.trim() ?? "").filter((t) => /\d+ (day|week|month|year|hour)s? ago|Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec/.test(t));
+        const date = ytDate || (dateCandidates[0] ?? "");
+        const platform = platformText || (ytChannel ? "YouTube" : "");
+        const source = ytChannel || sourceText;
+        let type = "unknown";
+        const pl = platform.toLowerCase();
+        const src = source.toLowerCase();
+        const srcRaw = sourceText.toLowerCase();
+        if (pl.includes("reddit") || src.startsWith("r/")) type = "reddit";
+        else if (pl.includes("facebook") || srcRaw.includes("facebook")) type = "facebook";
+        else if (pl.includes("instagram") || srcRaw.includes("instagram")) type = "instagram";
+        else if (pl.includes("tiktok") || srcRaw.includes("tiktok")) type = "tiktok";
+        else if (pl.includes("youtube") || !!ytChannel) type = "youtube";
+        else type = "news";
+        return { type, title, url, source, platform, popularComment, engagement, date, duration, authorNote };
+      });
+    }, sels);
+  }
+  async extractOrganicResults(page) {
+    const sels = OrganicSelectors;
+    return page.evaluate((s) => {
+      const out = [];
+      let pos = 0;
+      document.querySelectorAll(s.result).forEach((card) => {
+        const titleEl = card.querySelector(s.title);
+        if (!titleEl) return;
+        const title = titleEl.textContent?.trim() ?? "";
+        const linkEl = titleEl.closest("a");
+        const url = linkEl?.href ?? "";
+        if (!title || !url) return;
+        pos++;
+        const cite = card.querySelector(s.cite)?.textContent?.trim() ?? null;
+        const snippet = card.querySelector(s.snippet)?.textContent?.trim() ?? null;
+        const isRedditStyle = !!card.querySelector(s.redditCite);
+        const ratingEl = card.querySelector(s.ratingWrap);
+        const inlineRating = ratingEl ? { value: ratingEl.querySelector(s.ratingValue)?.textContent?.trim() ?? "", count: ratingEl.querySelector(s.reviewCount)?.textContent?.trim() ?? "" } : null;
+        let domain = "";
+        try {
+          domain = new URL(url).hostname.replace(/^www\./, "");
+        } catch {
+          domain = card.querySelector(s.siteName)?.textContent?.trim() ?? "";
+        }
+        out.push({ position: pos, title, url, domain, cite, snippet, isRedditStyle, inlineRating });
+      });
+      return out;
+    }, sels);
+  }
+  async extractLocalPack(page) {
+    const sels = LocalPackSelectors;
+    return page.evaluate((s) => {
+      const out = [];
+      let container = null;
+      document.querySelectorAll('[role="heading"]').forEach((h) => {
+        if (!container && h.textContent?.includes(s.headingText)) container = h.closest("[data-hveid]");
+      });
+      if (!container) return out;
+      container.querySelectorAll(s.card).forEach((card, i) => {
+        const name = card.querySelector(s.name)?.textContent?.trim() ?? "";
+        if (!name) return;
+        const rating = card.querySelector(s.ratingValue)?.textContent?.trim() ?? null;
+        const reviewRaw = card.querySelector(s.reviewCount)?.textContent?.trim() ?? null;
+        const reviewCount = reviewRaw ? reviewRaw.replace(/[()]/g, "").trim() : null;
+        let cid = card.querySelector("a[data-cid]")?.getAttribute("data-cid") ?? null;
+        if (!cid) {
+          for (const link of Array.from(card.querySelectorAll("a[href]"))) {
+            const m1 = link.href.match(/[?&]cid=(\d+)/);
+            if (m1) {
+              cid = m1[1];
+              break;
+            }
+            const m2 = link.href.match(/!1s0x[0-9a-f]+:0x([0-9a-f]+)/i);
+            if (m2) {
+              try {
+                cid = BigInt("0x" + m2[1]).toString();
+              } catch {
+              }
+              if (cid) break;
+            }
+          }
+        }
+        const metadata = [];
+        card.querySelectorAll("div, span").forEach((el) => {
+          const text = Array.from(el.childNodes).filter((n) => n.nodeType === 3).map((n) => n.textContent?.trim() ?? "").filter((t) => t.length > 1 && t.length < 120).join(" ");
+          if (text && !metadata.includes(text)) metadata.push(text);
+        });
+        const links = Array.from(card.querySelectorAll("a[href]"));
+        const directionsUrl = links.find((a) => a.href.includes("google.com/maps"))?.href ?? null;
+        const websiteUrl = links.find((a) => !a.href.includes("google.com") && a.href.startsWith("http"))?.href ?? null;
+        out.push({ position: i + 1, name, cid, rating, reviewCount, metadata, websiteUrl, directionsUrl });
+      });
+      return out;
+    }, sels);
+  }
+  async extractEntityIds(page) {
+    return page.evaluate(() => {
+      const kgIds = /* @__PURE__ */ new Set();
+      const cids = /* @__PURE__ */ new Set();
+      const gcids = /* @__PURE__ */ new Set();
+      const recordMap = /* @__PURE__ */ new Map();
+      function nameFromWrapper(el) {
+        const sel = [".OSrXXb", ".dbg0pd", ".tzt0oe", '[role="heading"]', "h3"];
+        for (const s of sel) {
+          const found = el.querySelector(s);
+          if (found?.textContent?.trim()) return found.textContent.trim();
+        }
+        return "";
+      }
+      document.querySelectorAll('[id^="pv-/g/"]').forEach((wrapper) => {
+        const raw = wrapper.getAttribute("id");
+        if (!raw) return;
+        const kgId = raw.replace("pv-", "");
+        kgIds.add(kgId);
+        const name = nameFromWrapper(wrapper);
+        const cidEl = wrapper.querySelector("a[data-cid]");
+        const cid = cidEl?.getAttribute("data-cid") ?? null;
+        if (cid) cids.add(cid);
+        if (name) recordMap.set(kgId, { name, kgId, cid, gcid: null });
+      });
+      document.querySelectorAll("[data-mid]").forEach((el) => {
+        const mid = el.getAttribute("data-mid");
+        if (!mid?.startsWith("/g/")) return;
+        kgIds.add(mid);
+        if (!recordMap.has(mid)) {
+          const name = nameFromWrapper(el);
+          if (name) recordMap.set(mid, { name, kgId: mid, cid: null, gcid: null });
+        }
+      });
+      document.querySelectorAll(".w7Dbne").forEach((card) => {
+        const cidEl = card.querySelector("a[data-cid]");
+        const cid = cidEl?.getAttribute("data-cid") ?? null;
+        if (!cid) return;
+        cids.add(cid);
+        const name = card.querySelector(".OSrXXb")?.textContent?.trim() ?? "";
+        if (!name) return;
+        const kgIdEl = card.querySelector('[id^="pv-/g/"]');
+        const kgId = kgIdEl ? kgIdEl.getAttribute("id").replace("pv-", "") : null;
+        const key = kgId ?? `cid:${cid}`;
+        if (recordMap.has(key)) {
+          const existing = recordMap.get(key);
+          if (!existing.cid) recordMap.set(key, { ...existing, cid });
+        } else {
+          recordMap.set(key, { name, kgId, cid, gcid: null });
+        }
+      });
+      document.querySelectorAll("a[data-cid]").forEach((el) => {
+        const cid = el.getAttribute("data-cid");
+        if (!cid) return;
+        cids.add(cid);
+        const alreadyNamed = [...recordMap.values()].some((r) => r.cid === cid);
+        if (!alreadyNamed) {
+          let node = el.parentElement;
+          let name = "";
+          for (let i = 0; i < 8 && node; i++) {
+            const h = node.querySelector('.OSrXXb, .dbg0pd, [role="heading"], h3');
+            if (h?.textContent?.trim()) {
+              name = h.textContent.trim();
+              break;
+            }
+            node = node.parentElement;
+          }
+          if (name) recordMap.set(`cid:${cid}`, { name, kgId: null, cid, gcid: null });
+        }
+      });
+      const scriptContent = Array.from(document.querySelectorAll("script:not([src])")).map((s) => s.textContent ?? "").filter((t) => t.length > 1e4).join("\n");
+      for (const m of scriptContent.matchAll(/\/g\/[a-zA-Z0-9_-]{5,20}/g)) kgIds.add(m[0]);
+      for (const m of scriptContent.matchAll(/gcid:[a-zA-Z0-9_]+/g)) gcids.add(m[0]);
+      for (const m of scriptContent.matchAll(/0x[0-9a-f]+:0x([0-9a-f]+)/gi)) {
+        try {
+          cids.add(BigInt("0x" + m[1]).toString());
+        } catch {
+        }
+      }
+      return { entities: [...recordMap.values()], kgIds: [...kgIds], cids: [...cids], gcids: [...gcids] };
+    });
+  }
+  mergeLocalPackIntoEntities(entityIds, localPack) {
+    const cidSet = new Set(entityIds.cids);
+    const records = entityIds.entities.map((r) => ({ ...r }));
+    for (const biz of localPack) {
+      if (!biz.cid) continue;
+      cidSet.add(biz.cid);
+      const nameNorm = biz.name.toLowerCase().trim();
+      const byName = records.find((r) => r.name.toLowerCase().trim() === nameNorm);
+      if (byName) {
+        if (!byName.cid) byName.cid = biz.cid;
+      } else if (!records.find((r) => r.cid === biz.cid)) {
+        records.push({ name: biz.name, kgId: null, cid: biz.cid, gcid: null });
+      }
+    }
+    return { ...entityIds, entities: records, cids: [...cidSet] };
+  }
+  async extractAISurfaces(page) {
+    return page.evaluate(extractAISurfacesFromDocument, {
+      aio: AIOverviewSelectors,
+      aim: AIModeSelectors,
+      expandWaitMs: 1500
+    });
+  }
+  buildTree(flat, _seed) {
+    const roots = [];
+    const nodeMap = /* @__PURE__ */ new Map();
+    for (const row of flat) {
+      const node = {
+        question: row.question,
+        answer: row.answer || null,
+        sourceTitle: row.source_title || null,
+        sourceSite: row.source_site || null,
+        sourceCite: row.source_cite || null,
+        depth: row.depth,
+        parentQuestion: row.parent_question || null,
+        children: []
+      };
+      nodeMap.set(row.question, node);
+    }
+    for (const node of nodeMap.values()) {
+      if (node.parentQuestion && nodeMap.has(node.parentQuestion)) {
+        nodeMap.get(node.parentQuestion).children.push(node);
+      } else {
+        roots.push(node);
+      }
+    }
+    return roots;
+  }
+  getBrowserDebugSnapshot() {
+    return this.driver.getDebugSnapshot();
+  }
+  buildHarvestDebugSnapshot(options, canonicalLocation, uule, locationEvidence) {
+    if (!options.debug) return void 0;
+    return {
+      enabled: true,
+      request: {
+        query: options.query,
+        locationInput: options.location ?? null,
+        canonicalLocation,
+        uule,
+        gl: options.gl,
+        hl: options.hl,
+        device: options.device,
+        proxyMode: options.proxyMode,
+        proxyZip: options.proxyZip ?? null,
+        serpOnly: options.serpOnly,
+        pages: options.pages ?? 1
+      },
+      browser: this.getBrowserDebugSnapshot(),
+      ...locationEvidence ? { locationEvidence } : {}
+    };
+  }
+  async extract(options, signal) {
+    const startMs = Date.now();
+    const isMobile = options.device === "mobile";
+    const config = {
+      headless: options.headless,
+      profileDir: options.profileDir,
+      proxy: options.proxy,
+      kernelApiKey: options.kernelApiKey,
+      kernelProxyId: options.kernelProxyId,
+      kernelProxyResolution: options.kernelProxyResolution,
+      proxyMode: options.proxyMode,
+      viewport: isMobile ? { width: 390, height: 844 } : { width: 1280, height: 800 },
+      locale: `${options.hl}-${options.gl.toUpperCase()}`,
+      userAgent: isMobile ? MOBILE_USER_AGENT2 : DESKTOP_USER_AGENT2,
+      deviceScaleFactor: isMobile ? 3 : 1,
+      isMobile,
+      hasTouch: isMobile,
+      debug: options.debug
+    };
+    let errorCount = 0;
+    const diagnosticWarnings = [];
+    try {
+      this.throwIfAborted(signal);
+      await this.driver.launch(config);
+      this.throwIfAborted(signal);
+      const canonicalLocation = options.location ? normalizeLocation(options.location) : null;
+      const uule = canonicalLocation ? encodeUule(canonicalLocation) : null;
+      const { hasPaa } = await this.driver.navigateToSERP(
+        options.query,
+        uule,
+        options.gl,
+        options.hl,
+        {
+          ...options.serpOnly ? { num: 100 } : {},
+          debug: options.debug
+        }
+      );
+      this.throwIfAborted(signal);
+      const page = this.driver.getPage();
+      await this.throwIfCaptcha(page, "Google SERP");
+      if (options.serpOnly) {
+        const [organicResults2, localPack2, rawEntityIds2] = await Promise.all([
+          this.extractOrganicResults(page),
+          this.extractLocalPack(page),
+          this.extractEntityIds(page)
+        ]);
+        const entityIds2 = this.mergeLocalPackIntoEntities(rawEntityIds2, localPack2);
+        const aiSurfaces2 = await this.extractAISurfaces(page);
+        let locationEvidence2 = options.debug ? inferSerpLocationEvidence(canonicalLocation, organicResults2, localPack2) : void 0;
+        let allOrganic2 = organicResults2;
+        if ((options.pages ?? 1) >= 2) {
+          const p2params = new URLSearchParams({ q: options.query, gl: options.gl, hl: options.hl, pws: "0", start: "10" });
+          if (uule) p2params.set("uule", uule);
+          await this.driver.navigateTo("https://www.google.com/search?" + p2params.toString());
+          await this.throwIfCaptcha(page, "Google SERP page 2");
+          const p2organic = await this.extractOrganicResults(page);
+          allOrganic2 = [...organicResults2, ...p2organic.map((r) => ({ ...r, position: r.position + 10 }))];
+          if (options.debug) {
+            locationEvidence2 = inferSerpLocationEvidence(canonicalLocation, allOrganic2, localPack2);
+          }
+        }
+        const stats2 = {
+          seed: options.query,
+          totalQuestions: 0,
+          maxDepthReached: 0,
+          durationMs: Date.now() - startMs,
+          errorCount
+        };
+        this.reporter.onComplete(stats2);
+        return {
+          seed: options.query,
+          location: options.location ?? null,
+          extractedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          diagnostics: {
+            completionStatus: "serp_only",
+            problem: null,
+            ...options.debug ? { debug: this.buildHarvestDebugSnapshot(options, canonicalLocation, uule, locationEvidence2) } : {}
+          },
+          totalQuestions: 0,
+          surface: aiSurfaces2.surface,
+          aiOverview: aiSurfaces2.aiOverview,
+          aiMode: aiSurfaces2.aiMode,
+          whatPeopleSaying: [],
+          tree: [],
+          flat: [],
+          videos: [],
+          forums: [],
+          organicResults: allOrganic2,
+          localPack: localPack2,
+          entityIds: entityIds2,
+          stats: stats2
+        };
+      }
+      const [videos, forums, whatPeopleSaying, rawEntityIds, organicResults, localPack] = await Promise.all([
+        this.extractVideos(page),
+        this.extractForums(page),
+        this.extractWhatPeopleSaying(page),
+        this.extractEntityIds(page),
+        this.extractOrganicResults(page),
+        this.extractLocalPack(page)
+      ]);
+      const entityIds = this.mergeLocalPackIntoEntities(rawEntityIds, localPack);
+      const initialLocationEvidence = options.debug ? inferSerpLocationEvidence(canonicalLocation, organicResults, localPack) : void 0;
+      this.reporter.onVideos(videos);
+      this.reporter.onForums(forums);
+      if (!hasPaa) {
+        let noPaaOrganic = organicResults;
+        let locationEvidence2 = initialLocationEvidence;
+        if ((options.pages ?? 1) >= 2) {
+          const p2params = new URLSearchParams({ q: options.query, gl: options.gl, hl: options.hl, pws: "0", start: "10" });
+          if (uule) p2params.set("uule", uule);
+          await this.driver.navigateTo("https://www.google.com/search?" + p2params.toString());
+          await this.throwIfCaptcha(page, "Google SERP page 2");
+          const p2organic = await this.extractOrganicResults(page);
+          noPaaOrganic = [...organicResults, ...p2organic.map((r) => ({ ...r, position: r.position + 10 }))];
+          if (options.debug) {
+            locationEvidence2 = inferSerpLocationEvidence(canonicalLocation, noPaaOrganic, localPack);
+          }
+        }
+        const aiSurfaces2 = await this.extractAISurfaces(page);
+        const stats2 = {
+          seed: options.query,
+          totalQuestions: 0,
+          maxDepthReached: 0,
+          durationMs: Date.now() - startMs,
+          errorCount
+        };
+        this.reporter.onComplete(stats2);
+        return {
+          seed: options.query,
+          location: options.location ?? null,
+          extractedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          diagnostics: {
+            completionStatus: "no_paa",
+            problem: null,
+            ...options.debug ? { debug: this.buildHarvestDebugSnapshot(options, canonicalLocation, uule, locationEvidence2) } : {}
+          },
+          totalQuestions: 0,
+          surface: aiSurfaces2.surface,
+          aiOverview: aiSurfaces2.aiOverview,
+          aiMode: aiSurfaces2.aiMode,
+          whatPeopleSaying,
+          tree: [],
+          flat: [],
+          videos,
+          forums,
+          organicResults: noPaaOrganic,
+          localPack,
+          entityIds,
+          stats: stats2
+        };
+      }
+      const flat = await this.runBFS(page, options, signal);
+      this.throwIfAborted(signal);
+      const aiSurfaces = await this.extractAISurfaces(page);
+      const shortVidsParams = new URLSearchParams({ q: options.query, gl: options.gl, hl: options.hl, pws: "0", udm: ShortVideoSelectors.udm });
+      if (uule) shortVidsParams.set("uule", uule);
+      let shortVideos = [];
+      try {
+        shortVideos = await this.extractShortVideos(page, "https://www.google.com/search?" + shortVidsParams.toString());
+      } catch (err) {
+        if (!(err instanceof CaptchaError)) throw err;
+        errorCount++;
+        diagnosticWarnings.push({
+          code: "short_videos_captcha_skipped",
+          surface: "short_videos",
+          message: err.message,
+          retryable: true
+        });
+      }
+      this.reporter.onVideos(shortVideos);
+      let allOrganic = organicResults;
+      let locationEvidence = initialLocationEvidence;
+      if ((options.pages ?? 1) >= 2) {
+        const p2params = new URLSearchParams({ q: options.query, gl: options.gl, hl: options.hl, pws: "0", start: "10" });
+        if (uule) p2params.set("uule", uule);
+        await this.driver.navigateTo("https://www.google.com/search?" + p2params.toString());
+        await this.throwIfCaptcha(page, "Google SERP page 2");
+        const p2organic = await this.extractOrganicResults(page);
+        allOrganic = [...organicResults, ...p2organic.map((r) => ({ ...r, position: r.position + 10 }))];
+        if (options.debug) {
+          locationEvidence = inferSerpLocationEvidence(canonicalLocation, allOrganic, localPack);
+        }
+      }
+      const allVideos = [...videos, ...shortVideos];
+      const tree = this.buildTree(flat, options.query);
+      const stats = {
+        seed: options.query,
+        totalQuestions: flat.length,
+        maxDepthReached: flat.reduce((m, r) => Math.max(m, r.depth), 0),
+        durationMs: Date.now() - startMs,
+        errorCount
+      };
+      this.reporter.onComplete(stats);
+      return {
+        seed: options.query,
+        location: options.location ?? null,
+        extractedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        diagnostics: {
+          completionStatus: "paa_found",
+          problem: null,
+          ...diagnosticWarnings.length > 0 ? { warnings: diagnosticWarnings } : {},
+          ...options.debug ? { debug: this.buildHarvestDebugSnapshot(options, canonicalLocation, uule, locationEvidence) } : {}
+        },
+        totalQuestions: flat.length,
+        surface: aiSurfaces.surface,
+        aiOverview: aiSurfaces.aiOverview,
+        aiMode: aiSurfaces.aiMode,
+        whatPeopleSaying,
+        tree,
+        flat,
+        videos: allVideos,
+        forums,
+        organicResults: allOrganic,
+        localPack,
+        entityIds,
+        stats
+      };
+    } catch (err) {
+      errorCount++;
+      this.reporter.onError(err instanceof Error ? err : new Error(String(err)));
+      throw err;
+    }
+  }
+};
+
+// src/output/OutputSerializer.ts
+import { promises as fs } from "fs";
+import path from "path";
+import Papa from "papaparse";
+var OutputSerializer = class {
+  async writeJSON(result, outputDir) {
+    await fs.mkdir(outputDir, { recursive: true });
+    const slug = result.seed.toLowerCase().replace(/\W+/g, "-").slice(0, 40);
+    const filename = `${slug}-${Date.now()}.json`;
+    const fullPath = path.join(outputDir, filename);
+    await fs.writeFile(fullPath, JSON.stringify(result, null, 2), "utf8");
+    return fullPath;
+  }
+  async writeCSV(rows, outputDir) {
+    await fs.mkdir(outputDir, { recursive: true });
+    const seedRaw = rows[0]?.seed_query ?? "paa";
+    const slug = seedRaw.toLowerCase().replace(/\W+/g, "-").slice(0, 40);
+    const csv = Papa.unparse(rows, { header: true });
+    const filename = `${slug}-${Date.now()}.csv`;
+    const fullPath = path.join(outputDir, filename);
+    await fs.writeFile(fullPath, csv, "utf8");
+    return fullPath;
+  }
+  async writeVideoCSV(videos, seed, outputDir) {
+    await fs.mkdir(outputDir, { recursive: true });
+    const slug = seed.toLowerCase().replace(/\W+/g, "-").slice(0, 40);
+    const csv = Papa.unparse(videos, { header: true });
+    const filename = `${slug}-videos-${Date.now()}.csv`;
+    const fullPath = path.join(outputDir, filename);
+    await fs.writeFile(fullPath, csv, "utf8");
+    return fullPath;
+  }
+  async writeForumCSV(forums, seed, outputDir) {
+    await fs.mkdir(outputDir, { recursive: true });
+    const slug = seed.toLowerCase().replace(/\W+/g, "-").slice(0, 40);
+    const csv = Papa.unparse(forums, { header: true });
+    const filename = `${slug}-forums-${Date.now()}.csv`;
+    const fullPath = path.join(outputDir, filename);
+    await fs.writeFile(fullPath, csv, "utf8");
+    return fullPath;
+  }
+  async writeAIOverviewCSV(citations, text, seed, outputDir) {
+    await fs.mkdir(outputDir, { recursive: true });
+    const slug = seed.toLowerCase().replace(/\W+/g, "-").slice(0, 40);
+    const rows = citations.map((c, i) => ({
+      seed_query: seed,
+      response_text: i === 0 ? text ?? "" : "",
+      citation_text: c.text,
+      citation_href: c.href
+    }));
+    const csv = Papa.unparse(rows, { header: true });
+    const filename = `${slug}-ai-overview-${Date.now()}.csv`;
+    const fullPath = path.join(outputDir, filename);
+    await fs.writeFile(fullPath, csv, "utf8");
+    return fullPath;
+  }
+  async writeAIModeCSV(citations, text, seed, outputDir) {
+    await fs.mkdir(outputDir, { recursive: true });
+    const slug = seed.toLowerCase().replace(/\W+/g, "-").slice(0, 40);
+    const rows = citations.map((c, i) => ({
+      seed_query: seed,
+      response_text: i === 0 ? text ?? "" : "",
+      citation_text: c.text,
+      citation_href: c.href
+    }));
+    const csv = Papa.unparse(rows, { header: true });
+    const filename = `${slug}-ai-mode-${Date.now()}.csv`;
+    const fullPath = path.join(outputDir, filename);
+    await fs.writeFile(fullPath, csv, "utf8");
+    return fullPath;
+  }
+  async writeWhatPeopleSayingCSV(cards, seed, outputDir) {
+    await fs.mkdir(outputDir, { recursive: true });
+    const slug = seed.toLowerCase().replace(/\W+/g, "-").slice(0, 40);
+    const rows = cards.map((c) => ({ seed_query: seed, ...c }));
+    const csv = Papa.unparse(rows, { header: true });
+    const filename = `${slug}-what-people-saying-${Date.now()}.csv`;
+    const fullPath = path.join(outputDir, filename);
+    await fs.writeFile(fullPath, csv, "utf8");
+    return fullPath;
+  }
+};
+
+// src/output/ProgressReporter.ts
+var ProgressReporter = class {
+  onQuestion(node) {
+    process.stdout.write(JSON.stringify({ event: "question", depth: node.depth, question: node.question }) + "\n");
+  }
+  onDepth(depth) {
+    process.stdout.write(JSON.stringify({ event: "depth", depth }) + "\n");
+  }
+  onVideos(videos) {
+    for (const v of videos) {
+      process.stdout.write(JSON.stringify({ event: "video", type: v.type, platform: v.platform, duration: v.duration, title: v.title, channel: v.channel, url: v.url }) + "\n");
+    }
+  }
+  onForums(forums) {
+    for (const f of forums) {
+      process.stdout.write(JSON.stringify({ event: "forum", title: f.title, source: f.source, url: f.url }) + "\n");
+    }
+  }
+  onComplete(stats) {
+    process.stdout.write(JSON.stringify({ event: "complete", ...stats }) + "\n");
+  }
+  onError(err) {
+    process.stderr.write(JSON.stringify({ event: "error", type: err.constructor.name, message: err.message }) + "\n");
+  }
+};
+
+// src/kernel-proxy-resolver.ts
+import Kernel2 from "@onkernel/sdk";
+var US_STATE_CODES = {
+  alabama: "AL",
+  alaska: "AK",
+  arizona: "AZ",
+  arkansas: "AR",
+  california: "CA",
+  colorado: "CO",
+  connecticut: "CT",
+  delaware: "DE",
+  florida: "FL",
+  georgia: "GA",
+  hawaii: "HI",
+  idaho: "ID",
+  illinois: "IL",
+  indiana: "IN",
+  iowa: "IA",
+  kansas: "KS",
+  kentucky: "KY",
+  louisiana: "LA",
+  maine: "ME",
+  maryland: "MD",
+  massachusetts: "MA",
+  michigan: "MI",
+  minnesota: "MN",
+  mississippi: "MS",
+  missouri: "MO",
+  montana: "MT",
+  nebraska: "NE",
+  nevada: "NV",
+  "new hampshire": "NH",
+  "new jersey": "NJ",
+  "new mexico": "NM",
+  "new york": "NY",
+  "north carolina": "NC",
+  "north dakota": "ND",
+  ohio: "OH",
+  oklahoma: "OK",
+  oregon: "OR",
+  pennsylvania: "PA",
+  "rhode island": "RI",
+  "south carolina": "SC",
+  "south dakota": "SD",
+  tennessee: "TN",
+  texas: "TX",
+  utah: "UT",
+  vermont: "VT",
+  virginia: "VA",
+  washington: "WA",
+  "west virginia": "WV",
+  wisconsin: "WI",
+  wyoming: "WY"
+};
+var US_CITY_CENTER_ZIPS = {
+  "atlanta|GA": "30303",
+  "austin|TX": "78701",
+  "baltimore|MD": "21201",
+  "boston|MA": "02108",
+  "boulder|CO": "80302",
+  "charlotte|NC": "28202",
+  "chicago|IL": "60601",
+  "colorado_springs|CO": "80903",
+  "columbus|OH": "43215",
+  "dallas|TX": "75201",
+  "denver|CO": "80202",
+  "detroit|MI": "48226",
+  "fort_collins|CO": "80524",
+  "fort_worth|TX": "76102",
+  "houston|TX": "77002",
+  "indianapolis|IN": "46204",
+  "jacksonville|FL": "32202",
+  "las_vegas|NV": "89101",
+  "los_angeles|CA": "90012",
+  "louisville|KY": "40202",
+  "loveland|CO": "80537",
+  "memphis|TN": "38103",
+  "miami|FL": "33131",
+  "minneapolis|MN": "55401",
+  "nashville|TN": "37203",
+  "new_york|NY": "10001",
+  "orlando|FL": "32801",
+  "philadelphia|PA": "19103",
+  "phoenix|AZ": "85004",
+  "portland|OR": "97205",
+  "raleigh|NC": "27601",
+  "richmond|VA": "23219",
+  "sacramento|CA": "95814",
+  "salt_lake_city|UT": "84101",
+  "san_antonio|TX": "78205",
+  "san_diego|CA": "92101",
+  "san_francisco|CA": "94103",
+  "san_jose|CA": "95113",
+  "seattle|WA": "98101"
+};
+function proxyIdSuffix2(proxyId) {
+  return proxyId ? proxyId.slice(-6) : null;
+}
+function resolution(source, proxyMode, proxyId, target, error) {
+  return {
+    kernelProxyId: proxyId,
+    resolution: {
+      source,
+      proxyMode,
+      proxyIdPresent: Boolean(proxyId),
+      proxyIdSuffix: proxyIdSuffix2(proxyId),
+      target,
+      error
+    }
+  };
+}
+function normalizeStateName(value) {
+  return value.trim().toLowerCase().replace(/\s+/g, " ");
+}
+function normalizeCountryName(value) {
+  return value.trim().toLowerCase().replace(/\./g, "").replace(/\s+/g, " ");
+}
+function isUnitedStates(country) {
+  if (!country) return true;
+  const normalized = normalizeCountryName(country);
+  return normalized === "united states" || normalized === "united states of america" || normalized === "usa" || normalized === "us";
+}
+function stateCodeFor(region) {
+  const trimmed = region.trim();
+  if (/^[A-Za-z]{2}$/.test(trimmed)) return trimmed.toUpperCase();
+  return US_STATE_CODES[normalizeStateName(trimmed)] ?? null;
+}
+function kernelCityIdentifierCandidates(city) {
+  const ascii = city.normalize("NFKD").replace(/[^\x00-\x7F]/g, "").toLowerCase();
+  const words = ascii.split(/[^a-z0-9]+/).filter(Boolean);
+  const underscored = words.join("_");
+  const compact = words.join("");
+  return Array.from(new Set([underscored, compact].filter(Boolean)));
+}
+function proxyName(country, state, city) {
+  return city ? `mcp-serp-residential-${country.toLowerCase()}-${state.toLowerCase()}-${city}` : `mcp-serp-residential-${country.toLowerCase()}-${state.toLowerCase()}`;
+}
+function zipProxyName(zip) {
+  return `mcp-serp-residential-us-zip-${zip}`;
+}
+function parseKernelLocationProxyTarget(location, gl) {
+  if (!location || gl.toLowerCase() !== "us") return null;
+  const canonicalLocation = normalizeLocation(location);
+  let parts = canonicalLocation.split(",").map((part) => part.trim()).filter(Boolean);
+  if (parts.length > 1 && isUnitedStates(parts[parts.length - 1])) {
+    parts = parts.slice(0, -1);
+  }
+  if (parts.length === 1) {
+    const stateOnly = stateCodeFor(parts[0]);
+    if (!stateOnly) return null;
+    return {
+      canonicalLocation,
+      level: "state",
+      country: "US",
+      state: stateOnly,
+      city: "",
+      cityCandidates: [],
+      proxyName: proxyName("US", stateOnly),
+      config: {
+        country: "US",
+        state: stateOnly
+      }
+    };
+  }
+  const [city = "", region = ""] = parts;
+  if (!city || !region) return null;
+  const state = stateCodeFor(region);
+  if (!state) return null;
+  const cityCandidates = kernelCityIdentifierCandidates(city);
+  const primaryCity = cityCandidates[0];
+  if (!primaryCity) return null;
+  return {
+    canonicalLocation,
+    level: "city",
+    country: "US",
+    state,
+    city: primaryCity,
+    cityCandidates,
+    proxyName: proxyName("US", state, primaryCity),
+    config: {
+      country: "US",
+      state,
+      city: primaryCity
+    }
+  };
+}
+function cityZipKey(target) {
+  return `${target.city}|${target.state}`;
+}
+function knownZipFor(target, explicitZip) {
+  if (explicitZip && /^\d{5}$/.test(explicitZip)) return explicitZip;
+  return US_CITY_CENTER_ZIPS[cityZipKey(target)] ?? null;
+}
+function zipTarget(target, zip) {
+  return {
+    ...target,
+    level: "zip",
+    zip,
+    proxyName: zipProxyName(zip),
+    config: {
+      country: target.country,
+      state: target.state,
+      zip
+    }
+  };
+}
+function configMatches(config, target, city) {
+  if (target.level === "zip") {
+    return config?.country?.toUpperCase() === target.country && config?.zip === target.zip;
+  }
+  return config?.country?.toUpperCase() === target.country && config?.state?.toUpperCase() === target.state && (city ? config?.city === city : !config?.city);
+}
+function findExistingTargetProxy(proxies, target) {
+  return proxies.find((proxy) => proxy.type === "residential" && proxy.status !== "unavailable" && Boolean(proxy.id) && (proxy.name === target.proxyName || configMatches(proxy.config, target, target.level === "city" ? target.city : void 0))) ?? null;
+}
+function findExistingProxy(proxies, target) {
+  for (const city of target.cityCandidates) {
+    const name = proxyName(target.country, target.state, city);
+    const found = proxies.find((proxy) => proxy.type === "residential" && proxy.status !== "unavailable" && Boolean(proxy.id) && (proxy.name === name || configMatches(proxy.config, target, city)));
+    if (found) return found;
+  }
+  return null;
+}
+function stateTarget(target) {
+  return {
+    ...target,
+    level: "state",
+    proxyName: proxyName(target.country, target.state),
+    config: {
+      country: target.country,
+      state: target.state
+    }
+  };
+}
+function findExistingStateProxy(proxies, target) {
+  const name = proxyName(target.country, target.state);
+  return proxies.find((proxy) => proxy.type === "residential" && proxy.status !== "unavailable" && Boolean(proxy.id) && (proxy.name === name || configMatches(proxy.config, target))) ?? null;
+}
+function escalatedTargetLevel(target, attemptIndex) {
+  return stateTarget(target);
+}
+function errorText2(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+async function resolveKernelProxyId(options) {
+  if (options.proxyMode === "none") {
+    return resolution("disabled", options.proxyMode, void 0, null, null);
+  }
+  if (options.proxyMode === "configured") {
+    return resolution("configured_fallback", options.proxyMode, options.configuredKernelProxyId, null, null);
+  }
+  const target = parseKernelLocationProxyTarget(options.location, options.gl);
+  if (!target || !options.kernelApiKey) {
+    return resolution("configured_fallback", options.proxyMode, options.configuredKernelProxyId, target, target ? null : "location could not be normalized to a US city/state proxy target");
+  }
+  const kernel = new Kernel2({ apiKey: options.kernelApiKey });
+  try {
+    const attemptIndex = options.attemptIndex ?? 0;
+    if (attemptIndex >= 1) {
+      const escalatedTarget = escalatedTargetLevel(target, attemptIndex);
+      const createErrors2 = [];
+      try {
+        const created = await kernel.proxies.create({
+          type: "residential",
+          name: escalatedTarget.proxyName,
+          config: escalatedTarget.config
+        });
+        if (created.id) {
+          return resolution("location_created", options.proxyMode, created.id, escalatedTarget, null);
+        }
+        createErrors2.push(`${escalatedTarget.state}: Kernel did not return a proxy id`);
+      } catch (err) {
+        createErrors2.push(`${escalatedTarget.state}: ${errorText2(err)}`);
+      }
+      return resolution("configured_fallback", options.proxyMode, options.configuredKernelProxyId, escalatedTarget, createErrors2.join(" | "));
+    }
+    const proxies = await kernel.proxies.list();
+    const zip = knownZipFor(target, options.proxyZip);
+    const createErrors = [];
+    if (zip) {
+      const targetZip = zipTarget(target, zip);
+      const existingZip = findExistingTargetProxy(proxies, targetZip);
+      if (existingZip?.id) {
+        return resolution("location_reused", options.proxyMode, existingZip.id, targetZip, null);
+      }
+      try {
+        const created = await kernel.proxies.create({
+          type: "residential",
+          name: targetZip.proxyName,
+          config: {
+            country: targetZip.country,
+            zip
+          }
+        });
+        if (created.id) {
+          return resolution("location_created", options.proxyMode, created.id, targetZip, null);
+        }
+        createErrors.push(`${zip}: Kernel did not return a proxy id`);
+      } catch (err) {
+        createErrors.push(`${zip}: ${errorText2(err)}`);
+      }
+    }
+    const existing = findExistingProxy(proxies, target);
+    if (existing?.id) {
+      return resolution("location_reused", options.proxyMode, existing.id, target, createErrors.join(" | ") || null);
+    }
+    for (const city of target.cityCandidates) {
+      try {
+        const created = await kernel.proxies.create({
+          type: "residential",
+          name: proxyName(target.country, target.state, city),
+          config: {
+            country: target.country,
+            state: target.state,
+            city
+          }
+        });
+        if (created.id) {
+          return resolution("location_created", options.proxyMode, created.id, {
+            ...target,
+            level: "city",
+            city,
+            proxyName: proxyName(target.country, target.state, city),
+            config: {
+              country: target.country,
+              state: target.state,
+              city
+            }
+          }, null);
+        }
+        createErrors.push(`${city}: Kernel did not return a proxy id`);
+      } catch (err) {
+        createErrors.push(`${city}: ${errorText2(err)}`);
+      }
+    }
+    const fallbackTarget = stateTarget(target);
+    const existingState = findExistingStateProxy(proxies, fallbackTarget);
+    if (existingState?.id) {
+      return resolution("location_reused", options.proxyMode, existingState.id, fallbackTarget, createErrors.join(" | "));
+    }
+    try {
+      const created = await kernel.proxies.create({
+        type: "residential",
+        name: fallbackTarget.proxyName,
+        config: fallbackTarget.config
+      });
+      if (created.id) {
+        return resolution("location_created", options.proxyMode, created.id, fallbackTarget, createErrors.join(" | "));
+      }
+      createErrors.push(`${fallbackTarget.state}: Kernel did not return a proxy id`);
+    } catch (err) {
+      createErrors.push(`${fallbackTarget.state}: ${errorText2(err)}`);
+    }
+    return resolution("configured_fallback", options.proxyMode, options.configuredKernelProxyId, target, createErrors.join(" | "));
+  } catch (err) {
+    return resolution("configured_fallback", options.proxyMode, options.configuredKernelProxyId, target, errorText2(err));
+  }
+}
+
+// src/harvest.ts
+var MAX_ATTEMPTS = 3;
+function abortReason(signal) {
+  if (signal.reason instanceof DOMException && signal.reason.name === "TimeoutError") return signal.reason;
+  return new RequestAbortedError();
+}
+function getAbortSignal(rawOptions) {
+  if (!rawOptions || typeof rawOptions !== "object") return void 0;
+  const signal = rawOptions.signal;
+  if (signal instanceof AbortSignal) return signal;
+  return void 0;
+}
+function getAttemptLogSink(rawOptions) {
+  if (!rawOptions || typeof rawOptions !== "object") return void 0;
+  const sink = rawOptions.onAttemptEvent;
+  return typeof sink === "function" ? sink : void 0;
+}
+async function emitAttemptEvent(sink, event) {
+  if (!sink) return;
+  try {
+    await sink(event);
+  } catch (err) {
+    console.warn(JSON.stringify({
+      event: "harvest_attempt_log_failed",
+      attempt_number: event.attemptNumber,
+      message: err instanceof Error ? err.message : String(err)
+    }));
+  }
+}
+function classifyAttemptError(err) {
+  if (err instanceof CaptchaError) return "captcha";
+  if (err instanceof RequestAbortedError) return "request_aborted";
+  if (err instanceof DOMException && (err.name === "TimeoutError" || err.name === "AbortError")) return "timeout";
+  const message = err instanceof Error ? err.message : String(err);
+  return /timeout|timed out|Timeout \d+ms exceeded|deadline/i.test(message) ? "timeout" : "error";
+}
+function classifyAttemptResult(result) {
+  return result.diagnostics?.completionStatus ?? (result.totalQuestions > 0 ? "paa_found" : "no_paa");
+}
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+async function extractOnce(options, signal) {
+  const driver = new BrowserDriver();
+  const reporter = new ProgressReporter();
+  const extractor = new PAAExtractor(driver, reporter);
+  if (signal?.aborted) {
+    return {
+      result: null,
+      error: abortReason(signal),
+      cleanup: await driver.close(),
+      debug: null
+    };
+  }
+  let onAbort;
+  const abortPromise = signal ? new Promise((_, reject) => {
+    onAbort = () => reject(abortReason(signal));
+    signal.addEventListener("abort", onAbort, { once: true });
+  }) : null;
+  let result = null;
+  let error = null;
+  let cleanup;
+  let debug = null;
+  try {
+    const extraction = extractor.extract(options, signal);
+    if (abortPromise) extraction.catch(() => {
+    });
+    result = await (abortPromise ? Promise.race([extraction, abortPromise]) : extraction);
+  } catch (err) {
+    error = err;
+  } finally {
+    if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+    debug = result?.diagnostics.debug ?? (options.debug ? {
+      enabled: true,
+      request: {
+        query: options.query,
+        locationInput: options.location ?? null,
+        canonicalLocation: null,
+        uule: null,
+        gl: options.gl,
+        hl: options.hl,
+        device: options.device,
+        proxyMode: options.proxyMode,
+        proxyZip: options.proxyZip ?? null,
+        serpOnly: options.serpOnly,
+        pages: options.pages ?? 1
+      },
+      browser: driver.getDebugSnapshot()
+    } : null);
+    cleanup = await driver.close();
+  }
+  return error ? { result: null, error, cleanup, debug } : { result, error: null, cleanup, debug };
+}
+async function harvest(rawOptions) {
+  const raw = typeof rawOptions === "object" && rawOptions !== null ? rawOptions : {};
+  const signal = getAbortSignal(rawOptions);
+  const onAttemptEvent = getAttemptLogSink(rawOptions);
+  const requestedProxyMode = raw.proxyMode;
+  const proxyMode = requestedProxyMode === "none" ? "none" : requestedProxyMode === "configured" ? "configured" : "location";
+  const kernelApiKey = typeof raw.kernelApiKey === "string" ? raw.kernelApiKey.trim() : process.env.KERNEL_API_KEY?.trim();
+  const configuredKernelProxyId = typeof raw.kernelProxyId === "string" ? raw.kernelProxyId.trim() : process.env.KERNEL_PROXY_ID?.trim();
+  const proxyOpts = {
+    kernelApiKey,
+    proxyMode,
+    configuredKernelProxyId,
+    location: typeof raw.location === "string" ? raw.location : void 0,
+    proxyZip: typeof raw.proxyZip === "string" ? raw.proxyZip : void 0,
+    gl: typeof raw.gl === "string" ? raw.gl : "us"
+  };
+  const serializer = new OutputSerializer();
+  for (let i = 0; i < MAX_ATTEMPTS; i++) {
+    const attemptNumber = i + 1;
+    const startedAtMs = Date.now();
+    try {
+      if (signal?.aborted) throw abortReason(signal);
+      const resolution2 = await resolveKernelProxyId({ ...proxyOpts, attemptIndex: i });
+      const mergedAttempt = {
+        ...raw,
+        kernelApiKey,
+        kernelProxyId: resolution2.kernelProxyId,
+        kernelProxyResolution: resolution2.resolution,
+        proxyMode
+      };
+      if (proxyMode === "none") mergedAttempt.kernelProxyId = void 0;
+      const attemptOptions = HarvestOptionsSchema.parse(mergedAttempt);
+      await emitAttemptEvent(onAttemptEvent, {
+        type: "started",
+        attemptNumber,
+        maxAttempts: MAX_ATTEMPTS,
+        query: attemptOptions.query,
+        location: attemptOptions.location ?? null,
+        maxQuestions: attemptOptions.maxQuestions,
+        startedAt: new Date(startedAtMs).toISOString()
+      });
+      console.info(JSON.stringify({
+        event: "harvest_attempt_started",
+        attempt_number: attemptNumber,
+        max_attempts: MAX_ATTEMPTS,
+        query: attemptOptions.query,
+        location: attemptOptions.location ?? null,
+        max_questions: attemptOptions.maxQuestions
+      }));
+      const attempt = await extractOnce(attemptOptions, signal);
+      if (attempt.error) {
+        const err = attempt.error;
+        if (err instanceof CaptchaError) {
+          const willRetry = i < MAX_ATTEMPTS - 1;
+          console.warn(JSON.stringify({
+            event: "harvest_attempt_captcha",
+            attempt_number: attemptNumber,
+            max_attempts: MAX_ATTEMPTS,
+            message: err.message,
+            will_retry: willRetry
+          }));
+          await emitAttemptEvent(onAttemptEvent, {
+            type: "finished",
+            attemptNumber,
+            maxAttempts: MAX_ATTEMPTS,
+            outcome: "captcha",
+            kernelSessionId: attempt.cleanup.kernelSessionId,
+            questionCount: 0,
+            durationMs: Date.now() - startedAtMs,
+            error: err.message,
+            willRetry,
+            cleanup: attempt.cleanup,
+            debug: attempt.debug,
+            completedAt: (/* @__PURE__ */ new Date()).toISOString()
+          });
+          if (willRetry) continue;
+          break;
+        }
+        await emitAttemptEvent(onAttemptEvent, {
+          type: "finished",
+          attemptNumber,
+          maxAttempts: MAX_ATTEMPTS,
+          outcome: classifyAttemptError(err),
+          kernelSessionId: attempt.cleanup.kernelSessionId,
+          questionCount: 0,
+          durationMs: Date.now() - startedAtMs,
+          error: errorMessage(err),
+          willRetry: false,
+          cleanup: attempt.cleanup,
+          debug: attempt.debug,
+          completedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        throw err;
+      }
+      const result = attempt.result;
+      if (!result) throw new Error("Harvest attempt completed without a result");
+      await emitAttemptEvent(onAttemptEvent, {
+        type: "finished",
+        attemptNumber,
+        maxAttempts: MAX_ATTEMPTS,
+        outcome: classifyAttemptResult(result),
+        kernelSessionId: attempt.cleanup.kernelSessionId,
+        questionCount: result.totalQuestions,
+        durationMs: Date.now() - startedAtMs,
+        error: null,
+        willRetry: false,
+        cleanup: attempt.cleanup,
+        debug: attempt.debug,
+        completedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      if (attemptOptions.format === "json" || attemptOptions.format === "both") {
+        await serializer.writeJSON(result, attemptOptions.outputDir);
+      }
+      if (attemptOptions.format === "csv" || attemptOptions.format === "both") {
+        await Promise.all([
+          serializer.writeCSV(result.flat, attemptOptions.outputDir),
+          result.videos.length > 0 ? serializer.writeVideoCSV(result.videos, result.seed, attemptOptions.outputDir) : Promise.resolve(""),
+          result.forums.length > 0 ? serializer.writeForumCSV(result.forums, result.seed, attemptOptions.outputDir) : Promise.resolve(""),
+          result.aiOverview.detected ? serializer.writeAIOverviewCSV(result.aiOverview.citations, result.aiOverview.text, result.seed, attemptOptions.outputDir) : Promise.resolve(""),
+          result.aiMode.detected ? serializer.writeAIModeCSV(result.aiMode.citations, result.aiMode.text, result.seed, attemptOptions.outputDir) : Promise.resolve(""),
+          result.whatPeopleSaying.length > 0 ? serializer.writeWhatPeopleSayingCSV(result.whatPeopleSaying, result.seed, attemptOptions.outputDir) : Promise.resolve("")
+        ]);
+      }
+      return result;
+    } catch (err) {
+      if (err instanceof CaptchaError) {
+        const willRetry = i < MAX_ATTEMPTS - 1;
+        console.warn(JSON.stringify({
+          event: "harvest_attempt_captcha",
+          attempt_number: attemptNumber,
+          max_attempts: MAX_ATTEMPTS,
+          message: err.message,
+          will_retry: willRetry
+        }));
+        await emitAttemptEvent(onAttemptEvent, {
+          type: "finished",
+          attemptNumber,
+          maxAttempts: MAX_ATTEMPTS,
+          outcome: "captcha",
+          kernelSessionId: null,
+          questionCount: 0,
+          durationMs: Date.now() - startedAtMs,
+          error: err.message,
+          willRetry,
+          cleanup: {
+            kernelSessionId: null,
+            kernelDeleteStarted: false,
+            kernelDeleteSucceeded: null,
+            kernelDeleteError: null,
+            browserCloseSucceeded: null,
+            browserCloseError: null
+          },
+          debug: null,
+          completedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        if (willRetry) continue;
+        break;
+      }
+      await emitAttemptEvent(onAttemptEvent, {
+        type: "finished",
+        attemptNumber,
+        maxAttempts: MAX_ATTEMPTS,
+        outcome: classifyAttemptError(err),
+        kernelSessionId: null,
+        questionCount: 0,
+        durationMs: Date.now() - startedAtMs,
+        error: errorMessage(err),
+        willRetry: false,
+        cleanup: {
+          kernelSessionId: null,
+          kernelDeleteStarted: false,
+          kernelDeleteSucceeded: null,
+          kernelDeleteError: null,
+          browserCloseSucceeded: null,
+          browserCloseError: null
+        },
+        debug: null,
+        completedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      throw err;
+    }
+  }
+  console.warn(JSON.stringify({
+    event: "harvest_captcha_exhausted",
+    max_attempts: MAX_ATTEMPTS,
+    session_kind: kernelApiKey ? "kernel" : "local"
+  }));
+  throw new CaptchaError(sanitizeVendorName(`CAPTCHA on all ${MAX_ATTEMPTS} fresh sessions. Try again in a few minutes.`));
+}
+
+export {
+  MapsPlaceOptionsSchema,
+  RawMapsOverviewSchema,
+  RawMapsHoursRowSchema,
+  RawMapsReviewStatsSchema,
+  RawMapsAboutAttributeSchema,
+  MapsSelectors,
+  CaptchaError,
+  RequestAbortedError,
+  buildYouTubeChannelVideosUrl,
+  BrowserDriver,
+  harvest
+};
+//# sourceMappingURL=chunk-HERFK7W6.js.map