search-web-api 1.0.13

package/src/autocomplete/autocomplete-search-engine-backends.ts

@@ -0,0 +1,231 @@
+/**
+ * Autocomplete Search Engine Backends — Provides query-completion suggestions
+ * by querying the native autocomplete APIs of eight major search engines: Baidu,
+ * Brave, DuckDuckGo, Google, Qwant, Startpage, Wikipedia, and Yandex. Each
+ * backend normalises locale codes to the format expected by its API and returns
+ * a plain string array. `searchAutocompleteMulti` fans out to multiple backends
+ * in parallel and merges the deduplicated results.
+ */
+
+import grab from "grab-url";
+import { parseHTML } from "linkedom";
+
+type AutocompleteFunction = (query: string, locale?: string) => Promise<string[]>;
+
+async function getSuggestions(url: string, options: any = {}): Promise<any> {
+  try {
+    const response = await grab(url, {
+      timeout: 3,
+      responseType: options.responseType || "json",
+      ...options,
+    });
+
+    if (typeof response === "object" && "data" in response) return response.data;
+    return response;
+  } catch (error) {
+    console.error("Autocomplete error:", error);
+    return null;
+  }
+}
+
+/**
+ * Baidu autocomplete — returns suggestions from Baidu's `sugrec` endpoint.
+ */
+export async function baidu(query: string, _locale?: string): Promise<string[]> {
+  const params = new URLSearchParams({ ie: "utf-8", json: "1", prod: "pc", wd: query });
+  const data = await getSuggestions(`https://www.baidu.com/sugrec?${params}`);
+  const results: string[] = [];
+  if (data && data.g) for (const item of data.g) results.push(item.q);
+  return results;
+}
+
+/**
+ * Brave autocomplete — returns suggestions from Brave Search's suggest API.
+ */
+export async function brave(query: string, _locale?: string): Promise<string[]> {
+  const params = new URLSearchParams({ q: query });
+  const data = await getSuggestions(`https://search.brave.com/api/suggest?${params}`, {
+    headers: { Cookie: "country=all" },
+  });
+  if (data && Array.isArray(data) && data.length > 1) return data[1];
+  return [];
+}
+
+/**
+ * DuckDuckGo autocomplete — maps `locale` (e.g. `en-US`) to a `kl` region code.
+ */
+export async function duckduckgo(query: string, locale: string = "en-US"): Promise<string[]> {
+  const region = locale.toLowerCase().split("-").reverse().join("-");
+  const params = new URLSearchParams({ q: query, kl: region });
+  const data = await getSuggestions(`https://duckduckgo.com/ac/?type=list&${params}`);
+  if (data && Array.isArray(data) && data.length > 1) return data[1];
+  return [];
+}
+
+/**
+ * Google autocomplete — routes to the locale-appropriate Google subdomain and
+ * strips HTML entities from suggestion text using linkedom.
+ */
+export async function google(query: string, locale: string = "en"): Promise<string[]> {
+  const subdomainMap: { [key: string]: string } = {
+    de: "google.de", fr: "google.fr", es: "google.es", it: "google.it",
+    nl: "google.nl", pt: "google.pt", ru: "google.ru",
+    ja: "google.co.jp", zh: "google.com.hk", ko: "google.co.kr",
+  };
+
+  const lang = locale.split("-")[0];
+  const subdomain = subdomainMap[lang] || "google.com";
+  const params = new URLSearchParams({ q: query, client: "gws-wiz", hl: lang });
+  const response = await getSuggestions(
+    `https://${subdomain}/complete/search?${params}`,
+    { responseType: "text" },
+  );
+
+  const results: string[] = [];
+  if (response) {
+    try {
+      const jsonStart = response.indexOf("[");
+      const jsonEnd = response.lastIndexOf("]") + 1;
+      if (jsonStart >= 0 && jsonEnd > jsonStart) {
+        const data = JSON.parse(response.substring(jsonStart, jsonEnd));
+        if (data[0]) {
+          for (const item of data[0]) {
+            const { document } = parseHTML(item[0]);
+            const text = document.body?.textContent?.trim();
+            if (text) results.push(text);
+          }
+        }
+      }
+    } catch {
+      // Ignore parse errors
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Qwant autocomplete — uses Qwant's v3 suggest API with locale normalisation.
+ */
+export async function qwant(query: string, locale: string = "en_US"): Promise<string[]> {
+  const params = new URLSearchParams({
+    q: query,
+    locale: locale.replace("-", "_"),
+    version: "2",
+  });
+  const data = await getSuggestions(`https://api.qwant.com/v3/suggest?${params}`);
+  const results: string[] = [];
+  if (data && data.status === "success" && data.data?.items)
+    for (const item of data.data.items) results.push(item.value);
+  return results;
+}
+
+/**
+ * Startpage autocomplete — maps locale to the `lui` language parameter.
+ */
+export async function startpage(query: string, locale: string = "en"): Promise<string[]> {
+  const langMap: { [key: string]: string } = {
+    da: "dansk", de: "deutsch", en: "english", es: "espanol",
+    fr: "francais", nb: "norsk", nl: "nederlands",
+    pl: "polski", pt: "portugues", sv: "svenska",
+  };
+
+  const lui = langMap[locale.split("-")[0]] || "english";
+  const params = new URLSearchParams({
+    q: query, format: "opensearch", segment: "startpage.defaultffx", lui,
+  });
+
+  const data = await getSuggestions(`https://www.startpage.com/suggestions?${params}`, {
+    headers: { "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36" },
+  });
+
+  if (data && Array.isArray(data) && data.length >= 2 && Array.isArray(data[1])) return data[1];
+  return [];
+}
+
+/**
+ * Wikipedia autocomplete — uses the OpenSearch API on the locale-appropriate Wikipedia subdomain.
+ */
+export async function wikipedia(query: string, locale: string = "en"): Promise<string[]> {
+  const langMap: { [key: string]: string } = {
+    en: "en.wikipedia.org", de: "de.wikipedia.org", fr: "fr.wikipedia.org",
+    es: "es.wikipedia.org", it: "it.wikipedia.org", nl: "nl.wikipedia.org",
+    pt: "pt.wikipedia.org", ru: "ru.wikipedia.org", ja: "ja.wikipedia.org",
+    zh: "zh.wikipedia.org", ar: "ar.wikipedia.org", ko: "ko.wikipedia.org",
+  };
+
+  const netloc = langMap[locale.split("-")[0]] || "en.wikipedia.org";
+  const params = new URLSearchParams({
+    action: "opensearch", format: "json", formatversion: "2",
+    search: query, namespace: "0", limit: "10",
+  });
+
+  const data = await getSuggestions(`https://${netloc}/w/api.php?${params}`);
+  if (data && Array.isArray(data) && data.length > 1) return data[1];
+  return [];
+}
+
+/**
+ * Yandex autocomplete — uses Yandex's `suggest-ff.cgi` endpoint.
+ */
+export async function yandex(query: string, _locale?: string): Promise<string[]> {
+  const params = new URLSearchParams({ part: query });
+  const data = await getSuggestions(
+    `https://suggest.yandex.com/suggest-ff.cgi?${params}`,
+  );
+  if (data && Array.isArray(data) && data.length > 1) return data[1];
+  return [];
+}
+
+/** Map of all available autocomplete backend names to their functions. */
+export const backends: { [key: string]: AutocompleteFunction } = {
+  baidu, brave, duckduckgo, google, qwant, startpage, wikipedia, yandex,
+};
+
+/**
+ * Get autocomplete suggestions from a specific backend.
+ *
+ * @param backendName - Name of the backend (e.g. `"google"`, `"duckduckgo"`).
+ * @param query - Partial search query to complete.
+ * @param locale - BCP-47 locale code such as `"en-US"` or `"de-DE"`.
+ */
+export async function searchAutocomplete(
+  backendName: string,
+  query: string,
+  locale: string = "en-US",
+): Promise<string[]> {
+  const backend = backends[backendName];
+  if (!backend) {
+    console.warn(`Autocomplete backend '${backendName}' not found`);
+    return [];
+  }
+  try {
+    return await backend(query, locale);
+  } catch (error) {
+    console.error(`Autocomplete error for ${backendName}:`, error);
+    return [];
+  }
+}
+
+/**
+ * Fan out to multiple autocomplete backends in parallel and return a
+ * deduplicated union of all suggestions.
+ *
+ * @param backendNames - Array of backend names to query.
+ * @param query - Partial search query.
+ * @param locale - BCP-47 locale code.
+ */
+export async function searchAutocompleteMulti(
+  backendNames: string[],
+  query: string,
+  locale: string = "en-US",
+): Promise<string[]> {
+  const results = await Promise.all(
+    backendNames.map((name) => searchAutocomplete(name, query, locale)),
+  );
+
+  const merged = new Set<string>();
+  for (const result of results) for (const suggestion of result) merged.add(suggestion);
+
+  return Array.from(merged);
+}

package/src/category-registry.ts

@@ -0,0 +1,6 @@
+/**
+ * Category Registry — Re-exports the CategoryRegistry class, the CATEGORIES
+ * config map (with per-category scoring weights), and the global
+ * `categoryRegistry` singleton from the canonical registry module.
+ */
+export * from "./registry/search-engine-category-registry.js";

package/src/config/search-engine-constants.ts

@@ -0,0 +1,216 @@
+/**
+ * Search Engine Constants — Static configuration used across the search API:
+ * the list of valid result categories, allowed recency filter values, a curated
+ * list of public SearXNG instance domains, and a per-category directory of
+ * engine names with short descriptions for documentation and UI rendering.
+ */
+
+export const CATEGORY_LIST = [
+  "general",
+  "news",
+  "videos",
+  "images",
+  "science",
+  "it",
+  "files",
+  "social+media",
+  "map",
+  "music",
+];
+
+export const RECENCY_ALLOWED_LIST = ["day", "week", "month", "year"];
+
+export const SEARX_DOMAINS = [
+  "baresearch.org",
+  "copp.gg",
+  "darmarit.org",
+  "etsi.me",
+  "fairsuch.net",
+  "nogoo.me",
+  "northboot.xyz",
+  "nyc1.sx.ggtyler.dev",
+  "ooglester.com",
+  "opnxng.com",
+  "paulgo.io",
+  "priv.au",
+  "s.trung.fun",
+  "search.blitzw.in",
+  "search.charliewhiskey.net",
+  "search.citw.lgbt",
+  "search.darkness.services",
+  "search.datura.network",
+  "search.dotone.nl",
+  "search.gcomm.ch",
+  "search.hbubli.cc",
+  "search.im-in.space",
+  "search.incogniweb.net",
+  "search.inetol.net",
+  "search.leptons.xyz",
+  "search.nadeko.net",
+  "search.ngn.tf",
+  "search.ononoki.org",
+  "search.privacyredirect.com",
+  "search.sapti.me",
+  "search.rowie.at",
+  "search.projectsegfau.lt",
+  "search.tommy-tran.com",
+  "searx.aleteoryx.me",
+  "searx.ankha.ac",
+  "searx.be",
+  "searx.colbster937.dev",
+  "searx.daetalytica.io",
+  "searx.dresden.network",
+  "searx.foss.family",
+  "searx.hu",
+  "searx.juancord.xyz",
+  "searx.lunar.icu",
+  "searx.mxchange.org",
+  "searx.namejeff.xyz",
+  "searx.oakleycord.dev",
+  "searx.ro",
+  "searx.sev.monster",
+  "searx.thefloatinglab.world",
+  "searx.tiekoetter.com",
+  "searx.tuxcloud.net",
+  "searx.work",
+  "searx.zhenyapav.com",
+  "searxng.hweeren.com",
+  "searxng.online",
+  "searxng.shreven.org",
+  "searxng.site",
+  "skyrimhater.com",
+  "sx.ca.zorby.top",
+  "sx.catgirl.cloud",
+  "sx.thatxtreme.dev",
+  "sx.zorby.top",
+  "xo.wtf",
+];
+
+/** Directory of engine names and short descriptions grouped by category. */
+export const engines: Record<string, [string, string][]> = {
+  general: [
+    ["google", "The world's most popular web search engine."],
+    ["bing", "Microsoft's web search engine for the general web."],
+    ["brave", "Privacy-focused web search integrated with the Brave browser."],
+    ["duckduckgo", "Privacy-oriented search engine that does not track users."],
+    ["qwant", "European privacy-focused web search engine."],
+    ["startpage", "Search engine that proxies Google results with enhanced privacy."],
+    ["yahoo", "Web portal providing search, email, and news."],
+    ["ask", "Question-answering oriented web search engine."],
+    ["wikipedia", "Free, community-edited online encyclopedia."],
+    ["wikidata", "Structured, collaborative knowledge base from Wikimedia."],
+    ["wolframalpha", "Computational knowledge engine for factual queries and calculations."],
+  ],
+  news: [
+    ["duckduckgo news", "Aggregated news search powered by DuckDuckGo."],
+    ["mojeek news", "News search vertical from the independent Mojeek engine."],
+    ["bing news", "News aggregation and search from Microsoft Bing."],
+    ["brave.news", "Privacy-focused news search from Brave Search."],
+    ["google news", "Google's personalized news aggregation and search service."],
+    ["qwant news", "News search and headlines from Qwant."],
+    ["yahoo news", "News portal and search from Yahoo."],
+    ["tagesschau (DE)", "German-language news search for Tagesschau, a major public broadcaster."],
+  ],
+  videos: [
+    ["bing videos", "Video search vertical from Microsoft Bing."],
+    ["brave.videos", "Video search vertical of Brave Search."],
+    ["duckduckgo videos", "Video search results from DuckDuckGo."],
+    ["google videos", "Video-focused search results from Google."],
+    ["qwant videos", "Video search vertical from Qwant."],
+    ["bilibili", "Chinese video sharing and streaming platform popular for animation and games."],
+    ["dailymotion", "Global video-sharing and hosting platform."],
+    ["invidious", "Alternative, privacy-friendly front-end for YouTube content."],
+    ["odysee", "Decentralized, blockchain-based video hosting platform."],
+    ["peertube", "Federated, open source video hosting network."],
+    ["piped", "Privacy-respecting alternative front-end for YouTube."],
+    ["rumble", "Video sharing platform focusing on independent creators."],
+    ["vimeo", "Ad-free video hosting platform used by filmmakers and businesses."],
+    ["youtube", "The largest global video sharing and streaming platform."],
+  ],
+  images: [
+    ["bing images", "Image search engine by Microsoft Bing."],
+    ["brave.images", "Image search vertical of Brave Search."],
+    ["duckduckgo images", "Image search results from DuckDuckGo."],
+    ["google images", "Google's dedicated image search service."],
+    ["qwant images", "Image search vertical from Qwant."],
+    ["deviantart", "Online community and gallery for digital art and illustrations."],
+    ["flickr", "Image and short video hosting platform for photographers."],
+    ["imgur", "Image hosting and sharing site popular for memes and galleries."],
+    ["pinterest", "Visual discovery and bookmarking platform centered on images."],
+    ["unsplash", "Library of freely usable, high-resolution photos."],
+    ["wallhaven", "Community-driven wallpaper and background image repository."],
+    ["wikicommons.images", "Image search across media stored on Wikimedia Commons."],
+  ],
+  science: [
+    ["arxiv", "Repository of preprint research papers in physics, math, CS and more."],
+    ["crossref", "Infrastructure service providing DOIs and metadata for scholarly content."],
+    ["google scholar", "Google's search engine for scholarly literature and citations."],
+    ["internetarchivescholar", "Internet Archive search for digitized scholarly works."],
+    ["pubmed", "Database of biomedical and life sciences literature from NCBI."],
+    ["semantic scholar", "AI-powered literature search and discovery tool for research papers."],
+  ],
+  it: [
+    ["alpine linux packages", "Search index for Alpine Linux software packages."],
+    ["crates.io", "Official package registry for Rust crates."],
+    ["docker hub", "Central repository of Docker container images."],
+    ["hex", "Package manager and repository for the Erlang and Elixir ecosystem."],
+    ["hoogle", "API search engine for Haskell libraries and functions."],
+    ["lib.rs", "Alternative index and front-end for Rust crates."],
+    ["metacpan", "Search engine for Perl modules hosted on CPAN."],
+    ["npm", "Package registry and manager for JavaScript and Node.js."],
+    ["packagist", "Primary package repository for PHP Composer."],
+    ["pkg.go.dev", "Documentation and discovery service for Go modules."],
+    ["pub.dev", "Package repository for Dart and Flutter packages."],
+    ["pypi", "Python Package Index, the main repository for Python packages."],
+    ["rubygems", "Package manager and repository for Ruby gems."],
+    ["voidlinux", "Package search for the Void Linux distribution."],
+    ["askubuntu", "Q&A site focused on Ubuntu usage and troubleshooting."],
+    ["stackoverflow", "Question-and-answer site for programmers and software development."],
+    ["superuser", "Q&A site for advanced computer users and system administration."],
+    ["bitbucket", "Git-based source code hosting and collaboration platform by Atlassian."],
+    ["codeberg", "Non-profit, open source Git hosting platform."],
+    ["gitea.com", "Hosted instance of the lightweight Gitea Git service."],
+    ["github", "Popular Git-based code hosting and collaboration platform."],
+    ["gitlab", "DevOps platform offering Git hosting, CI/CD, and project management."],
+    ["sourcehut", "Minimalist suite of tools for software development and mailing lists."],
+    ["arch linux wiki", "Extensive documentation wiki for Arch Linux and related tools."],
+    ["gentoo", "Documentation wiki for the Gentoo Linux distribution."],
+    ["mdn", "Mozilla Developer Network documentation for web technologies."],
+    ["searchcode code", "Search engine indexing source code across public repositories."],
+  ],
+  files: [
+    ["library of congress", "Catalog and digital collections from the U.S. Library of Congress."],
+    ["wikibooks", "Wikimedia project hosting free textbooks and manuals."],
+    ["wikisource", "Wikimedia digital library of source texts and documents."],
+    ["wikiversity", "Wikimedia project for educational resources and courses."],
+    ["wikivoyage", "Free, community-created travel guide from Wikimedia."],
+    ["google play movies", "Google's store for purchasing and renting movies and TV series."],
+    ["mediathekviewweb (DE)", "Web interface to German public TV media libraries."],
+    ["ina (FR)", "French National Audiovisual Institute archive search."],
+    ["wikicommons.videos", "Search for video media stored on Wikimedia Commons."],
+    ["wikicommons.audio", "Search for audio files stored on Wikimedia Commons."],
+    ["apk mirror", "Repository for Android APK files outside official app stores."],
+    ["apple app store", "Official iOS and iPadOS app distribution platform."],
+    ["fdroid", "Catalog of free and open source Android applications."],
+    ["google play apps", "Official Android app store operated by Google."],
+  ],
+  "social+media": [
+    ["pinterest", "Visual discovery, bookmarking, and inspiration social platform."],
+    ["reddit", "Social news aggregation and discussion website organized by communities."],
+    ["9gag", "Humor-focused social media site for sharing memes and short posts."],
+    ["lemmy posts", "Post search across Lemmy, a federated link-aggregation platform."],
+  ],
+  map: [
+    ["apple maps", "Apple's mapping and navigation service for its devices."],
+    ["openstreetmap", "Collaborative, open data world map project."],
+  ],
+  music: [
+    ["genius", "Platform for song lyrics, annotations, and music commentary."],
+    ["radio browser", "Directory and search engine for online radio stations."],
+    ["bandcamp", "Music platform for independent artists to sell and stream releases."],
+    ["deezer", "On-demand music streaming service."],
+    ["mixcloud", "Streaming platform for DJ mixes, radio shows, and podcasts."],
+    ["soundcloud", "Audio distribution and music sharing platform for creators."],
+    ["youtube", "Video platform heavily used for streaming music and music videos."],
+  ],
+};

package/src/constants.ts

@@ -0,0 +1,6 @@
+/**
+ * Constants — Re-exports all static search API constants from the canonical
+ * config module: CATEGORY_LIST, RECENCY_ALLOWED_LIST, SEARX_DOMAINS, and the
+ * per-category engine directory used for documentation and UI rendering.
+ */
+export * from "./config/search-engine-constants.js";

package/src/engine-descriptions.ts

@@ -0,0 +1,7 @@
+/**
+ * Engine Descriptions — Re-exports the `engineDescriptions` map and helper
+ * functions (`getEngineDescription`, `getEnginesWithDescriptions`) from the
+ * canonical registry module. Descriptions are sourced from SearXNG's
+ * engine_descriptions.json and cover all 75+ supported engines.
+ */
+export * from "./registry/search-engine-descriptions.js";

package/src/engine-status.ts

@@ -0,0 +1,7 @@
+/**
+ * Engine Status — Re-exports the EngineStatusTracker class and the global
+ * `engineStatusTracker` singleton from the canonical registry module.
+ * The tracker records per-engine success/failure counts, response times,
+ * and health status, and gates which engines are eligible to run.
+ */
+export * from "./registry/search-engine-status-tracker.js";

package/src/engine.ts

@@ -0,0 +1,6 @@
+/**
+ * Engine — Re-exports the core engine types (EngineResult, Engine, EngineFunction)
+ * and the `extractResponseData` helper from the canonical types module. All
+ * engine source adapters import from `types/search-engine-interface` directly.
+ */
+export * from "./types/search-engine-interface.js";

package/src/registry/search-engine-category-registry.ts

@@ -0,0 +1,200 @@
+/**
+ * Search Engine Category Registry — Manages the mapping of search engines to
+ * categories (general, images, videos, news, maps, academic, etc.) and stores
+ * per-category default scoring weights. Based on SearXNG's engine categorisation
+ * system, it supports multi-category searches and weighted result combination.
+ */
+
+import { Engine } from "../types/search-engine-interface.js";
+import { CategoryConfig } from "../types/search-result-types.js";
+
+export const CATEGORIES: { [key: string]: CategoryConfig } = {
+  general: {
+    name: "general",
+    displayName: "General",
+    description: "General web search",
+    defaultWeight: 1.0,
+  },
+  images: {
+    name: "images",
+    displayName: "Images",
+    description: "Image search",
+    defaultWeight: 1.0,
+  },
+  videos: {
+    name: "videos",
+    displayName: "Videos",
+    description: "Video search",
+    defaultWeight: 1.0,
+  },
+  news: {
+    name: "news",
+    displayName: "News",
+    description: "News search",
+    defaultWeight: 1.1,
+  },
+  maps: {
+    name: "maps",
+    displayName: "Maps",
+    description: "Maps and locations",
+    defaultWeight: 1.0,
+  },
+  music: {
+    name: "music",
+    displayName: "Music",
+    description: "Music search",
+    defaultWeight: 1.0,
+  },
+  it: {
+    name: "it",
+    displayName: "IT",
+    description: "Programming and IT resources",
+    defaultWeight: 1.2,
+  },
+  academic: {
+    name: "academic",
+    displayName: "Academic",
+    description: "Scientific papers and academic resources",
+    defaultWeight: 1.3,
+  },
+  social: {
+    name: "social",
+    displayName: "Social Media",
+    description: "Social media content",
+    defaultWeight: 0.9,
+  },
+  files: {
+    name: "files",
+    displayName: "Files",
+    description: "File search",
+    defaultWeight: 1.0,
+  },
+  torrents: {
+    name: "torrents",
+    displayName: "Torrents",
+    description: "Torrent search",
+    defaultWeight: 0.8,
+  },
+  shopping: {
+    name: "shopping",
+    displayName: "Shopping",
+    description: "Shopping and products",
+    defaultWeight: 1.0,
+  },
+  specialized: {
+    name: "specialized",
+    displayName: "Specialized",
+    description: "Specialized search engines",
+    defaultWeight: 1.1,
+  },
+};
+
+/**
+ * CategoryRegistry manages engines organised by category.
+ * Supports multi-category search with proper result combination.
+ */
+export class CategoryRegistry {
+  private enginesByCategory: Map<string, Engine[]> = new Map();
+  private allEngines: Engine[] = [];
+
+  /**
+   * Register a single engine in the registry.
+   */
+  registerEngine(engine: Engine): void {
+    if (!this.allEngines.find((e) => e.name === engine.name)) {
+      this.allEngines.push(engine);
+    }
+
+    const categories = engine.categories || ["general"];
+    for (const category of categories) {
+      if (!this.enginesByCategory.has(category)) {
+        this.enginesByCategory.set(category, []);
+      }
+
+      const engines = this.enginesByCategory.get(category)!;
+      if (!engines.find((e) => e.name === engine.name)) {
+        engines.push(engine);
+      }
+    }
+  }
+
+  /**
+   * Register multiple engines at once.
+   */
+  registerEngines(engines: Engine[]): void {
+    for (const engine of engines) {
+      this.registerEngine(engine);
+    }
+  }
+
+  /**
+   * Get all engines that belong to any of the given categories.
+   */
+  getEnginesByCategories(categories: string[]): Engine[] {
+    const engines = new Set<Engine>();
+
+    for (const category of categories) {
+      const categoryEngines = this.enginesByCategory.get(category) || [];
+      for (const engine of categoryEngines) {
+        engines.add(engine);
+      }
+    }
+
+    return Array.from(engines);
+  }
+
+  /**
+   * Get engines by their names.
+   */
+  getEnginesByNames(names: string[]): Engine[] {
+    return this.allEngines.filter((e) => names.includes(e.name));
+  }
+
+  /**
+   * Get all available category names.
+   */
+  getCategories(): string[] {
+    return Array.from(this.enginesByCategory.keys());
+  }
+
+  /**
+   * Get all registered engines.
+   */
+  getAllEngines(): Engine[] {
+    return this.allEngines;
+  }
+
+  /**
+   * Get engines for a single category.
+   */
+  getCategoryEngines(category: string): Engine[] {
+    return this.enginesByCategory.get(category) || [];
+  }
+
+  /**
+   * Get the configuration object for a category.
+   */
+  getCategoryConfig(category: string): CategoryConfig | undefined {
+    return CATEGORIES[category];
+  }
+
+  /**
+   * Get a count of registered engines per category plus totals.
+   */
+  getStats() {
+    const stats: { [category: string]: number } = {};
+
+    for (const [category, engines] of this.enginesByCategory.entries()) {
+      stats[category] = engines.length;
+    }
+
+    return {
+      totalEngines: this.allEngines.length,
+      categories: this.getCategories().length,
+      enginesByCategory: stats,
+    };
+  }
+}
+
+/** Global singleton instance used throughout the application. */
+export const categoryRegistry = new CategoryRegistry();