@vmz/vmz 0.3.13 → 0.3.15

package/dist/dev/dev-session.js

@@ -10,7 +10,8 @@
  * 3. Soft reload failure → **auto-respawn** serve-host (fresh ESM graph), not "keep broken host".
  */
 import { spawn } from 'node:child_process';
-import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { buildIntegratedDocuments, projectHasDocuments } from '../document/document-integrate.js';
 import { createWorkspace, resolveNativePath } from '../workspace/public-api.js';
@@ -22,6 +23,8 @@ import { coalesceRootBurst, collectDevWatchRoots, classifyWatchRoot, isDependenc
 import { createConfigCycle } from './config-cycle.js';
 import { buildReloadPayload, filterGenerationIgnore, parseHmrPlan, registerWrittenOutputsIgnore, shouldSoftReload, staticRevisionFromArtifact, } from './dev-incremental.js';
 import { diffFingerprints, fileFingerprintMap } from '../workspace/watch-diff.js';
+import { packFromDeploymentIr, deploymentUnitOrigins } from '../workspace/pack.js';
+import { loadDeploymentIr } from '../workspace/bundler-adapter.js';
 /** Track serve-host so a failed/killed launcher cannot leave an orphan port. */
 const DEV_HOST_PID = '.vmz-dev-host.pid';
 function cycleFailure(report) {
@@ -29,6 +32,218 @@ function cycleFailure(report) {
     const error = new Error(detail);
     return report.error ? Object.assign(error, { diagnostic: report.error }) : error;
 }
+/**
+ * Pack 输入快照：dev 只在「决定产物字节的全部输入」完全不变时才复用上次产物。
+ * 判据是文件内容哈希，不使用 mtime、文件数量或后缀推导；读不到或未知的输入一律按变更处理。
+ */
+const PACK_INPUT_IGNORED_DIRS = new Set(['_vmz', 'node_modules', '.cache', '.git']);
+const PACK_INPUT_IGNORED_NAMES = /^\.vmz-dev-host\.pid$/;
+/** Rust 侧的模块路径带 `//?/`（或 `\\?\`）verbatim 前缀，落盘读取前需要剥离。 */
+function packInputFsPath(filePath) {
+    return filePath.replace(/^(?:\\\\\?\\|\/\/\?\/)/, '').replace(/\\/g, '/');
+}
+function readFileDigest(filePath) {
+    try {
+        return createHash('sha256').update(readFileSync(filePath)).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+function findLockfile(project) {
+    let dir = path.resolve(project);
+    while (true) {
+        const candidate = path.join(dir, 'pnpm-lock.yaml');
+        if (existsSync(candidate))
+            return candidate;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+function listPackInputDir(dir) {
+    const names = [];
+    const walk = (current, prefix) => {
+        let entries;
+        try {
+            entries = readdirSync(current, { withFileTypes: true });
+        }
+        catch {
+            return false;
+        }
+        entries.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+        for (const entry of entries) {
+            if (PACK_INPUT_IGNORED_DIRS.has(entry.name) || PACK_INPUT_IGNORED_NAMES.test(entry.name))
+                continue;
+            const rel = prefix ? `${prefix}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (!walk(path.join(current, entry.name), rel))
+                    return false;
+            }
+            else {
+                names.push(rel);
+            }
+        }
+        return true;
+    };
+    return walk(dir, '') ? names : null;
+}
+/** manifest 形状不认识时返回 null（而非空集合），避免把未知输入当成「没变化」。 */
+function packInputFiles(manifest) {
+    if (!Array.isArray(manifest.chunks) || manifest.chunks.length === 0)
+        return null;
+    const files = new Set();
+    for (const chunk of manifest.chunks) {
+        if (!Array.isArray(chunk.modules))
+            return null;
+        for (const module of chunk.modules) {
+            if (typeof module !== 'string' || !module)
+                return null;
+            files.add(packInputFsPath(module));
+        }
+    }
+    if (!Array.isArray(manifest.styles))
+        return null;
+    for (const style of manifest.styles) {
+        if (!Array.isArray(style.sourcePaths))
+            return null;
+        for (const source of style.sourcePaths) {
+            if (typeof source !== 'string' || !source)
+                return null;
+            files.add(packInputFsPath(source));
+        }
+    }
+    return [...files].sort();
+}
+/** pack 只经 `deploymentUnitOrigins` 读取 IR；对这份 origins 取规范摘要，避免把构建期 affected/seed 噪声算成输入变更。 */
+function deploymentOriginsDigest(outDir) {
+    try {
+        const origins = deploymentUnitOrigins(outDir, loadDeploymentIr(outDir));
+        const canonical = Object.keys(origins)
+            .sort()
+            .map((key) => `${key}\u0000${origins[key]}`);
+        return createHash('sha256').update(canonical.join('\u0001')).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+/** 记下决定 pack 产物的全部输入；任何一项取不到就放弃快照（等同于永远重打包）。 */
+export function capturePackInputSnapshot(manifest, outDir, project) {
+    const inputs = packInputFiles(manifest);
+    if (!inputs)
+        return null;
+    const files = [];
+    for (const file of inputs) {
+        const digest = readFileDigest(file);
+        if (!digest)
+            return null;
+        files.push({ path: file, digest });
+    }
+    const listings = [];
+    for (const dir of [...new Set(files.map((file) => path.dirname(file.path)))].sort()) {
+        if (dir.split(/[\\/]/).includes('node_modules'))
+            continue;
+        const names = listPackInputDir(dir);
+        if (!names)
+            return null;
+        listings.push({ dir, names });
+    }
+    const deploymentOrigins = deploymentOriginsDigest(outDir);
+    if (!deploymentOrigins)
+        return null;
+    const lockfilePath = findLockfile(project);
+    if (!lockfilePath)
+        return null;
+    const lockfileDigest = readFileDigest(lockfilePath);
+    if (!lockfileDigest)
+        return null;
+    const manifestPath = path.join(outDir, '_vmz', 'pack-manifest.json');
+    const manifestDigest = readFileDigest(manifestPath);
+    if (!manifestDigest)
+        return null;
+    return {
+        files,
+        listings,
+        deploymentOrigins,
+        lockfile: { path: lockfilePath, digest: lockfileDigest },
+        manifest: { path: manifestPath, digest: manifestDigest },
+    };
+}
+/** 返回 null 表示全部输入字节全等；否则返回第一个变化原因。 */
+export function packInputsChangedReason(snapshot, outDir) {
+    const lockfileDigest = readFileDigest(snapshot.lockfile.path);
+    if (!lockfileDigest)
+        return `lockfile unreadable: ${snapshot.lockfile.path}`;
+    if (lockfileDigest !== snapshot.lockfile.digest)
+        return 'lockfile changed';
+    const manifestDigest = readFileDigest(snapshot.manifest.path);
+    if (!manifestDigest)
+        return `pack manifest unreadable: ${snapshot.manifest.path}`;
+    if (manifestDigest !== snapshot.manifest.digest)
+        return 'pack manifest changed';
+    const deploymentOrigins = deploymentOriginsDigest(outDir);
+    if (!deploymentOrigins)
+        return 'deployment IR unreadable';
+    if (deploymentOrigins !== snapshot.deploymentOrigins)
+        return 'deployment IR changed';
+    for (const file of snapshot.files) {
+        const digest = readFileDigest(file.path);
+        if (!digest)
+            return `input unreadable: ${file.path}`;
+        if (digest !== file.digest)
+            return `input changed: ${file.path}`;
+    }
+    for (const listing of snapshot.listings) {
+        const names = listPackInputDir(listing.dir);
+        if (!names)
+            return `input directory unreadable: ${listing.dir}`;
+        if (names.length !== listing.names.length)
+            return `input directory changed: ${listing.dir}`;
+        for (let i = 0; i < names.length; i += 1) {
+            if (names[i] !== listing.names[i])
+                return `input directory changed: ${listing.dir}`;
+        }
+    }
+    return null;
+}
+/** 复用上次 manifest 前确认 entry/chunk/island 查表指向的文件仍在盘上；缺任何一个就退回真实 pack。 */
+export function missingPackOutput(manifest, outDir) {
+    const packDir = path.join(outDir, '_vmz', 'pack');
+    if (!existsSync(path.join(outDir, '_vmz', 'pack-manifest.json')))
+        return '_vmz/pack-manifest.json';
+    const names = new Set();
+    for (const entry of manifest.entryFiles ?? [])
+        if (typeof entry.file === 'string' && entry.file)
+            names.add(entry.file);
+    for (const dynamic of manifest.dynamicFiles ?? []) {
+        if (typeof dynamic.from === 'string' && dynamic.from)
+            names.add(dynamic.from);
+        if (typeof dynamic.to === 'string' && dynamic.to)
+            names.add(dynamic.to);
+    }
+    for (const chunk of manifest.chunks ?? []) {
+        if (typeof chunk.fileName === 'string' && chunk.fileName)
+            names.add(chunk.fileName);
+        if (typeof chunk.sourceMap === 'string' && chunk.sourceMap)
+            names.add(chunk.sourceMap);
+    }
+    for (const style of manifest.styles ?? [])
+        if (typeof style.fileName === 'string' && style.fileName)
+            names.add(style.fileName);
+    for (const asset of manifest.assets ?? [])
+        if (typeof asset.fileName === 'string' && asset.fileName)
+            names.add(asset.fileName);
+    for (const unit of manifest.unitChunks ?? [])
+        if (typeof unit.fileName === 'string' && unit.fileName)
+            names.add(unit.fileName);
+    for (const name of names) {
+        if (!existsSync(path.join(packDir, ...name.split('/'))))
+            return name;
+    }
+    return null;
+}
 export function createDevSession(options) {
     const project = options.project;
     const outDir = options.outDir;
@@ -39,7 +254,8 @@ export function createDevSession(options) {
     let delivery = options.delivery ?? null;
     const createWs = options.createWorkspaceFn ?? createWorkspace;
     const spawnHost = options.spawnHostFn ?? defaultSpawnHost;
-    const softReload = options.softReloadFn ?? defaultSoftReload;
+    const softReload = options.softReloadFn ?? ((body) => defaultReloadRequest(host, port, body));
+    const packBrowser = options.packFn ?? packFromDeploymentIr;
     const makeConfigCycle = options.configCycleFn ?? createConfigCycle;
     const configCandidates = configCandidatePaths(project);
     let configCycle = null;
@@ -48,6 +264,9 @@ export function createDevSession(options) {
     let stopped = false;
     let lastOutputRevision = null;
     let lastStaticRevision = null;
+    let lastBuildMs = 0;
+    let lastPackManifest = null;
+    let lastPackInputs = null;
     const generationIgnore = new Set();
     function planAndRebuild(changes) {
         if (changes?.length)
@@ -61,7 +280,9 @@ export function createDevSession(options) {
         catch {
             hmrPlan = null;
         }
+        const startedAt = Date.now();
         const report = ws.build();
+        lastBuildMs = Date.now() - startedAt;
         return { report, hmrPlan };
     }
     function rebuild(changes) {
@@ -75,7 +296,6 @@ export function createDevSession(options) {
     }
     async function maybeReloadAfterBuild(report, hmrPlan, opts = {}) {
         const rev = report.outputRevision ?? report.output_revision ?? null;
-        const skipEntry = Boolean(rev && rev === lastOutputRevision);
         if (!opts.force && !opts.staticOnly && !shouldSoftReload(report, lastOutputRevision)) {
             log.info('rebuild ok — artifact unchanged, skip soft reload');
             if (rev)
@@ -85,14 +305,12 @@ export function createDevSession(options) {
         }
         const payload = buildReloadPayload(report, hmrPlan, {
             staticRevision: lastStaticRevision ?? undefined,
-            skipEntryRewrite: skipEntry && !opts.force,
         });
         if (opts.staticOnly) {
             payload.full = false;
             payload.islandHmr = false;
-            payload.skipEntryRewrite = true;
         }
-        const kind = await reloadAfterBuild(payload);
+        const kind = await reloadAfterBuild(payload, { staticOnly: Boolean(opts.staticOnly) });
         if (rev)
             lastOutputRevision = rev;
         registerWrittenOutputsIgnore(report.writtenOutputs ?? report.written_outputs, outDir, project, generationIgnore);
@@ -117,7 +335,7 @@ export function createDevSession(options) {
             return false;
         const mode = report.full ? 'full' : 'affected';
         const chunks = (report.affectedChunks || []).join(', ') || '(none)';
-        log.info(`${label} ok (${mode}; chunks=[${chunks}]; ${(report.emitted ?? []).length} emitted)`);
+        log.info(`${label} ok (${mode}; chunks=[${chunks}]; ${(report.emitted ?? []).length} emitted; ${lastBuildMs}ms build)`);
         return true;
     }
     /**
@@ -149,11 +367,11 @@ export function createDevSession(options) {
         log.info(`wechat pack ok → ${path.join(project, packRoot)} (WeChat DevTools compiles WXSS here)`);
         return true;
     }
-    async function waitHostReady(timeoutMs = 8000) {
+    async function waitHostUp(timeoutMs = 8000) {
         const start = Date.now();
         while (Date.now() - start < timeoutMs) {
             try {
-                const res = await fetch(`http://${host}:${port}/__vmz/ready`);
+                const res = await fetch(`http://${host}:${port}/__vmz/health`);
                 if (res.ok)
                     return;
             }
@@ -162,7 +380,7 @@ export function createDevSession(options) {
             }
             await sleep(50);
         }
-        throw new Error(`serve-host not ready on ${host}:${port}`);
+        throw new Error(`serve-host not up on ${host}:${port}`);
     }
     async function waitHostGone(timeoutMs = 3000) {
         const start = Date.now();
@@ -176,29 +394,93 @@ export function createDevSession(options) {
             }
         }
     }
-    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
+     * 两阶段重建：host `prepare` 写入口 → CLI 侧 `vmz-pack` → host `commit` 发布。
+     * dev 的浏览器交付必须走 pack，否则逐文件模块保留裸包说明符。
+     * pack 失败显式 SSE error 且不回退到未打包入口。`staticOnly`（仅 public
+     * 资产）不改变客户端图，因此不重打包。
      */
-    async function reloadAfterBuild(payload) {
+    async function reloadWithPack(payload, opts = {}) {
         try {
-            await softReload(host, port, payload);
-            return 'soft';
+            await softReload({ phase: 'prepare', payload });
         }
         catch (err) {
+            if (opts.initial) {
+                log.warn(`initial serve-host load failed (${err}) — host stays up`);
+                return 'error';
+            }
             log.warn(`soft reload failed (${err}) — auto-respawning serve-host`);
             await respawnHost('soft-reload-failed');
             return 'respawn';
         }
+        if (!opts.staticOnly) {
+            const startedAt = Date.now();
+            const changedReason = lastPackInputs ? packInputsChangedReason(lastPackInputs, outDir) : 'no pack input snapshot';
+            const missing = changedReason === null && lastPackManifest ? missingPackOutput(lastPackManifest, outDir) : null;
+            if (changedReason === null && !missing && lastPackManifest) {
+                log.info(`dev pack skip (inputs unchanged, ${Date.now() - startedAt}ms)`);
+            }
+            else {
+                if (changedReason)
+                    log.info(`dev pack (inputs changed: ${changedReason})`);
+                if (missing)
+                    log.info(`dev pack (manifest reuse rejected: missing ${missing})`);
+                try {
+                    const { manifest } = packBrowser(outDir, { projectRoot: project });
+                    lastPackManifest = manifest;
+                    lastPackInputs = capturePackInputSnapshot(lastPackManifest, outDir, project);
+                    log.info(`dev pack ok (${manifest.chunkCount} chunks, ${Date.now() - startedAt}ms)`);
+                    if (!lastPackInputs)
+                        log.info('dev pack inputs: snapshot unavailable (unknown input) — next rebuild repacks');
+                }
+                catch (err) {
+                    lastPackManifest = null;
+                    lastPackInputs = null;
+                    const message = err instanceof Error ? err.message : String(err);
+                    log.error(`dev pack failed: ${message}`);
+                    try {
+                        await softReload({
+                            phase: 'abort',
+                            error: { message, stack: err instanceof Error ? err.stack : undefined },
+                        });
+                    }
+                    catch {
+                        /* host may be gone; keep the reported pack error */
+                    }
+                    return 'error';
+                }
+            }
+        }
+        try {
+            await softReload({ phase: 'commit' });
+            return 'soft';
+        }
+        catch (err) {
+            if (opts.initial) {
+                log.warn(`initial serve-host commit failed (${err}) — host stays up`);
+                return 'error';
+            }
+            log.warn(`reload commit failed (${err}) — auto-respawning serve-host`);
+            await respawnHost('commit-failed');
+            return 'respawn';
+        }
+    }
+    async function respawnHost(reason) {
+        log.warn(`respawning serve-host (${reason})…`);
+        killChild(child);
+        child = null;
+        await waitHostGone();
+        child = spawnHost({ project, outDir, host, port });
+        await waitHostUp();
+        const kind = await reloadWithPack({}, { initial: true });
+        if (kind === 'soft')
+            log.info('serve-host respawned — browser SSE will reconnect and reload');
+        else
+            log.warn('serve-host respawned but initial reload failed — fix the error and save');
+    }
+    /** @param {object} payload */
+    async function reloadAfterBuild(payload, opts = {}) {
+        return reloadWithPack(payload, opts);
     }
     let docEnginesPromise = null;
     /** `engines.code` / `engines.markdown` for the document layer (loaded once per session). */
@@ -215,6 +497,33 @@ export function createDevSession(options) {
         if (!existsSync(src)) {
             throw new Error(`vmz dev: missing src/ under ${project}`);
         }
+        // Snapshot watch roots and their fingerprints **before** the initial build.
+        // A save that lands while `vmz dev` boots must still be detected by the first
+        // poll. Taking the baseline after the initial reload absorbs that edit into the
+        // baseline, so the host serves the pre-edit bytes until the next save.
+        const docsRoot = path.join(project, 'documents');
+        const localesRoot = path.join(project, 'locales');
+        const designsRoot = path.join(project, 'designs');
+        const watched = collectDevWatchRoots({ project, outDir });
+        const publicRoot = watched.publicRoot;
+        /** Candidate config files plus their local reachable deps; refreshed after each cycle. */
+        const refreshConfigPaths = () => {
+            const deps = configCandidates
+                .filter((p) => existsSync(p))
+                .flatMap((p) => collectConfigDependencies(p, project));
+            return [...new Set([...configCandidates, ...deps])];
+        };
+        let configPaths = refreshConfigPaths();
+        /** @type {string[]} */
+        const watchRoots = [...watched.roots];
+        /** @type {string[]} */
+        let dependencyRoots = [...watched.dependencyRoots];
+        /** @type {Map<string, Map<string, string>>} */
+        const fingerprints = new Map();
+        for (const root of watchRoots) {
+            fingerprints.set(root, fileFingerprintMap(root));
+        }
+        let configFingerprints = configFingerprintMap(configPaths);
         // Config evaluation + plugin contributions run in a detached build process.
         // Functions/plugin objects never cross the boundary; only the data report does.
         if (configCandidates.some((p) => existsSync(p))) {
@@ -253,27 +562,16 @@ export function createDevSession(options) {
                 throw new Error(`vmz dev: missing ${hostJs}`);
             }
             child = spawnHost({ project, outDir, host, port });
-            await waitHostReady().catch((err) => {
+            await waitHostUp().catch((err) => {
                 log.warn(String(err));
             });
+            const initialKind = await reloadAfterBuild({}, { staticOnly: false }).catch((err) => {
+                log.warn(`initial reload failed: ${err}`);
+                return 'error';
+            });
+            if (initialKind !== 'soft')
+                log.warn('initial serve-host reload failed — fix the error and save');
         }
-        const docsRoot = path.join(project, 'documents');
-        const localesRoot = path.join(project, 'locales');
-        const designsRoot = path.join(project, 'designs');
-        const watched = collectDevWatchRoots({ project, outDir });
-        const publicRoot = watched.publicRoot;
-        /** Candidate config files plus their local reachable deps; refreshed after each cycle. */
-        const refreshConfigPaths = () => {
-            const deps = configCandidates
-                .filter((p) => existsSync(p))
-                .flatMap((p) => collectConfigDependencies(p, project));
-            return [...new Set([...configCandidates, ...deps])];
-        };
-        let configPaths = refreshConfigPaths();
-        /** @type {string[]} */
-        const watchRoots = [...watched.roots];
-        /** @type {string[]} */
-        let dependencyRoots = [...watched.dependencyRoots];
         if (wechatPreview) {
             log.info(`dev → WeChat DevTools (watching ${watchRoots.join(', ')}; keep dist/wechat open)`);
         }
@@ -283,12 +581,6 @@ export function createDevSession(options) {
         if (dependencyRoots.length) {
             log.info(`dev dependency watch roots (${dependencyRoots.length}): ${dependencyRoots.join(', ')}`);
         }
-        /** @type {Map<string, Map<string, string>>} */
-        const fingerprints = new Map();
-        for (const root of watchRoots) {
-            fingerprints.set(root, fileFingerprintMap(root));
-        }
-        let configFingerprints = configFingerprintMap(configPaths);
         const signal = options.signal;
         const onAbort = () => {
             void stop();
@@ -360,8 +652,7 @@ export function createDevSession(options) {
                     break;
                 if (!wechatPreview && child && child.exitCode != null) {
                     log.warn(`serve-host exited (${child.exitCode}) — respawning…`);
-                    child = spawnHost({ project, outDir, host, port });
-                    await waitHostReady().catch(() => { });
+                    await respawnHost('host-exited');
                     continue;
                 }
                 let batch;
@@ -459,7 +750,7 @@ export function createDevSession(options) {
                     commitFingerprints();
                     if (!wechatPreview) {
                         const kind = await maybeReloadAfterBuild({ reloadRequired: true }, null, { force: true, staticOnly: true });
-                        if (kind !== 'skip')
+                        if (kind === 'soft' || kind === 'respawn')
                             log.info('soft reload ok (public assets)');
                     }
                     continue;
@@ -555,7 +846,7 @@ export function createDevSession(options) {
                     }
                     const kind = await maybeReloadAfterBuild(report, hmrPlan, { force: true });
                     commitFingerprints();
-                    if (kind !== 'skip') {
+                    if (kind === 'soft' || kind === 'respawn') {
                         log.info(kind === 'respawn' ? 'reload ok (respawned; deps)' : 'soft reload ok (full page; deps)');
                     }
                     continue;
@@ -592,7 +883,7 @@ export function createDevSession(options) {
                         force: needFullReload,
                     });
                     commitFingerprints();
-                    if (kind !== 'skip') {
+                    if (kind === 'soft' || kind === 'respawn') {
                         log.info(kind === 'respawn'
                             ? 'reload ok (respawned serve-host)'
                             : needFullReload
@@ -627,7 +918,7 @@ export function createDevSession(options) {
                     }
                     const kind = await maybeReloadAfterBuild(report, hmrPlan, { force: true });
                     commitFingerprints();
-                    if (kind !== 'skip') {
+                    if (kind === 'soft' || kind === 'respawn') {
                         log.info(kind === 'respawn' ? 'reload ok (respawned; designs)' : 'soft reload ok (full page; designs)');
                     }
                     continue;
@@ -648,7 +939,7 @@ export function createDevSession(options) {
                     else {
                         const kind = await maybeReloadAfterBuild({ reloadRequired: true, full: true }, null, { force: true });
                         commitFingerprints();
-                        if (kind !== 'skip') {
+                        if (kind === 'soft' || kind === 'respawn') {
                             log.info(kind === 'respawn' ? 'reload ok (respawned; locales)' : 'soft reload ok (full page; locales)');
                         }
                         if (!batch.docsDirty)
@@ -670,7 +961,7 @@ export function createDevSession(options) {
                     else {
                         const kind = await maybeReloadAfterBuild({ reloadRequired: true, full: true }, null, { force: true });
                         commitFingerprints();
-                        if (kind !== 'skip') {
+                        if (kind === 'soft' || kind === 'respawn') {
                             log.info(kind === 'respawn' ? 'reload ok (respawned; docs)' : 'soft reload ok (full page; docs)');
                         }
                     }
@@ -740,23 +1031,24 @@ function defaultSpawnHost(opts) {
     return child;
 }
 /**
+ * Host reload request（两阶段协议：`prepare` / `commit` / `abort`）。
  * @param {string} host
  * @param {number} port
- * @param {object} [payload]
+ * @param {Record<string, unknown>} body
  */
-async function defaultSoftReload(host, port, payload = {}) {
+async function defaultReloadRequest(host, port, body) {
     const url = `http://${host}:${port}/__vmz/reload`;
-    const body = JSON.stringify(payload);
     const res = await fetch(url, {
         method: 'POST',
         headers: { 'content-type': 'application/json' },
-        body,
+        body: JSON.stringify(body),
     });
     if (!res.ok)
         throw new Error(`HTTP ${res.status}`);
     const json = await res.json().catch(() => ({}));
     if (!json?.ok)
         throw new Error(JSON.stringify(json));
+    return json;
 }
 function killChild(child) {
     if (!child || child.killed)

package/dist/document/document-base-css.d.ts

@@ -8,7 +8,7 @@
  * colors inside code blocks come from the Shiki theme and stay identical on
  * every site. Sites do not ship document stylesheets.
  *
- * House rules (规划设计/vmz 05): pure-white base with near-black blocks for
+ * House rules: pure-white base with near-black blocks for
  * rhythm, body text ≥ 16px, small text ≥ 12px at weight ≥ 400, no uppercase
  * letter-spaced micro labels, no 3D / volumetric surfaces.
  */

package/dist/document/document-base-css.js

@@ -8,7 +8,7 @@
  * colors inside code blocks come from the Shiki theme and stay identical on
  * every site. Sites do not ship document stylesheets.
  *
- * House rules (规划设计/vmz 05): pure-white base with near-black blocks for
+ * House rules: pure-white base with near-black blocks for
  * rhythm, body text ≥ 16px, small text ≥ 12px at weight ≥ 400, no uppercase
  * letter-spaced micro labels, no 3D / volumetric surfaces.
  */

package/dist/document/document-designs.js

@@ -2,7 +2,7 @@
  * Document — wire the compiled app stylesheet and the framework-owned document
  * base layer into static document assets.
  *
- * Layering (see 规划设计/vmz 04 文档层):
+ * Layering:
  * - `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`),

package/dist/workspace/cdn-policy.d.ts

@@ -42,6 +42,12 @@ interface LocalStaticHostOpts {
     host?: string;
     port?: number;
 }
+export interface LocalStaticHost {
+    host: string;
+    port: number;
+    baseUrl: string;
+    close: () => Promise<void>;
+}
 export declare function buildCdnPolicyManifest(staticManifest: Record<string, unknown>, opts?: BuildCdnPolicyOpts): CdnPolicyManifest;
 /**
  * Write CDN policy + adapter projections under dist/_vmz.
@@ -165,7 +171,7 @@ export declare function projectCdnAdapter(policy: CdnPolicyManifest, adapterId:
  * @param {{ host?: string, port?: number }} [opts]
  * @returns {Promise<{ host: string, port: number, baseUrl: string, close: () => Promise<void> }>}
  */
-export declare function listenLocalStaticHost(distDir: string, policy: Record<string, unknown>, opts?: LocalStaticHostOpts): Promise<unknown>;
+export declare function listenLocalStaticHost(distDir: string, policy: Record<string, unknown>, opts?: LocalStaticHostOpts): Promise<LocalStaticHost>;
 /**
  * @param {string} distDir
  * @param {Record<string, any>} policy