@vmz/vmz 0.1.23 → 0.1.25

package/dist/content-addressed-assets.d.ts

@@ -7,6 +7,7 @@
  * so barrels resolve at dist root.
  */
 export declare const CONTENT_ADDRESSED_ASSETS_SCHEMA = "vmz.content_addressed_assets.v0";
+export declare const ASSET_PLAN_SCHEMA = "vmz.asset.plan.v0";
 interface ContentAddressedAssetObject {
     logicalPath: string;
     assetPath: string;

package/dist/content-addressed-assets.js

@@ -13,6 +13,7 @@ import { requireNativeAddon } from './native-addon.js';
 import { canonicalJson, sha256Hex } from './release-pack.js';
 import { writePrettyJsonFile } from './pretty-json.js';
 export const CONTENT_ADDRESSED_ASSETS_SCHEMA = 'vmz.content_addressed_assets.v0';
+export const ASSET_PLAN_SCHEMA = 'vmz.asset.plan.v0';
 /** Immutable delivery candidates (client-facing bytes). */
 const DEFAULT_CANDIDATES = [
     'entry-client.js',
@@ -92,6 +93,14 @@ export function emitContentAddressedAssets(distDir, opts = {}) {
     const objects = [];
     const rewrites = {};
     const ordered = orderCandidates(candidates);
+    const vmzMetaDir = path.join(abs, '_vmz');
+    fs.mkdirSync(vmzMetaDir, { recursive: true });
+    writePrettyJsonFile(path.join(vmzMetaDir, 'asset-plan.json'), {
+        schema: ASSET_PLAN_SCHEMA,
+        layout: 'assets/<sha256>.<ext>',
+        immutable: true,
+        candidates: ordered,
+    });
     for (const rel of ordered) {
         // Aggregators are replaced in later passes; leaf JS must rewrite ./ → ../ so a
         // hashed barrel under assets/ never 404s on second-hop relative re-exports.

package/dist/dev-incremental.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Dev incremental state helpers (0.1.24): HMR plan parsing, reload decisions, static revision.
+ */
+export interface HmrPlanWire {
+    mode?: string;
+    islandOnly?: boolean;
+    island_only?: boolean;
+    rerunLoaders?: string[];
+    rerun_loaders?: string[];
+    affectedChunks?: string[];
+    affected_chunks?: string[];
+    seedChunks?: string[];
+    seed_chunks?: string[];
+}
+export interface BuildReportWire {
+    full?: boolean;
+    islandHmr?: boolean;
+    island_hmr?: boolean;
+    affectedChunks?: string[];
+    affected_chunks?: string[];
+    seedChunks?: string[];
+    seed_chunks?: string[];
+    emitted?: string[];
+    outputRevision?: string;
+    output_revision?: string;
+    writtenOutputs?: string[];
+    written_outputs?: string[];
+    reloadRequired?: boolean;
+    reload_required?: boolean;
+}
+export interface DevReloadPayload {
+    affectedChunks?: string[];
+    seedChunks?: string[];
+    emitted?: string[];
+    full?: boolean;
+    islandHmr?: boolean;
+    rerunLoaders?: string[];
+    staticRevision?: string;
+    skipEntryRewrite?: boolean;
+    outputRevision?: string;
+}
+export declare function parseHmrPlan(raw: string | object | null | undefined): HmrPlanWire | null;
+export declare function hmrRerunLoaders(plan: HmrPlanWire | null | undefined): string[];
+export declare function buildReloadPayload(report: BuildReportWire, hmrPlan: HmrPlanWire | null, opts?: {
+    staticRevision?: string;
+    skipEntryRewrite?: boolean;
+}): DevReloadPayload;
+export declare function shouldSoftReload(report: BuildReportWire, lastOutputRevision: string | null, opts?: {
+    force?: boolean;
+}): boolean;
+export declare function staticRevisionFromArtifact(artifact: {
+    files?: Array<{
+        path: string;
+        bytes?: number;
+    }>;
+    fileCount?: number;
+} | null): string;
+export declare function filterGenerationIgnore(changed: string[], ignore: Set<string>): string[];
+export declare function devPathNormalize(p: string): string;
+export declare function registerWrittenOutputsIgnore(writtenOutputs: string[] | undefined, outDir: string, projectRoot: string, ignore: Set<string>): void;

package/dist/dev-incremental.js

@@ -0,0 +1,86 @@
+/**
+ * Dev incremental state helpers (0.1.24): HMR plan parsing, reload decisions, static revision.
+ */
+import path from 'node:path';
+export function parseHmrPlan(raw) {
+    if (!raw)
+        return null;
+    try {
+        const doc = typeof raw === 'string' ? JSON.parse(raw) : raw;
+        return doc && typeof doc === 'object' ? doc : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function hmrRerunLoaders(plan) {
+    if (!plan)
+        return [];
+    const list = plan.rerunLoaders ?? plan.rerun_loaders ?? [];
+    return Array.isArray(list) ? list.map(String) : [];
+}
+export function buildReloadPayload(report, hmrPlan, opts = {}) {
+    const rerunLoaders = hmrRerunLoaders(hmrPlan);
+    const affectedChunks = report.affectedChunks ?? report.affected_chunks ?? [];
+    const islandHmr = Boolean(report.islandHmr ?? report.island_hmr);
+    const mode = String(hmrPlan?.mode ?? '').toLowerCase();
+    let full = Boolean(report.full);
+    if (mode === 'full')
+        full = true;
+    if (islandHmr && rerunLoaders.length === 0 && affectedChunks.length > 0) {
+        full = true;
+    }
+    return {
+        affectedChunks,
+        seedChunks: report.seedChunks ?? report.seed_chunks ?? [],
+        emitted: report.emitted ?? [],
+        full,
+        islandHmr: islandHmr && !full,
+        rerunLoaders,
+        staticRevision: opts.staticRevision,
+        skipEntryRewrite: opts.skipEntryRewrite,
+        outputRevision: report.outputRevision ?? report.output_revision,
+    };
+}
+export function shouldSoftReload(report, lastOutputRevision, opts = {}) {
+    if (opts.force)
+        return true;
+    const reloadRequired = report.reloadRequired ?? report.reload_required;
+    if (reloadRequired === false)
+        return false;
+    const rev = report.outputRevision ?? report.output_revision ?? '';
+    if (lastOutputRevision && rev && rev === lastOutputRevision)
+        return false;
+    return true;
+}
+export function staticRevisionFromArtifact(artifact) {
+    if (!artifact || artifact.fileCount === 0)
+        return 'empty';
+    const parts = (artifact.files ?? []).map((f) => `${f.path}:${f.bytes ?? 0}`);
+    parts.sort();
+    let h = 0xcbf29ce484222325n;
+    for (const p of parts) {
+        for (const b of Buffer.from(p)) {
+            h = (h * 0x100000001b3n + BigInt(b)) & 0xffffffffffffffffn;
+        }
+    }
+    return h.toString(16);
+}
+export function filterGenerationIgnore(changed, ignore) {
+    if (!ignore.size)
+        return changed;
+    return changed.filter((p) => !ignore.has(devPathNormalize(p)));
+}
+export function devPathNormalize(p) {
+    return String(p).replace(/\\/g, '/');
+}
+export function registerWrittenOutputsIgnore(writtenOutputs, outDir, projectRoot, ignore) {
+    for (const rel of writtenOutputs ?? []) {
+        const abs = path.isAbsolute(rel) ? rel : path.join(outDir, rel);
+        ignore.add(devPathNormalize(abs));
+        const underProject = devPathNormalize(abs);
+        if (underProject.startsWith(devPathNormalize(projectRoot))) {
+            ignore.add(underProject);
+        }
+    }
+}

package/dist/dev-session.js

@@ -16,7 +16,8 @@ import { buildIntegratedDocuments, projectHasDocuments } from './document-integr
 import { createWorkspace, resolveNativePath } from './index.js';
 import { emitLocaleRuntimeModules, localeHasErrors } from './locale-check.js';
 import { log } from './log.js';
-import { coalesceRootBurst, collectDevWatchRoots, classifyWatchRoot, isDependencyPath, mergeDirtySets } from './dev-watch-roots.js';
+import { coalesceRootBurst, collectDevWatchRoots, classifyWatchRoot, isDependencyPath, mergeDirtySets, collectDevConfigPaths, configFingerprintMap, } from './dev-watch-roots.js';
+import { buildReloadPayload, filterGenerationIgnore, parseHmrPlan, registerWrittenOutputsIgnore, shouldSoftReload, staticRevisionFromArtifact, } from './dev-incremental.js';
 import { diffFingerprints, fileFingerprintMap } from './watch-diff.js';
 /** Track serve-host so a failed/killed launcher cannot leave an orphan port. */
 const DEV_HOST_PID = '.vmz-dev-host.pid';
@@ -33,10 +34,57 @@ export function createDevSession(options) {
     const ws = createWs({ root: project, outDir });
     let child = null;
     let stopped = false;
-    function rebuild(changes) {
+    let lastOutputRevision = null;
+    let lastStaticRevision = null;
+    const generationIgnore = new Set();
+    function planAndRebuild(changes) {
         if (changes?.length)
             ws.updateFiles(changes);
-        return ws.build();
+        let hmrPlan = null;
+        try {
+            if (typeof ws.queryHmrPlan === 'function') {
+                hmrPlan = parseHmrPlan(ws.queryHmrPlan());
+            }
+        }
+        catch {
+            hmrPlan = null;
+        }
+        const report = ws.build();
+        return { report, hmrPlan };
+    }
+    function rebuild(changes) {
+        return planAndRebuild(changes).report;
+    }
+    async function emitPublicAndTrack() {
+        const { emitPublicStaticAssets } = await import('./public-static-assets.js');
+        const artifact = emitPublicStaticAssets(outDir, { projectRoot: project });
+        lastStaticRevision = staticRevisionFromArtifact(artifact);
+        return artifact;
+    }
+    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)
+                lastOutputRevision = rev;
+            registerWrittenOutputsIgnore(report.writtenOutputs ?? report.written_outputs, outDir, project, generationIgnore);
+            return 'skip';
+        }
+        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);
+        if (rev)
+            lastOutputRevision = rev;
+        registerWrittenOutputsIgnore(report.writtenOutputs ?? report.written_outputs, outDir, project, generationIgnore);
+        return kind;
     }
     function emitLocales() {
         const localeEmit = emitLocaleRuntimeModules(project, outDir);
@@ -154,16 +202,14 @@ export function createDevSession(options) {
             }
         }
         log.info('initial build (N-API workspace, full)…');
-        const initial = rebuild();
+        const initialPair = planAndRebuild();
+        const initial = initialPair.report;
         if (!printReport(initial, 'build')) {
             throw new Error('vmz dev: initial build failed');
         }
+        lastOutputRevision = initial.outputRevision ?? initial.output_revision ?? null;
         // `vmz build` assemble copies `public/**` → outDir; soft `ws.build()` does not.
-        // Without this, marketing images and other opaque assets 404 under `vmz dev`.
-        {
-            const { emitPublicStaticAssets } = await import('./public-static-assets.js');
-            emitPublicStaticAssets(outDir, { projectRoot: project });
-        }
+        await emitPublicAndTrack();
         // Reclaim orphan serve-host from a previous crashed launcher (same outDir).
         reclaimStaleDevHost(outDir);
         if (projectHasDocuments(project)) {
@@ -191,6 +237,8 @@ export function createDevSession(options) {
         const localesRoot = path.join(project, 'locales');
         const designsRoot = path.join(project, 'designs');
         const watched = collectDevWatchRoots({ project, outDir });
+        const publicRoot = watched.publicRoot;
+        const configPaths = watched.configPaths.length ? watched.configPaths : collectDevConfigPaths(project);
         /** @type {string[]} */
         const watchRoots = [...watched.roots];
         /** @type {string[]} */
@@ -209,6 +257,7 @@ export function createDevSession(options) {
         for (const root of watchRoots) {
             fingerprints.set(root, fileFingerprintMap(root));
         }
+        let configFingerprints = configFingerprintMap(configPaths);
         const signal = options.signal;
         const onAbort = () => {
             void stop();
@@ -218,7 +267,7 @@ export function createDevSession(options) {
          * Scan all watch roots into a batch. Does not update fingerprints.
          */
         function scanBatch() {
-            /** @type {{ srcChanged: string[], srcDeleted: string[], depChanged: string[], depDeleted: string[], designsChanged: string[], designsDeleted: string[], docsDirty: boolean, localesDirty: boolean, designsDirty: boolean }} */
+            /** @type {{ srcChanged: string[], srcDeleted: string[], depChanged: string[], depDeleted: string[], designsChanged: string[], designsDeleted: string[], publicChanged: string[], docsDirty: boolean, localesDirty: boolean, designsDirty: boolean, configDirty: boolean }} */
             const batch = {
                 srcChanged: [],
                 srcDeleted: [],
@@ -226,11 +275,13 @@ export function createDevSession(options) {
                 depDeleted: [],
                 designsChanged: [],
                 designsDeleted: [],
+                publicChanged: [],
                 docsDirty: false,
                 localesDirty: false,
                 designsDirty: false,
+                configDirty: false,
             };
-            const watchCtx = { src, docsRoot, localesRoot, designsRoot, dependencyRoots };
+            const watchCtx = { src, docsRoot, localesRoot, designsRoot, publicRoot, dependencyRoots };
             for (const root of watchRoots) {
                 const prev = fingerprints.get(root) || new Map();
                 const next = fileFingerprintMap(root);
@@ -242,6 +293,9 @@ export function createDevSession(options) {
                     batch.srcChanged.push(...diff.changed);
                     batch.srcDeleted.push(...diff.deleted);
                 }
+                else if (kind === 'public') {
+                    batch.publicChanged.push(...diff.changed);
+                }
                 else if (kind === 'locales') {
                     batch.localesDirty = true;
                 }
@@ -282,16 +336,51 @@ export function createDevSession(options) {
                 let batch;
                 try {
                     batch = scanBatch();
+                    const nextConfigFp = configFingerprintMap(configPaths);
+                    const configDiff = diffFingerprints(configFingerprints, nextConfigFp);
+                    if (configDiff.changed.length || configDiff.deleted.length) {
+                        batch.configDirty = true;
+                    }
                 }
                 catch (err) {
                     log.warn('watch error:', err);
                     continue;
                 }
+                if (generationIgnore.size) {
+                    batch.srcChanged = filterGenerationIgnore(batch.srcChanged, generationIgnore);
+                    batch.srcDeleted = filterGenerationIgnore(batch.srcDeleted, generationIgnore);
+                    generationIgnore.clear();
+                }
                 const srcDirty = batch.srcChanged.length + batch.srcDeleted.length;
                 const depDirty = batch.depChanged.length + batch.depDeleted.length;
                 const designsDirty = batch.designsDirty || batch.designsChanged.length + batch.designsDeleted.length;
-                if (!srcDirty && !depDirty && !batch.docsDirty && !batch.localesDirty && !designsDirty)
+                const publicDirty = batch.publicChanged.length;
+                if (!srcDirty && !depDirty && !batch.docsDirty && !batch.localesDirty && !designsDirty && !publicDirty && !batch.configDirty) {
                     continue;
+                }
+                if (batch.configDirty) {
+                    log.info('vmz.config change detected — respawn required (devControl)');
+                    configFingerprints = configFingerprintMap(configPaths);
+                    commitFingerprints();
+                    await respawnHost('config-changed');
+                    const report = rebuild();
+                    if (printReport(report, 'rebuild')) {
+                        lastOutputRevision = report.outputRevision ?? report.output_revision ?? null;
+                        await emitPublicAndTrack();
+                    }
+                    continue;
+                }
+                if (publicDirty && !srcDirty && !depDirty && !batch.docsDirty && !batch.localesDirty && !designsDirty) {
+                    log.info(`public change detected (${publicDirty} file(s)) — re-emit static assets…`);
+                    await emitPublicAndTrack();
+                    commitFingerprints();
+                    if (!wechatPreview) {
+                        const kind = await maybeReloadAfterBuild({ reloadRequired: true }, null, { force: true, staticOnly: true });
+                        if (kind !== 'skip')
+                            log.info('soft reload ok (public assets)');
+                    }
+                    continue;
+                }
                 // Coalesce multi-file bursts without dropping the initial dirty set.
                 if (srcDirty > 1) {
                     const coalesced = await coalesceRootBurst(src, fingerprints, {
@@ -344,7 +433,6 @@ export function createDevSession(options) {
                     batch.designsChanged = designsMerged.changed;
                     batch.designsDeleted = designsMerged.deleted;
                 }
-                commitFingerprints();
                 if (!batch.srcChanged.length &&
                     !batch.srcDeleted.length &&
                     !batch.depChanged.length &&
@@ -357,11 +445,12 @@ export function createDevSession(options) {
                 // Dependency changes: conservative full rebuild + full reload (v0.1.5).
                 if (batch.depChanged.length || batch.depDeleted.length) {
                     log.info(`dependency change detected (${batch.depChanged.length} update, ${batch.depDeleted.length} delete) — full rebuild…`);
-                    const report = rebuild();
+                    const { report, hmrPlan } = planAndRebuild();
                     if (!printReport(report, 'rebuild')) {
                         log.warn('rebuild failed — keeping previous server');
                         continue;
                     }
+                    await emitPublicAndTrack();
                     // Refresh watch roots in case the graph gained new packages.
                     const refreshed = collectDevWatchRoots({ project, outDir });
                     for (const r of refreshed.roots) {
@@ -381,14 +470,11 @@ export function createDevSession(options) {
                             log.warn('wechat pack failed — keeping previous dist/wechat');
                         continue;
                     }
-                    const kind = await reloadAfterBuild({
-                        affectedChunks: report.affectedChunks ?? [],
-                        seedChunks: report.seedChunks ?? [],
-                        emitted: report.emitted ?? [],
-                        full: true,
-                        islandHmr: false,
-                    });
-                    log.info(kind === 'respawn' ? 'reload ok (respawned; deps)' : 'soft reload ok (full page; deps)');
+                    const kind = await maybeReloadAfterBuild(report, hmrPlan, { force: true });
+                    commitFingerprints();
+                    if (kind !== 'skip') {
+                        log.info(kind === 'respawn' ? 'reload ok (respawned; deps)' : 'soft reload ok (full page; deps)');
+                    }
                     continue;
                 }
                 let needFullReload = batch.docsDirty || batch.designsDirty;
@@ -398,11 +484,12 @@ export function createDevSession(options) {
                         ...batch.srcChanged.map((p) => ({ path: p, kind: /** @type {'update'} */ ('update') })),
                         ...batch.srcDeleted.map((p) => ({ path: p, kind: /** @type {'delete'} */ ('delete') })),
                     ];
-                    const report = rebuild(changes);
+                    const { report, hmrPlan } = planAndRebuild(changes);
                     if (!printReport(report, 'rebuild')) {
                         log.warn('rebuild failed — keeping previous server');
                         continue;
                     }
+                    await emitPublicAndTrack();
                     if (batch.docsDirty || projectHasDocuments(project)) {
                         const docs = await buildIntegratedDocuments({ projectRoot: project, outDir });
                         if (!docs.ok) {
@@ -418,20 +505,19 @@ export function createDevSession(options) {
                         }
                         continue;
                     }
-                    const kind = await reloadAfterBuild({
-                        affectedChunks: report.affectedChunks ?? [],
-                        seedChunks: report.seedChunks ?? [],
-                        emitted: report.emitted ?? [],
-                        full: Boolean(report.full) || needFullReload,
-                        islandHmr: Boolean(report.islandHmr) && !needFullReload,
+                    const kind = await maybeReloadAfterBuild(report, hmrPlan, {
+                        force: 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');
+                    commitFingerprints();
+                    if (kind !== 'skip') {
+                        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');
+                    }
                     continue;
                 }
                 if (batch.designsChanged.length || batch.designsDeleted.length || batch.designsDirty) {
@@ -440,11 +526,12 @@ export function createDevSession(options) {
                         ...batch.designsChanged.map((p) => ({ path: p, kind: /** @type {'update'} */ ('update') })),
                         ...batch.designsDeleted.map((p) => ({ path: p, kind: /** @type {'delete'} */ ('delete') })),
                     ];
-                    const report = rebuild(changes.length ? changes : undefined);
+                    const { report, hmrPlan } = planAndRebuild(changes.length ? changes : undefined);
                     if (!printReport(report, 'rebuild')) {
                         log.warn('designs rebuild failed — keeping previous styles');
                         continue;
                     }
+                    await emitPublicAndTrack();
                     if (batch.docsDirty || projectHasDocuments(project)) {
                         const docs = await buildIntegratedDocuments({ projectRoot: project, outDir });
                         if (!docs.ok)
@@ -455,14 +542,11 @@ export function createDevSession(options) {
                             log.warn('wechat pack failed — keeping previous dist/wechat');
                         continue;
                     }
-                    const kind = await reloadAfterBuild({
-                        affectedChunks: report.affectedChunks ?? [],
-                        seedChunks: report.seedChunks ?? [],
-                        emitted: report.emitted ?? [],
-                        full: true,
-                        islandHmr: false,
-                    });
-                    log.info(kind === 'respawn' ? 'reload ok (respawned; designs)' : 'soft reload ok (full page; designs)');
+                    const kind = await maybeReloadAfterBuild(report, hmrPlan, { force: true });
+                    commitFingerprints();
+                    if (kind !== 'skip') {
+                        log.info(kind === 'respawn' ? 'reload ok (respawned; designs)' : 'soft reload ok (full page; designs)');
+                    }
                     continue;
                 }
                 if (batch.localesDirty) {
@@ -479,8 +563,11 @@ export function createDevSession(options) {
                             continue;
                     }
                     else {
-                        const kind = await reloadAfterBuild({ full: true, islandHmr: false, emitted: [] });
-                        log.info(kind === 'respawn' ? 'reload ok (respawned; locales)' : 'soft reload ok (full page; locales)');
+                        const kind = await maybeReloadAfterBuild({ reloadRequired: true, full: true }, null, { force: true });
+                        commitFingerprints();
+                        if (kind !== 'skip') {
+                            log.info(kind === 'respawn' ? 'reload ok (respawned; locales)' : 'soft reload ok (full page; locales)');
+                        }
                         if (!batch.docsDirty)
                             continue;
                     }
@@ -498,8 +585,11 @@ export function createDevSession(options) {
                         }
                     }
                     else {
-                        const kind = await reloadAfterBuild({ full: true, islandHmr: false, emitted: [] });
-                        log.info(kind === 'respawn' ? 'reload ok (respawned; docs)' : 'soft reload ok (full page; docs)');
+                        const kind = await maybeReloadAfterBuild({ reloadRequired: true, full: true }, null, { force: true });
+                        commitFingerprints();
+                        if (kind !== 'skip') {
+                            log.info(kind === 'respawn' ? 'reload ok (respawned; docs)' : 'soft reload ok (full page; docs)');
+                        }
                     }
                 }
             }

package/dist/dev-watch-roots.d.ts

@@ -1,7 +1,16 @@
 /**
  * Dev watch helpers: coalesce multi-file bursts without dropping dirty set,
  * and derive extra watch roots from the compile graph (deployment unit sources).
+ *
+ * DevInput layers (0.1.24): author · dependency · public · devControl.
+ * Never watch `dist/`, generated indexes, or generation write-set paths.
  */
+/** Author-facing vs generated dev input bucket. */
+export type DevInputKind = 'author' | 'dependency' | 'public' | 'devControl' | 'locales' | 'docs' | 'designs' | 'other';
+/** `vmz.config.*` at project root (devControl). */
+export declare function collectDevConfigPaths(project: string): string[];
+/** Fingerprint map for explicit config files (not directory walks). */
+export declare function configFingerprintMap(configPaths: string[]): Map<string, string>;
 export interface DirtySet {
     changed: string[];
     deleted: string[];
@@ -59,7 +68,11 @@ export declare function collectDevWatchRoots(opts: CollectDevWatchRootsOpts): {
     roots: string[];
     dependencyRoots: string[];
     applicationRoots: string[];
+    publicRoot: string | null;
+    configPaths: string[];
 };
+/** Map watch bucket to DevInput layer. */
+export declare function devInputKindForWatchBucket(bucket: ReturnType<typeof classifyWatchRoot>): DevInputKind;
 /**
  * Classify which watch bucket a root belongs to.
  * @param {string} root
@@ -77,9 +90,10 @@ export interface ClassifyWatchRootCtx {
     docsRoot: string;
     localesRoot: string;
     designsRoot: string;
+    publicRoot?: string | null;
     dependencyRoots: string[];
 }
-export declare function classifyWatchRoot(root: string, ctx: ClassifyWatchRootCtx): 'src' | 'locales' | 'docs' | 'designs' | 'dep' | 'other';
+export declare function classifyWatchRoot(root: string, ctx: ClassifyWatchRootCtx): 'src' | 'locales' | 'docs' | 'designs' | 'dep' | 'public' | 'other';
 /**
  * Classify whether a changed file lives under a dependency watch root (not app src).
  * @param {string} file

package/dist/dev-watch-roots.js

@@ -1,10 +1,33 @@
 /**
  * Dev watch helpers: coalesce multi-file bursts without dropping dirty set,
  * and derive extra watch roots from the compile graph (deployment unit sources).
+ *
+ * DevInput layers (0.1.24): author · dependency · public · devControl.
+ * Never watch `dist/`, generated indexes, or generation write-set paths.
  */
-import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { diffFingerprints, fileFingerprintMap } from './watch-diff.js';
+const CONFIG_BASENAMES = ['vmz.config.ts', 'vmz.config.js', 'vmz.config.mjs', 'vmz.config.cjs'];
+/** `vmz.config.*` at project root (devControl). */
+export function collectDevConfigPaths(project) {
+    const root = path.resolve(project);
+    return CONFIG_BASENAMES.map((name) => path.join(root, name)).filter((p) => existsSync(p));
+}
+/** Fingerprint map for explicit config files (not directory walks). */
+export function configFingerprintMap(configPaths) {
+    const map = new Map();
+    for (const p of configPaths) {
+        try {
+            const st = statSync(p);
+            map.set(p, `${st.mtimeMs}:${st.size}`);
+        }
+        catch {
+            /* ignore */
+        }
+    }
+    return map;
+}
 export function mergeDirtySets(a, b) {
     const changed = new Set(a?.changed || []);
     const deleted = new Set(a?.deleted || []);
@@ -135,10 +158,14 @@ export function localLinkDependencyRoots(project) {
 export function collectDevWatchRoots(opts) {
     const project = path.resolve(opts.project);
     const outDir = path.resolve(opts.outDir);
+    void 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');
+    const publicRootPath = path.join(project, 'public');
+    const publicRoot = existsSync(publicRootPath) && statSync(publicRootPath).isDirectory() ? publicRootPath : null;
+    const configPaths = collectDevConfigPaths(project);
     const applicationRoots = [];
     if (existsSync(src))
         applicationRoots.push(src);
@@ -148,6 +175,8 @@ export function collectDevWatchRoots(opts) {
         applicationRoots.push(localesRoot);
     if (existsSync(designsRoot))
         applicationRoots.push(designsRoot);
+    if (publicRoot)
+        applicationRoots.push(publicRoot);
     const depSet = new Set();
     const depJson = path.join(outDir, 'vmz-deployment.json');
     if (existsSync(depJson)) {
@@ -188,11 +217,29 @@ export function collectDevWatchRoots(opts) {
         if (!roots.includes(r))
             roots.push(r);
     }
-    return { roots, dependencyRoots, applicationRoots };
+    return { roots, dependencyRoots, applicationRoots, publicRoot, configPaths };
+}
+/** Map watch bucket to DevInput layer. */
+export function devInputKindForWatchBucket(bucket) {
+    if (bucket === 'src')
+        return 'author';
+    if (bucket === 'dep')
+        return 'dependency';
+    if (bucket === 'public')
+        return 'public';
+    if (bucket === 'locales')
+        return 'locales';
+    if (bucket === 'docs')
+        return 'docs';
+    if (bucket === 'designs')
+        return 'designs';
+    return 'other';
 }
 export function classifyWatchRoot(root, ctx) {
     if (root === ctx.src)
         return 'src';
+    if (ctx.publicRoot && root === ctx.publicRoot)
+        return 'public';
     if (root === ctx.localesRoot)
         return 'locales';
     if (root === ctx.docsRoot)

package/dist/locale-router.d.ts

@@ -132,7 +132,7 @@ export declare function parseLocaleFromPath(pathname: string, supportedLocales:
 };
 export type { LocaleHrefArtifact } from '@vmz/core/localize-body-links';
 /** Rewrite a same-app href — single implementation in `@vmz/core/localize-body-links`. */
-export { localizeBodyLinks, localizeSameAppHref } from '@vmz/core/localize-body-links';
+export { localizeBodyLinks, localizeSameAppHref, buildLocaleLinkPlan, applyLocaleLinkPlan } from '@vmz/core/localize-body-links';
 /** Plan redirect / negotiation for an incoming URL (omit-prefix aware). */
 export declare function planLocalePathNavigation(input: {
     pathname: string;

package/dist/locale-router.js

@@ -229,7 +229,7 @@ export function parseLocaleFromPath(pathname, supportedLocales) {
     return { localeId: null, restPath: normalizePath(pathname) };
 }
 /** Rewrite a same-app href — single implementation in `@vmz/core/localize-body-links`. */
-export { localizeBodyLinks, localizeSameAppHref } from '@vmz/core/localize-body-links';
+export { localizeBodyLinks, localizeSameAppHref, buildLocaleLinkPlan, applyLocaleLinkPlan } from '@vmz/core/localize-body-links';
 /** Plan redirect / negotiation for an incoming URL (omit-prefix aware). */
 export function planLocalePathNavigation(input) {
     const routing = {

package/dist/static-emit.d.ts

@@ -3,6 +3,7 @@
  * Reuses the same Direct SSR path as serve-host (no second SSG runtime).
  */
 export declare const STATIC_DELIVERY_MANIFEST_SCHEMA = "vmz.static.delivery_manifest.v0";
+export declare const STATIC_EMIT_PLAN_SCHEMA = "vmz.static.emit_plan.v0";
 export type EmitWebStaticOpts = {
     origin?: string;
     applicationId?: string;

package/dist/static-emit.js

@@ -11,13 +11,14 @@ import { resolveRouteLayoutChain } from '@vmz/core/route-layout-chain';
 import { listClientComponentsSync } from '@vmz/core/component-registry';
 import { emitCdnPolicy } from './cdn-policy.js';
 import { emitContentAddressedAssets, hashedAssetHref } from './content-addressed-assets.js';
-import { absoluteUrl, buildLocalePageMeta, localizeBodyLinks } from './locale-router.js';
+import { absoluteUrl, buildLocalePageMeta, buildLocaleLinkPlan, applyLocaleLinkPlan } from './locale-router.js';
 import { requireNativeAddon } from './native-addon.js';
 import { writePrettyJsonFile } from './pretty-json.js';
 import { emitPublicStaticAssets } from './public-static-assets.js';
 import { listPublicPageUnits, parsePathPattern, unitBrowserPathPattern } from './route-path.js';
 import { emitSiteFavicon, readSiteFaviconHeadHtml } from './site-favicon.js';
 export const STATIC_DELIVERY_MANIFEST_SCHEMA = 'vmz.static.delivery_manifest.v0';
+export const STATIC_EMIT_PLAN_SCHEMA = 'vmz.static.emit_plan.v0';
 export async function emitWebStatic(distDir, opts = {}) {
     const origin = String(opts.origin || process.env.VMZ_SITE_ORIGIN || 'https://example.test').replace(/\/$/, '');
     const applicationId = opts.applicationId || path.basename(path.dirname(distDir));
@@ -40,6 +41,8 @@ export async function emitWebStatic(distDir, opts = {}) {
     const cssLogical = readCssEntry(distDir);
     const cssEntry = hashedAssetHref(assets.rewrites, cssLogical) || hashedAssetHref(assets.rewrites, 'vmz.css');
     const moduleScriptSrc = hashedAssetHref(assets.rewrites, 'entry-client.js') || '/entry-client.js';
+    const localeArt = loadLocaleArtifact(distDir);
+    const localeLinkPlan = buildLocaleLinkPlan(localeArt);
     for (const page of pageCatalog) {
         const pattern = page.pathPattern || patternFromSegs(page.segs);
         const routeId = guessRouteId(distDir, page.chunkId);
@@ -104,8 +107,6 @@ export async function emitWebStatic(distDir, opts = {}) {
                 continue;
             bodyHtml = await renderToString(Layout, {}, { slotHtml: bodyHtml });
         }
-        const localeArt = loadLocaleArtifact(distDir);
-        // Locale artifact routeId is chunkId (`pages/about`), not the page class name.
         const localeWrites = expandLocaleStaticGenerations({
             localeArt,
             routeId: page.chunkId,
@@ -118,7 +119,7 @@ export async function emitWebStatic(distDir, opts = {}) {
             const absHtml = path.join(distDir, gen.htmlPath);
             fs.mkdirSync(path.dirname(absHtml), { recursive: true });
             // Each LocaleId HTML must retain locale on same-app Links (realization authority).
-            const localizedBody = gen.localeId && localeArt ? localizeBodyLinks(bodyHtml, gen.localeId, localeArt) : bodyHtml;
+            const localizedBody = gen.localeId && localeLinkPlan.rows.length ? applyLocaleLinkPlan(bodyHtml, gen.localeId, localeLinkPlan) : bodyHtml;
             const html = wrapDocument({
                 bodyHtml: localizedBody,
                 chunkId: page.chunkId,
@@ -227,6 +228,22 @@ export async function emitWebStatic(distDir, opts = {}) {
     const digest = sha256Hex(canonicalJson(manifest));
     manifest.manifestDigest = digest;
     writePrettyJsonFile(path.join(vmzDir, 'static-delivery-manifest.json'), manifest);
+    writePrettyJsonFile(path.join(vmzDir, 'static-emit-plan.json'), {
+        schema: STATIC_EMIT_PLAN_SCHEMA,
+        applicationId,
+        deliveryProfile: 'static',
+        origin,
+        localeLinks: localeLinkPlan,
+        assetPlanPath: '_vmz/asset-plan.json',
+        routes: generations.map((g) => ({
+            routeId: g.routeId,
+            path: g.path,
+            chunkId: g.chunkId,
+            htmlPath: g.htmlPath,
+            classification: g.classification,
+            localeId: g.localeId || null,
+        })),
+    });
     const cdn = emitCdnPolicy(distDir, manifest);
     return {
         manifest,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vmz/vmz",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "type": "module",
   "description": "VMZ Node toolchain — N-API workspace session + CLI (publish name @vmz/vmz)",
   "license": "MIT",
@@ -48,16 +48,16 @@
     }
   },
   "dependencies": {
-    "@vmz/commander": "0.1.23",
-    "@vmz/core": "0.1.23",
-    "@vmz/diagnostic": "0.1.23",
-    "@vmz/plugin": "0.1.23",
-    "@vmz/protocol": "0.1.23",
+    "@vmz/commander": "0.1.25",
+    "@vmz/core": "0.1.25",
+    "@vmz/diagnostic": "0.1.25",
+    "@vmz/plugin": "0.1.25",
+    "@vmz/protocol": "0.1.25",
     "jiti": "^2.6.1"
   },
   "peerDependencies": {
-    "@vmz/plugin-markdown-it": "0.1.23",
-    "@vmz/test": "0.1.23",
+    "@vmz/plugin-markdown-it": "0.1.25",
+    "@vmz/test": "0.1.25",
     "typescript": "^5.8.3"
   },
   "peerDependenciesMeta": {
@@ -92,12 +92,12 @@
     "cli"
   ],
   "optionalDependencies": {
-    "@vmz/vmz-win32-x64": "0.1.23",
-    "@vmz/vmz-win32-arm64": "0.1.23",
-    "@vmz/vmz-darwin-x64": "0.1.23",
-    "@vmz/vmz-darwin-arm64": "0.1.23",
-    "@vmz/vmz-linux-x64": "0.1.23",
-    "@vmz/vmz-linux-arm64": "0.1.23"
+    "@vmz/vmz-win32-x64": "0.1.25",
+    "@vmz/vmz-win32-arm64": "0.1.25",
+    "@vmz/vmz-darwin-x64": "0.1.25",
+    "@vmz/vmz-darwin-arm64": "0.1.25",
+    "@vmz/vmz-linux-x64": "0.1.25",
+    "@vmz/vmz-linux-arm64": "0.1.25"
   },
   "publishConfig": {
     "access": "public"