@vmz/vmz 0.3.11 → 0.3.13

package/dist/document/document-build.js

@@ -4,9 +4,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { checkDocuments, manifestHasErrors } from './document-check.js';
+import { DOCUMENT_BASE_CSS } from './document-base-css.js';
+import { DOCUMENT_CLIENT_HREF, DOCUMENT_CLIENT_JS } from './document-client.js';
 import { resolveDocumentDesignsCss } from './document-designs.js';
-import { enrichDocumentContent, pageHtmlRel } from './document-enrich.js';
+import { enrichDocumentContent, pageHtmlRel, pageRoute, routeHrefForDocLink } from './document-enrich.js';
 import { enrichDocumentEvidence } from './document-evidence.js';
+import { resolveDocumentCodeHighlighter } from './document-highlight.js';
 import { artifactHrefFromHtml, buildDocumentIslands, buildDocumentSearch, collectFenceBodies, renderIslandShellsHtml, } from './document-interactive.js';
 import { assertIntegratedDistReady, renderCompiledDocumentLayout } from './document-layout-render.js';
 import { resolveMarkdownEngine } from './document-markdown.js';
@@ -39,11 +42,19 @@ export async function buildDocuments(opts) {
         return { ok: false, manifest, outDir, pages: [] };
     }
     const analyzedByPageId = new Map();
+    const highlighter = await resolveDocumentCodeHighlighter({ code: opts.engines?.code }, manifest.diagnostics);
+    const pageKeySet = new Map();
+    for (const p of manifest.pages) {
+        const set = pageKeySet.get(p.identity.locale) || new Set();
+        set.add(p.identity.pageKey);
+        pageKeySet.set(p.identity.locale, set);
+    }
     for (const page of manifest.pages) {
         const abs = path.isAbsolute(page.sourcePath) ? page.sourcePath : path.join(manifest.root, page.sourcePath);
         const source = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : '';
         const id = `${page.identity.locale}:${page.identity.pageKey}`;
-        analyzedByPageId.set(id, engine.analyzeMarkdown(source));
+        const hooks = documentRenderHooks(page, enriched.routeBase, pageKeySet, routing, highlighter);
+        analyzedByPageId.set(id, engine.analyzeMarkdown(source, hooks));
     }
     const fenceBodies = collectFenceBodies(analyzedByPageId, manifest.pages);
     const search = buildDocumentSearch({
@@ -67,12 +78,20 @@ export async function buildDocuments(opts) {
     }
     fs.mkdirSync(outDir, { recursive: true });
     const designs = resolveDocumentDesignsCss(projectRoot, appDistDir);
-    let designsHref = null;
-    if (designs.css && designs.href) {
-        const cssPath = path.join(outDir, designs.href);
+    // Framework document base always emits; site token bundle emits when the
+    // project has compiled tokens (integrated) or a `designs/styles/index.css`
+    // entry (standalone).
+    const baseCssPath = path.join(outDir, designs.baseHref);
+    fs.mkdirSync(path.dirname(baseCssPath), { recursive: true });
+    fs.writeFileSync(baseCssPath, DOCUMENT_BASE_CSS, 'utf8');
+    // Framework client enhancement (search + copy) ships with every build.
+    const clientPath = path.join(outDir, DOCUMENT_CLIENT_HREF);
+    fs.mkdirSync(path.dirname(clientPath), { recursive: true });
+    fs.writeFileSync(clientPath, DOCUMENT_CLIENT_JS, 'utf8');
+    if (designs.tokensCss && designs.tokensHref) {
+        const cssPath = path.join(outDir, designs.tokensHref);
         fs.mkdirSync(path.dirname(cssPath), { recursive: true });
-        fs.writeFileSync(cssPath, designs.css, 'utf8');
-        designsHref = designs.href;
+        fs.writeFileSync(cssPath, designs.tokensCss, 'utf8');
     }
     const viewsDir = path.join(outDir, 'views');
     fs.mkdirSync(viewsDir, { recursive: true });
@@ -82,6 +101,10 @@ export async function buildDocuments(opts) {
         const info = enriched.byId.get(id);
         if (!info)
             continue;
+        // Render-pass HTML: fences highlighted and author links rewritten to
+        // route form (validation already ran on the author form in enrich).
+        const rendered = analyzedByPageId.get(id);
+        const bodyHtml = rendered?.html ?? info.html;
         const nav = enriched.navByLocale[page.identity.locale] || [];
         const htmlRel = pageHtmlRel(enriched.routeBase, page.identity.locale, page.identity.pageKey);
         const htmlAbs = path.join(outDir, htmlRel);
@@ -95,10 +118,12 @@ export async function buildDocuments(opts) {
         });
         const slotHtml = buildDocumentSlotHtml({
             nav,
-            bodyHtml: info.html,
+            bodyHtml,
             headings: info.headings,
-            htmlRel,
+            title: info.title,
             route: info.route,
+            routeBase: enriched.routeBase,
+            locale: page.identity.locale,
             routing,
             searchShellHtml: shells.searchHtml,
             playgroundShellHtml: shells.playgroundHtml,
@@ -116,8 +141,10 @@ export async function buildDocuments(opts) {
             headings: info.headings,
             nav,
             bodyKind: 'html',
-            html: info.html,
-            designsCss: designsHref,
+            html: bodyHtml,
+            designsCss: designs.tokensHref,
+            documentCss: designs.baseHref,
+            clientJs: DOCUMENT_CLIENT_HREF,
             noJsReadable: true,
             hydrate: 'island-only',
             hostShell: useCompiledShell ? 'compiled-layout' : false,
@@ -135,14 +162,9 @@ export async function buildDocuments(opts) {
             title: info.title,
             locale: page.identity.locale,
             route: info.route,
-            nav,
-            bodyHtml: info.html,
-            headings: info.headings,
-            designsHref,
-            htmlRel,
-            searchShellHtml: shells.searchHtml,
-            playgroundShellHtml: shells.playgroundHtml,
-            routing,
+            slotHtml,
+            tokensHref: designs.tokensHref,
+            baseHref: designs.baseHref,
             compiledLayoutHtml,
             useCompiledShell,
         });
@@ -159,7 +181,9 @@ export async function buildDocuments(opts) {
             engine: engine.engine,
             outDir: path.relative(projectRoot, outDir).replace(/\\/g, '/') || '.',
             designs: designs.source,
-            designsCss: designsHref,
+            designsCss: designs.tokensHref,
+            documentCss: designs.baseHref,
+            clientJs: DOCUMENT_CLIENT_HREF,
             hostShell: useCompiledShell ? 'compiled-layout' : 'standalone',
             pages: written,
             evidence: 'document.evidence.json',
@@ -180,22 +204,36 @@ function resolveAppDistDir(opts, outDir) {
     }
     return fs.existsSync(path.join(outDir, 'vmz-dom.js')) ? outDir : null;
 }
-/** Document main column + sidebar (injected into DocumentLayout slot). */
-function buildDocumentSlotHtml({ nav, bodyHtml, headings, htmlRel, route, routing, searchShellHtml = '', playgroundShellHtml = '', }) {
+/** Document-layer chrome copy, localized by page locale (normal case, no decorative micro labels). */
+function docUiCopy(locale) {
+    return locale.startsWith('zh')
+        ? { home: '首页', docs: '文档', toc: '本页内容' }
+        : { home: 'Home', docs: 'Documentation', toc: 'On this page' };
+}
+/**
+ * Document main column + sidebar (injected into the DocumentLayout slot;
+ * standalone mounts wrap the same markup — one DOM shape, one stylesheet).
+ * In-site links are route-form (`/d/<locale>/<pageKey>`), identical to
+ * application routes — no `.html` file paths leak into the page.
+ */
+function buildDocumentSlotHtml({ nav, bodyHtml, headings, title, route, routeBase, locale, routing, searchShellHtml = '', playgroundShellHtml = '', }) {
     const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+    const copy = docUiCopy(locale);
     const navItems = nav
         .map((n) => {
-        const href = routing.strategy === 'none' || routing.strategy === 'domain' ? n.href : relativeHref(htmlRel, n.href, route);
         const current = n.href === route ? ' aria-current="page"' : '';
-        return `      <li><a href="${esc(href)}"${current}>${esc(n.title)}</a></li>`;
+        return `      <li><a href="${esc(n.href)}"${current}>${esc(n.title)}</a></li>`;
     })
         .join('\n');
     const toc = headings.length > 1
-        ? `<nav aria-label="On this page" class="toc">\n    <ol>\n${headings
+        ? `<nav aria-label="${esc(copy.toc)}" class="toc">\n    <p class="toc__label">${esc(copy.toc)}</p>\n    <ol>\n${headings
             .map((h) => `      <li class="h${h.level}"><a href="#${esc(h.id)}">${esc(h.text)}</a></li>`)
             .join('\n')}\n    </ol>\n  </nav>\n`
         : '';
-    const docsNav = `  <nav aria-label="Documents" class="doc-subnav">
+    const docsRoot = pageRoute(routeBase, locale, 'index', routing);
+    const breadcrumb = `<nav class="doc-breadcrumb" aria-label="Breadcrumb"><a href="/">${esc(copy.home)}</a><span aria-hidden="true"> / </span><a href="${esc(docsRoot)}">${esc(copy.docs)}</a><span aria-hidden="true"> / </span><span aria-current="page">${esc(title)}</span></nav>`;
+    const docsNav = `  <p class="doc-sidebar__label">${esc(copy.docs)}</p>
+  <nav aria-label="Documents" class="doc-subnav">
     <ul>
 ${navItems}
     </ul>
@@ -206,55 +244,40 @@ ${searchShellHtml}
     </aside>
     <div class="doc-content">
   ${toc}<main id="main">
+${breadcrumb}
 ${bodyHtml}
 ${playgroundShellHtml}
   </main>
     </div>`;
 }
 /**
- * No-JS readable static HTML: nav + main landmarks, Island shells without scripts.
- * Integrated mounts wrap content in compiled DocumentLayout (SiteHeader/SiteFooter SSR).
+ * No-JS readable static HTML: nav + main landmarks, Island shells, and exactly
+ * one deferred framework enhancement module (`assets/vmz-document.js` — search
+ * filter + copy buttons). Integrated mounts wrap content in compiled
+ * DocumentLayout (SiteHeader/SiteFooter SSR); standalone mounts emit the same
+ * `.site.site--docs > .doc-body` skeleton themselves.
  */
-function renderStaticHtml({ title, locale, route, nav, bodyHtml, headings, designsHref, htmlRel, searchShellHtml = '', playgroundShellHtml = '', routing = { strategy: 'prefix' }, compiledLayoutHtml, useCompiledShell = false, }) {
-    const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-    const depth = htmlRel.split('/').length - 1;
-    const prefix = depth > 0 ? '../'.repeat(depth) : './';
+function renderStaticHtml({ title, locale, slotHtml, tokensHref, baseHref, compiledLayoutHtml, useCompiledShell = false, }) {
     const cssHrefs = [];
     if (useCompiledShell) {
         cssHrefs.push('/vmz.css');
     }
-    if (designsHref)
-        cssHrefs.push(useCompiledShell ? `/${designsHref}` : prefix + designsHref);
-    let bodyInner;
-    if (useCompiledShell) {
-        bodyInner = compiledLayoutHtml || '';
-    }
-    else {
-        const navItems = nav
-            .map((n) => {
-            const href = routing.strategy === 'none' || routing.strategy === 'domain' ? n.href : relativeHref(htmlRel, n.href, route);
-            const current = n.href === route ? ' aria-current="page"' : '';
-            return `      <li><a href="${esc(href)}"${current}>${esc(n.title)}</a></li>`;
-        })
-            .join('\n');
-        const toc = headings.length > 1
-            ? `<nav aria-label="On this page" class="toc">\n    <ol>\n${headings
-                .map((h) => `      <li class="h${h.level}"><a href="#${esc(h.id)}">${esc(h.text)}</a></li>`)
-                .join('\n')}\n    </ol>\n  </nav>\n`
-            : '';
-        bodyInner = `  <a class="skip-link" href="#main">Skip to content</a>
-  <nav aria-label="Documents" class="doc-subnav">
-    <ul>
-${navItems}
-    </ul>
-  </nav>
-${searchShellHtml}
-  ${toc}<main id="main">
-${bodyHtml}
-${playgroundShellHtml}
-  </main>
+    // Absolute hrefs: document pages are served under the mount root by the
+    // same host as the app (integrated) or as the site root (standalone).
+    if (tokensHref)
+        cssHrefs.push(`/${tokensHref}`);
+    cssHrefs.push(`/${baseHref}`);
+    const enhancement = `<script type="module" src="/${DOCUMENT_CLIENT_HREF}"></script>`;
+    const bodyInner = useCompiledShell
+        ? `${compiledLayoutHtml || ''}\n  ${enhancement}`
+        : `  <a class="skip-link" href="#main">Skip to content</a>
+  <div class="site site--docs">
+    <div class="doc-body">
+${slotHtml}
+    </div>
+  </div>
+  ${enhancement}
 `;
-    }
     const native = requireNativeAddon();
     if (typeof native.generateHtmlShell !== 'function') {
         throw new Error('vmz native addon missing generateHtmlShell — rebuild with `pnpm napi:build`');
@@ -267,19 +290,12 @@ ${playgroundShellHtml}
         bodyAttrs: ['data-vmz-hydrate', 'island-only'],
     });
 }
-function relativeHref(fromHtmlRel, toRoute, _fromRoute) {
-    const toParts = String(toRoute).replace(/^\//, '').split('/').filter(Boolean);
-    let toRel;
-    if (toParts.length <= 2) {
-        toRel = [...toParts, 'index.html'].join('/');
-    }
-    else {
-        const file = toParts.slice(2).join('/') + '.html';
-        toRel = [...toParts.slice(0, 2), file].join('/');
-    }
-    const fromDir = path.posix.dirname(fromHtmlRel.replace(/\\/g, '/'));
-    let rel = path.posix.relative(fromDir, toRel);
-    if (!rel.startsWith('.') && !rel.startsWith('/'))
-        rel = './' + rel;
-    return rel || './index.html';
+/** Render-pass hooks: fence highlight + author link → route-form rewrite + heading anchors. */
+function documentRenderHooks(page, routeBase, pageKeySet, routing, highlighter) {
+    return {
+        resolveHref: (href) => routeHrefForDocLink(href, page.identity.pageKey, page.identity.locale, routeBase, pageKeySet, routing),
+        // Self-links on h2+ (the h1 is the page title — anchoring it is noise).
+        headingAnchor: (h) => (h.level >= 2 ? `#${h.id}` : null),
+        ...(highlighter ? { highlight: (code, lang) => highlighter.highlightFenceInline(code, lang) } : {}),
+    };
 }

package/dist/document/document-client.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Framework-owned document client enhancement (`assets/vmz-document.js`).
+ *
+ * Progressive enhancement only: pages stay no-JS readable. The module wires
+ * the static DocumentSearch shell to `document.search.json` (locale-scoped
+ * substring filter, full keyboard loop) and injects copy buttons on article
+ * code blocks. No framework runtime, no full-page hydration.
+ *
+ * Emitted verbatim by `buildDocuments`; keep it dependency-free plain JS —
+ * this file is served as-authored, never bundled.
+ */
+export declare const DOCUMENT_CLIENT_HREF = "assets/vmz-document.js";
+export declare const DOCUMENT_CLIENT_JS = "/* vmz document layer \u2014 progressive enhancement (no framework runtime). */\n(function () {\n    'use strict';\n\n    var doc = document.documentElement;\n    var zh = String(doc.lang || '').toLowerCase().indexOf('zh') === 0;\n    var copy = zh\n        ? { search: '\u641C\u7D22\u6587\u6863', noResults: '\u6CA1\u6709\u5339\u914D\u7ED3\u679C', hintJs: '\u8F93\u5165\u5173\u952E\u8BCD\u8FC7\u6EE4\u6587\u6863', copyLabel: '\u590D\u5236', copied: '\u5DF2\u590D\u5236', results: '\u641C\u7D22\u7ED3\u679C' }\n        : { search: 'Search docs', noResults: 'No matching results', hintJs: 'Type to filter the docs', copyLabel: 'Copy', copied: 'Copied', results: 'Search results' };\n\n    function ready(fn) {\n        if (document.readyState === 'loading') {\n            document.addEventListener('DOMContentLoaded', fn, { once: true });\n        } else {\n            fn();\n        }\n    }\n\n    /* Search ------------------------------------------------------------ */\n\n    function enhanceSearch(host) {\n        var input = host.querySelector('.doc-search__input');\n        var list = host.querySelector('.doc-search__results');\n        var hint = host.querySelector('.doc-search__hint');\n        if (!input || !list) return;\n        var indexHref = host.getAttribute('data-vmz-search-index');\n        if (!indexHref) return;\n\n        var locale = String(doc.lang || '');\n        var records = null;\n        var loading = null;\n        var active = -1;\n        var current = [];\n\n        function loadIndex() {\n            if (records) return Promise.resolve(records);\n            if (loading) return loading;\n            loading = fetch(indexHref, { credentials: 'same-origin' })\n                .then(function (res) {\n                    if (!res.ok) throw new Error('search index ' + res.status);\n                    return res.json();\n                })\n                .then(function (json) {\n                    records = (json && json.records ? json.records : []).filter(function (r) {\n                        return r && r.locale === locale && (r.kind === 'page' || r.kind === 'heading') && r.route;\n                    });\n                    return records;\n                })\n                .catch(function () {\n                    records = [];\n                    return records;\n                });\n            return loading;\n        }\n\n        function close() {\n            list.hidden = true;\n            input.setAttribute('aria-expanded', 'false');\n            current = [];\n            active = -1;\n        }\n\n        function open() {\n            list.hidden = false;\n            input.setAttribute('aria-expanded', 'true');\n        }\n\n        function render(query) {\n            var q = String(query || '').trim().toLowerCase();\n            current = [];\n            active = -1;\n            list.innerHTML = '';\n            if (!q) {\n                close();\n                return;\n            }\n            loadIndex().then(function (all) {\n                // Re-read the live query: a slow fetch must not paint stale hits.\n                var live = String(input.value || '').trim().toLowerCase();\n                if (live !== q) return;\n                var seen = {};\n                for (var i = 0; i < all.length && current.length < 8; i++) {\n                    var r = all[i];\n                    var hay = String(r.title || '') + ' ' + String(r.text || '');\n                    if (hay.toLowerCase().indexOf(live) < 0) continue;\n                    if (seen[r.route]) continue;\n                    seen[r.route] = true;\n                    current.push(r);\n                }\n                list.innerHTML = '';\n                if (!current.length) {\n                    var empty = document.createElement('li');\n                    empty.className = 'doc-search__empty';\n                    empty.setAttribute('role', 'option');\n                    empty.setAttribute('aria-disabled', 'true');\n                    empty.textContent = copy.noResults;\n                    list.appendChild(empty);\n                } else {\n                    current.forEach(function (r, i) {\n                        var li = document.createElement('li');\n                        li.setAttribute('role', 'option');\n                        li.id = 'vmz-doc-search-hit-' + i;\n                        li.setAttribute('aria-selected', 'false');\n                        var a = document.createElement('a');\n                        a.href = r.route;\n                        a.textContent = r.title || r.route;\n                        if (r.kind === 'heading') {\n                            var ctx = document.createElement('span');\n                            ctx.className = 'doc-search__ctx';\n                            ctx.textContent = '\u00A0\u00B7\u00A0' + (r.pageKey || '');\n                            a.appendChild(ctx);\n                        }\n                        li.appendChild(a);\n                        list.appendChild(li);\n                    });\n                }\n                open();\n            });\n        }\n\n        function move(delta) {\n            if (!current.length) return;\n            active = (active + delta + current.length) % current.length;\n            var rows = list.querySelectorAll('li[role=\"option\"]');\n            rows.forEach(function (row, i) {\n                row.setAttribute('aria-selected', i === active ? 'true' : 'false');\n            });\n            input.setAttribute('aria-activedescendant', 'vmz-doc-search-hit-' + active);\n        }\n\n        input.setAttribute('role', 'combobox');\n        input.setAttribute('aria-controls', list.id || 'vmz-doc-search-results');\n        list.id = list.id || 'vmz-doc-search-results';\n        input.setAttribute('aria-expanded', 'false');\n        input.setAttribute('placeholder', copy.search);\n        list.setAttribute('aria-label', copy.results);\n        if (hint) hint.textContent = copy.hintJs;\n\n        input.addEventListener('input', function () {\n            render(input.value);\n        });\n        input.addEventListener('focus', function () {\n            loadIndex();\n        });\n        input.addEventListener('keydown', function (ev) {\n            if (ev.key === 'ArrowDown') {\n                ev.preventDefault();\n                move(1);\n            } else if (ev.key === 'ArrowUp') {\n                ev.preventDefault();\n                move(-1);\n            } else if (ev.key === 'Enter') {\n                if (active >= 0 && current[active]) {\n                    ev.preventDefault();\n                    window.location.assign(current[active].route);\n                }\n            } else if (ev.key === 'Escape') {\n                input.value = '';\n                close();\n            }\n        });\n        document.addEventListener('click', function (ev) {\n            if (!host.contains(ev.target)) close();\n        });\n    }\n\n    /* Code copy ----------------------------------------------------------- */\n\n    function enhanceCopy() {\n        if (!navigator.clipboard || typeof navigator.clipboard.writeText !== 'function') return;\n        var blocks = document.querySelectorAll('.doc-content main pre');\n        blocks.forEach(function (pre) {\n            if (pre.querySelector('.doc-copy')) return;\n            var btn = document.createElement('button');\n            btn.type = 'button';\n            btn.className = 'doc-copy';\n            btn.textContent = copy.copyLabel;\n            btn.setAttribute('aria-label', copy.copyLabel);\n            btn.addEventListener('click', function () {\n                var code = pre.querySelector('code');\n                var text = code ? code.innerText : pre.innerText;\n                navigator.clipboard.writeText(text).then(function () {\n                    btn.textContent = copy.copied;\n                    btn.classList.add('doc-copy--done');\n                    setTimeout(function () {\n                        btn.textContent = copy.copyLabel;\n                        btn.classList.remove('doc-copy--done');\n                    }, 1200);\n                });\n            });\n            pre.appendChild(btn);\n        });\n    }\n\n    ready(function () {\n        try {\n            var host = document.querySelector('[data-vmz-search-index]');\n            if (host) enhanceSearch(host);\n            enhanceCopy();\n        } catch (err) {\n            /* Enhancement must never take the readable page down. */\n        }\n    });\n})();\n";

package/dist/document/document-client.js

@@ -0,0 +1,217 @@
+/**
+ * Framework-owned document client enhancement (`assets/vmz-document.js`).
+ *
+ * Progressive enhancement only: pages stay no-JS readable. The module wires
+ * the static DocumentSearch shell to `document.search.json` (locale-scoped
+ * substring filter, full keyboard loop) and injects copy buttons on article
+ * code blocks. No framework runtime, no full-page hydration.
+ *
+ * Emitted verbatim by `buildDocuments`; keep it dependency-free plain JS —
+ * this file is served as-authored, never bundled.
+ */
+export const DOCUMENT_CLIENT_HREF = 'assets/vmz-document.js';
+export const DOCUMENT_CLIENT_JS = `/* vmz document layer — progressive enhancement (no framework runtime). */
+(function () {
+    'use strict';
+
+    var doc = document.documentElement;
+    var zh = String(doc.lang || '').toLowerCase().indexOf('zh') === 0;
+    var copy = zh
+        ? { search: '搜索文档', noResults: '没有匹配结果', hintJs: '输入关键词过滤文档', copyLabel: '复制', copied: '已复制', results: '搜索结果' }
+        : { search: 'Search docs', noResults: 'No matching results', hintJs: 'Type to filter the docs', copyLabel: 'Copy', copied: 'Copied', results: 'Search results' };
+
+    function ready(fn) {
+        if (document.readyState === 'loading') {
+            document.addEventListener('DOMContentLoaded', fn, { once: true });
+        } else {
+            fn();
+        }
+    }
+
+    /* Search ------------------------------------------------------------ */
+
+    function enhanceSearch(host) {
+        var input = host.querySelector('.doc-search__input');
+        var list = host.querySelector('.doc-search__results');
+        var hint = host.querySelector('.doc-search__hint');
+        if (!input || !list) return;
+        var indexHref = host.getAttribute('data-vmz-search-index');
+        if (!indexHref) return;
+
+        var locale = String(doc.lang || '');
+        var records = null;
+        var loading = null;
+        var active = -1;
+        var current = [];
+
+        function loadIndex() {
+            if (records) return Promise.resolve(records);
+            if (loading) return loading;
+            loading = fetch(indexHref, { credentials: 'same-origin' })
+                .then(function (res) {
+                    if (!res.ok) throw new Error('search index ' + res.status);
+                    return res.json();
+                })
+                .then(function (json) {
+                    records = (json && json.records ? json.records : []).filter(function (r) {
+                        return r && r.locale === locale && (r.kind === 'page' || r.kind === 'heading') && r.route;
+                    });
+                    return records;
+                })
+                .catch(function () {
+                    records = [];
+                    return records;
+                });
+            return loading;
+        }
+
+        function close() {
+            list.hidden = true;
+            input.setAttribute('aria-expanded', 'false');
+            current = [];
+            active = -1;
+        }
+
+        function open() {
+            list.hidden = false;
+            input.setAttribute('aria-expanded', 'true');
+        }
+
+        function render(query) {
+            var q = String(query || '').trim().toLowerCase();
+            current = [];
+            active = -1;
+            list.innerHTML = '';
+            if (!q) {
+                close();
+                return;
+            }
+            loadIndex().then(function (all) {
+                // Re-read the live query: a slow fetch must not paint stale hits.
+                var live = String(input.value || '').trim().toLowerCase();
+                if (live !== q) return;
+                var seen = {};
+                for (var i = 0; i < all.length && current.length < 8; i++) {
+                    var r = all[i];
+                    var hay = String(r.title || '') + ' ' + String(r.text || '');
+                    if (hay.toLowerCase().indexOf(live) < 0) continue;
+                    if (seen[r.route]) continue;
+                    seen[r.route] = true;
+                    current.push(r);
+                }
+                list.innerHTML = '';
+                if (!current.length) {
+                    var empty = document.createElement('li');
+                    empty.className = 'doc-search__empty';
+                    empty.setAttribute('role', 'option');
+                    empty.setAttribute('aria-disabled', 'true');
+                    empty.textContent = copy.noResults;
+                    list.appendChild(empty);
+                } else {
+                    current.forEach(function (r, i) {
+                        var li = document.createElement('li');
+                        li.setAttribute('role', 'option');
+                        li.id = 'vmz-doc-search-hit-' + i;
+                        li.setAttribute('aria-selected', 'false');
+                        var a = document.createElement('a');
+                        a.href = r.route;
+                        a.textContent = r.title || r.route;
+                        if (r.kind === 'heading') {
+                            var ctx = document.createElement('span');
+                            ctx.className = 'doc-search__ctx';
+                            ctx.textContent = ' · ' + (r.pageKey || '');
+                            a.appendChild(ctx);
+                        }
+                        li.appendChild(a);
+                        list.appendChild(li);
+                    });
+                }
+                open();
+            });
+        }
+
+        function move(delta) {
+            if (!current.length) return;
+            active = (active + delta + current.length) % current.length;
+            var rows = list.querySelectorAll('li[role="option"]');
+            rows.forEach(function (row, i) {
+                row.setAttribute('aria-selected', i === active ? 'true' : 'false');
+            });
+            input.setAttribute('aria-activedescendant', 'vmz-doc-search-hit-' + active);
+        }
+
+        input.setAttribute('role', 'combobox');
+        input.setAttribute('aria-controls', list.id || 'vmz-doc-search-results');
+        list.id = list.id || 'vmz-doc-search-results';
+        input.setAttribute('aria-expanded', 'false');
+        input.setAttribute('placeholder', copy.search);
+        list.setAttribute('aria-label', copy.results);
+        if (hint) hint.textContent = copy.hintJs;
+
+        input.addEventListener('input', function () {
+            render(input.value);
+        });
+        input.addEventListener('focus', function () {
+            loadIndex();
+        });
+        input.addEventListener('keydown', function (ev) {
+            if (ev.key === 'ArrowDown') {
+                ev.preventDefault();
+                move(1);
+            } else if (ev.key === 'ArrowUp') {
+                ev.preventDefault();
+                move(-1);
+            } else if (ev.key === 'Enter') {
+                if (active >= 0 && current[active]) {
+                    ev.preventDefault();
+                    window.location.assign(current[active].route);
+                }
+            } else if (ev.key === 'Escape') {
+                input.value = '';
+                close();
+            }
+        });
+        document.addEventListener('click', function (ev) {
+            if (!host.contains(ev.target)) close();
+        });
+    }
+
+    /* Code copy ----------------------------------------------------------- */
+
+    function enhanceCopy() {
+        if (!navigator.clipboard || typeof navigator.clipboard.writeText !== 'function') return;
+        var blocks = document.querySelectorAll('.doc-content main pre');
+        blocks.forEach(function (pre) {
+            if (pre.querySelector('.doc-copy')) return;
+            var btn = document.createElement('button');
+            btn.type = 'button';
+            btn.className = 'doc-copy';
+            btn.textContent = copy.copyLabel;
+            btn.setAttribute('aria-label', copy.copyLabel);
+            btn.addEventListener('click', function () {
+                var code = pre.querySelector('code');
+                var text = code ? code.innerText : pre.innerText;
+                navigator.clipboard.writeText(text).then(function () {
+                    btn.textContent = copy.copied;
+                    btn.classList.add('doc-copy--done');
+                    setTimeout(function () {
+                        btn.textContent = copy.copyLabel;
+                        btn.classList.remove('doc-copy--done');
+                    }, 1200);
+                });
+            });
+            pre.appendChild(btn);
+        });
+    }
+
+    ready(function () {
+        try {
+            var host = document.querySelector('[data-vmz-search-index]');
+            if (host) enhanceSearch(host);
+            enhanceCopy();
+        } catch (err) {
+            /* Enhancement must never take the readable page down. */
+        }
+    });
+})();
+`;

package/dist/document/document-cmd.js

@@ -8,6 +8,7 @@ import { enrichDocumentContent } from './document-enrich.js';
 import { enrichDocumentEvidence } from './document-evidence.js';
 import { resolveMarkdownEngine } from './document-markdown.js';
 import { createWorkspace } from '../workspace/public-api.js';
+import { loadVmzConfig } from '../workspace/plugin-host.js';
 import { log } from '../workspace/log.js';
 import { emitPrettyJson } from '../workspace/pretty-json.js';
 export function registerDocumentCommands(parent) {
@@ -62,7 +63,8 @@ async function cmdDocumentBuild(args) {
     const strict = Boolean(args.strict);
     let result;
     try {
-        result = await buildDocuments({ projectRoot, outDir, strict });
+        const cfg = await loadVmzConfig(projectRoot).catch(() => null);
+        result = await buildDocuments({ projectRoot, outDir, strict, engines: cfg?.engines });
     }
     catch (e) {
         const msg = e instanceof Error ? e.message : String(e);

package/dist/document/document-designs.d.ts

@@ -1,6 +1,12 @@
 export interface DocumentDesignsCssResult {
-    css: string;
-    source: string | null;
-    href: string | null;
+    /** Site token stylesheet body (empty when the project has no compiled tokens). */
+    tokensCss: string;
+    tokensSource: string | null;
+    /** Site token stylesheet href (emitted name), null when no tokens exist. */
+    tokensHref: string | null;
+    /** Framework document base stylesheet href (always emitted). */
+    baseHref: string;
+    /** Combined source description for the manifest. */
+    source: string;
 }
 export declare function resolveDocumentDesignsCss(projectRoot: string, appDistDir?: string | null): DocumentDesignsCssResult;

package/dist/document/document-designs.js

@@ -1,53 +1,39 @@
 /**
- * Document — wire project `/designs` and the compiled app stylesheet into
- * static document assets.
+ * Document — wire the compiled app stylesheet and the framework-owned document
+ * base layer into static document assets.
  *
- * Layout chrome comes from `designs/document/chrome.css`. Theme tokens are not
- * re-derived here: they come from the app build output (`vmz-designs.css` /
- * `vmz.css` under `appDistDir`), which is the single compiled artifact.
+ * Layering (see 规划设计/vmz 04 文档层):
+ * - `assets/vmz-designs.css`: the site's compiled design tokens (`vmz-designs.css`
+ *   / `vmz.css` from the app build, or `designs/styles/index.css` standalone).
+ * - `assets/vmz-document.css`: the framework document base (`DOCUMENT_BASE_CSS`),
+ *   the single canonical layout/typography surface. Site `designs/document/*`
+ *   is no longer an input — brand customization goes through `designs/tokens`.
  */
 import fs from 'node:fs';
 import path from 'node:path';
 export function resolveDocumentDesignsCss(projectRoot, appDistDir) {
-    const designsDir = path.join(projectRoot, 'designs');
-    if (!fs.existsSync(designsDir) || !fs.statSync(designsDir).isDirectory()) {
-        return { css: '', source: null, href: null };
-    }
-    const parts = [];
-    const sources = [];
-    // Layout first so @import stays at stylesheet top; compiled tokens follow.
-    const layoutCandidates = [
-        path.join(designsDir, 'document', 'chrome.css'),
-        path.join(designsDir, 'styles', 'document.css'),
-    ];
-    for (const p of layoutCandidates) {
-        if (!fs.existsSync(p))
-            continue;
-        parts.push(fs.readFileSync(p, 'utf8'));
-        sources.push(path.relative(projectRoot, p).replace(/\\/g, '/'));
-        break;
-    }
+    let tokensCss = '';
+    let tokensSource = null;
     if (appDistDir) {
         const compiled = [path.join(appDistDir, 'vmz-designs.css'), path.join(appDistDir, 'vmz.css')].find((p) => fs.existsSync(p));
         if (!compiled) {
             throw new Error(`vmz.document: app dist ${appDistDir} is missing vmz-designs.css / vmz.css; build the app before the documents`);
         }
-        parts.push(fs.readFileSync(compiled, 'utf8'));
-        sources.push(path.relative(projectRoot, compiled).replace(/\\/g, '/'));
+        tokensCss = fs.readFileSync(compiled, 'utf8');
+        tokensSource = path.relative(projectRoot, compiled).replace(/\\/g, '/');
     }
     else {
-        const entry = path.join(designsDir, 'styles', 'index.css');
+        const entry = path.join(projectRoot, 'designs', 'styles', 'index.css');
         if (fs.existsSync(entry)) {
-            parts.push(fs.readFileSync(entry, 'utf8'));
-            sources.push(path.relative(projectRoot, entry).replace(/\\/g, '/'));
+            tokensCss = fs.readFileSync(entry, 'utf8');
+            tokensSource = 'designs/styles/index.css';
         }
     }
-    if (!parts.length) {
-        return { css: '', source: 'designs/', href: null };
-    }
     return {
-        css: parts.join('\n\n'),
-        source: sources.join('+'),
-        href: 'assets/vmz-designs.css',
+        tokensCss,
+        tokensSource,
+        tokensHref: tokensCss ? 'assets/vmz-designs.css' : null,
+        baseHref: 'assets/vmz-document.css',
+        source: ['vmz/document-base', tokensSource].filter(Boolean).join('+'),
     };
 }

package/dist/document/document-enrich.d.ts

@@ -50,3 +50,12 @@ export declare function pageRoute(routeBase: string, locale: string, pageKey: st
 /** Static file path relative to out dir (posix). */
 export declare function pageHtmlRel(routeBase: string, locale: string, pageKey: string): string;
 export declare function enrichDocumentContent(manifest: DocumentManifest, ctx: EnrichDocumentContentCtx): EnrichDocumentContentResult;
+/**
+ * Author link → route-form href for emitted pages (document layer link form:
+ * `/d/<locale>/<pageKey>` without `.html`, matching application routes).
+ *
+ * Returns `null` for links that must stay as-authored: external/mailto, API
+ * refs, pure anchors, absolute application routes outside the document mount,
+ * and unresolvable relatives (the check pass reports those as broken).
+ */
+export declare function routeHrefForDocLink(href: string, fromPageKey: string, locale: string, routeBase: string, pageKeySet: Map<string, Set<string>>, routing?: DocumentRoutingStrategy): string | null;