@vmz/vmz 0.1.0 → 0.1.2

package/dist/build-assemble.js

@@ -2,13 +2,14 @@
  * B5 Assemble dispatch + B6 build-proof (per-build semantic id slots).
  */
 // @ts-nocheck
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync } from 'node:fs';
 import path from 'node:path';
 import { semanticIdsForAssembly, sha256Hex, canonicalJson } from './delivery-profile.js';
 import { emitServerArtifact } from './server-artifact.js';
 import { emitEmbeddedPackaging } from './embedded-packaging.js';
 import { emitSiteDelivery } from './site-delivery.js';
 import { emitWebStatic } from './static-emit.js';
+import { writePrettyJsonFile } from './pretty-json.js';
 export const BUILD_PROOF_SCHEMA = 'vmz.build.proof.v0';
 export const ASSEMBLE_MANIFEST_SCHEMA = 'vmz.assemble.manifest.v0';
 /**
@@ -106,7 +107,7 @@ export async function assembleDelivery(outDir, ctx) {
     const vmzDir = path.join(outDir, '_vmz');
     mkdirSync(vmzDir, { recursive: true });
     const file = path.join(vmzDir, 'assemble-manifest.json');
-    writeFileSync(file, `${JSON.stringify(result, null, 2)}\n`, 'utf8');
+    writePrettyJsonFile(file, result);
     return { manifest: result, path: file };
 }
 /**
@@ -186,6 +187,6 @@ export function emitBuildProof(outDir, ctx) {
     const vmzDir = path.join(outDir, '_vmz');
     mkdirSync(vmzDir, { recursive: true });
     const file = path.join(vmzDir, 'build-proof.json');
-    writeFileSync(file, `${JSON.stringify(body, null, 2)}\n`, 'utf8');
+    writePrettyJsonFile(file, body);
     return { proof: body, path: file };
 }

package/dist/cdn-policy.js

@@ -8,6 +8,7 @@ import fs from 'node:fs';
 import http from 'node:http';
 import path from 'node:path';
 import { assertLocaleCacheKey, localeAwareCacheKey } from './locale-router.js';
+import { writePrettyJsonFile } from './pretty-json.js';
 export const CDN_POLICY_MANIFEST_SCHEMA = 'vmz.cdn.policy_manifest.v0';
 export const CDN_ADAPTER_PROJECTION_SCHEMA = 'vmz.cdn.adapter_projection.v0';
 /** HTML: revalidate. Hashed/static assets: long immutable. */
@@ -27,11 +28,7 @@ export function buildCdnPolicyManifest(staticManifest, opts = {}) {
     const origin = String(staticManifest.origin || '');
     const localeArt = opts.localeArtifact || null;
     const localeRedirects = buildOmitPrefixRedirects(staticManifest, localeArt);
-    const redirects = [
-        { from: '/home', to: '/', status: 301, reason: 'canonical-alias' },
-        ...localeRedirects,
-        ...(opts.redirects || []),
-    ];
+    const redirects = [{ from: '/home', to: '/', status: 301, reason: 'canonical-alias' }, ...localeRedirects, ...(opts.redirects || [])];
     const headers = [
         { match: '**/*.html', headers: { 'cache-control': CACHE_HTML } },
         {
@@ -149,14 +146,14 @@ export function emitCdnPolicy(distDir, staticManifest, opts = {}) {
     const policy = buildCdnPolicyManifest(staticManifest, { ...opts, localeArtifact });
     const vmzDir = path.join(distDir, '_vmz');
     fs.mkdirSync(vmzDir, { recursive: true });
-    fs.writeFileSync(path.join(vmzDir, 'cdn-policy-manifest.json'), `${JSON.stringify(policy, null, 2)}\n`, 'utf8');
+    writePrettyJsonFile(path.join(vmzDir, 'cdn-policy-manifest.json'), policy);
     const local = projectCdnAdapter(policy, 'local-static');
     const netlify = projectCdnAdapter(policy, 'netlify');
     const adaptersDir = path.join(vmzDir, 'adapters');
     fs.mkdirSync(path.join(adaptersDir, 'local-static'), { recursive: true });
     fs.mkdirSync(path.join(adaptersDir, 'netlify'), { recursive: true });
-    fs.writeFileSync(path.join(adaptersDir, 'local-static', 'projection.json'), `${JSON.stringify(local, null, 2)}\n`, 'utf8');
-    fs.writeFileSync(path.join(adaptersDir, 'netlify', 'projection.json'), `${JSON.stringify(netlify, null, 2)}\n`, 'utf8');
+    writePrettyJsonFile(path.join(adaptersDir, 'local-static', 'projection.json'), local);
+    writePrettyJsonFile(path.join(adaptersDir, 'netlify', 'projection.json'), netlify);
     fs.writeFileSync(path.join(adaptersDir, 'netlify', '_headers'), String(netlify.files['_headers'] || ''), 'utf8');
     fs.writeFileSync(path.join(adaptersDir, 'netlify', '_redirects'), String(netlify.files['_redirects'] || ''), 'utf8');
     return { policy, adapters: { 'local-static': local, netlify } };

package/dist/cli.js

@@ -5,7 +5,7 @@
 import { spawn } from 'node:child_process';
 import { copyFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
-import { HOST_PROTOCOL, createWorkspace, getProtocolVersions, resolveCoreRuntimeDist } from './index.js';
+import { HOST_PROTOCOL, createWorkspace, getProtocolVersions, resolveCoreRuntimeDist, resolveNativePath } from './index.js';
 import { createDevSession } from './dev-session.js';
 import { gateGlobalProjectCommand, getInvocationContext, isGlobalAllowedCommand } from './invocation.js';
 import { log } from './log.js';
@@ -106,8 +106,8 @@ Usage:
   vmz check [path]              Check project via Workspace
   vmz build [path] [options]    Build project via Workspace
   vmz serve [path] [options]    Serve dist (optional --build)
-  vmz dev [path] [options]      Long-lived rebuild session (no CLI spawn)
-  vmz format [path] [--check]   Format .vmz via N-API (oxc codegen)
+  vmz dev [path] [options]      Rebuild session; --target mini-program-wechat packs dist/wechat
+  vmz format [path] [--check]   Format .vmz via N-API (oxc formatter + EditorConfig)
   vmz lint [path] [--deny-warnings]  Lint (= check) via N-API
   vmz test [path] [options]     Native test discover / report
   vmz document|docs <cmd>       Project /documents domain 
@@ -124,6 +124,7 @@ Options:
   --out-dir, -o <dir>   Output directory (default: dist)
   --release             Release build (omit serve-host; pack minify slot; proof)
   --profile <name>      Delivery profile (default from config; builtins: web-ssr|web-static|web-client|web-hybrid)
+  --target <id>         Dev preview: browser (default) | mini-program-wechat (pack dist/wechat; WeChat DevTools)
   --origin <url>        Site origin for static-cdn canonical/sitemap
   --host <host>         Listen host (default: 127.0.0.1)
   --port <port>         Listen port (dev: omit = auto from 5173; set = lock)
@@ -373,10 +374,7 @@ async function cmdBuild(args) {
         });
         // Always surface locale diagnostics (warnings included) — missing /locales must not be silent.
         // Dedupe: runtime emit + route realization both report the same missing-manifest warning.
-        const localeDiags = dedupeDiagnostics([
-            ...(localeEmit.diagnostics ?? []),
-            ...(localeRoutes.diagnostics ?? []),
-        ]);
+        const localeDiags = dedupeDiagnostics([...(localeEmit.diagnostics ?? []), ...(localeRoutes.diagnostics ?? [])]);
         log.diagnostics(localeDiags);
         if (!localeEmit.ok || localeHasErrors({ diagnostics: localeEmit.diagnostics })) {
             log.error('locale runtime emit failed');
@@ -404,7 +402,15 @@ async function cmdBuild(args) {
                 profileId: selected.selection.profileId,
                 assembly: selected.selection.assembly,
                 coreDist: resolveCoreRuntimeDist(),
+                projectRoot: project,
             });
+            const lower = pack.manifest?.clientPackageLowering;
+            if (lower?.bareSpecs?.length) {
+                log.info(`pack client packages (${lower.bareSpecs.length} bare → vendor; rewritten=${lower.rewrittenFiles})`);
+            }
+            if (lower?.remainingBareSpecs?.length) {
+                log.warn(`pack client packages: ${lower.remainingBareSpecs.length} bare specifier(s) still unresolved for browser: ${lower.remainingBareSpecs.slice(0, 8).join(', ')}${lower.remainingBareSpecs.length > 8 ? '…' : ''}`);
+            }
             log.info(`pack ok (units=${pack.manifest.unitCount}, digest=${String(pack.manifest.packDigest).slice(0, 12)}…)`);
         }
         catch (err) {
@@ -488,6 +494,7 @@ async function cmdServe(args) {
             VMZ_DIST: outDir,
             VMZ_PORT: String(port),
             VMZ_HOST: host,
+            VMZ_NATIVE_NODE: resolveNativePath(),
         },
         stdio: 'inherit',
     });
@@ -534,6 +541,11 @@ async function cmdDev(args) {
         }
     }
     const pollMs = Number(args['poll-ms'] ?? 300);
+    const targetRaw = typeof args.target === 'string' ? args.target : 'browser';
+    if (targetRaw !== 'browser' && targetRaw !== 'mini-program-wechat') {
+        log.error(`unknown --target ${targetRaw} (browser | mini-program-wechat)`);
+        return 1;
+    }
     const ac = new AbortController();
     const onSig = () => {
         log.info('shutting down…');
@@ -547,6 +559,7 @@ async function cmdDev(args) {
         host,
         port,
         pollMs,
+        target: targetRaw,
         signal: ac.signal,
     });
     try {

package/dist/content-addressed-assets.js

@@ -8,6 +8,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { canonicalJson, sha256Hex } from './release-pack.js';
+import { writePrettyJsonFile } from './pretty-json.js';
 export const CONTENT_ADDRESSED_ASSETS_SCHEMA = 'vmz.content_addressed_assets.v0';
 /** Immutable delivery candidates (client-facing bytes). */
 const DEFAULT_CANDIDATES = [
@@ -85,7 +86,7 @@ export function emitContentAddressedAssets(distDir, opts = {}) {
     const vmzDir = path.join(abs, '_vmz');
     fs.mkdirSync(vmzDir, { recursive: true });
     const outPath = path.join(vmzDir, 'content-addressed-assets.json');
-    fs.writeFileSync(outPath, `${JSON.stringify(manifest, null, 2)}\n`, 'utf8');
+    writePrettyJsonFile(outPath, manifest);
     return { manifest, assetsDir, rewrites, manifestPath: outPath };
 }
 /**

package/dist/delivery-profile.d.ts

@@ -32,6 +32,16 @@ export declare function pickSiteAuthoring(raw: any): {
     artifact: string;
     sources: any;
 };
+/**
+ * `delivery.packaging.wechat` — vendor identity, not WeChat JSON / wx APIs.
+ * @param {unknown} raw
+ * @param {Array<{ code: string, message: string }>} diagnostics
+ */
+export declare function pickDeliveryPackaging(raw: any, diagnostics: any): {
+    wechat?: undefined;
+} | {
+    wechat: {};
+};
 export declare function normalizeDeliveryAuthoring(raw: any): {
     ok: boolean;
     table: {

package/dist/delivery-profile.js

@@ -49,6 +49,67 @@ export function pickSiteAuthoring(raw) {
     }
     return site;
 }
+/**
+ * `delivery.packaging.wechat` — vendor identity, not WeChat JSON / wx APIs.
+ * @param {unknown} raw
+ * @param {Array<{ code: string, message: string }>} diagnostics
+ */
+export function pickDeliveryPackaging(raw, diagnostics) {
+    if (!isPlainObject(raw) || raw.packaging == null)
+        return null;
+    if (!isPlainObject(raw.packaging)) {
+        diagnostics.push({ code: 'delivery.packaging', message: 'delivery.packaging must be an object' });
+        return null;
+    }
+    for (const key of Object.keys(raw.packaging)) {
+        if (key !== 'wechat') {
+            diagnostics.push({
+                code: 'delivery.packaging.vendor',
+                message: `delivery.packaging.${key} is not a known vendor (wechat)`,
+            });
+        }
+    }
+    const wechat = raw.packaging.wechat;
+    if (wechat == null)
+        return {};
+    if (!isPlainObject(wechat)) {
+        diagnostics.push({
+            code: 'delivery.packaging.wechat',
+            message: 'delivery.packaging.wechat must be an object',
+        });
+        return null;
+    }
+    for (const [k, v] of Object.entries(wechat)) {
+        if (typeof v === 'function') {
+            diagnostics.push({
+                code: 'delivery.packaging.executable',
+                message: `delivery.packaging.wechat.${k} must be pure data (no functions)`,
+            });
+            continue;
+        }
+        if (k !== 'appId' && k !== 'projectName' && k !== 'title') {
+            diagnostics.push({
+                code: 'delivery.packaging.wechat.field',
+                message: `delivery.packaging.wechat.${k} is not a known field (appId|projectName|title)`,
+            });
+        }
+        else if (v != null && typeof v !== 'string') {
+            diagnostics.push({
+                code: 'delivery.packaging.wechat.type',
+                message: `delivery.packaging.wechat.${k} must be a string`,
+            });
+        }
+    }
+    const out = {};
+    if (typeof wechat.appId === 'string' && wechat.appId.trim())
+        out.appId = wechat.appId.trim();
+    if (typeof wechat.projectName === 'string' && wechat.projectName.trim()) {
+        out.projectName = wechat.projectName.trim();
+    }
+    if (typeof wechat.title === 'string' && wechat.title.trim())
+        out.title = wechat.title.trim();
+    return { wechat: out };
+}
 function normalizeProfileEntry(entry, id, diagnostics) {
     if (!isPlainObject(entry)) {
         diagnostics.push({ code: 'delivery.profile.invalid', message: `profiles.${id} must be an object` });
@@ -183,6 +244,10 @@ export function normalizeDeliveryAuthoring(raw) {
             },
         };
     }
+    else if (isPlainObject(raw.packaging)) {
+        defaultId = String(raw.default || 'web-ssr').trim() || 'web-ssr';
+        profileInputs = { ...BUILTIN_PROFILES };
+    }
     else {
         return {
             ok: false,
@@ -206,6 +271,9 @@ export function normalizeDeliveryAuthoring(raw) {
             message: `delivery.default '${defaultId}' is not a known profile`,
         });
     }
+    if (diagnostics.length)
+        return { ok: false, diagnostics };
+    const packaging = pickDeliveryPackaging(raw, diagnostics);
     if (diagnostics.length)
         return { ok: false, diagnostics };
     const table = {
@@ -213,6 +281,7 @@ export function normalizeDeliveryAuthoring(raw) {
         default: defaultId,
         profiles,
         sugar,
+        ...(packaging ? { packaging } : {}),
     };
     table.digest = sha256Hex(canonicalJson(table));
     return { ok: true, table };

package/dist/dev-session.d.ts

@@ -3,6 +3,11 @@
  *
  * 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".
  */
 /**
  * @typedef {object} DevSessionOptions
@@ -11,6 +16,7 @@
  * @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]

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,7 +58,6 @@ export function createDevSession(options) {
     }
     function emitLocales() {
         const localeEmit = emitLocaleRuntimeModules(project, outDir);
-        // Always surface locale diagnostics (warnings included) — missing /locales must not be silent.
         log.diagnostics(localeEmit.diagnostics ?? []);
         if (!localeEmit.ok || localeHasErrors({ diagnostics: localeEmit.diagnostics })) {
             log.error('locale runtime emit failed');
@@ -72,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');
@@ -89,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));
         }
@@ -108,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);
@@ -146,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();
@@ -181,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');
@@ -190,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) {
@@ -214,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…');
@@ -231,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)');
                     }
                 }
             }
@@ -288,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'],
     });