@open-mercato/web-research-serp 0.7.1-develop.7194.1.ab4fc81f82

package/.turbo/turbo-build.log

@@ -0,0 +1,2 @@
+[build:web-research-serp] found 4 entry points
+[build:web-research-serp] built successfully

package/build.mjs

@@ -0,0 +1,10 @@
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { buildPackage } from '../../scripts/build-package.mjs'
+
+const packageDir = dirname(fileURLToPath(import.meta.url))
+
+await buildPackage(packageDir, {
+  name: 'web-research-serp',
+  entryPoints: 'src/**/*.ts',
+})

package/dist/adapter.js

@@ -0,0 +1,102 @@
+import {
+  CONTRACT_VERSION,
+  READY,
+  blocked,
+  classifyPage,
+  defineAdapterModule,
+  notReady,
+  searchOk,
+  toOutcomeFailure
+} from "@open-mercato/web-research";
+import { z } from "zod";
+import { extractSerpResults } from "./extract.js";
+import { DEFAULT_ENGINES, SERP_PROFILES } from "./profiles.js";
+const serpOptionsSchema = z.object({
+  engines: z.array(z.enum(["ddg-html", "ddg-lite"])).min(1).optional(),
+  /** Bytes to read per SERP; enough for a full result page, small enough to bound cost. */
+  maxBytes: z.number().int().min(4096).max(4 * 1024 * 1024).optional()
+});
+const DEFAULT_MAX_BYTES = 1024 * 1024;
+const MIN_PLAUSIBLE_SERP_BYTES = 2048;
+const ACCEPT_HTML = ["text/html", "application/xhtml+xml"];
+function attempt(engine, request, context, maxBytes) {
+  const profile = SERP_PROFILES[engine];
+  return context.http.request(profile.buildUrl(request), {
+    maxBytes,
+    accept: ACCEPT_HTML,
+    signal: context.signal,
+    headers: { referer: profile.baseUrl }
+  }).then((response) => {
+    const results = extractSerpResults(response.body, profile.selector, profile.baseUrl, request.limit);
+    if (results.length > 0) return searchOk(results);
+    const verdict = classifyPage({
+      status: response.status,
+      contentType: response.contentType,
+      html: response.body,
+      text: ""
+    });
+    if (verdict.verdict === "blocked") {
+      return blocked(`${profile.label} served a challenge page (${verdict.reason ?? "unknown"})`);
+    }
+    if (response.body.length > MIN_PLAUSIBLE_SERP_BYTES) {
+      return blocked(
+        `${profile.label} returned a page we could not parse (${response.body.length} bytes, 0 results) - selectors may be stale`
+      );
+    }
+    return { status: "empty" };
+  }).catch((error) => toOutcomeFailure(error));
+}
+function createSerpAdapter(options) {
+  const engines = options.engines ?? DEFAULT_ENGINES;
+  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+  return {
+    id: "serp-html",
+    kind: "serp",
+    capabilities: {
+      search: true,
+      fetch: false,
+      snippets: true,
+      content: false,
+      freshness: true,
+      siteFilter: true,
+      cost: "free"
+    },
+    /** `free` — no health check to pay for. */
+    probeCost: "free",
+    readiness: () => engines.length > 0 ? READY : notReady("no search engines are enabled"),
+    async search(request, context) {
+      let lastFailure = null;
+      for (const engine of engines) {
+        if (context.signal.aborted) break;
+        context.report("started", `querying ${SERP_PROFILES[engine].label}`);
+        const outcome = await attempt(engine, request, context, maxBytes);
+        if (outcome.status === "ok") {
+          const results = outcome.results;
+          context.report("ok", `${SERP_PROFILES[engine].label} returned ${results.length} result(s)`, {
+            resultCount: results.length
+          });
+          return outcome;
+        }
+        lastFailure = outcome;
+        context.report(
+          outcome.status === "empty" ? "empty" : "blocked",
+          outcome.status === "empty" ? `${SERP_PROFILES[engine].label} had no results` : outcome.reason
+        );
+      }
+      return lastFailure ?? { status: "empty" };
+    }
+  };
+}
+const serpAdapterModule = defineAdapterModule({
+  id: "serp-html",
+  kind: "serp",
+  contractVersion: CONTRACT_VERSION,
+  optionsSchema: serpOptionsSchema,
+  createAdapter: createSerpAdapter
+});
+export {
+  createSerpAdapter,
+  serpAdapterModule,
+  serpOptionsSchema
+};
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/adapter.ts"],
+  "sourcesContent": ["import {\n  CONTRACT_VERSION,\n  READY,\n  blocked,\n  classifyPage,\n  defineAdapterModule,\n  notReady,\n  searchOk,\n  toOutcomeFailure,\n  type AdapterContext,\n  type RawResult,\n  type SearchAdapter,\n  type SearchOutcome,\n  type SearchRequest,\n} from '@open-mercato/web-research'\nimport { z } from 'zod'\nimport { extractSerpResults } from './extract'\nimport { DEFAULT_ENGINES, SERP_PROFILES, type SerpEngineId } from './profiles'\n\nexport const serpOptionsSchema = z.object({\n  engines: z.array(z.enum(['ddg-html', 'ddg-lite'])).min(1).optional(),\n  /** Bytes to read per SERP; enough for a full result page, small enough to bound cost. */\n  maxBytes: z.number().int().min(4096).max(4 * 1024 * 1024).optional(),\n})\n\nexport type SerpOptions = z.infer<typeof serpOptionsSchema>\n\nconst DEFAULT_MAX_BYTES = 1024 * 1024\n/** Below this a 200 response is a challenge or an error page, not a result page. */\nconst MIN_PLAUSIBLE_SERP_BYTES = 2_048\n\nconst ACCEPT_HTML = ['text/html', 'application/xhtml+xml']\n\nfunction attempt(\n  engine: SerpEngineId,\n  request: SearchRequest,\n  context: AdapterContext,\n  maxBytes: number,\n): Promise<SearchOutcome> {\n  const profile = SERP_PROFILES[engine]\n  return context.http\n    .request(profile.buildUrl(request), {\n      maxBytes,\n      accept: ACCEPT_HTML,\n      signal: context.signal,\n      headers: { referer: profile.baseUrl },\n    })\n    .then((response): SearchOutcome => {\n      const results = extractSerpResults(response.body, profile.selector, profile.baseUrl, request.limit)\n      if (results.length > 0) return searchOk(results)\n\n      const verdict = classifyPage({\n        status: response.status,\n        contentType: response.contentType,\n        html: response.body,\n        text: '',\n      })\n      if (verdict.verdict === 'blocked') {\n        return blocked(`${profile.label} served a challenge page (${verdict.reason ?? 'unknown'})`)\n      }\n      // A substantial page that yields nothing means our selectors no longer match\n      // the engine's markup. Reporting `blocked` rather than `empty` is deliberate:\n      // it escalates to the browser tier and shows up as a fault instead of\n      // masquerading as a legitimate \"no results\".\n      if (response.body.length > MIN_PLAUSIBLE_SERP_BYTES) {\n        return blocked(\n          `${profile.label} returned a page we could not parse (${response.body.length} bytes, 0 results) - selectors may be stale`,\n        )\n      }\n      return { status: 'empty' }\n    })\n    .catch((error: unknown) => toOutcomeFailure(error))\n}\n\nexport function createSerpAdapter(options: SerpOptions): SearchAdapter {\n  const engines = options.engines ?? DEFAULT_ENGINES\n  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES\n\n  return {\n    id: 'serp-html',\n    kind: 'serp',\n    capabilities: {\n      search: true,\n      fetch: false,\n      snippets: true,\n      content: false,\n      freshness: true,\n      siteFilter: true,\n      cost: 'free',\n    },\n    /** `free` \u2014 no health check to pay for. */\n    probeCost: 'free' as const,\n    readiness: () => (engines.length > 0 ? READY : notReady('no search engines are enabled')),\n    async search(request, context) {\n      let lastFailure: SearchOutcome | null = null\n\n      for (const engine of engines) {\n        if (context.signal.aborted) break\n        context.report('started', `querying ${SERP_PROFILES[engine].label}`)\n        const outcome = await attempt(engine, request, context, maxBytes)\n        if (outcome.status === 'ok') {\n          const results: readonly RawResult[] = outcome.results\n          context.report('ok', `${SERP_PROFILES[engine].label} returned ${results.length} result(s)`, {\n            resultCount: results.length,\n          })\n          return outcome\n        }\n        lastFailure = outcome\n        context.report(\n          outcome.status === 'empty' ? 'empty' : 'blocked',\n          outcome.status === 'empty' ? `${SERP_PROFILES[engine].label} had no results` : outcome.reason,\n        )\n      }\n\n      return lastFailure ?? { status: 'empty' }\n    },\n  }\n}\n\nexport const serpAdapterModule = defineAdapterModule({\n  id: 'serp-html',\n  kind: 'serp',\n  contractVersion: CONTRACT_VERSION,\n  optionsSchema: serpOptionsSchema,\n  createAdapter: createSerpAdapter,\n})\n"],
+  "mappings": "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",
+  "names": []
+}

package/dist/extract.js

@@ -0,0 +1,90 @@
+import { canonicalizeUrl, tokenizeHtml } from "@open-mercato/web-research";
+function hasClass(attributes, wanted) {
+  const raw = attributes.get("class");
+  if (!raw) return false;
+  return raw.split(/\s+/).includes(wanted);
+}
+function extractSerpResults(html, selector, baseUrl, limit) {
+  const drafts = [];
+  let linkDepth = 0;
+  let pendingHref = null;
+  let pendingTitle = "";
+  let snippetDepth = 0;
+  let snippetTag = null;
+  let pendingSnippet = "";
+  const finishLink = () => {
+    if (pendingHref === null) return;
+    const title = pendingTitle.replace(/\s+/g, " ").trim();
+    let resolved;
+    try {
+      resolved = new URL(pendingHref, baseUrl).toString();
+    } catch {
+      pendingHref = null;
+      pendingTitle = "";
+      return;
+    }
+    const canonical = canonicalizeUrl(resolved);
+    pendingHref = null;
+    pendingTitle = "";
+    if (canonical === null) return;
+    drafts.push({ url: canonical.url, title, snippet: null });
+  };
+  for (const token of tokenizeHtml(html)) {
+    if (drafts.length >= limit && linkDepth === 0 && snippetDepth === 0) break;
+    if (token.kind === "open") {
+      if (linkDepth > 0) {
+        if (token.name === "a") linkDepth += 1;
+        continue;
+      }
+      if (snippetDepth > 0) {
+        if (token.name === snippetTag) snippetDepth += 1;
+        continue;
+      }
+      if (token.name === "a" && hasClass(token.attributes, selector.linkClass)) {
+        const href = token.attributes.get("href");
+        if (href) {
+          pendingHref = href;
+          pendingTitle = "";
+          linkDepth = 1;
+        }
+        continue;
+      }
+      if (selector.snippetClass && hasClass(token.attributes, selector.snippetClass)) {
+        snippetDepth = 1;
+        snippetTag = token.name;
+        pendingSnippet = "";
+      }
+      continue;
+    }
+    if (token.kind === "close") {
+      if (linkDepth > 0) {
+        if (token.name === "a") {
+          linkDepth -= 1;
+          if (linkDepth === 0) finishLink();
+        }
+        continue;
+      }
+      if (snippetDepth > 0 && token.name === snippetTag) {
+        snippetDepth -= 1;
+        if (snippetDepth === 0) {
+          const snippet = pendingSnippet.replace(/\s+/g, " ").trim();
+          const target = drafts[drafts.length - 1];
+          if (target && target.snippet === null && snippet.length > 0) target.snippet = snippet;
+          pendingSnippet = "";
+        }
+      }
+      continue;
+    }
+    if (linkDepth > 0) pendingTitle += token.value;
+    else if (snippetDepth > 0) pendingSnippet += token.value;
+  }
+  return drafts.slice(0, limit).map((draft) => ({
+    url: draft.url,
+    title: draft.title.length > 0 ? draft.title : draft.url,
+    snippet: draft.snippet
+  }));
+}
+export {
+  extractSerpResults
+};
+//# sourceMappingURL=extract.js.map

package/dist/extract.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/extract.ts"],
+  "sourcesContent": ["import { canonicalizeUrl, tokenizeHtml, type RawResult } from '@open-mercato/web-research'\n\nexport type SerpSelector = {\n  /** Class carried by each result's primary anchor. */\n  readonly linkClass: string\n  /** Class carried by each result's snippet element. */\n  readonly snippetClass?: string\n}\n\nfunction hasClass(attributes: ReadonlyMap<string, string>, wanted: string): boolean {\n  const raw = attributes.get('class')\n  if (!raw) return false\n  return raw.split(/\\s+/).includes(wanted)\n}\n\ntype Draft = {\n  url: string\n  title: string\n  snippet: string | null\n}\n\n/**\n * Pulls results out of a search engine's HTML.\n *\n * Runs over the shared tokenizer rather than regex: SERP markup is deeply nested\n * and attribute-heavy, which is exactly where a lazy-quantifier regex either\n * mismatches or stalls.\n */\nexport function extractSerpResults(\n  html: string,\n  selector: SerpSelector,\n  baseUrl: string,\n  limit: number,\n): RawResult[] {\n  const drafts: Draft[] = []\n  let linkDepth = 0\n  let pendingHref: string | null = null\n  let pendingTitle = ''\n  let snippetDepth = 0\n  let snippetTag: string | null = null\n  let pendingSnippet = ''\n\n  const finishLink = (): void => {\n    if (pendingHref === null) return\n    const title = pendingTitle.replace(/\\s+/g, ' ').trim()\n    let resolved: string\n    try {\n      resolved = new URL(pendingHref, baseUrl).toString()\n    } catch {\n      pendingHref = null\n      pendingTitle = ''\n      return\n    }\n    // Engines wrap outbound links in their own redirector; canonicalizeUrl\n    // unwraps the known ones and rejects anything that is not http(s).\n    const canonical = canonicalizeUrl(resolved)\n    pendingHref = null\n    pendingTitle = ''\n    if (canonical === null) return\n    drafts.push({ url: canonical.url, title, snippet: null })\n  }\n\n  for (const token of tokenizeHtml(html)) {\n    if (drafts.length >= limit && linkDepth === 0 && snippetDepth === 0) break\n\n    if (token.kind === 'open') {\n      if (linkDepth > 0) {\n        if (token.name === 'a') linkDepth += 1\n        continue\n      }\n      if (snippetDepth > 0) {\n        if (token.name === snippetTag) snippetDepth += 1\n        continue\n      }\n      if (token.name === 'a' && hasClass(token.attributes, selector.linkClass)) {\n        const href = token.attributes.get('href')\n        if (href) {\n          pendingHref = href\n          pendingTitle = ''\n          linkDepth = 1\n        }\n        continue\n      }\n      if (selector.snippetClass && hasClass(token.attributes, selector.snippetClass)) {\n        snippetDepth = 1\n        snippetTag = token.name\n        pendingSnippet = ''\n      }\n      continue\n    }\n\n    if (token.kind === 'close') {\n      // Only the capturing element's own close ends a capture. Decrementing on\n      // any close tag would truncate at the first nested `<b>`/`<span>`, which\n      // real SERP markup is full of.\n      if (linkDepth > 0) {\n        if (token.name === 'a') {\n          linkDepth -= 1\n          if (linkDepth === 0) finishLink()\n        }\n        continue\n      }\n      if (snippetDepth > 0 && token.name === snippetTag) {\n        snippetDepth -= 1\n        if (snippetDepth === 0) {\n          const snippet = pendingSnippet.replace(/\\s+/g, ' ').trim()\n          const target = drafts[drafts.length - 1]\n          if (target && target.snippet === null && snippet.length > 0) target.snippet = snippet\n          pendingSnippet = ''\n        }\n      }\n      continue\n    }\n\n    if (linkDepth > 0) pendingTitle += token.value\n    else if (snippetDepth > 0) pendingSnippet += token.value\n  }\n\n  return drafts.slice(0, limit).map((draft) => ({\n    url: draft.url,\n    title: draft.title.length > 0 ? draft.title : draft.url,\n    snippet: draft.snippet,\n  }))\n}\n"],
+  "mappings": "AAAA,SAAS,iBAAiB,oBAAoC;AAS9D,SAAS,SAAS,YAAyC,QAAyB;AAClF,QAAM,MAAM,WAAW,IAAI,OAAO;AAClC,MAAI,CAAC,IAAK,QAAO;AACjB,SAAO,IAAI,MAAM,KAAK,EAAE,SAAS,MAAM;AACzC;AAeO,SAAS,mBACd,MACA,UACA,SACA,OACa;AACb,QAAM,SAAkB,CAAC;AACzB,MAAI,YAAY;AAChB,MAAI,cAA6B;AACjC,MAAI,eAAe;AACnB,MAAI,eAAe;AACnB,MAAI,aAA4B;AAChC,MAAI,iBAAiB;AAErB,QAAM,aAAa,MAAY;AAC7B,QAAI,gBAAgB,KAAM;AAC1B,UAAM,QAAQ,aAAa,QAAQ,QAAQ,GAAG,EAAE,KAAK;AACrD,QAAI;AACJ,QAAI;AACF,iBAAW,IAAI,IAAI,aAAa,OAAO,EAAE,SAAS;AAAA,IACpD,QAAQ;AACN,oBAAc;AACd,qBAAe;AACf;AAAA,IACF;AAGA,UAAM,YAAY,gBAAgB,QAAQ;AAC1C,kBAAc;AACd,mBAAe;AACf,QAAI,cAAc,KAAM;AACxB,WAAO,KAAK,EAAE,KAAK,UAAU,KAAK,OAAO,SAAS,KAAK,CAAC;AAAA,EAC1D;AAEA,aAAW,SAAS,aAAa,IAAI,GAAG;AACtC,QAAI,OAAO,UAAU,SAAS,cAAc,KAAK,iBAAiB,EAAG;AAErE,QAAI,MAAM,SAAS,QAAQ;AACzB,UAAI,YAAY,GAAG;AACjB,YAAI,MAAM,SAAS,IAAK,cAAa;AACrC;AAAA,MACF;AACA,UAAI,eAAe,GAAG;AACpB,YAAI,MAAM,SAAS,WAAY,iBAAgB;AAC/C;AAAA,MACF;AACA,UAAI,MAAM,SAAS,OAAO,SAAS,MAAM,YAAY,SAAS,SAAS,GAAG;AACxE,cAAM,OAAO,MAAM,WAAW,IAAI,MAAM;AACxC,YAAI,MAAM;AACR,wBAAc;AACd,yBAAe;AACf,sBAAY;AAAA,QACd;AACA;AAAA,MACF;AACA,UAAI,SAAS,gBAAgB,SAAS,MAAM,YAAY,SAAS,YAAY,GAAG;AAC9E,uBAAe;AACf,qBAAa,MAAM;AACnB,yBAAiB;AAAA,MACnB;AACA;AAAA,IACF;AAEA,QAAI,MAAM,SAAS,SAAS;AAI1B,UAAI,YAAY,GAAG;AACjB,YAAI,MAAM,SAAS,KAAK;AACtB,uBAAa;AACb,cAAI,cAAc,EAAG,YAAW;AAAA,QAClC;AACA;AAAA,MACF;AACA,UAAI,eAAe,KAAK,MAAM,SAAS,YAAY;AACjD,wBAAgB;AAChB,YAAI,iBAAiB,GAAG;AACtB,gBAAM,UAAU,eAAe,QAAQ,QAAQ,GAAG,EAAE,KAAK;AACzD,gBAAM,SAAS,OAAO,OAAO,SAAS,CAAC;AACvC,cAAI,UAAU,OAAO,YAAY,QAAQ,QAAQ,SAAS,EAAG,QAAO,UAAU;AAC9E,2BAAiB;AAAA,QACnB;AAAA,MACF;AACA;AAAA,IACF;AAEA,QAAI,YAAY,EAAG,iBAAgB,MAAM;AAAA,aAChC,eAAe,EAAG,mBAAkB,MAAM;AAAA,EACrD;AAEA,SAAO,OAAO,MAAM,GAAG,KAAK,EAAE,IAAI,CAAC,WAAW;AAAA,IAC5C,KAAK,MAAM;AAAA,IACX,OAAO,MAAM,MAAM,SAAS,IAAI,MAAM,QAAQ,MAAM;AAAA,IACpD,SAAS,MAAM;AAAA,EACjB,EAAE;AACJ;",
+  "names": []
+}

package/dist/index.js

@@ -0,0 +1,14 @@
+import { createSerpAdapter, serpAdapterModule, serpOptionsSchema } from "./adapter.js";
+import { extractSerpResults } from "./extract.js";
+import { DEFAULT_ENGINES, SERP_PROFILES } from "./profiles.js";
+import { serpAdapterModule as serpAdapterModule2 } from "./adapter.js";
+export {
+  DEFAULT_ENGINES,
+  SERP_PROFILES,
+  createSerpAdapter,
+  serpAdapterModule2 as default,
+  extractSerpResults,
+  serpAdapterModule,
+  serpOptionsSchema
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": ["export { createSerpAdapter, serpAdapterModule, serpOptionsSchema, type SerpOptions } from './adapter'\nexport { extractSerpResults, type SerpSelector } from './extract'\nexport { DEFAULT_ENGINES, SERP_PROFILES, type SerpEngineId, type SerpEngineProfile } from './profiles'\n\nexport { serpAdapterModule as default } from './adapter'\n"],
+  "mappings": "AAAA,SAAS,mBAAmB,mBAAmB,yBAA2C;AAC1F,SAAS,0BAA6C;AACtD,SAAS,iBAAiB,qBAAgE;AAE1F,SAA8B,qBAArBA,0BAAoC;",
+  "names": ["serpAdapterModule"]
+}

package/dist/profiles.js

@@ -0,0 +1,49 @@
+function buildQuery(request) {
+  const parts = [request.query];
+  if (request.site) parts.push(`site:${request.site}`);
+  return parts.join(" ");
+}
+function freshnessParam(request) {
+  switch (request.freshness) {
+    case "day":
+      return "d";
+    case "week":
+      return "w";
+    case "month":
+      return "m";
+    case "year":
+      return "y";
+    default:
+      return null;
+  }
+}
+function duckDuckGoUrl(base, request) {
+  const url = new URL(base);
+  url.searchParams.set("q", buildQuery(request));
+  const freshness = freshnessParam(request);
+  if (freshness) url.searchParams.set("df", freshness);
+  if (request.locale) url.searchParams.set("kl", request.locale.toLowerCase().replace("_", "-"));
+  return url.toString();
+}
+const SERP_PROFILES = {
+  "ddg-html": {
+    id: "ddg-html",
+    label: "DuckDuckGo (HTML)",
+    baseUrl: "https://html.duckduckgo.com/html/",
+    selector: { linkClass: "result__a", snippetClass: "result__snippet" },
+    buildUrl: (request) => duckDuckGoUrl("https://html.duckduckgo.com/html/", request)
+  },
+  "ddg-lite": {
+    id: "ddg-lite",
+    label: "DuckDuckGo (Lite)",
+    baseUrl: "https://lite.duckduckgo.com/lite/",
+    selector: { linkClass: "result-link", snippetClass: "result-snippet" },
+    buildUrl: (request) => duckDuckGoUrl("https://lite.duckduckgo.com/lite/", request)
+  }
+};
+const DEFAULT_ENGINES = ["ddg-html", "ddg-lite"];
+export {
+  DEFAULT_ENGINES,
+  SERP_PROFILES
+};
+//# sourceMappingURL=profiles.js.map

package/dist/profiles.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/profiles.ts"],
+  "sourcesContent": ["import type { SearchRequest } from '@open-mercato/web-research'\nimport type { SerpSelector } from './extract'\n\nexport type SerpEngineId = 'ddg-html' | 'ddg-lite'\n\nexport type SerpEngineProfile = {\n  readonly id: SerpEngineId\n  readonly label: string\n  readonly baseUrl: string\n  readonly selector: SerpSelector\n  buildUrl(request: SearchRequest): string\n}\n\nfunction buildQuery(request: SearchRequest): string {\n  const parts = [request.query]\n  if (request.site) parts.push(`site:${request.site}`)\n  return parts.join(' ')\n}\n\n/** DuckDuckGo maps a freshness window onto its `df` parameter. */\nfunction freshnessParam(request: SearchRequest): string | null {\n  switch (request.freshness) {\n    case 'day':\n      return 'd'\n    case 'week':\n      return 'w'\n    case 'month':\n      return 'm'\n    case 'year':\n      return 'y'\n    default:\n      return null\n  }\n}\n\nfunction duckDuckGoUrl(base: string, request: SearchRequest): string {\n  const url = new URL(base)\n  url.searchParams.set('q', buildQuery(request))\n  const freshness = freshnessParam(request)\n  if (freshness) url.searchParams.set('df', freshness)\n  if (request.locale) url.searchParams.set('kl', request.locale.toLowerCase().replace('_', '-'))\n  return url.toString()\n}\n\n/**\n * Engine markup is a contract nobody signed \u2014 it changes without notice. Keeping\n * profiles as data means a break is a one-line selector edit plus a fixture, and\n * the adapter's zero-results self-check turns a silent parser rot into a visible\n * `blocked` diagnostic rather than an empty answer.\n */\nexport const SERP_PROFILES: Readonly<Record<SerpEngineId, SerpEngineProfile>> = {\n  'ddg-html': {\n    id: 'ddg-html',\n    label: 'DuckDuckGo (HTML)',\n    baseUrl: 'https://html.duckduckgo.com/html/',\n    selector: { linkClass: 'result__a', snippetClass: 'result__snippet' },\n    buildUrl: (request) => duckDuckGoUrl('https://html.duckduckgo.com/html/', request),\n  },\n  'ddg-lite': {\n    id: 'ddg-lite',\n    label: 'DuckDuckGo (Lite)',\n    baseUrl: 'https://lite.duckduckgo.com/lite/',\n    selector: { linkClass: 'result-link', snippetClass: 'result-snippet' },\n    buildUrl: (request) => duckDuckGoUrl('https://lite.duckduckgo.com/lite/', request),\n  },\n}\n\nexport const DEFAULT_ENGINES: readonly SerpEngineId[] = ['ddg-html', 'ddg-lite']\n"],
+  "mappings": "AAaA,SAAS,WAAW,SAAgC;AAClD,QAAM,QAAQ,CAAC,QAAQ,KAAK;AAC5B,MAAI,QAAQ,KAAM,OAAM,KAAK,QAAQ,QAAQ,IAAI,EAAE;AACnD,SAAO,MAAM,KAAK,GAAG;AACvB;AAGA,SAAS,eAAe,SAAuC;AAC7D,UAAQ,QAAQ,WAAW;AAAA,IACzB,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT;AACE,aAAO;AAAA,EACX;AACF;AAEA,SAAS,cAAc,MAAc,SAAgC;AACnE,QAAM,MAAM,IAAI,IAAI,IAAI;AACxB,MAAI,aAAa,IAAI,KAAK,WAAW,OAAO,CAAC;AAC7C,QAAM,YAAY,eAAe,OAAO;AACxC,MAAI,UAAW,KAAI,aAAa,IAAI,MAAM,SAAS;AACnD,MAAI,QAAQ,OAAQ,KAAI,aAAa,IAAI,MAAM,QAAQ,OAAO,YAAY,EAAE,QAAQ,KAAK,GAAG,CAAC;AAC7F,SAAO,IAAI,SAAS;AACtB;AAQO,MAAM,gBAAmE;AAAA,EAC9E,YAAY;AAAA,IACV,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,SAAS;AAAA,IACT,UAAU,EAAE,WAAW,aAAa,cAAc,kBAAkB;AAAA,IACpE,UAAU,CAAC,YAAY,cAAc,qCAAqC,OAAO;AAAA,EACnF;AAAA,EACA,YAAY;AAAA,IACV,IAAI;AAAA,IACJ,OAAO;AAAA,IACP,SAAS;AAAA,IACT,UAAU,EAAE,WAAW,eAAe,cAAc,iBAAiB;AAAA,IACrE,UAAU,CAAC,YAAY,cAAc,qCAAqC,OAAO;AAAA,EACnF;AACF;AAEO,MAAM,kBAA2C,CAAC,YAAY,UAAU;",
+  "names": []
+}

package/jest.config.cjs

@@ -0,0 +1,28 @@
+/** @type {import('jest').Config} */
+const base = require('../../jest.config.base.cjs')
+
+module.exports = {
+  ...base,
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  watchman: false,
+  rootDir: '.',
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],
+  moduleNameMapper: {
+    '^@open-mercato/web-research/(.*)$': '<rootDir>/../web-research/src/$1',
+    '^@open-mercato/web-research$': '<rootDir>/../web-research/src/index.ts',
+  },
+  transform: {
+    '^.+\\.(t|j)sx?$': [
+      'ts-jest',
+      {
+        tsconfig: {
+          rootDir: '.',
+          ignoreDeprecations: '6.0',
+        },
+      },
+    ],
+  },
+  testMatch: ['<rootDir>/src/**/__tests__/**/*.test.(ts|tsx)'],
+  passWithNoTests: true,
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@open-mercato/web-research-serp",
+  "version": "0.7.1-develop.7194.1.ab4fc81f82",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "openMercato": {
+    "webResearchAdapter": {
+      "id": "serp-html"
+    }
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "watch": "node watch.mjs",
+    "test": "jest --config jest.config.cjs",
+    "typecheck": "tsc --noEmit"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/index.js"
+    },
+    "./*.ts": {
+      "types": "./src/*.ts",
+      "default": "./dist/*.js"
+    },
+    "./*": {
+      "types": [
+        "./src/*.ts"
+      ],
+      "default": "./dist/*.js"
+    }
+  },
+  "peerDependencies": {
+    "@open-mercato/web-research": "^0.6.0"
+  },
+  "dependencies": {
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@open-mercato/web-research": "0.7.1-develop.7194.1.ab4fc81f82",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^26.0.1",
+    "esbuild": "^0.28.1",
+    "glob": "^13.0.6",
+    "jest": "^30.4.2",
+    "ts-jest": "^29.4.11",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/open-mercato/open-mercato",
+    "directory": "packages/web-research-serp"
+  },
+  "stableVersion": "0.7.0"
+}

package/src/__tests__/serp.test.ts

@@ -0,0 +1,154 @@
+import { createStubHttpClient, createTestContext, describeAdapterContract } from '@open-mercato/web-research/testing'
+import { createSerpAdapter, serpAdapterModule } from '../adapter'
+import { extractSerpResults } from '../extract'
+import { SERP_PROFILES } from '../profiles'
+
+const DDG_HTML = `
+<!DOCTYPE html>
+<html><body>
+  <div class="results">
+    <div class="result results_links">
+      <h2 class="result__title">
+        <a rel="nofollow" class="result__a" href="//duckduckgo.com/l/?uddg=https%3A%2F%2Fexample.com%2Fone&amp;rut=x">First &amp; best</a>
+      </h2>
+      <a class="result__snippet" href="//duckduckgo.com/l/?uddg=https%3A%2F%2Fexample.com%2Fone">Snippet <b>one</b> here.</a>
+    </div>
+    <div class="result results_links">
+      <h2 class="result__title">
+        <a rel="nofollow" class="result__a" href="https://other.org/two">Second result</a>
+      </h2>
+      <div class='result__snippet'>Snippet two.</div>
+    </div>
+    <div class="result results_links result--ad">
+      <a class="result__a" href="javascript:void(0)">Not a real link</a>
+    </div>
+  </div>
+</body></html>`
+
+const CHALLENGE_HTML = `<html><body><h1>Just a moment...</h1><div id="cf_chl_opt"></div>${'x'.repeat(3000)}</body></html>`
+
+describe('extractSerpResults', () => {
+  it('reads title, url and snippet, unwrapping the engine redirector', () => {
+    const results = extractSerpResults(DDG_HTML, SERP_PROFILES['ddg-html'].selector, 'https://html.duckduckgo.com/html/', 10)
+
+    expect(results).toEqual([
+      { url: 'https://example.com/one', title: 'First & best', snippet: 'Snippet one here.' },
+      { url: 'https://other.org/two', title: 'Second result', snippet: 'Snippet two.' },
+    ])
+  })
+
+  it('keeps text that spans nested inline markup', () => {
+    const html = `<a class="result__a" href="https://e.com/x">Deep <b>bold <i>and</i></b> tail</a>`
+    const results = extractSerpResults(html, SERP_PROFILES['ddg-html'].selector, 'https://e.com/', 10)
+    expect(results[0].title).toBe('Deep bold and tail')
+  })
+
+  it('drops entries whose href is not http(s)', () => {
+    const results = extractSerpResults(DDG_HTML, SERP_PROFILES['ddg-html'].selector, 'https://html.duckduckgo.com/html/', 10)
+    expect(results.map((result) => result.title)).not.toContain('Not a real link')
+  })
+
+  it('respects the requested limit', () => {
+    const results = extractSerpResults(DDG_HTML, SERP_PROFILES['ddg-html'].selector, 'https://html.duckduckgo.com/html/', 1)
+    expect(results).toHaveLength(1)
+  })
+
+  it('returns nothing when the markup does not match', () => {
+    expect(extractSerpResults('<html><body><p>nope</p></body></html>', SERP_PROFILES['ddg-html'].selector, 'https://x/', 10)).toEqual([])
+  })
+})
+
+describe('serp adapter', () => {
+  it('returns results from the first engine that answers', async () => {
+    const http = createStubHttpClient(() => ({ body: DDG_HTML }))
+    const adapter = createSerpAdapter({})
+
+    const outcome = await adapter.search({ query: 'test', limit: 10 }, createTestContext({ http }))
+
+    expect(outcome.status).toBe('ok')
+    expect(http.calls).toHaveLength(1)
+    expect(http.calls[0]).toContain('html.duckduckgo.com')
+  })
+
+  it('falls through to the next engine when the first is blocked', async () => {
+    const isDuckDuckGoHtmlHost = (candidateUrl: string) => {
+      try {
+        return new URL(candidateUrl).hostname === 'html.duckduckgo.com'
+      } catch {
+        return false
+      }
+    }
+
+    const http = createStubHttpClient((url) =>
+      isDuckDuckGoHtmlHost(url)
+        ? { body: CHALLENGE_HTML, status: 200 }
+        : { body: DDG_HTML.replace(/result__a/g, 'result-link').replace(/result__snippet/g, 'result-snippet') },
+    )
+    const adapter = createSerpAdapter({})
+
+    const outcome = await adapter.search({ query: 'test', limit: 10 }, createTestContext({ http }))
+
+    expect(outcome.status).toBe('ok')
+    expect(http.calls).toHaveLength(2)
+  })
+
+  it('reports a substantial unparseable page as blocked, not empty', async () => {
+    // Stale selectors must surface as a fault. Reporting `empty` would let the
+    // engine quietly return nothing forever after a markup change.
+    const http = createStubHttpClient(() => ({ body: `<html><body>${'<div>x</div>'.repeat(400)}</body></html>` }))
+    const adapter = createSerpAdapter({ engines: ['ddg-html'] })
+
+    const outcome = await adapter.search({ query: 'test', limit: 10 }, createTestContext({ http }))
+
+    expect(outcome.status).toBe('blocked')
+    if (outcome.status === 'blocked') expect(outcome.reason).toContain('selectors may be stale')
+  })
+
+  it('reports a tiny empty page as empty', async () => {
+    const http = createStubHttpClient(() => ({ body: '<html><body></body></html>' }))
+    const adapter = createSerpAdapter({ engines: ['ddg-html'] })
+
+    const outcome = await adapter.search({ query: 'test', limit: 10 }, createTestContext({ http }))
+
+    expect(outcome.status).toBe('empty')
+  })
+
+  it('passes site and freshness filters through to the engine URL', async () => {
+    const http = createStubHttpClient(() => ({ body: DDG_HTML }))
+    const adapter = createSerpAdapter({ engines: ['ddg-html'] })
+
+    await adapter.search(
+      { query: 'pricing', limit: 5, site: 'example.com', freshness: 'week', locale: 'en-US' },
+      createTestContext({ http }),
+    )
+
+    const requested = decodeURIComponent(http.calls[0])
+    expect(requested).toContain('site:example.com')
+    expect(requested).toContain('df=w')
+    expect(requested).toContain('kl=en-us')
+  })
+
+  it('stops early when the caller aborts', async () => {
+    const http = createStubHttpClient(() => ({ body: CHALLENGE_HTML }))
+    const controller = new AbortController()
+    controller.abort()
+    const adapter = createSerpAdapter({})
+
+    const outcome = await adapter.search(
+      { query: 'test', limit: 10 },
+      createTestContext({ http, signal: controller.signal }),
+    )
+
+    expect(outcome.status).toBe('empty')
+    expect(http.calls).toHaveLength(0)
+  })
+})
+
+describeAdapterContract(
+  serpAdapterModule,
+  {
+    configuredOptions: {},
+    context: () => createTestContext({ http: createStubHttpClient(() => ({ body: DDG_HTML })) }),
+  },
+  { describe, it, expect: expect as never },
+)

package/src/adapter.ts

@@ -0,0 +1,126 @@
+import {
+  CONTRACT_VERSION,
+  READY,
+  blocked,
+  classifyPage,
+  defineAdapterModule,
+  notReady,
+  searchOk,
+  toOutcomeFailure,
+  type AdapterContext,
+  type RawResult,
+  type SearchAdapter,
+  type SearchOutcome,
+  type SearchRequest,
+} from '@open-mercato/web-research'
+import { z } from 'zod'
+import { extractSerpResults } from './extract'
+import { DEFAULT_ENGINES, SERP_PROFILES, type SerpEngineId } from './profiles'
+
+export const serpOptionsSchema = z.object({
+  engines: z.array(z.enum(['ddg-html', 'ddg-lite'])).min(1).optional(),
+  /** Bytes to read per SERP; enough for a full result page, small enough to bound cost. */
+  maxBytes: z.number().int().min(4096).max(4 * 1024 * 1024).optional(),
+})
+
+export type SerpOptions = z.infer<typeof serpOptionsSchema>
+
+const DEFAULT_MAX_BYTES = 1024 * 1024
+/** Below this a 200 response is a challenge or an error page, not a result page. */
+const MIN_PLAUSIBLE_SERP_BYTES = 2_048
+
+const ACCEPT_HTML = ['text/html', 'application/xhtml+xml']
+
+function attempt(
+  engine: SerpEngineId,
+  request: SearchRequest,
+  context: AdapterContext,
+  maxBytes: number,
+): Promise<SearchOutcome> {
+  const profile = SERP_PROFILES[engine]
+  return context.http
+    .request(profile.buildUrl(request), {
+      maxBytes,
+      accept: ACCEPT_HTML,
+      signal: context.signal,
+      headers: { referer: profile.baseUrl },
+    })
+    .then((response): SearchOutcome => {
+      const results = extractSerpResults(response.body, profile.selector, profile.baseUrl, request.limit)
+      if (results.length > 0) return searchOk(results)
+
+      const verdict = classifyPage({
+        status: response.status,
+        contentType: response.contentType,
+        html: response.body,
+        text: '',
+      })
+      if (verdict.verdict === 'blocked') {
+        return blocked(`${profile.label} served a challenge page (${verdict.reason ?? 'unknown'})`)
+      }
+      // A substantial page that yields nothing means our selectors no longer match
+      // the engine's markup. Reporting `blocked` rather than `empty` is deliberate:
+      // it escalates to the browser tier and shows up as a fault instead of
+      // masquerading as a legitimate "no results".
+      if (response.body.length > MIN_PLAUSIBLE_SERP_BYTES) {
+        return blocked(
+          `${profile.label} returned a page we could not parse (${response.body.length} bytes, 0 results) - selectors may be stale`,
+        )
+      }
+      return { status: 'empty' }
+    })
+    .catch((error: unknown) => toOutcomeFailure(error))
+}
+
+export function createSerpAdapter(options: SerpOptions): SearchAdapter {
+  const engines = options.engines ?? DEFAULT_ENGINES
+  const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES
+
+  return {
+    id: 'serp-html',
+    kind: 'serp',
+    capabilities: {
+      search: true,
+      fetch: false,
+      snippets: true,
+      content: false,
+      freshness: true,
+      siteFilter: true,
+      cost: 'free',
+    },
+    /** `free` — no health check to pay for. */
+    probeCost: 'free' as const,
+    readiness: () => (engines.length > 0 ? READY : notReady('no search engines are enabled')),
+    async search(request, context) {
+      let lastFailure: SearchOutcome | null = null
+
+      for (const engine of engines) {
+        if (context.signal.aborted) break
+        context.report('started', `querying ${SERP_PROFILES[engine].label}`)
+        const outcome = await attempt(engine, request, context, maxBytes)
+        if (outcome.status === 'ok') {
+          const results: readonly RawResult[] = outcome.results
+          context.report('ok', `${SERP_PROFILES[engine].label} returned ${results.length} result(s)`, {
+            resultCount: results.length,
+          })
+          return outcome
+        }
+        lastFailure = outcome
+        context.report(
+          outcome.status === 'empty' ? 'empty' : 'blocked',
+          outcome.status === 'empty' ? `${SERP_PROFILES[engine].label} had no results` : outcome.reason,
+        )
+      }
+
+      return lastFailure ?? { status: 'empty' }
+    },
+  }
+}
+
+export const serpAdapterModule = defineAdapterModule({
+  id: 'serp-html',
+  kind: 'serp',
+  contractVersion: CONTRACT_VERSION,
+  optionsSchema: serpOptionsSchema,
+  createAdapter: createSerpAdapter,
+})

package/src/extract.ts

@@ -0,0 +1,124 @@
+import { canonicalizeUrl, tokenizeHtml, type RawResult } from '@open-mercato/web-research'
+
+export type SerpSelector = {
+  /** Class carried by each result's primary anchor. */
+  readonly linkClass: string
+  /** Class carried by each result's snippet element. */
+  readonly snippetClass?: string
+}
+
+function hasClass(attributes: ReadonlyMap<string, string>, wanted: string): boolean {
+  const raw = attributes.get('class')
+  if (!raw) return false
+  return raw.split(/\s+/).includes(wanted)
+}
+
+type Draft = {
+  url: string
+  title: string
+  snippet: string | null
+}
+
+/**
+ * Pulls results out of a search engine's HTML.
+ *
+ * Runs over the shared tokenizer rather than regex: SERP markup is deeply nested
+ * and attribute-heavy, which is exactly where a lazy-quantifier regex either
+ * mismatches or stalls.
+ */
+export function extractSerpResults(
+  html: string,
+  selector: SerpSelector,
+  baseUrl: string,
+  limit: number,
+): RawResult[] {
+  const drafts: Draft[] = []
+  let linkDepth = 0
+  let pendingHref: string | null = null
+  let pendingTitle = ''
+  let snippetDepth = 0
+  let snippetTag: string | null = null
+  let pendingSnippet = ''
+
+  const finishLink = (): void => {
+    if (pendingHref === null) return
+    const title = pendingTitle.replace(/\s+/g, ' ').trim()
+    let resolved: string
+    try {
+      resolved = new URL(pendingHref, baseUrl).toString()
+    } catch {
+      pendingHref = null
+      pendingTitle = ''
+      return
+    }
+    // Engines wrap outbound links in their own redirector; canonicalizeUrl
+    // unwraps the known ones and rejects anything that is not http(s).
+    const canonical = canonicalizeUrl(resolved)
+    pendingHref = null
+    pendingTitle = ''
+    if (canonical === null) return
+    drafts.push({ url: canonical.url, title, snippet: null })
+  }
+
+  for (const token of tokenizeHtml(html)) {
+    if (drafts.length >= limit && linkDepth === 0 && snippetDepth === 0) break
+
+    if (token.kind === 'open') {
+      if (linkDepth > 0) {
+        if (token.name === 'a') linkDepth += 1
+        continue
+      }
+      if (snippetDepth > 0) {
+        if (token.name === snippetTag) snippetDepth += 1
+        continue
+      }
+      if (token.name === 'a' && hasClass(token.attributes, selector.linkClass)) {
+        const href = token.attributes.get('href')
+        if (href) {
+          pendingHref = href
+          pendingTitle = ''
+          linkDepth = 1
+        }
+        continue
+      }
+      if (selector.snippetClass && hasClass(token.attributes, selector.snippetClass)) {
+        snippetDepth = 1
+        snippetTag = token.name
+        pendingSnippet = ''
+      }
+      continue
+    }
+
+    if (token.kind === 'close') {
+      // Only the capturing element's own close ends a capture. Decrementing on
+      // any close tag would truncate at the first nested `<b>`/`<span>`, which
+      // real SERP markup is full of.
+      if (linkDepth > 0) {
+        if (token.name === 'a') {
+          linkDepth -= 1
+          if (linkDepth === 0) finishLink()
+        }
+        continue
+      }
+      if (snippetDepth > 0 && token.name === snippetTag) {
+        snippetDepth -= 1
+        if (snippetDepth === 0) {
+          const snippet = pendingSnippet.replace(/\s+/g, ' ').trim()
+          const target = drafts[drafts.length - 1]
+          if (target && target.snippet === null && snippet.length > 0) target.snippet = snippet
+          pendingSnippet = ''
+        }
+      }
+      continue
+    }
+
+    if (linkDepth > 0) pendingTitle += token.value
+    else if (snippetDepth > 0) pendingSnippet += token.value
+  }
+
+  return drafts.slice(0, limit).map((draft) => ({
+    url: draft.url,
+    title: draft.title.length > 0 ? draft.title : draft.url,
+    snippet: draft.snippet,
+  }))
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+export { createSerpAdapter, serpAdapterModule, serpOptionsSchema, type SerpOptions } from './adapter'
+export { extractSerpResults, type SerpSelector } from './extract'
+export { DEFAULT_ENGINES, SERP_PROFILES, type SerpEngineId, type SerpEngineProfile } from './profiles'
+
+export { serpAdapterModule as default } from './adapter'

package/src/profiles.ts

@@ -0,0 +1,68 @@
+import type { SearchRequest } from '@open-mercato/web-research'
+import type { SerpSelector } from './extract'
+
+export type SerpEngineId = 'ddg-html' | 'ddg-lite'
+
+export type SerpEngineProfile = {
+  readonly id: SerpEngineId
+  readonly label: string
+  readonly baseUrl: string
+  readonly selector: SerpSelector
+  buildUrl(request: SearchRequest): string
+}
+
+function buildQuery(request: SearchRequest): string {
+  const parts = [request.query]
+  if (request.site) parts.push(`site:${request.site}`)
+  return parts.join(' ')
+}
+
+/** DuckDuckGo maps a freshness window onto its `df` parameter. */
+function freshnessParam(request: SearchRequest): string | null {
+  switch (request.freshness) {
+    case 'day':
+      return 'd'
+    case 'week':
+      return 'w'
+    case 'month':
+      return 'm'
+    case 'year':
+      return 'y'
+    default:
+      return null
+  }
+}
+
+function duckDuckGoUrl(base: string, request: SearchRequest): string {
+  const url = new URL(base)
+  url.searchParams.set('q', buildQuery(request))
+  const freshness = freshnessParam(request)
+  if (freshness) url.searchParams.set('df', freshness)
+  if (request.locale) url.searchParams.set('kl', request.locale.toLowerCase().replace('_', '-'))
+  return url.toString()
+}
+
+/**
+ * Engine markup is a contract nobody signed — it changes without notice. Keeping
+ * profiles as data means a break is a one-line selector edit plus a fixture, and
+ * the adapter's zero-results self-check turns a silent parser rot into a visible
+ * `blocked` diagnostic rather than an empty answer.
+ */
+export const SERP_PROFILES: Readonly<Record<SerpEngineId, SerpEngineProfile>> = {
+  'ddg-html': {
+    id: 'ddg-html',
+    label: 'DuckDuckGo (HTML)',
+    baseUrl: 'https://html.duckduckgo.com/html/',
+    selector: { linkClass: 'result__a', snippetClass: 'result__snippet' },
+    buildUrl: (request) => duckDuckGoUrl('https://html.duckduckgo.com/html/', request),
+  },
+  'ddg-lite': {
+    id: 'ddg-lite',
+    label: 'DuckDuckGo (Lite)',
+    baseUrl: 'https://lite.duckduckgo.com/lite/',
+    selector: { linkClass: 'result-link', snippetClass: 'result-snippet' },
+    buildUrl: (request) => duckDuckGoUrl('https://lite.duckduckgo.com/lite/', request),
+  },
+}
+
+export const DEFAULT_ENGINES: readonly SerpEngineId[] = ['ddg-html', 'ddg-lite']

package/tsconfig.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/__tests__/**"]
+}

package/watch.mjs

@@ -0,0 +1,7 @@
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { watch } from '../../scripts/watch.mjs'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+watch(__dirname)