@vmz/core 0.1.29 → 0.1.30

package/dist/client-nav.js

@@ -370,21 +370,40 @@ export function installClientNavigation(opts = {}) {
         if (a.hasAttribute('download') || a.getAttribute('target') === '_blank')
             return;
         ev.preventDefault();
-        // Retain current LocaleId on same-app Link (realization) — never trust a stale unprefixed href.
-        const realized = localizeClickHref(u.pathname + u.search + u.hash);
+        // Prefer frozen RouteId×LocaleId href table (0.1.30); fall back only when table missing.
+        const realized = localizeClickHref(u.pathname + u.search + u.hash, a.getAttribute('data-vmz-route'));
         void transitionTo(realized, {
             replace: a.getAttribute('data-vmz-replace') === 'true',
         });
     }
     /**
      * @param {string} href
+     * @param {string | null} [routeId]
      */
-    function localizeClickHref(href) {
+    function localizeClickHref(href, routeId) {
         if (!doc?.documentElement)
             return href;
         const locale = doc.documentElement.getAttribute('data-locale');
+        if (!locale)
+            return href;
+        const frozen = lookupFrozenLocaleHref(routeId, locale);
+        if (frozen) {
+            let search = '';
+            let hash = '';
+            const hashIdx = href.indexOf('#');
+            let pathPart = href;
+            if (hashIdx >= 0) {
+                hash = pathPart.slice(hashIdx);
+                pathPart = pathPart.slice(0, hashIdx);
+            }
+            const qIdx = pathPart.indexOf('?');
+            if (qIdx >= 0) {
+                search = pathPart.slice(qIdx);
+            }
+            return `${frozen}${search}${hash}`;
+        }
         const raw = doc.documentElement.getAttribute('data-vmz-locale-routing');
-        if (!locale || !raw)
+        if (!raw)
             return href;
         let routing;
         try {
@@ -617,7 +636,7 @@ export function installClientNavigation(opts = {}) {
         }
     }
     /**
-     * Re-realize current URL under target LocaleId (stable path stays; LocaleId is projection).
+     * Re-realize current URL under target LocaleId via frozen href table when present.
      * @param {string} href
      * @param {string} localeId
      * @param {{ strategy?: string, defaultPrefix?: string, defaultLocale?: string, locales?: string[] }} routing
@@ -638,6 +657,13 @@ export function installClientNavigation(opts = {}) {
         }
         if (!pathname)
             pathname = '/';
+        const fromLocale = doc.documentElement?.getAttribute('data-locale') || null;
+        const routeId = doc.documentElement?.getAttribute('data-vmz-route') ||
+            doc.querySelector?.('[data-vmz-app][data-vmz-route]')?.getAttribute?.('data-vmz-route') ||
+            resolveRouteIdFromHrefTable(pathname, fromLocale);
+        const frozen = lookupFrozenLocaleHref(routeId, localeId);
+        if (frozen)
+            return `${frozen}${search}${hash}`;
         const supported = Array.isArray(routing.locales) ? routing.locales : [];
         const parts = pathname.split('/').filter(Boolean);
         let rest = pathname;
@@ -659,6 +685,52 @@ export function installClientNavigation(opts = {}) {
         const pathOut = rest === '/' ? `/${localeId}` : `/${localeId}${rest}`;
         return `${pathOut}${search}${hash}`;
     }
+    /**
+     * @returns {Record<string, Record<string, string>> | null}
+     */
+    function readLocaleHrefTable() {
+        const raw = doc.documentElement?.getAttribute('data-vmz-locale-hrefs');
+        if (!raw)
+            return null;
+        try {
+            const table = JSON.parse(raw);
+            return table && typeof table === 'object' ? table : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * @param {string | null | undefined} routeId
+     * @param {string} localeId
+     */
+    function lookupFrozenLocaleHref(routeId, localeId) {
+        if (!routeId || !localeId)
+            return null;
+        const table = readLocaleHrefTable();
+        const href = table?.[routeId]?.[localeId];
+        return typeof href === 'string' && href && !/\[[^\]]+\]/.test(href) && !/\/:[^/]+/.test(href) ? href : null;
+    }
+    /**
+     * Reverse-lookup RouteId from frozen table when html lacks data-vmz-route.
+     * @param {string} pathname
+     * @param {string | null} localeId
+     */
+    function resolveRouteIdFromHrefTable(pathname, localeId) {
+        const table = readLocaleHrefTable();
+        if (!table || !localeId)
+            return null;
+        const norm = pathname.length > 1 && pathname.endsWith('/') ? pathname.slice(0, -1) : pathname || '/';
+        for (const [routeId, byLocale] of Object.entries(table)) {
+            const href = byLocale?.[localeId];
+            if (typeof href !== 'string')
+                continue;
+            const h = href.length > 1 && href.endsWith('/') ? href.slice(0, -1) : href;
+            if (h === norm)
+                return routeId;
+        }
+        return null;
+    }
     if (win) {
         win.__vmzTransitionLocale = transitionLocale;
         win.__vmzClientNavSetFetch = (fn) => {

package/dist/localize-body-links.d.ts

@@ -49,7 +49,9 @@ export declare function linkRouteAliasesFromUnits(units: Array<{
 export declare function buildLocaleLinkPlan(artifact: LocaleHrefArtifact | null | undefined): LocaleLinkPlan;
 /** Apply plan rows to `<a data-vmz-route="RouteId">` markers for one LocaleId. */
 export declare function applyLocaleLinkPlan(html: string, localeId: string, plan: LocaleLinkPlan, escapeAttr?: (s: string) => string): string;
-/** Rewrite `<a data-vmz-route href>` using locale realization plan (Plan-native). */
-export declare function localizeBodyLinks(html: string, localeId: string, artifact: LocaleHrefArtifact, escapeAttr?: (s: string) => string): string;
+/** Rewrite `<a data-vmz-route href>` using a frozen locale link plan (preferred) or build once from realization. */
+export declare function localizeBodyLinks(html: string, localeId: string, artifact: LocaleHrefArtifact, escapeAttr?: (s: string) => string, frozenPlan?: LocaleLinkPlan | null): string;
+/** Compact RouteId → LocaleId → href table for browser (no path-prefix algebra). */
+export declare function localeHrefTableFromPlan(plan: LocaleLinkPlan | null | undefined): Record<string, Record<string, string>>;
 /** Legacy same-app href helper for callers without `data-vmz-route` markers. */
 export declare function localizeSameAppHref(href: string, localeId: string, artifact: LocaleHrefArtifact): string;

package/dist/localize-body-links.js

@@ -71,11 +71,28 @@ export function applyLocaleLinkPlan(html, localeId, plan, escapeAttr = (s) => St
         return `<a${newAttrs}>`;
     });
 }
-/** Rewrite `<a data-vmz-route href>` using locale realization plan (Plan-native). */
-export function localizeBodyLinks(html, localeId, artifact, escapeAttr) {
+/** Rewrite `<a data-vmz-route href>` using a frozen locale link plan (preferred) or build once from realization. */
+export function localizeBodyLinks(html, localeId, artifact, escapeAttr, frozenPlan) {
     if (!html || !localeId || !artifact)
         return html;
-    return applyLocaleLinkPlan(html, localeId, buildLocaleLinkPlan(artifact), escapeAttr);
+    const plan = frozenPlan && frozenPlan.schema === LOCALE_LINK_PLAN_SCHEMA && Array.isArray(frozenPlan.rows)
+        ? frozenPlan
+        : buildLocaleLinkPlan(artifact);
+    return applyLocaleLinkPlan(html, localeId, plan, escapeAttr);
+}
+/** Compact RouteId → LocaleId → href table for browser (no path-prefix algebra). */
+export function localeHrefTableFromPlan(plan) {
+    /** @type {Record<string, Record<string, string>>} */
+    const out = Object.create(null);
+    for (const row of plan?.rows || []) {
+        if (!row?.routeId || !row?.localeId || !row?.href)
+            continue;
+        if (/\[[^\]]+\]/.test(row.href) || /\/:[^/]+/.test(row.href))
+            continue;
+        const byLocale = out[row.routeId] || (out[row.routeId] = Object.create(null));
+        byLocale[row.localeId] = row.href;
+    }
+    return out;
 }
 function normalizePath(pathname) {
     let p = String(pathname || '/');

package/dist/serve-host.d.ts

@@ -3,8 +3,8 @@
  *
  * Invoked by `vmz serve` / `vmz dev` (or: node dist/vmz-serve-host.mjs).
  *
- * Pathname matches `vmz-deployment.json` `pathPattern` (explicit `<router>.path`
- * or file-route default). Mini page stems are a different host projection.
+ * Pathname matches compiled `_vmz/route-catalog.json` (frozen segs / pathPattern).
+ * Hosts must not re-parse deployment pathPattern into a live catalog.
  * Not an SPA shell.
  *
  * `VMZ_DEV=1`: POST `/__vmz/reload` soft-reloads modules (cache-bust import);

package/dist/serve-host.mjs

@@ -4,8 +4,8 @@
  *
  * Invoked by `vmz serve` / `vmz dev` (or: node dist/vmz-serve-host.mjs).
  *
- * Pathname matches `vmz-deployment.json` `pathPattern` (explicit `<router>.path`
- * or file-route default). Mini page stems are a different host projection.
+ * Pathname matches compiled `_vmz/route-catalog.json` (frozen segs / pathPattern).
+ * Hosts must not re-parse deployment pathPattern into a live catalog.
  * Not an SPA shell.
  *
  * `VMZ_DEV=1`: POST `/__vmz/reload` soft-reloads modules (cache-bust import);
@@ -23,11 +23,14 @@ import { createRequire, registerHooks } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { listClientComponents } from './list-client-components.js';
-import { linkRouteAliasesFromUnits, localizeBodyLinks } from './localize-body-links.js';
+import { LOCALE_LINK_PLAN_SCHEMA, linkRouteAliasesFromUnits, localeHrefTableFromPlan, localizeBodyLinks } from './localize-body-links.js';
 import { loadNativeAddon } from './native-addon.js';
 import { createRenderHost } from './render-host.js';
 import { resolveRouteLayoutChain } from './route-layout-chain.js';
 import { handleNodeRequest, setRoutes, setServerModuleResolver } from './vmz-runtime.js';
+const ROUTE_CATALOG_SCHEMA = 'vmz.route.catalog.v0';
+const ROUTE_CATALOG_REL = '_vmz/route-catalog.json';
+const LOCALE_LINK_PLAN_REL = '_vmz/locale-link-plan.json';
 const require = createRequire(import.meta.url);
 const distDir = process.env.VMZ_DIST ? path.resolve(process.env.VMZ_DIST) : path.dirname(fileURLToPath(import.meta.url));
 /** App project root for bare import / JSON resolve (dev SSR ≡ build node_modules). */
@@ -154,6 +157,8 @@ let styleBundleHash = null;
 let styleTheme = null;
 /** Locale route realization artifact from `_vmz/locale-route-realization.json` (optional). */
 let localeArtifact = null;
+/** Frozen locale link plan from `_vmz/locale-link-plan.json` (0.1.30 authority). */
+let localeLinkPlan = null;
 /** @type {Set<import('node:http').ServerResponse>} */
 const sseClients = new Set();
 /** In-flight HTTP requests (graceful shutdown drain). */
@@ -575,6 +580,10 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
             defaultLocale: localeArtifact.defaultLocale,
             locales: (localeArtifact.locales || []).map((l) => l.id),
         }));
+        const hrefTable = localeHrefTableFromPlan(localeLinkPlan);
+        if (hrefTable && Object.keys(hrefTable).length) {
+            htmlExtraAttrs.push('data-vmz-locale-hrefs', JSON.stringify(hrefTable));
+        }
     }
     const pageDocMeta = resolvePageDocumentMeta(Page);
     const prevLocaleHint = globalThis.__vmzLocaleIdHint;
@@ -605,9 +614,9 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
             if (signal?.aborted)
                 return;
         }
-        // Locale discipline: same-app Links retain current LocaleId (realization authority).
+        // Locale discipline: apply frozen link plan rows (0.1.30) — no path algebra.
         if (localeArtifact && localeId) {
-            bodyHtml = localizeBodyLinks(bodyHtml, localeId, localeArtifact);
+            bodyHtml = localizeBodyLinks(bodyHtml, localeId, localeArtifact, undefined, localeLinkPlan);
         }
     }
     finally {
@@ -816,6 +825,13 @@ async function softReload(opts = {}) {
         catch {
             localeArtifact = null;
         }
+        try {
+            const rawPlan = JSON.parse(await readFile(path.join(distDir, ...LOCALE_LINK_PLAN_REL.split('/')), 'utf8'));
+            localeLinkPlan = rawPlan?.schema === LOCALE_LINK_PLAN_SCHEMA && Array.isArray(rawPlan.rows) ? rawPlan : null;
+        }
+        catch {
+            localeLinkPlan = null;
+        }
         const componentEntries = await listClientComponents(distDir, { strict: !isDev });
         ssrRenderHost = await createRenderHost(distDir, {
             strictDeployment: !isDev,
@@ -1108,54 +1124,51 @@ async function loadPageCtor(chunkId) {
     return mod.default;
 }
 /**
- * Discover compiled page modules from Route Graph `pathPattern` in
- * `vmz-deployment.json` only (plan-only host — no `pages/**` walk).
+ * Load compiled page catalog from `_vmz/route-catalog.json` (0.1.30 authority).
+ * Hosts must not re-parse deployment pathPattern into a live catalog.
  * @param {string} dir
  */
 async function listPageClientFiles(dir) {
-    const fromDep = await listPagesFromDeployment(dir);
-    if (!fromDep.length) {
+    const fromCatalog = await listPagesFromRouteCatalog(dir);
+    if (!fromCatalog.length) {
         if (isDev) {
-            console.warn(`vmz dev: no page units with pathPattern in ${path.join(dir, 'vmz-deployment.json')}`);
+            console.warn(`vmz dev: missing compiled ${ROUTE_CATALOG_SCHEMA} at ${path.join(dir, ...ROUTE_CATALOG_REL.split('/'))}`);
             return [];
         }
-        throw new Error(`vmz serve: no page units with pathPattern in ${path.join(dir, 'vmz-deployment.json')} (plan-only host)`);
+        throw new Error(`vmz serve: missing compiled ${ROUTE_CATALOG_SCHEMA} at ${path.join(dir, ...ROUTE_CATALOG_REL.split('/'))}`);
     }
-    return fromDep;
+    return fromCatalog;
 }
 /**
  * @param {string} dir
  */
-async function listPagesFromDeployment(dir) {
-    /** @type {Array<{ chunkId: string, pageRel: string, segs: ReturnType<typeof parsePathPattern> }>} */
+async function listPagesFromRouteCatalog(dir) {
+    /** @type {Array<{ chunkId: string, pageRel: string, routeId?: string, pathPattern?: string, segs: ReturnType<typeof parsePathPattern> }>} */
     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, '/');
+        const raw = await readFile(path.join(dir, ...ROUTE_CATALOG_REL.split('/')), 'utf8');
+        const catalog = JSON.parse(raw);
+        if (catalog?.schema !== ROUTE_CATALOG_SCHEMA || !Array.isArray(catalog.pages))
+            return [];
+        for (const page of catalog.pages) {
+            const chunkId = String(page?.chunkId || '').replace(/\\/g, '/');
             if (!chunkId.startsWith('pages/'))
                 continue;
             const stem = chunkId.split('/').pop() || '';
             if (isRouteBoundaryStem(stem))
                 continue;
-            const pattern = String(unit.pathPattern || '').trim();
-            if (!pattern) {
-                throw new Error(`vmz serve: page unit ${chunkId} missing pathPattern in vmz-deployment.json (plan-only host)`);
-            }
-            const pageRel = String(unit.clientEntry || `${chunkId}.client.js`).replace(/\\/g, '/');
+            const segs = Array.isArray(page?.segs) && page.segs.length ? page.segs : parsePathPattern(String(page?.pathPattern || ''));
+            const pageRel = String(page?.pageRel || `${chunkId}.client.js`).replace(/\\/g, '/');
             out.push({
                 chunkId,
                 pageRel,
-                segs: parsePathPattern(pattern),
+                routeId: typeof page?.routeId === 'string' ? page.routeId : chunkId,
+                pathPattern: typeof page?.pathPattern === 'string' ? page.pathPattern : undefined,
+                segs,
             });
         }
     }
-    catch (err) {
-        if (err && typeof err.message === 'string' && err.message.includes('plan-only host'))
-            throw err;
+    catch {
         return [];
     }
     return out;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vmz/core",
-  "version": "0.1.29",
+  "version": "0.1.30",
   "type": "module",
   "description": "VMZ production runtime core — DOM / SSR / HTTP / WriteBarrier (no compiler)",
   "exports": {
@@ -66,12 +66,12 @@
     "linkedom": "^0.18.13"
   },
   "optionalDependencies": {
-    "@vmz/vmz-win32-x64": "0.1.29",
-    "@vmz/vmz-win32-arm64": "0.1.29",
-    "@vmz/vmz-darwin-x64": "0.1.29",
-    "@vmz/vmz-darwin-arm64": "0.1.29",
-    "@vmz/vmz-linux-x64": "0.1.29",
-    "@vmz/vmz-linux-arm64": "0.1.29"
+    "@vmz/vmz-win32-x64": "0.1.30",
+    "@vmz/vmz-win32-arm64": "0.1.30",
+    "@vmz/vmz-darwin-x64": "0.1.30",
+    "@vmz/vmz-darwin-arm64": "0.1.30",
+    "@vmz/vmz-linux-x64": "0.1.30",
+    "@vmz/vmz-linux-arm64": "0.1.30"
   },
   "publishConfig": {
     "access": "public"