@vmz/vmz 0.1.20 → 0.1.22

package/dist/dev-session.js

@@ -10,7 +10,7 @@
  * 3. Soft reload failure → **auto-respawn** serve-host (fresh ESM graph), not "keep broken host".
  */
 import { spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { buildIntegratedDocuments, projectHasDocuments } from './document-integrate.js';
 import { createWorkspace, resolveNativePath } from './index.js';
@@ -18,6 +18,8 @@ import { emitLocaleRuntimeModules, localeHasErrors } from './locale-check.js';
 import { log } from './log.js';
 import { coalesceRootBurst, collectDevWatchRoots, classifyWatchRoot, isDependencyPath, mergeDirtySets } from './dev-watch-roots.js';
 import { diffFingerprints, fileFingerprintMap } from './watch-diff.js';
+/** Track serve-host so a failed/killed launcher cannot leave an orphan port. */
+const DEV_HOST_PID = '.vmz-dev-host.pid';
 export function createDevSession(options) {
     const project = options.project;
     const outDir = options.outDir;
@@ -141,11 +143,29 @@ export function createDevSession(options) {
         if (!existsSync(src)) {
             throw new Error(`vmz dev: missing src/ under ${project}`);
         }
+        // Same as `vmz build`: materialize plugin sources (e.g. `<Shiki>`) before compile.
+        // Soft rebuilds reuse the workspace; config/plugin changes still need a process restart
+        // until `vmz.config.*` is watched.
+        {
+            const { loadVmzConfig, applyPlugins } = await import('./plugin-host.js');
+            const { plugins, engines } = await loadVmzConfig(project);
+            if (plugins.length) {
+                await applyPlugins(ws, plugins, { project, outDir, engines });
+            }
+        }
         log.info('initial build (N-API workspace, full)…');
         const initial = rebuild();
         if (!printReport(initial, 'build')) {
             throw new Error('vmz dev: initial build failed');
         }
+        // `vmz build` assemble copies `public/**` → outDir; soft `ws.build()` does not.
+        // Without this, marketing images and other opaque assets 404 under `vmz dev`.
+        {
+            const { emitPublicStaticAssets } = await import('./public-static-assets.js');
+            emitPublicStaticAssets(outDir, { projectRoot: project });
+        }
+        // Reclaim orphan serve-host from a previous crashed launcher (same outDir).
+        reclaimStaleDevHost(outDir);
         if (projectHasDocuments(project)) {
             const docs = await buildIntegratedDocuments({ projectRoot: project, outDir });
             if (!docs.ok) {
@@ -495,6 +515,7 @@ export function createDevSession(options) {
         stopped = true;
         killChild(child);
         child = null;
+        clearDevHostPid(outDir, null);
         try {
             ws.dispose();
         }
@@ -523,7 +544,7 @@ export function listWatchedFiles(srcDir) {
 function defaultSpawnHost(opts) {
     const hostJs = path.join(opts.outDir, 'vmz-serve-host.mjs');
     const node = process.env.VMZ_NODE || process.execPath;
-    return spawn(node, [hostJs], {
+    const child = spawn(node, [hostJs], {
         cwd: opts.project,
         env: {
             ...process.env,
@@ -535,7 +556,13 @@ function defaultSpawnHost(opts) {
             VMZ_NATIVE_NODE: resolveNativePath(),
         },
         stdio: ['ignore', 'inherit', 'inherit'],
+        // Keep child in the same process group so launcher exit can reclaim it.
+        detached: false,
+        windowsHide: true,
     });
+    writeDevHostPid(opts.outDir, child.pid);
+    child.once('exit', () => clearDevHostPid(opts.outDir, child.pid));
+    return child;
 }
 /**
  * @param {string} host
@@ -559,12 +586,103 @@ async function defaultSoftReload(host, port, payload = {}) {
 function killChild(child) {
     if (!child || child.killed)
         return;
+    const pid = child.pid;
+    try {
+        if (process.platform === 'win32' && pid) {
+            // Tree-kill so orphaned grandchildren (if any) do not keep the port.
+            spawn('taskkill', ['/pid', String(pid), '/T', '/F'], {
+                stdio: 'ignore',
+                windowsHide: true,
+            });
+        }
+        else {
+            child.kill('SIGTERM');
+        }
+    }
+    catch {
+        try {
+            child.kill();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+function devHostPidPath(outDir) {
+    return path.join(outDir, DEV_HOST_PID);
+}
+function writeDevHostPid(outDir, pid) {
+    if (!outDir || !pid)
+        return;
+    try {
+        writeFileSync(devHostPidPath(outDir), `${pid}\n`, 'utf8');
+    }
+    catch {
+        /* ignore */
+    }
+}
+function clearDevHostPid(outDir, pid) {
+    if (!outDir)
+        return;
+    try {
+        const p = devHostPidPath(outDir);
+        if (!existsSync(p))
+            return;
+        if (pid != null) {
+            const cur = Number(readFileSync(p, 'utf8').trim());
+            if (Number.isFinite(cur) && cur !== pid)
+                return;
+        }
+        unlinkSync(p);
+    }
+    catch {
+        /* ignore */
+    }
+}
+/** Kill leftover serve-host recorded for this outDir (previous crashed `vmz dev`). */
+function reclaimStaleDevHost(outDir) {
+    const p = devHostPidPath(outDir);
+    if (!existsSync(p))
+        return;
+    let pid = 0;
     try {
-        child.kill();
+        pid = Number(readFileSync(p, 'utf8').trim());
+    }
+    catch {
+        clearDevHostPid(outDir, null);
+        return;
+    }
+    if (!Number.isFinite(pid) || pid <= 0) {
+        clearDevHostPid(outDir, null);
+        return;
+    }
+    if (pid === process.pid) {
+        clearDevHostPid(outDir, null);
+        return;
+    }
+    try {
+        process.kill(pid, 0);
+    }
+    catch {
+        clearDevHostPid(outDir, null);
+        return;
+    }
+    log.warn(`reclaiming stale serve-host pid=${pid} (prior vmz dev left an orphan)`);
+    try {
+        if (process.platform === 'win32') {
+            spawn('taskkill', ['/pid', String(pid), '/T', '/F'], {
+                stdio: 'ignore',
+                windowsHide: true,
+            });
+        }
+        else {
+            process.kill(pid, 'SIGTERM');
+        }
     }
     catch {
         /* ignore */
     }
+    clearDevHostPid(outDir, null);
 }
 function sleep(ms) {
     return new Promise((r) => setTimeout(r, ms));

package/dist/document-integrate.js

@@ -8,6 +8,7 @@ import { buildDocuments } from './document-build.js';
 import { resolveDocumentsRoot } from './document-check.js';
 import { pageHtmlRel } from './document-enrich.js';
 import { loadLocalesRouting } from './document-routing-config.js';
+import { ensureLocaleImportsRewritten } from './locale-check.js';
 import { log } from './log.js';
 import { requireNativeAddon } from './native-addon.js';
 export function projectHasDocuments(projectRoot) {
@@ -22,6 +23,13 @@ export async function buildIntegratedDocuments(opts) {
         return { ok: true, skipped: true };
     }
     try {
+        // Node dynamic import of compiled chrome forbids bare `#locales/*`
+        // (no package.json imports). Rewrite must be complete before mount.
+        const locales = ensureLocaleImportsRewritten(outDir);
+        if (!locales.ok) {
+            log.error(locales.error || 'locale import rewrite incomplete');
+            return { ok: false, error: locales.error || 'locale rewrite', pages: 0 };
+        }
         const result = await buildDocuments({
             projectRoot,
             outDir,

package/dist/index.js

@@ -127,6 +127,7 @@ export const SERVE_HOST_RUNTIME_FILES = [
     ['deployment-registry.js', 'deployment-registry.js'],
     ['render-host.js', 'render-host.js'],
     ['route-layout-chain.js', 'route-layout-chain.js'],
+    ['localize-body-links.js', 'localize-body-links.js'],
 ];
 /** Copy serve-host + registry bootstrap modules from `@vmz/core` into app outDir. */
 export function materializeServeHostRuntime(outDir, coreDist = resolveCoreRuntimeDist()) {

package/dist/locale-check.d.ts

@@ -80,12 +80,25 @@ export declare function emitLocaleTypedModules(report: ReturnType<typeof checkLo
  *
  * Variant pick reads `html[data-locale]` (else defaultLocale). Thin bridge until
  * host LocaleTransition reloads locale-scoped chunks (I2/I4).
+ *
+ * Contract: after this returns `ok`, `distDir` must not contain bare `#locales/`
+ * import specifiers (document SSR / Node import would otherwise require a fake
+ * `package.json#imports` map).
  */
 export declare function emitLocaleRuntimeModules(projectRoot: string, distDir: string): {
     ok: boolean;
     written: string[];
     diagnostics: LocaleDiagnostic[];
 };
+/**
+ * Rewrite `#locales/*` → relative `locales/*.js` and assert none remain.
+ * Call before document SSR (`createRenderHost`) or any Node import of app dist.
+ */
+export declare function ensureLocaleImportsRewritten(distDir: string): {
+    ok: boolean;
+    rewritten: number;
+    error?: string;
+};
 /** MessageId rename plan — WorkspaceEdit-shaped, no parallel rename IR. */
 export declare function planLocaleRename(report: ReturnType<typeof checkLocales>, fromId: string, toId: string): {
     schema: string;

package/dist/locale-check.js

@@ -589,6 +589,10 @@ export function emitLocaleTypedModules(report, outDir) {
  *
  * Variant pick reads `html[data-locale]` (else defaultLocale). Thin bridge until
  * host LocaleTransition reloads locale-scoped chunks (I2/I4).
+ *
+ * Contract: after this returns `ok`, `distDir` must not contain bare `#locales/`
+ * import specifiers (document SSR / Node import would otherwise require a fake
+ * `package.json#imports` map).
  */
 export function emitLocaleRuntimeModules(projectRoot, distDir) {
     const report = checkLocales({ projectRoot, checkUnused: false });
@@ -597,6 +601,21 @@ export function emitLocaleRuntimeModules(projectRoot, distDir) {
     }
     // Missing locales.json5 is warning-only for now — surface diagnostics, skip emit.
     if (!report.manifest) {
+        const leftover = findBareLocaleImports(distDir);
+        if (leftover.length) {
+            return {
+                ok: false,
+                written: [],
+                diagnostics: [
+                    ...(report.diagnostics || []),
+                    {
+                        severity: 'error',
+                        code: 'locale::dist_bare_import',
+                        message: `dist still has #locales/* imports but locales manifest is missing: ${leftover.slice(0, 4).join(', ')}`,
+                    },
+                ],
+            };
+        }
         return { ok: true, written: [], diagnostics: report.diagnostics || [] };
     }
     const defaultLocale = report.manifest.defaultLocale || 'zh-hans';
@@ -630,12 +649,55 @@ export function emitLocaleRuntimeModules(projectRoot, distDir) {
         fs.writeFileSync(file, code, 'utf8');
         written.push(file);
     }
-    rewriteLocaleImportsInDist(distDir);
+    const ensured = ensureLocaleImportsRewritten(distDir);
+    if (!ensured.ok) {
+        return {
+            ok: false,
+            written,
+            diagnostics: [
+                ...(report.diagnostics || []),
+                {
+                    severity: 'error',
+                    code: 'locale::dist_bare_import',
+                    message: ensured.error || 'bare #locales/* imports remain in dist',
+                },
+            ],
+        };
+    }
     return { ok: true, written, diagnostics: report.diagnostics || [] };
 }
+/**
+ * Rewrite `#locales/*` → relative `locales/*.js` and assert none remain.
+ * Call before document SSR (`createRenderHost`) or any Node import of app dist.
+ */
+export function ensureLocaleImportsRewritten(distDir) {
+    const rewritten = rewriteLocaleImportsInDist(distDir);
+    const leftover = findBareLocaleImports(distDir);
+    if (leftover.length) {
+        return {
+            ok: false,
+            rewritten,
+            error: `bare #locales/* remain after rewrite: ${leftover.slice(0, 6).join(', ')}`,
+        };
+    }
+    return { ok: true, rewritten };
+}
+/** True import / dynamic-import of `#locales/…` (not comments mentioning the prefix). */
+const BARE_LOCALE_IMPORT_RE = /(?:from\s*|import\s*\()\s*['"`]#locales\//;
+function findBareLocaleImports(distDir) {
+    const hits = [];
+    walkDistJs(distDir, (file) => {
+        const text = fs.readFileSync(file, 'utf8');
+        if (!BARE_LOCALE_IMPORT_RE.test(text))
+            return;
+        hits.push(path.relative(distDir, file).replace(/\\/g, '/'));
+    });
+    return hits;
+}
 function rewriteLocaleImportsInDist(distDir) {
     const files = [];
     walkDistJs(distDir, (file) => files.push(file));
+    let rewritten = 0;
     for (const file of files) {
         const text = fs.readFileSync(file, 'utf8');
         if (!text.includes('#locales/'))
@@ -649,9 +711,12 @@ function rewriteLocaleImportsInDist(distDir) {
                 rel = `./${rel}`;
             return `from ${quote}${rel}${quote}`;
         });
-        if (next !== text)
+        if (next !== text) {
             fs.writeFileSync(file, next, 'utf8');
+            rewritten += 1;
+        }
     }
+    return rewritten;
 }
 function walkDistJs(dir, fn) {
     if (!fs.existsSync(dir))
@@ -659,7 +724,8 @@ function walkDistJs(dir, fn) {
     for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
         const full = path.join(dir, ent.name);
         if (ent.isDirectory()) {
-            if (ent.name === 'node_modules')
+            // Skip package trees and pack vendor — only app emit must clear `#locales/*`.
+            if (ent.name === 'node_modules' || ent.name === 'vendor')
                 continue;
             walkDistJs(full, fn);
         }

package/dist/locale-router.d.ts

@@ -130,17 +130,9 @@ export declare function parseLocaleFromPath(pathname: string, supportedLocales:
     localeId: string;
     restPath: string;
 };
-export interface LocaleHrefArtifact {
-    locales?: Array<{
-        id: string;
-    } | string>;
-    defaultLocale?: string;
-    routing?: LocaleRoutingOpts;
-}
-/** 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;
+export type { LocaleHrefArtifact } from '@vmz/core/localize-body-links';
+/** Rewrite a same-app href — single implementation in `@vmz/core/localize-body-links`. */
+export { localizeBodyLinks, localizeSameAppHref } from '@vmz/core/localize-body-links';
 /** Plan redirect / negotiation for an incoming URL (omit-prefix aware). */
 export declare function planLocalePathNavigation(input: {
     pathname: string;

package/dist/locale-router.js

@@ -228,58 +228,8 @@ export function parseLocaleFromPath(pathname, supportedLocales) {
     }
     return { localeId: null, restPath: normalizePath(pathname) };
 }
-/** 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}>`;
-    });
-}
+/** Rewrite a same-app href — single implementation in `@vmz/core/localize-body-links`. */
+export { localizeBodyLinks, localizeSameAppHref } from '@vmz/core/localize-body-links';
 /** Plan redirect / negotiation for an incoming URL (omit-prefix aware). */
 export function planLocalePathNavigation(input) {
     const routing = {

package/dist/log.js

@@ -22,14 +22,16 @@ export const log = {
     },
     diagnostic(d) {
         const severity = d.severity === 'warning' || d.severity === 'advice' || d.severity === 'error' ? d.severity : 'error';
-        const code = d.code && String(d.code).length ? String(d.code) : 'diag.message';
+        // Only invent transitional `diag.message` when wire has no code; never remap a real code.
+        const hasCode = Boolean(d.code && String(d.code).length);
+        const code = hasCode ? String(d.code) : 'diag.message';
         const locale = resolveVmzLocale();
         const catalog = loadCliCatalog(locale);
         const line = formatDiagnostic({
             path: d.path || '',
             severity,
             code,
-            args: d.args || (d.message ? { message: String(d.message) } : undefined),
+            args: d.args ?? (!hasCode && d.message ? { message: String(d.message) } : undefined),
             message: d.message,
             span: d.span,
         }, {

package/dist/pack.js

@@ -20,7 +20,7 @@ export const PACK_MANIFEST_SCHEMA = 'vmz.pack.manifest.v0';
 export function ensureRuntimeCompanions(outDir, coreDist) {
     if (!coreDist)
         return [];
-    const names = ['dom-core.js', 'dom-ssr.js', 'dom.client.js'];
+    const names = ['dom-core.js', 'dom-ssr.js', 'dom.client.js', 'direct-host-box.js', 'unknown-component.js'];
     const copied = [];
     for (const name of names) {
         const src = path.join(coreDist, name);

package/dist/plugin-host.js

@@ -274,13 +274,13 @@ function sourceItem(id, path, content) {
  * @param {string[]} engines
  */
 function buildMathFacade(defaultEngine, engines) {
-    const defaultLit = JSON.stringify(defaultEngine);
+    const defaultLit = jsSingleQuoted(defaultEngine);
     const branches = engines
         .map((eng, i) => {
         const tag = engineToTag(eng);
-        const kw = i === 0 ? 'if' : 'else-if';
-        const engLit = JSON.stringify(eng);
-        return `  <${tag} ${kw}={(engine || ${defaultLit}) === ${engLit}} tex={tex} display={display} />`;
+        const kw = i === 0 ? 'v-if' : 'v-else-if';
+        const engLit = jsSingleQuoted(eng);
+        return `  <${tag} ${kw}="(engine || ${defaultLit}) === ${engLit}" :tex="tex" :display="display" />`;
     })
         .join('\n');
     return `<template>
@@ -301,13 +301,13 @@ export default class Math {
  * @param {string[]} engines
  */
 function buildCodeFacade(defaultEngine, engines) {
-    const defaultLit = JSON.stringify(defaultEngine);
+    const defaultLit = jsSingleQuoted(defaultEngine);
     const branches = engines
         .map((eng, i) => {
         const tag = engineToTag(eng);
-        const kw = i === 0 ? 'if' : 'else-if';
-        const engLit = JSON.stringify(eng);
-        return `  <${tag} ${kw}={(engine || ${defaultLit}) === ${engLit}} code={code} lang={lang} theme={theme} />`;
+        const kw = i === 0 ? 'v-if' : 'v-else-if';
+        const engLit = jsSingleQuoted(eng);
+        return `  <${tag} ${kw}="(engine || ${defaultLit}) === ${engLit}" :code="code" :lang="lang" :theme="theme" />`;
     })
         .join('\n');
     return `<template>
@@ -329,13 +329,13 @@ export default class Code {
  * @param {string[]} engines
  */
 function buildMarkdownFacade(defaultEngine, engines) {
-    const defaultLit = JSON.stringify(defaultEngine);
+    const defaultLit = jsSingleQuoted(defaultEngine);
     const branches = engines
         .map((eng, i) => {
         const tag = engineToTag(eng);
-        const kw = i === 0 ? 'if' : 'else-if';
-        const engLit = JSON.stringify(eng);
-        return `  <${tag} ${kw}={(engine || ${defaultLit}) === ${engLit}} source={source} />`;
+        const kw = i === 0 ? 'v-if' : 'v-else-if';
+        const engLit = jsSingleQuoted(eng);
+        return `  <${tag} ${kw}="(engine || ${defaultLit}) === ${engLit}" :source="source" />`;
     })
         .join('\n');
     return `<template>
@@ -350,6 +350,10 @@ export default class Markdown {
 </script>
 `;
 }
+/** Embed a JS string literal inside a double-quoted Vue attribute. */
+function jsSingleQuoted(value) {
+    return `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
 /** @param {string} engine */
 function engineToTag(engine) {
     const map = {

package/dist/route-path.d.ts

@@ -6,7 +6,7 @@ export declare function isRouteBoundaryStem(stem: string): boolean;
 export declare function isRouteGroupDir(seg: string): boolean;
 /**
  * File-route fallback (`pages/home` → `/home`, `pages/index` → `/`).
- * Used only when a deployment unit has no `pathPattern`.
+ * Kept for tooling diagnostics only — production hosts must use Plan `pathPattern`.
  */
 export declare function filePathPatternFromChunk(chunkId: string): string;
 export type DeploymentPageUnit = {
@@ -17,7 +17,7 @@ export type DeploymentPageUnit = {
     pathPattern?: string;
     routeId?: string;
 };
-/** Canonical Browser HTTP pattern for a page unit. Mini must not read this. */
+/** Canonical Browser HTTP pattern for a page unit. Mini must not read this. Requires Plan `pathPattern`. */
 export declare function unitBrowserPathPattern(unit: DeploymentPageUnit | null | undefined): string;
 export type PathSeg = {
     kind: 'static';

package/dist/route-path.js

@@ -10,7 +10,7 @@ export function isRouteGroupDir(seg) {
 }
 /**
  * File-route fallback (`pages/home` → `/home`, `pages/index` → `/`).
- * Used only when a deployment unit has no `pathPattern`.
+ * Kept for tooling diagnostics only — production hosts must use Plan `pathPattern`.
  */
 export function filePathPatternFromChunk(chunkId) {
     const rel = String(chunkId || '').replace(/^pages\//, '');
@@ -28,12 +28,14 @@ export function filePathPatternFromChunk(chunkId) {
     }
     return segs.length ? `/${segs.join('/')}` : '/';
 }
-/** Canonical Browser HTTP pattern for a page unit. Mini must not read this. */
+/** Canonical Browser HTTP pattern for a page unit. Mini must not read this. Requires Plan `pathPattern`. */
 export function unitBrowserPathPattern(unit) {
     const explicit = String(unit?.pathPattern || '').trim();
-    if (explicit)
-        return explicit.startsWith('/') ? explicit : `/${explicit}`;
-    return filePathPatternFromChunk(String(unit?.chunkId || ''));
+    if (!explicit) {
+        const chunkId = String(unit?.chunkId || '');
+        throw new Error(`unitBrowserPathPattern: page unit ${chunkId || '(unknown)'} missing pathPattern (plan-only host)`);
+    }
+    return explicit.startsWith('/') ? explicit : `/${explicit}`;
 }
 export function parsePathPattern(pattern) {
     const raw = String(pattern || '').trim();

package/dist/server-artifact.d.ts

@@ -1,19 +1,10 @@
 /**
- * P4 ServerArtifact — compiled route decision tree + public ServerRoute contracts
- * + internal capability units + selected runtime adapter. Web Standards Fetch entry.
+ * P4 ServerArtifact — thin host write of Rust/N-API normalized Plan.
+ * Assembly / digests / adapters live in vmz-artifacts via N-API.
  */
 export declare const SERVER_ARTIFACT_SCHEMA = "vmz.server.artifact.v0";
 export declare const HTTP_CONTRACT_SCHEMA = "vmz.http.contract.v0";
 export declare const SERVER_RUNTIME_ADAPTER_SCHEMA = "vmz.server.runtime_adapter.v0";
-/**
- * @param {string} outDir
- * @param {{
- *   profileId?: string | null,
- *   assembly?: string | null,
- *   serverRuntime?: string | null,
- *   packDigest?: string | null,
- * }} [opts]
- */
 interface ServerArtifactOpts {
     profileId?: string | null;
     assembly?: string | null;
@@ -42,6 +33,7 @@ interface ServerArtifactBody {
     packDigest: string | null;
     adapters: Record<string, unknown>;
     artifactDigest?: string;
+    [key: string]: unknown;
 }
 export declare function emitServerArtifact(outDir: string, opts?: ServerArtifactOpts): {
     artifact: ServerArtifactBody;
@@ -49,47 +41,7 @@ export declare function emitServerArtifact(outDir: string, opts?: ServerArtifact
     httpContractDigest: string;
 };
 /**
- * @param {Record<string, any>} artifact
- * @param {string} adapterId
+ * Project a runtime adapter document from a normalized artifact (N-API).
  */
-export declare function projectServerRuntimeAdapter(artifact: any, adapterId: any): {
-    host: string;
-    invoke: string;
-    status: string;
-    schema: string;
-    adapterId: string;
-    artifactDigest: any;
-    httpContractDigest: any;
-    spaFallback: boolean;
-    entry: any;
-    publicRouteCount: any;
-    internalCapabilityCount: any;
-} | {
-    host: string;
-    invoke: string;
-    status: string;
-    note: string;
-    schema: string;
-    adapterId: string;
-    artifactDigest: any;
-    httpContractDigest: any;
-    spaFallback: boolean;
-    entry: any;
-    publicRouteCount: any;
-    internalCapabilityCount: any;
-} | {
-    host: string;
-    invoke: string;
-    status: string;
-    note: string;
-    consumes: string[];
-    schema: string;
-    adapterId: string;
-    artifactDigest: any;
-    httpContractDigest: any;
-    spaFallback: boolean;
-    entry: any;
-    publicRouteCount: any;
-    internalCapabilityCount: any;
-};
+export declare function projectServerRuntimeAdapter(artifact: Record<string, unknown>, adapterId: string): any;
 export {};