@vmz/vmz 0.1.9 → 0.1.11

package/dist/cli.js

@@ -3,9 +3,9 @@
  * Node CLI command implementations .
  */
 import { spawn } from 'node:child_process';
-import { copyFileSync, existsSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { HOST_PROTOCOL, createWorkspace, getProtocolVersions, resolveCoreRuntimeDist, resolveNativePath } from './index.js';
+import { HOST_PROTOCOL, createWorkspace, getProtocolVersions, materializeServeHostRuntime, resolveCoreRuntimeDist, resolveNativePath, } from './index.js';
 import { createDevSession } from './dev-session.js';
 import { gateGlobalProjectCommand, getInvocationContext, isGlobalAllowedCommand } from './invocation.js';
 import { log } from './log.js';
@@ -501,14 +501,12 @@ async function cmdServe(args) {
     });
     const hostJs = path.join(outDir, 'vmz-serve-host.mjs');
     if (!existsSync(hostJs)) {
-        const coreDist = resolveCoreRuntimeDist();
-        const src = coreDist ? path.join(coreDist, 'serve-host.mjs') : null;
-        if (src && existsSync(src)) {
-            copyFileSync(src, hostJs);
+        try {
+            materializeServeHostRuntime(outDir);
             log.info(`materialized ${hostJs} from @vmz/core (release builds omit it)`);
         }
-        else {
-            log.error(`missing ${hostJs} — run \`vmz build\` (without --release) or ensure @vmz/core is installed`);
+        catch (err) {
+            log.error(`missing ${hostJs} — run \`vmz build\` (without --release) or ensure @vmz/core is installed (${err instanceof Error ? err.message : err})`);
             return 1;
         }
     }

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

@@ -1,9 +1,15 @@
 /**
  * A3: content-addressed assets/<hash> layout for immutable CDN objects.
  * Logical paths stay available for serve/dev; static HTML rewrites to hashed URLs.
- * Identical bytes → identical asset path (cross-release / cross-source reuse by digest).
+ * CSS aggregators (vmz.css) rewrite `@import` to hashed sibling paths under assets/.
  */
 export declare const CONTENT_ADDRESSED_ASSETS_SCHEMA = "vmz.content_addressed_assets.v0";
+/**
+ * Rewrite relative `@import "./foo.css"` to hashed paths under assets/.
+ * @param {string} cssText
+ * @param {Record<string, string>} rewrites logical (no leading slash) or `/logical` → `assets/hash.ext`
+ */
+export declare function rewriteCssImports(cssText: any, rewrites: any): any;
 /**
  * Emit `assets/<sha256>.<ext>` copies and rewrite HTML href/src to hashed URLs.
  * @param {string} distDir

package/dist/content-addressed-assets.js

@@ -1,7 +1,7 @@
 /**
  * A3: content-addressed assets/<hash> layout for immutable CDN objects.
  * Logical paths stay available for serve/dev; static HTML rewrites to hashed URLs.
- * Identical bytes → identical asset path (cross-release / cross-source reuse by digest).
+ * CSS aggregators (vmz.css) rewrite `@import` to hashed sibling paths under assets/.
  */
 // @ts-nocheck
 import crypto from 'node:crypto';
@@ -16,11 +16,33 @@ const DEFAULT_CANDIDATES = [
     'entry-event.js',
     'vmz.css',
     'vmz-designs.css',
+    'vmz-style.css',
     'vmz-dom.js',
     'vmz-runtime.js',
     'vmz-http.js',
     'vmz-client-nav.js',
 ];
+/** CSS files that may @import other logical CSS; processed after leaf CSS is hashed. */
+const CSS_AGGREGATORS = new Set(['vmz.css']);
+const CSS_IMPORT_RE = /@import\s*(?:url\()?['"]?(\.\/)?([^'")\s;]+)['"]?\)?/gi;
+/**
+ * Rewrite relative `@import "./foo.css"` to hashed paths under assets/.
+ * @param {string} cssText
+ * @param {Record<string, string>} rewrites logical (no leading slash) or `/logical` → `assets/hash.ext`
+ */
+export function rewriteCssImports(cssText, rewrites) {
+    return cssText.replace(CSS_IMPORT_RE, (match, _dot, target) => {
+        const logical = String(target || '').replace(/^\.\//, '');
+        if (!logical)
+            return match;
+        const hashed = rewrites[logical] || rewrites[`/${logical}`] || rewrites[`assets/${logical}`];
+        if (!hashed)
+            return match;
+        const rel = hashed.startsWith('/') ? hashed.slice(1) : hashed;
+        const sibling = rel.startsWith('assets/') ? `./${path.basename(rel)}` : `./${rel}`;
+        return `@import"${sibling}"`;
+    });
+}
 /**
  * Emit `assets/<sha256>.<ext>` copies and rewrite HTML href/src to hashed URLs.
  * @param {string} distDir
@@ -38,36 +60,24 @@ export function emitContentAddressedAssets(distDir, opts = {}) {
     const objects = [];
     /** @type {Record<string, string>} */
     const rewrites = {};
-    for (const rel of candidates) {
-        const logical = String(rel).replace(/\\/g, '/').replace(/^\//, '');
-        const src = path.join(abs, ...logical.split('/'));
-        if (!fs.existsSync(src) || !fs.statSync(src).isFile())
+    const ordered = orderCandidates(candidates);
+    for (const rel of ordered) {
+        ingestCandidate(abs, rel, rewrites, objects, { transform: null });
+    }
+    // Aggregator CSS (vmz.css) must import hashed leaf files — rewrite then hash.
+    for (const rel of ordered) {
+        if (!CSS_AGGREGATORS.has(rel))
             continue;
-        const buf = fs.readFileSync(src);
-        const digest = sha256Hex(buf);
-        const ext = path.extname(logical) || '';
-        const assetRel = `assets/${digest}${ext}`;
-        const dest = path.join(abs, ...assetRel.split('/'));
-        if (!fs.existsSync(dest)) {
-            fs.mkdirSync(path.dirname(dest), { recursive: true });
-            fs.writeFileSync(dest, buf);
-        }
-        else {
-            // Cross-release reuse: identical digest must not be rewritten.
-            const existing = sha256Hex(fs.readFileSync(dest));
-            if (existing !== digest) {
-                throw new Error(`content-address collision at ${assetRel}`);
-            }
-        }
-        objects.push({
-            logicalPath: logical,
-            assetPath: assetRel,
-            digest,
-            bytes: buf.length,
-            immutable: true,
+        const src = path.join(abs, rel);
+        if (!fs.existsSync(src))
+            continue;
+        const rewritten = rewriteCssImports(fs.readFileSync(src, 'utf8'), rewrites);
+        removeLogicalObject(objects, rel);
+        delete rewrites[`/${rel}`];
+        delete rewrites[rel];
+        ingestCandidate(abs, rel, rewrites, objects, {
+            transform: () => Buffer.from(rewritten, 'utf8'),
         });
-        rewrites[`/${logical}`] = `/${assetRel}`;
-        rewrites[logical] = assetRel;
     }
     objects.sort((a, b) => (a.logicalPath < b.logicalPath ? -1 : a.logicalPath > b.logicalPath ? 1 : 0));
     let rewrittenHtml = 0;
@@ -89,6 +99,74 @@ export function emitContentAddressedAssets(distDir, opts = {}) {
     writePrettyJsonFile(outPath, manifest);
     return { manifest, assetsDir, rewrites, manifestPath: outPath };
 }
+/**
+ * @param {string[]} candidates
+ */
+function orderCandidates(candidates) {
+    const set = new Set(candidates.map((c) => String(c).replace(/\\/g, '/').replace(/^\//, '')));
+    /** @type {string[]} */
+    const out = [];
+    for (const name of DEFAULT_CANDIDATES) {
+        if (set.has(name) && !CSS_AGGREGATORS.has(name))
+            out.push(name);
+    }
+    for (const name of [...set].sort()) {
+        if (!CSS_AGGREGATORS.has(name) && !out.includes(name))
+            out.push(name);
+    }
+    if (set.has('vmz.css'))
+        out.push('vmz.css');
+    return out;
+}
+/**
+ * @param {Array<Record<string, any>>} objects
+ * @param {string} logical
+ */
+function removeLogicalObject(objects, logical) {
+    const idx = objects.findIndex((o) => o.logicalPath === logical);
+    if (idx >= 0)
+        objects.splice(idx, 1);
+}
+/**
+ * @param {string} absDist
+ * @param {string} rel
+ * @param {Record<string, string>} rewrites
+ * @param {Array<Record<string, any>>} objects
+ * @param {{ transform?: ((buf: Buffer) => Buffer) | null }} opts
+ */
+function ingestCandidate(absDist, rel, rewrites, objects, opts) {
+    const logical = String(rel).replace(/\\/g, '/').replace(/^\//, '');
+    const src = path.join(absDist, ...logical.split('/'));
+    if (!fs.existsSync(src) || !fs.statSync(src).isFile())
+        return;
+    let buf = fs.readFileSync(src);
+    if (typeof opts.transform === 'function') {
+        buf = opts.transform(buf);
+    }
+    const digest = sha256Hex(buf);
+    const ext = path.extname(logical) || '';
+    const assetRel = `assets/${digest}${ext}`;
+    const dest = path.join(absDist, ...assetRel.split('/'));
+    if (!fs.existsSync(dest)) {
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.writeFileSync(dest, buf);
+    }
+    else {
+        const existing = sha256Hex(fs.readFileSync(dest));
+        if (existing !== digest) {
+            throw new Error(`content-address collision at ${assetRel}`);
+        }
+    }
+    objects.push({
+        logicalPath: logical,
+        assetPath: assetRel,
+        digest,
+        bytes: buf.length,
+        immutable: true,
+    });
+    rewrites[`/${logical}`] = `/${assetRel}`;
+    rewrites[logical] = assetRel;
+}
 /**
  * Resolve an immutable object by digest under dist/assets (cross-source reuse).
  * @param {string} distDir
@@ -124,7 +202,6 @@ export function assertSharedAssetPath(distDir, a, b, ext = '.js') {
     const rel = `assets/${da}${ext}`;
     const dest = path.join(distDir, ...rel.split('/'));
     fs.writeFileSync(dest, typeof a === 'string' ? Buffer.from(a) : a);
-    // Second write of identical bytes must be reuse, not fork.
     fs.writeFileSync(dest, typeof b === 'string' ? Buffer.from(b) : b);
     const again = resolveAssetByDigest(distDir, da, ext);
     if (!again || again.assetPath !== rel) {
@@ -139,7 +216,6 @@ function collectCandidates(distDir) {
         if (fs.existsSync(path.join(distDir, name)))
             out.push(name);
     }
-    // Include top-level *.client.js and pages/**/*.client.js referenced by resume.
     walk(distDir, distDir, (rel) => {
         if (/\.client\.js$/i.test(rel))
             out.push(rel);
@@ -173,7 +249,6 @@ function rewriteHtmlReferences(distDir, rewrites) {
         let text = fs.readFileSync(file, 'utf8');
         let next = text;
         for (const [from, to] of pairs) {
-            // href="/x" src="/x" and unquoted variants in attributes
             next = next.split(from).join(to);
         }
         if (next !== text) {

package/dist/document-build.js

@@ -8,6 +8,7 @@ import { checkDocuments, manifestHasErrors } from './document-check.js';
 import { resolveDocumentDesignsCss } from './document-designs.js';
 import { enrichDocumentContent, pageHtmlRel } from './document-enrich.js';
 import { enrichDocumentEvidence } from './document-evidence.js';
+import { docsRouteNone, loadLocaleCommonMessages, loadLocalesRouting, localeNonePickerScript, readSiteGithubUrl, renderHostChromeTemplate, } from './document-host-chrome.js';
 import { artifactHrefFromHtml, buildDocumentIslands, buildDocumentSearch, collectFenceBodies, renderIslandShellsHtml, } from './document-interactive.js';
 import { resolveMarkdownEngine } from './document-markdown.js';
 import { DOCUMENT_VIEW_SCHEMA } from './document-schema.js';
@@ -22,10 +23,12 @@ export async function buildDocuments(opts) {
     const outDir = path.resolve(opts.outDir || path.join(projectRoot, 'dist', 'documents'));
     const strict = Boolean(opts.strict);
     const manifest = checkDocuments({ projectRoot, strict });
+    const routing = loadLocalesRouting(projectRoot) || { strategy: 'prefix' };
     const engine = await resolveMarkdownEngine({ engines: opts.engines, projectRoot });
     const enriched = enrichDocumentContent(manifest, {
         analyzeMarkdown: engine.analyzeMarkdown,
         projectRoot,
+        routing,
     });
     manifest.diagnostics = enriched.diagnostics;
     const evidence = await enrichDocumentEvidence(manifest, {
@@ -60,8 +63,8 @@ export async function buildDocuments(opts) {
     });
     manifest.search = search;
     manifest.islands = islands;
-    const hostChrome = resolveHostSiteChrome(projectRoot);
-    const useHostShell = Boolean(hostChrome) && (manifest.mounts || []).some((m) => m.mode === 'integrated');
+    const hostChromeRaw = resolveHostSiteChromeRaw(projectRoot);
+    const useHostShell = Boolean(hostChromeRaw) && (manifest.mounts || []).some((m) => m.mode === 'integrated');
     fs.mkdirSync(outDir, { recursive: true });
     const designs = resolveDocumentDesignsCss(projectRoot);
     /** @type {string | null} */
@@ -127,7 +130,12 @@ export async function buildDocuments(opts) {
             htmlRel,
             searchShellHtml: shells.searchHtml,
             playgroundShellHtml: shells.playgroundHtml,
-            hostChrome: useHostShell ? hostChrome : null,
+            hostChrome: useHostShell
+                ? renderHostChromeForLocale(projectRoot, page.identity.locale, routing, enriched.routeBase, hostChromeRaw)
+                : null,
+            routing,
+            routeBase: enriched.routeBase,
+            pageKey: page.identity.pageKey,
         });
         fs.writeFileSync(htmlAbs, html, 'utf8');
         written.push({ route: info.route, htmlPath: htmlRel, viewPath: viewRel });
@@ -159,7 +167,7 @@ export async function buildDocuments(opts) {
  * No-JS readable static HTML: nav + main landmarks, Island shells without scripts.
  * Integrated mounts reuse host SiteHeader/SiteFooter templates when present.
  */
-function renderStaticHtml({ title, locale, route, nav, bodyHtml, headings, designsHref, htmlRel, searchShellHtml = '', playgroundShellHtml = '', hostChrome = null, }) {
+function renderStaticHtml({ title, locale, route, nav, bodyHtml, headings, designsHref, htmlRel, searchShellHtml = '', playgroundShellHtml = '', hostChrome = null, routing = { strategy: 'prefix' }, routeBase = '/docs', pageKey = 'index', }) {
     const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
     const depth = htmlRel.split('/').length - 1;
     const prefix = depth > 0 ? '../'.repeat(depth) : './';
@@ -174,7 +182,7 @@ function renderStaticHtml({ title, locale, route, nav, bodyHtml, headings, desig
         cssHrefs.push(hostChrome ? `/${designsHref}` : prefix + designsHref);
     const navItems = nav
         .map((n) => {
-        const href = relativeHref(htmlRel, n.href, route);
+        const href = routing.strategy === 'none' || routing.strategy === 'domain' ? n.href : relativeHref(htmlRel, n.href, route);
         const current = n.href === route ? ' aria-current="page"' : '';
         return `      <li><a href="${esc(href)}"${current}>${esc(n.title)}</a></li>`;
     })
@@ -210,6 +218,7 @@ ${playgroundShellHtml}
   </div>
 ${hostChrome.footer}
   </div>
+${routing.strategy === 'none' && hostChrome ? localeNonePickerScript() : ''}
 `;
     }
     else {
@@ -239,7 +248,7 @@ ${playgroundShellHtml}
  * @param {string} projectRoot
  * @returns {{ header: string, footer: string } | null}
  */
-function resolveHostSiteChrome(projectRoot) {
+function resolveHostSiteChromeRaw(projectRoot) {
     const headerPath = path.join(projectRoot, 'src', 'components', 'SiteHeader.vmz');
     const footerPath = path.join(projectRoot, 'src', 'components', 'SiteFooter.vmz');
     if (!fs.existsSync(headerPath) || !fs.existsSync(footerPath))
@@ -250,6 +259,28 @@ function resolveHostSiteChrome(projectRoot) {
         return null;
     return { header, footer };
 }
+/**
+ * @param {string} projectRoot
+ * @param {string} localeId
+ * @param {{ strategy?: string }} routing
+ * @param {string} routeBase
+ * @param {{ header: string, footer: string }} raw
+ */
+function renderHostChromeForLocale(projectRoot, localeId, routing, routeBase, raw) {
+    const messages = loadLocaleCommonMessages(projectRoot, localeId);
+    const githubUrl = readSiteGithubUrl(projectRoot);
+    const docsRootHref = routing.strategy === 'none' || routing.strategy === 'domain'
+        ? `${routeBase.replace(/\/$/, '')}/`
+        : `${routeBase.replace(/\/$/, '')}/${localeId}/`;
+    const guideHref = routing.strategy === 'none' || routing.strategy === 'domain'
+        ? docsRouteNone(routeBase, 'guide/getting-started')
+        : `${docsRootHref}guide/getting-started`;
+    const opts = { docsRootHref, guideHref, githubUrl, routing };
+    return {
+        header: renderHostChromeTemplate(raw.header, localeId, messages, opts),
+        footer: renderHostChromeTemplate(raw.footer, localeId, messages, opts),
+    };
+}
 /** @param {string} filePath */
 function extractVmzTemplateHtml(filePath) {
     const src = fs.readFileSync(filePath, 'utf8');

package/dist/document-enrich.d.ts

@@ -2,8 +2,9 @@
  * @param {string} routeBase e.g. /docs
  * @param {string} locale
  * @param {string} pageKey
+ * @param {{ strategy?: string }} [routing]
  */
-export declare function pageRoute(routeBase: any, locale: any, pageKey: any): string;
+export declare function pageRoute(routeBase: any, locale: any, pageKey: any, routing?: {}): string;
 /**
  * Static file path relative to out dir (posix).
  * @param {string} routeBase

package/dist/document-enrich.js

@@ -9,10 +9,16 @@ import { DIAG } from './document-schema.js';
  * @param {string} routeBase e.g. /docs
  * @param {string} locale
  * @param {string} pageKey
+ * @param {{ strategy?: string }} [routing]
  */
-export function pageRoute(routeBase, locale, pageKey) {
+export function pageRoute(routeBase, locale, pageKey, routing = {}) {
     const base = String(routeBase || '/').replace(/\/$/, '') || '';
     const key = pageKey === 'index' ? '' : pageKey.replace(/\\/g, '/');
+    const strategy = routing.strategy || 'prefix';
+    if (strategy === 'none' || strategy === 'domain') {
+        const parts = [base.replace(/^\//, ''), key].filter((p) => p !== '');
+        return '/' + (parts.length ? parts.join('/') : '');
+    }
     const parts = [base.replace(/^\//, ''), locale, key].filter((p) => p !== '');
     return '/' + parts.join('/');
 }
@@ -35,6 +41,7 @@ export function pageHtmlRel(routeBase, locale, pageKey) {
  */
 export function enrichDocumentContent(manifest, ctx) {
     const routeBase = manifest.mounts?.[0]?.routeBase || '/docs';
+    const routing = ctx.routing || { strategy: 'prefix' };
     /** @type {Map<string, { html: string, headings: any[], links: any[], title: string, route: string, anchors: string[] }>} */
     const byId = new Map();
     /** @type {import('./document-schema.js').DocumentDiagnostic[]} */
@@ -45,7 +52,7 @@ export function enrichDocumentContent(manifest, ctx) {
         const abs = path.isAbsolute(page.sourcePath) ? page.sourcePath : path.join(manifest.root, page.sourcePath);
         const source = fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : '';
         const analyzed = ctx.analyzeMarkdown(source);
-        const route = pageRoute(routeBase, page.identity.locale, page.identity.pageKey);
+        const route = pageRoute(routeBase, page.identity.locale, page.identity.pageKey, routing);
         const anchors = analyzed.headings.map((h) => h.id);
         const title = analyzed.headings.find((h) => h.level === 1)?.text || analyzed.headings[0]?.text || page.identity.pageKey;
         // Duplicate anchors on page
@@ -61,7 +68,11 @@ export function enrichDocumentContent(manifest, ctx) {
             }
             seen.add(id);
         }
-        if (routeOwners.has(route)) {
+        const owner = `${page.identity.locale}:${page.identity.pageKey}`;
+        if (routing.strategy === 'none' || routing.strategy === 'domain') {
+            routeOwners.set(route, owner);
+        }
+        else if (routeOwners.has(route)) {
             diagnostics.push({
                 code: DIAG.ROUTE_DUPLICATE,
                 severity: 'error',
@@ -70,7 +81,7 @@ export function enrichDocumentContent(manifest, ctx) {
             });
         }
         else {
-            routeOwners.set(route, `${page.identity.locale}:${page.identity.pageKey}`);
+            routeOwners.set(route, owner);
         }
         page.route = route;
         page.anchors = anchors;

package/dist/document-host-chrome.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @param {string} projectRoot
+ * @returns {{ strategy?: string, defaultLocale?: string } | null}
+ */
+export declare function loadLocalesRouting(projectRoot: any): any;
+/**
+ * @param {string} projectRoot
+ * @param {string} localeId
+ */
+export declare function loadLocaleCommonMessages(projectRoot: any, localeId: any): any;
+/**
+ * @param {string} projectRoot
+ */
+export declare function readSiteGithubUrl(projectRoot: any): string;
+/**
+ * @param {string} template
+ * @param {string} localeId
+ * @param {Record<string, string>} messages
+ * @param {{ docsRootHref: string, guideHref: string, githubUrl: string, routing?: { strategy?: string } }} opts
+ */
+export declare function renderHostChromeTemplate(template: any, localeId: any, messages: any, opts: any): any;
+/** Inline locale preference picker for strategy `none` (Host state, not URL). */
+export declare function localeNonePickerScript(): string;
+/**
+ * @param {string} routeBase
+ * @param {string} pageKey
+ */
+export declare function docsRouteNone(routeBase: any, pageKey: any): string;

package/dist/document-host-chrome.js

@@ -0,0 +1,128 @@
+// @ts-nocheck
+/**
+ * Integrated DocumentMount — lower host SiteHeader/SiteFooter .vmz templates to
+ * static HTML with locale-resolved copy (LocaleId is Host preference, not URL).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * @param {string} projectRoot
+ * @returns {{ strategy?: string, defaultLocale?: string } | null}
+ */
+export function loadLocalesRouting(projectRoot) {
+    const p = path.join(projectRoot, 'locales', 'locales.json5');
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        const raw = fs.readFileSync(p, 'utf8');
+        let s = raw.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
+        const m = s.match(/routing\s*:\s*\{([\s\S]*?)\}/);
+        if (!m)
+            return null;
+        let block = `{${m[1]}}`;
+        block = block.replace(/([,{]\s*)([A-Za-z_][A-Za-z0-9_]*)\s*:/g, '$1"$2":');
+        block = block.replace(/'([^'\\]*(?:\\.[^'\\]*)*)'/g, (_, inner) => JSON.stringify(inner));
+        block = block.replace(/,\s*([}\]])/g, '$1');
+        return JSON.parse(block);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * @param {string} projectRoot
+ * @param {string} localeId
+ */
+export function loadLocaleCommonMessages(projectRoot, localeId) {
+    const p = path.join(projectRoot, 'locales', localeId, 'common.json5');
+    if (!fs.existsSync(p))
+        return {};
+    try {
+        let s = fs.readFileSync(p, 'utf8');
+        s = s.replace(/\/\*[\s\S]*?\*\//g, '').replace(/^\s*\/\/.*$/gm, '');
+        s = s.replace(/([,{]\s*)([A-Za-z_][A-Za-z0-9_]*)\s*:/g, '$1"$2":');
+        s = s.replace(/'([^'\\]*(?:\\.[^'\\]*)*)'/g, (_, inner) => JSON.stringify(inner));
+        s = s.replace(/,\s*([}\]])/g, '$1');
+        return JSON.parse(s);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * @param {string} projectRoot
+ */
+export function readSiteGithubUrl(projectRoot) {
+    const p = path.join(projectRoot, 'src', 'lib', 'site.ts');
+    if (!fs.existsSync(p))
+        return 'https://github.com/voml/iris-orm';
+    const m = fs.readFileSync(p, 'utf8').match(/githubUrl\s*=\s*["']([^"']+)["']/);
+    return m?.[1] || 'https://github.com/voml/iris-orm';
+}
+/**
+ * @param {string} template
+ * @param {string} localeId
+ * @param {Record<string, string>} messages
+ * @param {{ docsRootHref: string, guideHref: string, githubUrl: string, routing?: { strategy?: string } }} opts
+ */
+export function renderHostChromeTemplate(template, localeId, messages, opts) {
+    const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+    const bindings = {
+        brandLabel: messages.brand || 'Iris',
+        brandFullLabel: `${messages.brand || 'Iris'} ORM`,
+        navHomeLabel: messages.navHome || 'Home',
+        navDocsLabel: messages.navDocs || 'Docs',
+        navPlaygroundLabel: messages.navPlayground || 'Playground',
+        navGithubLabel: messages.navGithub || 'GitHub',
+        selectLanguageLabel: messages.selectLanguage || 'Language',
+        langZhLabel: messages.langZh || '中文',
+        langEnLabel: messages.langEn || 'English',
+        footerTagLabel: messages.footerTag || messages.brand || 'Iris',
+        footerScopeLabel: messages.footerScopeNote || '',
+        footerCopyrightLabel: messages.footerCopyright || '',
+        footerGuideLabel: messages.footerGuide || messages.ctaInstall || 'Getting started',
+        footerColProductLabel: messages.footerColProduct || 'Product',
+        footerColProjectLabel: messages.footerColProject || 'Project',
+        ctaInstallLabel: messages.ctaInstall || messages.ctaDocs || 'Docs',
+        docsRootHref: opts.docsRootHref,
+        guideHref: opts.guideHref,
+        githubUrl: opts.githubUrl,
+    };
+    let html = template;
+    html = html.replace(/data-home=\{home \? 'true' : 'false'\}/g, 'data-home="false"');
+    html = html.replace(/href=\{docsRootHref\}/g, `href="${esc(bindings.docsRootHref)}"`);
+    html = html.replace(/href=\{guideHref\}/g, `href="${esc(bindings.guideHref)}"`);
+    html = html.replace(/href=\{githubUrl\}/g, `href="${esc(bindings.githubUrl)}"`);
+    for (const [key, val] of Object.entries(bindings)) {
+        html = html.replace(new RegExp(`\\{${key}\\}`, 'g'), esc(String(val)));
+    }
+    html = html.replace(/<Link(\s)/g, '<a class="vmz-ui-link"$1');
+    html = html.replace(/<\/Link>/g, '</a>');
+    html = html.replace(/<Icon[^>]*\/>/g, '');
+    html = html.replace(/<div class="locale-switch"[\s\S]*?<\/div>/g, () => {
+        const zh = `<button type="button" class="locale-switch__btn${localeId === 'zh-hans' ? ' is-active' : ''}" data-vmz-locale-pick="zh-hans"${localeId === 'zh-hans' ? ' aria-current="true"' : ''}>${esc(bindings.langZhLabel)}</button>`;
+        const en = `<button type="button" class="locale-switch__btn${localeId === 'en-us' ? ' is-active' : ''}" data-vmz-locale-pick="en-us"${localeId === 'en-us' ? ' aria-current="true"' : ''}>${esc(bindings.langEnLabel)}</button>`;
+        return `<div class="locale-switch" role="group" aria-label="${esc(bindings.selectLanguageLabel)}">${zh}${en}</div>`;
+    });
+    html = html.replace(/<Button[\s\S]*?onClick=\{\(\) => this\.switchLocale\('zh-hans'\)\}[\s\S]*?>\s*[\s\S]*?<\/Button>/g, `<button type="button" class="locale-switch__btn${localeId === 'zh-hans' ? ' is-active' : ''}" data-vmz-locale-pick="zh-hans"${localeId === 'zh-hans' ? ' aria-current="true"' : ''}>${esc(bindings.langZhLabel)}</button>`);
+    html = html.replace(/<Button[\s\S]*?onClick=\{\(\) => this\.switchLocale\('en-us'\)\}[\s\S]*?>\s*[\s\S]*?<\/Button>/g, `<button type="button" class="locale-switch__btn${localeId === 'en-us' ? ' is-active' : ''}" data-vmz-locale-pick="en-us"${localeId === 'en-us' ? ' aria-current="true"' : ''}>${esc(bindings.langEnLabel)}</button>`);
+    html = html.replace(/<Button[\s\S]*?<\/Button>/g, '');
+    html = html.replace(/aria-current=\{localeId === '[^']+' \? 'true' : null\}/g, '');
+    html = html.replace(/aria-label=\{selectLanguageLabel\}/g, `aria-label="${esc(bindings.selectLanguageLabel)}"`);
+    html = html.replace(/label=\{[^}]+\}/g, '');
+    return html;
+}
+/** Inline locale preference picker for strategy `none` (Host state, not URL). */
+export function localeNonePickerScript() {
+    return `<script>(function(){try{document.querySelectorAll("[data-vmz-locale-pick]").forEach(function(btn){btn.addEventListener("click",function(){var id=btn.getAttribute("data-vmz-locale-pick");if(!id)return;try{localStorage.setItem("vmz.locale",id);}catch(e){}try{document.cookie="vmz.locale="+encodeURIComponent(id)+"; path=/; max-age=31536000; SameSite=Lax";}catch(e){}location.reload();});});}catch(e){}})();</script>`;
+}
+/**
+ * @param {string} routeBase
+ * @param {string} pageKey
+ */
+export function docsRouteNone(routeBase, pageKey) {
+    const base = String(routeBase || '/').replace(/\/$/, '') || '';
+    const key = pageKey === 'index' ? '' : pageKey.replace(/\\/g, '/');
+    const parts = [base.replace(/^\//, ''), key].filter((p) => p !== '');
+    return '/' + (parts.length ? parts.join('/') : '');
+}

package/dist/document-integrate.js

@@ -7,6 +7,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { buildDocuments } from './document-build.js';
 import { resolveDocumentsRoot } from './document-check.js';
+import { loadLocalesRouting } from './document-host-chrome.js';
+import { pageHtmlRel } from './document-enrich.js';
 import { log } from './log.js';
 import { requireNativeAddon } from './native-addon.js';
 /**
@@ -40,7 +42,7 @@ export async function buildIntegratedDocuments(opts) {
             }
             return { ok: false, error: 'document diagnostics', pages: 0 };
         }
-        writeMountRootRedirects(result.manifest, outDir);
+        writeMountRootRedirects(result.manifest, outDir, projectRoot);
         log.info(`document mount: pages=${result.pages.length} → ${path.relative(process.cwd(), outDir) || '.'}`);
         return { ok: true, pages: result.pages.length };
     }
@@ -51,22 +53,34 @@ export async function buildIntegratedDocuments(opts) {
     }
 }
 /**
- * Emit `{routeBase}/index.html` → defaultLocale landing (for /d/ and /docs/).
+ * Emit `{routeBase}/index.html` for integrated mounts.
+ * `routing.strategy: none` → copy default-locale docs index (LocaleId is Host state).
+ * prefix strategy → redirect HTML to `{routeBase}/{defaultLocale}/`.
  * @param {import('./document-schema.js').DocumentManifest} manifest
  * @param {string} outDir
+ * @param {string} projectRoot
  */
-function writeMountRootRedirects(manifest, outDir) {
+function writeMountRootRedirects(manifest, outDir, projectRoot) {
     const defaultLocale = manifest.defaultLocale || manifest.locales?.[0];
     if (!defaultLocale)
         return;
+    const routing = loadLocalesRouting(projectRoot) || { strategy: 'prefix' };
     for (const mount of manifest.mounts || []) {
         if (!mount?.routeBase || mount.routeBase === '/')
             continue;
         const base = String(mount.routeBase).replace(/\/$/, '');
-        const target = `${base}/${defaultLocale}/`;
         const relDir = base.replace(/^\//, '');
         const abs = path.join(outDir, relDir, 'index.html');
         fs.mkdirSync(path.dirname(abs), { recursive: true });
+        if (routing.strategy === 'none' || routing.strategy === 'domain') {
+            const srcRel = pageHtmlRel(base, defaultLocale, 'index');
+            const srcAbs = path.join(outDir, srcRel);
+            if (fs.existsSync(srcAbs)) {
+                fs.copyFileSync(srcAbs, abs);
+            }
+            continue;
+        }
+        const target = `${base}/${defaultLocale}/`;
         const native = requireNativeAddon();
         if (typeof native.generateRedirectHtml !== 'function') {
             throw new Error('vmz native addon missing generateRedirectHtml — rebuild with `pnpm napi:build`');

package/dist/index.d.ts

@@ -53,6 +53,14 @@ export declare function handshake(host?: {
  * @returns {string | null}
  */
 export declare function resolveCoreRuntimeDist(): string;
+/** Runtime companions required by dist/vmz-serve-host.mjs relative imports. */
+export declare const SERVE_HOST_RUNTIME_FILES: string[][];
+/**
+ * Copy serve-host + registry bootstrap modules from `@vmz/core` into app outDir.
+ * @param {string} outDir
+ * @param {string} [coreDist]
+ */
+export declare function materializeServeHostRuntime(outDir: any, coreDist?: string): void;
 /**
  * @typedef {object} WorkspaceOptions
  * @property {string} root
@@ -234,6 +242,8 @@ declare const _default: {
     expectedProtocol: typeof expectedProtocol;
     resolveNativePath: typeof resolveNativePath;
     resolveCoreRuntimeDist: typeof resolveCoreRuntimeDist;
+    materializeServeHostRuntime: typeof materializeServeHostRuntime;
+    SERVE_HOST_RUNTIME_FILES: string[][];
     loadNative: typeof loadNative;
     getProtocolVersions: typeof getProtocolVersions;
     handshake: typeof handshake;

package/dist/index.js

@@ -4,7 +4,7 @@
  * Coarse-grained only — no transform hooks / per-AST callbacks.
  */
 import { createRequire } from 'node:module';
-import { existsSync } from 'node:fs';
+import { copyFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { materializeWechatPackaging } from './wechat-packaging.js';
@@ -144,6 +144,31 @@ export function resolveCoreRuntimeDist() {
         return nested;
     return null;
 }
+/** Runtime companions required by dist/vmz-serve-host.mjs relative imports. */
+export const SERVE_HOST_RUNTIME_FILES = [
+    ['serve-host.mjs', 'vmz-serve-host.mjs'],
+    ['list-client-components.js', 'list-client-components.js'],
+    ['deployment-registry.js', 'deployment-registry.js'],
+    ['render-host.js', 'render-host.js'],
+];
+/**
+ * Copy serve-host + registry bootstrap modules from `@vmz/core` into app outDir.
+ * @param {string} outDir
+ * @param {string} [coreDist]
+ */
+export function materializeServeHostRuntime(outDir, coreDist = resolveCoreRuntimeDist()) {
+    if (!coreDist) {
+        throw new Error('materializeServeHostRuntime: @vmz/core dist not found');
+    }
+    for (const [srcName, outName] of SERVE_HOST_RUNTIME_FILES) {
+        const src = path.join(coreDist, srcName);
+        const dst = path.join(outDir, outName);
+        if (!existsSync(src)) {
+            throw new Error(`materializeServeHostRuntime: missing ${src}`);
+        }
+        copyFileSync(src, dst);
+    }
+}
 /**
  * @typedef {object} WorkspaceOptions
  * @property {string} root
@@ -458,6 +483,8 @@ export default {
     expectedProtocol,
     resolveNativePath,
     resolveCoreRuntimeDist,
+    materializeServeHostRuntime,
+    SERVE_HOST_RUNTIME_FILES,
     loadNative,
     getProtocolVersions,
     handshake,

package/dist/static-emit.js

@@ -7,7 +7,8 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { preloadComponentRegistry } from '@vmz/core/component-registry';
+import { createRenderHost } from '@vmz/core/render-host';
+import { listClientComponentsSync } from '@vmz/core/component-registry';
 import { emitCdnPolicy } from './cdn-policy.js';
 import { emitContentAddressedAssets } from './content-addressed-assets.js';
 import { absoluteUrl, buildLocalePageMeta, localizeBodyLinks } from './locale-router.js';
@@ -30,8 +31,8 @@ export async function emitWebStatic(distDir, opts = {}) {
     if (!fs.existsSync(domPath)) {
         throw new Error(`emitWebStatic: missing ${domPath} — run vmz build first`);
     }
-    const { renderToString, renderToStream, registerComponents } = await import(pathToFileURL(domPath).href);
-    await preloadComponentRegistry(distDir, registerComponents);
+    const host = await createRenderHost(distDir, { strictDeployment: true, preload: 'none' });
+    const { renderToString, renderToStream } = host;
     const pageCatalog = listPageClientFiles(distDir);
     /** @type {Array<{
      *   routeId: string,
@@ -100,6 +101,7 @@ export async function emitWebStatic(distDir, opts = {}) {
         }
         const meta = await resolvePageMeta(Page, { params, props, pathname: pattern, origin });
         const layoutChain = resolveLayoutChain(distDir, page.chunkId);
+        await host.ensureComponents([page.chunkId, ...layoutChain]);
         let bodyHtml = '';
         for await (const chunk of renderToStream(Page, props, {})) {
             bodyHtml += chunk;
@@ -217,6 +219,7 @@ export async function emitWebStatic(distDir, opts = {}) {
     const digest = sha256Hex(canonicalJson(manifest));
     manifest.manifestDigest = digest;
     writePrettyJsonFile(path.join(vmzDir, 'static-delivery-manifest.json'), manifest);
+    emitStaticClientEntries(distDir, pageCatalog);
     const assets = emitContentAddressedAssets(distDir);
     manifest.contentAddressedAssets = {
         schema: assets.manifest.schema,
@@ -558,3 +561,50 @@ function buildSitemap(_origin, generations) {
     }
     return native.generateSitemapXml(urls);
 }
+/**
+ * Static CDN must ship entry-client/event like serve-host (content-addressed + HTML rewrite).
+ * @param {string} distDir
+ * @param {Array<{ chunkId: string }>} pageCatalog
+ */
+function emitStaticClientEntries(distDir, pageCatalog) {
+    const componentEntries = listClientComponentsSync(distDir, { strict: true });
+    const indexChunk = pageCatalog.find((p) => p.chunkId === 'pages/index')?.chunkId || pageCatalog[0]?.chunkId || 'pages/index';
+    const resumeEntries = loadPageResumeEntriesSync(distDir, indexChunk);
+    const lazySet = new Set(resumeEntries
+        .filter((e) => isEventResumeStrategy(e.strategy))
+        .map((e) => e.component)
+        .filter(Boolean));
+    const eager = componentEntries.filter((e) => !lazySet.has(e.name));
+    const lazy = componentEntries.filter((e) => lazySet.has(e.name));
+    const native = requireNativeAddon();
+    if (typeof native.generateServeEntryClient !== 'function') {
+        throw new Error('vmz native addon missing generateServeEntryClient — rebuild with `pnpm napi:build`');
+    }
+    fs.writeFileSync(path.join(distDir, 'entry-client.js'), native.generateServeEntryClient(eager, lazy, ''), 'utf8');
+    if (typeof native.generateServeEntryEvent === 'function') {
+        fs.writeFileSync(path.join(distDir, 'entry-event.js'), native.generateServeEntryEvent(''), 'utf8');
+    }
+}
+/**
+ * @param {string} distDir
+ * @param {string} chunkId
+ */
+function loadPageResumeEntriesSync(distDir, chunkId) {
+    try {
+        const dep = JSON.parse(fs.readFileSync(path.join(distDir, 'vmz-deployment.json'), 'utf8'));
+        const units = Array.isArray(dep.units) ? dep.units : [];
+        const page = units.find((u) => u.chunkId === chunkId) || units.find((u) => u.chunkId === 'pages/index') || units.find((u) => u.kind === 'page');
+        const entries = Array.isArray(page?.resumeEntries) ? page.resumeEntries : [];
+        return entries.map((e) => ({
+            component: String(e.component || ''),
+            strategy: String(e.strategy || ''),
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+/** @param {string} strategy */
+function isEventResumeStrategy(strategy) {
+    return strategy === 'event' || strategy === 'click' || String(strategy).startsWith('event:');
+}

package/package.json

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