@vmz/vmz 0.1.13 → 0.1.14

package/dist/locale-cmd.js

@@ -12,6 +12,7 @@ import { checkLocaleRouter } from './locale-router.js';
 import { checkLocaleRuntime } from './locale-runtime.js';
 import { checkLocaleConformance, diffLocaleCatalogs, explainLocaleMessage, extractHardcodedText, pseudoLocalizeCatalog, } from './locale-tooling.js';
 import { log } from './log.js';
+import { emitPrettyJson, generatePrettyJson } from './pretty-json.js';
 function printLocaleHelp() {
     console.log(`vmz locale — /locales application i18n (–)
 
@@ -91,14 +92,7 @@ function cmdLocaleCheck(args) {
     const report = checkLocales({ projectRoot, strict: Boolean(args.strict) });
     const jsonOut = args.json;
     if (jsonOut) {
-        const text = JSON.stringify(report, null, 2);
-        if (typeof jsonOut === 'string') {
-            fs.writeFileSync(jsonOut, `${text}\n`, 'utf8');
-            log.info(`wrote ${jsonOut}`);
-        }
-        else {
-            console.log(text);
-        }
+        emitPrettyJson(jsonOut, report, { logWrote: (p) => log.info(`wrote ${p}`) });
     }
     else {
         for (const d of report.diagnostics) {
@@ -151,7 +145,7 @@ function cmdLocaleRename(args) {
     const report = checkLocales({ projectRoot, checkUnused: false });
     const plan = planLocaleRename(report, fromId, toId);
     if (args.json) {
-        console.log(JSON.stringify(plan, null, 2));
+        emitPrettyJson(args.json, plan);
     }
     else if (plan.status !== 'ready') {
         log.error(plan.error || 'rename failed');
@@ -181,14 +175,7 @@ function cmdLocaleRuntimeCheck(args) {
     });
     const { session: _session, ...jsonReport } = report;
     if (args.json) {
-        const text = JSON.stringify(jsonReport, null, 2);
-        if (typeof args.json === 'string') {
-            fs.writeFileSync(args.json, `${text}\n`, 'utf8');
-            log.info(`wrote ${args.json}`);
-        }
-        else {
-            console.log(text);
-        }
+        emitJson(args, jsonReport);
     }
     else {
         for (const d of report.diagnostics) {
@@ -231,14 +218,7 @@ function cmdLocaleRouterCheck(args) {
         origin: routesFile.origin || 'https://example.test',
     });
     if (args.json) {
-        const text = JSON.stringify(report, null, 2);
-        if (typeof args.json === 'string') {
-            fs.writeFileSync(args.json, `${text}\n`, 'utf8');
-            log.info(`wrote ${args.json}`);
-        }
-        else {
-            console.log(text);
-        }
+        emitJson(args, report);
     }
     else {
         for (const d of report.diagnostics) {
@@ -268,14 +248,7 @@ function cmdLocaleDeliveryCheck(args) {
         planVersion: 'plan.v0',
     });
     if (args.json) {
-        const text = JSON.stringify(report, null, 2);
-        if (typeof args.json === 'string') {
-            fs.writeFileSync(args.json, `${text}\n`, 'utf8');
-            log.info(`wrote ${args.json}`);
-        }
-        else {
-            console.log(text);
-        }
+        emitJson(args, report);
     }
     else {
         for (const d of report.diagnostics) {
@@ -290,14 +263,9 @@ function cmdLocaleDeliveryCheck(args) {
     return report.status === 'ready' ? 0 : 1;
 }
 function emitJson(args, report) {
-    const text = JSON.stringify(report, null, 2);
-    if (typeof args.json === 'string') {
-        fs.writeFileSync(args.json, `${text}\n`, 'utf8');
-        log.info(`wrote ${args.json}`);
-    }
-    else {
-        console.log(text);
-    }
+    emitPrettyJson(args.json, report, {
+        logWrote: (p) => log.info(`wrote ${p}`),
+    });
 }
 function cmdLocaleExplain(args) {
     const messageId = typeof args._[0] === 'string' ? args._[0] : '';
@@ -401,7 +369,7 @@ function cmdLocalePseudo(args) {
         const outDir = (typeof args.out === 'string' && args.out) || path.join(projectRoot, 'dist', 'locales-pseudo');
         fs.mkdirSync(outDir, { recursive: true });
         const outFile = path.join(outDir, `${report.pseudoLocale}.json`);
-        fs.writeFileSync(outFile, `${JSON.stringify(report.catalog, null, 2)}\n`, 'utf8');
+        fs.writeFileSync(outFile, `${generatePrettyJson(report.catalog)}\n`, 'utf8');
         log.info(`locale pseudo: source=${sourceLocale} keys=${Object.keys(report.catalog).length} out=${outFile}`);
     }
     return report.status === 'ready' ? 0 : 1;

package/dist/locale-route-emit.d.ts

@@ -26,7 +26,10 @@ export declare function emitLocaleRouteRealization(projectRoot: any, distDir: an
             defaultLocale: any;
         };
         origin: string;
-        routes: any;
+        routes: {
+            routeId: string;
+            path: string;
+        }[];
         realizations: any[];
         pageMetas: any[];
     };

package/dist/locale-route-emit.js

@@ -7,34 +7,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { checkLocales, localeHasErrors } from './locale-check.js';
 import { buildLocalePageMeta, buildLocaleRouteRealizationTable } from './locale-router.js';
+import { writePrettyJsonFile } from './pretty-json.js';
+import { listPublicPageUnits, unitBrowserPathPattern } from './route-path.js';
 export const LOCALE_ROUTE_REALIZATION_ARTIFACT_SCHEMA = 'vmz.locale.route_realization.v0';
-/**
- * @param {string} chunkId
- */
-function pathPatternFromChunk(chunkId) {
-    const rel = String(chunkId || '').replace(/^pages\//, '');
-    const parts = rel.split('/').filter(Boolean);
-    const segs = [];
-    for (let i = 0; i < parts.length; i++) {
-        const p = parts[i];
-        if (p === 'index' && i === parts.length - 1)
-            continue;
-        segs.push(p);
-    }
-    return segs.length ? `/${segs.join('/')}` : '/';
-}
-/**
- * Layouts are not public RouteNodes for locale realization / SEO.
- * @param {string} chunkId
- */
-function isPublicPageChunk(chunkId) {
-    const id = String(chunkId || '');
-    if (!id.startsWith('pages/'))
-        return false;
-    if (/(^|\/)Layout$/.test(id))
-        return false;
-    return true;
-}
 /**
  * @param {string} projectRoot
  * @param {string} distDir
@@ -59,10 +34,10 @@ export function emitLocaleRouteRealization(projectRoot, distDir, opts = {}) {
         };
     }
     const deployment = JSON.parse(fs.readFileSync(deploymentPath, 'utf8'));
-    const pages = (deployment.units || []).filter((u) => u.kind === 'page' && isPublicPageChunk(String(u.chunkId)));
+    const pages = listPublicPageUnits(deployment);
     const routes = pages.map((u) => ({
         routeId: String(u.chunkId),
-        path: pathPatternFromChunk(String(u.chunkId)),
+        path: unitBrowserPathPattern(u),
     }));
     const localeEntries = report.manifest?.locales || [];
     const locales = localeEntries.map((l) => l.id);
@@ -117,14 +92,14 @@ export function emitLocaleRouteRealization(projectRoot, distDir, opts = {}) {
     const vmzDir = path.join(distDir, '_vmz');
     fs.mkdirSync(vmzDir, { recursive: true });
     const outPath = path.join(vmzDir, 'locale-route-realization.json');
-    fs.writeFileSync(outPath, `${JSON.stringify(artifact, null, 2)}\n`, 'utf8');
+    writePrettyJsonFile(outPath, artifact);
     const manifestOut = path.join(vmzDir, 'locale-manifest.json');
-    fs.writeFileSync(manifestOut, `${JSON.stringify({
+    writePrettyJsonFile(manifestOut, {
         schema: 'vmz.locale.manifest.v0',
         defaultLocale,
         locales: artifact.locales,
         routing: artifact.routing,
-    }, null, 2)}\n`, 'utf8');
+    });
     return {
         ok: true,
         written: ['_vmz/locale-route-realization.json', '_vmz/locale-manifest.json'],

package/dist/locale-router.js

@@ -90,16 +90,34 @@ export function buildLocaleRouteRealizationTable(input) {
                 pathPattern: normalizePath(route.path),
             };
             realizations.push(entry);
-            const prev = pathOwners.get(entry.path);
-            if (prev && prev !== `${route.routeId}@${localeId}`) {
-                diagnostics.push({
-                    code: DIAG_LOCALE_ROUTE_COLLISION,
-                    severity: 'error',
-                    message: `path ${entry.path} claimed by ${prev} and ${route.routeId}@${localeId}`,
-                });
+            // `none` / `domain`: LocaleId is Host preference — many locales share one URL path.
+            // Collision only when *different RouteIds* claim the same path.
+            if (routing.strategy === 'none' || routing.strategy === 'domain') {
+                const prevRoute = pathOwners.get(entry.path);
+                if (prevRoute && prevRoute !== route.routeId) {
+                    diagnostics.push({
+                        code: DIAG_LOCALE_ROUTE_COLLISION,
+                        severity: 'error',
+                        message: `path ${entry.path} claimed by ${prevRoute} and ${route.routeId}`,
+                    });
+                }
+                else {
+                    pathOwners.set(entry.path, route.routeId);
+                }
             }
             else {
-                pathOwners.set(entry.path, `${route.routeId}@${localeId}`);
+                const owner = `${route.routeId}@${localeId}`;
+                const prev = pathOwners.get(entry.path);
+                if (prev && prev !== owner) {
+                    diagnostics.push({
+                        code: DIAG_LOCALE_ROUTE_COLLISION,
+                        severity: 'error',
+                        message: `path ${entry.path} claimed by ${prev} and ${owner}`,
+                    });
+                }
+                else {
+                    pathOwners.set(entry.path, owner);
+                }
             }
         }
     }

package/dist/native-addon.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Load the N-API addon or throw (production printers must not fall back to TS).
+ * @returns {any}
+ */
+export declare function requireNativeAddon(): any;
+/**
+ * @returns {any | null}
+ */
+export declare function tryLoadNativeAddon(): any;

package/dist/native-addon.js

@@ -0,0 +1,84 @@
+// @ts-nocheck
+/**
+ * Load the N-API `.node` addon without importing `index.js`
+ * (avoids cycles with modules re-exported from the package entry).
+ */
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const require = createRequire(import.meta.url);
+/** @type {any} */
+let cached;
+/**
+ * Load the N-API addon or throw (production printers must not fall back to TS).
+ * @returns {any}
+ */
+export function requireNativeAddon() {
+    const native = tryLoadNativeAddon();
+    if (!native) {
+        throw new Error('vmz native addon missing — run `pnpm napi:build` (CodeGenerators live in vmz-generator via N-API)');
+    }
+    return native;
+}
+/**
+ * @returns {any | null}
+ */
+export function tryLoadNativeAddon() {
+    if (cached !== undefined)
+        return cached;
+    try {
+        const envPath = (typeof process.env.VMZ_NATIVE_NODE === 'string' && process.env.VMZ_NATIVE_NODE.trim()) || '';
+        if (envPath) {
+            cached = require(path.resolve(envPath));
+            return cached;
+        }
+        const { platform, arch } = process;
+        let triple = `${platform}-${arch}`;
+        if (platform === 'win32' && arch === 'x64')
+            triple = 'win32-x64-msvc';
+        else if (platform === 'win32' && arch === 'arm64')
+            triple = 'win32-arm64-msvc';
+        else if (platform === 'darwin' && arch === 'arm64')
+            triple = 'darwin-arm64';
+        else if (platform === 'darwin' && arch === 'x64')
+            triple = 'darwin-x64';
+        else if (platform === 'linux' && arch === 'x64')
+            triple = 'linux-x64-gnu';
+        else if (platform === 'linux' && arch === 'arm64')
+            triple = 'linux-arm64-gnu';
+        const short = triple === 'win32-x64-msvc'
+            ? 'win32-x64'
+            : triple === 'win32-arm64-msvc'
+                ? 'win32-arm64'
+                : triple === 'linux-x64-gnu'
+                    ? 'linux-x64'
+                    : triple === 'linux-arm64-gnu'
+                        ? 'linux-arm64'
+                        : triple;
+        const pkgRoot = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+        const name = `@vmz/vmz-${short}`;
+        /** @type {string[]} */
+        const candidates = [];
+        try {
+            const resolved = require.resolve(`${name}/package.json`);
+            const dir = path.dirname(resolved);
+            candidates.push(path.join(dir, `vmz.${triple}.node`), path.join(dir, 'vmz.node'));
+        }
+        catch {
+            /* optional */
+        }
+        candidates.push(path.join(pkgRoot, 'node_modules', name, `vmz.${triple}.node`), path.join(pkgRoot, 'node_modules', name, 'vmz.node'));
+        for (const p of candidates) {
+            if (fs.existsSync(p)) {
+                cached = require(p);
+                return cached;
+            }
+        }
+        cached = null;
+    }
+    catch {
+        cached = null;
+    }
+    return cached;
+}

package/dist/pack.js

@@ -5,10 +5,11 @@
  */
 // @ts-nocheck
 import crypto from 'node:crypto';
-import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { loadDeploymentIr, planBundleInputs } from './bundler-adapter.js';
 import { packClientBareImports } from './pack-client-packages.js';
+import { writePrettyJsonFile } from './pretty-json.js';
 export const PACK_MANIFEST_SCHEMA = 'vmz.pack.manifest.v0';
 /**
  * Ensure dom split companions sit next to vmz-dom.js (barrel imports ./dom-core.js).
@@ -100,7 +101,7 @@ export function packFromDeploymentIr(outDir, opts = {}) {
     const vmzDir = path.join(outDir, '_vmz');
     mkdirSync(vmzDir, { recursive: true });
     const file = path.join(vmzDir, 'pack-manifest.json');
-    writeFileSync(file, `${JSON.stringify(body, null, 2)}\n`, 'utf8');
+    writePrettyJsonFile(file, body);
     return { manifest: body, path: file, clientPackages };
 }
 function stableStringify(value) {

package/dist/pretty-json.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Pretty-print a value through `vmz-generator` (N-API).
+ * @param {unknown} value
+ * @returns {string} Pretty JSON without trailing newline.
+ */
+export declare function generatePrettyJson(value: any): any;
+/**
+ * Write a pretty JSON artifact with a trailing newline.
+ * @param {string} filePath
+ * @param {unknown} value
+ */
+export declare function writePrettyJsonFile(filePath: any, value: any): void;
+/**
+ * CLI `--json` helper: write to a path when `target` is a string, else stdout.
+ * @param {string | boolean | undefined} target
+ * @param {unknown} value
+ * @param {{ logWrote?: (path: string) => void }} [opts]
+ */
+export declare function emitPrettyJson(target: any, value: any, opts?: {}): void;

package/dist/pretty-json.js

@@ -0,0 +1,43 @@
+// @ts-nocheck
+/**
+ * Production JSON artifact printer — always via N-API JsonCodeGenerator.
+ * Do not use `JSON.stringify(x, null, 2)` for on-disk artifacts.
+ */
+import fs from 'node:fs';
+import { requireNativeAddon } from './native-addon.js';
+/**
+ * Pretty-print a value through `vmz-generator` (N-API).
+ * @param {unknown} value
+ * @returns {string} Pretty JSON without trailing newline.
+ */
+export function generatePrettyJson(value) {
+    const native = requireNativeAddon();
+    if (typeof native.generatePrettyJson !== 'function') {
+        throw new Error('vmz native addon missing generatePrettyJson — rebuild with `pnpm napi:build`');
+    }
+    return native.generatePrettyJson(JSON.stringify(value));
+}
+/**
+ * Write a pretty JSON artifact with a trailing newline.
+ * @param {string} filePath
+ * @param {unknown} value
+ */
+export function writePrettyJsonFile(filePath, value) {
+    fs.writeFileSync(filePath, `${generatePrettyJson(value)}\n`, 'utf8');
+}
+/**
+ * CLI `--json` helper: write to a path when `target` is a string, else stdout.
+ * @param {string | boolean | undefined} target
+ * @param {unknown} value
+ * @param {{ logWrote?: (path: string) => void }} [opts]
+ */
+export function emitPrettyJson(target, value, opts = {}) {
+    const text = generatePrettyJson(value);
+    if (typeof target === 'string') {
+        fs.writeFileSync(target, `${text}\n`, 'utf8');
+        if (typeof opts.logWrote === 'function')
+            opts.logWrote(target);
+        return;
+    }
+    console.log(text);
+}

package/dist/production-observability.js

@@ -7,6 +7,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 PRODUCTION_OBSERVABILITY_SCHEMA = 'vmz.production.observability.v0';
 export const PRODUCTION_TRACE_SCHEMA = 'vmz.production.trace.v0';
 /** Facets that production traces must be able to carry (08 A5). */
@@ -457,8 +458,8 @@ export function emitProductionObservability(distDir, overrides = {}, meta = {})
     fs.mkdirSync(vmzDir, { recursive: true });
     const contractPath = path.join(vmzDir, 'production-observability.json');
     const tracePath = path.join(vmzDir, 'production-trace.sample.json');
-    fs.writeFileSync(contractPath, `${JSON.stringify(contract, null, 2)}\n`, 'utf8');
-    fs.writeFileSync(tracePath, `${JSON.stringify(trace, null, 2)}\n`, 'utf8');
+    writePrettyJsonFile(contractPath, contract);
+    writePrettyJsonFile(tracePath, trace);
     return { contract, trace, contractPath, tracePath };
 }
 export function observabilityDigest(contract) {

package/dist/production-test-pack.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 PRODUCTION_SCENARIO_PACK_SCHEMA = 'vmz.production.scenario_pack.v0';
 export const PRODUCTION_CI_PROFILE_SCHEMA = 'vmz.production.ci_profile.v0';
 export const PRODUCTION_TEST_REPORT_SCHEMA = 'vmz.production.test_report.v0';
@@ -431,9 +432,9 @@ export function emitProductionTestArtifacts(root, report, pack, profile) {
     const reportPath = path.join(dir, 'report.json');
     const packPath = path.join(dir, 'scenario-pack.json');
     const profilePath = path.join(dir, 'ci-profile.json');
-    fs.writeFileSync(reportPath, `${JSON.stringify(stamped, null, 2)}\n`, 'utf8');
-    fs.writeFileSync(packPath, `${JSON.stringify(pack, null, 2)}\n`, 'utf8');
-    fs.writeFileSync(profilePath, `${JSON.stringify(profile, null, 2)}\n`, 'utf8');
+    writePrettyJsonFile(reportPath, stamped);
+    writePrettyJsonFile(packPath, pack);
+    writePrettyJsonFile(profilePath, profile);
     return { reportPath, packPath, profilePath, report: stamped };
 }
 /** Assert CI profile forbids JS test-runner disguise. */

package/dist/public-static-assets.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Opaque site-root static files: project `public/**` → deploy root (static / web-static).
+ * Not dependency packaging (no node_modules / @dxo/* scanning).
+ */
+export declare const PUBLIC_STATIC_ASSETS_SCHEMA = "vmz.public_static_assets.v0";
+/**
+ * @param {string} distDir
+ * @param {{ projectRoot?: string, publicDir?: string }} [opts]
+ */
+export declare function emitPublicStaticAssets(distDir: any, opts?: {}): {
+    schema: string;
+    status: string;
+    reason: string;
+    fileCount: number;
+    files: any[];
+    skippedConflicts: any[];
+} | {
+    schema: string;
+    status: string;
+    source: string;
+    fileCount: number;
+    files: any[];
+    skippedConflicts: any[];
+};

package/dist/public-static-assets.js

@@ -0,0 +1,140 @@
+/**
+ * Opaque site-root static files: project `public/**` → deploy root (static / web-static).
+ * Not dependency packaging (no node_modules / @dxo/* scanning).
+ */
+// @ts-nocheck
+import fs from 'node:fs';
+import path from 'node:path';
+import { writePrettyJsonFile } from './pretty-json.js';
+export const PUBLIC_STATIC_ASSETS_SCHEMA = 'vmz.public_static_assets.v0';
+/** Relative paths under dist that VMZ owns; public/ must not clobber. */
+const RESERVED_EXACT = new Set([
+    'entry-client.js',
+    'entry-event.js',
+    'vmz-dom.js',
+    'vmz-runtime.js',
+    'vmz-http.js',
+    'vmz-client-nav.js',
+    'vmz.css',
+    'vmz-designs.css',
+    'vmz-style.css',
+    'vmz-deployment.json',
+    'vmz-routes.json',
+    'vmz-plugin-targets.json',
+    'sitemap.xml',
+    'robots.txt',
+    '404.html',
+]);
+/**
+ * @param {string} distDir
+ * @param {{ projectRoot?: string, publicDir?: string }} [opts]
+ */
+export function emitPublicStaticAssets(distDir, opts = {}) {
+    const absDist = path.resolve(distDir);
+    const projectRoot = opts.projectRoot ? path.resolve(opts.projectRoot) : null;
+    const publicDir = opts.publicDir ? path.resolve(opts.publicDir) : projectRoot ? path.join(projectRoot, 'public') : null;
+    if (!publicDir || !fs.existsSync(publicDir) || !fs.statSync(publicDir).isDirectory()) {
+        const skipped = {
+            schema: PUBLIC_STATIC_ASSETS_SCHEMA,
+            status: 'skipped',
+            reason: publicDir ? 'public/ missing' : 'no projectRoot',
+            fileCount: 0,
+            files: [],
+            skippedConflicts: [],
+        };
+        writeArtifact(absDist, skipped);
+        return skipped;
+    }
+    /** @type {Array<{ path: string, bytes: number }>} */
+    const files = [];
+    /** @type {Array<{ path: string, reason: string }>} */
+    const skippedConflicts = [];
+    walkFiles(publicDir, (absFile) => {
+        const rel = path.relative(publicDir, absFile).replace(/\\/g, '/');
+        if (!rel || rel.startsWith('..'))
+            return;
+        if (shouldSkipReserved(rel)) {
+            skippedConflicts.push({ path: rel, reason: 'reserved-vmz-path' });
+            return;
+        }
+        const dest = path.join(absDist, ...rel.split('/'));
+        if (fs.existsSync(dest) && isReservedExisting(rel, dest, absDist)) {
+            skippedConflicts.push({ path: rel, reason: 'would-clobber-generated' });
+            return;
+        }
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.copyFileSync(absFile, dest);
+        files.push({ path: rel, bytes: fs.statSync(dest).size });
+    });
+    files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+    const artifact = {
+        schema: PUBLIC_STATIC_ASSETS_SCHEMA,
+        status: 'ready',
+        source: 'public/',
+        fileCount: files.length,
+        files,
+        skippedConflicts,
+    };
+    writeArtifact(absDist, artifact);
+    return artifact;
+}
+/**
+ * @param {string} rel
+ */
+function shouldSkipReserved(rel) {
+    if (rel === '_vmz' || rel.startsWith('_vmz/'))
+        return true;
+    if (RESERVED_EXACT.has(rel))
+        return true;
+    if (rel.startsWith('pages/') || rel.startsWith('components/'))
+        return true;
+    if (/\.client\.js$/i.test(rel))
+        return true;
+    if (rel.startsWith('assets/') && /^assets\/[a-f0-9]{64}\./i.test(rel))
+        return true;
+    return false;
+}
+/**
+ * After compile, many generated files already exist; do not let public overwrite them.
+ * Allow overwrite of non-reserved paths (e.g. re-copy same wasm).
+ * @param {string} rel
+ * @param {string} dest
+ * @param {string} absDist
+ */
+function isReservedExisting(rel, dest, absDist) {
+    if (shouldSkipReserved(rel))
+        return true;
+    // Never overwrite generated HTML shells that static-emit will (or did) write.
+    if (/\.html$/i.test(rel) && fs.existsSync(dest)) {
+        const text = fs.readFileSync(dest, 'utf8');
+        if (text.includes('data-vmz-page') || text.includes('entry-client'))
+            return true;
+    }
+    void absDist;
+    return false;
+}
+/**
+ * @param {string} dir
+ * @param {(absFile: string) => void} onFile
+ */
+function walkFiles(dir, onFile) {
+    for (const name of fs.readdirSync(dir)) {
+        if (name === '.' || name === '..')
+            continue;
+        const full = path.join(dir, name);
+        const st = fs.statSync(full);
+        if (st.isDirectory())
+            walkFiles(full, onFile);
+        else if (st.isFile())
+            onFile(full);
+    }
+}
+/**
+ * @param {string} absDist
+ * @param {Record<string, unknown>} artifact
+ */
+function writeArtifact(absDist, artifact) {
+    const vmzDir = path.join(absDist, '_vmz');
+    fs.mkdirSync(vmzDir, { recursive: true });
+    writePrettyJsonFile(path.join(vmzDir, 'public-static-assets.json'), artifact);
+}