@wgtechlabs/mdd-engine 0.1.0-dev.3c34eeb → 0.1.0-dev.8884a23

package/README.md

@@ -12,6 +12,7 @@ Built with TypeScript and Bun. Runs on Node.js 22, 24, and 26 without Bun. The d
 my-project/
   mdd/
     config.json           # optional
+    footer.md             # optional shared social links
     contents/
       index.md            # required homepage
       get-started/
@@ -69,9 +70,43 @@ The result includes:
 - `navigation`: sorted folder/page tree, with optional landing URLs.
 - `assets`: referenced content files with checkout-relative sources, documentation-root-relative destinations, and public URLs.
 - `theme`: the built-in default or selected theme file locations.
+- `footer`: optional shared footer source and validated social-link data.
 
 Paths in the model use forward slashes. Resolve sources against the same `projectDir` used to compile. Asset destinations are filesystem paths, while asset URLs and page routes are URL-encoded. Decode page-route segments when deriving output directories. Prefix asset destinations with the documentation output directory when exporting; do not prefix them with a GitHub repository name a second time. The engine emits no files and starts no server.
 
+## Headless search
+
+Build a serializable index from a successful compilation:
+
+```js
+import { createSearchIndex } from '@wgtechlabs/mdd-engine';
+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 }]
+```
+
+The dependency-free `/search` entry point works in browsers and Node. Results reuse compiled page URLs and heading anchors, respect the public base path, and contain plain text for the consuming interface to display safely. MDD owns exporting/loading the index and presenting search controls. See [search matching, limits, and validation](docs/SEARCH.md).
+
+## Shared social footer
+
+Write social links once in `mdd/footer.md`:
+
+```markdown
+:::socials
+- [GitHub](https://github.com/wgtechlabs)
+- [Community](https://example.org/community)
+:::
+```
+
+The engine returns these as `site.footer.socials`, with plain labels and validated absolute HTTPS URLs. It does not render a footer or select icons. MDD composes the main footer and its theme styles it. This file is excluded from pages, navigation, and search; `socials` is not an article component. See the [footer format and boundaries](docs/FOOTER.md).
+
 ## Markdown and components
 
 Supported Markdown includes headings, lists, code fences, links, images, GFM tables, task lists, and strikethrough. Optional YAML frontmatter supports `title`, `description`, `navTitle`, and finite numeric `order`:
@@ -98,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.
@@ -124,7 +173,7 @@ bun run coverage
 bun audit
 ```
 
-`bun run build` emits Node ESM and TypeScript declarations to `dist/`. `bun run smoke` creates a package archive, installs it into an isolated consumer, and runs it with the current Node binary. It checks that Bun is unavailable inside the consumer and that all three base-path fixtures compile. On POSIX systems, `MDD_TEST_NODE_BINARIES` can contain colon-separated Node binary paths to exercise the same archive across versions.
+`bun run build` emits Node ESM and TypeScript declarations to `dist/`. `bun run smoke` creates a package archive, installs it into an isolated consumer, and runs it with the current Node binary. It checks compilation, footer data, and serialized search at all three base paths without Bun in the runtime, and bundles the isolated search entry for browsers. On POSIX systems, `MDD_TEST_NODE_BINARIES` can contain colon-separated Node binary paths to exercise the same archive across versions.
 
 Follow [Clean Workflow](AGENTS.md), [contributing](CONTRIBUTING.md), and the [engine contract](docs/SPEC.md). See [verification](docs/VERIFICATION.md) for the checks performed during bootstrap.
 

package/dist/alerts.d.ts

@@ -1,7 +1,7 @@
 import type { Root } from "mdast";
 declare module "mdast" {
     interface TextData {
-        mddAlertMarker?: true;
+        mddAlertLabel?: string;
     }
 }
 /** Recognize alerts only at the document root, using unescaped source syntax. */

package/dist/alerts.js

@@ -31,7 +31,7 @@ export function transformAlerts(tree, source) {
         const markerText = {
             type: "text",
             value: `[!${kind}]`,
-            data: { mddAlertMarker: true },
+            data: { mddAlertLabel: label },
         };
         node.children.unshift({
             type: "paragraph",

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/footer.d.ts

@@ -0,0 +1,3 @@
+import type { Diagnostic, Footer } from "./types.js";
+/** The shared footer is data, never an article or executable author markup. */
+export declare function parseFooter(source: string, file: string, diagnostics: Diagnostic[]): Footer | undefined;

package/dist/footer.js

@@ -0,0 +1,82 @@
+import { parseMarkdown } from "./markdown.js";
+function socialUrl(value) {
+    // Reject URL normalization that could hide a scheme, credentials, or controls.
+    if (!/^https:\/\/[^/?#]/i.test(value) || /[\s\\\p{Cc}\p{Cf}]/u.test(value))
+        return undefined;
+    try {
+        const url = new URL(value);
+        if (url.protocol !== "https:" ||
+            !url.hostname ||
+            url.username ||
+            url.password)
+            return undefined;
+        return url.href;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The shared footer is data, never an article or executable author markup. */
+export function parseFooter(source, file, diagnostics) {
+    if (!source.trim())
+        return undefined;
+    const tree = parseMarkdown(source);
+    const report = (code, message, node) => {
+        diagnostics.push({
+            severity: "error",
+            code,
+            message,
+            file,
+            line: node.position?.start.line,
+            column: node.position?.start.column,
+        });
+    };
+    const component = tree.children[0];
+    if (tree.children.length !== 1 ||
+        component?.type !== "containerDirective" ||
+        component.name !== "socials" ||
+        Object.keys(component.attributes ?? {}).length) {
+        report("INVALID_FOOTER", "Use a single :::socials block without attributes in footer.md.", component ?? tree);
+        return undefined;
+    }
+    const list = component.children[0];
+    if (component.children.length !== 1 ||
+        list?.type !== "list" ||
+        list.ordered ||
+        !list.children.length) {
+        report("INVALID_FOOTER", "The socials block must contain an unordered list of labeled Markdown links.", list ?? component);
+        return undefined;
+    }
+    const socials = [];
+    for (const item of list.children) {
+        const paragraph = item.children[0];
+        const link = paragraph?.type === "paragraph" ? paragraph.children[0] : undefined;
+        if (item.children.length !== 1 ||
+            item.checked != null ||
+            paragraph?.type !== "paragraph" ||
+            paragraph.children.length !== 1 ||
+            link?.type !== "link" ||
+            !link.children.length ||
+            link.children.some((child) => child.type !== "text")) {
+            report("INVALID_SOCIAL_LINK", "Each item must be one Markdown link with a plain text label, without tasks or nested content.", item);
+            continue;
+        }
+        const label = link.children
+            .map((child) => (child.type === "text" ? child.value : ""))
+            .join("")
+            .trim();
+        if (!label) {
+            report("INVALID_SOCIAL_LINK", "Social links need a nonempty label.", link);
+            continue;
+        }
+        const url = socialUrl(link.url);
+        if (!url) {
+            report("UNSAFE_SOCIAL_URL", "Social links must use absolute HTTPS URLs without credentials, whitespace, controls, or backslashes.", link);
+            continue;
+        }
+        socials.push({ label, url });
+    }
+    return socials.length === list.children.length
+        ? { source: file, socials }
+        : undefined;
+}

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import type { CompileOptions, CompileResult } from "./types.js";
-export type { Asset, CompileOptions, CompileResult, Diagnostic, Heading, Metadata, NavigationItem, Page, Site, Theme, } from "./types.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. */
 export declare function compileProject(options: CompileOptions): Promise<CompileResult>;

package/dist/index.js

@@ -1,8 +1,11 @@
 import { readFile } from "node:fs/promises";
+import { parseFooter } from "./footer.js";
 import { resolveLinks } from "./links.js";
 import { parseDocument, renderDocument, } from "./markdown.js";
 import { loadProject, relativeSource } from "./project.js";
 import { navigationFor, normalizeBasePath, publicUrl, routeFor, } from "./routes.js";
+export { search, validateSearchIndex, } from "./search.js";
+export { createSearchIndex } from "./search-index.js";
 const reserved = new Set([
     "_assets",
     "_mdd",
@@ -46,6 +49,18 @@ export async function compileProject(options) {
     const project = await loadProject(options, diagnostics);
     if (!project)
         return { diagnostics };
+    let footer;
+    if (project.footer) {
+        const source = relativeSource(project.root, project.footer);
+        const text = await readFile(project.footer, "utf8");
+        try {
+            footer = parseFooter(text, source, diagnostics);
+        }
+        catch (error) {
+            diagnostics.push(nestingDiagnostic(error, source));
+            return { diagnostics };
+        }
+    }
     const sources = [];
     const routes = new Map();
     for (const file of project.files) {
@@ -123,6 +138,7 @@ export async function compileProject(options) {
             navigation: navigationFor(pages, sources.map((source) => source.relative)),
             assets,
             theme: project.theme,
+            ...(footer ? { footer } : {}),
         },
         diagnostics,
     };

package/dist/markdown.d.ts

@@ -6,6 +6,8 @@ export interface ParsedDocument {
     title: string;
     headings: Heading[];
 }
+/** Shared syntax parser; callers validate the allowed document context. */
+export declare function parseMarkdown(source: string): Root;
 export declare function parseDocument(source: string, file: string, diagnostics: Diagnostic[]): ParsedDocument;
 export declare function renderDocument(document: ParsedDocument): Promise<{
     html: string;

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"],
@@ -51,13 +62,17 @@ const markdownRenderer = unified()
     handlers: {
         text(node, _parent, state, info) {
             // Only generated alert markers bypass normal Markdown escaping.
-            return node.data?.mddAlertMarker === true
+            return node.data?.mddAlertLabel !== undefined
                 ? node.value
                 : state.safe(node.value, info);
         },
     },
 });
 const removedNotices = new Set(["note", "tip", "warning"]);
+/** Shared syntax parser; callers validate the allowed document context. */
+export function parseMarkdown(source) {
+    return parser.parse(source);
+}
 /** Keep the same first-wins, reachable definitions that the HTML renderer uses. */
 function retainReferencedDefinitions(tree) {
     const definitions = new Map();
@@ -111,7 +126,7 @@ function unsafeUrl(url, image) {
         !(image ? ["http", "https"] : ["http", "https", "mailto", "tel"]).includes(scheme));
 }
 export function parseDocument(source, file, diagnostics) {
-    const tree = parser.parse(source);
+    const tree = parseMarkdown(source);
     transformAlerts(tree, source);
     retainReferencedDefinitions(tree);
     const metadata = {};
@@ -202,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/project.d.ts

@@ -5,6 +5,7 @@ export interface Project {
     title?: string;
     theme: Theme;
     files: string[];
+    footer?: string;
 }
 export declare class AuthoringError extends Error {
     readonly code: string;

package/dist/project.js

@@ -139,7 +139,7 @@ async function optionalFile(root, file) {
     }
     return safeFile(root, file);
 }
-async function scan(root) {
+async function scan(root, excludedFile) {
     const files = [];
     async function walk(directory) {
         const entries = await readdir(directory, { withFileTypes: true }).catch((error) => {
@@ -156,6 +156,8 @@ async function scan(root) {
             if (entry.isSymbolicLink()) {
                 throw new AuthoringError("CONTENT_SYMLINK", `Content discovery does not follow symlinks: ${file}`);
             }
+            if (file === excludedFile)
+                continue;
             if (entry.isDirectory())
                 await walk(file);
             else if (path.extname(entry.name).toLowerCase() === ".md")
@@ -174,6 +176,12 @@ export async function loadProject(options, diagnostics) {
             throw new Error(`Cannot resolve project directory ${options.projectDir}`, { cause: error });
         });
         const mddRoot = await directory(root, relativePath(options.mddDir ?? "mdd", "mddDir"));
+        const footerPath = path.join(mddRoot, "footer.md");
+        source = relativeSource(root, footerPath);
+        const footer = await optionalFile(root, footerPath);
+        if (footer && (await lstat(footerPath)).isSymbolicLink()) {
+            throw new AuthoringError("FOOTER_SYMLINK", "The shared footer must be a regular file, not a symlink.");
+        }
         const configPath = path.join(mddRoot, "config.json");
         source = relativeSource(root, configPath);
         const configFile = await optionalFile(root, configPath);
@@ -229,14 +237,21 @@ export async function loadProject(options, diagnostics) {
             };
         }
         source = relativeSource(root, contentsRoot);
-        const files = await scan(contentsRoot);
+        const files = await scan(contentsRoot, footer ?? footerPath);
         if (!files.includes(path.join(contentsRoot, "index.md"))) {
             source = relativeSource(root, path.join(contentsRoot, "index.md"));
             throw new AuthoringError("MISSING_HOME", "The content root must contain an index.md homepage.");
         }
         if (diagnostics.some((diagnostic) => diagnostic.severity === "error"))
             return undefined;
-        return { root, contentsRoot, title, theme, files };
+        return {
+            root,
+            contentsRoot,
+            title,
+            theme,
+            files,
+            ...(footer ? { footer } : {}),
+        };
     }
     catch (error) {
         if (!(error instanceof AuthoringError))

package/dist/search-index.d.ts

@@ -0,0 +1,4 @@
+import { type SearchIndex } from "./search.js";
+import type { Site } from "./types.js";
+/** Build only from successfully compiled pages; no source paths or HTML are indexed. */
+export declare function createSearchIndex(site: Site): SearchIndex;

package/dist/search-index.js

@@ -0,0 +1,98 @@
+import { toString as nodeText } from "mdast-util-to-string";
+import remarkGfm from "remark-gfm";
+import remarkParse from "remark-parse";
+import { unified } from "unified";
+import { SKIP, visit } from "unist-util-visit";
+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, breadcrumbs) {
+    const sections = [{ title: "", url: page.url, text: "" }];
+    const ancestors = [];
+    let headingIndex = 0;
+    const chunks = [[]];
+    const tree = parser.parse(page.markdown);
+    transformAlerts(tree, page.markdown);
+    visit(tree, (node) => {
+        if (node.type === "definition" || node.type === "html")
+            return SKIP;
+        if (node.type === "heading") {
+            const heading = page.headings[headingIndex++];
+            if (!heading ||
+                heading.text !== nodeText(node) ||
+                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;
+        }
+        const text = chunks[chunks.length - 1];
+        if (!text)
+            return;
+        if (blockTypes.has(node.type) || node.type === "break")
+            text.push(" ");
+        if (node.type === "text" ||
+            node.type === "code" ||
+            node.type === "inlineCode")
+            text.push(node.type === "text"
+                ? (node.data?.mddAlertLabel ?? node.value)
+                : node.value);
+        if ((node.type === "image" || node.type === "imageReference") && node.alt)
+            text.push(node.alt);
+    });
+    if (headingIndex !== page.headings.length) {
+        throw new TypeError("Search indexing requires matching compiled Markdown and headings.");
+    }
+    sections.forEach((entry, index) => {
+        entry.text = (chunks[index] ?? []).join("").replace(/\s+/gu, " ").trim();
+    });
+    return {
+        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 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

@@ -0,0 +1,52 @@
+/** Versioned, JSON-serializable input for the browser-safe search API. */
+export interface SearchIndex {
+    version: 1;
+    pages: SearchPage[];
+}
+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 {
+    /** Empty for content before the first heading. */
+    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;
+/** 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

@@ -0,0 +1,485 @@
+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("/") ||
+        value.startsWith("//") ||
+        !value.endsWith("/") ||
+        /[?#\\\s\p{Cc}]/u.test(value))
+        return false;
+    try {
+        const parsed = new URL(value, "https://mdd.invalid");
+        return (parsed.pathname === value &&
+            value.split("/").every((part) => {
+                const decoded = decodeURIComponent(part);
+                return (decoded !== "." && decoded !== ".." && !/[/\\\p{Cc}]/u.test(decoded));
+            }));
+    }
+    catch {
+        return false;
+    }
+}
+function sectionUrl(value, page) {
+    if (value === page)
+        return true;
+    if (typeof value !== "string" || !value.startsWith(`${page}#`))
+        return false;
+    try {
+        const fragment = value.slice(page.length + 1);
+        const id = decodeURIComponent(fragment);
+        return (id.startsWith("mdd-") &&
+            !/\p{Cc}/u.test(id) &&
+            fragment === encodeURIComponent(id));
+    }
+    catch {
+        return false;
+    }
+}
+/** Validate deserialized data before any result can become a link. */
+export function validateSearchIndex(value) {
+    if (!record(value) || value.version !== 1 || !Array.isArray(value.pages)) {
+        throw new TypeError("Invalid search index: expected version 1 and pages.");
+    }
+    const urls = new Set();
+    for (const page of value.pages) {
+        if (!record(page) ||
+            !pageUrl(page.url) ||
+            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);
+        const sections = new Set();
+        for (const section of page.sections) {
+            if (!record(section) ||
+                !sectionUrl(section.url, page.url) ||
+                sections.has(section.url) ||
+                typeof section.title !== "string" ||
+                typeof section.text !== "string" ||
+                !breadcrumbs(section.breadcrumbs, 6))
+                throw new TypeError("Invalid search index section.");
+            sections.add(section.url);
+        }
+    }
+}
+function normalize(value) {
+    return value
+        .normalize("NFKC")
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\p{M}_]+/gu, " ")
+        .trim();
+}
+function contains(value, pattern) {
+    return pattern.whole
+        ? ` ${value} `.includes(` ${pattern.text} `)
+        : value.includes(pattern.text);
+}
+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]);
+    }
+    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);
+        const description = normalize(page.description);
+        const sections = page.sections.map((section) => ({
+            section,
+            title: normalize(section.title),
+            text: normalize(section.text),
+        }));
+        const weights = terms.map((term) => {
+            if (title.includes(term))
+                return 8;
+            if (sections.some((section) => section.title.includes(term)))
+                return 4;
+            if (description.includes(term))
+                return 2;
+            return sections.some((section) => section.text.includes(term)) ? 1 : 0;
+        });
+        if (weights.some((weight) => weight === 0))
+            continue;
+        const metadataMatch = terms.every((term) => title.includes(term) || description.includes(term));
+        const matches = sections
+            .map((entry) => ({
+            ...entry,
+            score: terms.reduce((score, term) => score +
+                (entry.title.includes(term)
+                    ? 4
+                    : entry.text.includes(term)
+                        ? 1
+                        : 0), 0),
+        }))
+            .filter((entry) => terms.every((term) => title.includes(term) ||
+            description.includes(term) ||
+            entry.title.includes(term) ||
+            entry.text.includes(term)));
+        // A stable sort preserves document order when multiple sections tie.
+        matches.sort((a, b) => b.score - a.score);
+        const best = matches[0]?.section;
+        results.push({
+            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,
+        });
+    }
+    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/dist/types.d.ts

@@ -54,6 +54,15 @@ export type Theme = {
     css: string;
     js?: string;
 };
+export interface SocialLink {
+    label: string;
+    url: string;
+}
+export interface Footer {
+    /** POSIX path relative to projectDir; not a documentation page. */
+    source: string;
+    socials: SocialLink[];
+}
 export interface Site {
     title: string;
     basePath: string;
@@ -61,6 +70,7 @@ export interface Site {
     navigation: NavigationItem[];
     assets: Asset[];
     theme: Theme;
+    footer?: Footer;
 }
 export interface CompileOptions {
     projectDir: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wgtechlabs/mdd-engine",
-  "version": "0.1.0-dev.3c34eeb",
+  "version": "0.1.0-dev.8884a23",
   "description": "Headless Markdown documentation compiler for mdd",
   "type": "module",
   "license": "MIT",
@@ -18,6 +18,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
+    },
+    "./search": {
+      "types": "./dist/search.d.ts",
+      "import": "./dist/search.js"
     }
   },
   "types": "./dist/index.d.ts",