@vmz/core 0.0.4 → 0.1.1

package/dist/serve-host.mjs

@@ -1,28 +1,78 @@
 // @ts-nocheck
 /**
- * Generic VMZ Node host — SSR file-route pages + dist static + RPC/REST.
+ * Generic VMZ Node host — SSR Route Graph pages + dist static + RPC/REST.
  *
  * Invoked by `vmz serve` / `vmz dev` (or: node dist/vmz-serve-host.mjs).
  *
- * Pathname → `pages/**` (PascalCase stem → lowercase URL; `index` → parent;
- * `[Param]` / `[...rest]` dynamic). Not an SPA shell.
+ * Pathname matches `vmz-deployment.json` `pathPattern` (explicit `<router>.path`
+ * or file-route default). Mini page stems are a different host projection.
+ * Not an SPA shell.
  *
  * `VMZ_DEV=1`: POST `/__vmz/reload` soft-reloads modules (cache-bust import);
  * GET `/__vmz/events` SSE notifies the browser:
  * - island HMR → re-import `entry-client.js` (no full document reload)
  * - otherwise → `location.reload`
+ *
+ * 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 { readdir, readFile, writeFile } from 'node:fs/promises';
 import http from 'node:http';
+import { createRequire, registerHooks } from 'node:module';
 import path from 'node:path';
-import { readdir, writeFile, readFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { setServerModuleResolver, setRoutes, handleNodeRequest } from './vmz-runtime.js';
 import { registerComponents, renderToStream, renderToString } from './vmz-dom.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));
 const host = process.env.VMZ_HOST || '127.0.0.1';
 const port = Number(process.env.VMZ_PORT || process.env.PORT || 5173);
 const isDev = process.env.VMZ_DEV === '1' || process.env.VMZ_DEV === 'true';
+// Absolute origin for in-process client graphs that fall back to HTTP RPC
+// (separate `dist/vmz-runtime.js` instance without setServerModuleResolver).
+globalThis.__VMZ_RPC_ORIGIN = `http://${host}:${port}`;
+/**
+ * Soft reload only busts the top-level `import(page?t=token)`. Nested relative
+ * imports (`../../lib/units.js`) keep the first-loaded ESM cache entry — so a
+ * page can demand exports that the stale dep never had (or vice versa).
+ * Propagate `t` from parentURL onto file: children under this dist.
+ */
+if (isDev) {
+    const distUrlPrefix = pathToFileURL(distDir.endsWith(path.sep) ? distDir : `${distDir}${path.sep}`).href;
+    registerHooks({
+        resolve(specifier, context, nextResolve) {
+            const result = nextResolve(specifier, context);
+            if (!specifier.startsWith('.') || !context.parentURL || !result?.url)
+                return result;
+            let token = '';
+            try {
+                token = new URL(context.parentURL).searchParams.get('t') || '';
+            }
+            catch {
+                return result;
+            }
+            if (!token)
+                return result;
+            if (!result.url.startsWith('file:'))
+                return result;
+            if (!result.url.startsWith(distUrlPrefix)) {
+                try {
+                    if (!fileURLToPath(result.url).startsWith(distDir))
+                        return result;
+                }
+                catch {
+                    return result;
+                }
+            }
+            const u = new URL(result.url);
+            if (u.searchParams.get('t') === token)
+                return result;
+            u.searchParams.set('t', token);
+            return { ...result, url: u.href, shortCircuit: true };
+        },
+    });
+}
 /** @type {number} */
 let reloadToken = Date.now();
 /** @type {Array<{ chunkId: string, pageRel: string, segs: ReturnType<typeof parseChunkSegments> }>} */
@@ -33,6 +83,8 @@ const pageCtors = new Map();
 let cssEntry = null;
 /** @type {{ defaultThemeId: string, themeIds: string[], activationAttr: string, contentHash: string|null } | null} */
 let styleTheme = null;
+/** Locale route realization artifact from `_vmz/locale-route-realization.json` (optional). */
+let localeArtifact = null;
 /** @type {Set<import('node:http').ServerResponse>} */
 const sseClients = new Set();
 /** In-flight HTTP requests (graceful shutdown drain). */
@@ -42,6 +94,12 @@ let shuttingDown = false;
 let ready = false;
 /** @type {{ message: string, stack?: string, at: number } | null} */
 let lastDevError = null;
+/**
+ * Native CodeGenerators handle — must be declared before top-level `await softReload()`
+ * (TDZ: requireNativeGenerator may run during that await).
+ * @type {any}
+ */
+let _nativeGen;
 setServerModuleResolver((moduleId) => {
     const rel = moduleId.replace(/^#server\//, '') + '.js';
     return bustUrl(pathToFileURL(path.join(distDir, '#server', rel)).href);
@@ -94,9 +152,14 @@ async function renderPageStream(pathname, opts = {}) {
     if (isDev && lastDevError && pageCtors.size === 0) {
         return { status: 500, stream: emitDevErrorHtml(lastDevError) };
     }
-    let match = matchFileRoute(pathname, pageCatalog);
+    const localePlan = resolveLocalePath(pathname);
+    if (localePlan.redirectTo) {
+        return { status: 302, redirect: localePlan.redirectTo, headers: { Location: localePlan.redirectTo } };
+    }
+    const routePath = localePlan.restPath || pathname;
+    let match = matchFileRoute(routePath, pageCatalog);
     let status = 200;
-    const gated = await runRouteGate(pathname, match?.chunkId);
+    const gated = await runRouteGate(routePath, match?.chunkId);
     if (gated === 'not_found') {
         match = findRootCatchAll(pageCatalog);
         status = 404;
@@ -121,16 +184,24 @@ async function renderPageStream(pathname, opts = {}) {
         }
         return null;
     }
-    const params = extractRouteParams(match.segs, pathname);
+    const params = extractRouteParams(match.segs, routePath);
     const method = String(opts.method || 'GET').toUpperCase();
+    const localeCtx = {
+        localeId: localePlan.localeId,
+        dir: localePlan.dir,
+        pathname,
+        routePath,
+        alternates: pageMetaAlternates(match.chunkId, localePlan.localeId),
+    };
     if (typeof Page.access === 'function') {
         const access = await Page.access({
             params,
-            pathname,
+            pathname: routePath,
             chunkId: match.chunkId,
             signal: opts.signal,
             searchParams: opts.searchParams,
             method,
+            localeId: localeCtx.localeId,
         });
         const closed = normalizeAccessResult(access);
         if (closed.kind === 'redirect') {
@@ -148,7 +219,7 @@ async function renderPageStream(pathname, opts = {}) {
                     const eventOnlyShell = isEventOnlyShell(resumeEntries.map((e) => e.strategy));
                     return {
                         status: 404,
-                        stream: emitPageHtml(NotFound, catchAll.chunkId, eventOnlyShell, { ...params }, opts),
+                        stream: emitPageHtml(NotFound, catchAll.chunkId, eventOnlyShell, { ...params }, opts, [], localeCtx),
                     };
                 }
             }
@@ -159,12 +230,13 @@ async function renderPageStream(pathname, opts = {}) {
     if (method === 'POST' && typeof Page.action === 'function') {
         const acted = await Page.action({
             params,
-            pathname,
+            pathname: routePath,
             chunkId: match.chunkId,
             signal: opts.signal,
             searchParams: opts.searchParams,
             body: opts.body,
             method,
+            localeId: localeCtx.localeId,
         });
         const actionClosed = normalizeActionResult(acted);
         if (actionClosed.kind === 'redirect') {
@@ -183,10 +255,11 @@ async function renderPageStream(pathname, opts = {}) {
     if (typeof Page.load === 'function') {
         const loaded = await Page.load({
             params,
-            pathname,
+            pathname: routePath,
             chunkId: match.chunkId,
             signal: opts.signal,
             searchParams: opts.searchParams,
+            localeId: localeCtx.localeId,
         });
         if (opts.signal?.aborted) {
             return { status: 499, stream: emitAccessShell('route-nav-cancelled') };
@@ -204,7 +277,7 @@ async function renderPageStream(pathname, opts = {}) {
     const layoutChain = resolveLayoutChain(match.chunkId);
     return {
         status,
-        stream: emitPageHtml(Page, match.chunkId, eventOnlyShell, props, opts, layoutChain),
+        stream: emitPageHtml(Page, match.chunkId, eventOnlyShell, props, opts, layoutChain, localeCtx),
     };
 }
 /**
@@ -260,11 +333,36 @@ function normalizeActionResult(acted) {
  * @param {string} marker
  */
 async function* emitAccessShell(marker) {
-    yield `<!DOCTYPE html>
-<html lang="en">
-<head><meta charset="utf-8" /><title>VMZ</title></head>
-<body><p>${marker}</p></body>
-</html>`;
+    const native = requireNativeGenerator();
+    if (typeof native.generateHtmlShell !== 'function') {
+        throw new Error('vmz native addon missing generateHtmlShell — rebuild with `pnpm napi:build`');
+    }
+    yield native.generateHtmlShell({
+        title: 'App',
+        lang: 'en',
+        cssHrefs: [],
+        bodyHtml: `<p>${marker}</p>`,
+        bodyAttrs: [],
+    });
+}
+/**
+ * Prefer page `static meta()` for document title/description — never brand the framework in business HTML.
+ * @param {any} Page
+ */
+function resolvePageDocumentMeta(Page) {
+    try {
+        let raw = {};
+        if (typeof Page?.meta === 'function')
+            raw = Page.meta() || {};
+        else if (Page?.meta && typeof Page.meta === 'object')
+            raw = Page.meta;
+        const title = String(raw.title || '').trim();
+        const description = String(raw.description || '').trim();
+        return { title: title || 'App', description };
+    }
+    catch {
+        return { title: 'App', description: '' };
+    }
 }
 /**
  * @param {any} Page
@@ -274,12 +372,18 @@ async function* emitAccessShell(marker) {
  * @param {{ signal?: AbortSignal, searchParams?: URLSearchParams, cookieHeader?: string }} [opts]
  * @param {string[]} [layoutChain] layout chunk ids outer→inner
  */
-async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {}, layoutChain = []) {
+async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {}, layoutChain = [], localeCtx = {}) {
     const signal = opts.signal;
     const live = isDev
         ? `\n  <script>
   (() => {
     const es = new EventSource("/__vmz/events");
+    let sawDisconnect = false;
+    es.onerror = () => { sawDisconnect = true; };
+    es.onopen = () => {
+      // Host respawn drops SSE — reload once the new process is up (no manual restart).
+      if (sawDisconnect) location.reload();
+    };
     function showOverlay(err) {
       let el = document.getElementById("vmz-dev-overlay");
       if (!el) {
@@ -298,7 +402,7 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
       const stack = (err && err.stack) || "";
       const esc = (s) => String(s).replace(/[&<>]/g, (c) => ({"&":"&amp;","<":"&lt;",">":"&gt;"}[c]));
       el.innerHTML = "<div style=\\"max-width:56rem;margin:0 auto\\">"
-        + "<p style=\\"margin:0 0 .5rem;color:#f87171;font-weight:700\\">VMZ Dev Error</p>"
+        + "<p style=\\"margin:0 0 .5rem;color:#f87171;font-weight:700\\">Dev Error</p>"
         + "<pre style=\\"white-space:pre-wrap;margin:0 0 1rem;font-size:13px;line-height:1.45\\">" + esc(msg) + "</pre>"
         + (stack ? "<pre style=\\"white-space:pre-wrap;opacity:.7;font-size:12px\\">" + esc(stack) + "</pre>" : "")
         + "<p style=\\"opacity:.65;font-size:12px\\">Fix the file and save — soft reload will clear this overlay.</p>"
@@ -370,50 +474,88 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
             `/* paint immediately */` +
             `var d=document.createElement("div");d.id="vmz-dev-overlay";d.setAttribute("role","alert");` +
             `Object.assign(d.style,{position:"fixed",inset:"0",zIndex:"2147483646",background:"rgba(15,17,21,0.92)",color:"#f4f4f5",fontFamily:"ui-monospace,monospace",padding:"2rem",overflow:"auto"});` +
-            `d.innerHTML="<div style='max-width:56rem;margin:0 auto'><p style='color:#f87171;font-weight:700'>VMZ Dev Error</p><pre style='white-space:pre-wrap'>"+String(e.message||e).replace(/[<>&]/g,function(c){return {"<":"&lt;",">":"&gt;","&":"&amp;"}[c]})+"</pre></div>";` +
+            `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>`
         : '';
     if (signal?.aborted)
         return;
     const themeId = resolveThemeId(opts.searchParams, opts.cookieHeader);
-    const htmlTheme = htmlThemeAttributeForId(themeId);
     const themeBoot = themeBootstrapScript();
-    const cssLink = cssEntry ? `  <link rel="stylesheet" href="/${String(cssEntry).replace(/^\/+/, '')}?t=${reloadToken}" />\n` : '';
     const propsJson = JSON.stringify(props ?? {});
-    const layoutAttr = layoutChain.length ? ` data-vmz-layout="${escapeAttr(layoutChain.join(','))}"` : '';
-    yield `<!DOCTYPE html>
-<html lang="en"${htmlTheme}>
-<head>
-  <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>VMZ</title>
-${themeBoot}${cssLink}</head>
-<body>
-  <div id="app" data-vmz-page="${escapeAttr(chunkId)}"${layoutAttr} data-vmz-props="${escapeAttr(propsJson)}">`;
+    const localeId = localeCtx.localeId || localeArtifact?.defaultLocale || 'en';
+    const dir = localeCtx.dir || 'ltr';
+    /** @type {string[]} */
+    const htmlExtraAttrs = [...htmlThemeAttrPair(themeId)];
+    if (localeArtifact?.routing) {
+        htmlExtraAttrs.push('data-vmz-locale-routing', JSON.stringify({
+            strategy: localeArtifact.routing.strategy || 'prefix',
+            defaultPrefix: localeArtifact.routing.defaultPrefix || 'include',
+            defaultLocale: localeArtifact.defaultLocale,
+            locales: (localeArtifact.locales || []).map((l) => l.id),
+        }));
+    }
+    const pageDocMeta = resolvePageDocumentMeta(Page);
+    const prevLocaleHint = globalThis.__vmzLocaleIdHint;
+    globalThis.__vmzLocaleIdHint = localeId;
     let bodyHtml = '';
-    for await (const chunk of renderToStream(Page, props, { signal })) {
+    try {
+        for await (const chunk of renderToStream(Page, props, { signal })) {
+            if (signal?.aborted)
+                return;
+            bodyHtml += chunk;
+        }
         if (signal?.aborted)
             return;
-        bodyHtml += chunk;
+        // Wrap page HTML in layout chain (outer → inner) via default slot injection.
+        for (let i = layoutChain.length - 1; i >= 0; i--) {
+            const Layout = await loadPageCtor(layoutChain[i]);
+            if (!Layout)
+                continue;
+            bodyHtml = await renderToString(Layout, {}, { signal, slotHtml: bodyHtml });
+            if (signal?.aborted)
+                return;
+        }
+        // Locale discipline: same-app Links retain current LocaleId (realization authority).
+        if (localeArtifact && localeId) {
+            bodyHtml = localizeBodyLinksInHost(bodyHtml, localeId, localeArtifact);
+        }
     }
-    if (signal?.aborted)
-        return;
-    // Wrap page HTML in layout chain (outer → inner) via default slot injection.
-    for (let i = layoutChain.length - 1; i >= 0; i--) {
-        const Layout = await loadPageCtor(layoutChain[i]);
-        if (!Layout)
-            continue;
-        bodyHtml = await renderToString(Layout, {}, { signal, slotHtml: bodyHtml });
-        if (signal?.aborted)
-            return;
+    finally {
+        if (prevLocaleHint === undefined)
+            delete globalThis.__vmzLocaleIdHint;
+        else
+            globalThis.__vmzLocaleIdHint = prevLocaleHint;
     }
-    yield bodyHtml;
     if (signal?.aborted)
         return;
-    yield `</div>
-  <script type="module" src="/${eventOnlyShell ? 'entry-event.js' : 'entry-client.js'}?t=${reloadToken}"></script>${live}${bootOverlay}
-</body>
-</html>`;
+    const native = requireNativeGenerator();
+    if (typeof native.generatePageShell !== 'function') {
+        throw new Error('vmz native addon missing generatePageShell — rebuild with `pnpm napi:build`');
+    }
+    const entrySrc = `/${eventOnlyShell ? 'entry-event.js' : 'entry-client.js'}?t=${reloadToken}`;
+    const cssHref = cssEntry ? `${String(cssEntry).replace(/^\/+/, '')}?t=${reloadToken}` : undefined;
+    yield native.generatePageShell({
+        bodyHtml,
+        chunkId,
+        layoutChain,
+        propsJson,
+        meta: {
+            title: pageDocMeta.title,
+            description: pageDocMeta.description,
+            canonical: '',
+            robots: '',
+            lang: localeId,
+            dir,
+            alternates: localeCtx.alternates || [],
+        },
+        // napi Option<String>: omit/undefined = None; null is rejected as String
+        ...(cssHref ? { cssEntry: cssHref } : {}),
+        isErrorDocument: false,
+        htmlExtraAttrs,
+        headExtraHtml: themeBoot,
+        moduleScriptSrc: entrySrc,
+        bodyTailHtml: `${live}${bootOverlay}`,
+    });
 }
 const server = http.createServer((req, res) => {
     const url = new URL(req.url || '/', `http://${host}:${port}`);
@@ -528,17 +670,20 @@ 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[], full?: boolean, islandHmr?: boolean } }} [opts]
+ * @param {{ quiet?: boolean, payload?: { affectedChunks?: string[], seedChunks?: string[], emitted?: string[], full?: boolean, islandHmr?: boolean } }} [opts]
  */
 async function softReload(opts = {}) {
     const prevToken = reloadToken;
     const prevCatalog = pageCatalog;
+    const prevCtors = new Map(pageCtors);
     const nextToken = Date.now();
     reloadToken = nextToken;
     const affected = opts.payload?.affectedChunks ?? [];
     const seeds = opts.payload?.seedChunks ?? [];
+    const emitted = opts.payload?.emitted ?? [];
     const full = opts.payload?.full;
     const islandHmr = Boolean(opts.payload?.islandHmr);
+    const reloadAllPages = shouldReloadAllPages({ full, affected, emitted, islandHmr });
     try {
         try {
             const routes = JSON.parse(await readFile(path.join(distDir, 'vmz-routes.json'), 'utf8'));
@@ -547,6 +692,12 @@ async function softReload(opts = {}) {
         catch {
             setRoutes([]);
         }
+        try {
+            localeArtifact = JSON.parse(await readFile(path.join(distDir, '_vmz', 'locale-route-realization.json'), 'utf8'));
+        }
+        catch {
+            localeArtifact = null;
+        }
         const componentEntries = await listClientComponents(distDir);
         const nextCatalog = await listPageClientFiles(distDir);
         if (!nextCatalog.length) {
@@ -570,7 +721,8 @@ async function softReload(opts = {}) {
             components[entry.name] = mod.default;
         }
         if (!islandHmr) {
-            for (const p of nextCatalog) {
+            const pagesToLoad = reloadAllPages ? nextCatalog : nextCatalog.filter((p) => pageNeedsReload(p.chunkId, affected));
+            for (const p of pagesToLoad) {
                 const pageRel = `${p.chunkId}.client.js`;
                 const href = bustUrl(pathToFileURL(path.join(distDir, pageRel)).href);
                 const mod = await import(href);
@@ -579,9 +731,21 @@ async function softReload(opts = {}) {
         }
         pageCatalog = nextCatalog;
         if (!islandHmr) {
-            pageCtors.clear();
-            for (const [k, v] of nextCtors)
-                pageCtors.set(k, v);
+            if (reloadAllPages) {
+                pageCtors.clear();
+                for (const [k, v] of nextCtors)
+                    pageCtors.set(k, v);
+            }
+            else {
+                // Keep unaffected page constructors; only swap what we re-imported.
+                for (const [k, v] of nextCtors)
+                    pageCtors.set(k, v);
+                // Drop ctors for pages that disappeared from catalog.
+                for (const id of [...pageCtors.keys()]) {
+                    if (!nextCatalog.some((p) => p.chunkId === id))
+                        pageCtors.delete(id);
+                }
+            }
         }
         if (Object.keys(components).length) {
             registerComponents(components);
@@ -613,7 +777,8 @@ async function softReload(opts = {}) {
         }));
         if (!opts.quiet) {
             const aff = affected.length > 0 ? ` affected=[${affected.join(', ')}]` : full === false ? ' affected=[]' : '';
-            console.log(`vmz serve: soft reload ok (mode=${mode}; pages=${pageCatalog.length}; t=${reloadToken}${aff})`);
+            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})`);
         }
         return {
             affectedChunks: affected,
@@ -623,15 +788,49 @@ async function softReload(opts = {}) {
             mode,
             eventOnlyShell,
             pageCount: pageCatalog.length,
+            reloadedPages: islandHmr ? 0 : nextCtors.size,
+            reloadAllPages,
         };
     }
     catch (err) {
         reloadToken = prevToken;
         pageCatalog = prevCatalog;
+        pageCtors.clear();
+        for (const [k, v] of prevCtors)
+            pageCtors.set(k, v);
         lastDevError = normalizeDevError(err);
         throw err;
     }
 }
+/**
+ * Shared lib / full rebuild / missing affected list → refresh every page ctor.
+ * Otherwise only re-import the dirty page chunks (Vite-like module graph).
+ * @param {{ full?: boolean, affected: string[], emitted: string[], islandHmr: boolean }} opts
+ */
+function shouldReloadAllPages(opts) {
+    if (opts.islandHmr)
+        return false;
+    if (opts.full)
+        return true;
+    if (!opts.affected.length)
+        return true;
+    for (const f of opts.emitted) {
+        const n = String(f).replace(/\\/g, '/');
+        if (n.includes('/lib/') || /\/Application\.client\.js$/.test(n) || /\/vmz-(dom|runtime|http|client-nav)\.js$/.test(n)) {
+            return true;
+        }
+    }
+    return false;
+}
+/** @param {string} chunkId @param {string[]} affected */
+function pageNeedsReload(chunkId, affected) {
+    if (chunkId === 'pages/Layout' || chunkId.endsWith('/Layout'))
+        return true;
+    return affected.some((a) => {
+        const id = String(a);
+        return id === chunkId || chunkId.startsWith(`${id}/`) || id.startsWith(`${chunkId}/`);
+    });
+}
 /** @param {string} event */
 function notifySse(event) {
     for (const client of [...sseClients]) {
@@ -659,23 +858,16 @@ function normalizeDevError(err) {
 async function* emitDevErrorHtml(err) {
     const msg = escapeHtml(err.message || 'Unknown error');
     const stack = err.stack ? escapeHtml(err.stack) : '';
-    yield `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>VMZ Dev Error</title>
-  <style>
+    const style = `<style>
     body{margin:0;background:#0f1115;color:#f4f4f5;font:14px/1.5 ui-monospace,SFMono-Regular,Menlo,Consolas,monospace}
     main{max-width:56rem;margin:0 auto;padding:2rem 1.25rem}
     h1{margin:0 0 .75rem;color:#f87171;font-size:1.1rem}
     pre{white-space:pre-wrap;margin:0 0 1rem}
     .hint{opacity:.65;font-size:12px}
-  </style>
-</head>
-<body>
+  </style>`;
+    const body = `${style}
   <main>
-    <h1>VMZ Dev Error</h1>
+    <h1>Dev Error</h1>
     <pre>${msg}</pre>
     ${stack ? `<pre style="opacity:.7;font-size:12px">${stack}</pre>` : ''}
     <p class="hint">Dev host stayed up. Fix the source and save — soft reload will recover.</p>
@@ -689,14 +881,147 @@ async function* emitDevErrorHtml(err) {
       if (msg && msg.type === "hmr") location.reload();
     };
   })();
-  </script>
-</body>
-</html>`;
+  </script>`;
+    const native = requireNativeGenerator();
+    if (typeof native.generateHtmlShell !== 'function') {
+        throw new Error('vmz native addon missing generateHtmlShell — rebuild with `pnpm napi:build`');
+    }
+    yield native.generateHtmlShell({
+        title: 'Dev Error',
+        lang: 'en',
+        cssHrefs: [],
+        bodyHtml: body,
+        bodyAttrs: [],
+    });
 }
 /** @param {string} s */
 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.
+ * @param {string} pathname
+ */
+function resolveLocalePath(pathname) {
+    const raw = String(pathname || '/');
+    const normalized = raw.length > 1 && raw.endsWith('/') ? raw.slice(0, -1) : raw || '/';
+    if (!localeArtifact) {
+        return { localeId: 'en', dir: 'ltr', restPath: normalized, redirectTo: null };
+    }
+    const supported = (localeArtifact.locales || []).map((l) => l.id);
+    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 parts = normalized.split('/').filter(Boolean);
+    let localeId = null;
+    let restPath = normalized;
+    if (parts.length && supported.includes(parts[0])) {
+        localeId = parts[0];
+        const rest = parts.slice(1);
+        restPath = rest.length ? `/${rest.join('/')}` : '/';
+    }
+    // omit defaultPrefix: prefixed defaultLocale URL redirects to unprefixed canonical.
+    if (routing.defaultPrefix === 'omit' && localeId === defaultLocale) {
+        return {
+            localeId: defaultLocale,
+            dir: directions[defaultLocale] || 'ltr',
+            restPath,
+            redirectTo: restPath,
+        };
+    }
+    const contentLocale = localeId || defaultLocale;
+    return {
+        localeId: contentLocale,
+        dir: directions[contentLocale] || 'ltr',
+        restPath,
+        redirectTo: null,
+    };
+}
+/**
+ * Realize href for current LocaleId (prefix strategy). Kept local so serve-host
+ * stays free of CLI package imports.
+ * @param {string} href
+ * @param {string} localeId
+ * @param {any} artifact
+ */
+function localizeSameAppHrefHost(href, localeId, artifact) {
+    if (!href || !localeId || !artifact)
+        return href;
+    if (href.startsWith('#') || /^(mailto|tel|javascript):/i.test(href))
+        return href;
+    if (/^[a-z][a-z0-9+.-]*:/i.test(href) && !href.startsWith('/'))
+        return href;
+    let pathname = String(href);
+    let search = '';
+    let hash = '';
+    const hashIdx = pathname.indexOf('#');
+    if (hashIdx >= 0) {
+        hash = pathname.slice(hashIdx);
+        pathname = pathname.slice(0, hashIdx);
+    }
+    const qIdx = pathname.indexOf('?');
+    if (qIdx >= 0) {
+        search = pathname.slice(qIdx);
+        pathname = pathname.slice(0, qIdx);
+    }
+    if (!pathname)
+        pathname = '/';
+    const supported = (artifact.locales || []).map((l) => l.id).filter(Boolean);
+    const defaultLocale = artifact.defaultLocale || artifact.routing?.defaultLocale;
+    const routing = artifact.routing || {};
+    const strategy = routing.strategy || 'prefix';
+    const defaultPrefix = routing.defaultPrefix || 'include';
+    const parts = pathname.split('/').filter(Boolean);
+    let rest = pathname;
+    if (parts.length && supported.includes(parts[0])) {
+        const r = parts.slice(1);
+        rest = r.length ? `/${r.join('/')}` : '/';
+    }
+    if (rest.length > 1 && rest.endsWith('/'))
+        rest = rest.slice(0, -1);
+    if (!rest.startsWith('/'))
+        rest = `/${rest}`;
+    if (strategy === 'none' || strategy === 'domain')
+        return `${rest}${search}${hash}`;
+    const omitDefault = defaultPrefix === 'omit' && localeId === defaultLocale;
+    if (omitDefault)
+        return `${rest}${search}${hash}`;
+    const pathOut = rest === '/' ? `/${localeId}` : `/${localeId}${rest}`;
+    return `${pathOut}${search}${hash}`;
+}
+/**
+ * @param {string} html
+ * @param {string} localeId
+ * @param {any} artifact
+ */
+function localizeBodyLinksInHost(html, localeId, artifact) {
+    if (!html || !localeId || !artifact)
+        return html;
+    return String(html).replace(/<a\b([^>]*)>/gi, (full, attrs) => {
+        if (!/\bdata-vmz-route\s*=/.test(attrs))
+            return full;
+        const hm = attrs.match(/\bhref\s*=\s*"([^"]*)"/i);
+        if (!hm)
+            return full;
+        const next = localizeSameAppHrefHost(hm[1], localeId, artifact);
+        if (next === hm[1])
+            return full;
+        const newAttrs = attrs.replace(/\bhref\s*=\s*"[^"]*"/i, `href="${escapeAttr(next)}"`);
+        return `<a${newAttrs}>`;
+    });
+}
+/**
+ * @param {string} chunkId
+ * @param {string} localeId
+ */
+function pageMetaAlternates(chunkId, localeId) {
+    if (!localeArtifact?.pageMetas)
+        return [];
+    const meta = localeArtifact.pageMetas.find((m) => m.routeId === chunkId && m.locale === localeId) ||
+        localeArtifact.pageMetas.find((m) => m.routeId === chunkId && m.locale === localeArtifact.defaultLocale);
+    return Array.isArray(meta?.alternates) ? meta.alternates : [];
+}
 /** @param {string} href */
 function bustUrl(href) {
     const u = new URL(href);
@@ -752,10 +1077,14 @@ async function listClientComponents(dir) {
     return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
 /**
- * Discover compiled page modules under dist/pages.
+ * Discover compiled page modules. Prefer Route Graph `pathPattern` from
+ * `vmz-deployment.json`; fall back to walking `pages/**` (file-route only).
  * @param {string} dir
  */
 async function listPageClientFiles(dir) {
+    const fromDep = await listPagesFromDeployment(dir);
+    if (fromDep.length)
+        return fromDep;
     const root = path.join(dir, 'pages');
     /** @type {Array<{ chunkId: string, pageRel: string, segs: ReturnType<typeof parseChunkSegments> }>} */
     const out = [];
@@ -787,6 +1116,38 @@ async function listPageClientFiles(dir) {
     await walk(root, []);
     return out;
 }
+/**
+ * @param {string} dir
+ */
+async function listPagesFromDeployment(dir) {
+    /** @type {Array<{ chunkId: string, pageRel: string, segs: ReturnType<typeof parseChunkSegments> }>} */
+    const out = [];
+    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 !== 'page')
+                continue;
+            const chunkId = String(unit.chunkId || '').replace(/\\/g, '/');
+            if (!chunkId.startsWith('pages/'))
+                continue;
+            const stem = chunkId.split('/').pop() || '';
+            if (isRouteBoundaryStem(stem))
+                continue;
+            const pageRel = String(unit.clientEntry || `${chunkId}.client.js`).replace(/\\/g, '/');
+            const pattern = String(unit.pathPattern || '').trim();
+            out.push({
+                chunkId,
+                pageRel,
+                segs: pattern ? parsePathPattern(pattern) : parseChunkSegments(chunkId),
+            });
+        }
+    }
+    catch {
+        return [];
+    }
+    return out;
+}
 /**
  * File-route segments from chunk id (`pages/Install` → `/install`).
  * Skips URL-invisible `(group)` dirs; boundary stems never reach here.
@@ -803,17 +1164,43 @@ function parseChunkSegments(chunkId) {
             continue;
         if (p === 'index' && i === parts.length - 1)
             continue;
-        const catchAll = /^\[\.\.\.([^\]]+)\]$/.exec(p);
-        const param = /^\[([^\]]+)\]$/.exec(p);
-        if (catchAll)
-            segs.push({ kind: 'catch', name: catchAll[1] });
-        else if (param)
-            segs.push({ kind: 'param', name: param[1] });
-        else
-            segs.push({ kind: 'static', value: p.toLowerCase() });
+        segs.push(parsePathSegment(p));
+    }
+    return segs;
+}
+/**
+ * Browser HTTP pattern (`/` / `/home` / `/users/:id` / `/blog/[...slug]`).
+ * @param {string} pattern
+ */
+function parsePathPattern(pattern) {
+    const raw = String(pattern || '').trim();
+    if (!raw || raw === '/')
+        return [];
+    const parts = raw.replace(/^\/+/, '').split('/').filter(Boolean);
+    /** @type {Array<{ kind: 'static' | 'param' | 'catch', value?: string, name?: string }>} */
+    const segs = [];
+    for (const p of parts) {
+        if (isRouteGroupDir(p))
+            continue;
+        segs.push(parsePathSegment(p));
     }
     return segs;
 }
+/**
+ * @param {string} p
+ */
+function parsePathSegment(p) {
+    const catchAll = /^\[\.\.\.([^\]]+)\]$/.exec(p);
+    const param = /^\[([^\]]+)\]$/.exec(p);
+    const colon = /^:([A-Za-z_][\w]*)$/.exec(p);
+    if (catchAll)
+        return { kind: 'catch', name: catchAll[1] };
+    if (param)
+        return { kind: 'param', name: param[1] };
+    if (colon)
+        return { kind: 'param', name: colon[1] };
+    return { kind: 'static', value: p.toLowerCase() };
+}
 function isRouteGroupDir(seg) {
     return typeof seg === 'string' && seg.startsWith('(') && seg.endsWith(')') && seg.length > 2;
 }
@@ -963,50 +1350,11 @@ async function runRouteGate(pathname, chunkId) {
  */
 function emitEntryClient(eager, lazy, token) {
     const q = `?t=${token}`;
-    const imports = eager.map((e) => `import ${e.name} from ${JSON.stringify(`./${e.entry}${q}`)};`).join('\n');
-    const map = eager.length ? `registerComponents({ ${eager.map((e) => e.name).join(', ')} });` : '';
-    const entryByName = Object.fromEntries([...eager, ...lazy].map((e) => [e.name, e.entry]));
-    const loader = lazy.length
-        ? `const __vmzComponentEntries = ${JSON.stringify(entryByName)};
-globalThis.__vmzLoadComponent = async (name) => {
-  const entry = __vmzComponentEntries[name] || ("components/" + name + ".client.js");
-  const mod = await import("./" + entry + "${q}");
-  return mod.default;
-};`
-        : '';
-    return `/**
- * Generated by vmz serve — hydrate matched file-route page (data-vmz-page) + layout chain + client Link takeover.
- */
-import { registerComponents, hydrate, hydrateRoute, destroy } from ${JSON.stringify(`./vmz-dom.js${q}`)};
-import { installClientNavigation } from ${JSON.stringify(`./vmz-client-nav.js${q}`)};
-${imports}
-
-${map}
-${loader}
-
-const root = document.getElementById("app");
-if (!root) throw new Error("vmz: missing #app");
-const chunkId = root.getAttribute("data-vmz-page");
-if (!chunkId) throw new Error("vmz: missing data-vmz-page");
-let props = {};
-try {
-  const raw = root.getAttribute("data-vmz-props");
-  if (raw) props = JSON.parse(raw);
-} catch { /* ignore */ }
-const layoutChain = (root.getAttribute("data-vmz-layout") || "").split(",").map((s) => s.trim()).filter(Boolean);
-const layoutCtors = [];
-for (const id of layoutChain) {
-  layoutCtors.push((await import("./" + id + ".client.js${q}")).default);
-}
-const Page = (await import("./" + chunkId + ".client.js${q}")).default;
-await hydrateRoute(Page, root, props, layoutCtors);
-installClientNavigation({
-  hydrate,
-  hydrateRoute,
-  destroy,
-  importPage: async (id) => (await import("./" + id + ".client.js${q}")).default,
-});
-`;
+    const native = requireNativeGenerator();
+    if (typeof native.generateServeEntryClient !== 'function') {
+        throw new Error('vmz native addon missing generateServeEntryClient — rebuild with `pnpm napi:build`');
+    }
+    return native.generateServeEntryClient(eager, lazy, q);
 }
 /**
  * EventEntry zero-framework bootstrap: no static import of vmz-dom / page / islands.
@@ -1015,35 +1363,80 @@ installClientNavigation({
  */
 function emitEntryEvent(token) {
     const q = `?t=${token}`;
-    return `/**
- * Generated by vmz serve — EventEntry zero-framework JS shell.
+    const native = requireNativeGenerator();
+    if (typeof native.generateServeEntryEvent !== 'function') {
+        throw new Error('vmz native addon missing generateServeEntryEvent — rebuild with `pnpm napi:build`');
+    }
+    return native.generateServeEntryEvent(q);
+}
+/**
+ * Load vmz N-API CodeGenerators (same discovery as `@vmz/vmz` native-addon).
+ * @returns {any}
  */
-(async () => {
-  const roots = [...document.querySelectorAll(
-    '[data-vmz-entry="event"], [data-vmz-client="event"], [data-vmz-client^="event:"]',
-  )];
-  for (const el of roots) {
-    if (el.__vmzEventWired) continue;
-    el.__vmzEventWired = true;
-    const strat = el.getAttribute("data-vmz-client") || "event";
-    let type = "click";
-    if (strat.startsWith("event:") && strat.length > 6) type = strat.slice(6) || "click";
-    else if (strat === "click") type = "click";
-    el.addEventListener(
-      type,
-      async () => {
-        const { registerComponents, resume } = await import(${JSON.stringify(`./vmz-dom.js${q}`)});
-        const name = el.getAttribute("data-vmz-island");
-        if (!name) throw new Error("vmz: EventEntry missing data-vmz-island");
-        const Comp = (await import("./components/" + name + ".client.js${q}")).default;
-        registerComponents({ [name]: Comp });
-        await resume(Comp, el);
-      },
-      { once: true },
-    );
-  }
-})();
-`;
+function requireNativeGenerator() {
+    if (_nativeGen !== undefined) {
+        if (!_nativeGen) {
+            throw new Error('vmz native addon missing — run `pnpm napi:build` (serve entry printers live in vmz-generator via N-API)');
+        }
+        return _nativeGen;
+    }
+    try {
+        const envPath = (typeof process.env.VMZ_NATIVE_NODE === 'string' && process.env.VMZ_NATIVE_NODE.trim()) || '';
+        if (envPath) {
+            _nativeGen = require(path.resolve(envPath));
+            return _nativeGen;
+        }
+        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 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 */
+        }
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        candidates.push(path.join(here, 'node_modules', name, `vmz.${triple}.node`), path.join(here, 'node_modules', name, 'vmz.node'), path.join(here, '..', 'node_modules', name, `vmz.${triple}.node`), path.join(here, '..', 'node_modules', name, 'vmz.node'));
+        for (const p of candidates) {
+            if (existsSync(p)) {
+                _nativeGen = require(p);
+                return _nativeGen;
+            }
+        }
+        _nativeGen = null;
+    }
+    catch {
+        _nativeGen = null;
+    }
+    if (!_nativeGen) {
+        throw new Error('vmz native addon missing — run `pnpm napi:build` (serve entry printers live in vmz-generator via N-API)');
+    }
+    return _nativeGen;
 }
 /**
  * Style Theme cookie / localStorage key (host contract, not a second theme API).
@@ -1101,14 +1494,15 @@ function resolveThemeId(searchParams, cookieHeader) {
 /**
  * Always emit activation attr for an explicit theme id (incl. default) so it overrides OS media.
  * @param {string|null} themeId
+ * @returns {[string, string] | []} flattened attr pair for generatePageShell
  */
-function htmlThemeAttributeForId(themeId) {
+function htmlThemeAttrPair(themeId) {
     if (!styleTheme || !themeId)
-        return '';
+        return [];
     const attr = styleTheme.activationAttr || 'data-theme';
     if (!(styleTheme.themeIds || []).includes(themeId))
-        return '';
-    return ` ${attr}="${escapeAttr(themeId)}"`;
+        return [];
+    return [attr, themeId];
 }
 /**
  * Inline boot when SSR had no query/cookie: apply explicit `localStorage` only.