simple-dynamsoft-mcp 7.6.1 → 7.7.0

package/README.md

@@ -305,6 +305,8 @@ The server exposes this minimal tool surface:
 
 Typical doc Q&A flow: `search` -> `read_document` with the exact `doc://` URI -> answer from the returned text and cite its public URL. Clients that support MCP resources can also fetch the same `doc://` / `sample://` URIs with `resources/read`.
 
+DBR searches also cover the shared Capture Vision API pages that the DBR docs link to (for example `CaptureVisionRouter.capture()` and `getSimplifiedSettings()`/`updateSettings()`); these hits keep their official `capture-vision/docs` URL and are labelled `shared Capture Vision API used by DBR` in search results. Doc URIs are path-based (`doc://dbr/web/web/<version>/user-guide/use-in-framework`) and change only when the docs move or the SDK version changes.
+
 ## Advanced Configuration And Operator Docs
 
 Advanced settings, CI/runbook details, and maintenance workflows live in:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "simple-dynamsoft-mcp",
-  "version": "7.6.1",
+  "version": "7.7.0",
   "description": "MCP server for Dynamsoft SDKs - Capture Vision, Barcode Reader (Mobile/Python/Web), Dynamic Web TWAIN, and Document Viewer. Provides documentation, code snippets, and API guidance.",
   "license": "MIT",
   "repository": {
@@ -24,13 +24,15 @@
   "scripts": {
     "start": "node src/index.js",
     "test": "npm run test:lite",
-    "test:unit": "node --test test/unit/gemini-retry.test.js test/unit/profile-config.test.js test/unit/lexical-provider.test.js test/unit/hydration-mode.test.js test/unit/hydration-policy.test.js test/unit/repo-map.test.js test/unit/download-utils.test.js test/unit/logging.test.js test/unit/request-logging.test.js test/unit/request-log-file.test.js test/unit/rag-signature-manifest.test.js test/unit/startup-timing.test.js test/unit/http-startup-readiness.test.js test/unit/resource-index-startup.test.js test/unit/create-server.test.js test/unit/server-helpers.test.js test/unit/update-sdk-versions.test.js test/unit/version-policy.test.js test/unit/query-expansion.test.js test/unit/docs-loader-enrich.test.js",
+    "test:unit": "node --test test/unit/gemini-retry.test.js test/unit/profile-config.test.js test/unit/lexical-provider.test.js test/unit/hydration-mode.test.js test/unit/hydration-policy.test.js test/unit/repo-map.test.js test/unit/download-utils.test.js test/unit/logging.test.js test/unit/request-logging.test.js test/unit/request-log-file.test.js test/unit/rag-signature-manifest.test.js test/unit/startup-timing.test.js test/unit/http-startup-readiness.test.js test/unit/resource-index-startup.test.js test/unit/create-server.test.js test/unit/server-helpers.test.js test/unit/update-sdk-versions.test.js test/unit/version-policy.test.js test/unit/query-expansion.test.js test/unit/docs-loader-enrich.test.js test/unit/shared-docs.test.js test/unit/vector-cache.test.js test/unit/doc-slugs.test.js",
     "test:lite": "npm run test:stdio && npm run test:http && npm run test:package",
     "test:lexical": "node --test test/integration/stdio.test.js test/integration/http.test.js",
     "test:gemini": "node scripts/run-gemini-tests.mjs",
     "test:stdio": "node --test test/integration/stdio.test.js",
     "test:http": "node --test test/integration/http.test.js",
     "test:package": "node --test test/integration/package-runtime.test.js",
+    "test:retrieval": "node --test test/integration/retrieval-quality.test.js",
+    "eval:retrieval": "node scripts/eval-retrieval.mjs",
     "test:contract": "node --test test/contract/contract.test.js",
     "check:version-drift": "node scripts/check-version-drift.mjs",
     "test:lazy": "node --test test/integration/lazy-hydration.test.js",

package/scripts/eval-retrieval.mjs

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+// Measures search relevance against the golden query set.
+//
+//   node scripts/eval-retrieval.mjs [--provider=lexical|gemini] [--case=<id>] [--show] [--json=<path>]
+//
+// The provider is passed through RAG_PROVIDER before the RAG layer loads, with
+// fallback disabled so a failing provider is reported instead of masked.
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const args = Object.fromEntries(
+  process.argv.slice(2).map((arg) => {
+    const [key, ...rest] = arg.replace(/^--/, "").split("=");
+    return [key, rest.length ? rest.join("=") : "true"];
+  })
+);
+const provider = args.provider || "lexical";
+process.env.RAG_PROVIDER = provider;
+process.env.RAG_FALLBACK = "none";
+process.env.RAG_PREWARM = "false";
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+const goldenPath = args.golden || join(repoRoot, "test", "fixtures", "retrieval-golden.json");
+const golden = JSON.parse(readFileSync(goldenPath, "utf8"));
+const cases = args.case ? golden.cases.filter((item) => item.id === args.case) : golden.cases;
+if (cases.length === 0) {
+  console.error(`No golden cases matched ${args.case}`);
+  process.exit(1);
+}
+
+const { ensureResourceIndexReady } = await import("../src/server/resource-index.js");
+const { searchResources } = await import("../src/rag/index.js");
+const { runRetrievalEval } = await import("./lib/retrieval-eval.mjs");
+const { isResultInScope } = await import("./lib/scope-matcher.mjs");
+
+ensureResourceIndexReady();
+const report = await runRetrievalEval({ searchResources, cases, k: golden.k || 5, isInScope: isResultInScope });
+report.provider = provider;
+
+const fmt = (value) => (value === null || value === undefined ? "n/a" : value.toFixed(3));
+for (const item of report.cases) {
+  const flag = item.gap ? "GAP " : item.requiredHit === false ? "MISS" : "ok  ";
+  console.log(`${flag} ${item.id.padEnd(34)} recall=${fmt(item.recall)} mrr=${fmt(item.mrr)} ndcg=${fmt(item.ndcg)} dup=${item.duplicates} off=${item.offScope} rn=${item.releaseNotes} ms=${item.latencyMs.toFixed(0)}`);
+  if (args.show || item.requiredHit === false) {
+    for (const hit of item.top) {
+      console.log(`       ${hit.rank}. [g${hit.grade}] [${hit.product}] ${hit.title} :: ${hit.url || hit.uri}`);
+    }
+    for (const url of item.requiredMissing) console.log(`       missing: ${url}`);
+  }
+}
+
+const s = report.summary;
+console.log(`\nprovider=${provider} cases=${s.cases} (gap=${s.gapCases}) k=${report.k}`);
+console.log(`recall@${report.k}=${fmt(s.recallAtK)} mrr=${fmt(s.mrr)} ndcg@${report.k}=${fmt(s.ndcgAtK)} required_hit=${fmt(s.requiredHitRate)}`);
+console.log(`duplicate_rate=${fmt(s.duplicateRate)} off_scope_rate=${fmt(s.offScopeRate)} release_notes_rate=${fmt(s.releaseNotesRate)}`);
+const lat = s.latencyMs;
+console.log(`latency_ms first_query=${lat.firstQuery.toFixed(0)} first_pass p50=${lat.p50FirstPass.toFixed(0)} p95=${lat.p95FirstPass.toFixed(0)} | warm p50=${lat.p50Warm.toFixed(0)} p95=${lat.p95Warm.toFixed(0)}`);
+
+if (args.json) {
+  writeFileSync(args.json, JSON.stringify(report, null, 2));
+  console.log(`wrote ${args.json}`);
+}

package/scripts/lib/retrieval-eval.mjs

@@ -0,0 +1,134 @@
+// Retrieval-quality metrics for the golden query set (test/fixtures/retrieval-golden.json).
+// Cases grade relevant documents by public URL (not doc:// URI) so judgments
+// survive URI-scheme and index-order changes.
+
+function normalizeUrl(url) {
+  return String(url || "").split("#")[0].split("?")[0].replace(/\/index\.html$/i, "/").toLowerCase();
+}
+
+function gradeOf(result, relevant) {
+  const key = normalizeUrl(result.url);
+  if (!key) return 0;
+  return relevant.get(key) || 0;
+}
+
+function dcg(gains) {
+  return gains.reduce((sum, gain, index) => sum + ((2 ** gain) - 1) / Math.log2(index + 2), 0);
+}
+
+function percentile(values, p) {
+  if (values.length === 0) return 0;
+  const sorted = [...values].sort((a, b) => a - b);
+  const index = Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1);
+  return sorted[Math.max(0, index)];
+}
+
+// `isInScope(result, filters)` (when given) applies the server's own
+// product/edition/platform matching so cross-platform leakage is counted too.
+function isOffScope(result, testCase, isInScope) {
+  const product = testCase.filters?.product;
+  if (product && result.product !== product) return true;
+  if (isInScope && !isInScope(result, testCase.filters || {})) return true;
+  const prefixes = testCase.allowedUrlPrefixes;
+  if (Array.isArray(prefixes) && prefixes.length > 0 && result.url) {
+    return !prefixes.some((prefix) => String(result.url).startsWith(prefix));
+  }
+  return false;
+}
+
+function isReleaseNotes(result) {
+  return /\/release-notes?\//i.test(String(result.url || ""));
+}
+
+function scoreCase(testCase, results, k, isInScope) {
+  const relevant = new Map(
+    Object.entries(testCase.relevant || {}).map(([url, grade]) => [normalizeUrl(url), Number(grade) || 0])
+  );
+  const top = results.slice(0, k);
+  const gains = top.map((result) => gradeOf(result, relevant));
+  const positiveGains = [...relevant.values()].filter((g) => g > 0).sort((a, b) => b - a);
+  const idealGains = positiveGains.slice(0, k);
+  const relevantCount = positiveGains.length;
+
+  const firstHit = gains.findIndex((gain) => gain > 0);
+  const found = new Set(top.filter((result) => gradeOf(result, relevant) > 0).map((r) => normalizeUrl(r.url)));
+  const required = [...relevant.entries()].filter(([, grade]) => grade >= 3).map(([url]) => url);
+  const requiredFound = required.filter((url) => found.has(url));
+
+  const urls = top.map((result) => normalizeUrl(result.url || result.uri));
+  const duplicates = urls.length - new Set(urls).size;
+
+  return {
+    id: testCase.id,
+    gap: relevantCount === 0,
+    recall: relevantCount ? found.size / relevantCount : null,
+    mrr: relevantCount ? (firstHit >= 0 ? 1 / (firstHit + 1) : 0) : null,
+    ndcg: relevantCount ? dcg(gains) / dcg(idealGains) : null,
+    requiredHit: required.length ? requiredFound.length === required.length : null,
+    requiredMissing: required.filter((url) => !found.has(url)),
+    duplicates,
+    offScope: top.filter((result) => isOffScope(result, testCase, isInScope)).length,
+    releaseNotes: top.filter(isReleaseNotes).length,
+    returned: top.length,
+    top: top.map((result, index) => ({
+      rank: index + 1,
+      grade: gains[index],
+      product: result.product,
+      title: result.title,
+      url: result.url || "",
+      uri: result.uri
+    }))
+  };
+}
+
+function mean(values) {
+  const present = values.filter((value) => value !== null && value !== undefined);
+  if (present.length === 0) return null;
+  return present.reduce((sum, value) => sum + value, 0) / present.length;
+}
+
+function summarize(caseScores, firstPass, warmPass) {
+  const totalReturned = caseScores.reduce((sum, item) => sum + item.returned, 0) || 1;
+  const required = caseScores.filter((item) => item.requiredHit !== null);
+  return {
+    cases: caseScores.length,
+    gapCases: caseScores.filter((item) => item.gap).length,
+    recallAtK: mean(caseScores.map((item) => item.recall)),
+    mrr: mean(caseScores.map((item) => item.mrr)),
+    ndcgAtK: mean(caseScores.map((item) => item.ndcg)),
+    requiredHitRate: required.length ? required.filter((item) => item.requiredHit).length / required.length : null,
+    duplicateRate: caseScores.reduce((sum, item) => sum + item.duplicates, 0) / totalReturned,
+    offScopeRate: caseScores.reduce((sum, item) => sum + item.offScope, 0) / totalReturned,
+    releaseNotesRate: caseScores.reduce((sum, item) => sum + item.releaseNotes, 0) / totalReturned,
+    // First pass pays index loading and per-scope index builds; the warm pass
+    // repeats the same queries, so it reflects steady-state search cost.
+    latencyMs: {
+      firstQuery: firstPass[0] ?? 0,
+      p50FirstPass: percentile(firstPass, 50),
+      p95FirstPass: percentile(firstPass, 95),
+      p50Warm: percentile(warmPass, 50),
+      p95Warm: percentile(warmPass, 95)
+    }
+  };
+}
+
+async function runRetrievalEval({ searchResources, cases, k = 5, isInScope }) {
+  const caseScores = [];
+  const firstPass = [];
+  const warmPass = [];
+  for (const testCase of cases) {
+    const startedAt = performance.now();
+    const results = await searchResources({ query: testCase.query, ...(testCase.filters || {}), limit: k, throwOnError: true });
+    const latencyMs = performance.now() - startedAt;
+    firstPass.push(latencyMs);
+    caseScores.push({ ...scoreCase(testCase, results, k, isInScope), latencyMs });
+  }
+  for (const testCase of cases) {
+    const startedAt = performance.now();
+    await searchResources({ query: testCase.query, ...(testCase.filters || {}), limit: k, throwOnError: true });
+    warmPass.push(performance.now() - startedAt);
+  }
+  return { k, summary: summarize(caseScores, firstPass, warmPass), cases: caseScores };
+}
+
+export { normalizeUrl, scoreCase, summarize, runRetrievalEval };

package/scripts/lib/scope-matcher.mjs

@@ -0,0 +1,17 @@
+// Scope check for retrieval evaluation, using the same normalizers and
+// matchers the search path applies to filters.
+import {
+  normalizeProduct,
+  normalizePlatform,
+  normalizeEdition,
+  editionMatches,
+  platformMatches
+} from "../../src/server/resource-index.js";
+import { normalizeSearchFilters, entryMatchesScope } from "../../src/rag/search-utils.js";
+
+function isResultInScope(result, rawFilters) {
+  const filters = normalizeSearchFilters(rawFilters, { normalizeProduct, normalizePlatform, normalizeEdition });
+  return entryMatchesScope(result, filters, { editionMatches, platformMatches });
+}
+
+export { isResultInScope };

package/scripts/prebuild-rag-index.mjs

@@ -32,6 +32,8 @@ if (!existsSync(cacheDir)) {
   throw new Error(`RAG cache directory not found after prebuild: ${cacheDir}`);
 }
 
+// Each cache is a JSON header plus a sibling `.f32` vector file (see
+// src/rag/vector-cache.js); both ship in the release archive.
 const cacheFiles = readdirSync(cacheDir, { withFileTypes: true })
   .filter((entry) => entry.isFile())
   .map((entry) => join(cacheDir, entry.name))
@@ -48,6 +50,12 @@ if (cacheFiles.length === 0) {
   throw new Error(`No cache JSON files found in ${cacheDir}.`);
 }
 
+const vectorFiles = cacheFiles.map((path) => path.replace(/\.json$/i, ".f32"));
+const missingVectors = vectorFiles.filter((path) => !existsSync(path));
+if (missingVectors.length > 0) {
+  throw new Error(`Vector files missing for cache headers: ${missingVectors.map((path) => basename(path)).join(", ")}`);
+}
+
 let indexSignature = "";
 let indexCacheKey = "";
 const geminiCacheFile = cacheFiles.find((path) => /rag-gemini-.*\.json$/i.test(path));
@@ -69,7 +77,7 @@ const manifest = {
   indexSignature,
   indexCacheKey,
   cacheDir: toPosixPath(cacheDir),
-  files: cacheFiles.map((path) => {
+  files: [...cacheFiles, ...vectorFiles].sort().map((path) => {
     const stats = statSync(path);
     return {
       name: toPosixPath(path.slice(cacheDir.length + 1)),

package/scripts/verify-doc-resources.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { resourceIndex, readResourceContent } from "../src/server/resource-index.js";
+import { ensureResourceIndexReady, resourceIndex, readResourceContent } from "../src/server/resource-index.js";
 
 function parsePositiveInt(value, fallback) {
   const parsed = Number.parseInt(String(value ?? ""), 10);
@@ -9,6 +9,7 @@ function parsePositiveInt(value, fallback) {
 }
 
 async function main() {
+  ensureResourceIndexReady();
   const concurrency = parsePositiveInt(process.env.DOC_VERIFY_CONCURRENCY, 8);
   const docs = resourceIndex.filter((entry) => entry.type === "doc");
   const total = docs.length;

package/src/data/repo-map.js

@@ -3,14 +3,33 @@ import { getHydrationProduct } from "../server/public-offerings.js";
 
 const REPO_MAP = {
   dbr: {
+    // DBR docs index the Capture Vision pages they link to (shared APIs such as
+    // CaptureVisionRouter), so each DBR edition also needs the matching DCV
+    // edition repo plus DCV core.
     docs: {
-      web: ["documentation/barcode-reader-docs-js"],
-      mobile: ["documentation/barcode-reader-docs-mobile"],
-      server: ["documentation/barcode-reader-docs-server"],
+      web: [
+        "documentation/barcode-reader-docs-js",
+        "documentation/capture-vision-docs-js",
+        "documentation/capture-vision-docs"
+      ],
+      mobile: [
+        "documentation/barcode-reader-docs-mobile",
+        "documentation/capture-vision-docs-mobile",
+        "documentation/capture-vision-docs"
+      ],
+      server: [
+        "documentation/barcode-reader-docs-server",
+        "documentation/capture-vision-docs-server",
+        "documentation/capture-vision-docs"
+      ],
       any: [
         "documentation/barcode-reader-docs-js",
         "documentation/barcode-reader-docs-mobile",
-        "documentation/barcode-reader-docs-server"
+        "documentation/barcode-reader-docs-server",
+        "documentation/capture-vision-docs",
+        "documentation/capture-vision-docs-js",
+        "documentation/capture-vision-docs-mobile",
+        "documentation/capture-vision-docs-server"
       ]
     },
     samples: {

package/src/rag/config.js

@@ -63,12 +63,10 @@ const ragConfig = {
   modelCacheDir: readEnvValue("RAG_MODEL_CACHE_DIR", join(dataRoot, ".rag-cache", "models")),
   chunkSize: readIntEnv("RAG_CHUNK_SIZE", 1200),
   chunkOverlap: readIntEnv("RAG_CHUNK_OVERLAP", 200),
-  // Keep the total embedded-chunk count within V8's ~512MB max-string limit,
-  // which the prebuilt Gemini cache hits via a single JSON.stringify of ~3072-dim
-  // vectors. At 24 the release prebuild overflowed ("Invalid string length"); 6 is
-  // the count the pre-v7.4 release built successfully on this data. Raising this
-  // needs the ceiling-proof cache format tracked in the v7.5 follow-ups.
-  maxChunksPerDoc: readIntEnv("RAG_MAX_CHUNKS_PER_DOC", 6),
+  // 0 = embed every chunk of every doc (~19.7k chunks vs ~10.3k at the old cap
+  // of 6). Each chunk is one Gemini embedding per release prebuild; the vector
+  // cache is header + float32 (src/rag/vector-cache.js), so there is no size cap.
+  maxChunksPerDoc: readIntEnv("RAG_MAX_CHUNKS_PER_DOC", 0),
   maxTextChars: readIntEnv("RAG_MAX_TEXT_CHARS", 4000),
   minScore: readFloatEnv("RAG_MIN_SCORE", 0.2),
   includeScore: readBoolEnv("RAG_INCLUDE_SCORE", false),

package/src/rag/index.js

@@ -102,7 +102,22 @@ function refreshRagIndexes() {
   logRag(`indexes refreshed resources=${resourceIndex.length}`);
 }
 
-async function searchResources({ query, product, edition, platform, type, limit }) {
+function dedupeByPublicUrl(results, limit) {
+  const seen = new Set();
+  const unique = [];
+  for (const entry of results) {
+    const key = entry.url || entry.uri;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    unique.push(entry);
+    if (limit && unique.length >= limit) break;
+  }
+  return unique;
+}
+
+// `throwOnError` makes an all-providers failure throw instead of returning [];
+// evaluation uses it so a broken provider cannot pass as zero relevance.
+async function searchResources({ query, product, edition, platform, type, limit, throwOnError = false }) {
   const startedAt = Date.now();
   const filters = normalizeSearchFilters({ product, edition, platform, type }, {
     normalizeProduct,
@@ -133,7 +148,11 @@ async function searchResources({ query, product, edition, platform, type, limit
   for (const name of providers) {
     try {
       const provider = await providerOrchestrator.loadSearchProvider(name);
-      const results = await provider.search(searchQuery, filters, maxResults);
+      // Shared pages (e.g. Capture Vision core reference) are indexed once per
+      // DBR edition, so an edition-less search can hit the same public page
+      // several times. Over-fetch, then keep the best hit per public URL.
+      const candidates = await provider.search(searchQuery, filters, maxResults ? maxResults * 3 : undefined);
+      const results = dedupeByPublicUrl(candidates, maxResults);
       if (!ragLogState.providerFirstUse.has(name)) {
         ragLogState.providerFirstUse.add(name);
         logRag("provider_selected", {
@@ -191,6 +210,7 @@ async function searchResources({ query, product, edition, platform, type, limit
       latency_bucket: latencyBucket(elapsedMs),
       error: lastError.message
     }, { level: "error" });
+    if (throwOnError) throw lastError;
   }
   return [];
 }

package/src/rag/lexical-provider.js

@@ -1,5 +1,5 @@
 import Fuse from "fuse.js";
-import { expandQueryTokens, extractSnippet } from "./search-utils.js";
+import { chunkMarkdown, expandQueryTokens, extractSnippet } from "./search-utils.js";
 
 const DEFAULT_FUSE_OPTIONS = {
   keys: [
@@ -12,27 +12,40 @@ const DEFAULT_FUSE_OPTIONS = {
   includeScore: true
 };
 
-const BODY_INDEX_CHARS = 4000;
+// Section size and overlap for body scoring; match the embedding chunking so
+// lexical and Gemini see the same units, and so a term cut at a chunk boundary
+// still appears whole in the neighbouring chunk.
+const SECTION_CHARS = 1200;
+const SECTION_OVERLAP_CHARS = 200;
 
-// Field-weighted BM25 haystack: title/tags outrank summary; doc/sample body text
-// is indexed at low weight so body-only content is findable; the URI's last slug
+// Field-weighted header: title/tags outrank summary; the URI's last slug
 // segment is kept (it is often the most descriptive token) while scheme/version
 // noise is dropped (issue #147).
-function buildLexicalHaystack(entry) {
+function buildHeaderText(entry) {
   const title = entry.title || "";
   const tags = Array.isArray(entry.tags) ? entry.tags.join(" ") : "";
   const summary = entry.summary || "";
-  const body = entry.embedText ? String(entry.embedText).slice(0, BODY_INDEX_CHARS) : "";
   const uriSlug = String(entry.uri || "").split("/").filter(Boolean).pop() || "";
-  return [
-    title, title, title,
-    tags, tags,
-    summary,
-    uriSlug,
-    body
-  ].join(" \n ");
+  return [title, title, title, tags, tags, summary, uriSlug].join(" \n ");
 }
 
+// The whole body, split on headings (each section keeps its heading path), so
+// content deep in long guides is searchable and a page is ranked by its best
+// matching section instead of by one length-diluted blob.
+function buildBodySections(entry) {
+  if (!entry.embedText) return [];
+  return chunkMarkdown(entry.embedText, SECTION_CHARS, SECTION_OVERLAP_CHARS, 0);
+}
+
+const MAX_SCOPED_FUSE_INDEXES = 64;
+
+// Fuse matches long natural-language questions only through fragments of the
+// pattern, giving a weak, noisy signal at a cost of seconds on large scopes.
+// On the golden set (scripts/eval-retrieval.mjs), skipping it above this length
+// kept recall, raised MRR, and cut warm p95 from ~2.2s to ~0.2s. BM25 carries
+// long queries.
+const MAX_FUSE_QUERY_CHARS = 64;
+
 const BM25_K1 = 1.2;
 const BM25_B = 0.75;
 
@@ -61,63 +74,86 @@ function compareLexicalResults(a, b) {
   return String(a.entry.uri || "").localeCompare(String(b.entry.uri || ""));
 }
 
-function buildBm25Index(entries) {
-  const documents = [];
+function buildBm25Stats(units) {
   const documentFrequency = new Map();
   let totalLength = 0;
-
-  entries.forEach((entry, index) => {
-    const haystack = buildLexicalHaystack(entry);
-
-    const tokens = tokenize(haystack);
-    const termFreq = new Map();
-    tokens.forEach((token) => {
-      termFreq.set(token, (termFreq.get(token) || 0) + 1);
-    });
-
-    const seen = new Set();
-    for (const token of tokens) {
-      if (seen.has(token)) continue;
-      seen.add(token);
+  for (const unit of units) {
+    unit.termFreq = new Map();
+    for (const token of unit.tokens) {
+      unit.termFreq.set(token, (unit.termFreq.get(token) || 0) + 1);
+    }
+    for (const token of unit.termFreq.keys()) {
       documentFrequency.set(token, (documentFrequency.get(token) || 0) + 1);
     }
+    unit.length = unit.tokens.length;
+    totalLength += unit.length;
+    delete unit.tokens;
+  }
+  return {
+    documentFrequency,
+    totalDocuments: units.length,
+    avgLength: units.length > 0 ? totalLength / units.length : 0
+  };
+}
 
-    totalLength += tokens.length;
-    documents.push({
-      index,
-      entry,
-      length: tokens.length,
-      termFreq,
-      snippetText: entry.embedText || entry.summary || entry.title || ""
-    });
-  });
-
-  const avgLength = documents.length > 0 ? totalLength / documents.length : 0;
+// Two BM25 indexes: one header unit per entry, one unit per body section.
+// A page scores header + best section.
+function buildBm25Index(entries) {
+  const documents = entries.map((entry, index) => ({
+    index,
+    entry,
+    tokens: tokenize(buildHeaderText(entry)),
+    sections: [],
+    fallbackSnippet: entry.summary || entry.title || ""
+  }));
+  const sections = [];
+  for (const doc of documents) {
+    for (const text of buildBodySections(doc.entry)) {
+      const section = { text, tokens: tokenize(text) };
+      doc.sections.push(section);
+      sections.push(section);
+    }
+  }
   return {
     documents,
-    documentFrequency,
-    totalDocuments: documents.length,
-    avgLength
+    headerStats: buildBm25Stats(documents),
+    sectionStats: buildBm25Stats(sections)
   };
 }
 
-function computeBm25Score(indexState, docState, terms) {
+function computeBm25Score(stats, unit, terms) {
   if (terms.length === 0) return 0;
-  if (!docState.length || !indexState.avgLength) return 0;
+  if (!unit.length || !stats.avgLength) return 0;
 
   let score = 0;
   for (const term of terms) {
-    const tf = docState.termFreq.get(term) || 0;
+    const tf = unit.termFreq.get(term) || 0;
     if (!tf) continue;
-    const df = indexState.documentFrequency.get(term) || 0;
-    const idf = Math.log(1 + (indexState.totalDocuments - df + 0.5) / (df + 0.5));
-    const denom = tf + BM25_K1 * (1 - BM25_B + BM25_B * (docState.length / indexState.avgLength));
+    const df = stats.documentFrequency.get(term) || 0;
+    const idf = Math.log(1 + (stats.totalDocuments - df + 0.5) / (df + 0.5));
+    const denom = tf + BM25_K1 * (1 - BM25_B + BM25_B * (unit.length / stats.avgLength));
     score += idf * ((tf * (BM25_K1 + 1)) / denom);
   }
 
   return score;
 }
 
+function scoreDocument(index, doc, terms) {
+  let best = null;
+  let bestScore = 0;
+  for (const section of doc.sections) {
+    const score = computeBm25Score(index.sectionStats, section, terms);
+    if (score > bestScore) {
+      bestScore = score;
+      best = section;
+    }
+  }
+  return {
+    score: computeBm25Score(index.headerStats, doc, terms) + bestScore,
+    snippetText: best ? best.text : doc.fallbackSnippet
+  };
+}
+
 function createLexicalProvider({
   entries,
   entryMatchesScope,
@@ -126,10 +162,24 @@ function createLexicalProvider({
   bm25Weight = 0.7,
   fuseWeight = 0.3
 }) {
-  const fuse = new Fuse(entries, fuseOptions);
   const bm25Index = buildBm25Index(entries);
   const entryByUri = new Map(entries.map((entry) => [entry.uri, entry]));
-  const snippetTextByUri = new Map(bm25Index.documents.map((doc) => [doc.entry.uri, doc.snippetText]));
+  // Fuse cost grows with the number of entries scanned, and its hits were
+  // filtered by scope only afterwards. One Fuse index per scope keeps scoped
+  // searches proportional to that scope; the scope set is small and bounded.
+  const fuseByScope = new Map();
+  const getScopedFuse = (filters) => {
+    const key = [filters?.product, filters?.edition, filters?.platform, filters?.type].map((v) => v || "").join("|");
+    let scoped = fuseByScope.get(key);
+    if (!scoped) {
+      scoped = new Fuse(entries.filter((entry) => entryMatchesScope(entry, filters || {})), fuseOptions);
+      if (fuseByScope.size >= MAX_SCOPED_FUSE_INDEXES) {
+        fuseByScope.delete(fuseByScope.keys().next().value);
+      }
+      fuseByScope.set(key, scoped);
+    }
+    return scoped;
+  };
 
   return {
     name: "lexical",
@@ -137,7 +187,7 @@ function createLexicalProvider({
       // Expand with domain synonyms/stems so vocabulary gaps (webcam/camera,
       // datamatrix/data matrix, scanning/scan) do not zero the BM25 component.
       const terms = expandQueryTokens([...new Set(tokenize(query))]);
-      const fuseHits = fuse.search(query);
+      const fuseHits = query.length <= MAX_FUSE_QUERY_CHARS ? getScopedFuse(filters).search(query) : [];
       const fuseScoreByUri = new Map();
 
       for (const hit of fuseHits) {
@@ -154,9 +204,11 @@ function createLexicalProvider({
       // out-of-scope fuzzy match deflate every in-scope fuse contribution (issue #147).
       let maxFuse = 0;
 
+      const snippetTextByUri = new Map();
       for (const doc of bm25Index.documents) {
         if (!entryMatchesScope(doc.entry, filters)) continue;
-        const score = computeBm25Score(bm25Index, doc, terms);
+        const { score, snippetText } = scoreDocument(bm25Index, doc, terms);
+        snippetTextByUri.set(doc.entry.uri, snippetText);
         if (score > 0) {
           bm25ScoreByUri.set(doc.entry.uri, score);
           if (score > maxBm25) maxBm25 = score;