@vmz/vmz 0.1.13 → 0.1.15

package/dist/dev-watch-roots.js

@@ -0,0 +1,245 @@
+// @ts-nocheck
+/**
+ * Dev watch helpers: coalesce multi-file bursts without dropping dirty set,
+ * and derive extra watch roots from the compile graph (deployment unit sources).
+ */
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import { diffFingerprints, fileFingerprintMap } from './watch-diff.js';
+/**
+ * @typedef {{ changed: string[], deleted: string[] }} DirtySet
+ */
+/**
+ * Merge dirty sets: later change cancels delete and vice versa.
+ * @param {DirtySet} a
+ * @param {DirtySet} b
+ * @returns {DirtySet}
+ */
+export function mergeDirtySets(a, b) {
+    const changed = new Set(a?.changed || []);
+    const deleted = new Set(a?.deleted || []);
+    for (const f of b?.changed || []) {
+        changed.add(f);
+        deleted.delete(f);
+    }
+    for (const f of b?.deleted || []) {
+        deleted.add(f);
+        changed.delete(f);
+    }
+    return { changed: [...changed], deleted: [...deleted] };
+}
+/**
+ * Wait until `root` stops changing; return the **accumulated** dirty set since `initial`.
+ * Updates `fingerprints` for `root` as it polls. Does **not** discard `initial`.
+ *
+ * @param {string} root
+ * @param {Map<string, Map<string, string>>} fingerprints
+ * @param {DirtySet} initial
+ * @param {{ sleep?: (ms: number) => Promise<void>, maxRounds?: number, settleMs?: number }} [opts]
+ * @returns {Promise<DirtySet>}
+ */
+export async function coalesceRootBurst(root, fingerprints, initial, opts = {}) {
+    const sleepFn = opts.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const maxRounds = opts.maxRounds ?? 20;
+    const settleMs = opts.settleMs ?? 220;
+    let accumulated = {
+        changed: [...(initial?.changed || [])],
+        deleted: [...(initial?.deleted || [])],
+    };
+    let guard = 0;
+    while (guard++ < maxRounds) {
+        await sleepFn(settleMs);
+        const prev = fingerprints.get(root) || new Map();
+        const next = fileFingerprintMap(root);
+        const diff = diffFingerprints(prev, next);
+        fingerprints.set(root, next);
+        if (!diff.changed.length && !diff.deleted.length)
+            break;
+        accumulated = mergeDirtySets(accumulated, diff);
+    }
+    return accumulated;
+}
+/**
+ * Walk up from a file to find a package.json directory.
+ * @param {string} file
+ * @returns {string | null}
+ */
+export function findPackageRoot(file) {
+    let dir = path.dirname(path.resolve(file));
+    for (let i = 0; i < 24; i++) {
+        if (existsSync(path.join(dir, 'package.json')))
+            return dir;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * Prefer package/src when present; otherwise the directory containing the source file.
+ * @param {string} sourceFile
+ * @returns {string | null}
+ */
+export function watchRootForSourceFile(sourceFile) {
+    const abs = path.resolve(sourceFile);
+    if (!existsSync(abs))
+        return null;
+    const pkg = findPackageRoot(abs);
+    if (pkg) {
+        const src = path.join(pkg, 'src');
+        if (existsSync(src))
+            return src;
+        return pkg;
+    }
+    return path.dirname(abs);
+}
+/**
+ * Absolute roots for workspace / file / link deps that have a src tree.
+ * @param {string} project
+ * @returns {string[]}
+ */
+export function localLinkDependencyRoots(project) {
+    const pkgPath = path.join(path.resolve(project), 'package.json');
+    if (!existsSync(pkgPath))
+        return [];
+    /** @type {string[]} */
+    const roots = [];
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+        for (const [name, spec] of Object.entries(deps)) {
+            if (typeof spec !== 'string')
+                continue;
+            let target = null;
+            if (spec.startsWith('workspace:')) {
+                // Resolve via node_modules (pnpm links workspace packages there).
+                const nm = path.join(path.resolve(project), 'node_modules', ...name.split('/'));
+                if (existsSync(path.join(nm, 'package.json')))
+                    target = nm;
+            }
+            else if (spec.startsWith('file:') || spec.startsWith('link:')) {
+                const rel = spec.replace(/^(file|link):/, '');
+                target = path.resolve(project, rel);
+            }
+            if (!target)
+                continue;
+            try {
+                target = realpathSync(target);
+            }
+            catch {
+                /* keep as-is */
+            }
+            const src = path.join(target, 'src');
+            if (existsSync(src))
+                roots.push(src);
+            else if (existsSync(target))
+                roots.push(target);
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return roots;
+}
+/**
+ * Collect watch roots: project src/locales/documents + compile-graph external sources
+ * + local link/workspace package roots. Never adds a bare registry node_modules tree.
+ *
+ * @param {{ project: string, outDir: string }} opts
+ * @returns {{ roots: string[], dependencyRoots: string[], applicationRoots: string[] }}
+ */
+export function collectDevWatchRoots(opts) {
+    const project = path.resolve(opts.project);
+    const outDir = path.resolve(opts.outDir);
+    const src = path.join(project, 'src');
+    const docsRoot = path.join(project, 'documents');
+    const localesRoot = path.join(project, 'locales');
+    const designsRoot = path.join(project, 'designs');
+    /** @type {string[]} */
+    const applicationRoots = [];
+    if (existsSync(src))
+        applicationRoots.push(src);
+    if (existsSync(docsRoot))
+        applicationRoots.push(docsRoot);
+    if (existsSync(localesRoot))
+        applicationRoots.push(localesRoot);
+    if (existsSync(designsRoot))
+        applicationRoots.push(designsRoot);
+    /** @type {Set<string>} */
+    const depSet = new Set();
+    const depJson = path.join(outDir, 'vmz-deployment.json');
+    if (existsSync(depJson)) {
+        try {
+            const dep = JSON.parse(readFileSync(depJson, 'utf8'));
+            for (const unit of dep.units || []) {
+                const source = unit?.source;
+                if (typeof source !== 'string' || !source)
+                    continue;
+                let abs = path.resolve(source);
+                try {
+                    abs = realpathSync(abs);
+                }
+                catch {
+                    /* keep */
+                }
+                const underProject = abs === project || abs.startsWith(project + path.sep) || abs.startsWith(project + '/');
+                if (underProject)
+                    continue;
+                const root = watchRootForSourceFile(abs);
+                if (root)
+                    depSet.add(path.resolve(root));
+            }
+        }
+        catch {
+            /* ignore corrupt deployment */
+        }
+    }
+    for (const r of localLinkDependencyRoots(project)) {
+        depSet.add(path.resolve(r));
+    }
+    // Drop dependency roots that are already under an application root.
+    const dependencyRoots = [...depSet].filter((r) => {
+        return !applicationRoots.some((app) => r === app || r.startsWith(app + path.sep) || r.startsWith(app + '/'));
+    });
+    const roots = [...applicationRoots];
+    for (const r of dependencyRoots) {
+        if (!roots.includes(r))
+            roots.push(r);
+    }
+    return { roots, dependencyRoots, applicationRoots };
+}
+/**
+ * Classify which watch bucket a root belongs to.
+ * @param {string} root
+ * @param {{
+ *   src: string,
+ *   docsRoot: string,
+ *   localesRoot: string,
+ *   designsRoot: string,
+ *   dependencyRoots: string[],
+ * }} ctx
+ * @returns {'src' | 'locales' | 'docs' | 'designs' | 'dep' | 'other'}
+ */
+export function classifyWatchRoot(root, ctx) {
+    if (root === ctx.src)
+        return 'src';
+    if (root === ctx.localesRoot)
+        return 'locales';
+    if (root === ctx.docsRoot)
+        return 'docs';
+    if (root === ctx.designsRoot)
+        return 'designs';
+    if ((ctx.dependencyRoots || []).includes(root))
+        return 'dep';
+    return 'other';
+}
+/**
+ * Classify whether a changed file lives under a dependency watch root (not app src).
+ * @param {string} file
+ * @param {string[]} dependencyRoots
+ */
+export function isDependencyPath(file, dependencyRoots) {
+    const abs = path.resolve(file);
+    return (dependencyRoots || []).some((r) => abs === r || abs.startsWith(r + path.sep) || abs.startsWith(r + '/'));
+}

package/dist/document-build.d.ts

@@ -1,5 +1,5 @@
 /**
- * @param {{ projectRoot: string, outDir?: string, strict?: boolean, engines?: { markdown?: string } }} opts
+ * @param {{ projectRoot: string, outDir?: string, appDistDir?: string, strict?: boolean, engines?: { markdown?: string } }} opts
  */
 export declare function buildDocuments(opts: any): Promise<{
     ok: boolean;
@@ -8,7 +8,7 @@ export declare function buildDocuments(opts: any): Promise<{
         root: string;
         defaultLocale: any;
         locales: any[];
-        localeLabels: {};
+        localeLabels: any;
         collections: any[];
         mounts: any[];
         pages: {
@@ -57,6 +57,7 @@ export declare function buildDocuments(opts: any): Promise<{
             outDir: string;
             designs: string;
             designsCss: any;
+            hostShell: string;
             pages: any[];
             evidence: string;
             search: string;
@@ -65,7 +66,7 @@ export declare function buildDocuments(opts: any): Promise<{
         root: string;
         defaultLocale: any;
         locales: any[];
-        localeLabels: {};
+        localeLabels: any;
         collections: any[];
         mounts: any[];
         pages: {

package/dist/document-build.js

@@ -9,21 +9,27 @@ import { resolveDocumentDesignsCss } from './document-designs.js';
 import { enrichDocumentContent, pageHtmlRel } from './document-enrich.js';
 import { enrichDocumentEvidence } from './document-evidence.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';
+import { loadLocalesRouting } from './document-routing-config.js';
 import { DOCUMENT_VIEW_SCHEMA } from './document-schema.js';
 import { createWorkspace } from './index.js';
+import { requireNativeAddon } from './native-addon.js';
+import { writePrettyJsonFile } from './pretty-json.js';
 /**
- * @param {{ projectRoot: string, outDir?: string, strict?: boolean, engines?: { markdown?: string } }} opts
+ * @param {{ projectRoot: string, outDir?: string, appDistDir?: string, strict?: boolean, engines?: { markdown?: string } }} opts
  */
 export async function buildDocuments(opts) {
     const projectRoot = path.resolve(opts.projectRoot);
     const outDir = path.resolve(opts.outDir || path.join(projectRoot, 'dist', 'documents'));
     const strict = Boolean(opts.strict);
     const manifest = checkDocuments({ projectRoot, strict });
+    const routing = loadLocalesRouting(projectRoot) || { strategy: 'prefix' };
     const engine = await resolveMarkdownEngine({ engines: opts.engines, projectRoot });
     const enriched = enrichDocumentContent(manifest, {
         analyzeMarkdown: engine.analyzeMarkdown,
         projectRoot,
+        routing,
     });
     manifest.diagnostics = enriched.diagnostics;
     const evidence = await enrichDocumentEvidence(manifest, {
@@ -58,8 +64,12 @@ export async function buildDocuments(opts) {
     });
     manifest.search = search;
     manifest.islands = islands;
-    const hostChrome = resolveHostSiteChrome(projectRoot);
-    const useHostShell = Boolean(hostChrome) && (manifest.mounts || []).some((m) => m.mode === 'integrated');
+    const integratedMount = (manifest.mounts || []).some((m) => m.mode === 'integrated');
+    const appDistDir = resolveAppDistDir(opts, outDir);
+    const useCompiledShell = Boolean(integratedMount && appDistDir);
+    if (integratedMount && appDistDir) {
+        assertIntegratedDistReady(appDistDir);
+    }
     fs.mkdirSync(outDir, { recursive: true });
     const designs = resolveDocumentDesignsCss(projectRoot);
     /** @type {string | null} */
@@ -90,6 +100,20 @@ export async function buildDocuments(opts) {
             pageKey: page.identity.pageKey,
             locale: page.identity.locale,
         });
+        const slotHtml = buildDocumentSlotHtml({
+            nav,
+            bodyHtml: info.html,
+            headings: info.headings,
+            htmlRel,
+            route: info.route,
+            routing,
+            searchShellHtml: shells.searchHtml,
+            playgroundShellHtml: shells.playgroundHtml,
+        });
+        let compiledLayoutHtml = null;
+        if (useCompiledShell) {
+            compiledLayoutHtml = await renderCompiledDocumentLayout(appDistDir, page.identity.locale, slotHtml);
+        }
         const view = {
             schema: DOCUMENT_VIEW_SCHEMA,
             pageKey: page.identity.pageKey,
@@ -103,7 +127,7 @@ export async function buildDocuments(opts) {
             designsCss: designsHref,
             noJsReadable: true,
             hydrate: 'island-only',
-            hostShell: useHostShell,
+            hostShell: useCompiledShell ? 'compiled-layout' : false,
             islands: ['DocumentSearch'].concat((islands.islands || [])
                 .filter((isl) => isl.kind === 'playground' &&
                 isl.fence?.locale === page.identity.locale &&
@@ -113,7 +137,7 @@ export async function buildDocuments(opts) {
         const viewRel = path.posix.join('views', page.identity.locale, `${page.identity.pageKey === 'index' ? 'index' : page.identity.pageKey}.view.json`);
         const viewAbs = path.join(outDir, viewRel);
         fs.mkdirSync(path.dirname(viewAbs), { recursive: true });
-        fs.writeFileSync(viewAbs, JSON.stringify(view, null, 2) + '\n', 'utf8');
+        writePrettyJsonFile(viewAbs, view);
         const html = renderStaticHtml({
             title: info.title,
             locale: page.identity.locale,
@@ -125,7 +149,9 @@ export async function buildDocuments(opts) {
             htmlRel,
             searchShellHtml: shells.searchHtml,
             playgroundShellHtml: shells.playgroundHtml,
-            hostChrome: useHostShell ? hostChrome : null,
+            routing,
+            compiledLayoutHtml,
+            useCompiledShell,
         });
         fs.writeFileSync(htmlAbs, html, 'utf8');
         written.push({ route: info.route, htmlPath: htmlRel, viewPath: viewRel });
@@ -141,39 +167,38 @@ export async function buildDocuments(opts) {
             outDir: path.relative(projectRoot, outDir).replace(/\\/g, '/') || '.',
             designs: designs.source,
             designsCss: designsHref,
+            hostShell: useCompiledShell ? 'compiled-layout' : 'standalone',
             pages: written,
             evidence: 'document.evidence.json',
             search: 'document.search.json',
             islands: 'document.islands.json',
         },
     };
-    fs.writeFileSync(path.join(outDir, 'document.manifest.json'), JSON.stringify(manifestOut, null, 2) + '\n', 'utf8');
-    fs.writeFileSync(path.join(outDir, 'document.evidence.json'), JSON.stringify(evidence.evidence, null, 2) + '\n', 'utf8');
-    fs.writeFileSync(path.join(outDir, 'document.search.json'), JSON.stringify(search, null, 2) + '\n', 'utf8');
-    fs.writeFileSync(path.join(outDir, 'document.islands.json'), JSON.stringify(islands, null, 2) + '\n', 'utf8');
+    writePrettyJsonFile(path.join(outDir, 'document.manifest.json'), manifestOut);
+    writePrettyJsonFile(path.join(outDir, 'document.evidence.json'), evidence.evidence);
+    writePrettyJsonFile(path.join(outDir, 'document.search.json'), search);
+    writePrettyJsonFile(path.join(outDir, 'document.islands.json'), islands);
     return { ok: true, manifest: manifestOut, outDir, pages: written, search, islands };
 }
 /**
- * No-JS readable static HTML: nav + main landmarks, Island shells without scripts.
- * Integrated mounts reuse host SiteHeader/SiteFooter templates when present.
+ * @param {{ appDistDir?: string }} opts
+ * @param {string} outDir
  */
-function renderStaticHtml({ title, locale, route, nav, bodyHtml, headings, designsHref, htmlRel, searchShellHtml = '', playgroundShellHtml = '', hostChrome = null, }) {
-    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) : './';
-    /** @type {string[]} */
-    const cssHrefs = [];
-    if (hostChrome) {
-        // Integrated documents are served with pretty directory URLs. Root
-        // absolute assets remain correct for both emitted files and rewrites.
-        cssHrefs.push('/vmz.css');
+function resolveAppDistDir(opts, outDir) {
+    if (opts.appDistDir) {
+        const p = path.resolve(opts.appDistDir);
+        return fs.existsSync(path.join(p, 'vmz-dom.js')) ? p : null;
     }
-    if (designsHref)
-        cssHrefs.push(hostChrome ? `/${designsHref}` : prefix + designsHref);
-    const cssLink = cssHrefs.map((href) => `  <link rel="stylesheet" href="${esc(href)}" />`).join('\n') + (cssHrefs.length ? '\n' : '');
+    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 = '' }) {
+    const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
     const navItems = nav
         .map((n) => {
-        const href = relativeHref(htmlRel, n.href, route);
+        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>`;
     })
@@ -188,21 +213,7 @@ function renderStaticHtml({ title, locale, route, nav, bodyHtml, headings, desig
 ${navItems}
     </ul>
   </nav>`;
-    if (hostChrome) {
-        const header = hostChrome.header.replace(/(<a\s+href="\/d\/?")([^>]*>文档<\/a>)/, '$1 aria-current="page"$2');
-        return `<!DOCTYPE html>
-<html lang="${esc(locale)}">
-<head>
-  <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>${esc(title)}</title>
-${cssLink}</head>
-<body data-vmz-hydrate="island-only">
-  <div class="site site--docs">
-  <a class="skip-link" href="#main">Skip to content</a>
-${header}
-  <div class="doc-body">
-    <aside class="doc-sidebar">
+    return `    <aside class="doc-sidebar">
 ${docsNav}
 ${searchShellHtml}
     </aside>
@@ -211,54 +222,65 @@ ${searchShellHtml}
 ${bodyHtml}
 ${playgroundShellHtml}
   </main>
-    </div>
-  </div>
-${hostChrome.footer}
-  </div>
-</body>
-</html>
-`;
+    </div>`;
+}
+/**
+ * No-JS readable static HTML: nav + main landmarks, Island shells without scripts.
+ * Integrated mounts wrap content in compiled DocumentLayout (SiteHeader/SiteFooter SSR).
+ */
+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) : './';
+    /** @type {string[]} */
+    const cssHrefs = [];
+    if (useCompiledShell) {
+        cssHrefs.push('/vmz.css');
     }
-    return `<!DOCTYPE html>
-<html lang="${esc(locale)}">
-<head>
-  <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>${esc(title)}</title>
-${cssLink}</head>
-<body data-vmz-hydrate="island-only">
-  <a class="skip-link" href="#main">Skip to content</a>
-${docsNav}
+    if (designsHref)
+        cssHrefs.push(useCompiledShell ? `/${designsHref}` : prefix + designsHref);
+    /** @type {string} */
+    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>
-</body>
-</html>
 `;
-}
-/**
- * Integrated DocumentMount: reuse host SiteHeader / SiteFooter .vmz templates.
- * @param {string} projectRoot
- * @returns {{ header: string, footer: string } | null}
- */
-function resolveHostSiteChrome(projectRoot) {
-    const headerPath = path.join(projectRoot, 'src', 'components', 'SiteHeader.vmz');
-    const footerPath = path.join(projectRoot, 'src', 'components', 'SiteFooter.vmz');
-    if (!fs.existsSync(headerPath) || !fs.existsSync(footerPath))
-        return null;
-    const header = extractVmzTemplateHtml(headerPath);
-    const footer = extractVmzTemplateHtml(footerPath);
-    if (!header || !footer)
-        return null;
-    return { header, footer };
-}
-/** @param {string} filePath */
-function extractVmzTemplateHtml(filePath) {
-    const src = fs.readFileSync(filePath, 'utf8');
-    const m = src.match(/<template>([\s\S]*?)<\/template>/);
-    return m ? m[1].trim() : '';
+    }
+    const native = requireNativeAddon();
+    if (typeof native.generateHtmlShell !== 'function') {
+        throw new Error('vmz native addon missing generateHtmlShell — rebuild with `pnpm napi:build`');
+    }
+    return native.generateHtmlShell({
+        title,
+        lang: locale,
+        cssHrefs,
+        bodyHtml: bodyInner,
+        bodyAttrs: ['data-vmz-hydrate', 'island-only'],
+    });
 }
 function relativeHref(fromHtmlRel, toRoute, _fromRoute) {
     const toParts = String(toRoute).replace(/^\//, '').split('/').filter(Boolean);

package/dist/document-check.d.ts

@@ -1,5 +1,8 @@
 /**
  * Build DocumentManifest + run / --strict checks.
+ *
+ * Author documents config is parsed by Rust DocumentRoutePlan; TS only
+ * merges filesystem scan (pageKeys) and coverage diagnostics.
  */
 /**
  * Resolve project documents root.
@@ -7,14 +10,30 @@
  */
 export declare function resolveDocumentsRoot(projectRoot: any): string;
 /**
- * Parse documents.config.json or a JSON-compatible export-default .ts/.js.
+ * Load normalized DocumentRoutePlan from Rust (author JSON5/JSON/declaration).
+ * @param {string} projectRoot
+ */
+export declare function loadDocumentsRoutePlan(projectRoot: any): any;
+/**
+ * @deprecated Prefer loadDocumentsRoutePlan(projectRoot). Kept for call sites that
+ * only need the plan-shaped config fields.
  * @param {string} documentsRoot
- * @returns {{ config: Record<string, any> | null, diagnostics: any[], configPath: string | null }}
  */
 export declare function loadDocumentsConfig(documentsRoot: any): {
-    config: any;
-    diagnostics: any[];
+    config: {
+        defaultLocale: any;
+        locales: {
+            [k: string]: {
+                label: unknown;
+            };
+        };
+        collections: {
+            [k: string]: any;
+        };
+    };
+    diagnostics: any;
     configPath: string;
+    plan: any;
 };
 /**
  * @param {object} opts
@@ -27,7 +46,7 @@ export declare function checkDocuments(opts: any): {
     root: string;
     defaultLocale: any;
     locales: any[];
-    localeLabels: {};
+    localeLabels: any;
     collections: any[];
     mounts: any[];
     pages: {