@vmz/core 0.1.20 → 0.1.22

package/dist/deployment-registry.d.ts

@@ -55,7 +55,7 @@ export declare function loadComponentEntries(distDir: any, opts?: {}): Promise<a
  */
 export declare function importAndRegisterComponentEntries(distDir: any, entries: any, registerComponents: any, opts?: {}): Promise<{}>;
 /**
- * Bootstrap component registry from deployment (all, closure, or directory fallback).
+ * Bootstrap component registry from deployment (all or closure — no directory fallback).
  * @param {string} distDir
  * @param {(map: Record<string, unknown>) => void} registerComponents
  * @param {{

package/dist/deployment-registry.js

@@ -4,7 +4,6 @@
  * Parse/validate and graph queries delegate to Rust vmz-artifacts via N-API.
  */
 import fs from 'node:fs';
-import { readdir } from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { requireNativeFn } from './native-addon.js';
@@ -131,35 +130,13 @@ export async function loadComponentEntries(distDir, opts = {}) {
             entries = entries.filter((e) => closure.has(e.chunkId));
         }
     }
-    else if (!strict) {
-        entries = await listComponentEntriesFromDirectory(distDir);
+    else if (strict) {
+        throw new Error(`vmz: missing vmz-deployment.json under ${distDir} (plan-only host)`);
     }
+    // No directory scan fallback — component closure comes from Deployment Plan only.
     entries = mergeExplicitComponentEntries(entries, opts.explicit);
     return dedupeComponentEntriesByTag(entries, { strict });
 }
-/**
- * @param {string} distDir
- * @returns {Promise<Array<{ chunkId: string, name: string, entry: string }>>}
- */
-async function listComponentEntriesFromDirectory(distDir) {
-    const folder = path.join(distDir, 'components');
-    /** @type {string[]} */
-    let files = [];
-    try {
-        files = await readdir(folder);
-    }
-    catch {
-        return [];
-    }
-    return files
-        .filter((name) => name.endsWith('.client.js'))
-        .map((f) => {
-        const name = f.replace(/\.client\.js$/, '');
-        const chunkId = `components/${name}`;
-        return { chunkId, name, entry: `components/${name}.client.js` };
-    })
-        .sort((a, b) => a.name.localeCompare(b.name));
-}
 /**
  * @param {string} distDir
  * @param {Array<{ chunkId: string, name: string, entry: string }>} entries
@@ -192,7 +169,7 @@ export async function importAndRegisterComponentEntries(distDir, entries, regist
     return map;
 }
 /**
- * Bootstrap component registry from deployment (all, closure, or directory fallback).
+ * Bootstrap component registry from deployment (all or closure — no directory fallback).
  * @param {string} distDir
  * @param {(map: Record<string, unknown>) => void} registerComponents
  * @param {{

package/dist/direct-host-box.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Direct host box model (`ui-direct-host-box`).
+ * Chip hosts opt into `display: contents`; block surfaces keep a real layout box.
+ */
+/** @type {ReadonlySet<string>} */
+export declare const INLINE_HOST_CONTENTS: Set<string>;
+/**
+ * @param {string} name
+ * @param {{ __vmzHostBox?: string } | null | undefined} Ctor
+ * @returns {'contents' | 'block'}
+ */
+export declare function resolveDirectHostBox(name: any, Ctor: any): any;
+/**
+ * Apply host box to a live DOM element (create / hydrate / resume).
+ * @param {HTMLElement} host
+ * @param {string} name
+ * @param {{ __vmzHostBox?: string } | null | undefined} Ctor
+ */
+export declare function applyDirectHostBox(host: any, name: any, Ctor: any): void;
+/**
+ * SSR attrs fragment for host box (only when contents).
+ * @param {string} name
+ * @param {{ __vmzHostBox?: string } | null | undefined} Ctor
+ * @returns {string | null}
+ */
+export declare function directHostBoxStyleAttr(name: any, Ctor: any): string;

package/dist/direct-host-box.js

@@ -0,0 +1,41 @@
+/**
+ * Direct host box model (`ui-direct-host-box`).
+ * Chip hosts opt into `display: contents`; block surfaces keep a real layout box.
+ */
+/** @type {ReadonlySet<string>} */
+export const INLINE_HOST_CONTENTS = new Set(['Button', 'Badge', 'Link', 'Tag', 'Icon']);
+/**
+ * @param {string} name
+ * @param {{ __vmzHostBox?: string } | null | undefined} Ctor
+ * @returns {'contents' | 'block'}
+ */
+export function resolveDirectHostBox(name, Ctor) {
+    const explicit = Ctor && typeof Ctor.__vmzHostBox === 'string' ? Ctor.__vmzHostBox : null;
+    if (explicit === 'contents' || explicit === 'block')
+        return explicit;
+    if (INLINE_HOST_CONTENTS.has(String(name || '')))
+        return 'contents';
+    return 'block';
+}
+/**
+ * Apply host box to a live DOM element (create / hydrate / resume).
+ * @param {HTMLElement} host
+ * @param {string} name
+ * @param {{ __vmzHostBox?: string } | null | undefined} Ctor
+ */
+export function applyDirectHostBox(host, name, Ctor) {
+    if (!host || !host.style)
+        return;
+    if (resolveDirectHostBox(name, Ctor) === 'contents') {
+        host.style.display = 'contents';
+    }
+}
+/**
+ * SSR attrs fragment for host box (only when contents).
+ * @param {string} name
+ * @param {{ __vmzHostBox?: string } | null | undefined} Ctor
+ * @returns {string | null}
+ */
+export function directHostBoxStyleAttr(name, Ctor) {
+    return resolveDirectHostBox(name, Ctor) === 'contents' ? 'display:contents' : null;
+}

package/dist/dom-core.d.ts

@@ -6,6 +6,8 @@
  * Mount and client patches run that same schedule (SSR/hydrate/resume in dom-ssr).
  * Field writes only run registered dep patches — never re-create structure.
  */
+export { applyDirectHostBox, INLINE_HOST_CONTENTS, resolveDirectHostBox } from './direct-host-box.js';
+export { createUnknownComponentElement, markUnknownComponentHost, serializeUnknownComponentNode, UNKNOWN_COMPONENT_ERROR, } from './unknown-component.js';
 /** @param {boolean} [on] */
 export declare function __vmzPrecisionEnable(on?: boolean): void;
 /** @param {boolean} [on] */

package/dist/dom-core.js

@@ -7,14 +7,12 @@
  * Mount and client patches run that same schedule (SSR/hydrate/resume in dom-ssr).
  * Field writes only run registered dep patches — never re-create structure.
  */
+import { applyDirectHostBox } from './direct-host-box.js';
+import { createUnknownComponentElement } from './unknown-component.js';
+export { applyDirectHostBox, INLINE_HOST_CONTENTS, resolveDirectHostBox } from './direct-host-box.js';
+export { createUnknownComponentElement, markUnknownComponentHost, serializeUnknownComponentNode, UNKNOWN_COMPONENT_ERROR, } from './unknown-component.js';
 /** @type {Record<string, new (props?: object) => any>} */
 const components = Object.create(null);
-/**
- * Inline chip hosts that opt into `display: contents` (`ui-direct-host-box`).
- * Block surfaces (DataTable / shells / overlays) must keep a real layout box.
- * @type {Set<string>}
- */
-const INLINE_HOST_CONTENTS = new Set(['Button', 'Badge', 'Link', 'Tag', 'Icon']);
 /**
  * Precision lab counters (test / MCP / benchmarks — not a user API).
  * Primary keys: BindingId (IR). `*ByDep` is transitional stable-string adapter.
@@ -452,22 +450,23 @@ export const directApi = {
             // resume: resume on schedule; EventEntry may lazy-load chunk via __vmzLoadComponent.
             scheduleClientOn(host, String(client), async () => {
                 const Ctor = await resolveComponent(name);
-                if (!Ctor)
-                    throw new Error(`vmz:dom unknown component <${name} />`);
+                if (!Ctor) {
+                    // Replace placeholder island with leaf error node (do not throw page).
+                    const err = createUnknownComponentElement(name, 'island');
+                    host.replaceWith(err);
+                    return;
+                }
                 await resume(Ctor, host, { props: resolved, state: {} });
             });
             return host;
         }
         const Ctor = components[name];
-        if (!Ctor)
-            throw new Error(`vmz:dom unknown component <${name} />`);
-        // Inline chips opt into no-box host (`ui-direct-host-box`). Block surfaces
-        // (tables/shells/overlays) keep a real box — default `contents` breaks
-        // hit-testing / slot hosts (DataTable select timed out in ui-automation).
-        const hostBox = Ctor.__vmzHostBox;
-        if (hostBox === 'contents' || (hostBox == null && INLINE_HOST_CONTENTS.has(String(name)))) {
-            host.style.display = 'contents';
+        if (!Ctor) {
+            return createUnknownComponentElement(name, 'client');
         }
+        // Inline chips → `display: contents` (`ui-direct-host-box`). Block surfaces
+        // keep a real box (DataTable select timed out when defaulting everything).
+        applyDirectHostBox(host, name, Ctor);
         const child = createInstance(Ctor, resolved);
         if (!(Ctor.__vmzDirect && typeof Ctor.__vmzCreate === 'function')) {
             throw new Error(`vmz:dom direct component <${name}> requires __vmzCreate (rebuild child with Direct)`);

package/dist/dom-ssr.js

@@ -3,7 +3,9 @@
  * VMZ DOM SSR / hydrate / resume — precise patches, no VDOM diff.
  * 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 { markUnknownComponentHost, serializeUnknownComponentNode } from './unknown-component.js';
 /** @type {Error | null} last linkedom resolve failure (for clear SSR errors) */
 let _ssrDocumentLastError = null;
 /**
@@ -742,8 +744,9 @@ const serializeApi = {
     },
     component(hostInst, name, props, client) {
         const Ctor = getRegisteredComponent(name);
-        if (!Ctor)
-            throw new Error(`vmz:dom unknown component <${name} />`);
+        if (!Ctor) {
+            return serializeUnknownComponentNode(name);
+        }
         /** @type {Record<string, any>} */
         const resolved = {};
         for (const [k, v] of Object.entries(props || {})) {
@@ -788,6 +791,9 @@ const serializeApi = {
                 'data-vmz-props': JSON.stringify(stripFns(resolved)),
                 'data-vmz-resume': JSON.stringify(resume),
             };
+            const boxStyle = directHostBoxStyleAttr(name, Ctor);
+            if (boxStyle)
+                attrs.style = boxStyle;
             if (isEventEntryStrategy(String(client))) {
                 attrs['data-vmz-entry'] = 'event';
             }
@@ -810,11 +816,9 @@ const serializeApi = {
                 const node = Ctor.__vmzCreate.call(child, serializeApi);
                 /** @type {Record<string, string>} */
                 const attrs = { 'data-vmz': name };
-                const hostBox = Ctor.__vmzHostBox;
-                if (hostBox === 'contents' ||
-                    (hostBox == null && (name === 'Button' || name === 'Badge' || name === 'Link' || name === 'Tag' || name === 'Icon'))) {
-                    attrs.style = 'display:contents';
-                }
+                const boxStyle = directHostBoxStyleAttr(name, Ctor);
+                if (boxStyle)
+                    attrs.style = boxStyle;
                 return {
                     __kind: 'el',
                     tag: 'div',
@@ -892,6 +896,8 @@ export async function resume(Component, container, slice = null) {
         destroy(container.__vmzInst);
         container.__vmzInst = null;
     }
+    const hostName = container.getAttribute('data-vmz') || container.getAttribute('data-vmz-island') || Component.name || '';
+    applyDirectHostBox(container, hostName, Component);
     const props = parsed.props || {};
     const inst = createInstance(Component, props);
     if (parsed.state)
@@ -935,7 +941,7 @@ export function resumeIslands(root = globalThis.document) {
         scheduleClientOn(el, strategy, async () => {
             const Ctor = await resolveComponent(name);
             if (!Ctor) {
-                console.error(`vmz:dom resume: unknown component ${name}`);
+                markUnknownComponentHost(el, name, 'resume');
                 return;
             }
             await resume(Ctor, el);
@@ -961,7 +967,7 @@ export function attachEventEntries(root = globalThis.document) {
         scheduleClientOn(el, strategy, async () => {
             const Ctor = await resolveComponent(name);
             if (!Ctor) {
-                console.error(`vmz:dom EventEntry: unknown component ${name}`);
+                markUnknownComponentHost(el, name, 'event-entry');
                 return;
             }
             await resume(Ctor, el);

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

@@ -1,6 +1,6 @@
 /**
- * Discover compiled client component modules from dist (deployment graph or components/).
- * Shared by serve-host SSR, static emit, and test hosts.
+ * Discover compiled client component modules from Deployment Plan only.
+ * Shared by serve-host SSR, static emit, and test hosts (plan-only host).
  */
 export { DEPLOYMENT_SCHEMA, readDeploymentDocument, componentEntriesFromDeployment, collectDependsOnClosure, dedupeComponentEntriesByTag, mergeExplicitComponentEntries, loadComponentEntries, importAndRegisterComponentEntries, bootstrapComponentRegistry, } from './deployment-registry.js';
 export { createRenderHost } from './render-host.js';

package/dist/list-client-components.js

@@ -1,10 +1,8 @@
 // @ts-nocheck
 /**
- * Discover compiled client component modules from dist (deployment graph or components/).
- * Shared by serve-host SSR, static emit, and test hosts.
+ * Discover compiled client component modules from Deployment Plan only.
+ * Shared by serve-host SSR, static emit, and test hosts (plan-only host).
  */
-import fs from 'node:fs';
-import { readdir } from 'node:fs/promises';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { componentEntriesFromDeployment, dedupeComponentEntriesByTag, mergeExplicitComponentEntries, readDeploymentDocument, } from './deployment-registry.js';
@@ -31,24 +29,9 @@ export async function listClientComponents(dir, opts = {}) {
         }));
     }
     if (strict) {
-        throw new Error(`vmz: missing vmz-deployment.json under ${dir} (strict deployment mode)`);
+        throw new Error(`vmz: missing vmz-deployment.json under ${dir} (plan-only host)`);
     }
-    const folder = path.join(dir, 'components');
-    /** @type {string[]} */
-    let files = [];
-    try {
-        files = await readdir(folder);
-    }
-    catch {
-        return [];
-    }
-    return files
-        .filter((name) => name.endsWith('.client.js'))
-        .map((f) => {
-        const name = f.replace(/\.client\.js$/, '');
-        return { name, entry: `components/${name}.client.js`, chunkId: `components/${name}` };
-    })
-        .sort((a, b) => a.name.localeCompare(b.name));
+    return [];
 }
 /**
  * Sync variant for callers that already use fs sync (legacy static-emit helpers).
@@ -72,24 +55,9 @@ export function listClientComponentsSync(dir, opts = {}) {
         }));
     }
     if (strict) {
-        throw new Error(`vmz: missing vmz-deployment.json under ${dir} (strict deployment mode)`);
-    }
-    const folder = path.join(dir, 'components');
-    /** @type {string[]} */
-    let files = [];
-    try {
-        files = fs.readdirSync(folder);
-    }
-    catch {
-        return [];
+        throw new Error(`vmz: missing vmz-deployment.json under ${dir} (plan-only host)`);
     }
-    return files
-        .filter((name) => name.endsWith('.client.js'))
-        .map((f) => {
-        const name = f.replace(/\.client\.js$/, '');
-        return { name, entry: `components/${name}.client.js`, chunkId: `components/${name}` };
-    })
-        .sort((a, b) => a.name.localeCompare(b.name));
+    return [];
 }
 /**
  * @param {Array<{ name: string, entry: string, chunkId?: string }>} entries

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

@@ -0,0 +1,19 @@
+/**
+ * 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).
+ */
+export type LocaleHrefArtifact = {
+    locales?: Array<{
+        id: string;
+    } | string>;
+    defaultLocale?: string;
+    routing?: {
+        strategy?: string;
+        defaultPrefix?: string;
+        defaultLocale?: 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 declare function localizeBodyLinks(html: string, localeId: string, artifact: LocaleHrefArtifact, escapeAttr?: (s: string) => string): string;

package/dist/localize-body-links.js

@@ -0,0 +1,89 @@
+/**
+ * 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).
+ */
+function normalizePath(pathname) {
+    let p = String(pathname || '/');
+    if (!p.startsWith('/'))
+        p = `/${p}`;
+    if (p.length > 1 && p.endsWith('/'))
+        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. */
+export function localizeSameAppHref(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) => (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}>`;
+    });
+}

package/dist/position-context.d.ts

@@ -0,0 +1,15 @@
+/**
+ * PositionContext backed by compiler OffsetIndex via N-API (`offsetIndexLineCol`).
+ * `@vmz/diagnostic` stays free of a native dependency — hosts wire this helper.
+ */
+export type LineCol = {
+    line: number;
+    column: number;
+};
+export type PositionContext = {
+    lineCol(offset: number): LineCol;
+};
+/**
+ * Build a diagnostic PositionContext for `sourceText` using the native OffsetIndex.
+ */
+export declare function createPositionContext(sourceText: string): PositionContext;

package/dist/position-context.js

@@ -0,0 +1,19 @@
+/**
+ * PositionContext backed by compiler OffsetIndex via N-API (`offsetIndexLineCol`).
+ * `@vmz/diagnostic` stays free of a native dependency — hosts wire this helper.
+ */
+import { requireNativeFn } from './native-addon.js';
+/**
+ * Build a diagnostic PositionContext for `sourceText` using the native OffsetIndex.
+ */
+export function createPositionContext(sourceText) {
+    const source = String(sourceText ?? '');
+    const lineColFn = requireNativeFn('offsetIndexLineCol');
+    return {
+        lineCol(offset) {
+            const off = Math.max(0, Number(offset) || 0);
+            const row = lineColFn(source, off >>> 0);
+            return { line: row.line, column: row.column };
+        },
+    };
+}

package/dist/route-layout-chain.d.ts

@@ -1,18 +1,18 @@
 /**
- * File-route layout chain: Application shell (outermost) + nested page Layout components.
+ * Layout chain from Deployment Plan only (plan-only host).
  */
 /** Chunk id for `src/Application.vmz` emit (`Application.client.js`). */
 export declare const APPLICATION_SHELL_CHUNK = "Application";
 /**
- * True when the compile output includes a root Application shell.
+ * True when Deployment Plan lists an Application shell unit.
  */
 export declare function hasApplicationShell(distDir: string): boolean;
 /**
- * Nearest page Layout.client.js walking up from the page chunk (outer to inner).
- * Does not include Application — use resolveRouteLayoutChain.
+ * Nested layout ids from Plan for a page (excludes Application).
+ * Prefer `resolveRouteLayoutChain` for SSR / hydrate.
  */
 export declare function resolveNestedLayoutChain(distDir: string, pageChunkId: string): string[];
 /**
- * Full SSR / hydrate layout chain: optional Application shell, then nested page layouts.
+ * Full SSR / hydrate layout chain from Deployment Plan `layoutChain`.
  */
 export declare function resolveRouteLayoutChain(distDir: string, pageChunkId: string): string[];

package/dist/route-layout-chain.js

@@ -1,41 +1,36 @@
 /**
- * File-route layout chain: Application shell (outermost) + nested page Layout components.
+ * Layout chain from Deployment Plan only (plan-only host).
  */
-import { existsSync } from 'node:fs';
-import path from 'node:path';
+import { readDeploymentDocument } from './deployment-registry.js';
 /** Chunk id for `src/Application.vmz` emit (`Application.client.js`). */
 export const APPLICATION_SHELL_CHUNK = 'Application';
 /**
- * True when the compile output includes a root Application shell.
+ * True when Deployment Plan lists an Application shell unit.
  */
 export function hasApplicationShell(distDir) {
-    return existsSync(path.join(distDir, `${APPLICATION_SHELL_CHUNK}.client.js`));
+    const deployment = readDeploymentDocument(distDir, { strict: false });
+    const units = Array.isArray(deployment?.units) ? deployment.units : [];
+    return units.some((u) => String(u?.chunkId || '') === APPLICATION_SHELL_CHUNK);
 }
 /**
- * Nearest page Layout.client.js walking up from the page chunk (outer to inner).
- * Does not include Application — use resolveRouteLayoutChain.
+ * Nested layout ids from Plan for a page (excludes Application).
+ * Prefer `resolveRouteLayoutChain` for SSR / hydrate.
  */
 export function resolveNestedLayoutChain(distDir, pageChunkId) {
-    const rel = pageChunkId.replace(/^pages\//, '');
-    const parts = rel.split('/').filter(Boolean);
-    parts.pop();
-    const chain = [];
-    for (let i = parts.length; i >= 0; i--) {
-        const dirParts = parts.slice(0, i);
-        const layoutChunk = ['pages', ...dirParts, 'Layout'].join('/');
-        if (existsSync(path.join(distDir, `${layoutChunk}.client.js`))) {
-            chain.unshift(layoutChunk);
-        }
-    }
-    return chain;
+    return resolveRouteLayoutChain(distDir, pageChunkId).filter((id) => id !== APPLICATION_SHELL_CHUNK);
 }
 /**
- * Full SSR / hydrate layout chain: optional Application shell, then nested page layouts.
+ * Full SSR / hydrate layout chain from Deployment Plan `layoutChain`.
  */
 export function resolveRouteLayoutChain(distDir, pageChunkId) {
-    const chain = resolveNestedLayoutChain(distDir, pageChunkId);
-    if (hasApplicationShell(distDir)) {
-        chain.unshift(APPLICATION_SHELL_CHUNK);
+    const deployment = readDeploymentDocument(distDir, { strict: true });
+    const units = Array.isArray(deployment?.units) ? deployment.units : [];
+    const unit = units.find((u) => String(u?.chunkId || '').replace(/\\/g, '/') === pageChunkId);
+    if (!unit) {
+        throw new Error(`resolveRouteLayoutChain: no deployment unit for ${pageChunkId} (plan-only host)`);
+    }
+    if (!Array.isArray(unit.layoutChain)) {
+        throw new Error(`resolveRouteLayoutChain: page unit ${pageChunkId} missing layoutChain (plan-only host)`);
     }
-    return chain;
+    return unit.layoutChain.map((id) => String(id));
 }

package/dist/serve-host.mjs

@@ -17,11 +17,12 @@
  * dist so soft reload does not keep a stale `lib/*.js` ESM cache entry.
  */
 import { existsSync, readFileSync } from 'node:fs';
-import { readdir, readFile, writeFile } from 'node:fs/promises';
+import { readFile, writeFile } from 'node:fs/promises';
 import http from 'node:http';
 import { createRequire, registerHooks } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
+import { localizeBodyLinks } from './localize-body-links.js';
 import { createRenderHost } from './render-host.js';
 import { listClientComponents } from './list-client-components.js';
 import { loadNativeAddon } from './native-addon.js';
@@ -141,7 +142,7 @@ let reloadToken = Date.now();
 let ssrRenderHost = null;
 /** @type {string | null} Correlatable build id from vmz dev (Living §12.8). */
 let lastDevBuildId = null;
-/** @type {Array<{ chunkId: string, pageRel: string, segs: ReturnType<typeof parseChunkSegments> }>} */
+/** @type {Array<{ chunkId: string, pageRel: string, segs: ReturnType<typeof parsePathPattern> }>} */
 let pageCatalog = [];
 /** @type {Map<string, any>} */
 const pageCtors = new Map();
@@ -606,7 +607,7 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
         }
         // Locale discipline: same-app Links retain current LocaleId (realization authority).
         if (localeArtifact && localeId) {
-            bodyHtml = localizeBodyLinksInHost(bodyHtml, localeId, localeArtifact);
+            bodyHtml = localizeBodyLinks(bodyHtml, localeId, localeArtifact);
         }
     }
     finally {
@@ -799,9 +800,7 @@ async function softReload(opts = {}) {
             cacheBust: nextToken,
         });
         const nextCatalog = await listPageClientFiles(distDir);
-        if (!nextCatalog.length) {
-            throw new Error(`vmz serve: no pages/**/*.client.js in ${distDir}`);
-        }
+        // empty catalog throws inside listPageClientFiles
         /** @type {Map<string, any>} */
         const nextCtors = new Map();
         if (!islandHmr) {
@@ -1053,79 +1052,6 @@ function resolveLocalePath(pathname, cookieHeader) {
         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
@@ -1152,50 +1078,22 @@ async function loadPageCtor(chunkId) {
     return mod.default;
 }
 /**
- * Discover compiled page modules. Prefer Route Graph `pathPattern` from
- * `vmz-deployment.json`; fall back to walking `pages/**` (file-route only).
+ * Discover compiled page modules from Route Graph `pathPattern` in
+ * `vmz-deployment.json` only (plan-only host — no `pages/**` walk).
  * @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 = [];
-    async function walk(abs, relParts) {
-        let ents;
-        try {
-            ents = await readdir(abs, { withFileTypes: true });
-        }
-        catch {
-            return;
-        }
-        for (const e of ents) {
-            if (e.isDirectory()) {
-                await walk(path.join(abs, e.name), [...relParts, e.name]);
-            }
-            else if (e.isFile() && e.name.endsWith('.client.js')) {
-                const stem = e.name.replace(/\.client\.js$/, '');
-                if (isRouteBoundaryStem(stem))
-                    continue;
-                const chunkId = ['pages', ...relParts, stem].join('/');
-                out.push({
-                    chunkId,
-                    pageRel: `${chunkId}.client.js`,
-                    segs: parseChunkSegments(chunkId),
-                });
-            }
-        }
+    if (!fromDep.length) {
+        throw new Error(`vmz serve: no page units with pathPattern in ${path.join(dir, 'vmz-deployment.json')} (plan-only host)`);
     }
-    await walk(root, []);
-    return out;
+    return fromDep;
 }
 /**
  * @param {string} dir
  */
 async function listPagesFromDeployment(dir) {
-    /** @type {Array<{ chunkId: string, pageRel: string, segs: ReturnType<typeof parseChunkSegments> }>} */
+    /** @type {Array<{ chunkId: string, pageRel: string, segs: ReturnType<typeof parsePathPattern> }>} */
     const out = [];
     try {
         const raw = await readFile(path.join(dir, 'vmz-deployment.json'), 'utf8');
@@ -1209,40 +1107,25 @@ async function listPagesFromDeployment(dir) {
             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();
+            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, '/');
             out.push({
                 chunkId,
                 pageRel,
-                segs: pattern ? parsePathPattern(pattern) : parseChunkSegments(chunkId),
+                segs: parsePathPattern(pattern),
             });
         }
     }
-    catch {
+    catch (err) {
+        if (err && typeof err.message === 'string' && err.message.includes('plan-only host'))
+            throw err;
         return [];
     }
     return out;
 }
-/**
- * File-route segments from chunk id (`pages/Install` → `/install`).
- * Skips URL-invisible `(group)` dirs; boundary stems never reach here.
- * @param {string} chunkId
- */
-function parseChunkSegments(chunkId) {
-    const rel = chunkId.replace(/^pages\//, '');
-    const parts = rel.split('/').filter(Boolean);
-    /** @type {Array<{ kind: 'static' | 'param' | 'catch', value?: string, name?: string }>} */
-    const segs = [];
-    for (let i = 0; i < parts.length; i++) {
-        const p = parts[i];
-        if (isRouteGroupDir(p))
-            continue;
-        if (p === 'index' && i === parts.length - 1)
-            continue;
-        segs.push(parsePathSegment(p));
-    }
-    return segs;
-}
 /**
  * Browser HTTP pattern (`/` / `/home` / `/users/:id` / `/blog/[...slug]`).
  * @param {string} pattern
@@ -1306,7 +1189,7 @@ function matchFileRoute(pathname, catalog) {
     return best;
 }
 /**
- * @param {ReturnType<typeof parseChunkSegments>} segs
+ * @param {ReturnType<typeof parsePathPattern>} segs
  * @param {string} pathname
  * @returns {Record<string, string>}
  */
@@ -1335,7 +1218,7 @@ function extractRouteParams(segs, pathname) {
     return params;
 }
 /**
- * @param {ReturnType<typeof parseChunkSegments>} segs
+ * @param {ReturnType<typeof parsePathPattern>} segs
  * @param {string[]} pathParts
  * @returns {number | null}
  */

package/dist/unknown-component.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Unknown Direct component resilience (`ssr-unknown-component-error-node`).
+ * Leaf failure → subtree error node; do not throw out of document SSR.
+ */
+/** @type {string} */
+export declare const UNKNOWN_COMPONENT_ERROR = "unknown-component";
+/**
+ * Append a leaf diagnostic for tooling (does not replace the error node).
+ * @param {string} name
+ * @param {string} [via]
+ */
+export declare function noteUnknownComponent(name: any, via?: string): void;
+/**
+ * SSR serialize-tree error node (keeps document HTTP 200).
+ * @param {string} name
+ */
+export declare function serializeUnknownComponentNode(name: any): {
+    __kind: string;
+    tag: string;
+    attrs: {
+        'data-vmz-error': string;
+        'data-vmz-component': string;
+    };
+    children: any[];
+    appendChild(c: any): void;
+};
+/**
+ * Live DOM error host (client create / schedule).
+ * @param {string} name
+ * @param {string} [via]
+ * @returns {HTMLElement}
+ */
+export declare function createUnknownComponentElement(name: any, via?: string): HTMLDivElement;
+/**
+ * Mark an existing island host as unknown (resume / EventEntry).
+ * @param {HTMLElement} el
+ * @param {string} name
+ * @param {string} [via]
+ */
+export declare function markUnknownComponentHost(el: any, name: any, via?: string): void;

package/dist/unknown-component.js

@@ -0,0 +1,112 @@
+/**
+ * Unknown Direct component resilience (`ssr-unknown-component-error-node`).
+ * Leaf failure → subtree error node; do not throw out of document SSR.
+ */
+/** @type {string} */
+export const UNKNOWN_COMPONENT_ERROR = 'unknown-component';
+/**
+ * @returns {boolean}
+ */
+function isDevSurface() {
+    try {
+        if (typeof process !== 'undefined' && process.env) {
+            if (process.env.VMZ_DEV === '1' || process.env.VMZ_DEV === 'true')
+                return true;
+            if (process.env.NODE_ENV === 'development')
+                return true;
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return false;
+}
+/**
+ * Append a leaf diagnostic for tooling (does not replace the error node).
+ * @param {string} name
+ * @param {string} [via]
+ */
+export function noteUnknownComponent(name, via = 'ssr') {
+    const detail = { kind: UNKNOWN_COMPONENT_ERROR, component: String(name || ''), via };
+    try {
+        if (typeof console !== 'undefined' && typeof console.error === 'function') {
+            console.error(`vmz:dom unknown component <${name} /> (${via})`);
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    try {
+        const g = typeof globalThis !== 'undefined' ? globalThis : null;
+        if (!g)
+            return;
+        if (!Array.isArray(g.__VMZ_COMPONENT_ERRORS__)) {
+            g.__VMZ_COMPONENT_ERRORS__ = [];
+        }
+        /** @type {unknown[]} */
+        const bag = g.__VMZ_COMPONENT_ERRORS__;
+        bag.push(detail);
+    }
+    catch {
+        /* ignore */
+    }
+}
+/**
+ * SSR serialize-tree error node (keeps document HTTP 200).
+ * @param {string} name
+ */
+export function serializeUnknownComponentNode(name) {
+    noteUnknownComponent(name, 'ssr');
+    /** @type {Record<string, string>} */
+    const attrs = {
+        'data-vmz-error': UNKNOWN_COMPONENT_ERROR,
+        'data-vmz-component': String(name || ''),
+    };
+    /** @type {any[]} */
+    const children = [];
+    if (isDevSurface()) {
+        children.push({
+            __kind: 'text',
+            value: `Unknown component <${name} />`,
+        });
+    }
+    return {
+        __kind: 'el',
+        tag: 'div',
+        attrs,
+        children,
+        appendChild(c) {
+            if (c != null)
+                this.children.push(c);
+        },
+    };
+}
+/**
+ * Live DOM error host (client create / schedule).
+ * @param {string} name
+ * @param {string} [via]
+ * @returns {HTMLElement}
+ */
+export function createUnknownComponentElement(name, via = 'client') {
+    noteUnknownComponent(name, via);
+    const host = document.createElement('div');
+    host.setAttribute('data-vmz-error', UNKNOWN_COMPONENT_ERROR);
+    host.setAttribute('data-vmz-component', String(name || ''));
+    if (isDevSurface()) {
+        host.textContent = `Unknown component <${name} />`;
+    }
+    return host;
+}
+/**
+ * Mark an existing island host as unknown (resume / EventEntry).
+ * @param {HTMLElement} el
+ * @param {string} name
+ * @param {string} [via]
+ */
+export function markUnknownComponentHost(el, name, via = 'resume') {
+    if (!el)
+        return;
+    noteUnknownComponent(name, via);
+    el.setAttribute('data-vmz-error', UNKNOWN_COMPONENT_ERROR);
+    el.setAttribute('data-vmz-component', String(name || ''));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vmz/core",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "type": "module",
   "description": "VMZ production runtime core — DOM / SSR / HTTP / WriteBarrier (no compiler)",
   "exports": {
@@ -39,6 +39,14 @@
     "./route-layout-chain": {
       "types": "./dist/route-layout-chain.d.ts",
       "default": "./dist/route-layout-chain.js"
+    },
+    "./localize-body-links": {
+      "types": "./dist/localize-body-links.d.ts",
+      "default": "./dist/localize-body-links.js"
+    },
+    "./position-context": {
+      "types": "./dist/position-context.d.ts",
+      "default": "./dist/position-context.js"
     }
   },
   "files": [
@@ -58,12 +66,12 @@
     "linkedom": "^0.18.13"
   },
   "optionalDependencies": {
-    "@vmz/vmz-win32-x64": "0.1.20",
-    "@vmz/vmz-win32-arm64": "0.1.20",
-    "@vmz/vmz-darwin-x64": "0.1.20",
-    "@vmz/vmz-darwin-arm64": "0.1.20",
-    "@vmz/vmz-linux-x64": "0.1.20",
-    "@vmz/vmz-linux-arm64": "0.1.20"
+    "@vmz/vmz-win32-x64": "0.1.22",
+    "@vmz/vmz-win32-arm64": "0.1.22",
+    "@vmz/vmz-darwin-x64": "0.1.22",
+    "@vmz/vmz-darwin-arm64": "0.1.22",
+    "@vmz/vmz-linux-x64": "0.1.22",
+    "@vmz/vmz-linux-arm64": "0.1.22"
   },
   "publishConfig": {
     "access": "public"