@wgtechlabs/mdd-engine 0.1.0-pr.08f3b80 → 0.1.0-pr.55ddedf

package/README.md

@@ -85,6 +85,10 @@ import { search } from '@wgtechlabs/mdd-engine/search';
 const index = createSearchIndex(result.site);
 const restored = JSON.parse(JSON.stringify(index));
 console.log(search(restored, 'installation', { limit: 10 }));
+// Multiple heading hits, breadcrumbs, and ranges for UI highlights.
+console.log(search(restored, 'instalation', {
+  mode: 'sections', fuzzy: true, limit: 8,
+}));
 // [{ title, url, section?, excerpt, score }]
 ```
 
@@ -129,6 +133,20 @@ Use GitHub-style alerts with `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, or `CAUTION`
 
 `:::details[More information]` remains supported and becomes `details`/`summary`; its label is optional, attributes are errors, and its readable Markdown uses a blockquote with a bold label. The old `:::note`, `:::tip`, and `:::warning` directives now fail with a `REMOVED_COMPONENT` migration diagnostic. See [alerts and migration](docs/ALERTS.md) for all five types, theme hooks, and how to preserve custom titles and bodies.
 
+Document an API endpoint with a leaf directive, then use ordinary Markdown for parameters and request/response examples:
+
+```markdown
+## Retrieve a widget
+
+::endpoint{method="GET" path="/v1/widgets/{id}"}
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `id` | string | Widget identifier. |
+```
+
+The required `method` accepts GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE, or CONNECT, normalizing lowercase/mixed case to uppercase. The required `path` starts with a single `/` and contains no whitespace or control characters; braces and query punctuation remain literal text. Labels, extra attributes, and inline/container forms are errors. The engine emits a `div.mdd-endpoint` containing `strong.mdd-endpoint-method.mdd-method-get` (or the corresponding lowercase method) and `code.mdd-endpoint-path`. Normalized Markdown contains `**GET**` followed by the code-formatted path, so the signature stays readable and searchable. Endpoint paths are not rewritten with the documentation base path. This is documentation only: no HTTP requests run. MDD and its themes provide presentation.
+
 Title precedence is frontmatter title, first H1, then readable filename. Navigation uses `navTitle` when supplied. Explicit `order` sorts first; remaining siblings sort deterministically by label and path.
 
 Local `.md` links, extensionless routes, reference links, and images resolve from their source document. A leading slash addresses the documentation root. `basePath` prefixes public links, including `/docs/` and `/repository/docs/`. When a file-style URL matches both an existing supported asset and a page route, the asset wins: `chart.png` selects the image, while `/chart.png/` explicitly selects the page. If no regular asset exists, dotted page routes still resolve. External links are preserved without network requests. Headings have `mdd-`-prefixed GitHub-style slugs; author links such as `#installation` are rewritten to `#mdd-installation`. Duplicate headings receive `-1`, `-2`, and subsequent suffixes.

package/dist/endpoints.d.ts

@@ -0,0 +1,3 @@
+import type { Nodes, Paragraph } from "mdast";
+/** Endpoint signatures are documentation text, never links or executable requests. */
+export declare function endpointParagraph(node: Nodes, source: string, report: (message: string) => void): Paragraph | undefined;

package/dist/endpoints.js

@@ -0,0 +1,68 @@
+const methods = new Set([
+    "GET",
+    "HEAD",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+    "OPTIONS",
+    "TRACE",
+    "CONNECT",
+]);
+/** Endpoint signatures are documentation text, never links or executable requests. */
+export function endpointParagraph(node, source, report) {
+    if (node.type !== "leafDirective") {
+        report('Use the leaf form ::endpoint{method="GET" path="/example"}.');
+        return;
+    }
+    const offset = node.position?.start.offset;
+    if (node.children.length ||
+        (offset !== undefined && source.startsWith("::endpoint[", offset))) {
+        report("The endpoint component does not support a label.");
+        return;
+    }
+    const attributes = node.attributes ?? {};
+    if (Object.keys(attributes).some((key) => key !== "method" && key !== "path")) {
+        report("The endpoint component supports only method and path attributes.");
+        return;
+    }
+    const method = (attributes.method ?? "").toUpperCase();
+    if (!methods.has(method)) {
+        report("The endpoint method must be GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS, TRACE, or CONNECT.");
+        return;
+    }
+    const path = attributes.path ?? "";
+    if (!path.startsWith("/") ||
+        path.startsWith("//") ||
+        // biome-ignore lint/suspicious/noControlCharactersInRegex: Endpoint text cannot contain invisible controls or whitespace.
+        /[\s\u0000-\u001f\u007f-\u009f]/u.test(path)) {
+        report("The endpoint path must start with a single / and contain no whitespace or control characters.");
+        return;
+    }
+    return {
+        type: "paragraph",
+        position: node.position,
+        // Tight lists unwrap ordinary paragraphs; retain the signature's block hook.
+        data: { hName: "div", hProperties: { className: ["mdd-endpoint"] } },
+        children: [
+            {
+                type: "strong",
+                data: {
+                    hProperties: {
+                        className: [
+                            "mdd-endpoint-method",
+                            `mdd-method-${method.toLowerCase()}`,
+                        ],
+                    },
+                },
+                children: [{ type: "text", value: method }],
+            },
+            { type: "text", value: " " },
+            {
+                type: "inlineCode",
+                value: path,
+                data: { hProperties: { className: ["mdd-endpoint-path"] } },
+            },
+        ],
+    };
+}

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { CompileOptions, CompileResult } from "./types.js";
-export { type SearchIndex, type SearchOptions, type SearchPage, type SearchResult, type SearchSection, search, validateSearchIndex, } from "./search.js";
+export { type SearchIndex, type SearchMatch, type SearchOptions, type SearchPage, type SearchResult, type SearchSection, search, validateSearchIndex, } from "./search.js";
 export { createSearchIndex } from "./search-index.js";
 export type { Asset, CompileOptions, CompileResult, Diagnostic, Footer, Heading, Metadata, NavigationItem, Page, Site, SocialLink, Theme, } from "./types.js";
 /** Compile a local checkout; never fetch repositories, execute author code, or emit files. */

package/dist/markdown.js

@@ -13,6 +13,7 @@ import { unified } from "unified";
 import { SKIP, visit } from "unist-util-visit";
 import { parseDocument as parseYaml } from "yaml";
 import { transformAlerts } from "./alerts.js";
+import { endpointParagraph } from "./endpoints.js";
 const parser = unified()
     .use(remarkParse)
     .use(remarkGfm)
@@ -29,10 +30,20 @@ const htmlRenderer = unified()
         ...defaultSchema.attributes,
         aside: [["className", /^mdd-/]],
         details: [["className", "mdd-details"]],
+        div: [["className", "mdd-endpoint"]],
         p: [
             ...(defaultSchema.attributes?.p ?? []),
             ["className", "mdd-component-label"],
         ],
+        strong: [
+            ...(defaultSchema.attributes?.strong ?? []),
+            [
+                "className",
+                "mdd-endpoint-method",
+                /^mdd-method-(get|head|post|put|patch|delete|options|trace|connect)$/,
+            ],
+        ],
+        code: [["className", /^language-./, "mdd-endpoint-path"]],
         summary: [
             ...(defaultSchema.attributes?.summary ?? []),
             ["className", "mdd-component-label"],
@@ -206,8 +217,16 @@ export function parseDocument(source, file, diagnostics) {
             report("REMOVED_COMPONENT", `The ${node.name} directive was removed; use > [!${node.name.toUpperCase()}] followed by quoted body lines. Keep any optional custom title as bold text in the alert body.`, node);
             return;
         }
+        if (node.name === "endpoint") {
+            const paragraph = endpointParagraph(node, source, (message) => report("INVALID_COMPONENT", message, node));
+            if (paragraph && parent && index !== undefined) {
+                parent.children[index] = paragraph;
+                return [SKIP, index];
+            }
+            return;
+        }
         if (node.type !== "containerDirective" || node.name !== "details") {
-            report("UNKNOWN_COMPONENT", `Unsupported component ${node.name}; use a GitHub alert or a details container.`, node);
+            report("UNKNOWN_COMPONENT", `Unsupported component ${node.name}; use a GitHub alert, details container, or endpoint leaf.`, node);
             return;
         }
         if (Object.keys(node.attributes ?? {}).length) {

package/dist/search-index.js

@@ -7,8 +7,9 @@ import { transformAlerts } from "./alerts.js";
 import { validateSearchIndex, } from "./search.js";
 const parser = unified().use(remarkParse).use(remarkGfm);
 const blockTypes = new Set(["paragraph", "code", "tableCell", "listItem"]);
-function indexPage(page) {
+function indexPage(page, breadcrumbs) {
     const sections = [{ title: "", url: page.url, text: "" }];
+    const ancestors = [];
     let headingIndex = 0;
     const chunks = [[]];
     const tree = parser.parse(page.markdown);
@@ -23,11 +24,20 @@ function indexPage(page) {
                 heading.depth !== node.depth) {
                 throw new TypeError("Search indexing requires matching compiled Markdown and headings.");
             }
+            while (ancestors.length &&
+                (ancestors.at(-1)?.depth ?? 0) >= heading.depth)
+                ancestors.pop();
             sections.push({
                 title: heading.text,
                 url: `${page.url}#${encodeURIComponent(heading.id)}`,
                 text: "",
+                breadcrumbs: ancestors
+                    .filter((ancestor) => !(ancestor.depth === 1 &&
+                    ancestor.text.normalize("NFKC").toLowerCase() ===
+                        page.title.normalize("NFKC").toLowerCase()))
+                    .map((ancestor) => ancestor.text),
             });
+            ancestors.push(heading);
             chunks.push([]);
             return SKIP;
         }
@@ -55,12 +65,33 @@ function indexPage(page) {
         url: page.url,
         title: page.title,
         description: page.description ?? "",
+        breadcrumbs,
         sections,
     };
 }
 /** Build only from successfully compiled pages; no source paths or HTML are indexed. */
 export function createSearchIndex(site) {
-    const index = { version: 1, pages: site.pages.map(indexPage) };
+    const navigation = new Map();
+    const pending = site.navigation.map((item) => ({
+        item,
+        ancestors: [],
+    }));
+    while (pending.length) {
+        const entry = pending.pop();
+        if (!entry)
+            break;
+        const { item, ancestors } = entry;
+        if (ancestors.length > 64)
+            throw new TypeError("Search navigation exceeds 64 ancestor labels.");
+        if (item.url)
+            navigation.set(item.url, ancestors);
+        for (const child of item.children ?? [])
+            pending.push({ item: child, ancestors: [...ancestors, item.title] });
+    }
+    const index = {
+        version: 1,
+        pages: site.pages.map((page) => indexPage(page, navigation.get(page.url) ?? [])),
+    };
     index.pages.sort((a, b) => (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
     validateSearchIndex(index);
     return index;

package/dist/search.d.ts

@@ -7,6 +7,8 @@ export interface SearchPage {
     url: string;
     title: string;
     description: string;
+    /** Navigation ancestor labels, excluding this page's own label. */
+    breadcrumbs?: string[];
     sections: SearchSection[];
 }
 export interface SearchSection {
@@ -14,20 +16,37 @@ export interface SearchSection {
     title: string;
     url: string;
     text: string;
+    /** Ancestor headings, excluding this heading and a duplicate page-title H1. */
+    breadcrumbs?: string[];
 }
 export interface SearchOptions {
     /** Maximum results, from 0 to 100. Defaults to 10. */
     limit?: number;
+    /** Defaults to one result per page; sections returns independent heading hits. */
+    mode?: "pages" | "sections";
+    /** Allow one single-edit query correction per result. Requires sections mode. */
+    fuzzy?: boolean;
 }
+/** UTF-16 offsets into the original displayed field; end is exclusive. */
+export type SearchMatch = [start: number, end: number];
 export interface SearchResult {
+    kind: "page" | "section";
     title: string;
     url: string;
+    pageUrl: string;
+    breadcrumbs: string[];
     /** Present when the destination is a compiled heading. */
     section?: string;
     excerpt: string;
     score: number;
+    matches: {
+        title: SearchMatch[];
+        section: SearchMatch[];
+        excerpt: SearchMatch[];
+        breadcrumbs: SearchMatch[][];
+    };
 }
 /** Validate deserialized data before any result can become a link. */
 export declare function validateSearchIndex(value: unknown): asserts value is SearchIndex;
-/** Return at most one hit per page, without filesystem, network, or DOM access. */
+/** Query without filesystem, network, or DOM access; page mode preserves legacy ranking. */
 export declare function search(index: SearchIndex, query: string, options?: SearchOptions): SearchResult[];

package/dist/search.js

@@ -1,6 +1,17 @@
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
+function breadcrumbs(value, maximum) {
+    if (value === undefined)
+        return true;
+    if (!Array.isArray(value) || value.length > maximum)
+        return false;
+    // Iterate holes too: a sparse array does not contain only string labels.
+    for (const label of value)
+        if (typeof label !== "string")
+            return false;
+    return true;
+}
 function pageUrl(value) {
     if (typeof value !== "string" ||
         !value.startsWith("/") ||
@@ -48,6 +59,7 @@ export function validateSearchIndex(value) {
             urls.has(page.url) ||
             typeof page.title !== "string" ||
             typeof page.description !== "string" ||
+            !breadcrumbs(page.breadcrumbs, 64) ||
             !Array.isArray(page.sections))
             throw new TypeError("Invalid search index page.");
         urls.add(page.url);
@@ -57,7 +69,8 @@ export function validateSearchIndex(value) {
                 !sectionUrl(section.url, page.url) ||
                 sections.has(section.url) ||
                 typeof section.title !== "string" ||
-                typeof section.text !== "string")
+                typeof section.text !== "string" ||
+                !breadcrumbs(section.breadcrumbs, 6))
                 throw new TypeError("Invalid search index section.");
             sections.add(section.url);
         }
@@ -70,29 +83,152 @@ function normalize(value) {
         .replace(/[^\p{L}\p{N}\p{M}_]+/gu, " ")
         .trim();
 }
-function excerpt(value) {
-    const characters = Array.from(value.replace(/\s+/gu, " ").trim());
-    return characters.length > 160
-        ? `${characters.slice(0, 159).join("")}…`
-        : characters.join("");
+function contains(value, pattern) {
+    return pattern.whole
+        ? ` ${value} `.includes(` ${pattern.text} `)
+        : value.includes(pattern.text);
 }
-/** Return at most one hit per page, without filesystem, network, or DOM access. */
-export function search(index, query, options = {}) {
-    validateSearchIndex(index);
-    const limit = options.limit ?? 10;
-    if (!Number.isInteger(limit) || limit < 0 || limit > 100) {
-        throw new RangeError("Search limit must be an integer from 0 to 100.");
+function mergeRanges(ranges) {
+    ranges.sort((a, b) => a[0] - b[0] || a[1] - b[1]);
+    const merged = [];
+    for (const range of ranges) {
+        const previous = merged.at(-1);
+        if (previous && range[0] <= previous[1])
+            previous[1] = Math.max(previous[1], range[1]);
+        else
+            merged.push([...range]);
     }
-    if (typeof query !== "string")
-        throw new TypeError("Search query must be a string.");
-    if (query.length > 512)
-        throw new RangeError("Search query must not exceed 512 characters.");
-    const terms = [...new Set(normalize(query).split(" ").filter(Boolean))];
-    const phrase = terms.join(" ");
-    if (terms.length > 32)
-        throw new RangeError("Search query must not exceed 32 unique terms.");
-    if (!terms.length || !limit)
+    return merged;
+}
+/** Map normalized matches to complete original graphemes, including NFKC expansions. */
+function matchRanges(value, patterns, firstOnly = false) {
+    const normalized = value.normalize("NFKC").toLowerCase();
+    const found = [];
+    for (const pattern of patterns) {
+        let offset = 0;
+        while (offset < normalized.length) {
+            const start = normalized.indexOf(pattern.text, offset);
+            if (start < 0)
+                break;
+            const end = start + pattern.text.length;
+            // One neighboring code point needs at most two UTF-16 units. Avoid scanning
+            // a growing prefix for each occurrence, or any boundary work for substrings.
+            if (!pattern.whole ||
+                (!/[\p{L}\p{N}\p{M}_]$/u.test(normalized.slice(Math.max(0, start - 2), start)) &&
+                    !/^[\p{L}\p{N}\p{M}_]/u.test(normalized.slice(end, end + 2)))) {
+                found.push([start, end]);
+                if (firstOnly)
+                    break;
+            }
+            offset = start + 1;
+        }
+    }
+    let ranges = mergeRanges(found);
+    if (!ranges.length)
         return [];
+    if (firstOnly)
+        ranges = ranges.slice(0, 1);
+    const groups = [];
+    for (const { segment, index } of new Intl.Segmenter(undefined, {
+        granularity: "grapheme",
+    }).segment(value)) {
+        let group = {
+            text: segment.normalize("NFKC"),
+            start: index,
+            end: index + segment.length,
+        };
+        // NFKC can combine adjacent graphemes, e.g. compatibility Hangul ㄱㅏ → 가.
+        while (groups.length) {
+            const previous = groups.at(-1);
+            if (!previous)
+                break;
+            const joined = previous.text + group.text;
+            const combined = joined.normalize("NFKC");
+            if (combined === joined)
+                break;
+            groups.pop();
+            group = { text: combined, start: previous.start, end: group.end };
+        }
+        groups.push(group);
+    }
+    // Whole-field lowercase retains contextual letters such as final sigma.
+    // Per-group lowercase supplies only lengths, including expansions like İ.
+    const mapped = [];
+    let offset = 0;
+    let rangeIndex = 0;
+    let originalStart = 0;
+    for (const group of groups) {
+        const next = offset + group.text.toLowerCase().length;
+        let range = ranges[rangeIndex];
+        while (range && range[0] < next) {
+            if (range[0] >= offset)
+                originalStart = group.start;
+            if (range[1] > next)
+                break;
+            mapped.push([originalStart, group.end]);
+            range = ranges[++rangeIndex];
+        }
+        if (!range)
+            break;
+        offset = next;
+    }
+    return mergeRanges(mapped);
+}
+function excerpt(value, patterns) {
+    const text = value.replace(/\s+/gu, " ").trim();
+    const characters = Array.from(text);
+    if (characters.length <= 160)
+        return text;
+    const match = matchRanges(text, patterns, true)[0];
+    const matchStart = match ? Array.from(text.slice(0, match[0])).length : 0;
+    const matchLength = match
+        ? Array.from(text.slice(match[0], match[1])).length
+        : 0;
+    // Reserve room for both ellipses and the matched term before adding context.
+    const context = Math.min(40, Math.max(0, 158 - matchLength));
+    const start = Math.min(Math.max(0, matchStart - context), characters.length - 159);
+    let end = Math.min(characters.length, start + 160 - (start > 0 ? 1 : 0));
+    if (end < characters.length)
+        end--;
+    const startOffset = characters.slice(0, start).join("").length;
+    const endOffset = characters.slice(0, end).join("").length;
+    // Move clipped edges inward to complete graphemes without exceeding the cap.
+    let safeStart = text.length;
+    let safeEnd = 0;
+    for (const { segment, index } of new Intl.Segmenter(undefined, {
+        granularity: "grapheme",
+    }).segment(text)) {
+        if (index >= startOffset && safeStart === text.length)
+            safeStart = index;
+        if (index + segment.length <= endOffset)
+            safeEnd = index + segment.length;
+        if (index >= endOffset)
+            break;
+    }
+    return `${safeStart > 0 ? "…" : ""}${text.slice(safeStart, safeEnd)}${safeEnd < text.length ? "…" : ""}`;
+}
+function candidateUrl(candidate) {
+    return candidate.destination?.url ?? candidate.page.url;
+}
+function compareCandidates(a, b) {
+    const aUrl = candidateUrl(a);
+    const bUrl = candidateUrl(b);
+    return (b.rank - a.rank ||
+        b.score - a.score ||
+        (aUrl < bUrl ? -1 : aUrl > bUrl ? 1 : 0));
+}
+function sourceText(sources, patterns, fallback) {
+    return (sources.find((text) => {
+        const normalized = normalize(text);
+        return patterns.some((pattern) => contains(normalized, pattern));
+    }) ??
+        sources.find((text) => text) ??
+        fallback);
+}
+/** Preserve page-mode weighting, cross-section coverage, and destination selection. */
+function pageCandidates(index, terms) {
+    const phrase = terms.join(" ");
+    const patterns = terms.map((text) => ({ text }));
     const results = [];
     for (const page of index.pages) {
         const title = normalize(page.title);
@@ -131,23 +267,219 @@ export function search(index, query, options = {}) {
         // A stable sort preserves document order when multiple sections tie.
         matches.sort((a, b) => b.score - a.score);
         const best = matches[0]?.section;
-        const destination = metadataMatch ? undefined : best;
         results.push({
-            title: page.title,
-            url: destination?.url ?? page.url,
-            ...(destination?.title ? { section: destination.title } : {}),
-            excerpt: excerpt(best?.text ||
-                page.description ||
-                page.sections.find((section) => section.text)?.text ||
-                page.title),
+            page,
+            destination: metadataMatch ? undefined : best,
+            source: sourceText([
+                best?.text ?? "",
+                page.description,
+                ...page.sections.map((section) => section.text),
+            ], patterns, page.title),
             score: weights.reduce((sum, weight) => sum + weight, 0) +
                 (title === phrase
                     ? 24
                     : sections.some((section) => section.title === phrase)
                         ? 12
                         : 0),
+            rank: 0,
+            patterns,
         });
     }
-    results.sort((a, b) => b.score - a.score || (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
-    return results.slice(0, limit);
+    return results;
+}
+/** Single insertion, deletion, substitution, or adjacent transposition, on code points. */
+function singleEdit(query, token) {
+    if (token.length > 66)
+        return false;
+    const text = Array.from(token);
+    if (Math.abs(query.length - text.length) > 1)
+        return false;
+    let start = 0;
+    while (start < query.length && query[start] === text[start])
+        start++;
+    if (start === Math.min(query.length, text.length))
+        return true;
+    if (query.length === text.length) {
+        if (query.slice(start + 1).join("") === text.slice(start + 1).join(""))
+            return true;
+        return (query[start] === text[start + 1] &&
+            query[start + 1] === text[start] &&
+            query.slice(start + 2).join("") === text.slice(start + 2).join(""));
+    }
+    return query.length > text.length
+        ? query.slice(start + 1).join("") === text.slice(start).join("")
+        : query.slice(start).join("") === text.slice(start + 1).join("");
+}
+function fieldScore(fields, pattern) {
+    return Math.max(0, ...fields
+        .filter((field) => contains(field.text, pattern))
+        .map((field) => field.weight));
+}
+function matchFields(fields, terms, fuzzy, required = []) {
+    const patterns = terms.map((text) => ({ text }));
+    const weights = patterns.map((pattern) => fieldScore(fields, pattern));
+    const missing = weights.flatMap((weight, index) => (weight ? [] : [index]));
+    if (!missing.length)
+        return {
+            patterns,
+            score: weights.reduce((a, b) => a + b, 0),
+            corrected: false,
+        };
+    const missingIndex = missing[0];
+    if (!fuzzy || missing.length !== 1 || missingIndex === undefined)
+        return;
+    const query = Array.from(terms[missingIndex] ?? "");
+    if (query.length < 4 || query.length > 32)
+        return;
+    const needsOwnCorrection = required.length > 0 &&
+        !patterns.some((pattern) => fieldScore(required, pattern));
+    let correction;
+    let correctionWeight = 0;
+    for (const field of fields) {
+        if (field.weight < correctionWeight)
+            continue;
+        for (const token of field.text.split(" ")) {
+            if (singleEdit(query, token) &&
+                (!needsOwnCorrection ||
+                    fieldScore(required, { text: token, whole: true }) > 0) &&
+                (field.weight > correctionWeight ||
+                    correction === undefined ||
+                    token < correction)) {
+                correction = token;
+                correctionWeight = field.weight;
+            }
+        }
+    }
+    if (!correction)
+        return;
+    patterns[missingIndex] = { text: correction, whole: true };
+    weights[missingIndex] = correctionWeight;
+    return {
+        patterns,
+        score: weights.reduce((a, b) => a + b, 0),
+        corrected: true,
+    };
+}
+/** Score only page metadata plus a single coherent section, never sibling bodies. */
+function sectionCandidates(index, terms, fuzzy) {
+    const phrase = terms.join(" ");
+    const results = [];
+    for (const page of index.pages) {
+        const title = normalize(page.title);
+        const metadata = [
+            { text: title, weight: 8 },
+            { text: normalize(page.description), weight: 2 },
+        ];
+        const pageMatch = matchFields(metadata, terms, fuzzy);
+        let pageCandidate;
+        if (pageMatch) {
+            const exact = title === phrase;
+            pageCandidate = {
+                page,
+                source: sourceText([page.description, ...page.sections.map((section) => section.text)], pageMatch.patterns, page.title),
+                score: pageMatch.score + (exact ? 24 : 0),
+                rank: pageMatch.corrected ? 0 : exact ? 2 : 1,
+                patterns: pageMatch.patterns,
+            };
+        }
+        for (const section of page.sections) {
+            const heading = normalize(section.title);
+            const body = normalize(section.text);
+            const ownFields = [
+                { text: heading, weight: 4 },
+                { text: body, weight: 1 },
+            ];
+            const match = matchFields([...metadata, ...ownFields], terms, fuzzy, ownFields);
+            if (!match?.patterns.some((pattern) => fieldScore(ownFields, pattern)))
+                continue;
+            // Repeated page headings without their own matching body add no useful destination.
+            if (pageMatch &&
+                heading === title &&
+                !match.patterns.some((pattern) => contains(body, pattern)))
+                continue;
+            const exact = heading === phrase;
+            const candidate = {
+                page,
+                destination: section.url === page.url ? undefined : section,
+                source: sourceText([section.text, page.description], match.patterns, section.title || page.title),
+                score: match.score + (exact ? 12 : 0),
+                rank: match.corrected ? 0 : exact ? 2 : 1,
+                patterns: match.patterns,
+            };
+            if (candidate.destination)
+                results.push(candidate);
+            else if (!pageCandidate ||
+                compareCandidates(candidate, pageCandidate) < 0)
+                pageCandidate = candidate;
+        }
+        if (pageCandidate)
+            results.push(pageCandidate);
+    }
+    return results;
+}
+// Greater than the largest raw score: 32 terms × weight 8 + title bonus 24.
+const sectionTierWeight = 281;
+function displayResult(candidate) {
+    const { page, destination, patterns } = candidate;
+    const isSection = destination !== undefined && destination.url !== page.url;
+    const trail = isSection
+        ? [
+            ...(page.breadcrumbs ?? []),
+            page.title,
+            ...(destination.breadcrumbs ?? []),
+        ]
+        : [...(page.breadcrumbs ?? [])];
+    const snippet = excerpt(candidate.source, patterns);
+    return {
+        kind: isSection ? "section" : "page",
+        title: page.title,
+        pageUrl: page.url,
+        url: candidateUrl(candidate),
+        ...(destination?.title ? { section: destination.title } : {}),
+        breadcrumbs: trail,
+        excerpt: snippet,
+        score: candidate.rank * sectionTierWeight + candidate.score,
+        matches: {
+            title: matchRanges(page.title, patterns),
+            section: matchRanges(destination?.title ?? "", patterns),
+            excerpt: matchRanges(snippet, patterns),
+            breadcrumbs: trail.map((label) => matchRanges(label, patterns)),
+        },
+    };
+}
+/** Query without filesystem, network, or DOM access; page mode preserves legacy ranking. */
+export function search(index, query, options = {}) {
+    validateSearchIndex(index);
+    if (options === null || typeof options !== "object" || Array.isArray(options))
+        throw new TypeError("Search options must be an object.");
+    const limit = options.limit ?? 10;
+    const mode = options.mode === undefined ? "pages" : options.mode;
+    const fuzzy = options.fuzzy === undefined ? false : options.fuzzy;
+    if (!Number.isInteger(limit) || limit < 0 || limit > 100)
+        throw new RangeError("Search limit must be an integer from 0 to 100.");
+    if (mode !== "pages" && mode !== "sections")
+        throw new RangeError("Search mode must be pages or sections.");
+    if (typeof fuzzy !== "boolean")
+        throw new TypeError("Search fuzzy option must be a boolean.");
+    if (fuzzy && mode !== "sections")
+        throw new RangeError("Fuzzy search requires sections mode.");
+    if (typeof query !== "string")
+        throw new TypeError("Search query must be a string.");
+    if (query.length > 512)
+        throw new RangeError("Search query must not exceed 512 characters.");
+    const terms = [...new Set(normalize(query).split(" ").filter(Boolean))];
+    if (terms.length > 32)
+        throw new RangeError("Search query must not exceed 32 unique terms.");
+    if (!terms.length || !limit)
+        return [];
+    const results = mode === "sections"
+        ? sectionCandidates(index, terms, false)
+        : pageCandidates(index, terms);
+    if (fuzzy && results.length < limit) {
+        const literalUrls = new Set(results.map(candidateUrl));
+        results.push(...sectionCandidates(index, terms, true).filter((candidate) => candidate.rank === 0 && !literalUrls.has(candidateUrl(candidate))));
+    }
+    results.sort(compareCandidates);
+    // Original-text mapping and excerpt windows are computed only for final hits.
+    return results.slice(0, limit).map(displayResult);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wgtechlabs/mdd-engine",
-  "version": "0.1.0-pr.08f3b80",
+  "version": "0.1.0-pr.55ddedf",
   "description": "Headless Markdown documentation compiler for mdd",
   "type": "module",
   "license": "MIT",