@vmz/vmz 0.1.10 → 0.1.11

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vmz/vmz",
-  "version": "0.1.10",
+  "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.10",
-    "@vmz/plugin": "0.1.10",
-    "@vmz/protocol": "0.1.10",
+    "@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.10",
-    "@vmz/test": "0.1.10",
+    "@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.10",
-    "@vmz/vmz-win32-arm64": "0.1.10",
-    "@vmz/vmz-darwin-x64": "0.1.10",
-    "@vmz/vmz-darwin-arm64": "0.1.10",
-    "@vmz/vmz-linux-x64": "0.1.10",
-    "@vmz/vmz-linux-arm64": "0.1.10"
+    "@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"