@vmz/vmz 0.0.4 → 0.1.1

package/dist/dev-session.js

@@ -4,12 +4,17 @@
  *
  * Rebuilds go through the N-API `Workspace` — never spawn `cargo` / `vmz-tools`.
  * session: only dirty leaves are marked; Workspace emits affected deployment units.
+ *
+ * Reload policy (Vite-like — author never hand-restarts):
+ * 1. Prefer in-process soft reload (`POST /__vmz/reload`) with transitive `?t=` via serve-host hook.
+ * 2. Soft reload only re-imports affected pages unless shared `lib/` / full rebuild.
+ * 3. Soft reload failure → **auto-respawn** serve-host (fresh ESM graph), not "keep broken host".
  */
 import { spawn } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { buildIntegratedDocuments, projectHasDocuments } from './document-integrate.js';
-import { createWorkspace } from './index.js';
+import { createWorkspace, resolveNativePath } from './index.js';
 import { emitLocaleRuntimeModules, localeHasErrors } from './locale-check.js';
 import { log } from './log.js';
 import { diffFingerprints, fileFingerprintMap } from './watch-diff.js';
@@ -20,6 +25,7 @@ import { diffFingerprints, fileFingerprintMap } from './watch-diff.js';
  * @property {string} [host]
  * @property {number} [port]
  * @property {number} [pollMs]
+ * @property {'browser' | 'mini-program-wechat'} [target]
  * @property {AbortSignal} [signal]
  * @property {typeof createWorkspace} [createWorkspaceFn]
  * @property {(opts: { project: string, outDir: string, host: string, port: number }) => import('node:child_process').ChildProcess} [spawnHostFn]
@@ -34,6 +40,7 @@ export function createDevSession(options) {
     const host = options.host ?? '127.0.0.1';
     const port = options.port ?? 5173;
     const pollMs = Math.max(50, options.pollMs ?? 300);
+    const wechatPreview = options.target === 'mini-program-wechat';
     const createWs = options.createWorkspaceFn ?? createWorkspace;
     const spawnHost = options.spawnHostFn ?? defaultSpawnHost;
     const softReload = options.softReloadFn ?? defaultSoftReload;
@@ -51,8 +58,8 @@ export function createDevSession(options) {
     }
     function emitLocales() {
         const localeEmit = emitLocaleRuntimeModules(project, outDir);
+        log.diagnostics(localeEmit.diagnostics ?? []);
         if (!localeEmit.ok || localeHasErrors({ diagnostics: localeEmit.diagnostics })) {
-            log.diagnostics(localeEmit.diagnostics ?? []);
             log.error('locale runtime emit failed');
             return false;
         }
@@ -71,13 +78,90 @@ export function createDevSession(options) {
         log.info(`${label} ok (${mode}; chunks=[${chunks}]; ${(report.emitted ?? []).length} emitted)`);
         return true;
     }
+    /**
+     * Rewrite `dist/wechat` so WeChat DevTools (already open) recompiles WXSS.
+     * Preview is vendor compile, not the browser serve-host.
+     */
+    function packWechatPreview() {
+        if (typeof ws.lowerMiniprogramWechatPackaging !== 'function') {
+            log.error('wechat pack: workspace missing lowerMiniprogramWechatPackaging');
+            return false;
+        }
+        let report;
+        try {
+            const raw = ws.lowerMiniprogramWechatPackaging();
+            report = typeof raw === 'string' ? JSON.parse(raw) : raw;
+        }
+        catch (err) {
+            log.error(`wechat pack failed: ${err}`);
+            return false;
+        }
+        log.diagnostics(report.diagnostics ?? []);
+        if (report.status !== 'ready') {
+            log.error(`wechat pack ${report.status || 'failed'}`);
+            return false;
+        }
+        const packRoot = report.packRoot || 'dist/wechat';
+        log.info(`wechat pack ok → ${path.join(project, packRoot)} (WeChat DevTools compiles WXSS here)`);
+        return true;
+    }
+    async function waitHostReady(timeoutMs = 8000) {
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+            try {
+                const res = await fetch(`http://${host}:${port}/__vmz/ready`);
+                if (res.ok)
+                    return;
+            }
+            catch {
+                /* not up yet */
+            }
+            await sleep(50);
+        }
+        throw new Error(`serve-host not ready on ${host}:${port}`);
+    }
+    async function waitHostGone(timeoutMs = 3000) {
+        const start = Date.now();
+        while (Date.now() - start < timeoutMs) {
+            try {
+                await fetch(`http://${host}:${port}/__vmz/health`);
+                await sleep(40);
+            }
+            catch {
+                return;
+            }
+        }
+    }
+    async function respawnHost(reason) {
+        log.warn(`respawning serve-host (${reason})…`);
+        killChild(child);
+        child = null;
+        await waitHostGone();
+        child = spawnHost({ project, outDir, host, port });
+        await waitHostReady();
+        log.info('serve-host respawned — browser SSE will reconnect and reload');
+    }
+    /**
+     * Soft reload first; on failure auto-respawn so authors never hand-restart.
+     * @param {object} payload
+     */
+    async function reloadAfterBuild(payload) {
+        try {
+            await softReload(host, port, payload);
+            return 'soft';
+        }
+        catch (err) {
+            log.warn(`soft reload failed (${err}) — auto-respawning serve-host`);
+            await respawnHost('soft-reload-failed');
+            return 'respawn';
+        }
+    }
     async function start() {
         const src = path.join(project, 'src');
         if (!existsSync(src)) {
             throw new Error(`vmz dev: missing src/ under ${project}`);
         }
         log.info('initial build (N-API workspace, full)…');
-        // Empty dirty → full project build (session).
         const initial = rebuild();
         if (!printReport(initial, 'build')) {
             throw new Error('vmz dev: initial build failed');
@@ -88,17 +172,32 @@ export function createDevSession(options) {
                 throw new Error('vmz dev: integrated document build failed');
             }
         }
-        const hostJs = path.join(outDir, 'vmz-serve-host.mjs');
-        if (!existsSync(hostJs)) {
-            throw new Error(`vmz dev: missing ${hostJs}`);
+        if (wechatPreview) {
+            if (!packWechatPreview()) {
+                throw new Error('vmz dev: wechat pack failed');
+            }
+        }
+        else {
+            const hostJs = path.join(outDir, 'vmz-serve-host.mjs');
+            if (!existsSync(hostJs)) {
+                throw new Error(`vmz dev: missing ${hostJs}`);
+            }
+            child = spawnHost({ project, outDir, host, port });
+            await waitHostReady().catch((err) => {
+                log.warn(String(err));
+            });
         }
-        child = spawnHost({ project, outDir, host, port });
         const docsRoot = path.join(project, 'documents');
         const localesRoot = path.join(project, 'locales');
         const watchRoots = [src].concat(existsSync(docsRoot) ? [docsRoot] : []).concat(existsSync(localesRoot) ? [localesRoot] : []);
-        log.info(`dev → http://${host}:${port} (watching ${watchRoots.join(', ')})`);
+        if (wechatPreview) {
+            log.info(`dev → WeChat DevTools (watching ${watchRoots.join(', ')}; keep dist/wechat open)`);
+        }
+        else {
+            log.info(`dev → http://${host}:${port} (watching ${watchRoots.join(', ')})`);
+        }
         /** @type {Map<string, Map<string, string>>} */
-        let fingerprints = new Map();
+        const fingerprints = new Map();
         for (const root of watchRoots) {
             fingerprints.set(root, fileFingerprintMap(root));
         }
@@ -107,21 +206,35 @@ export function createDevSession(options) {
             void stop();
         };
         signal?.addEventListener('abort', onAbort, { once: true });
+        /**
+         * Wait until src/ stops changing (multi-file agent edits).
+         */
+        async function coalesceSrcBurst() {
+            let guard = 0;
+            while (guard++ < 20) {
+                await sleep(220);
+                const prev = fingerprints.get(src) || new Map();
+                const next = fileFingerprintMap(src);
+                const diff = diffFingerprints(prev, next);
+                if (!diff.changed.length && !diff.deleted.length)
+                    break;
+                fingerprints.set(src, next);
+            }
+        }
         try {
             while (!stopped && !signal?.aborted) {
                 await sleep(pollMs);
                 if (stopped || signal?.aborted)
                     break;
-                if (child && child.exitCode != null) {
+                if (!wechatPreview && child && child.exitCode != null) {
                     log.warn(`serve-host exited (${child.exitCode}) — respawning…`);
                     child = spawnHost({ project, outDir, host, port });
+                    await waitHostReady().catch(() => { });
                     continue;
                 }
                 /** @type {{ srcChanged: string[], srcDeleted: string[], docsDirty: boolean, localesDirty: boolean }} */
                 let batch = { srcChanged: [], srcDeleted: [], docsDirty: false, localesDirty: false };
                 try {
-                    // Probe only — keep prior fingerprints until debounce resample
-                    // (same contract as pre-docs watcher: empty second pass would miss soft reload).
                     for (const root of watchRoots) {
                         const prev = fingerprints.get(root) || new Map();
                         const next = fileFingerprintMap(root);
@@ -145,8 +258,12 @@ export function createDevSession(options) {
                 }
                 if (!batch.srcChanged.length && !batch.srcDeleted.length && !batch.docsDirty && !batch.localesDirty)
                     continue;
-                await sleep(200);
-                // Resample against the same prior fingerprints, then commit.
+                if (batch.srcChanged.length + batch.srcDeleted.length > 1) {
+                    await coalesceSrcBurst();
+                }
+                else {
+                    await sleep(200);
+                }
                 batch = { srcChanged: [], srcDeleted: [], docsDirty: false, localesDirty: false };
                 for (const root of watchRoots) {
                     const prev = fingerprints.get(root) || new Map();
@@ -180,7 +297,6 @@ export function createDevSession(options) {
                         continue;
                     }
                     if (batch.docsDirty || projectHasDocuments(project)) {
-                        // App rebuild may refresh designs CSS consumed by documents.
                         const docs = await buildIntegratedDocuments({ projectRoot: project, outDir });
                         if (!docs.ok) {
                             log.warn('document mount rebuild failed — keeping previous docs');
@@ -189,22 +305,26 @@ export function createDevSession(options) {
                             needFullReload = true;
                         }
                     }
-                    try {
-                        await softReload(host, port, {
-                            affectedChunks: report.affectedChunks ?? [],
-                            seedChunks: report.seedChunks ?? [],
-                            full: Boolean(report.full) || needFullReload,
-                            islandHmr: Boolean(report.islandHmr) && !needFullReload,
-                        });
-                        log.info(needFullReload
+                    if (wechatPreview) {
+                        if (!packWechatPreview()) {
+                            log.warn('wechat pack failed — keeping previous dist/wechat');
+                        }
+                        continue;
+                    }
+                    const kind = await reloadAfterBuild({
+                        affectedChunks: report.affectedChunks ?? [],
+                        seedChunks: report.seedChunks ?? [],
+                        emitted: report.emitted ?? [],
+                        full: Boolean(report.full) || needFullReload,
+                        islandHmr: Boolean(report.islandHmr) && !needFullReload,
+                    });
+                    log.info(kind === 'respawn'
+                        ? 'reload ok (respawned serve-host)'
+                        : needFullReload
                             ? 'soft reload ok (full page; docs)'
                             : report.islandHmr
                                 ? 'soft reload ok (island HMR)'
-                                : 'soft reload ok (full page)');
-                    }
-                    catch (err) {
-                        log.warn(`soft reload failed (${err}) — keeping previous serve-host (fix and save)`);
-                    }
+                                : 'soft reload ok');
                     continue;
                 }
                 if (batch.localesDirty) {
@@ -213,15 +333,19 @@ export function createDevSession(options) {
                         log.warn('locale runtime emit failed — keeping previous modules');
                         continue;
                     }
-                    try {
-                        await softReload(host, port, { full: true, islandHmr: false });
-                        log.info('soft reload ok (full page; locales)');
+                    if (wechatPreview) {
+                        if (!packWechatPreview()) {
+                            log.warn('wechat pack failed — keeping previous dist/wechat');
+                        }
+                        if (!batch.docsDirty)
+                            continue;
                     }
-                    catch (err) {
-                        log.warn(`soft reload failed (${err}) — keeping previous serve-host (fix and save)`);
+                    else {
+                        const kind = await reloadAfterBuild({ full: true, islandHmr: false, emitted: [] });
+                        log.info(kind === 'respawn' ? 'reload ok (respawned; locales)' : 'soft reload ok (full page; locales)');
+                        if (!batch.docsDirty)
+                            continue;
                     }
-                    if (!batch.docsDirty)
-                        continue;
                 }
                 if (batch.docsDirty) {
                     log.info('documents change detected — rebuilding document mount…');
@@ -230,12 +354,14 @@ export function createDevSession(options) {
                         log.warn('document mount rebuild failed — keeping previous docs');
                         continue;
                     }
-                    try {
-                        await softReload(host, port, { full: true, islandHmr: false });
-                        log.info('soft reload ok (full page; docs)');
+                    if (wechatPreview) {
+                        if (!packWechatPreview()) {
+                            log.warn('wechat pack failed — keeping previous dist/wechat');
+                        }
                     }
-                    catch (err) {
-                        log.warn(`soft reload failed (${err}) — keeping previous serve-host (fix and save)`);
+                    else {
+                        const kind = await reloadAfterBuild({ full: true, islandHmr: false, emitted: [] });
+                        log.info(kind === 'respawn' ? 'reload ok (respawned; docs)' : 'soft reload ok (full page; docs)');
                     }
                 }
             }
@@ -287,6 +413,7 @@ function defaultSpawnHost(opts) {
             VMZ_PORT: String(opts.port),
             VMZ_HOST: opts.host,
             VMZ_DEV: '1',
+            VMZ_NATIVE_NODE: resolveNativePath(),
         },
         stdio: ['ignore', 'inherit', 'inherit'],
     });

package/dist/document-build.js

@@ -12,6 +12,8 @@ import { artifactHrefFromHtml, buildDocumentIslands, buildDocumentSearch, collec
 import { resolveMarkdownEngine } from './document-markdown.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
  */
@@ -113,7 +115,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,
@@ -147,10 +149,10 @@ export async function buildDocuments(opts) {
             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 };
 }
 /**
@@ -164,12 +166,12 @@ function renderStaticHtml({ title, locale, route, nav, bodyHtml, headings, desig
     /** @type {string[]} */
     const cssHrefs = [];
     if (hostChrome) {
-        // Same application stylesheet as landing pages (header/footer chrome).
-        cssHrefs.push(`${prefix}vmz.css`);
+        // Integrated documents are served with pretty directory URLs. Root
+        // absolute assets remain correct for both emitted files and rewrites.
+        cssHrefs.push('/vmz.css');
     }
     if (designsHref)
-        cssHrefs.push(prefix + designsHref);
-    const cssLink = cssHrefs.map((href) => `  <link rel="stylesheet" href="${esc(href)}" />`).join('\n') + (cssHrefs.length ? '\n' : '');
+        cssHrefs.push(hostChrome ? `/${designsHref}` : prefix + designsHref);
     const navItems = nav
         .map((n) => {
         const href = relativeHref(htmlRel, n.href, route);
@@ -187,51 +189,50 @@ function renderStaticHtml({ title, locale, route, nav, bodyHtml, headings, desig
 ${navItems}
     </ul>
   </nav>`;
+    /** @type {string} */
+    let bodyInner;
     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">
+        bodyInner = `  <div class="site site--docs">
   <a class="skip-link" href="#main">Skip to content</a>
 ${header}
+  <div class="doc-body">
+    <aside class="doc-sidebar">
 ${docsNav}
 ${searchShellHtml}
-  <div class="doc-body">
+    </aside>
+    <div class="doc-content">
   ${toc}<main id="main">
 ${bodyHtml}
 ${playgroundShellHtml}
   </main>
+    </div>
   </div>
 ${hostChrome.footer}
   </div>
-</body>
-</html>
 `;
     }
-    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>
+    else {
+        bodyInner = `  <a class="skip-link" href="#main">Skip to content</a>
 ${docsNav}
 ${searchShellHtml}
   ${toc}<main id="main">
 ${bodyHtml}
 ${playgroundShellHtml}
   </main>
-</body>
-</html>
 `;
+    }
+    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'],
+    });
 }
 /**
  * Integrated DocumentMount: reuse host SiteHeader / SiteFooter .vmz templates.

package/dist/document-cmd.js

@@ -2,7 +2,6 @@
 /**
  * `vmz document` / `vmz docs` CLI .
  */
-import fs from 'node:fs';
 import path from 'node:path';
 import { buildDocuments } from './document-build.js';
 import { checkDocuments, manifestHasErrors } from './document-check.js';
@@ -12,6 +11,7 @@ import { resolveMarkdownEngine } from './document-markdown.js';
 import { createWorkspace } from './index.js';
 import { log } from './log.js';
 import { parseArgs } from './cli.js';
+import { emitPrettyJson } from './pretty-json.js';
 function printDocumentHelp() {
     console.log(`vmz document — project /documents domain
 
@@ -95,14 +95,7 @@ async function cmdDocumentCheck(args) {
     }
     const jsonOut = args.json;
     if (jsonOut) {
-        const text = JSON.stringify(manifest, null, 2);
-        if (typeof jsonOut === 'string') {
-            fs.writeFileSync(jsonOut, text + '\n', 'utf8');
-            log.info(`wrote ${jsonOut}`);
-        }
-        else {
-            console.log(text);
-        }
+        emitPrettyJson(jsonOut, manifest, { logWrote: (p) => log.info(`wrote ${p}`) });
     }
     else {
         for (const d of manifest.diagnostics) {

package/dist/document-enrich.js

@@ -199,6 +199,14 @@ function resolveDocHref(href, fromPageKey, locale, routeBase, pageKeySet) {
     pk = normalizePageKey(pk);
     const keys = pageKeySet.get(locale) || new Set();
     if (!keys.has(pk)) {
+        // A directory index and a leaf page share the same normalized PageKey shape.
+        // Prefer the regular sibling resolution above, then retry relative to the
+        // PageKey itself so `guide/optimizations/index.md` keeps its directory.
+        const indexJoined = path.posix.normalize(path.posix.join(fromPageKey || '.', pathPart));
+        const indexPk = normalizePageKey(indexJoined.replace(/^\.\//, ''));
+        if (keys.has(indexPk)) {
+            return { ok: true, locale, pageKey: indexPk, anchor, anchors: [] };
+        }
         return { ok: false, reason: `no PageKey ${pk} in ${locale}` };
     }
     return { ok: true, locale, pageKey: pk, anchor, anchors: [] };

package/dist/document-integrate.js

@@ -8,6 +8,7 @@ import path from 'node:path';
 import { buildDocuments } from './document-build.js';
 import { resolveDocumentsRoot } from './document-check.js';
 import { log } from './log.js';
+import { requireNativeAddon } from './native-addon.js';
 /**
  * @param {string} projectRoot
  */
@@ -66,23 +67,15 @@ function writeMountRootRedirects(manifest, outDir) {
         const relDir = base.replace(/^\//, '');
         const abs = path.join(outDir, relDir, 'index.html');
         fs.mkdirSync(path.dirname(abs), { recursive: true });
-        const html = `<!DOCTYPE html>
-<html lang="${escapeAttr(defaultLocale)}">
-<head>
-  <meta charset="utf-8" />
-  <meta http-equiv="refresh" content="0;url=${escapeAttr(target)}" />
-  <link rel="canonical" href="${escapeAttr(target)}" />
-  <title>Documents</title>
-</head>
-<body>
-  <p><a href="${escapeAttr(target)}">Continue to ${escapeAttr(defaultLocale)} docs</a></p>
-</body>
-</html>
-`;
+        const native = requireNativeAddon();
+        if (typeof native.generateRedirectHtml !== 'function') {
+            throw new Error('vmz native addon missing generateRedirectHtml — rebuild with `pnpm napi:build`');
+        }
+        const html = native.generateRedirectHtml({
+            lang: defaultLocale,
+            target,
+            title: 'Documents',
+        });
         fs.writeFileSync(abs, html, 'utf8');
     }
 }
-/** @param {string} s */
-function escapeAttr(s) {
-    return String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
-}

package/dist/embedded-packaging.d.ts

@@ -0,0 +1,22 @@
+/**
+ * rust-embedded packaging adapter: resource index + baseline closure.
+ * Packaging only — does not invent route / MIME / fallback semantics.
+ */
+export declare const EMBEDDED_RESOURCE_INDEX_SCHEMA = "vmz.embedded.resource_index.v0";
+/**
+ * Walk outDir and build path → digest → relative blob path map.
+ * Copies files into `dist/_vmz/embedded-baseline/` (whole release, no file-level mix).
+ * @param {string} outDir
+ * @param {{ siteId?: string, contractDigest?: string | null }} [opts]
+ */
+export declare function emitEmbeddedPackaging(outDir: any, opts?: {}): {
+    index: {
+        schema: string;
+        siteId: any;
+        contractDigest: any;
+        objectCount: number;
+        objects: any[];
+    };
+    indexPath: string;
+    baselineDir: string;
+};