@vmz/core 0.1.31 → 0.2.0

package/dist/{serve-host.mjs → host/serve-host.mjs}

@@ -1,6 +1,5 @@
-// @ts-nocheck
 /**
- * Generic VMZ Node host — SSR Route Graph pages + dist static + RPC/REST.
+ * Generic VMZ Node host �?SSR Route Graph pages + dist static + RPC/REST.
  *
  * Invoked by `vmz serve` / `vmz dev` (or: node dist/vmz-serve-host.mjs).
  *
@@ -10,8 +9,8 @@
  *
  * `VMZ_DEV=1`: POST `/__vmz/reload` soft-reloads modules (cache-bust import);
  * GET `/__vmz/events` SSE notifies the browser:
- * - island HMR → re-import `entry-client.js` (no full document reload)
- * - otherwise → `location.reload`
+ * - island HMR �?re-import `entry-client.js` (no full document reload)
+ * - otherwise �?`location.reload`
  *
  * Dev resolve hook propagates `?t=` onto nested relative `file:` imports under
  * dist so soft reload does not keep a stale `lib/*.js` ESM cache entry.
@@ -27,12 +26,11 @@ import { LOCALE_LINK_PLAN_SCHEMA, linkRouteAliasesFromUnits, localeHrefTableFrom
 import { loadNativeAddon } from './native-addon.js';
 import { createRenderHost } from './render-host.js';
 import { resolveRouteLayoutChain } from './route-layout-chain.js';
-import { handleNodeRequest, setRoutes, setServerModuleResolver } from './vmz-runtime.js';
+import { handleNodeRequest, setRoutes, setServerModuleResolver } from '../faces/vmz-runtime.js';
 const ROUTE_CATALOG_SCHEMA = 'vmz.route.catalog.v0';
 const ROUTE_CATALOG_REL = '_vmz/route-catalog.json';
 const LOCALE_LINK_PLAN_REL = '_vmz/locale-link-plan.json';
 const require = createRequire(import.meta.url);
-/** App delivery root. Host companions may live under `_vmz/host/` (0.1.31). */
 function resolveServeDistDir() {
     if (process.env.VMZ_DIST)
         return path.resolve(process.env.VMZ_DIST);
@@ -45,14 +43,12 @@ function resolveServeDistDir() {
     return here;
 }
 const distDir = resolveServeDistDir();
-/** App project root for bare import / JSON resolve (dev SSR ≡ build node_modules). */
 function projectRootForResolve() {
     const fromEnv = typeof process.env.VMZ_PROJECT_ROOT === 'string' ? process.env.VMZ_PROJECT_ROOT.trim() : '';
     if (fromEnv)
         return path.resolve(fromEnv);
     return process.cwd();
 }
-/** @type {ReturnType<typeof createRequire> | null} */
 let appPackageRequire = null;
 function appPackageRequireResolve() {
     if (!appPackageRequire) {
@@ -112,7 +108,7 @@ const isDev = process.env.VMZ_DEV === '1' || process.env.VMZ_DEV === 'true';
 globalThis.__VMZ_RPC_ORIGIN = `http://${host}:${port}`;
 /**
  * Soft reload only busts the top-level `import(page?t=token)`. Nested relative
- * imports (`../../lib/units.js`) keep the first-loaded ESM cache entry — so a
+ * imports (`../../lib/units.js`) keep the first-loaded ESM cache entry �?so a
  * page can demand exports that the stale dep never had (or vice versa).
  * Propagate `t` from parentURL onto file: children under this dist.
  */
@@ -151,34 +147,20 @@ if (isDev) {
         },
     });
 }
-/** @type {number} */
 let reloadToken = Date.now();
-/** @type {Awaited<ReturnType<typeof createRenderHost>> | null} */
 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 parsePathPattern> }>} */
 let pageCatalog = [];
-/** @type {Map<string, any>} */
 const pageCtors = new Map();
-/** Stylesheet from deployment `cssEntry` (e.g. vmz.css). */
 let cssEntry = null;
-/** Fingerprint of style inputs — busts `@import` siblings when tokens change (VMZ-8). */
 let styleBundleHash = null;
-/** @type {{ defaultThemeId: string, themeIds: string[], activationAttr: string, contentHash: string|null } | null} */
 let styleTheme = null;
-/** Locale route realization artifact from `_vmz/locale-route-realization.json` (optional). */
 let localeArtifact = null;
-/** Frozen locale link plan from `_vmz/locale-link-plan.json` (0.1.30 authority). */
 let localeLinkPlan = null;
-/** @type {Set<import('node:http').ServerResponse>} */
 const sseClients = new Set();
-/** In-flight HTTP requests (graceful shutdown drain). */
 let inFlight = 0;
-/** When true, refuse new work except health. */
 let shuttingDown = false;
 let ready = false;
-/** @type {{ message: string, stack?: string, at: number } | null} */
 let lastDevError = null;
 setServerModuleResolver((moduleId) => {
     const rel = moduleId.replace(/^#server\//, '') + '.js';
@@ -190,13 +172,9 @@ try {
 }
 catch (err) {
     lastDevError = normalizeDevError(err);
-    ready = true; // still accept HTTP — serve error page / recover on next reload
+    ready = true; // still accept HTTP �?serve error page / recover on next reload
     console.error('vmz serve: initial load failed (dev host stays up)', lastDevError.message);
 }
-/**
- * @param {import('node:http').IncomingMessage} req
- * @returns {Promise<string>}
- */
 function readRequestBody(req) {
     return new Promise((resolve, reject) => {
         const chunks = [];
@@ -205,17 +183,16 @@ function readRequestBody(req) {
         req.on('error', reject);
     });
 }
-/**
- * @param {string} pathname
- * @returns {Promise<string | null>}
- */
 async function renderPage(pathname, opts = {}) {
     const rendered = await renderPageStream(pathname, opts);
     if (!rendered)
         return null;
-    const stream = rendered.stream ?? rendered;
+    const raw = rendered.stream ?? rendered;
+    if (!raw || typeof raw !== 'object' || typeof raw[Symbol.asyncIterator] !== 'function') {
+        return null;
+    }
     let html = '';
-    for await (const chunk of stream) {
+    for await (const chunk of raw) {
         html += chunk;
     }
     return html;
@@ -224,9 +201,6 @@ async function renderPage(pathname, opts = {}) {
  * Stream shell + Direct serialize body for the matched file-route page.
  * Runs Page.access (closed allow/redirect/not-found/deny) before load;
  * POST may run Page.action before re-render.
- * @param {string} pathname
- * @param {{ signal?: AbortSignal, searchParams?: URLSearchParams, cookieHeader?: string, method?: string, body?: unknown }} [opts]
- * @returns {Promise<{ status: number, stream?: AsyncGenerator<string, void, void>, redirect?: string, headers?: Record<string, string> } | null>}
  */
 async function renderPageStream(pathname, opts = {}) {
     try {
@@ -239,11 +213,6 @@ async function renderPageStream(pathname, opts = {}) {
         return { status: 500, stream: emitDevErrorHtml(normalized) };
     }
 }
-/**
- * @param {string} pathname
- * @param {{ signal?: AbortSignal, searchParams?: URLSearchParams, cookieHeader?: string, method?: string, body?: unknown }} [opts]
- * @returns {Promise<{ status: number, stream?: AsyncGenerator<string, void, void>, redirect?: string, headers?: Record<string, string> } | null>}
- */
 async function renderPageStreamInner(pathname, opts = {}) {
     if (isDev && lastDevError && pageCtors.size === 0) {
         return { status: 500, stream: emitDevErrorHtml(lastDevError) };
@@ -376,10 +345,6 @@ async function renderPageStreamInner(pathname, opts = {}) {
         stream: emitPageHtml(Page, match.chunkId, eventOnlyShell, props, opts, layoutChain, localeCtx),
     };
 }
-/**
- * @param {unknown} access
- * @returns {{ kind: 'allow' } | { kind: 'redirect', location: string } | { kind: 'deny' } | { kind: 'not-found' }}
- */
 function normalizeAccessResult(access) {
     if (access == null || access === true)
         return { kind: 'allow' };
@@ -392,10 +357,11 @@ function normalizeAccessResult(access) {
         if (k === 'not-found' || k === 'notfound')
             return { kind: 'not-found' };
     }
-    if (typeof access === 'object') {
-        const kind = String(access.kind || access.type || 'allow').toLowerCase();
+    if (typeof access === 'object' && access) {
+        const row = access;
+        const kind = String(row.kind || row.type || 'allow').toLowerCase();
         if (kind === 'redirect') {
-            const location = String(access.location || access.to || access.href || '');
+            const location = String(row.location || row.to || row.href || '');
             if (!location)
                 return { kind: 'deny' };
             return { kind: 'redirect', location };
@@ -408,30 +374,28 @@ function normalizeAccessResult(access) {
     }
     return { kind: 'allow' };
 }
-/**
- * @param {unknown} acted
- * @returns {{ kind: 'allow', props?: Record<string, unknown> } | { kind: 'redirect', location: string } | { kind: 'deny' } | { kind: 'not-found' }}
- */
 function normalizeActionResult(acted) {
     const base = normalizeAccessResult(acted);
     if (base.kind !== 'allow')
         return base;
-    if (acted && typeof acted === 'object' && acted.props && typeof acted.props === 'object') {
-        return { kind: 'allow', props: acted.props };
-    }
-    if (acted && typeof acted === 'object' && !('kind' in acted) && !('type' in acted) && !Array.isArray(acted)) {
-        return { kind: 'allow', props: acted };
+    if (acted && typeof acted === 'object' && !Array.isArray(acted)) {
+        const row = acted;
+        if (row.props && typeof row.props === 'object') {
+            return { kind: 'allow', props: row.props };
+        }
+        if (!('kind' in row) && !('type' in row)) {
+            return { kind: 'allow', props: row };
+        }
     }
     return { kind: 'allow' };
 }
 /**
  * Minimal HTML for closed access/action results when no NotFound page exists.
- * @param {string} marker
  */
 async function* emitAccessShell(marker) {
     const native = loadNativeAddon();
     if (typeof native.generateHtmlShell !== 'function') {
-        throw new Error('vmz native addon missing generateHtmlShell — rebuild with `pnpm napi:build`');
+        throw new Error('vmz native addon missing generateHtmlShell �?rebuild with `pnpm napi:build`');
     }
     yield native.generateHtmlShell({
         title: 'App',
@@ -442,8 +406,7 @@ async function* emitAccessShell(marker) {
     });
 }
 /**
- * Prefer page `static meta()` for document title/description — never brand the framework in business HTML.
- * @param {any} Page
+ * Prefer page `static meta()` for document title/description �?never brand the framework in business HTML.
  */
 function resolvePageDocumentMeta(Page) {
     try {
@@ -460,14 +423,6 @@ function resolvePageDocumentMeta(Page) {
         return { title: 'App', description: '' };
     }
 }
-/**
- * @param {any} Page
- * @param {string} chunkId
- * @param {boolean} eventOnlyShell
- * @param {Record<string, unknown>} props
- * @param {{ signal?: AbortSignal, searchParams?: URLSearchParams, cookieHeader?: string }} [opts]
- * @param {string[]} [layoutChain] layout chunk ids outer→inner
- */
 async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {}, layoutChain = [], localeCtx = {}) {
     const signal = opts.signal;
     const live = isDev
@@ -477,7 +432,7 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
     let sawDisconnect = false;
     es.onerror = () => { sawDisconnect = true; };
     es.onopen = () => {
-      // Host respawn drops SSE — reload once the new process is up (no manual restart).
+      // Host respawn drops SSE �?reload once the new process is up (no manual restart).
       if (sawDisconnect) location.reload();
     };
     function showOverlay(err) {
@@ -501,7 +456,7 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
         + "<p style=\\"margin:0 0 .5rem;color:#f87171;font-weight:700\\">Dev Error</p>"
         + "<pre style=\\"white-space:pre-wrap;margin:0 0 1rem;font-size:13px;line-height:1.45\\">" + esc(msg) + "</pre>"
         + (stack ? "<pre style=\\"white-space:pre-wrap;opacity:.7;font-size:12px\\">" + esc(stack) + "</pre>" : "")
-        + "<p style=\\"opacity:.65;font-size:12px\\">Fix the file and save — soft reload will clear this overlay.</p>"
+        + "<p style=\\"opacity:.65;font-size:12px\\">Fix the file and save �?soft reload will clear this overlay.</p>"
         + "</div>";
     }
     function hideOverlay() {
@@ -522,26 +477,11 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
       hideOverlay();
       if (msg.mode === "island") {
         try {
-          const { registerComponents, hydrate } = await import("/dom.browser.js?t=" + msg.token);
-          const names = (msg.affectedChunks || [])
-            .map((c) => String(c))
-            .filter((c) => c.startsWith("components/") || !c.includes("/"))
-            .map((c) => c.split("/").pop())
-            .filter(Boolean);
-          const map = {};
-          for (const name of names) {
-            let mod;
-            try {
-              mod = await import("/components/" + name + ".client.js?t=" + msg.token);
-            } catch {
-              mod = await import("/" + name + ".client.js?t=" + msg.token);
-            }
-            map[name] = mod.default;
-          }
-          if (Object.keys(map).length) registerComponents(map);
+          const { hydrate } = await import("/dom.browser.js?t=" + msg.token);
           const root = document.getElementById("app");
           const pageChunk = root && root.getAttribute("data-vmz-page");
           if (root && pageChunk) {
+            // Child Ctors come from page static imports after reload with cache token.
             const pageMod = await import("/" + pageChunk + ".client.js?t=" + msg.token);
             let hmrProps = {};
             try {
@@ -583,7 +523,6 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
     const propsJson = JSON.stringify(props ?? {});
     const localeId = localeCtx.localeId || localeArtifact?.defaultLocale || 'en';
     const dir = localeCtx.dir || 'ltr';
-    /** @type {string[]} */
     const htmlExtraAttrs = [...htmlThemeAttrPair(themeId)];
     if (localeArtifact?.routing) {
         htmlExtraAttrs.push('data-vmz-locale-routing', JSON.stringify({
@@ -617,7 +556,7 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
         }
         if (signal?.aborted)
             return;
-        // Wrap page HTML in layout chain (outer → inner) via default slot injection.
+        // Wrap page HTML in layout chain (outer �?inner) via default slot injection.
         for (let i = layoutChain.length - 1; i >= 0; i--) {
             const Layout = await loadPageCtor(layoutChain[i]);
             if (!Layout)
@@ -626,7 +565,7 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
             if (signal?.aborted)
                 return;
         }
-        // Locale discipline: apply frozen link plan rows (0.1.30) — no path algebra.
+        // Locale discipline: apply frozen link plan rows (0.1.30) �?no path algebra.
         if (localeArtifact && localeId) {
             bodyHtml = localizeBodyLinks(bodyHtml, localeId, localeArtifact, undefined, localeLinkPlan);
         }
@@ -641,7 +580,7 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
         return;
     const native = loadNativeAddon();
     if (typeof native.generatePageShell !== 'function') {
-        throw new Error('vmz native addon missing generatePageShell — rebuild with `pnpm napi:build`');
+        throw new Error('vmz native addon missing generatePageShell �?rebuild with `pnpm napi:build`');
     }
     const entrySrc = `/${eventOnlyShell ? 'entry-event.js' : 'entry-client.js'}?t=${reloadToken}`;
     const cssHref = cssEntryWithBust(cssEntry);
@@ -705,7 +644,7 @@ const server = http.createServer((req, res) => {
             .then((raw) => {
             let payload = {};
             try {
-                payload = raw ? JSON.parse(raw) : {};
+                payload = raw ? JSON.parse(String(raw)) : {};
             }
             catch {
                 payload = {};
@@ -754,7 +693,7 @@ async function gracefulShutdown(signal) {
         return;
     shuttingDown = true;
     ready = false;
-    console.log(`vmz serve: ${signal} — draining in-flight=${inFlight} timeout=${SHUTDOWN_TIMEOUT_MS}ms`);
+    console.log(`vmz serve: ${signal} �?draining in-flight=${inFlight} timeout=${SHUTDOWN_TIMEOUT_MS}ms`);
     server.close();
     const start = Date.now();
     while (inFlight > 0 && Date.now() - start < SHUTDOWN_TIMEOUT_MS) {
@@ -780,8 +719,6 @@ process.on('SIGINT', () => {
 /**
  * Attach author Link RouteId aliases so localizeBodyLinks can match `data-vmz-route="IndexPage"`
  * against realization rows keyed by chunk path (`pages/index`).
- * @param {any} artifact
- * @param {string} dir
  */
 function attachLinkRouteAliases(artifact, dir) {
     if (!artifact || typeof artifact !== 'object')
@@ -801,7 +738,6 @@ function attachLinkRouteAliases(artifact, dir) {
  * Re-import routes / pages / components with a new cache-bust token.
  * Keeps the HTTP server process alive (no Node restart).
  * Failed reloads keep the previous in-memory modules (Vite-like resilience).
- * @param {{ quiet?: boolean, payload?: { affectedChunks?: string[], seedChunks?: string[], emitted?: string[], full?: boolean, islandHmr?: boolean, buildId?: string, sourceRevision?: string, bundleRevision?: string, changed?: string[] } }} [opts]
  */
 async function softReload(opts = {}) {
     const prevToken = reloadToken;
@@ -820,7 +756,7 @@ async function softReload(opts = {}) {
     const bundleRevision = opts.payload?.bundleRevision != null ? String(opts.payload.bundleRevision) : null;
     if (buildId)
         lastDevBuildId = buildId;
-    // 0.1.31: payload-only scope. `reloadToken` is opaque cache-bust — never invent full/affected here.
+    // 0.1.31: payload-only scope. `reloadToken` is opaque cache-bust �?never invent full/affected here.
     const reloadAllPages = Boolean(full) || (!islandHmr && rerunLoaders.length === 0 && affected.length === 0);
     try {
         try {
@@ -852,7 +788,6 @@ async function softReload(opts = {}) {
         });
         const nextCatalog = await listPageClientFiles(distDir);
         // empty catalog throws inside listPageClientFiles
-        /** @type {Map<string, any>} */
         const nextCtors = new Map();
         if (!islandHmr) {
             const reloadSet = rerunLoaders.length > 0
@@ -952,7 +887,6 @@ async function softReload(opts = {}) {
         throw err;
     }
 }
-/** @param {string} chunkId @param {string[]} affected */
 function pageNeedsReload(chunkId, affected) {
     if (chunkId === 'pages/Layout' || chunkId.endsWith('/Layout'))
         return true;
@@ -961,7 +895,6 @@ function pageNeedsReload(chunkId, affected) {
         return id === chunkId || chunkId.startsWith(`${id}/`) || id.startsWith(`${chunkId}/`);
     });
 }
-/** @param {string} event */
 function notifySse(event) {
     for (const client of [...sseClients]) {
         try {
@@ -972,10 +905,9 @@ function notifySse(event) {
         }
     }
 }
-/** @param {unknown} err */
 function normalizeDevError(err) {
     if (err && typeof err === 'object') {
-        const e = /** @type {{ message?: string, stack?: string }} */ (err);
+        const e = err;
         return {
             message: e.message ? String(e.message) : String(err),
             stack: e.stack ? String(e.stack) : undefined,
@@ -984,7 +916,6 @@ function normalizeDevError(err) {
     }
     return { message: String(err), at: Date.now() };
 }
-/** @param {{ message: string, stack?: string }} err */
 async function* emitDevErrorHtml(err) {
     const msg = escapeHtml(err.message || 'Unknown error');
     const stack = err.stack ? escapeHtml(err.stack) : '';
@@ -1000,7 +931,7 @@ async function* emitDevErrorHtml(err) {
     <h1>Dev Error</h1>
     <pre>${msg}</pre>
     ${stack ? `<pre style="opacity:.7;font-size:12px">${stack}</pre>` : ''}
-    <p class="hint">Dev host stayed up. Fix the source and save — soft reload will recover.</p>
+    <p class="hint">Dev host stayed up. Fix the source and save �?soft reload will recover.</p>
   </main>
   <script>
   (() => {
@@ -1026,11 +957,10 @@ async function* emitDevErrorHtml(err) {
         }
     }
     catch {
-        /* fall through to plain HTML — never throw from the error page itself */
+        /* fall through to plain HTML �?never throw from the error page itself */
     }
     yield `<!DOCTYPE html><html lang="en"><head><meta charset="utf-8" /><title>Dev Error</title></head><body>${body}</body></html>`;
 }
-/** @param {string} s */
 function escapeHtml(s) {
     return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
 }
@@ -1039,8 +969,6 @@ function escapeHtml(s) {
  * - `prefix`: LocaleId from URL path (existing).
  * - `none`: Host preference from cookie `vmz.locale` (validated), else defaultLocale.
  *   URL never carries LocaleId.
- * @param {string} pathname
- * @param {string | undefined} cookieHeader
  */
 function resolveLocalePath(pathname, cookieHeader) {
     const raw = String(pathname || '/');
@@ -1088,10 +1016,6 @@ function resolveLocalePath(pathname, cookieHeader) {
         redirectTo: null,
     };
 }
-/**
- * @param {string} chunkId
- * @param {string} localeId
- */
 function pageMetaAlternates(chunkId, localeId) {
     if (!localeArtifact?.pageMetas)
         return [];
@@ -1099,13 +1023,11 @@ function pageMetaAlternates(chunkId, localeId) {
         localeArtifact.pageMetas.find((m) => m.routeId === chunkId && m.locale === localeArtifact.defaultLocale);
     return Array.isArray(meta?.alternates) ? meta.alternates : [];
 }
-/** @param {string} href */
 function bustUrl(href) {
     const u = new URL(href);
     u.searchParams.set('t', String(reloadToken));
     return u.href;
 }
-/** @param {string} chunkId */
 async function loadPageCtor(chunkId) {
     const pageRel = `${chunkId}.client.js`;
     const href = bustUrl(pathToFileURL(path.join(distDir, pageRel)).href);
@@ -1116,7 +1038,6 @@ async function loadPageCtor(chunkId) {
 /**
  * Load compiled page catalog from `_vmz/route-catalog.json` (0.1.30 authority).
  * Hosts must not re-parse deployment pathPattern into a live catalog.
- * @param {string} dir
  */
 async function listPageClientFiles(dir) {
     const fromCatalog = await listPagesFromRouteCatalog(dir);
@@ -1129,11 +1050,7 @@ async function listPageClientFiles(dir) {
     }
     return fromCatalog;
 }
-/**
- * @param {string} dir
- */
 async function listPagesFromRouteCatalog(dir) {
-    /** @type {Array<{ chunkId: string, pageRel: string, routeId?: string, pathPattern?: string, segs: ReturnType<typeof parsePathPattern> }>} */
     const out = [];
     try {
         const raw = await readFile(path.join(dir, ...ROUTE_CATALOG_REL.split('/')), 'utf8');
@@ -1165,14 +1082,12 @@ async function listPagesFromRouteCatalog(dir) {
 }
 /**
  * Browser HTTP pattern (`/` / `/home` / `/users/:id` / `/blog/[...slug]`).
- * @param {string} pattern
  */
 function parsePathPattern(pattern) {
     const raw = String(pattern || '').trim();
     if (!raw || raw === '/')
         return [];
     const parts = raw.replace(/^\/+/, '').split('/').filter(Boolean);
-    /** @type {Array<{ kind: 'static' | 'param' | 'catch', value?: string, name?: string }>} */
     const segs = [];
     for (const p of parts) {
         if (isRouteGroupDir(p))
@@ -1181,9 +1096,6 @@ function parsePathPattern(pattern) {
     }
     return segs;
 }
-/**
- * @param {string} p
- */
 function parsePathSegment(p) {
     const catchAll = /^\[\.\.\.([^\]]+)\]$/.exec(p);
     const param = /^\[([^\]]+)\]$/.exec(p);
@@ -1202,10 +1114,6 @@ function isRouteGroupDir(seg) {
 function isRouteBoundaryStem(stem) {
     return stem === 'Layout' || stem === 'Loading' || stem === 'Error' || stem === 'NotFound';
 }
-/**
- * @param {string} pathname
- * @param {typeof pageCatalog} catalog
- */
 function matchFileRoute(pathname, catalog) {
     const pathParts = decodeURIComponent(pathname.split('?')[0] || '/')
         .replace(/\/+$/, '')
@@ -1225,17 +1133,11 @@ function matchFileRoute(pathname, catalog) {
     }
     return best;
 }
-/**
- * @param {ReturnType<typeof parsePathPattern>} segs
- * @param {string} pathname
- * @returns {Record<string, string>}
- */
 function extractRouteParams(segs, pathname) {
     const pathParts = decodeURIComponent(pathname.split('?')[0] || '/')
         .replace(/\/+$/, '')
         .split('/')
         .filter(Boolean);
-    /** @type {Record<string, string>} */
     const params = {};
     let j = 0;
     for (let i = 0; i < segs.length; i++) {
@@ -1254,11 +1156,6 @@ function extractRouteParams(segs, pathname) {
     }
     return params;
 }
-/**
- * @param {ReturnType<typeof parsePathPattern>} segs
- * @param {string[]} pathParts
- * @returns {number | null}
- */
 function scoreRoute(segs, pathParts) {
     let i = 0;
     let j = 0;
@@ -1266,7 +1163,7 @@ function scoreRoute(segs, pathParts) {
     while (i < segs.length) {
         const s = segs[i];
         if (s.kind === 'catch') {
-            // Required catch-all `[...slug]` needs ≥1 remaining segment (not `/`).
+            // Required catch-all `[...slug]` needs �? remaining segment (not `/`).
             if (j >= pathParts.length)
                 return null;
             score += 1;
@@ -1296,9 +1193,7 @@ function findRootCatchAll(catalog) {
     return catalog.find((p) => isRootCatchAll(p)) || null;
 }
 /**
- * Optional app gate: `dist/vmz-route-gate.mjs` → `{ check(pathname, chunkId) => 'not_found' | null }`.
- * @param {string} pathname
- * @param {string | undefined} chunkId
+ * Optional app gate: `dist/vmz-route-gate.mjs` �?`{ check(pathname, chunkId) => 'not_found' | null }`.
  */
 async function runRouteGate(pathname, chunkId) {
     try {
@@ -1312,29 +1207,23 @@ async function runRouteGate(pathname, chunkId) {
         return null;
     }
 }
-/**
- * @param {Array<{ name: string, entry: string }>} eager
- * @param {Array<{ name: string, entry: string }>} lazy
- * @param {number} token
- */
 function emitEntryClient(eager, lazy, token) {
     const q = `?t=${token}`;
     const native = loadNativeAddon();
     if (typeof native.generateServeEntryClient !== 'function') {
-        throw new Error('vmz native addon missing generateServeEntryClient — rebuild with `pnpm napi:build`');
+        throw new Error('vmz native addon missing generateServeEntryClient �?rebuild with `pnpm napi:build`');
     }
     return native.generateServeEntryClient(eager, lazy, q);
 }
 /**
  * EventEntry zero-framework bootstrap: no static import of vmz-dom / page / islands.
  * Framework bytes load only inside the first matching DOM event handler.
- * @param {number} token
  */
 function emitEntryEvent(token) {
     const q = `?t=${token}`;
     const native = loadNativeAddon();
     if (typeof native.generateServeEntryEvent !== 'function') {
-        throw new Error('vmz native addon missing generateServeEntryEvent — rebuild with `pnpm napi:build`');
+        throw new Error('vmz native addon missing generateServeEntryEvent �?rebuild with `pnpm napi:build`');
     }
     return native.generateServeEntryEvent(q);
 }
@@ -1342,11 +1231,9 @@ function emitEntryEvent(token) {
  * Style Theme cookie / localStorage key (host contract, not a second theme API).
  */
 const THEME_STORE_KEY = 'vmz-theme';
-/** Host preference key for `routing.strategy: 'none'` (cookie + localStorage). */
 const LOCALE_STORE_KEY = 'vmz.locale';
 /**
  * Cache-bust stylesheet entry for dev reload (token + serve revision).
- * @param {string | null | undefined} entry
  */
 function cssEntryWithBust(entry) {
     if (!entry)
@@ -1358,10 +1245,6 @@ function cssEntryWithBust(entry) {
         params.set('h', styleBundleHash);
     return `${base}?${params.toString()}`;
 }
-/**
- * @param {string} dir
- * @returns {Promise<{ cssEntry: string|null, styleTheme: typeof styleTheme, styleBundleHash: string|null }>}
- */
 async function loadDeploymentStyle(dir) {
     try {
         const raw = await readFile(path.join(dir, 'vmz-deployment.json'), 'utf8');
@@ -1389,11 +1272,8 @@ async function loadDeploymentStyle(dir) {
     }
 }
 /**
- * Priority: `?theme=` → cookie → none (CSS `:root` + prefers-color-scheme media).
+ * Priority: `?theme=` �?cookie �?none (CSS `:root` + prefers-color-scheme media).
  * Explicit ids (including default) always win over OS preference via activation attr.
- * @param {URLSearchParams | undefined} searchParams
- * @param {string | undefined} cookieHeader
- * @returns {string|null}
  */
 function resolveThemeId(searchParams, cookieHeader) {
     if (!styleTheme)
@@ -1409,8 +1289,6 @@ function resolveThemeId(searchParams, cookieHeader) {
 }
 /**
  * Always emit activation attr for an explicit theme id (incl. default) so it overrides OS media.
- * @param {string|null} themeId
- * @returns {[string, string] | []} flattened attr pair for generatePageShell
  */
 function htmlThemeAttrPair(themeId) {
     if (!styleTheme || !themeId)
@@ -1422,7 +1300,7 @@ function htmlThemeAttrPair(themeId) {
 }
 /**
  * Inline boot when SSR had no query/cookie: apply explicit `localStorage` only.
- * No stored choice → leave bare `<html>` so CSS `@media (prefers-color-scheme)` follows OS live.
+ * No stored choice �?leave bare `<html>` so CSS `@media (prefers-color-scheme)` follows OS live.
  * Explicit ids (incl. default) always set the activation attr so they override OS media.
  */
 function themeBootstrapScript() {
@@ -1436,7 +1314,7 @@ function themeBootstrapScript() {
 /**
  * LocaleId as client state (routing.strategy = none): apply localStorage before any
  * page/client module runs so `#locales/*` pick the right variant. Prefix strategy
- * keeps LocaleId in the URL — no boot rewrite.
+ * keeps LocaleId in the URL �?no boot rewrite.
  * Also mirrors into cookie so the next SSR negotiate sees Host preference.
  */
 function localeBootstrapScript() {
@@ -1453,8 +1331,8 @@ function localeBootstrapScript() {
     return `  <script>(function(){try{var k=${key},ids=${idList};var id=localStorage.getItem(k);if(!id||ids.indexOf(id)<0)return;document.documentElement.setAttribute("data-locale",id);document.documentElement.setAttribute("lang",id);window.__vmzLocaleIdHint=id;document.cookie=k+"="+encodeURIComponent(id)+"; path=/; max-age=31536000; SameSite=Lax";}catch(e){}})();</script>\n`;
 }
 /**
- * Site favicon links from build artifact `_vmz/site-favicon.json` (author SVG → PNG/ICO).
- * Empty when skipped / missing — do not invent broken <link>s.
+ * Site favicon links from build artifact `_vmz/site-favicon.json` (author SVG �?PNG/ICO).
+ * Empty when skipped / missing �?do not invent broken <link>s.
  */
 function siteFaviconHeadHtml() {
     try {
@@ -1472,10 +1350,6 @@ function siteFaviconHeadHtml() {
         return '';
     }
 }
-/**
- * @param {string|undefined} header
- * @param {string} name
- */
 function readCookie(header, name) {
     if (!header)
         return null;
@@ -1496,19 +1370,10 @@ function readCookie(header, name) {
     }
     return null;
 }
-/**
- * @param {string} dir
- * @returns {Promise<string|null>}
- */
 async function loadCssEntry(dir) {
     const meta = await loadDeploymentStyle(dir);
     return meta.cssEntry;
 }
-/**
- * @param {string} dir
- * @param {string} chunkId
- * @returns {Promise<Array<{ component: string, strategy: string }>>}
- */
 async function loadPageResumeEntries(dir, chunkId) {
     try {
         const raw = await readFile(path.join(dir, 'vmz-deployment.json'), 'utf8');
@@ -1525,17 +1390,14 @@ async function loadPageResumeEntries(dir, chunkId) {
         return [];
     }
 }
-/** @param {string} strategy */
 function isEventStrategy(strategy) {
     return strategy === 'event' || strategy === 'click' || strategy.startsWith('event:');
 }
-/** @param {string[]} strategies */
 function isEventOnlyShell(strategies) {
     if (!strategies.length)
         return false;
     return strategies.every((s) => isEventStrategy(s));
 }
-/** @param {string} s */
 function escapeAttr(s) {
     return String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;');
 }