@vmz/core 0.1.7 → 0.1.9

package/dist/client-nav.js

@@ -437,10 +437,11 @@ export function installClientNavigation(opts = {}) {
     let localeTransitionGeneration = 0;
     /**
      * Atomic LocaleTransition (browser host slice):
-     * validate → realize path → navigate/fetch → commit locale attrs from SSR HTML.
+     * - prefix: validate → realize path → navigate/fetch → commit locale attrs from SSR HTML
+     * - none: validate → Host persist (localStorage+cookie) → commit attrs → reload (v1; no URL rewrite)
      * Failure keeps the previous locale surface (no half-page commit).
      * @param {string} toLocale
-     * @param {{ replace?: boolean }} [opts]
+     * @param {{ replace?: boolean, reload?: boolean }} [opts]
      */
     async function transitionLocale(toLocale, opts = {}) {
         const fromLocale = doc.documentElement?.getAttribute('data-locale') || null;
@@ -480,6 +481,10 @@ export function installClientNavigation(opts = {}) {
                 win.__vmzLastLocaleTransition = out;
             return out;
         }
+        const strategy = routing.strategy || 'prefix';
+        if (strategy === 'none') {
+            return transitionLocaleNone(toLocale, fromLocale, opts);
+        }
         const gen = ++localeTransitionGeneration;
         const targetHref = realizePathForLocale(loc.pathname + loc.search + loc.hash, toLocale, routing);
         const result = await transitionTo(targetHref, { replace: opts.replace !== false, softFail: true });
@@ -539,6 +544,64 @@ export function installClientNavigation(opts = {}) {
             win.__vmzLastLocaleTransition = out;
         return out;
     }
+    /**
+     * `routing.strategy: 'none'` — LocaleId is Host preference, not URL.
+     * Persist → commit document attrs + hint → full reload so `#locales/*` re-resolve (I2 v1).
+     * @param {string} toLocale
+     * @param {string | null} fromLocale
+     * @param {{ reload?: boolean }} [opts]
+     */
+    function transitionLocaleNone(toLocale, fromLocale, opts = {}) {
+        const STORE_KEY = 'vmz.locale';
+        try {
+            try {
+                localStorage.setItem(STORE_KEY, toLocale);
+            }
+            catch {
+                /* private mode */
+            }
+            try {
+                doc.cookie = `${STORE_KEY}=${encodeURIComponent(toLocale)}; path=/; max-age=31536000; SameSite=Lax`;
+            }
+            catch {
+                /* ignore */
+            }
+            if (doc.documentElement) {
+                doc.documentElement.setAttribute('data-locale', toLocale);
+                doc.documentElement.setAttribute('lang', toLocale);
+            }
+            if (win)
+                win.__vmzLocaleIdHint = toLocale;
+        }
+        catch (err) {
+            const out = {
+                status: 'rolled_back',
+                fromLocale,
+                toLocale,
+                reason: 'persist_failed',
+                detail: err && err.message ? String(err.message) : String(err),
+            };
+            if (win)
+                win.__vmzLastLocaleTransition = out;
+            return out;
+        }
+        const out = {
+            status: 'committed',
+            fromLocale,
+            toLocale,
+            reason: 'ok',
+            strategy: 'none',
+            href: loc.pathname + loc.search,
+            reload: opts.reload !== false,
+        };
+        if (win)
+            win.__vmzLastLocaleTransition = out;
+        // Reload so generated `#locales` modules re-run __vmzLocaleId() with new preference.
+        if (opts.reload !== false && loc && typeof loc.reload === 'function') {
+            loc.reload();
+        }
+        return out;
+    }
     /**
      * @returns {{ strategy?: string, defaultPrefix?: string, defaultLocale?: string, locales?: string[] } | null}
      */

package/dist/list-client-components.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Discover compiled client component modules from dist (deployment graph or components/).
+ * Shared by serve-host SSR and static emit assemble.
+ */
+/**
+ * @param {string} dir
+ * @returns {Promise<Array<{ name: string, entry: string }>>}
+ */
+export declare function listClientComponents(dir: any): Promise<any[]>;
+/**
+ * Sync variant for callers that already use fs sync (legacy static-emit helpers).
+ * @param {string} dir
+ * @returns {Array<{ name: string, entry: string }>}
+ */
+export declare function listClientComponentsSync(dir: any): any[];
+/**
+ * Import all (or filtered) client components and register for SSR / static emit.
+ * @param {string} distDir
+ * @param {(map: Record<string, unknown>) => void} registerComponents
+ * @param {{
+ *   cacheBust?: string | number,
+ *   include?: (entry: { name: string, entry: string }) => boolean,
+ * }} [opts]
+ */
+export declare function preloadComponentRegistry(distDir: any, registerComponents: any, opts?: {}): Promise<{}>;

package/dist/list-client-components.js

@@ -0,0 +1,120 @@
+// @ts-nocheck
+/**
+ * Discover compiled client component modules from dist (deployment graph or components/).
+ * Shared by serve-host SSR and static emit assemble.
+ */
+import fs from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+/**
+ * @param {string} dir
+ * @returns {Promise<Array<{ name: string, entry: string }>>}
+ */
+export async function listClientComponents(dir) {
+    /** @type {Map<string, { name: string, entry: string }>} */
+    const byName = new Map();
+    try {
+        const raw = await readFile(path.join(dir, 'vmz-deployment.json'), 'utf8');
+        const dep = JSON.parse(raw);
+        for (const unit of dep.units || []) {
+            if (unit?.kind !== 'component')
+                continue;
+            const chunkId = String(unit.chunkId || '');
+            const name = chunkId.split('/').pop();
+            if (!name)
+                continue;
+            const entry = String(unit.clientEntry || `${chunkId}.client.js`).replace(/\\/g, '/');
+            byName.set(name, { name, entry });
+        }
+    }
+    catch {
+        /* fall through to directory scan */
+    }
+    if (byName.size === 0) {
+        const folder = path.join(dir, 'components');
+        let files = [];
+        try {
+            files = await readdir(folder);
+        }
+        catch {
+            return [];
+        }
+        for (const f of files.filter((name) => name.endsWith('.client.js'))) {
+            const name = f.replace(/\.client\.js$/, '');
+            byName.set(name, { name, entry: `components/${name}.client.js` });
+        }
+    }
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Sync variant for callers that already use fs sync (legacy static-emit helpers).
+ * @param {string} dir
+ * @returns {Array<{ name: string, entry: string }>}
+ */
+export function listClientComponentsSync(dir) {
+    /** @type {Map<string, { name: string, entry: string }>} */
+    const byName = new Map();
+    const deploymentPath = path.join(dir, 'vmz-deployment.json');
+    if (fs.existsSync(deploymentPath)) {
+        try {
+            const dep = JSON.parse(fs.readFileSync(deploymentPath, 'utf8'));
+            for (const unit of dep.units || []) {
+                if (unit?.kind !== 'component')
+                    continue;
+                const chunkId = String(unit.chunkId || '');
+                const name = chunkId.split('/').pop();
+                if (!name)
+                    continue;
+                const entry = String(unit.clientEntry || `${chunkId}.client.js`).replace(/\\/g, '/');
+                byName.set(name, { name, entry });
+            }
+        }
+        catch {
+            /* fall through */
+        }
+    }
+    if (byName.size === 0) {
+        const folder = path.join(dir, 'components');
+        let files = [];
+        try {
+            files = fs.readdirSync(folder);
+        }
+        catch {
+            return [];
+        }
+        for (const f of files.filter((name) => name.endsWith('.client.js'))) {
+            const name = f.replace(/\.client\.js$/, '');
+            byName.set(name, { name, entry: `components/${name}.client.js` });
+        }
+    }
+    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Import all (or filtered) client components and register for SSR / static emit.
+ * @param {string} distDir
+ * @param {(map: Record<string, unknown>) => void} registerComponents
+ * @param {{
+ *   cacheBust?: string | number,
+ *   include?: (entry: { name: string, entry: string }) => boolean,
+ * }} [opts]
+ */
+export async function preloadComponentRegistry(distDir, registerComponents, opts = {}) {
+    const entries = await listClientComponents(distDir);
+    /** @type {Record<string, unknown>} */
+    const map = {};
+    for (const entry of entries) {
+        if (opts.include && !opts.include(entry))
+            continue;
+        const abs = path.join(distDir, entry.entry);
+        let href = pathToFileURL(abs).href;
+        if (opts.cacheBust != null && opts.cacheBust !== '') {
+            href = `${href}?t=${encodeURIComponent(String(opts.cacheBust))}`;
+        }
+        const mod = await import(href);
+        map[entry.name] = mod.default;
+    }
+    if (Object.keys(map).length)
+        registerComponents(map);
+    return map;
+}

package/dist/serve-host.mjs

@@ -16,13 +16,14 @@
  * Dev resolve hook propagates `?t=` onto nested relative `file:` imports under
  * dist so soft reload does not keep a stale `lib/*.js` ESM cache entry.
  */
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { readdir, readFile, writeFile } from 'node:fs/promises';
 import http from 'node:http';
 import { createRequire, registerHooks } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { registerComponents, renderToStream, renderToString } from './vmz-dom.js';
+import { listClientComponents } from './list-client-components.js';
 import { handleNodeRequest, setRoutes, setServerModuleResolver } from './vmz-runtime.js';
 const require = createRequire(import.meta.url);
 const distDir = process.env.VMZ_DIST ? path.resolve(process.env.VMZ_DIST) : path.dirname(fileURLToPath(import.meta.url));
@@ -75,6 +76,8 @@ if (isDev) {
 }
 /** @type {number} */
 let reloadToken = Date.now();
+/** @type {string | null} Correlatable build id from vmz dev (Living §12.8). */
+let lastDevBuildId = null;
 /** @type {Array<{ chunkId: string, pageRel: string, segs: ReturnType<typeof parseChunkSegments> }>} */
 let pageCatalog = [];
 /** @type {Map<string, any>} */
@@ -152,7 +155,7 @@ async function renderPageStream(pathname, opts = {}) {
     if (isDev && lastDevError && pageCtors.size === 0) {
         return { status: 500, stream: emitDevErrorHtml(lastDevError) };
     }
-    const localePlan = resolveLocalePath(pathname);
+    const localePlan = resolveLocalePath(pathname, opts.cookieHeader);
     if (localePlan.redirectTo) {
         return { status: 302, redirect: localePlan.redirectTo, headers: { Location: localePlan.redirectTo } };
     }
@@ -477,10 +480,13 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
             `d.innerHTML="<div style='max-width:56rem;margin:0 auto'><p style='color:#f87171;font-weight:700'>Dev Error</p><pre style='white-space:pre-wrap'>"+String(e.message||e).replace(/[<>&]/g,function(c){return {"<":"&lt;",">":"&gt;","&":"&amp;"}[c]})+"</pre></div>";` +
             `document.documentElement.appendChild(d);})();</script>`
         : '';
+    const buildIdBoot = isDev && lastDevBuildId ? `\n  <script>window.__VMZ_DEV_BUILD_ID__=${JSON.stringify(lastDevBuildId)};</script>` : '';
     if (signal?.aborted)
         return;
     const themeId = resolveThemeId(opts.searchParams, opts.cookieHeader);
     const themeBoot = themeBootstrapScript();
+    const localeBoot = localeBootstrapScript();
+    const faviconHead = siteFaviconHeadHtml();
     const propsJson = JSON.stringify(props ?? {});
     const localeId = localeCtx.localeId || localeArtifact?.defaultLocale || 'en';
     const dir = localeCtx.dir || 'ltr';
@@ -552,9 +558,9 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
         ...(cssHref ? { cssEntry: cssHref } : {}),
         isErrorDocument: false,
         htmlExtraAttrs,
-        headExtraHtml: themeBoot,
+        headExtraHtml: `${themeBoot}${localeBoot}${faviconHead}`,
         moduleScriptSrc: entrySrc,
-        bodyTailHtml: `${live}${bootOverlay}`,
+        bodyTailHtml: `${live}${bootOverlay}${buildIdBoot}`,
     });
 }
 const server = http.createServer((req, res) => {
@@ -670,7 +676,7 @@ process.on('SIGINT', () => {
  * Re-import routes / pages / components with a new cache-bust token.
  * Keeps the HTTP server process alive (no Node restart).
  * Failed reloads keep the previous in-memory modules (Vite-like resilience).
- * @param {{ quiet?: boolean, payload?: { affectedChunks?: string[], seedChunks?: string[], emitted?: string[], full?: boolean, islandHmr?: boolean } }} [opts]
+ * @param {{ quiet?: boolean, payload?: { affectedChunks?: string[], seedChunks?: string[], emitted?: string[], full?: boolean, islandHmr?: boolean, buildId?: string, sourceRevision?: string, bundleRevision?: string, changed?: string[] } }} [opts]
  */
 async function softReload(opts = {}) {
     const prevToken = reloadToken;
@@ -683,6 +689,11 @@ async function softReload(opts = {}) {
     const emitted = opts.payload?.emitted ?? [];
     const full = opts.payload?.full;
     const islandHmr = Boolean(opts.payload?.islandHmr);
+    const buildId = opts.payload?.buildId != null ? String(opts.payload.buildId) : null;
+    const sourceRevision = opts.payload?.sourceRevision != null ? String(opts.payload.sourceRevision) : null;
+    const bundleRevision = opts.payload?.bundleRevision != null ? String(opts.payload.bundleRevision) : null;
+    if (buildId)
+        lastDevBuildId = buildId;
     const reloadAllPages = shouldReloadAllPages({ full, affected, emitted, islandHmr });
     try {
         try {
@@ -772,13 +783,21 @@ async function softReload(opts = {}) {
             affectedChunks: affected,
             seedChunks: seeds,
             token: reloadToken,
+            buildId: buildId || lastDevBuildId,
+            sourceRevision,
+            bundleRevision,
+            serveRevision: String(reloadToken),
             full: Boolean(full),
             eventOnlyShell,
         }));
         if (!opts.quiet) {
             const aff = affected.length > 0 ? ` affected=[${affected.join(', ')}]` : full === false ? ' affected=[]' : '';
             const scope = islandHmr ? 'island' : reloadAllPages ? 'all-pages' : `pages=${nextCtors.size}`;
-            console.log(`vmz serve: soft reload ok (mode=${mode}; ${scope}; catalog=${pageCatalog.length}; t=${reloadToken}${aff})`);
+            const bid = buildId || lastDevBuildId;
+            const rev = bid || sourceRevision || bundleRevision
+                ? ` buildId=${bid || '-'} source=${sourceRevision || '-'} bundle=${bundleRevision || '-'} serve=${reloadToken}`
+                : ` t=${reloadToken}`;
+            console.log(`vmz serve: soft reload ok (mode=${mode}; ${scope}; catalog=${pageCatalog.length};${rev}${aff})`);
         }
         return {
             affectedChunks: affected,
@@ -790,6 +809,11 @@ async function softReload(opts = {}) {
             pageCount: pageCatalog.length,
             reloadedPages: islandHmr ? 0 : nextCtors.size,
             reloadAllPages,
+            buildId: buildId || lastDevBuildId,
+            sourceRevision,
+            bundleRevision,
+            serveRevision: String(reloadToken),
+            token: reloadToken,
         };
     }
     catch (err) {
@@ -899,11 +923,14 @@ function escapeHtml(s) {
     return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 }
 /**
- * Resolve LocaleId from pathname using `_vmz/locale-route-realization.json`.
- * LocaleId is a realization dimension — matching still uses stable route path.
+ * Resolve LocaleId for this request.
+ * - `prefix`: LocaleId from URL path (existing).
+ * - `none`: Host preference from cookie `vmz.locale` (validated), else defaultLocale.
+ *   URL never carries LocaleId.
  * @param {string} pathname
+ * @param {string | undefined} cookieHeader
  */
-function resolveLocalePath(pathname) {
+function resolveLocalePath(pathname, cookieHeader) {
     const raw = String(pathname || '/');
     const normalized = raw.length > 1 && raw.endsWith('/') ? raw.slice(0, -1) : raw || '/';
     if (!localeArtifact) {
@@ -913,6 +940,17 @@ function resolveLocalePath(pathname) {
     const defaultLocale = localeArtifact.defaultLocale || supported[0] || 'en';
     const directions = Object.fromEntries((localeArtifact.locales || []).map((l) => [l.id, l.direction || 'ltr']));
     const routing = localeArtifact.routing || {};
+    const strategy = routing.strategy || 'prefix';
+    if (strategy === 'none') {
+        const preferred = readCookie(cookieHeader, LOCALE_STORE_KEY);
+        const localeId = preferred && supported.includes(preferred) ? preferred : defaultLocale;
+        return {
+            localeId,
+            dir: directions[localeId] || 'ltr',
+            restPath: normalized,
+            redirectTo: null,
+        };
+    }
     const parts = normalized.split('/').filter(Boolean);
     let localeId = null;
     let restPath = normalized;
@@ -1036,46 +1074,6 @@ async function loadPageCtor(chunkId) {
     pageCtors.set(chunkId, mod.default);
     return mod.default;
 }
-/**
- * @param {string} dir
- * @returns {Promise<Array<{ name: string, entry: string }>>}
- */
-async function listClientComponents(dir) {
-    /** @type {Map<string, { name: string, entry: string }>} */
-    const byName = new Map();
-    try {
-        const raw = await readFile(path.join(dir, 'vmz-deployment.json'), 'utf8');
-        const dep = JSON.parse(raw);
-        for (const unit of dep.units || []) {
-            if (unit?.kind !== 'component')
-                continue;
-            const chunkId = String(unit.chunkId || '');
-            const name = chunkId.split('/').pop();
-            if (!name)
-                continue;
-            const entry = String(unit.clientEntry || `${chunkId}.client.js`).replace(/\\/g, '/');
-            byName.set(name, { name, entry });
-        }
-    }
-    catch {
-        /* fall through to directory scan */
-    }
-    if (byName.size === 0) {
-        const folder = path.join(dir, 'components');
-        let files = [];
-        try {
-            files = await readdir(folder);
-        }
-        catch {
-            return [];
-        }
-        for (const f of files.filter((name) => name.endsWith('.client.js'))) {
-            const name = f.replace(/\.client\.js$/, '');
-            byName.set(name, { name, entry: `components/${name}.client.js` });
-        }
-    }
-    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
-}
 /**
  * Discover compiled page modules. Prefer Route Graph `pathPattern` from
  * `vmz-deployment.json`; fall back to walking `pages/**` (file-route only).
@@ -1442,6 +1440,8 @@ function requireNativeGenerator() {
  * Style Theme cookie / localStorage key (host contract, not a second theme API).
  */
 const THEME_STORE_KEY = 'vmz-theme';
+/** Host preference key for `routing.strategy: 'none'` (cookie + localStorage). */
+const LOCALE_STORE_KEY = 'vmz.locale';
 /**
  * @param {string} dir
  * @returns {Promise<{ cssEntry: string|null, styleTheme: typeof styleTheme, styleBundleHash: string|null }>}
@@ -1517,6 +1517,45 @@ function themeBootstrapScript() {
     const key = JSON.stringify(THEME_STORE_KEY);
     return `  <script>(function(){try{var k=${key},attr=${attr},ids=${ids};var id=localStorage.getItem(k);if(!id||ids.indexOf(id)<0)return;document.documentElement.setAttribute(attr,id);}catch(e){}})();</script>\n`;
 }
+/**
+ * LocaleId as client state (routing.strategy = none): apply localStorage before any
+ * page/client module runs so `#locales/*` pick the right variant. Prefix strategy
+ * keeps LocaleId in the URL — no boot rewrite.
+ * Also mirrors into cookie so the next SSR negotiate sees Host preference.
+ */
+function localeBootstrapScript() {
+    if (!localeArtifact)
+        return '';
+    const routing = localeArtifact.routing || {};
+    if ((routing.strategy || 'prefix') !== 'none')
+        return '';
+    const ids = (localeArtifact.locales || []).map((l) => l.id).filter(Boolean);
+    if (!ids.length)
+        return '';
+    const key = JSON.stringify(LOCALE_STORE_KEY);
+    const idList = JSON.stringify(ids);
+    return `  <script>(function(){try{var k=${key},ids=${idList};var id=localStorage.getItem(k);if(!id||ids.indexOf(id)<0)return;document.documentElement.setAttribute("data-locale",id);document.documentElement.setAttribute("lang",id);window.__vmzLocaleIdHint=id;document.cookie=k+"="+encodeURIComponent(id)+"; path=/; max-age=31536000; SameSite=Lax";}catch(e){}})();</script>\n`;
+}
+/**
+ * Site favicon links from build artifact `_vmz/site-favicon.json` (author SVG → PNG/ICO).
+ * Empty when skipped / missing — do not invent broken <link>s.
+ */
+function siteFaviconHeadHtml() {
+    try {
+        const p = path.join(distDir, '_vmz', 'site-favicon.json');
+        if (!existsSync(p))
+            return '';
+        // Sync read: head is per-request; file is tiny and rebuilt with dist.
+        const raw = readFileSync(p, 'utf8');
+        const j = JSON.parse(raw);
+        if (j?.status !== 'ready' || typeof j.headHtml !== 'string')
+            return '';
+        return j.headHtml;
+    }
+    catch {
+        return '';
+    }
+}
 /**
  * @param {string|undefined} header
  * @param {string} name

package/dist/server.js

@@ -226,7 +226,7 @@ export async function handleNodeRequest(req, res, opts = {}) {
             return await writeFetchResponse(res, response);
         }
         // Static first for assets + DocumentMount (`/d/…`) so docs aren't swallowed by SSR 404 shells.
-        // web-static route HTML (`index.html`, `about/index.html`, …) is a CDN/deploy projection only —
+        // static route HTML (`index.html`, `about/index.html`, …) is a CDN/deploy projection only —
         // when Server Host SSR is active, those files must not shadow live render (local/dev ≡ SSR truth).
         if (verb === 'GET' && opts.distDir) {
             const nodePath = await import('node:path');
@@ -404,7 +404,7 @@ function safeDistFile(distDir, pathname, nodePath) {
     return full;
 }
 /**
- * web-static emits per-route HTML beside client assets. That HTML is for CDN / local-static
+ * static profile emits per-route HTML beside client assets. That HTML is for CDN / local-static
  * delivery hosts — not for Server Host when SSR is available. DocumentMount stays static.
  * @param {string} file
  * @param {string} pathname

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vmz/core",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "type": "module",
   "description": "VMZ production runtime core — DOM / SSR / HTTP / WriteBarrier (no compiler)",
   "exports": {
@@ -27,6 +27,10 @@
     "./client-nav": {
       "types": "./dist/client-nav.d.ts",
       "default": "./dist/client-nav.js"
+    },
+    "./component-registry": {
+      "types": "./dist/list-client-components.d.ts",
+      "default": "./dist/list-client-components.js"
     }
   },
   "files": [