mcp-scraper 0.40.1 → 0.40.2

package/dist/bin/paa-harvest.cjs

@@ -0,0 +1,3808 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/cli.ts
+var import_commander = require("commander");
+
+// src/lib/browser-service-env.ts
+function browserServiceApiKey() {
+  const value = (process.env.BROWSER_SERVICE_API_KEY ?? process.env.KERNEL_API_KEY)?.trim();
+  return value || void 0;
+}
+function browserServiceProxyId() {
+  return void 0;
+}
+
+// src/schemas.ts
+var import_zod = require("zod");
+var DEFAULT_PROXY_MODE = "none";
+var DEFAULT_MAPS_PROXY_MODE = "none";
+var HarvestOptionsSchema = import_zod.z.object({
+  query: import_zod.z.string().min(1),
+  location: import_zod.z.string().optional(),
+  gl: import_zod.z.string().length(2).default("us"),
+  hl: import_zod.z.string().length(2).default("en"),
+  device: import_zod.z.enum(["desktop", "mobile"]).default("desktop"),
+  proxyMode: import_zod.z.enum(["location", "configured", "none"]).default(DEFAULT_PROXY_MODE),
+  proxyZip: import_zod.z.string().regex(/^\d{5}$/).optional(),
+  keepDefaultProxy: import_zod.z.boolean().optional(),
+  requireUsEgress: import_zod.z.boolean().optional(),
+  maxAttempts: import_zod.z.number().int().min(1).max(12).optional(),
+  debug: import_zod.z.boolean().default(false),
+  depth: import_zod.z.number().int().min(1).max(30).default(3),
+  maxQuestions: import_zod.z.number().int().min(1).max(1e3).default(100),
+  headless: import_zod.z.boolean().default(false),
+  profileDir: import_zod.z.string().optional(),
+  proxy: import_zod.z.string().url().optional(),
+  kernelApiKey: import_zod.z.string().optional(),
+  kernelProxyId: import_zod.z.string().optional(),
+  kernelProxyResolution: import_zod.z.unknown().optional(),
+  outputDir: import_zod.z.string().default("./paa-output"),
+  format: import_zod.z.enum(["json", "csv", "both"]).default("both"),
+  serpOnly: import_zod.z.boolean().default(false),
+  pages: import_zod.z.number().int().min(1).max(2).default(1),
+  recency: import_zod.z.enum(["day", "week", "month", "year"]).optional(),
+  softDeadlineMs: import_zod.z.number().optional()
+});
+function recencyToTbs(recency) {
+  switch (recency) {
+    case "day":
+      return "qdr:d";
+    case "week":
+      return "qdr:w";
+    case "month":
+      return "qdr:m";
+    case "year":
+      return "qdr:y";
+    default:
+      return void 0;
+  }
+}
+var MapsPlaceOptionsSchema = import_zod.z.object({
+  businessName: import_zod.z.string().min(1),
+  location: import_zod.z.string().min(1),
+  gl: import_zod.z.string().length(2).default("us"),
+  hl: import_zod.z.string().length(2).default("en"),
+  includeReviews: import_zod.z.boolean().default(false),
+  maxReviews: import_zod.z.number().int().min(1).max(500).default(50),
+  includeServices: import_zod.z.boolean().default(false),
+  kernelApiKey: import_zod.z.string().optional(),
+  kernelProxyId: import_zod.z.string().optional(),
+  headless: import_zod.z.boolean().default(true)
+});
+var MapsSearchOptionsSchema = import_zod.z.object({
+  query: import_zod.z.string().min(1),
+  location: import_zod.z.string().optional(),
+  gl: import_zod.z.string().length(2).default("us"),
+  hl: import_zod.z.string().length(2).default("en"),
+  maxResults: import_zod.z.number().int().min(1).max(50).default(10),
+  includeServices: import_zod.z.boolean().default(false),
+  proxyMode: import_zod.z.enum(["location", "configured", "none"]).default(DEFAULT_MAPS_PROXY_MODE),
+  proxyZip: import_zod.z.string().regex(/^\d{5}$/).optional(),
+  serpRedirect: import_zod.z.boolean().optional(),
+  forceDirectEgress: import_zod.z.boolean().optional(),
+  debug: import_zod.z.boolean().default(false),
+  kernelApiKey: import_zod.z.string().optional(),
+  kernelProxyId: import_zod.z.string().optional(),
+  kernelProxyResolution: import_zod.z.unknown().optional(),
+  headless: import_zod.z.boolean().default(true)
+});
+var RawPAAItemSchema = import_zod.z.object({
+  question: import_zod.z.string().min(1),
+  answer: import_zod.z.string().optional(),
+  sourceTitle: import_zod.z.string().optional(),
+  sourceSite: import_zod.z.string().optional(),
+  sourceCite: import_zod.z.string().optional()
+});
+var RawMapsOverviewSchema = import_zod.z.object({
+  name: import_zod.z.string().nullable(),
+  rating: import_zod.z.string().nullable(),
+  reviewCount: import_zod.z.string().nullable(),
+  category: import_zod.z.string().nullable(),
+  address: import_zod.z.string().nullable(),
+  hoursSummary: import_zod.z.string().nullable(),
+  phone: import_zod.z.string().nullable(),
+  phoneDisplay: import_zod.z.string().nullable(),
+  website: import_zod.z.string().nullable(),
+  plusCode: import_zod.z.string().nullable(),
+  bookingUrl: import_zod.z.string().nullable()
+});
+var RawMapsHoursRowSchema = import_zod.z.object({
+  day: import_zod.z.string(),
+  hours: import_zod.z.string()
+});
+var RawMapsReviewStatsSchema = import_zod.z.object({
+  reviewHistogram: import_zod.z.array(import_zod.z.object({
+    stars: import_zod.z.number(),
+    count: import_zod.z.string()
+  })),
+  reviewTopics: import_zod.z.array(import_zod.z.object({
+    label: import_zod.z.string(),
+    count: import_zod.z.string()
+  }))
+});
+var RawMapsReviewCardSchema = import_zod.z.object({
+  reviewId: import_zod.z.string(),
+  author: import_zod.z.string().nullable(),
+  stars: import_zod.z.string().nullable(),
+  date: import_zod.z.string().nullable(),
+  text: import_zod.z.string().nullable(),
+  ownerResponse: import_zod.z.string().nullable()
+});
+var RawMapsAboutAttributeSchema = import_zod.z.object({
+  section: import_zod.z.string(),
+  attribute: import_zod.z.string()
+});
+
+// src/driver/BrowserDriver.ts
+var import_playwright_extra = require("playwright-extra");
+var import_puppeteer_extra_plugin_stealth = __toESM(require("puppeteer-extra-plugin-stealth"), 1);
+var import_playwright = require("playwright");
+var import_sdk = __toESM(require("@onkernel/sdk"), 1);
+
+// 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"
+};
+
+// 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);
+  }
+};
+var LocationMismatchError = class extends Error {
+  name = "LocationMismatchError";
+  constructor(message = "Google returned results for a different location than requested") {
+    super(message);
+  }
+};
+
+// src/api/cost-telemetry.ts
+var import_node_crypto2 = require("crypto");
+
+// src/api/db.ts
+var import_http = require("@libsql/client/http");
+var import_node_crypto = require("crypto");
+var import_zod2 = require("zod");
+var DB_URL = process.env.TURSO_DATABASE_URL ?? "file:./paa-api.db";
+var DB_TOKEN = process.env.TURSO_AUTH_TOKEN;
+var _db = null;
+function getDb() {
+  if (!_db) _db = (0, import_http.createClient)({ url: DB_URL, authToken: DB_TOKEN });
+  return _db;
+}
+var REQUEST_EVENT_RESULT_MAX_BYTES = 32 * 1024;
+var SiteAuditJobRowSchema = import_zod2.z.object({
+  id: import_zod2.z.string(),
+  user_id: import_zod2.z.number(),
+  status: import_zod2.z.string().default("pending"),
+  client_domain: import_zod2.z.string(),
+  session_path: import_zod2.z.string(),
+  request: import_zod2.z.string(),
+  result: import_zod2.z.string().nullable(),
+  error: import_zod2.z.string().nullable(),
+  created_at: import_zod2.z.string(),
+  updated_at: import_zod2.z.string()
+});
+var SiteAuditPhaseLogRowSchema = import_zod2.z.object({
+  id: import_zod2.z.number(),
+  job_id: import_zod2.z.string(),
+  phase: import_zod2.z.string(),
+  completed_at: import_zod2.z.string(),
+  output_summary: import_zod2.z.string()
+});
+
+// src/api/cost-context.ts
+var import_node_async_hooks = require("async_hooks");
+var storage = new import_node_async_hooks.AsyncLocalStorage();
+function runWithCostContext(ctx, fn) {
+  return storage.run(ctx, fn);
+}
+function currentCostContext() {
+  return storage.getStore();
+}
+
+// src/api/cost-rates.ts
+var KERNEL_HEADLESS_USD_PER_SEC = 166667e-10;
+var KERNEL_HEADFUL_USD_PER_SEC = 1333336e-10;
+var HEADLESS_OPS = /* @__PURE__ */ new Set(["serp", "fb_search", "fb_ad", "instagram"]);
+function envRate(name, fallback) {
+  const raw = process.env[name]?.trim();
+  if (!raw) return fallback;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback;
+}
+var NANGO_USD_PER_CONNECTION_MONTH = envRate("NANGO_USD_PER_CONNECTION_MONTH", 1);
+var NANGO_USD_PER_FUNCTION_RUN = envRate("NANGO_USD_PER_FUNCTION_RUN", 1e-4);
+var NANGO_USD_PER_PROXY_REQUEST = envRate("NANGO_USD_PER_PROXY_REQUEST", 1e-4);
+var NANGO_USD_PER_COMPUTE_SEC = envRate("NANGO_USD_PER_COMPUTE_SEC", 2e-4);
+function kernelCostUsd(ms, headful) {
+  const sec = Math.max(0, ms) / 1e3;
+  return sec * (headful ? KERNEL_HEADFUL_USD_PER_SEC : KERNEL_HEADLESS_USD_PER_SEC);
+}
+
+// src/api/cost-telemetry.ts
+var _ready = false;
+var _migrationPromise = null;
+async function migrateCostTelemetry() {
+  if (_ready) return;
+  if (_migrationPromise) return _migrationPromise;
+  _migrationPromise = runCostTelemetryMigration().finally(() => {
+    _migrationPromise = null;
+  });
+  return _migrationPromise;
+}
+async function runCostTelemetryMigration() {
+  const db = getDb();
+  const existing = await db.execute(`
+    SELECT
+      (SELECT COUNT(*) FROM sqlite_master WHERE type = 'table' AND name IN ('kernel_session_log', 'vendor_usage_log', 'cost_probe_runs')) = 3
+      AND (SELECT COUNT(*) FROM pragma_table_info('kernel_session_log') WHERE name IN ('proxy_source', 'proxy_type', 'method')) = 3
+      AND (SELECT COUNT(*) FROM pragma_table_info('vendor_usage_log') WHERE name = 'method') = 1
+      AND (SELECT COUNT(*) FROM pragma_table_info('cost_probe_runs') WHERE name IN ('units', 'unit_type', 'mode')) = 3
+      AS ready
+  `);
+  if (Number(existing.rows[0]?.ready ?? 0) === 1) {
+    _ready = true;
+    return;
+  }
+  await db.execute(`
+    CREATE TABLE IF NOT EXISTS kernel_session_log (
+      id                    TEXT PRIMARY KEY,
+      kernel_session_id     TEXT,
+      op                    TEXT,
+      source                TEXT NOT NULL,
+      probe_run_id          TEXT,
+      user_id               INTEGER,
+      stealth               INTEGER,
+      headless_sent         INTEGER,
+      proxy_used            INTEGER,
+      fallback              INTEGER NOT NULL DEFAULT 0,
+      opened_at             TEXT,
+      closed_at             TEXT,
+      duration_ms           INTEGER NOT NULL DEFAULT 0,
+      est_cost_usd_headless REAL NOT NULL DEFAULT 0,
+      est_cost_usd_headful  REAL NOT NULL DEFAULT 0,
+      error                 TEXT,
+      created_at            TEXT NOT NULL DEFAULT (datetime('now'))
+    )
+  `);
+  await db.execute(`CREATE INDEX IF NOT EXISTS kernel_session_log_op ON kernel_session_log(op)`);
+  await db.execute(`CREATE INDEX IF NOT EXISTS kernel_session_log_probe ON kernel_session_log(probe_run_id)`);
+  await db.execute(`CREATE INDEX IF NOT EXISTS kernel_session_log_created ON kernel_session_log(created_at)`);
+  try {
+    await db.execute(`ALTER TABLE kernel_session_log ADD COLUMN proxy_source TEXT`);
+  } catch {
+  }
+  try {
+    await db.execute(`ALTER TABLE kernel_session_log ADD COLUMN proxy_type TEXT`);
+  } catch {
+  }
+  try {
+    await db.execute(`ALTER TABLE kernel_session_log ADD COLUMN method TEXT`);
+  } catch {
+  }
+  await db.execute(`
+    CREATE TABLE IF NOT EXISTS vendor_usage_log (
+      id           TEXT PRIMARY KEY,
+      op           TEXT,
+      probe_run_id TEXT,
+      user_id      INTEGER,
+      vendor       TEXT NOT NULL,
+      model        TEXT,
+      units        REAL NOT NULL DEFAULT 0,
+      unit_type    TEXT,
+      est_cost_usd REAL NOT NULL DEFAULT 0,
+      error        TEXT,
+      created_at   TEXT NOT NULL DEFAULT (datetime('now'))
+    )
+  `);
+  await db.execute(`CREATE INDEX IF NOT EXISTS vendor_usage_log_op ON vendor_usage_log(op)`);
+  await db.execute(`CREATE INDEX IF NOT EXISTS vendor_usage_log_probe ON vendor_usage_log(probe_run_id)`);
+  await db.execute(`CREATE INDEX IF NOT EXISTS vendor_usage_log_created ON vendor_usage_log(created_at)`);
+  try {
+    await db.execute(`ALTER TABLE vendor_usage_log ADD COLUMN method TEXT`);
+  } catch {
+  }
+  await db.execute(`
+    CREATE TABLE IF NOT EXISTS cost_probe_runs (
+      id                            TEXT PRIMARY KEY,
+      tool                          TEXT NOT NULL,
+      target                        TEXT,
+      started_at                    TEXT NOT NULL DEFAULT (datetime('now')),
+      wall_ms                       INTEGER NOT NULL DEFAULT 0,
+      success                       INTEGER NOT NULL DEFAULT 0,
+      error                         TEXT,
+      http_only                     INTEGER NOT NULL DEFAULT 0,
+      kernel_used                   INTEGER NOT NULL DEFAULT 0,
+      kernel_sessions               INTEGER NOT NULL DEFAULT 0,
+      kernel_seconds_total          REAL NOT NULL DEFAULT 0,
+      kernel_tier_observed          TEXT,
+      est_kernel_cost_usd_headless  REAL NOT NULL DEFAULT 0,
+      est_kernel_cost_usd_headful   REAL NOT NULL DEFAULT 0,
+      vendor_cost_usd               REAL NOT NULL DEFAULT 0,
+      charged_credits               REAL NOT NULL DEFAULT 0,
+      margin_usd_headless_starter   REAL NOT NULL DEFAULT 0,
+      margin_usd_headful_starter    REAL NOT NULL DEFAULT 0,
+      notes                         TEXT
+    )
+  `);
+  await db.execute(`CREATE INDEX IF NOT EXISTS cost_probe_runs_tool ON cost_probe_runs(tool)`);
+  try {
+    await db.execute(`ALTER TABLE cost_probe_runs ADD COLUMN units REAL`);
+  } catch {
+  }
+  try {
+    await db.execute(`ALTER TABLE cost_probe_runs ADD COLUMN unit_type TEXT`);
+  } catch {
+  }
+  try {
+    await db.execute(`ALTER TABLE cost_probe_runs ADD COLUMN mode TEXT`);
+  } catch {
+  }
+  _ready = true;
+}
+async function recordKernelSession(r) {
+  try {
+    await migrateCostTelemetry();
+    const ctx = currentCostContext();
+    const durationMs = Math.max(0, r.closedAtMs - r.openedAtMs);
+    const db = getDb();
+    await db.execute({
+      sql: `INSERT INTO kernel_session_log
+        (id, kernel_session_id, op, source, probe_run_id, user_id, stealth, headless_sent, proxy_used, proxy_source, proxy_type, fallback, opened_at, closed_at, duration_ms, est_cost_usd_headless, est_cost_usd_headful, error, method)
+        VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+      args: [
+        (0, import_node_crypto2.randomUUID)(),
+        r.kernelSessionId ?? null,
+        ctx?.op ?? null,
+        r.source,
+        ctx?.probeRunId ?? null,
+        ctx?.userId ?? null,
+        boolToInt(r.stealth),
+        boolToInt(r.headlessSent),
+        boolToInt(r.proxyUsed),
+        r.proxySource ?? null,
+        r.proxyType ?? null,
+        r.fallback ? 1 : 0,
+        new Date(r.openedAtMs).toISOString(),
+        new Date(r.closedAtMs).toISOString(),
+        durationMs,
+        kernelCostUsd(durationMs, false),
+        kernelCostUsd(durationMs, true),
+        r.error ?? null,
+        ctx?.subOp ?? null
+      ]
+    });
+  } catch (err) {
+    console.warn("[cost-telemetry] recordKernelSession failed:", err instanceof Error ? err.message : String(err));
+  }
+}
+function boolToInt(v) {
+  if (v === null || v === void 0) return null;
+  return v ? 1 : 0;
+}
+
+// src/driver/BrowserDriver.ts
+import_playwright_extra.chromium.use((0, import_puppeteer_extra_plugin_stealth.default)());
+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 serpArrivalUrl(googleUrl, baseOverride) {
+  const base = (baseOverride ?? process.env.SERP_REDIRECT_BASE)?.trim().replace(/\/+$/, "");
+  if (!base) return googleUrl;
+  return `${base}/g/${Buffer.from(googleUrl, "utf8").toString("base64url")}`;
+}
+function isUsCountry(country) {
+  if (!country) return false;
+  return /united states|u\.?s\.?a?\.?|^us$/i.test(country.trim());
+}
+function errorText(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function isKernelProfileConflict(err) {
+  return /\b409\b|conflict|already exists/i.test(errorText(err));
+}
+async function ensureKernelProfile(kernelClient, name) {
+  try {
+    await kernelClient.profiles.create({ name });
+  } catch (err) {
+    if (!isKernelProfileConflict(err)) throw 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;
+  kernelOpenedAtMs = null;
+  kernelStealth = null;
+  kernelProxyUsed = null;
+  kernelProxySource = null;
+  kernelProxyType = null;
+  kernelHeadlessSent = 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 import_sdk.default({ apiKey: config.kernelApiKey });
+      const timeoutSeconds = positiveIntFromEnv("KERNEL_BROWSER_TIMEOUT_SECONDS", DEFAULT_KERNEL_BROWSER_TIMEOUT_SECONDS);
+      if (config.kernelProfileName && config.kernelProfileSaveChanges === true) {
+        await ensureKernelProfile(this.kernelClient, config.kernelProfileName);
+      }
+      const costCtx = currentCostContext();
+      let useHeadless;
+      if (config.headlessMode === "headful" || costCtx?.forceHeadful === true) useHeadless = false;
+      else if (config.headlessMode === "headless") useHeadless = true;
+      else useHeadless = costCtx?.forceHeadless === true || process.env.KERNEL_HEADLESS_DISABLED !== "true" && !!costCtx?.op && HEADLESS_OPS.has(costCtx.op);
+      this.kernelHeadlessSent = useHeadless ? true : null;
+      if (costCtx?.headlessSentOut) costCtx.headlessSentOut.value = this.kernelHeadlessSent;
+      const kernelBrowser = await this.kernelClient.browsers.create({
+        stealth: true,
+        timeout_seconds: timeoutSeconds,
+        ...useHeadless ? { headless: true } : {},
+        ...config.kernelProxyId ? { proxy_id: config.kernelProxyId } : {},
+        ...config.kernelProfileName ? {
+          profile: {
+            name: config.kernelProfileName,
+            ...typeof config.kernelProfileSaveChanges === "boolean" ? { save_changes: config.kernelProfileSaveChanges } : {}
+          }
+        } : {}
+      });
+      this.kernelSessionId = kernelBrowser.session_id;
+      this.kernelOpenedAtMs = Date.now();
+      this.kernelStealth = typeof kernelBrowser.stealth === "boolean" ? kernelBrowser.stealth : null;
+      this.kernelProxyUsed = typeof kernelBrowser.proxy_id === "string" ? Boolean(kernelBrowser.proxy_id) : Boolean(config.kernelProxyId);
+      this.kernelProxySource = config.kernelProxyResolution?.source ?? null;
+      this.kernelProxyType = config.kernelProxyResolution?.proxyType ?? null;
+      let defaultProxyDisabled = null;
+      let defaultProxyDisableError = null;
+      if (!config.kernelProxyId && !config.keepDefaultProxy) {
+        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),
+        profile_name_present: Boolean(config.kernelProfileName),
+        proxy_resolution_source: config.kernelProxyResolution?.source
+      }));
+      if (this.debugEnabled) {
+        await this.populateKernelRetrieveDebug(kernelDebug, config.kernelProxyId);
+      }
+      this.browser = await import_playwright.chromium.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 || config.requireUsEgress) {
+        this.debugSnapshot.networkLocation = await this.captureBrowserNetworkLocation();
+      }
+      if (config.requireUsEgress) {
+        const country = this.debugSnapshot.networkLocation?.country ?? null;
+        if (!isUsCountry(country)) {
+          throw new CaptchaError(`Non-US egress (${country ?? "unknown"}) \u2014 retrying with a fresh session`);
+        }
+      }
+      return;
+    }
+    const launchOpts = {
+      headless: config.headless,
+      proxy: config.proxy ? { server: config.proxy } : void 0,
+      ...config.browserExecutablePath ? { executablePath: config.browserExecutablePath } : {},
+      ...config.ignoreDefaultArgs ? { ignoreDefaultArgs: config.ignoreDefaultArgs } : {}
+    };
+    const ctxOpts = rankCheckContextOptions(config);
+    if (config.profileDir) {
+      this.context = await import_playwright_extra.chromium.launchPersistentContext(config.profileDir, {
+        ...launchOpts,
+        ...ctxOpts
+      });
+      await this.installEsbuildHelperShims(this.context);
+      this.page = await this.context.newPage();
+    } else {
+      this.browser = await import_playwright_extra.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 (options?.tbs) params.set("tbs", options.tbs);
+    if (uule) params.set("uule", uule);
+    const url = "https://www.google.com/search?" + params.toString();
+    const navUrl = serpArrivalUrl(url);
+    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(navUrl, { 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}`);
+    }
+    if (await this.isSerpChallengeVisible()) {
+      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 };
+    }
+    if (await this.isSerpChallengeVisible()) {
+      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 isSerpChallengeVisible() {
+    if (!this.page) return false;
+    const captchaCount = await this.page.locator(PAASelectors.captchaMarker).count().catch(() => 0);
+    if (captchaCount > 0) return true;
+    const finalUrl = this.page.url();
+    if (/google\.[^/]+\/sorry\//i.test(finalUrl)) return true;
+    const bodySnippet = await this.page.evaluate(() => {
+      const text = (document.body?.innerText ?? "").replace(/\s+/g, " ").trim();
+      return text.slice(0, 1e3);
+    }).catch(() => "");
+    return /recaptcha|unusual traffic|are you a robot|about this page|detected unusual traffic/i.test(bodySnippet);
+  }
+  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) {
+    const arrivalBase = process.env.ADS_ARRIVAL_REDIRECT_BASE?.trim();
+    const navUrl = arrivalBase ? serpArrivalUrl(url, arrivalBase) : url;
+    try {
+      await this.page.goto(navUrl, { waitUntil: "domcontentloaded", timeout: 45e3 });
+      if (/google\.[^/]+\/search\?/i.test(url) && await this.isSerpChallengeVisible()) {
+        throw new CaptchaError(this.captchaMessage());
+      }
+    } catch (err) {
+      if (err instanceof CaptchaError) throw 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;
+      const openedAtMs = this.kernelOpenedAtMs;
+      const stealth = this.kernelStealth;
+      const proxyUsed = this.kernelProxyUsed;
+      const proxySource = this.kernelProxySource;
+      const proxyType = this.kernelProxyType;
+      const headlessSent = this.kernelHeadlessSent;
+      this.browser = null;
+      this.context = null;
+      this.page = null;
+      this.kernelSessionId = null;
+      this.kernelClient = null;
+      this.kernelOpenedAtMs = null;
+      this.kernelHeadlessSent = null;
+      this.kernelProxySource = null;
+      this.kernelProxyType = null;
+      if (client && sessionId && openedAtMs != null) {
+        void recordKernelSession({ kernelSessionId: sessionId, source: "browser_driver", stealth, headlessSent, proxyUsed, proxySource, proxyType, openedAtMs, closedAtMs: Date.now() });
+      }
+      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-query.ts
+function normalizedTerms(value) {
+  return value.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().split(/[^a-z0-9]+/).filter(Boolean);
+}
+function includesTermSequence(query, phrase) {
+  const queryTerms = normalizedTerms(query);
+  const phraseTerms = normalizedTerms(phrase);
+  if (phraseTerms.length === 0 || phraseTerms.length > queryTerms.length) return false;
+  return queryTerms.some((_, start) => phraseTerms.every((term, index) => queryTerms[start + index] === term));
+}
+function cityFromCanonicalLocation(location, fallback) {
+  return location.split(",", 1)[0]?.trim() || fallback.split(",", 1)[0]?.trim() || fallback.trim();
+}
+function buildLocalizedSerpQuery(query, location, canonicalLocation) {
+  const normalizedQuery = query.trim();
+  const requestedLocation = location?.trim();
+  if (!requestedLocation || !canonicalLocation) return normalizedQuery;
+  const city = cityFromCanonicalLocation(canonicalLocation, requestedLocation);
+  return includesTermSequence(normalizedQuery, city) ? normalizedQuery : `${normalizedQuery} ${requestedLocation}`;
+}
+
+// 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 decodeSerpText(text) {
+  try {
+    return decodeURIComponent(text);
+  } catch {
+  }
+  try {
+    return decodeURIComponent(text.replace(/%(?![0-9a-fA-F]{2})/g, "%25"));
+  } catch {
+    return text;
+  }
+}
+function scanText(candidates, text) {
+  const normalized = decodeSerpText(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 hasSubstantiveContent(text) {
+    if (!text) return false;
+    const normalized = text.replace(/\s+/g, " ").trim();
+    return normalized.length >= 16 && normalized.split(" ").filter(Boolean).length >= 2;
+  }
+  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 aimRootDetected = surface === "aim" && !!aimRoot;
+  const aimContainer = aimRoot?.closest(selectors.aim.wrapper) ?? aimRoot;
+  const rawAimText = aimRootDetected ? cleanText(aimContainer) : null;
+  const aimDetected = aimRootDetected && hasSubstantiveContent(rawAimText);
+  const aimText = aimDetected ? rawAimText : null;
+  const aimCitations = aimDetected ? extractCitations(aimContainer) : [];
+  const aiOverviewDetected = !!aioRoot && hasSubstantiveContent(aioText);
+  return {
+    surface,
+    aiOverview: {
+      detected: aiOverviewDetected,
+      text: aiOverviewDetected ? aioText : null,
+      citations: aiOverviewDetected ? aioCitations : [],
+      expanded: aiOverviewDetected ? aioExpanded : false,
+      fullyExpanded: aiOverviewDetected ? aioFullyExpanded : false,
+      sections: aiOverviewDetected ? 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;
+  completeness = {
+    paaWithoutAnswer: 0,
+    paaWithoutSource: 0,
+    paaAnswersRecovered: 0,
+    aioShareCaptured: null
+  };
+  aioShareUrlEarly = null;
+  collectedRows = [];
+  partialContext = null;
+  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) => {
+        let sourceTitle = pair.querySelector(selectors.sourceTitle)?.innerText?.trim() || void 0;
+        let sourceSite = pair.querySelector(selectors.sourceSite)?.innerText?.trim() || void 0;
+        let sourceCite = pair.querySelector(selectors.sourceCite)?.innerText?.trim() || void 0;
+        if (!sourceCite) {
+          const seenHrefs = /* @__PURE__ */ new Set();
+          const anchors = [];
+          for (const a of Array.from(pair.querySelectorAll("a[href]"))) {
+            const href = a.href;
+            if (!/^https?:\/\//.test(href) || seenHrefs.has(href)) continue;
+            let host = "";
+            try {
+              host = new URL(href).hostname;
+            } catch {
+              continue;
+            }
+            if (/(^|\.)google(usercontent)?\.[a-z.]+$/.test(host)) continue;
+            seenHrefs.add(href);
+            anchors.push({ text: (a.textContent || "").trim(), href, host });
+          }
+          const primary = anchors.find((x) => x.text.length > 2) ?? anchors[0];
+          if (primary) {
+            sourceTitle = sourceTitle || primary.text || void 0;
+            sourceSite = sourceSite || primary.host.replace(/^www\./, "");
+            sourceCite = primary.href;
+          }
+        }
+        return {
+          question: pair.getAttribute(selectors.itemDataQ) || pair.getAttribute(selectors.itemDataInitQ) || pair.querySelector(selectors.itemQuestionEl)?.innerText?.trim() || "",
+          answer: cleanText(pair.querySelector(selectors.answerContainer)) || void 0,
+          sourceTitle,
+          sourceSite,
+          sourceCite
+        };
+      });
+    }, 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()
+    };
+  }
+  getPartialResult() {
+    const ctx = this.partialContext;
+    if (!ctx || this.collectedRows.length === 0) return null;
+    const flat = [...this.collectedRows];
+    const stats = {
+      seed: ctx.seed,
+      totalQuestions: flat.length,
+      maxDepthReached: flat.reduce((m, r) => Math.max(m, r.depth), 0),
+      durationMs: Date.now() - ctx.startMs,
+      errorCount: 0
+    };
+    return {
+      seed: ctx.seed,
+      location: ctx.location,
+      extractedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      diagnostics: {
+        completionStatus: "paa_found",
+        problem: null,
+        completeness: { ...this.completeness },
+        warnings: [{
+          code: "paa_partial",
+          surface: "paa",
+          message: `Harvest stopped before finishing; returning the ${flat.length} question(s) collected up to that point.`,
+          retryable: true
+        }]
+      },
+      totalQuestions: flat.length,
+      whatPeopleSaying: [],
+      tree: this.buildTree(flat, ctx.seed),
+      flat,
+      videos: [],
+      forums: [],
+      organicResults: [],
+      localPack: [],
+      entityIds: {},
+      stats
+    };
+  }
+  async runBFS(page, options, signal) {
+    const seenKeys = /* @__PURE__ */ new Set();
+    const seenQs = /* @__PURE__ */ new Set();
+    const orderedQs = [];
+    this.collectedRows = [];
+    const results = this.collectedRows;
+    const abandonedNeverReclick = /* @__PURE__ */ new Set();
+    const clickedOnceEver = /* @__PURE__ */ new Set();
+    const itemArgs = {
+      sel: PAASelectors.item,
+      dataQ: PAASelectors.itemDataQ,
+      dataInitQ: PAASelectors.itemDataInitQ,
+      questionEl: PAASelectors.itemQuestionEl,
+      answerSel: PAASelectors.answerContainer,
+      expandedClass: PAASelectors.expandedClass,
+      clickTarget: PAASelectors.clickTarget
+    };
+    const readItemStates = () => page.evaluate(
+      ({ sel, dataQ, dataInitQ, questionEl, expandedClass, answerSel }) => {
+        const answerText = (root) => {
+          if (!root) return "";
+          let out = "";
+          const walk = (n) => {
+            for (const c of Array.from(n.childNodes)) {
+              if (c.nodeType === Node.TEXT_NODE) out += c.textContent || "";
+              else if (c.nodeType === Node.ELEMENT_NODE && c.tagName !== "STYLE" && c.tagName !== "SCRIPT") walk(c);
+            }
+          };
+          walk(root);
+          return out.replace(/\s+/g, " ").trim();
+        };
+        return Array.from(document.querySelectorAll(sel)).map((el) => ({
+          q: el.getAttribute(dataQ) || el.getAttribute(dataInitQ) || el.querySelector(questionEl)?.innerText?.trim() || "",
+          done: el.classList.contains(expandedClass) || answerText(el.querySelector(answerSel)).length > 30
+        })).filter((s) => s.q);
+      },
+      itemArgs
+    );
+    const expandOneItemSerially = async (q) => {
+      const clicked = await page.evaluate(
+        ({ sel, dataQ, dataInitQ, clickTarget, q: target }) => {
+          const item = Array.from(document.querySelectorAll(sel)).find((el) => (el.getAttribute(dataQ) || el.getAttribute(dataInitQ)) === target);
+          const btn = item?.querySelector(clickTarget);
+          if (!btn) return false;
+          btn.scrollIntoView({ block: "center" });
+          btn.click();
+          return true;
+        },
+        { ...itemArgs, q }
+      ).catch(() => false);
+      if (!clicked) return "failed";
+      try {
+        const outcome = await page.waitForFunction(
+          ({ sel, dataQ, dataInitQ, answerSel, q: target }) => {
+            const answerText = (root) => {
+              if (!root) return "";
+              let out = "";
+              const walk = (n) => {
+                for (const c of Array.from(n.childNodes)) {
+                  if (c.nodeType === Node.TEXT_NODE) out += c.textContent || "";
+                  else if (c.nodeType === Node.ELEMENT_NODE && c.tagName !== "STYLE" && c.tagName !== "SCRIPT") walk(c);
+                }
+              };
+              walk(root);
+              return out.replace(/\s+/g, " ").trim();
+            };
+            const item = Array.from(document.querySelectorAll(sel)).find((el) => (el.getAttribute(dataQ) || el.getAttribute(dataInitQ)) === target);
+            if (!item) return "gone";
+            const text = answerText(item.querySelector(answerSel));
+            if (/an error has occurred/i.test(text.slice(0, 80))) return "error";
+            if (text.length > 30) return "ok";
+            return false;
+          },
+          { ...itemArgs, q },
+          { timeout: 6500, polling: 200 }
+        );
+        return await outcome.jsonValue() === "ok" ? "ok" : "failed";
+      } catch {
+        return "failed";
+      }
+    };
+    let round = 0;
+    let growthWaits = 0;
+    while (true) {
+      if (options.softDeadlineMs && Date.now() >= options.softDeadlineMs) break;
+      this.throwIfAborted(signal);
+      const states = await readItemStates();
+      for (const s of states) {
+        if (!seenQs.has(s.q)) {
+          seenQs.add(s.q);
+          orderedQs.push(s.q);
+        }
+      }
+      const kept = new Set(orderedQs.slice(0, options.maxQuestions));
+      const clickable = states.filter((s) => kept.has(s.q) && !clickedOnceEver.has(s.q) && !abandonedNeverReclick.has(s.q));
+      const target = clickable.find((s) => !s.done) ?? (seenQs.size < options.maxQuestions ? clickable[0] : void 0);
+      if (!target) {
+        if (seenQs.size >= options.maxQuestions) break;
+        if (++growthWaits > 1) break;
+        const grew = await page.waitForFunction(
+          ({ sel, min }) => document.querySelectorAll(sel).length > min,
+          { sel: PAASelectors.item, min: states.length },
+          { timeout: 3e3 }
+        ).catch(() => null);
+        if (!grew) break;
+        continue;
+      }
+      growthWaits = 0;
+      this.reporter.onDepth(++round);
+      await this.throwIfCaptcha(page, "Google PAA expansion");
+      clickedOnceEver.add(target.q);
+      if (await expandOneItemSerially(target.q) === "failed") abandonedNeverReclick.add(target.q);
+    }
+    const itemMap = new Map((await this.extractVisibleItems(page)).map((i) => [i.question, i]));
+    await this.fillIncompleteItems(page, orderedQs, itemMap, options, abandonedNeverReclick);
+    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));
+      }
+    }
+    this.completeness.paaWithoutAnswer = results.filter((r) => !r.answer).length;
+    this.completeness.paaWithoutSource = results.filter((r) => !r.source_title && !r.source_site && !r.source_cite).length;
+    return results;
+  }
+  async fillIncompleteItems(page, orderedQs, itemMap, options, abandonedNeverReclick) {
+    const kept = new Set(orderedQs.slice(0, options.maxQuestions));
+    const missingBefore = new Set(
+      [...kept].filter((q) => !itemMap.get(q)?.answer && !abandonedNeverReclick?.has(q))
+    );
+    if (missingBefore.size === 0) return;
+    for (let round = 0; round < 2; round++) {
+      if (options.softDeadlineMs && Date.now() >= options.softDeadlineMs) break;
+      const stillMissing = [...missingBefore].filter((q) => !itemMap.get(q)?.answer);
+      if (stillMissing.length === 0) break;
+      const reExpanded = await this.reExpandCollapsedItems(page).catch(() => false);
+      await page.waitForTimeout(reExpanded ? 900 : 500);
+      let improved = false;
+      for (const item of await this.extractVisibleItems(page)) {
+        if (!kept.has(item.question)) continue;
+        const existing = itemMap.get(item.question);
+        if (!item.answer || existing?.answer) continue;
+        itemMap.set(item.question, {
+          ...item,
+          sourceTitle: item.sourceTitle ?? existing?.sourceTitle,
+          sourceSite: item.sourceSite ?? existing?.sourceSite,
+          sourceCite: item.sourceCite ?? existing?.sourceCite
+        });
+        improved = true;
+      }
+      if (!improved) break;
+    }
+    this.completeness.paaAnswersRecovered = [...missingBefore].filter((q) => itemMap.get(q)?.answer).length;
+  }
+  async reExpandCollapsedItems(page) {
+    const unexpandedSel = `${PAASelectors.item}:not(.${PAASelectors.expandedClass}) ${PAASelectors.clickTarget}`;
+    const count = await page.locator(unexpandedSel).count().catch(() => 0);
+    if (count === 0) return false;
+    for (let i = 0; i < count; i++) {
+      try {
+        const btn = page.locator(unexpandedSel).first();
+        await btn.scrollIntoViewIfNeeded();
+        await btn.click({ force: true });
+        await page.waitForTimeout(300);
+      } catch {
+      }
+    }
+    return true;
+  }
+  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, options) {
+    const surfaces = await page.evaluate(extractAISurfacesFromDocument, {
+      aio: AIOverviewSelectors,
+      aim: AIModeSelectors,
+      expandWaitMs: 1500
+    });
+    if (!surfaces.aiOverview.detected) {
+      this.completeness.aioShareCaptured = null;
+      return surfaces;
+    }
+    const shareUrl = this.aioShareUrlEarly ?? await this.captureAIOverviewShareUrl(page, options).catch(() => null);
+    this.completeness.aioShareCaptured = shareUrl !== null;
+    return {
+      ...surfaces,
+      aiOverview: { ...surfaces.aiOverview, shareUrl }
+    };
+  }
+  async captureAIOverviewShareUrl(page, options) {
+    if (options?.softDeadlineMs && Date.now() >= options.softDeadlineMs) return null;
+    const clicked = await page.evaluate(() => {
+      const heads = Array.from(document.querySelectorAll('h1,h2,h3,[role="heading"],div')).filter((h) => (h.textContent || "").trim() === "AI Overview");
+      for (const head of heads) {
+        let sec = head;
+        for (let up = 0; up < 8 && sec; up++) {
+          const btn = sec.querySelector('[aria-label="Share"]');
+          if (btn) {
+            btn.scrollIntoView({ block: "center" });
+            btn.click();
+            return true;
+          }
+          sec = sec.parentElement;
+        }
+      }
+      return false;
+    }).catch(() => false);
+    if (!clicked) return null;
+    let url = null;
+    try {
+      const found = await page.waitForFunction(() => {
+        const w = document.createTreeWalker(document.body, NodeFilter.SHOW_TEXT);
+        while (w.nextNode()) {
+          const m = (w.currentNode.textContent || "").match(/https:\/\/share\.google\/aimode\/\S+/);
+          if (m) return m[0];
+        }
+        return false;
+      }, void 0, { timeout: 4500, polling: 250 });
+      url = await found.jsonValue();
+    } catch {
+      url = null;
+    }
+    await page.keyboard.press("Escape").catch(() => {
+    });
+    return url;
+  }
+  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();
+    this.completeness = { paaWithoutAnswer: 0, paaWithoutSource: 0, paaAnswersRecovered: 0, aioShareCaptured: null };
+    this.aioShareUrlEarly = null;
+    this.collectedRows = [];
+    this.partialContext = { seed: options.query, location: options.location ?? null, startMs };
+    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,
+      keepDefaultProxy: options.keepDefaultProxy,
+      requireUsEgress: options.requireUsEgress,
+      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 executedQuery = buildLocalizedSerpQuery(options.query, options.location, canonicalLocation);
+      const executionOptions = executedQuery === options.query ? options : { ...options, query: executedQuery };
+      const { hasPaa } = await this.driver.navigateToSERP(
+        executionOptions.query,
+        uule,
+        options.gl,
+        options.hl,
+        {
+          ...options.serpOnly ? { num: 100 } : {},
+          ...recencyToTbs(options.recency) ? { tbs: recencyToTbs(options.recency) } : {},
+          debug: options.debug
+        }
+      );
+      this.throwIfAborted(signal);
+      const page = this.driver.getPage();
+      await this.throwIfCaptcha(page, "Google SERP");
+      this.aioShareUrlEarly = await this.captureAIOverviewShareUrl(page, options).catch(() => null);
+      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, options);
+        let locationEvidence2 = options.debug ? inferSerpLocationEvidence(canonicalLocation, organicResults2, localPack2) : void 0;
+        let allOrganic2 = organicResults2;
+        if ((options.pages ?? 1) >= 2) {
+          const p2params = new URLSearchParams({ q: executionOptions.query, gl: options.gl, hl: options.hl, pws: "0", start: "10" });
+          if (recencyToTbs(options.recency)) p2params.set("tbs", recencyToTbs(options.recency));
+          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: executionOptions.query,
+          totalQuestions: 0,
+          maxDepthReached: 0,
+          durationMs: Date.now() - startMs,
+          errorCount
+        };
+        this.reporter.onComplete(stats2);
+        return {
+          seed: executionOptions.query,
+          location: options.location ?? null,
+          extractedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          diagnostics: {
+            completionStatus: "serp_only",
+            problem: null,
+            completeness: { ...this.completeness },
+            ...options.debug ? { debug: this.buildHarvestDebugSnapshot(executionOptions, 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: executionOptions.query, gl: options.gl, hl: options.hl, pws: "0", start: "10" });
+          if (recencyToTbs(options.recency)) p2params.set("tbs", recencyToTbs(options.recency));
+          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, options);
+        const stats2 = {
+          seed: executionOptions.query,
+          totalQuestions: 0,
+          maxDepthReached: 0,
+          durationMs: Date.now() - startMs,
+          errorCount
+        };
+        this.reporter.onComplete(stats2);
+        return {
+          seed: executionOptions.query,
+          location: options.location ?? null,
+          extractedAt: (/* @__PURE__ */ new Date()).toISOString(),
+          diagnostics: {
+            completionStatus: "no_paa",
+            problem: null,
+            completeness: { ...this.completeness },
+            ...options.debug ? { debug: this.buildHarvestDebugSnapshot(executionOptions, 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, executionOptions, signal);
+      this.throwIfAborted(signal);
+      const aiSurfaces = await this.extractAISurfaces(page, options);
+      const shortVidsParams = new URLSearchParams({ q: executionOptions.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: executionOptions.query, gl: options.gl, hl: options.hl, pws: "0", start: "10" });
+        if (recencyToTbs(options.recency)) p2params.set("tbs", recencyToTbs(options.recency));
+        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, executionOptions.query);
+      const stats = {
+        seed: executionOptions.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: executionOptions.query,
+        location: options.location ?? null,
+        extractedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        diagnostics: {
+          completionStatus: "paa_found",
+          problem: null,
+          completeness: { ...this.completeness },
+          ...diagnosticWarnings.length > 0 ? { warnings: diagnosticWarnings } : {},
+          ...options.debug ? { debug: this.buildHarvestDebugSnapshot(executionOptions, 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
+var import_node_fs = require("fs");
+var import_node_path = __toESM(require("path"), 1);
+var import_papaparse = __toESM(require("papaparse"), 1);
+
+// src/output/memory-library-sink.ts
+async function postToMemoryLibrary(args) {
+  const url = process.env.MCP_MEMORY_INGEST_URL;
+  const key = process.env.MCP_MEMORY_KEY;
+  if (!url || !key) return;
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ data: { apiKey: key, title: args.title, content: args.content, source: args.source } })
+    });
+    const body = await res.json().catch(() => null);
+    if (!res.ok || body?.result?.error) {
+      console.warn("[memory-library-sink] ingest not accepted:", res.status, body?.result?.message ?? "");
+    }
+  } catch (err) {
+    console.warn("[memory-library-sink] ingest failed:", err?.message);
+  }
+}
+
+// src/output/OutputSerializer.ts
+var OutputSerializer = class {
+  async writeJSON(result, outputDir) {
+    await import_node_fs.promises.mkdir(outputDir, { recursive: true });
+    const slug = result.seed.toLowerCase().replace(/\W+/g, "-").slice(0, 40);
+    const filename = `${slug}-${Date.now()}.json`;
+    const fullPath = import_node_path.default.join(outputDir, filename);
+    await import_node_fs.promises.writeFile(fullPath, JSON.stringify(result, null, 2), "utf8");
+    await postToMemoryLibrary({ title: `${result.seed} scrape`, content: JSON.stringify(result), source: `mcp-scraper:${fullPath}` });
+    return fullPath;
+  }
+  async writeCSV(rows, outputDir) {
+    await import_node_fs.promises.mkdir(outputDir, { recursive: true });
+    const seedRaw = rows[0]?.seed_query ?? "paa";
+    const slug = seedRaw.toLowerCase().replace(/\W+/g, "-").slice(0, 40);
+    const csv = import_papaparse.default.unparse(rows, { header: true });
+    const filename = `${slug}-${Date.now()}.csv`;
+    const fullPath = import_node_path.default.join(outputDir, filename);
+    await import_node_fs.promises.writeFile(fullPath, csv, "utf8");
+    return fullPath;
+  }
+  async writeVideoCSV(videos, seed, outputDir) {
+    await import_node_fs.promises.mkdir(outputDir, { recursive: true });
+    const slug = seed.toLowerCase().replace(/\W+/g, "-").slice(0, 40);
+    const csv = import_papaparse.default.unparse(videos, { header: true });
+    const filename = `${slug}-videos-${Date.now()}.csv`;
+    const fullPath = import_node_path.default.join(outputDir, filename);
+    await import_node_fs.promises.writeFile(fullPath, csv, "utf8");
+    return fullPath;
+  }
+  async writeForumCSV(forums, seed, outputDir) {
+    await import_node_fs.promises.mkdir(outputDir, { recursive: true });
+    const slug = seed.toLowerCase().replace(/\W+/g, "-").slice(0, 40);
+    const csv = import_papaparse.default.unparse(forums, { header: true });
+    const filename = `${slug}-forums-${Date.now()}.csv`;
+    const fullPath = import_node_path.default.join(outputDir, filename);
+    await import_node_fs.promises.writeFile(fullPath, csv, "utf8");
+    return fullPath;
+  }
+  async writeAIOverviewCSV(citations, text, seed, outputDir) {
+    await import_node_fs.promises.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 = import_papaparse.default.unparse(rows, { header: true });
+    const filename = `${slug}-ai-overview-${Date.now()}.csv`;
+    const fullPath = import_node_path.default.join(outputDir, filename);
+    await import_node_fs.promises.writeFile(fullPath, csv, "utf8");
+    return fullPath;
+  }
+  async writeAIModeCSV(citations, text, seed, outputDir) {
+    await import_node_fs.promises.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 = import_papaparse.default.unparse(rows, { header: true });
+    const filename = `${slug}-ai-mode-${Date.now()}.csv`;
+    const fullPath = import_node_path.default.join(outputDir, filename);
+    await import_node_fs.promises.writeFile(fullPath, csv, "utf8");
+    return fullPath;
+  }
+  async writeWhatPeopleSayingCSV(cards, seed, outputDir) {
+    await import_node_fs.promises.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 = import_papaparse.default.unparse(rows, { header: true });
+    const filename = `${slug}-what-people-saying-${Date.now()}.csv`;
+    const fullPath = import_node_path.default.join(outputDir, filename);
+    await import_node_fs.promises.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
+var import_sdk3 = __toESM(require("@onkernel/sdk"), 1);
+
+// src/backup-proxy.ts
+var import_node_crypto3 = require("crypto");
+var import_sdk2 = __toESM(require("@onkernel/sdk"), 1);
+var BACKUP_PROXY_HOST = "pr.oxylabs.io";
+var BACKUP_PROXY_PORT = 7777;
+var BACKUP_STICKY_SESSION_MINUTES = 10;
+var BACKUP_LAST_RESORT_ATTEMPTS = 2;
+function backupProxyUsername() {
+  const value = process.env.OXYLABS_USERNAME?.trim();
+  return value || void 0;
+}
+function backupProxyPassword() {
+  const value = process.env.OXYLABS_PASSWORD?.trim();
+  return value || void 0;
+}
+function backupProxyCountry() {
+  const value = process.env.OXYLABS_COUNTRY?.trim();
+  return (value || "US").toUpperCase();
+}
+function backupProxyAvailable() {
+  return Boolean(backupProxyUsername() && backupProxyPassword());
+}
+function randomStickySessionId() {
+  let digits = "";
+  for (let i = 0; i < 10; i++) digits += String((0, import_node_crypto3.randomInt)(0, 10));
+  return digits;
+}
+function buildBackupUsername(opts = {}) {
+  const user = backupProxyUsername();
+  if (!user) return void 0;
+  const base = user.startsWith("customer-") ? user : `customer-${user}`;
+  const country = (opts.country?.trim() || backupProxyCountry()).toUpperCase();
+  const sticky = opts.sticky ? `-sessid-${randomStickySessionId()}-sesstime-${BACKUP_STICKY_SESSION_MINUTES}` : "";
+  return `${base}-cc-${country}${sticky}`;
+}
+function scrubBackupProxyText(message) {
+  return message.replace(/pr\.oxylabs\.io(:\d+)?/gi, "backup proxy").replace(/oxylabs/gi, "backup proxy");
+}
+function backupProxyName(attemptIndex) {
+  const stamp = `${Date.now()}-${attemptIndex ?? 0}-${Math.random().toString(36).slice(2, 8)}`;
+  return `mcp-backup-custom-${stamp}`;
+}
+async function createBackupProxyId(kernelApiKey, opts = {}) {
+  const username = buildBackupUsername({ sticky: opts.sticky });
+  const password = backupProxyPassword();
+  if (!username || !password) throw new Error("backup proxy pool is not configured");
+  const kernel = new import_sdk2.default({ apiKey: kernelApiKey });
+  try {
+    const created = await kernel.proxies.create({
+      type: "custom",
+      name: backupProxyName(opts.attemptIndex),
+      protocol: "http",
+      config: {
+        host: BACKUP_PROXY_HOST,
+        port: BACKUP_PROXY_PORT,
+        username,
+        password
+      }
+    });
+    if (!created.id) throw new Error("backup proxy creation did not return a proxy id");
+    return created.id;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(scrubBackupProxyText(message));
+  }
+}
+
+// src/kernel-proxy-resolver.ts
+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, disposable = false) {
+  const proxyType = source === "disabled" ? "none" : source === "configured_fallback" ? "configured" : source === "isp_created" ? "isp" : source === "backup_custom" ? "custom" : source === "location_created" || source === "location_reused" ? "residential" : "unknown";
+  return {
+    kernelProxyId: proxyId,
+    ...disposable && proxyId ? { disposableProxyId: proxyId } : {},
+    resolution: {
+      source,
+      proxyType,
+      proxyMode,
+      proxyIdPresent: Boolean(proxyId),
+      proxyIdSuffix: proxyIdSuffix2(proxyId),
+      target,
+      error,
+      disposable
+    }
+  };
+}
+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 freshProxyName(baseName, attemptIndex) {
+  const stamp = `${Date.now()}-${attemptIndex ?? 0}-${Math.random().toString(36).slice(2, 8)}`;
+  return `${baseName}-fresh-${stamp}`;
+}
+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 withProxyName(target, name) {
+  return {
+    ...target,
+    proxyName: name
+  };
+}
+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);
+}
+function freshTargetCandidates(target, explicitZip, attemptIndex) {
+  const out = [];
+  const zip = knownZipFor(target, explicitZip);
+  if (zip) {
+    const targetZip = zipTarget(target, zip);
+    out.push(withProxyName(targetZip, freshProxyName(targetZip.proxyName, attemptIndex)));
+  }
+  for (const city of target.cityCandidates) {
+    const cityTarget = {
+      ...target,
+      level: "city",
+      city,
+      proxyName: proxyName(target.country, target.state, city),
+      config: {
+        country: target.country,
+        state: target.state,
+        city
+      }
+    };
+    out.push(withProxyName(cityTarget, freshProxyName(cityTarget.proxyName, attemptIndex)));
+  }
+  const fallbackTarget = stateTarget(target);
+  out.push(withProxyName(fallbackTarget, freshProxyName(fallbackTarget.proxyName, attemptIndex)));
+  return out;
+}
+async function settleCreateExhaustion(options, target, createErrors) {
+  if (options.backupOnExhaustion && createErrors.length > 0 && options.kernelApiKey && backupProxyAvailable()) {
+    try {
+      const backupId = await createBackupProxyId(options.kernelApiKey, { attemptIndex: options.attemptIndex });
+      return resolution("backup_custom", options.proxyMode, backupId, target, null, true);
+    } catch (err) {
+      createErrors.push(`backup: ${scrubBackupProxyText(errorText2(err))}`);
+    }
+  }
+  return resolution("configured_fallback", options.proxyMode, options.configuredKernelProxyId, target, createErrors.join(" | "));
+}
+async function resolveBackupKernelProxyId(options) {
+  if (!options.kernelApiKey || !backupProxyAvailable()) return null;
+  try {
+    const backupId = await createBackupProxyId(options.kernelApiKey, { attemptIndex: options.attemptIndex });
+    return resolution("backup_custom", options.proxyMode, backupId, null, null, true);
+  } catch {
+    return null;
+  }
+}
+async function createFreshLocationProxy(kernel, options, target) {
+  const createErrors = [];
+  for (const candidate of freshTargetCandidates(target, options.proxyZip, options.attemptIndex)) {
+    try {
+      const created = await kernel.proxies.create({
+        type: "residential",
+        name: candidate.proxyName,
+        config: candidate.level === "zip" ? { country: candidate.country, zip: candidate.zip } : candidate.config
+      });
+      if (created.id) {
+        return resolution("location_created", options.proxyMode, created.id, candidate, null, true);
+      }
+      createErrors.push(`${candidate.proxyName}: Kernel did not return a proxy id`);
+    } catch (err) {
+      createErrors.push(`${candidate.proxyName}: ${errorText2(err)}`);
+    }
+  }
+  if (process.env.KERNEL_PROXY_TYPE !== "residential") {
+    const ispTarget = stateTarget(target);
+    try {
+      const created = await kernel.proxies.create({
+        type: "isp",
+        name: freshProxyName(`mcp-serp-isp-${ispTarget.country.toLowerCase()}-${(ispTarget.state ?? "").toLowerCase()}`, options.attemptIndex),
+        config: { country: ispTarget.country, ...ispTarget.state ? { state: ispTarget.state } : {} }
+      });
+      if (created.id) {
+        return resolution("isp_created", options.proxyMode, created.id, ispTarget, null, true);
+      }
+      createErrors.push("isp: Kernel did not return a proxy id");
+    } catch (err) {
+      createErrors.push(`isp: ${errorText2(err)}`);
+    }
+  }
+  return settleCreateExhaustion(options, target, createErrors);
+}
+async function deleteKernelProxyId(kernelApiKey, proxyId) {
+  if (!kernelApiKey || !proxyId) return;
+  const kernel = new import_sdk3.default({ apiKey: kernelApiKey });
+  await kernel.proxies.delete(proxyId);
+}
+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 import_sdk3.default({ apiKey: options.kernelApiKey });
+  try {
+    const attemptIndex = options.attemptIndex ?? 0;
+    if (options.fresh) {
+      return await createFreshLocationProxy(kernel, options, target);
+    }
+    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 settleCreateExhaustion(options, escalatedTarget, createErrors2);
+    }
+    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 settleCreateExhaustion(options, target, createErrors);
+  } catch (err) {
+    return resolution("configured_fallback", options.proxyMode, options.configuredKernelProxyId, target, errorText2(err));
+  }
+}
+
+// src/harvest.ts
+var MAX_ATTEMPTS = 3;
+var LOCATION_PROXY_MAX_ATTEMPTS = 5;
+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 LocationMismatchError) return "location_mismatch";
+  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);
+  if (looksLikeProxyTunnelFailure(message)) return "proxy_tunnel_failed";
+  if (looksLikeProxyUnavailable(message)) return "proxy_unavailable";
+  return /timeout|timed out|Timeout \d+ms exceeded|deadline/i.test(message) ? "timeout" : "error";
+}
+function classifyAttemptResult(result) {
+  if (result.diagnostics.degradedResult) return "degraded_result";
+  return result.diagnostics?.completionStatus ?? (result.totalQuestions > 0 ? "paa_found" : "no_paa");
+}
+function resultHasUsableContent(result) {
+  return result.flat.length > 0 || result.organicResults.length > 0 || result.localPack.length > 0 || result.videos.length > 0 || result.forums.length > 0 || result.whatPeopleSaying.length > 0 || result.aiOverview.detected || result.aiMode.detected;
+}
+function withResultQuality(result) {
+  const hasUsableContent = resultHasUsableContent(result);
+  const hasWarnings = (result.diagnostics.warnings?.length ?? 0) > 0;
+  const resultQuality = hasUsableContent ? hasWarnings ? "partial" : "complete" : "degraded";
+  const degradedResult = resultQuality === "degraded";
+  result.diagnostics = {
+    ...result.diagnostics,
+    resultQuality,
+    degradedResult,
+    degradationReasons: degradedResult ? ["empty_primary_serp"] : [],
+    retryRecommended: degradedResult
+  };
+  return result;
+}
+function degradedResultMessage(result) {
+  const reasons = result.diagnostics.degradationReasons ?? [];
+  if (reasons.includes("empty_primary_serp")) {
+    return "No usable primary SERP surface was captured; the result may be incomplete.";
+  }
+  return "The harvest result was marked degraded.";
+}
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+function maxAttemptsForProxyMode(proxyMode) {
+  return proxyMode === "location" ? LOCATION_PROXY_MAX_ATTEMPTS : MAX_ATTEMPTS;
+}
+function looksLikeProxyTunnelFailure(message) {
+  return /ERR_TUNNEL_CONNECTION_FAILED|ERR_PROXY_CONNECTION_FAILED|ERR_SOCKS_CONNECTION_FAILED|tunnel connection failed|proxy connection failed|transport error: proxy/i.test(message);
+}
+function looksLikeProxyUnavailable(message) {
+  return /proxy unavailable|proxy_unavailable|connection_test_failed|did not return a proxy id|configured fallback/i.test(message);
+}
+function retryableLocationProxyError(outcome) {
+  return outcome === "captcha" || outcome === "proxy_tunnel_failed" || outcome === "proxy_unavailable";
+}
+function locationMismatchMessage(result) {
+  const evidence = result.diagnostics.debug?.locationEvidence;
+  const expected = evidence?.expected?.canonicalLocation ?? result.location ?? "requested location";
+  const candidates = evidence?.candidates.slice(0, 3).map((candidate) => `${candidate.city}, ${candidate.regionCode}`).join("; ");
+  return candidates ? `Google returned results for ${candidates}, not ${expected}` : `Google returned results for a different location than ${expected}`;
+}
+function shouldRetryLocationMismatch(result, proxyMode) {
+  return proxyMode === "location" && result.diagnostics.debug?.locationEvidence?.status === "mismatch";
+}
+function stripInternalDebug(result, keepDebug) {
+  if (keepDebug || !result.diagnostics.debug) return result;
+  const diagnostics = { ...result.diagnostics };
+  delete diagnostics.debug;
+  return { ...result, diagnostics };
+}
+async function cleanupDisposableProxy(kernelApiKey, proxyId) {
+  if (!kernelApiKey || !proxyId) return;
+  try {
+    await deleteKernelProxyId(kernelApiKey, proxyId);
+    console.info(JSON.stringify({
+      event: "kernel_proxy_deleted",
+      proxy_id_suffix: proxyId.slice(-6)
+    }));
+  } catch (err) {
+    console.warn(JSON.stringify({
+      event: "kernel_proxy_delete_failed",
+      proxy_id_suffix: proxyId.slice(-6),
+      message: errorMessage(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();
+  }
+  if (error) {
+    const outcome = classifyAttemptError(error);
+    const budgetExhausted = outcome === "timeout" || outcome === "request_aborted";
+    let salvaged = null;
+    if (budgetExhausted) {
+      try {
+        salvaged = typeof extractor.getPartialResult === "function" ? extractor.getPartialResult() : null;
+      } catch {
+        salvaged = null;
+      }
+    }
+    if (salvaged) {
+      return { result: salvaged, error: null, cleanup, debug, salvagedFrom: error };
+    }
+    return { result: null, error, cleanup, debug };
+  }
+  return { 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 === "location" || requestedProxyMode === "none" || requestedProxyMode === "configured" ? requestedProxyMode : DEFAULT_PROXY_MODE;
+  const kernelApiKey = typeof raw.kernelApiKey === "string" ? raw.kernelApiKey.trim() : browserServiceApiKey();
+  const configuredKernelProxyId = typeof raw.kernelProxyId === "string" ? raw.kernelProxyId.trim() : browserServiceProxyId();
+  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 requestedDebug = typeof raw.debug === "boolean" ? raw.debug : false;
+  const needsLocationEvidence = proxyMode === "location" && Boolean(proxyOpts.location);
+  const requestedMaxAttempts = raw.maxAttempts;
+  const baseMaxAttempts = typeof requestedMaxAttempts === "number" && Number.isInteger(requestedMaxAttempts) && requestedMaxAttempts >= 1 ? requestedMaxAttempts : maxAttemptsForProxyMode(proxyMode) + 1;
+  const maxAttempts = baseMaxAttempts + (backupProxyAvailable() ? BACKUP_LAST_RESORT_ATTEMPTS : 0);
+  const softDeadlineMs = typeof raw.softDeadlineMs === "number" ? raw.softDeadlineMs : null;
+  const serializer = new OutputSerializer();
+  let lastError = null;
+  let effectiveProxyMode = proxyMode;
+  let proxyFailures = 0;
+  for (let i = 0; i < maxAttempts; i++) {
+    const attemptNumber = i + 1;
+    const startedAtMs = Date.now();
+    try {
+      if (signal?.aborted) throw abortReason(signal);
+      const isBackupAttempt = i >= baseMaxAttempts;
+      if (isBackupAttempt && softDeadlineMs !== null && Date.now() >= softDeadlineMs) break;
+      const resolution2 = isBackupAttempt ? await resolveBackupKernelProxyId({ kernelApiKey, proxyMode: effectiveProxyMode, attemptIndex: i }) : await resolveKernelProxyId({
+        ...proxyOpts,
+        proxyMode: effectiveProxyMode,
+        attemptIndex: i,
+        fresh: effectiveProxyMode === "location",
+        backupOnExhaustion: true
+      });
+      if (!resolution2) break;
+      const mergedAttempt = {
+        ...raw,
+        kernelApiKey,
+        kernelProxyId: resolution2.kernelProxyId,
+        kernelProxyResolution: resolution2.resolution,
+        proxyMode: effectiveProxyMode,
+        debug: requestedDebug || needsLocationEvidence
+      };
+      if (effectiveProxyMode === "none" && !isBackupAttempt) mergedAttempt.kernelProxyId = void 0;
+      const attemptOptions = HarvestOptionsSchema.parse(mergedAttempt);
+      await emitAttemptEvent(onAttemptEvent, {
+        type: "started",
+        attemptNumber,
+        maxAttempts,
+        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: maxAttempts,
+        query: attemptOptions.query,
+        location: attemptOptions.location ?? null,
+        max_questions: attemptOptions.maxQuestions
+      }));
+      const baseCtx = currentCostContext();
+      const attempt = baseCtx ? await runWithCostContext({ ...baseCtx, forceHeadful: true }, () => extractOnce(attemptOptions, signal)) : await extractOnce(attemptOptions, signal);
+      if (attempt.error) {
+        const err = attempt.error;
+        const outcome2 = classifyAttemptError(err);
+        if ((outcome2 === "captcha" || outcome2 === "proxy_tunnel_failed") && effectiveProxyMode === "location") {
+          proxyFailures++;
+          if (proxyFailures >= 2) effectiveProxyMode = "none";
+        }
+        const willRetry2 = i < maxAttempts - 1 && (outcome2 === "captcha" || proxyMode === "location" && retryableLocationProxyError(outcome2));
+        if (outcome2 === "captcha") {
+          console.warn(JSON.stringify({
+            event: "harvest_attempt_captcha",
+            attempt_number: attemptNumber,
+            max_attempts: maxAttempts,
+            message: errorMessage(err),
+            will_retry: willRetry2
+          }));
+        } else if (willRetry2) {
+          console.warn(JSON.stringify({
+            event: "harvest_attempt_proxy_retry",
+            attempt_number: attemptNumber,
+            max_attempts: maxAttempts,
+            outcome: outcome2,
+            message: errorMessage(err),
+            will_retry: willRetry2
+          }));
+        }
+        await emitAttemptEvent(onAttemptEvent, {
+          type: "finished",
+          attemptNumber,
+          maxAttempts,
+          outcome: outcome2,
+          kernelSessionId: attempt.cleanup.kernelSessionId,
+          questionCount: 0,
+          durationMs: Date.now() - startedAtMs,
+          error: errorMessage(err),
+          willRetry: willRetry2,
+          cleanup: attempt.cleanup,
+          debug: attempt.debug,
+          completedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        await cleanupDisposableProxy(kernelApiKey, resolution2.disposableProxyId);
+        lastError = err;
+        if (willRetry2) continue;
+        break;
+      }
+      const result = attempt.result;
+      if (!result) throw new Error("Harvest attempt completed without a result");
+      if (shouldRetryLocationMismatch(result, proxyMode)) {
+        const err = new LocationMismatchError(locationMismatchMessage(result));
+        const willRetry2 = i < maxAttempts - 1;
+        console.warn(JSON.stringify({
+          event: "harvest_attempt_location_mismatch",
+          attempt_number: attemptNumber,
+          max_attempts: maxAttempts,
+          message: err.message,
+          will_retry: willRetry2
+        }));
+        await emitAttemptEvent(onAttemptEvent, {
+          type: "finished",
+          attemptNumber,
+          maxAttempts,
+          outcome: "location_mismatch",
+          kernelSessionId: attempt.cleanup.kernelSessionId,
+          questionCount: result.totalQuestions,
+          durationMs: Date.now() - startedAtMs,
+          error: err.message,
+          willRetry: willRetry2,
+          cleanup: attempt.cleanup,
+          debug: attempt.debug,
+          completedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        await cleanupDisposableProxy(kernelApiKey, resolution2.disposableProxyId);
+        lastError = err;
+        if (willRetry2) continue;
+        break;
+      }
+      const finalResult = withResultQuality(stripInternalDebug(result, requestedDebug));
+      const outcome = classifyAttemptResult(finalResult);
+      const willRetry = outcome === "degraded_result" && i < maxAttempts - 1;
+      const resultError = outcome === "degraded_result" ? degradedResultMessage(finalResult) : null;
+      if (willRetry) {
+        console.warn(JSON.stringify({
+          event: "harvest_attempt_degraded_result",
+          attempt_number: attemptNumber,
+          max_attempts: maxAttempts,
+          degradation_reasons: finalResult.diagnostics.degradationReasons,
+          will_retry: true
+        }));
+      }
+      await emitAttemptEvent(onAttemptEvent, {
+        type: "finished",
+        attemptNumber,
+        maxAttempts,
+        outcome,
+        kernelSessionId: attempt.cleanup.kernelSessionId,
+        questionCount: finalResult.totalQuestions,
+        durationMs: Date.now() - startedAtMs,
+        error: resultError,
+        willRetry,
+        cleanup: attempt.cleanup,
+        debug: attempt.debug,
+        completedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      await cleanupDisposableProxy(kernelApiKey, resolution2.disposableProxyId);
+      if (willRetry) continue;
+      if (attemptOptions.format === "json" || attemptOptions.format === "both") {
+        await serializer.writeJSON(finalResult, attemptOptions.outputDir);
+      }
+      if (attemptOptions.format === "csv" || attemptOptions.format === "both") {
+        await Promise.all([
+          serializer.writeCSV(finalResult.flat, attemptOptions.outputDir),
+          finalResult.videos.length > 0 ? serializer.writeVideoCSV(finalResult.videos, finalResult.seed, attemptOptions.outputDir) : Promise.resolve(""),
+          finalResult.forums.length > 0 ? serializer.writeForumCSV(finalResult.forums, finalResult.seed, attemptOptions.outputDir) : Promise.resolve(""),
+          finalResult.aiOverview.detected ? serializer.writeAIOverviewCSV(finalResult.aiOverview.citations, finalResult.aiOverview.text, finalResult.seed, attemptOptions.outputDir) : Promise.resolve(""),
+          finalResult.aiMode.detected ? serializer.writeAIModeCSV(finalResult.aiMode.citations, finalResult.aiMode.text, finalResult.seed, attemptOptions.outputDir) : Promise.resolve(""),
+          finalResult.whatPeopleSaying.length > 0 ? serializer.writeWhatPeopleSayingCSV(finalResult.whatPeopleSaying, finalResult.seed, attemptOptions.outputDir) : Promise.resolve("")
+        ]);
+      }
+      return finalResult;
+    } catch (err) {
+      const outcome = classifyAttemptError(err);
+      if ((outcome === "captcha" || outcome === "proxy_tunnel_failed") && effectiveProxyMode === "location") {
+        proxyFailures++;
+        if (proxyFailures >= 2) effectiveProxyMode = "none";
+      }
+      const willRetry = i < maxAttempts - 1 && (outcome === "captcha" || proxyMode === "location" && retryableLocationProxyError(outcome));
+      if (outcome === "captcha") {
+        console.warn(JSON.stringify({
+          event: "harvest_attempt_captcha",
+          attempt_number: attemptNumber,
+          max_attempts: maxAttempts,
+          message: errorMessage(err),
+          will_retry: willRetry
+        }));
+      } else if (willRetry) {
+        console.warn(JSON.stringify({
+          event: "harvest_attempt_proxy_retry",
+          attempt_number: attemptNumber,
+          max_attempts: maxAttempts,
+          outcome,
+          message: errorMessage(err),
+          will_retry: willRetry
+        }));
+      }
+      await emitAttemptEvent(onAttemptEvent, {
+        type: "finished",
+        attemptNumber,
+        maxAttempts,
+        outcome,
+        kernelSessionId: null,
+        questionCount: 0,
+        durationMs: Date.now() - startedAtMs,
+        error: errorMessage(err),
+        willRetry,
+        cleanup: {
+          kernelSessionId: null,
+          kernelDeleteStarted: false,
+          kernelDeleteSucceeded: null,
+          kernelDeleteError: null,
+          browserCloseSucceeded: null,
+          browserCloseError: null
+        },
+        debug: null,
+        completedAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+      lastError = err;
+      if (willRetry) continue;
+      if (outcome === "captcha") break;
+      throw err;
+    }
+  }
+  if (lastError && !(lastError instanceof CaptchaError)) throw lastError;
+  console.warn(JSON.stringify({
+    event: "harvest_captcha_exhausted",
+    max_attempts: maxAttempts,
+    session_kind: kernelApiKey ? "kernel" : "local"
+  }));
+  throw new CaptchaError(sanitizeVendorName(`CAPTCHA on all ${maxAttempts} fresh sessions. Try again in a few minutes.`));
+}
+
+// src/cli.ts
+var program = new import_commander.Command();
+program.name("paa-harvest").description("Recursively extract Google People Also Ask questions").requiredOption("-q, --query <query>", "Seed query").option("-l, --location <location>", 'Location name (e.g. "austin" or "Austin,Texas,United States")').option("--gl <gl>", "Google country code", "us").option("--hl <hl>", "Google language code", "en").option("-d, --depth <depth>", "BFS depth (1-30)", "3").option("-m, --max-questions <n>", "Max questions to harvest", "100").option("-o, --output <dir>", "Output directory", "./paa-output").option("-f, --format <format>", "Output format: json, csv, or both", "both").option("--headless", "Run browser in headless mode", false).option("--profile <dir>", "Persistent browser profile directory").option("--proxy <url>", "Proxy server URL").option("--kernel-api-key <key>", "Browser service API key (or set BROWSER_SERVICE_API_KEY env var)").action(async (opts) => {
+  try {
+    const result = await harvest({
+      query: opts.query,
+      location: opts.location,
+      gl: opts.gl,
+      hl: opts.hl,
+      depth: parseInt(opts.depth, 10),
+      maxQuestions: parseInt(opts.maxQuestions, 10),
+      outputDir: opts.output,
+      format: opts.format,
+      headless: opts.headless,
+      profileDir: opts.profile,
+      proxy: opts.proxy,
+      kernelApiKey: opts.kernelApiKey ?? browserServiceApiKey()
+    });
+    console.log(JSON.stringify({ totalQuestions: result.totalQuestions, outputDir: result.stats.seed }));
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
+});
+async function runCli() {
+  await program.parseAsync();
+}
+
+// bin/paa-harvest.ts
+runCli();
+//# sourceMappingURL=paa-harvest.cjs.map