@vmz/core 0.1.24 → 0.1.25

package/dist/dom-core.d.ts

@@ -71,6 +71,14 @@ export declare function settlePendingChildMounts(inst: any): Promise<void>;
  */
 export declare function runDirectCreate(Component: any, inst: any): any;
 /** Host API for compiler-emitted `__vmzCreate` (direct path, Program IR B). */
+/**
+ * First default `<slot>` owned by this component tree — skip nested `[data-vmz]`
+ * hosts (Button/Link/Empty label slots). `querySelector('slot')` steals those and
+ * projects parent siblings into the wrong host (commercial Drawer into Create btn).
+ * @param {Element | null | undefined} root
+ * @returns {Element | null}
+ */
+export declare function findOwnedDefaultSlot(root: any): any;
 export declare const directApi: {
     /** @type {object | null} */
     _inst: any;
@@ -86,8 +94,22 @@ export declare const directApi: {
      * }}
      */
     _eachCtx: any;
+    /** @type {null | {
+     * el: (tag: string) => Element,
+     * text: (value?: any) => Text,
+     * componentHost?: (name: string) => HTMLElement | null,
+     * enter?: (node: Element) => boolean,
+     * leave?: () => void,
+     * scopeDepth?: () => number,
+     * rewindScope?: (depth: number) => void,
+     * beginBranchScope?: () => () => void,
+     * }} */
+    _resumeAdopt: any;
     el(tag: any): any;
-    text(value: any): Text;
+    text(value: any): any;
+    /** Push adopted node's private resume pool for depth-first child create. */
+    adoptEnter(node: any): any;
+    adoptLeave(): void;
     frag(): DocumentFragment;
     attr(el: any, name: any, value: any): void;
     on(el: any, type: any, handler: any): void;
@@ -138,7 +160,7 @@ export declare const directApi: {
      * @param {Record<string, any>} props
      * @param {string | null} client
      */
-    component(hostInst: any, name: any, props: any, client: any): HTMLDivElement;
+    component(hostInst: any, name: any, props: any, client: any): any;
     /**
      * Keep nested Direct child props live with parent field writes.
      * @param {object} hostInst
@@ -150,6 +172,7 @@ export declare const directApi: {
     bindComponentProp(hostInst: any, hostEl: any, propName: any, deps: any, get: any): void;
     /**
      * Project parent children into nested Direct component default `<slot>`.
+     * Uses {@link findOwnedDefaultSlot} so nested Button/Link slots are not stolen.
      * @param {HTMLElement} hostEl
      * @param {Node} node
      */

package/dist/dom-core.js

@@ -262,6 +262,34 @@ export function runDirectCreate(Component, inst) {
     }
 }
 /** Host API for compiler-emitted `__vmzCreate` (direct path, Program IR B). */
+/**
+ * First default `<slot>` owned by this component tree — skip nested `[data-vmz]`
+ * hosts (Button/Link/Empty label slots). `querySelector('slot')` steals those and
+ * projects parent siblings into the wrong host (commercial Drawer into Create btn).
+ * @param {Element | null | undefined} root
+ * @returns {Element | null}
+ */
+export function findOwnedDefaultSlot(root) {
+    if (!root || root.nodeType !== 1)
+        return null;
+    const tag = String(root.tagName || '').toLowerCase();
+    if (tag === 'slot' && !root.getAttribute('name'))
+        return root;
+    const kids = root.children;
+    if (!kids || !kids.length)
+        return null;
+    for (let i = 0; i < kids.length; i++) {
+        const c = kids[i];
+        if (c.nodeType !== 1)
+            continue;
+        if (c.hasAttribute('data-vmz'))
+            continue;
+        const hit = findOwnedDefaultSlot(c);
+        if (hit)
+            return hit;
+    }
+    return null;
+}
 export const directApi = {
     /** @type {object | null} */
     _inst: null,
@@ -277,14 +305,52 @@ export const directApi = {
      * }}
      */
     _eachCtx: null,
+    /** @type {null | {
+     * el: (tag: string) => Element,
+     * text: (value?: any) => Text,
+     * componentHost?: (name: string) => HTMLElement | null,
+     * enter?: (node: Element) => boolean,
+     * leave?: () => void,
+     * scopeDepth?: () => number,
+     * rewindScope?: (depth: number) => void,
+     * beginBranchScope?: () => () => void,
+     * }} */
+    _resumeAdopt: null,
     el(tag) {
+        if (directApi._resumeAdopt)
+            return directApi._resumeAdopt.el(tag);
         noteDomCreate();
         return document.createElement(tag || 'div');
     },
     text(value) {
+        if (directApi._resumeAdopt)
+            return directApi._resumeAdopt.text(value);
         noteDomCreate();
         return document.createTextNode(value == null ? '' : String(value));
     },
+    /** Push adopted node's private resume pool for depth-first child create. */
+    adoptEnter(node) {
+        const adopt = directApi._resumeAdopt;
+        if (adopt && typeof adopt.enter === 'function') {
+            const ok = adopt.enter(node);
+            if (ok)
+                adopt._enterBalance = (adopt._enterBalance || 0) + 1;
+            return ok;
+        }
+        return false;
+    },
+    adoptLeave() {
+        const adopt = directApi._resumeAdopt;
+        // Emit always pairs leave after enter; if enter failed (fresh node, no
+        // pool), do not pop — unbalanced leave previously stole parent scopes
+        // and projected siblings into nested Button slots.
+        if (!adopt || typeof adopt.leave !== 'function')
+            return;
+        if ((adopt._enterBalance || 0) <= 0)
+            return;
+        adopt._enterBalance -= 1;
+        adopt.leave();
+    },
     frag() {
         noteDomCreate();
         return document.createDocumentFragment();
@@ -426,9 +492,16 @@ export const directApi = {
      * @param {string | null} client
      */
     component(hostInst, name, props, client) {
-        noteDomCreate();
-        const host = document.createElement('div');
-        host.setAttribute('data-vmz', name);
+        /** @type {HTMLElement | null} */
+        let host = null;
+        if (directApi._resumeAdopt && typeof directApi._resumeAdopt.componentHost === 'function') {
+            host = directApi._resumeAdopt.componentHost(name);
+        }
+        if (!host) {
+            noteDomCreate();
+            host = document.createElement('div');
+            host.setAttribute('data-vmz', name);
+        }
         /** @type {Record<string, any>} */
         const resolved = {};
         for (const [k, v] of Object.entries(props || {})) {
@@ -471,9 +544,23 @@ export const directApi = {
         if (!(Ctor.__vmzDirect && typeof Ctor.__vmzCreate === 'function')) {
             throw new Error(`vmz:dom direct component <${name}> requires __vmzCreate (rebuild child with Direct)`);
         }
-        const node = runDirectCreate(Ctor, child);
+        // Nested resume: keep parent `_resumeAdopt` so child reclaim parked SSR nodes.
+        // Enter the host's private child pool so nested create cannot see uncle siblings.
+        const adopt = directApi._resumeAdopt;
+        const entered = adopt && typeof adopt.enter === 'function' ? adopt.enter(host) : false;
+        let node;
+        try {
+            node = runDirectCreate(Ctor, child);
+        }
+        finally {
+            if (entered && adopt && typeof adopt.leave === 'function')
+                adopt.leave();
+        }
         if (node) {
-            child.__vmzDomRoot = node;
+            // ifBlock/eachBlock roots are DocumentFragments: appendChild moves
+            // children into `host` and empties the fragment. Keep a live Element
+            // root so projectDefaultSlot can find `<slot>` (Button v-if/v-else).
+            child.__vmzDomRoot = node.nodeType === 11 ? host : node;
             host.appendChild(node);
         }
         host.__vmzInst = child;
@@ -524,6 +611,7 @@ export const directApi = {
     },
     /**
      * Project parent children into nested Direct component default `<slot>`.
+     * Uses {@link findOwnedDefaultSlot} so nested Button/Link slots are not stolen.
      * @param {HTMLElement} hostEl
      * @param {Node} node
      */
@@ -531,22 +619,20 @@ export const directApi = {
         if (!hostEl || node == null)
             return;
         const child = hostEl.__vmzInst;
-        const root = (child && child.__vmzDomRoot) || hostEl;
+        let root = (child && child.__vmzDomRoot) || hostEl;
+        // Emptied DocumentFragment after append must not receive slot kids.
+        if (!root || root.nodeType !== 1)
+            root = hostEl;
         /** @type {Element | null} */
         let slot = null;
         if (root && root.nodeType === 1) {
-            if (String(root.tagName || '').toLowerCase() === 'slot' && !root.getAttribute('name')) {
-                slot = root;
-            }
-            else if (typeof root.querySelector === 'function') {
-                slot = root.querySelector('slot:not([name])');
-            }
+            slot = findOwnedDefaultSlot(root);
         }
         if (slot && slot.parentNode) {
             slot.replaceWith(node);
             return;
         }
-        if (root && typeof root.appendChild === 'function')
+        if (root && root.nodeType === 1 && typeof root.appendChild === 'function')
             root.appendChild(node);
         else
             hostEl.appendChild(node);
@@ -632,10 +718,14 @@ export const directApi = {
                 directApi._branchBinds = binds;
                 directApi._inst = inst;
                 let created = null;
+                const adopt = directApi._resumeAdopt;
+                const endBranch = adopt && typeof adopt.beginBranchScope === 'function' ? adopt.beginBranchScope() : null;
                 try {
                     created = branches[next].create.call(inst, directApi);
                 }
                 finally {
+                    if (typeof endBranch === 'function')
+                        endBranch();
                     directApi._branchBinds = prevSink;
                     directApi._inst = prevInst;
                 }

package/dist/dom-ssr.d.ts

@@ -2,6 +2,7 @@
  * VMZ DOM SSR / hydrate / resume — precise patches, no VDOM diff.
  * Imports client DOM primitives from ./dom-core.js for tree-shakeable browser entry.
  */
+import { findOwnedDefaultSlot } from './dom-core.js';
 export declare function renderToString(Component: any, props?: {}, opts?: {}): Promise<any>;
 /**
  * Stream SSR via the same Direct serialize schedule as `renderToString`.
@@ -16,10 +17,11 @@ export declare function renderToStream(Component: any, props?: {}, opts?: {}): A
 /**
  * Live-DOM counterpart: first default `<slot>` owned by this tree, not by a nested
  * `[data-vmz]` component (Button/Link labels, etc.).
+ * Re-exported from dom-core (single implementation).
  * @param {Element | null | undefined} root
  * @returns {Element | null}
  */
-export declare function findOwnedDefaultSlot(root: any): any;
+export { findOwnedDefaultSlot };
 /**
  * Hydrate/mount a file-route page inside an optional layout chain (outer → inner).
  * Mirrors SSR `slotHtml` wrapping: each layout's owned default slot becomes the

package/dist/dom-ssr.js

@@ -4,7 +4,7 @@
  * Imports client DOM primitives from ./dom-core.js for tree-shakeable browser entry.
  */
 import { applyDirectHostBox, directHostBoxStyleAttr } from './direct-host-box.js';
-import { applyDomAttr, applyPreservedState, BOOLEAN_HTML_ATTRS, createInstance, destroy, directApi, eventPropHandlerName, getRegisteredComponent, hasMeaningfulChild, isEventEntryStrategy, mount, noteDomCreate, resolveComponent, runDirectCreate, scheduleClientOn, settlePendingChildMounts, snapshotInstanceState, stripFns, } from './dom-core.js';
+import { applyPreservedState, BOOLEAN_HTML_ATTRS, createInstance, destroy, directApi, eventPropHandlerName, findOwnedDefaultSlot, getRegisteredComponent, hasMeaningfulChild, isEventEntryStrategy, mount, noteDomCreate, resolveComponent, runDirectCreate, scheduleClientOn, settlePendingChildMounts, snapshotInstanceState, stripFns, } from './dom-core.js';
 import { markUnknownComponentHost, serializeUnknownComponentNode } from './unknown-component.js';
 /** @type {Error | null} last linkedom resolve failure (for clear SSR errors) */
 let _ssrDocumentLastError = null;
@@ -185,31 +185,11 @@ function injectDefaultSlotHtml(node, html) {
 /**
  * Live-DOM counterpart: first default `<slot>` owned by this tree, not by a nested
  * `[data-vmz]` component (Button/Link labels, etc.).
+ * Re-exported from dom-core (single implementation).
  * @param {Element | null | undefined} root
  * @returns {Element | null}
  */
-export function findOwnedDefaultSlot(root) {
-    if (!root || root.nodeType !== 1)
-        return null;
-    const tag = String(root.tagName || '').toLowerCase();
-    if (tag === 'slot' && !root.getAttribute('name'))
-        return root;
-    const kids = root.children;
-    if (!kids || !kids.length)
-        return null;
-    for (let i = 0; i < kids.length; i++) {
-        const c = kids[i];
-        if (c.nodeType !== 1)
-            continue;
-        // Nested component host — its slots are not the layout page outlet.
-        if (c.hasAttribute('data-vmz'))
-            continue;
-        const hit = findOwnedDefaultSlot(c);
-        if (hit)
-            return hit;
-    }
-    return null;
-}
+export { findOwnedDefaultSlot };
 /**
  * Hydrate/mount a file-route page inside an optional layout chain (outer → inner).
  * Mirrors SSR `slotHtml` wrapping: each layout's owned default slot becomes the
@@ -592,6 +572,12 @@ const serializeApi = {
     onMethod() {
         /* named method events are also attached only during client resume */
     },
+    adoptEnter() {
+        return false;
+    },
+    adoptLeave() {
+        /* resume scope only */
+    },
     bindText(inst, bindingId, deps, get, textNode) {
         let raw = '';
         try {
@@ -620,13 +606,15 @@ const serializeApi = {
             return;
         // serializeApi.component returns a serialize el tree (or island shell).
         const root = hostEl.__kind === 'el' ? hostEl : null;
-        const findSlot = (n) => {
+        const findOwnedSlot = (n) => {
             if (!n || n.__kind !== 'el')
                 return null;
             if (n.tag === 'slot' && !(n.attrs && n.attrs.name))
                 return n;
             for (const c of n.children || []) {
-                const hit = findSlot(c);
+                if (c && c.__kind === 'el' && c.attrs && c.attrs['data-vmz'] != null)
+                    continue;
+                const hit = findOwnedSlot(c);
                 if (hit)
                     return hit;
             }
@@ -636,12 +624,14 @@ const serializeApi = {
         let slot = null;
         if (root) {
             for (const c of root.children || []) {
-                slot = findSlot(c);
+                if (c && c.__kind === 'el' && c.attrs && c.attrs['data-vmz'] != null)
+                    continue;
+                slot = findOwnedSlot(c);
                 if (slot)
                     break;
             }
             if (!slot)
-                slot = findSlot(root);
+                slot = findOwnedSlot(root);
         }
         if (slot) {
             slot.__rawHtml = null;
@@ -974,6 +964,167 @@ export function attachEventEntries(root = globalThis.document) {
         });
     }
 }
+/**
+ * Adopt parked SSR/Island nodes while `__vmzCreate` rebuilds the live tree.
+ * Children of `rootEl` are moved into `pool` first so the create schedule never
+ * leaves orphan SSR siblings beside if/each markers (duplicate h2 / stale text).
+ *
+ * Scope rules (sibling-host invariant):
+ * - Candidates are **direct children** of the current scope pool only (no deep
+ *   walk into other parked siblings).
+ * - Adopting a node parks its children into a **private** `__vmzResumePool`.
+ * - `enter(node)` / `leave()` push that private pool for depth-first child create.
+ * - `beginBranchScope()` moves one top-level SSR node into an isolated pool so
+ *   ifBlock branch create cannot steal parent siblings (Drawer / Button hosts).
+ *
+ * @param {DocumentFragment} pool
+ * @param {Element} rootEl
+ */
+function createResumeAdopt(pool, rootEl) {
+    const used = new WeakSet();
+    /** @type {DocumentFragment[]} */
+    const scopeStack = [pool];
+    /**
+     * @param {Node} root
+     * @param {(n: Text) => void} visit
+     */
+    const walkTexts = (root, visit) => {
+        if (!root)
+            return;
+        if (root.nodeType === 3) {
+            visit(/** @type {Text} */ (root));
+            return;
+        }
+        if (root.nodeType !== 1)
+            return;
+        for (let c = root.firstChild; c; c = c.nextSibling)
+            walkTexts(c, visit);
+    };
+    const currentScope = () => scopeStack[scopeStack.length - 1] || pool;
+    const markElement = (n) => {
+        used.add(n);
+        if (typeof n.getAttribute === 'function') {
+            const k = n.getAttribute('data-vmz-key');
+            if (k != null && n.__vmzKey == null)
+                n.__vmzKey = k;
+        }
+        // Private child pool — never dump into the parent/global pool (that let
+        // if branches reclaim Drawer/sibling hosts parked as uncles).
+        const childPool = document.createDocumentFragment();
+        while (n.firstChild)
+            childPool.appendChild(n.firstChild);
+        n.__vmzResumePool = childPool;
+        return n;
+    };
+    /** @returns {Generator<Element>} */
+    function* elementCandidates() {
+        const scope = currentScope();
+        if (scope === pool && rootEl && !used.has(rootEl))
+            yield rootEl;
+        // Snapshot — adopt may move nodes out of scope while iterating.
+        const kids = [...scope.childNodes];
+        for (const n of kids) {
+            if (n.nodeType === 1 && !used.has(/** @type {Element} */ (n))) {
+                yield /** @type {Element} */ (n);
+            }
+        }
+    }
+    /** @returns {Generator<Text>} */
+    function* textCandidates() {
+        const scope = currentScope();
+        const kids = [...scope.childNodes];
+        for (const n of kids) {
+            /** @type {Text[]} */
+            const found = [];
+            walkTexts(n, (t) => {
+                if (!used.has(t))
+                    found.push(t);
+            });
+            for (const t of found)
+                yield t;
+        }
+    }
+    const adoptElement = (tag) => {
+        const want = String(tag || 'div').toLowerCase();
+        for (const el of elementCandidates()) {
+            if (String(el.tagName).toLowerCase() === want)
+                return markElement(el);
+        }
+        noteDomCreate();
+        return document.createElement(tag || 'div');
+    };
+    const adoptText = (value) => {
+        for (const n of textCandidates()) {
+            used.add(n);
+            if (value != null && value !== '')
+                n.textContent = String(value);
+            return n;
+        }
+        noteDomCreate();
+        return document.createTextNode(value == null ? '' : String(value));
+    };
+    /** Reclaim SSR `<div data-vmz="Name">` hosts for nested Direct components. */
+    const componentHost = (name) => {
+        const want = String(name || '');
+        for (const el of elementCandidates()) {
+            if (String(el.tagName).toLowerCase() !== 'div')
+                continue;
+            if (el.getAttribute('data-vmz') !== want)
+                continue;
+            return markElement(el);
+        }
+        return null;
+    };
+    const enter = (node) => {
+        if (!node || !node.__vmzResumePool)
+            return false;
+        scopeStack.push(node.__vmzResumePool);
+        return true;
+    };
+    const leave = () => {
+        if (scopeStack.length <= 1)
+            return;
+        scopeStack.pop();
+    };
+    const scopeDepth = () => scopeStack.length;
+    const rewindScope = (depth) => {
+        const d = Math.max(1, Number(depth) || 1);
+        while (scopeStack.length > d)
+            scopeStack.pop();
+    };
+    /**
+     * Isolate the next top-level SSR sibling as the only candidates for an
+     * if/else branch create (commercial Card: Empty branch must not adopt Drawer).
+     * @returns {() => void} end callback
+     */
+    const beginBranchScope = () => {
+        const parent = currentScope();
+        const branchPool = document.createDocumentFragment();
+        for (const n of [...parent.childNodes]) {
+            if (n.nodeType === 1 && !used.has(/** @type {Element} */ (n))) {
+                branchPool.appendChild(n);
+                break;
+            }
+        }
+        scopeStack.push(branchPool);
+        const depth = scopeStack.length;
+        return () => {
+            while (branchPool.firstChild)
+                branchPool.removeChild(branchPool.firstChild);
+            rewindScope(depth - 1);
+        };
+    };
+    return {
+        el: adoptElement,
+        text: adoptText,
+        componentHost,
+        enter,
+        leave,
+        scopeDepth,
+        rewindScope,
+        beginBranchScope,
+    };
+}
 /**
  * Adopt existing Island DOM while running the same `__vmzCreate` schedule (resume).
  * @param {new (props?: object) => any} Component
@@ -985,50 +1136,32 @@ function runDirectResume(Component, inst, container) {
     if (!rootEl || rootEl.nodeType !== 1) {
         return runDirectCreate(Component, inst);
     }
-    let textI = 0;
-    const api = {
-        _inst: inst,
-        _branchBinds: null,
-        _itemPatches: null,
-        el(tag) {
-            if (String(rootEl.tagName).toLowerCase() !== String(tag).toLowerCase()) {
-                noteDomCreate();
-                return document.createElement(tag);
-            }
-            return rootEl;
-        },
-        frag() {
-            return document.createDocumentFragment();
-        },
-        text(s) {
-            while (textI < rootEl.childNodes.length) {
-                const n = rootEl.childNodes[textI++];
-                if (n.nodeType === 3) {
-                    if (s != null && s !== '')
-                        n.textContent = String(s);
-                    return n;
-                }
-            }
-            noteDomCreate();
-            return document.createTextNode(String(s ?? ''));
-        },
-        attr(el, name, value) {
-            applyDomAttr(el, name, value);
-        },
-        on(el, type, handler) {
-            el.addEventListener(type, handler);
-        },
-        bindText: directApi.bindText,
-        bindAttr: directApi.bindAttr,
-        bindComponentProp: directApi.bindComponentProp,
-        projectDefaultSlot: directApi.projectDefaultSlot,
-        setHtml: directApi.setHtml,
-        bindHtml: directApi.bindHtml,
-        ifBlock: directApi.ifBlock,
-        eachBlock: directApi.eachBlock,
-        component: directApi.component,
-    };
-    return Component.__vmzCreate.call(inst, api);
+    // Park SSR descendants so create can append if/each structure without orphan siblings.
+    const pool = document.createDocumentFragment();
+    while (rootEl.firstChild)
+        pool.appendChild(rootEl.firstChild);
+    const prevInst = directApi._inst;
+    const prevBranch = directApi._branchBinds;
+    const prevItems = directApi._itemPatches;
+    const prevEach = directApi._eachCtx;
+    const prevAdopt = directApi._resumeAdopt;
+    directApi._inst = inst;
+    directApi._branchBinds = null;
+    directApi._itemPatches = null;
+    directApi._eachCtx = null;
+    directApi._resumeAdopt = createResumeAdopt(pool, rootEl);
+    try {
+        return Component.__vmzCreate.call(inst, directApi);
+    }
+    finally {
+        directApi._resumeAdopt = prevAdopt;
+        directApi._inst = prevInst;
+        directApi._branchBinds = prevBranch;
+        directApi._itemPatches = prevItems;
+        directApi._eachCtx = prevEach;
+        while (pool.firstChild)
+            pool.removeChild(pool.firstChild);
+    }
 }
 /**
  * @param {new (props?: object) => any} Component
@@ -1071,14 +1204,10 @@ export async function hydrate(Component, container, props = {}, opts = {}) {
         }
     }
     else {
-        // Interim: shallow resume leaves if/each binders unbound. Recreate against live
-        // DOM so patches attach. Leaf nodeIdentity (same Element) remains TODO for deep adopt.
-        container.replaceChildren();
-        const node = runDirectCreate(Component, inst);
-        if (node) {
+        // Deep adopt: park SSR children, rebuild schedule, reclaim nodes (no orphan siblings).
+        const node = runDirectResume(Component, inst, container);
+        if (node)
             inst.__vmzDomRoot = node;
-            container.appendChild(node);
-        }
     }
     await settlePendingChildMounts(inst);
     container.__vmzInst = inst;

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

@@ -1,7 +1,8 @@
 /**
- * Single HTML `<a data-vmz-route>` locale rewrite for serve-host and static-emit.
- * Plan-only hosts must not keep a second copy of this semantic (0.1.22).
+ * Plan-native locale link rewrite for serve-host and static-emit.
+ * Href authority is RouteId × LocaleId realization rows — not path parsing on existing href.
  */
+export declare const LOCALE_LINK_PLAN_SCHEMA = "vmz.static.locale_link_plan.v0";
 export type LocaleHrefArtifact = {
     locales?: Array<{
         id: string;
@@ -12,8 +13,26 @@ export type LocaleHrefArtifact = {
         defaultPrefix?: string;
         defaultLocale?: string;
     };
+    realizations?: Array<{
+        routeId: string;
+        localeId: string;
+        path: string;
+    }>;
 };
-/** Rewrite a same-app href to the given LocaleId via route realization. */
-export declare function localizeSameAppHref(href: string, localeId: string, artifact: LocaleHrefArtifact): string;
-/** Rewrite `<a data-vmz-route href>` in HTML body to retain `localeId`. */
+export type LocaleLinkPlanRow = {
+    routeId: string;
+    localeId: string;
+    href: string;
+};
+export type LocaleLinkPlan = {
+    schema: typeof LOCALE_LINK_PLAN_SCHEMA;
+    rows: LocaleLinkPlanRow[];
+};
+/** Build RouteId × LocaleId → href rows from locale route realization artifact. */
+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;
+/** 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

@@ -1,7 +1,50 @@
 /**
- * Single HTML `<a data-vmz-route>` locale rewrite for serve-host and static-emit.
- * Plan-only hosts must not keep a second copy of this semantic (0.1.22).
+ * Plan-native locale link rewrite for serve-host and static-emit.
+ * Href authority is RouteId × LocaleId realization rows — not path parsing on existing href.
  */
+export const LOCALE_LINK_PLAN_SCHEMA = 'vmz.static.locale_link_plan.v0';
+/** Build RouteId × LocaleId → href rows from locale route realization artifact. */
+export function buildLocaleLinkPlan(artifact) {
+    const rows = [];
+    for (const r of artifact?.realizations || []) {
+        if (!r?.routeId || !r?.localeId || !r?.path)
+            continue;
+        rows.push({ routeId: String(r.routeId), localeId: String(r.localeId), href: String(r.path) });
+    }
+    rows.sort((a, b) => (a.routeId === b.routeId ? a.localeId.localeCompare(b.localeId) : a.routeId.localeCompare(b.routeId)));
+    return { schema: LOCALE_LINK_PLAN_SCHEMA, rows };
+}
+/** Apply plan rows to `<a data-vmz-route="RouteId">` markers for one LocaleId. */
+export function applyLocaleLinkPlan(html, localeId, plan, escapeAttr = (s) => String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;')) {
+    if (!html || !localeId || !plan?.rows?.length)
+        return html;
+    const byRoute = new Map();
+    for (const row of plan.rows) {
+        if (row.localeId === localeId)
+            byRoute.set(row.routeId, row.href);
+    }
+    if (!byRoute.size)
+        return html;
+    return String(html).replace(/<a\b([^>]*)>/gi, (full, attrs) => {
+        const rm = attrs.match(/\bdata-vmz-route\s*=\s*"([^"]*)"/i);
+        if (!rm)
+            return full;
+        const href = byRoute.get(rm[1]);
+        if (!href)
+            return full;
+        const hm = attrs.match(/\bhref\s*=\s*"([^"]*)"/i);
+        if (hm && hm[1] === href)
+            return full;
+        const newAttrs = hm ? attrs.replace(/\bhref\s*=\s*"[^"]*"/i, `href="${escapeAttr(href)}"`) : ` href="${escapeAttr(href)}"${attrs}`;
+        return `<a${newAttrs}>`;
+    });
+}
+/** Rewrite `<a data-vmz-route href>` using locale realization plan (Plan-native). */
+export function localizeBodyLinks(html, localeId, artifact, escapeAttr) {
+    if (!html || !localeId || !artifact)
+        return html;
+    return applyLocaleLinkPlan(html, localeId, buildLocaleLinkPlan(artifact), escapeAttr);
+}
 function normalizePath(pathname) {
     let p = String(pathname || '/');
     if (!p.startsWith('/'))
@@ -10,32 +53,7 @@ function normalizePath(pathname) {
         p = p.slice(0, -1);
     return p || '/';
 }
-function parseLocaleFromPath(pathname, supportedLocales) {
-    const parts = normalizePath(pathname).split('/').filter(Boolean);
-    if (!parts.length)
-        return { localeId: null, restPath: '/' };
-    if (supportedLocales.includes(parts[0])) {
-        const rest = parts.slice(1);
-        return { localeId: parts[0], restPath: rest.length ? `/${rest.join('/')}` : '/' };
-    }
-    return { localeId: null, restPath: normalizePath(pathname) };
-}
-function realizeRoutePath(localeId, pathPattern, routing) {
-    const strategy = routing.strategy || 'prefix';
-    const defaultPrefix = routing.defaultPrefix || 'include';
-    const defaultLocale = routing.defaultLocale;
-    const base = normalizePath(pathPattern);
-    if (strategy === 'none' || strategy === 'domain') {
-        return { path: base };
-    }
-    const omitDefault = defaultPrefix === 'omit' && localeId === defaultLocale;
-    if (omitDefault) {
-        return { path: base };
-    }
-    const pathOut = base === '/' ? `/${localeId}` : `/${localeId}${base}`;
-    return { path: pathOut };
-}
-/** Rewrite a same-app href to the given LocaleId via route realization. */
+/** Legacy same-app href helper for callers without `data-vmz-route` markers. */
 export function localizeSameAppHref(href, localeId, artifact) {
     if (!href || !localeId || !artifact)
         return href;
@@ -43,6 +61,7 @@ export function localizeSameAppHref(href, localeId, artifact) {
         return href;
     if (/^[a-z][a-z0-9+.-]*:/i.test(href) && !href.startsWith('/'))
         return href;
+    const plan = buildLocaleLinkPlan(artifact);
     let pathname = String(href);
     let search = '';
     let hash = '';
@@ -56,34 +75,12 @@ export function localizeSameAppHref(href, localeId, artifact) {
         search = pathname.slice(qIdx);
         pathname = pathname.slice(0, qIdx);
     }
-    if (!pathname)
-        pathname = '/';
-    const supported = (artifact.locales || []).map((l) => (typeof l === 'string' ? l : l.id)).filter(Boolean);
-    const defaultLocale = artifact.defaultLocale || artifact.routing?.defaultLocale;
-    const routing = {
-        strategy: artifact.routing?.strategy || 'prefix',
-        defaultPrefix: artifact.routing?.defaultPrefix || 'include',
-        defaultLocale,
-    };
-    const parsed = parseLocaleFromPath(pathname, supported);
-    const rest = parsed.restPath || '/';
-    const realized = realizeRoutePath(localeId, rest, routing);
-    return `${realized.path}${search}${hash}`;
-}
-/** Rewrite `<a data-vmz-route href>` in HTML body to retain `localeId`. */
-export function localizeBodyLinks(html, localeId, artifact, escapeAttr = (s) => String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;')) {
-    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 = localizeSameAppHref(hm[1], localeId, artifact);
-        if (next === hm[1])
-            return full;
-        const newAttrs = attrs.replace(/\bhref\s*=\s*"[^"]*"/i, `href="${escapeAttr(next)}"`);
-        return `<a${newAttrs}>`;
-    });
+    pathname = normalizePath(pathname || '/');
+    for (const row of plan.rows) {
+        if (row.localeId !== localeId)
+            continue;
+        if (normalizePath(row.href) === pathname)
+            return `${row.href}${search}${hash}`;
+    }
+    return href;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vmz/core",
-  "version": "0.1.24",
+  "version": "0.1.25",
   "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.24",
-    "@vmz/vmz-win32-arm64": "0.1.24",
-    "@vmz/vmz-darwin-x64": "0.1.24",
-    "@vmz/vmz-darwin-arm64": "0.1.24",
-    "@vmz/vmz-linux-x64": "0.1.24",
-    "@vmz/vmz-linux-arm64": "0.1.24"
+    "@vmz/vmz-win32-x64": "0.1.25",
+    "@vmz/vmz-win32-arm64": "0.1.25",
+    "@vmz/vmz-darwin-x64": "0.1.25",
+    "@vmz/vmz-darwin-arm64": "0.1.25",
+    "@vmz/vmz-linux-x64": "0.1.25",
+    "@vmz/vmz-linux-arm64": "0.1.25"
   },
   "publishConfig": {
     "access": "public"