@wgtechlabs/mdd-engine 0.1.0 → 0.1.1-dev.51a1fca

package/README.md

@@ -4,7 +4,7 @@ The headless Markdown documentation compiler behind mdd. Give it a local project
 
 Built with TypeScript and Bun. Runs on Node.js 22, 24, and 26 without Bun. The default is the latest Node LTS, currently pinned to **24.21.0**.
 
-> Initial implementation. Publishing to npm and GitHub Packages is configured for eligible pushes to `main`. Verify the first release before using registry installation instructions. See [releasing](docs/RELEASING.md).
+> Build Flow's default channels publish development, PR, and manual preview packages alongside regular releases to npm and GitHub Packages. See [build channels and releasing](docs/RELEASING.md).
 
 ## A documentation project
 
@@ -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/
@@ -38,7 +39,9 @@ All settings are optional. Custom paths are relative to `mdd/config.json` and mu
 
 ## Compile without a website
 
-After installing a locally packed copy of `@wgtechlabs/mdd-engine` in your Node project:
+Install the regular package with `bun add @wgtechlabs/mdd-engine`. After a successful preview publication, use `bun add @wgtechlabs/mdd-engine@dev` for development builds or `bun add @wgtechlabs/mdd-engine@pr` for PRs targeting `dev`. Preview tags track the most recently published package in their channel; install an exact version to test a particular PR. You can also install a locally packed copy.
+
+In your Node project:
 
 ```js
 import { compileProject } from '@wgtechlabs/mdd-engine';
@@ -59,15 +62,47 @@ if (!result.site) {
 
 `site` is absent whenever authoring errors exist. Diagnostics contain a stable code, severity, message, and source location where available. Unexpected filesystem failures reject the promise with context. Identical inputs produce identical output.
 
+Excessive Markdown nesting that exceeds the runtime's call stack produces a `CONTENT_TOO_DEEP` diagnostic identifying the source file.
+
 The result includes:
 
 - `pages`: source, route, public URL, title, description, article HTML, readable Markdown, headings, and navigation metadata.
 - `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 }));
+// [{ 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`:
@@ -80,16 +115,19 @@ order: 1
 ---
 # Installation
 
-:::note[Before you start]
-You need a local documentation project.
-:::
+> [!NOTE]
+> **Before you start**
+>
+> You need a local documentation project.
 
 :::details[More information]
 Ordinary **Markdown** works inside components.
 :::
 ```
 
-Use `note`, `tip`, `warning`, or `details` containers. Labels are optional; attributes and unknown component names are errors. Callouts become semantic `aside` elements, disclosures become `details`/`summary`, and each has a stable `mdd-<component>` class. Readable Markdown uses blockquotes with bold labels, without executable content.
+Use GitHub-style alerts with `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, or `CAUTION`. Put the exact uppercase marker on the opening line of a blockquote at the document root; nested blockquotes remain ordinary quotes. Alerts become semantic `aside` elements with `mdd-alert` and `mdd-<type>` classes. Their readable Markdown preserves the `> [!TYPE]` marker. The engine supplies meaning and labels; the reader composes the article, and themes supply icons and colors.
+
+`:::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.
 
 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.
 
@@ -117,7 +155,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

@@ -0,0 +1,8 @@
+import type { Root } from "mdast";
+declare module "mdast" {
+    interface TextData {
+        mddAlertLabel?: string;
+    }
+}
+/** Recognize alerts only at the document root, using unescaped source syntax. */
+export declare function transformAlerts(tree: Root, source: string): void;

package/dist/alerts.js

@@ -0,0 +1,56 @@
+/** Recognize alerts only at the document root, using unescaped source syntax. */
+export function transformAlerts(tree, source) {
+    for (const node of tree.children) {
+        if (node.type !== "blockquote")
+            continue;
+        const paragraph = node.children[0];
+        const first = paragraph?.type === "paragraph" ? paragraph.children[0] : undefined;
+        const offset = paragraph?.position?.start.offset;
+        if (paragraph?.type !== "paragraph" ||
+            first?.type !== "text" ||
+            offset === undefined ||
+            paragraph.position?.start.line !== node.position?.start.line)
+            continue;
+        const marker = /^\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\][\t ]*(?:\r\n|\r|\n|$)/.exec(source.slice(offset));
+        const kind = marker?.[1];
+        if (!kind)
+            continue;
+        first.value = first.value.slice(kind.length + 3);
+        const bodyStart = paragraph.children[0];
+        if (bodyStart?.type === "text") {
+            bodyStart.value = bodyStart.value.replace(/^[\t ]*(?:\r\n|\r|\n)?/, "");
+            if (!bodyStart.value)
+                paragraph.children.shift();
+        }
+        if (paragraph.children[0]?.type === "break")
+            paragraph.children.shift();
+        if (!paragraph.children.length)
+            node.children.shift();
+        const type = kind.toLowerCase();
+        const label = type.charAt(0).toUpperCase() + type.slice(1);
+        const markerText = {
+            type: "text",
+            value: `[!${kind}]`,
+            data: { mddAlertLabel: label },
+        };
+        node.children.unshift({
+            type: "paragraph",
+            children: [markerText],
+            data: {
+                hProperties: { className: ["mdd-component-label"] },
+                hChildren: [
+                    {
+                        type: "element",
+                        tagName: "strong",
+                        properties: {},
+                        children: [{ type: "text", value: label }],
+                    },
+                ],
+            },
+        });
+        node.data = {
+            hName: "aside",
+            hProperties: { className: ["mdd-alert", `mdd-${type}`] },
+        };
+    }
+}

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 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 { 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",
@@ -13,6 +16,18 @@ const reserved = new Set([
     "robots.txt",
     "404.html",
 ]);
+function nestingDiagnostic(error, file) {
+    // V8 reports this error for excessive nesting in both parsing and rendering.
+    if (!(error instanceof RangeError) ||
+        error.message !== "Maximum call stack size exceeded")
+        throw error;
+    return {
+        severity: "error",
+        code: "CONTENT_TOO_DEEP",
+        message: "Markdown nesting is too deep; reduce nested blocks or formatting.",
+        file,
+    };
+}
 /** Compile a local checkout; never fetch repositories, execute author code, or emit files. */
 export async function compileProject(options) {
     const diagnostics = [];
@@ -34,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) {
@@ -58,7 +85,15 @@ export async function compileProject(options) {
                 file: source,
             });
         routes.set(key, source);
-        const document = parseDocument(await readFile(file, "utf8"), source, diagnostics);
+        const text = await readFile(file, "utf8");
+        let document;
+        try {
+            document = parseDocument(text, source, diagnostics);
+        }
+        catch (error) {
+            diagnostics.push(nestingDiagnostic(error, source));
+            return { diagnostics };
+        }
         sources.push({ file, relative, route, document });
     }
     const assets = await resolveLinks(sources, project, basePath, diagnostics);
@@ -67,7 +102,14 @@ export async function compileProject(options) {
     const pages = [];
     for (const source of sources) {
         const { document } = source;
-        const rendered = await renderDocument(document);
+        let rendered;
+        try {
+            rendered = await renderDocument(document);
+        }
+        catch (error) {
+            diagnostics.push(nestingDiagnostic(error, relativeSource(project.root, source.file)));
+            return { diagnostics };
+        }
         pages.push({
             source: relativeSource(project.root, source.file),
             route: source.route,
@@ -96,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/links.js

@@ -60,8 +60,10 @@ export async function resolveLinks(pages, project, basePath, diagnostics) {
                     throw new AuthoringError("PATH_ESCAPE", "Local links must stay inside the content root");
                 let target = !decoded ? page : byFile.get(targetFile);
                 const extension = path.extname(decoded).toLowerCase();
-                let assetExists = false;
+                let asset = decoded.endsWith("/") ? undefined : assets.get(targetFile);
+                let assetExists = asset !== undefined;
                 if (!target &&
+                    !assetExists &&
                     !decoded.endsWith("/") &&
                     assetExtensions.has(extension)) {
                     try {
@@ -106,21 +108,23 @@ export async function resolveLinks(pages, project, basePath, diagnostics) {
                 if (isImage && [".pdf", ".txt"].includes(extension)) {
                     throw new AuthoringError("INVALID_IMAGE", "Images must reference a supported raster image");
                 }
-                if (!assetExists)
-                    await safeFile(project.contentsRoot, targetFile);
-                const source = relativeSource(project.root, targetFile);
-                const destination = `_assets/${relativeSource(project.contentsRoot, targetFile)}`;
-                const key = destination.normalize("NFC").toLowerCase();
-                const existing = destinations.get(key);
-                if (existing && existing !== source)
-                    throw new AuthoringError("ASSET_COLLISION", `Asset output collides with ${existing}`);
-                destinations.set(key, source);
-                const asset = {
-                    source,
-                    destination,
-                    url: publicUrl(basePath, encodePath(destination)),
-                };
-                assets.set(source, asset);
+                if (!asset) {
+                    if (!assetExists)
+                        await safeFile(project.contentsRoot, targetFile);
+                    const source = relativeSource(project.root, targetFile);
+                    const destination = `_assets/${relativeSource(project.contentsRoot, targetFile)}`;
+                    const key = destination.normalize("NFC").toLowerCase();
+                    const existing = destinations.get(key);
+                    if (existing && existing !== source)
+                        throw new AuthoringError("ASSET_COLLISION", `Asset output collides with ${existing}`);
+                    destinations.set(key, source);
+                    asset = {
+                        source,
+                        destination,
+                        url: publicUrl(basePath, encodePath(destination)),
+                    };
+                    assets.set(targetFile, asset);
+                }
                 node.url =
                     asset.url + query + (hash ? `#${encodeURIComponent(hash)}` : "");
             }
@@ -139,15 +143,6 @@ export async function resolveLinks(pages, project, basePath, diagnostics) {
                         message: `Malformed URL encoding in '${url}'`,
                         ...location,
                     });
-                else if (error instanceof Error &&
-                    "code" in error &&
-                    error.code === "ENOENT")
-                    diagnostics.push({
-                        severity: "error",
-                        code: "MISSING_ASSET",
-                        message: `Asset not found: '${url}'`,
-                        ...location,
-                    });
                 else
                     throw new Error(`Unable to resolve '${url}' in ${location.file}`, {
                         cause: error,

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

@@ -12,6 +12,7 @@ import remarkStringify from "remark-stringify";
 import { unified } from "unified";
 import { SKIP, visit } from "unist-util-visit";
 import { parseDocument as parseYaml } from "yaml";
+import { transformAlerts } from "./alerts.js";
 const parser = unified()
     .use(remarkParse)
     .use(remarkGfm)
@@ -44,8 +45,23 @@ const htmlRenderer = unified()
     },
 })
     .use(rehypeStringify);
-const markdownRenderer = unified().use(remarkGfm).use(remarkStringify);
-const componentNames = new Set(["note", "tip", "warning", "details"]);
+const markdownRenderer = unified()
+    .use(remarkGfm)
+    .use(remarkStringify, {
+    handlers: {
+        text(node, _parent, state, info) {
+            // Only generated alert markers bypass normal Markdown escaping.
+            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();
@@ -99,7 +115,8 @@ 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 = {};
     const headings = [];
@@ -160,6 +177,10 @@ export function parseDocument(source, file, diagnostics) {
     visit(tree, (node, index, parent) => {
         if (node.type === "html") {
             report("RAW_HTML", "Raw HTML is not supported; use Markdown or an mdd component.", node);
+            if (parent && index !== undefined) {
+                parent.children.splice(index, 1);
+                return [SKIP, index];
+            }
         }
         if ((node.type === "link" ||
             node.type === "image" ||
@@ -181,8 +202,12 @@ export function parseDocument(source, file, diagnostics) {
             node.type !== "textDirective") {
             return;
         }
-        if (node.type !== "containerDirective" || !componentNames.has(node.name)) {
-            report("UNKNOWN_COMPONENT", `Unsupported component ${node.name}; use a note, tip, warning, or details container.`, node);
+        if (removedNotices.has(node.name)) {
+            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.type !== "containerDirective" || node.name !== "details") {
+            report("UNKNOWN_COMPONENT", `Unsupported component ${node.name}; use a GitHub alert or a details container.`, node);
             return;
         }
         if (Object.keys(node.attributes ?? {}).length) {
@@ -191,7 +216,7 @@ export function parseDocument(source, file, diagnostics) {
         if (index === undefined || !parent)
             return;
         const first = node.children[0];
-        const defaultLabel = node.name.charAt(0).toUpperCase() + node.name.slice(1);
+        const defaultLabel = "Details";
         const label = first?.type === "paragraph" && first.data?.directiveLabel
             ? first
             : {
@@ -210,7 +235,7 @@ export function parseDocument(source, file, diagnostics) {
         }
         label.children = [{ type: "strong", children: label.children }];
         label.data = {
-            hName: node.name === "details" ? "summary" : "p",
+            hName: "summary",
             hProperties: { className: ["mdd-component-label"] },
         };
         parent.children[index] = {
@@ -218,8 +243,8 @@ export function parseDocument(source, file, diagnostics) {
             children: node.children,
             position: node.position,
             data: {
-                hName: node.name === "details" ? "details" : "aside",
-                hProperties: { className: [`mdd-${node.name}`] },
+                hName: "details",
+                hProperties: { className: ["mdd-details"] },
             },
         };
         // Revisit the replacement so nested content is validated exactly once.
@@ -238,17 +263,8 @@ export function parseDocument(source, file, diagnostics) {
 }
 export async function renderDocument(document) {
     const htmlTree = await htmlRenderer.run(document.tree);
-    const markdownTree = structuredClone(document.tree);
-    visit(markdownTree, (node, index, parent) => {
-        if ((node.type === "html" || node.type === "yaml") &&
-            parent &&
-            index !== undefined) {
-            parent.children.splice(index, 1);
-            return [SKIP, index];
-        }
-    });
     return {
         html: String(htmlRenderer.stringify(htmlTree)),
-        markdown: String(markdownRenderer.stringify(markdownTree)),
+        markdown: String(markdownRenderer.stringify(document.tree)),
     };
 }

package/dist/project.d.ts

@@ -1,12 +1,11 @@
 import type { CompileOptions, Diagnostic, Theme } from "./types.js";
 export interface Project {
     root: string;
-    mddRoot: string;
     contentsRoot: string;
-    themesRoot: string;
     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, mddRoot, contentsRoot, themesRoot, 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,67 @@
+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) {
+    const sections = [{ title: "", url: page.url, text: "" }];
+    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.");
+            }
+            sections.push({
+                title: heading.text,
+                url: `${page.url}#${encodeURIComponent(heading.id)}`,
+                text: "",
+            });
+            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 ?? "",
+        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) };
+    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,33 @@
+/** 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;
+    sections: SearchSection[];
+}
+export interface SearchSection {
+    /** Empty for content before the first heading. */
+    title: string;
+    url: string;
+    text: string;
+}
+export interface SearchOptions {
+    /** Maximum results, from 0 to 100. Defaults to 10. */
+    limit?: number;
+}
+export interface SearchResult {
+    title: string;
+    url: string;
+    /** Present when the destination is a compiled heading. */
+    section?: string;
+    excerpt: string;
+    score: number;
+}
+/** 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. */
+export declare function search(index: SearchIndex, query: string, options?: SearchOptions): SearchResult[];

package/dist/search.js

@@ -0,0 +1,153 @@
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+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" ||
+            !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")
+                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 excerpt(value) {
+    const characters = Array.from(value.replace(/\s+/gu, " ").trim());
+    return characters.length > 160
+        ? `${characters.slice(0, 159).join("")}…`
+        : characters.join("");
+}
+/** 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.");
+    }
+    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 [];
+    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;
+        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),
+            score: weights.reduce((sum, weight) => sum + weight, 0) +
+                (title === phrase
+                    ? 24
+                    : sections.some((section) => section.title === phrase)
+                        ? 12
+                        : 0),
+        });
+    }
+    results.sort((a, b) => b.score - a.score || (a.url < b.url ? -1 : a.url > b.url ? 1 : 0));
+    return results.slice(0, limit);
+}

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",
+  "version": "0.1.1-dev.51a1fca",
   "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",