@vmz/core 0.1.31 → 0.2.0

package/dist/{server.js → faces/server.js}

@@ -1,63 +1,36 @@
-// @ts-nocheck
 /**
  * Minimal VMZ runtime — `#server` invoke + RPC/REST HTTP + optional static/SSR.
  *
- *
  * Browser-safe: no static `node:*` imports. Node builtins are loaded only inside
  * Node/SSR request handlers so client bundles can `import { callServer }`.
  */
-/** @typedef {{ moduleId: string, method: string, args?: unknown[] }} RpcRequest */
-/** @typedef {{ verb: string, path: string, moduleId: string, method: string, className?: string }} Route */
-/**
- * @typedef {{
- * distDir?: string,
- * renderIndex?: => Promise<string> | string,
- * renderIndexStream?: (opts?: { signal?: AbortSignal }) => AsyncIterable<string>,
- * renderPage?: (pathname: string) => Promise<string | null> | string | null,
- * renderPageStream?: (pathname: string, opts?: { signal?: AbortSignal, searchParams?: URLSearchParams, cookieHeader?: string, method?: string, body?: unknown }) => Promise<AsyncIterable<string> | { status?: number, stream?: AsyncIterable<string>, redirect?: string, headers?: Record<string, string> } | null> | AsyncIterable<string> | null,
- * req?: import('node:http').IncomingMessage,
- * }} NodeRequestOptions
- */
 const DEFAULT_RPC_PATH = '/__vmz/rpc';
-/** @type {((id: string) => string | URL) | null} */
 let resolveServerModule = null;
-/** @type {Route[]} */
 let routes = [];
 /**
- * Map `#server/foo` → filesystem / URL the host can `import`.
- * Only set this in Node/SSR hosts — browser bundles must omit it so RPC goes HTTP.
+ * Map `#server/foo` �?filesystem / URL the host can `import`.
+ * Only set this in Node/SSR hosts �?browser bundles must omit it so RPC goes HTTP.
  */
 export function setServerModuleResolver(fn) {
     resolveServerModule = fn;
 }
-/** @param {Route[]} next */
 export function setRoutes(next) {
     routes = Array.isArray(next) ? next : [];
 }
-/**
- * @param {string} moduleId
- * @param {string} method
- * @param {unknown[]} args
- */
 export async function callServer(moduleId, method, args = []) {
     // Browser (or tests forcing HTTP): never touch server modules in-process.
-    // Node SSR / smokes set a resolver and leave __VMZ_USE_HTTP_RPC unset → local.
+    // Node SSR / smokes set a resolver and leave __VMZ_USE_HTTP_RPC unset �?local.
     if (globalThis.__VMZ_USE_HTTP_RPC || !resolveServerModule) {
         return callServerHttp(moduleId, method, args);
     }
     return callServerLocal(moduleId, method, args);
 }
-/**
- * @param {string} moduleId
- * @param {string} method
- * @param {unknown[]} args
- */
 async function callServerLocal(moduleId, method, args) {
     if (!resolveServerModule) {
         throw new Error(`vmz:runtime callServer(${moduleId}): setServerModuleResolver() required in Node`);
     }
     const spec = resolveServerModule(moduleId);
-    const mod = await import(spec);
+    const mod = await import(typeof spec === 'string' ? spec : spec.href);
     const Ctor = mod.default ?? mod[exportGuess(moduleId)];
     if (typeof Ctor !== 'function') {
         throw new Error(`vmz:runtime: no class export for ${moduleId}`);
@@ -69,11 +42,6 @@ async function callServerLocal(moduleId, method, args) {
     }
     return fn.apply(instance, args);
 }
-/**
- * @param {string} moduleId
- * @param {string} method
- * @param {unknown[]} args
- */
 async function callServerHttp(moduleId, method, args) {
     let rpcPath = (typeof globalThis !== 'undefined' && globalThis.__VMZ_RPC_PATH) || DEFAULT_RPC_PATH;
     // Node undici `fetch` rejects relative URLs; browsers accept path-only.
@@ -104,17 +72,11 @@ function exportGuess(moduleId) {
     const base = moduleId.split('/').pop() || 'Server';
     return `${base}Server`;
 }
-/**
- * @param {RpcRequest} body
- */
 export async function handleRpc(body) {
     return callServerLocal(body.moduleId, body.method, body.args ?? []);
 }
 /**
  * Match REST route from `vmz-routes.json`.
- * @param {string} verb
- * @param {string} pathname
- * @returns {Route | null}
  */
 export function matchRoute(verb, pathname) {
     const v = verb.toUpperCase();
@@ -122,13 +84,10 @@ export function matchRoute(verb, pathname) {
 }
 /**
  * Build `callServerLocal` args from a Fetch Request for REST routes.
- * GET/HEAD → `[]`. JSON POST/PUT/PATCH → `[body]`. form-urlencoded → `[record]`.
- * Multipart → `[record]` where File/Blob parts stay as File/Blob (tool-site binary upload).
+ * GET/HEAD �?`[]`. JSON POST/PUT/PATCH �?`[body]`. form-urlencoded �?`[record]`.
+ * Multipart �?`[record]` where File/Blob parts stay as File/Blob (tool-site binary upload).
  * Octet-stream PUT also forwards Upload resumable chunk headers (upload-id / chunk-index / chunk-total).
  * Extra args are ignored by zero-parameter server methods (JS).
- * @param {Request} request
- * @param {string} verb
- * @returns {Promise<unknown[]>}
  */
 async function routeArgsFromRequest(request, verb) {
     const v = String(verb || 'GET').toUpperCase();
@@ -147,12 +106,12 @@ async function routeArgsFromRequest(request, verb) {
         }
     }
     if (ctype.includes('multipart/form-data')) {
-        // Parse from raw bytes — undici Request.formData() can UTF-8-mangle high bytes in file parts
-        // (0xFF/0xFE → U+FFFD), which breaks Upload binary / tool-site intakes.
+        // Parse from raw bytes �?undici Request.formData() can UTF-8-mangle high bytes in file parts
+        // (0xFF/0xFE �?U+FFFD), which breaks Upload binary / tool-site intakes.
         const buf = Buffer.from(await request.arrayBuffer());
         return [parseMultipartBuffer(buf, ctype)];
     }
-    // Object-store PUT / resumable chunk PUT — keep bytes (never request.text()).
+    // Object-store PUT / resumable chunk PUT �?keep bytes (never request.text()).
     if (ctype.includes('application/octet-stream') ||
         ((v === 'PUT' || v === 'PATCH') && !ctype.includes('json') && !ctype.includes('x-www-form-urlencoded'))) {
         const buf = Buffer.from(await request.arrayBuffer());
@@ -180,8 +139,6 @@ async function routeArgsFromRequest(request, verb) {
 /**
  * Web Standards Fetch entry for ServerArtifact hosts (Node adapter, worker/edge parity).
  * Handles RPC + public ServerRoute only; static/SSR stay on Node host options.
- * @param {Request} request
- * @returns {Promise<Response>}
  */
 export async function handleFetchRequest(request) {
     const url = new URL(request.url);
@@ -209,9 +166,6 @@ export async function handleFetchRequest(request) {
 /**
  * Node `http.createServer` listener: RPC + REST + optional static / SSR index.
  * RPC/REST go through {@link handleFetchRequest} so Node and Fetch hosts share one core.
- * @param {import('node:http').IncomingMessage} req
- * @param {import('node:http').ServerResponse} res
- * @param {NodeRequestOptions} [opts]
  */
 export async function handleNodeRequest(req, res, opts = {}) {
     const host = req.headers.host || '127.0.0.1';
@@ -225,9 +179,8 @@ export async function handleNodeRequest(req, res, opts = {}) {
             const response = await handleFetchRequest(request);
             return await writeFetchResponse(res, response);
         }
-        // Static first for assets + DocumentMount (`/d/…`) so docs aren't swallowed by SSR 404 shells.
-        // static route HTML (`index.html`, `about/index.html`, …) is a CDN/deploy projection only —
-        // when Server Host SSR is active, those files must not shadow live render (local/dev ≡ SSR truth).
+        // Static first for assets + DocumentMount (`/d/�`) so docs aren't swallowed by SSR 404 shells.
+        // static route HTML (`index.html`, `about/index.html`, �? is a CDN/deploy projection only �?        // when Server Host SSR is active, those files must not shadow live render (local/dev �?SSR truth).
         if (verb === 'GET' && opts.distDir) {
             const nodePath = await import('node:path');
             const { readFile, stat } = await import('node:fs/promises');
@@ -263,7 +216,7 @@ export async function handleNodeRequest(req, res, opts = {}) {
                     /* ignore */
                 }
             };
-            // Do not abort on IncomingMessage `close` — that fires after a POST body is
+            // Do not abort on IncomingMessage `close` �?that fires after a POST body is
             // fully read (normal), which would cancel SSR before the first chunk.
             req.on('aborted', onClientGone);
             res.on('close', () => {
@@ -272,7 +225,6 @@ export async function handleNodeRequest(req, res, opts = {}) {
             });
             try {
                 if (typeof opts.renderPageStream === 'function') {
-                    /** @type {unknown} */
                     let body;
                     if (verb === 'POST') {
                         const ctype = String(req.headers['content-type'] || '');
@@ -329,7 +281,7 @@ export async function handleNodeRequest(req, res, opts = {}) {
         }
         if (!res.headersSent) {
             if (wantsBrowserHtml(req)) {
-                sendHtml(res, 404, browserErrorHtml(404, 'Not Found', `No page matched ${url.pathname}`));
+                sendHtml(res, 404, browserErrorHtml(404, 'Not Found', `No page matched ${url.pathname}`, undefined));
             }
             else {
                 sendJson(res, 404, { error: 'not found', path: url.pathname });
@@ -357,14 +309,8 @@ export async function handleNodeRequest(req, res, opts = {}) {
         }
     }
 }
-/**
- * @param {import('node:http').IncomingMessage} req
- * @param {URL} url
- * @returns {Promise<Request>}
- */
 async function incomingToRequest(req, url) {
     const method = (req.method || 'GET').toUpperCase();
-    /** @type {HeadersInit} */
     const headers = {};
     for (const [k, v] of Object.entries(req.headers)) {
         if (v == null)
@@ -378,10 +324,6 @@ async function incomingToRequest(req, url) {
     // Node undici requires duplex when constructing Request with a body.
     return new Request(url, { method, headers, body: raw, duplex: 'half' });
 }
-/**
- * @param {import('node:http').ServerResponse} res
- * @param {Response} response
- */
 async function writeFetchResponse(res, response) {
     const headers = {};
     response.headers.forEach((value, key) => {
@@ -396,10 +338,6 @@ async function writeFetchResponse(res, response) {
 }
 /**
  * Resolve a path under distDir; reject `..` escapes.
- * @param {string} distDir
- * @param {string} pathname
- * @param {typeof import('node:path')} nodePath
- * @returns {string | null}
  */
 function safeDistFile(distDir, pathname, nodePath) {
     let rel = decodeURIComponent(pathname.split('?')[0] || '/');
@@ -417,10 +355,7 @@ function safeDistFile(distDir, pathname, nodePath) {
 }
 /**
  * static profile emits per-route HTML beside client assets. That HTML is for CDN / local-static
- * delivery hosts — not for Server Host when SSR is available. DocumentMount stays static.
- * @param {string} file
- * @param {string} pathname
- * @param {typeof import('node:path')} nodePath
+ * delivery hosts �?not for Server Host when SSR is available. DocumentMount stays static.
  */
 function isWebStaticHtmlShadow(file, pathname, nodePath) {
     const ext = nodePath.extname(file).toLowerCase();
@@ -429,21 +364,16 @@ function isWebStaticHtmlShadow(file, pathname, nodePath) {
     let rel = decodeURIComponent(String(pathname || '').split('?')[0] || '/');
     if (!rel.startsWith('/'))
         rel = `/${rel}`;
-    // Integrated DocumentMount — keep static-first (see resolveDistStatic comment).
+    // Integrated DocumentMount �?keep static-first (see resolveDistStatic comment).
     if (rel === '/d' || rel.startsWith('/d/'))
         return false;
     return true;
 }
 /**
  * Static resolve for app assets + integrated document mounts:
- * `/d/` → `d/index.html`, `/d/zh-hans/guide` → `d/zh-hans/guide.html`.
- * @param {string} distDir
- * @param {string} pathname
- * @param {typeof import('node:path')} nodePath
- * @param {typeof import('node:fs/promises').stat} stat
- * @returns {Promise<string | null>}
+ * `/d/` �?`d/index.html`, `/d/zh-hans/guide` �?`d/zh-hans/guide.html`.
  */
-async function resolveDistStatic(distDir, pathname, nodePath, stat) {
+async function resolveDistStatic(distDir, pathname, nodePath, stat, _opts = {}) {
     const candidates = staticPathCandidates(pathname);
     for (const candidate of candidates) {
         const full = safeDistFile(distDir, candidate, nodePath);
@@ -466,15 +396,10 @@ async function resolveDistStatic(distDir, pathname, nodePath, stat) {
     }
     return null;
 }
-/**
- * @param {string} pathname
- * @returns {string[]}
- */
 function staticPathCandidates(pathname) {
     let rel = decodeURIComponent(pathname.split('?')[0] || '/');
     if (!rel.startsWith('/'))
         rel = `/${rel}`;
-    /** @type {string[]} */
     const out = [];
     const push = (p) => {
         if (p && !out.includes(p))
@@ -498,16 +423,11 @@ function staticPathCandidates(pathname) {
     }
     return out;
 }
-/** @param {string} p */
 function nodePathExt(p) {
     const base = p.split('/').pop() || '';
     const i = base.lastIndexOf('.');
     return i > 0 ? base.slice(i) : '';
 }
-/**
- * @param {string} filePath
- * @param {typeof import('node:path')} nodePath
- */
 function contentType(filePath, nodePath) {
     const ext = nodePath.extname(filePath).toLowerCase();
     switch (ext) {
@@ -528,9 +448,6 @@ function contentType(filePath, nodePath) {
             return 'application/octet-stream';
     }
 }
-/**
- * @param {import('node:http').IncomingMessage} req
- */
 function readJson(req) {
     return new Promise((resolve, reject) => {
         const chunks = [];
@@ -547,24 +464,17 @@ function readJson(req) {
         req.on('error', reject);
     });
 }
-/**
- * @param {import('node:http').IncomingMessage} req
- * @returns {Promise<Buffer>}
- */
 function readRawBody(req) {
     return new Promise((resolve, reject) => {
         const chunks = [];
         req.on('data', (c) => chunks.push(c));
-        // Buffer — never utf8-string: multipart File bytes must survive (Upload binary gate).
+        // Buffer �?never utf8-string: multipart File bytes must survive (Upload binary gate).
         req.on('end', () => resolve(Buffer.concat(chunks)));
         req.on('error', reject);
     });
 }
 /**
  * Buffer-safe multipart/form-data parser (file parts stay binary).
- * @param {Buffer} buf
- * @param {string} contentType
- * @returns {Record<string, unknown>}
  */
 function parseMultipartBuffer(buf, contentType) {
     const bm = /boundary=(?:"([^"]+)"|([^;\s]+))/i.exec(String(contentType || ''));
@@ -573,7 +483,6 @@ function parseMultipartBuffer(buf, contentType) {
         throw new Error('multipart: missing boundary');
     }
     const sep = Buffer.from(`--${boundary}`);
-    /** @type {Record<string, unknown>} */
     const out = {};
     let start = indexOfBuffer(buf, sep, 0);
     if (start < 0)
@@ -604,7 +513,7 @@ function parseMultipartBuffer(buf, contentType) {
                 if (fileM) {
                     const filename = fileM[1] || 'upload.bin';
                     const type = typeM ? String(typeM[1]).trim() : 'application/octet-stream';
-                    // Copy body — File may outlive the request buffer.
+                    // Copy body �?File may outlive the request buffer.
                     const copy = Buffer.from(body);
                     const file = new File([copy], filename, { type });
                     const prev = out[key];
@@ -629,11 +538,6 @@ function parseMultipartBuffer(buf, contentType) {
     }
     return out;
 }
-/**
- * @param {Buffer} hay
- * @param {Buffer} needle
- * @param {number} from
- */
 function indexOfBuffer(hay, needle, from) {
     if (!needle.length)
         return from;
@@ -646,11 +550,6 @@ function indexOfBuffer(hay, needle, from) {
     }
     return -1;
 }
-/**
- * @param {string} raw
- * @param {string} contentType
- * @returns {Record<string, string> | string}
- */
 function parseFormBody(raw, contentType) {
     if (!raw)
         return {};
@@ -667,10 +566,6 @@ function parseFormBody(raw, contentType) {
         return { raw };
     }
 }
-/**
- * @param {import('node:http').IncomingMessage} req
- * @returns {boolean}
- */
 function wantsBrowserHtml(req) {
     const accept = String(req.headers?.accept || '');
     const method = String(req.method || 'GET').toUpperCase();
@@ -697,11 +592,7 @@ function wantsBrowserHtml(req) {
 }
 /**
  * Browser-facing error document (no N-API). Used when SSR returns null or throws
- * on a document navigation — must not fall back to API-shaped JSON.
- * @param {number} status
- * @param {string} title
- * @param {string} message
- * @param {string} [stack]
+ * on a document navigation �?must not fall back to API-shaped JSON.
  */
 function browserErrorHtml(status, title, message, stack) {
     const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
@@ -728,17 +619,12 @@ function browserErrorHtml(status, title, message, stack) {
     <h1>${esc(title)}</h1>
     <pre>${esc(message)}</pre>
     ${stackBlock}
-    <p class="hint">Document navigation returns HTML errors — not API JSON.</p>
+    <p class="hint">Document navigation returns HTML errors �?not API JSON.</p>
   </main>
 </body>
 </html>
 `;
 }
-/**
- * @param {import('node:http').ServerResponse} res
- * @param {number} status
- * @param {unknown} body
- */
 function sendJson(res, status, body) {
     const payload = JSON.stringify(body);
     res.writeHead(status, {
@@ -747,11 +633,6 @@ function sendJson(res, status, body) {
     });
     res.end(payload);
 }
-/**
- * @param {import('node:http').ServerResponse} res
- * @param {number} status
- * @param {string} html
- */
 function sendHtml(res, status, html) {
     const payload = typeof html === 'string' ? html : String(html);
     res.writeHead(status, {
@@ -763,10 +644,6 @@ function sendHtml(res, status, html) {
 /**
  * Stream HTML without buffering the full document (event-flow / stream SSR host).
  * Honors AbortSignal + response destroy for cancel; awaits drain for backpressure.
- * @param {import('node:http').ServerResponse} res
- * @param {number} status
- * @param {AsyncIterable<string> | Iterable<string> | AsyncGenerator<string, any, any>} source
- * @param {AbortSignal} [signal]
  */
 async function sendHtmlStream(res, status, source, signal) {
     const aborted = () => Boolean(signal?.aborted || res.destroyed || res.writableEnded || !res.writable);
@@ -775,8 +652,8 @@ async function sendHtmlStream(res, status, source, signal) {
         'transfer-encoding': 'chunked',
         'cache-control': 'no-cache',
     };
-    // Defer writeHead until the first successful chunk so SSR throw → clean 500
-    // (not headersSent + destroy → ERR_EMPTY_RESPONSE).
+    // Defer writeHead until the first successful chunk so SSR throw �?clean 500
+    // (not headersSent + destroy �?ERR_EMPTY_RESPONSE).
     let started = false;
     try {
         for await (const chunk of source) {
@@ -814,26 +691,19 @@ async function sendHtmlStream(res, status, source, signal) {
     catch (err) {
         if (aborted())
             return;
-        // Before headers: let outer handler sendJson(500). After headers: rethrow → destroy.
+        // Before headers: let outer handler sendJson(500). After headers: rethrow �?destroy.
         throw err;
     }
     if (started && !res.writableEnded && !res.destroyed) {
         res.end();
     }
 }
-/**
- * @param {import('node:http').ServerResponse} res
- * @param {number} status
- * @param {Buffer} body
- * @param {string} type
- */
 function sendBytes(res, status, body, type) {
-    /** @type {Record<string, string | number>} */
     const headers = {
         'content-type': type,
         'content-length': body.byteLength,
     };
-    // Dev: stylesheets are rebuilt in-place — never cache @import siblings (VMZ-8).
+    // Dev: stylesheets are rebuilt in-place �?never cache @import siblings (VMZ-8).
     if (process.env.VMZ_DEV === '1' && typeof type === 'string' && type.startsWith('text/css')) {
         headers['cache-control'] = 'no-store';
     }

package/dist/{vmz-dom.d.ts → faces/vmz-dom.d.ts}

@@ -1,5 +1,5 @@
 /**
- * App-dist alias: compiler copies dom.js → vmz-dom.js.
+ * App-dist alias: compiler copies dom.js �?vmz-dom.js.
  * Package-local serve-host imports this path during `@vmz/core` build.
  */
 export * from './dom.js';

package/dist/{vmz-dom.js → faces/vmz-dom.js}

@@ -1,6 +1,5 @@
-// @ts-nocheck
 /**
- * App-dist alias: compiler copies dom.js → vmz-dom.js.
+ * App-dist alias: compiler copies dom.js �?vmz-dom.js.
  * Package-local serve-host imports this path during `@vmz/core` build.
  */
 export * from './dom.js';

package/dist/{vmz-runtime.d.ts → faces/vmz-runtime.d.ts}

@@ -1,5 +1,5 @@
 /**
- * App-dist alias: compiler copies server.js → vmz-runtime.js.
+ * App-dist alias: compiler copies server.js �?vmz-runtime.js.
  * Package-local serve-host imports this path during `@vmz/core` build.
  */
 export * from './server.js';

package/dist/{vmz-runtime.js → faces/vmz-runtime.js}

@@ -1,6 +1,5 @@
-// @ts-nocheck
 /**
- * App-dist alias: compiler copies server.js → vmz-runtime.js.
+ * App-dist alias: compiler copies server.js �?vmz-runtime.js.
  * Package-local serve-host imports this path during `@vmz/core` build.
  */
 export * from './server.js';

package/dist/host/deployment-registry.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Deployment graph — component registry bootstrap (shared by all SSR/DOM hosts).
+ * Parse/validate and graph queries delegate to Rust vmz-artifacts via N-API.
+ */
+import type { BootstrapComponentRegistryOpts, ComponentEntry, ComponentRegistryMap, DedupeComponentEntriesOpts, DeploymentDocument, ImportComponentEntriesOpts, LoadComponentEntriesOpts } from '../shared/host.types.js';
+export declare const DEPLOYMENT_SCHEMA = "vmz.deployment.v0";
+export declare function readDeploymentDocument(distDir: string, opts?: {
+    strict?: boolean;
+}): DeploymentDocument | null;
+export declare function componentEntriesFromDeployment(deployment: DeploymentDocument): ComponentEntry[];
+export declare function collectDependsOnClosure(deployment: DeploymentDocument, rootChunkIds: string[]): Set<string>;
+export declare function dedupeComponentEntriesByTag(entries: ComponentEntry[], opts?: DedupeComponentEntriesOpts): ComponentEntry[];
+export declare function mergeExplicitComponentEntries(entries: ComponentEntry[], explicit?: Record<string, string>): ComponentEntry[];
+export declare function loadComponentEntries(distDir: string, opts?: LoadComponentEntriesOpts): Promise<ComponentEntry[]>;
+export declare function importAndRegisterComponentEntries(distDir: string, entries: ComponentEntry[], registerComponents: (map: ComponentRegistryMap) => void, opts?: ImportComponentEntriesOpts): Promise<ComponentRegistryMap>;
+export declare function bootstrapComponentRegistry(distDir: string, registerComponents: (map: ComponentRegistryMap) => void, opts?: BootstrapComponentRegistryOpts): Promise<ComponentRegistryMap>;

package/dist/{deployment-registry.js → host/deployment-registry.js}

@@ -1,6 +1,5 @@
-// @ts-nocheck
 /**
- * Deployment graph → component registry bootstrap (shared by all SSR/DOM hosts).
+ * Deployment graph — component registry bootstrap (shared by all SSR/DOM hosts).
  * Parse/validate and graph queries delegate to Rust vmz-artifacts via N-API.
  */
 import fs from 'node:fs';
@@ -8,19 +7,10 @@ import path from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { requireNativeFn } from './native-addon.js';
 export const DEPLOYMENT_SCHEMA = 'vmz.deployment.v0';
-/**
- * @param {string} jsonText
- * @returns {any}
- */
 function parseDeploymentJson(jsonText) {
     requireNativeFn('deploymentValidate')(jsonText);
     return JSON.parse(jsonText);
 }
-/**
- * @param {string} distDir
- * @param {{ strict?: boolean }} [opts]
- * @returns {any | null}
- */
 export function readDeploymentDocument(distDir, opts = {}) {
     const strict = opts.strict === true;
     const filePath = path.join(distDir, 'vmz-deployment.json');
@@ -48,33 +38,17 @@ export function readDeploymentDocument(distDir, opts = {}) {
         return null;
     }
 }
-/**
- * @param {any} deployment
- * @returns {Array<{ chunkId: string, name: string, entry: string, source: string }>}
- */
 export function componentEntriesFromDeployment(deployment) {
     const json = JSON.stringify(deployment);
     return requireNativeFn('deploymentComponentEntries')(json);
 }
-/**
- * @param {any} deployment
- * @param {string[]} rootChunkIds
- * @returns {Set<string>}
- */
 export function collectDependsOnClosure(deployment, rootChunkIds) {
     const json = JSON.stringify(deployment);
     const ids = requireNativeFn('deploymentDependsOnClosure')(json, rootChunkIds);
     return new Set(ids);
 }
-/**
- * Resolve tag conflicts; strict mode throws, dev mode warns and keeps last chunkId.
- * @param {Array<{ chunkId: string, name: string, entry: string, source?: string }>} entries
- * @param {{ strict?: boolean }} [opts]
- * @returns {Array<{ chunkId: string, name: string, entry: string, source?: string }>}
- */
 export function dedupeComponentEntriesByTag(entries, opts = {}) {
     const strict = opts.strict === true;
-    /** @type {Map<string, { chunkId: string, name: string, entry: string, source?: string }>} */
     const byTag = new Map();
     for (const e of entries) {
         const prev = byTag.get(e.name);
@@ -88,13 +62,7 @@ export function dedupeComponentEntriesByTag(entries, opts = {}) {
     }
     return [...byTag.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
-/**
- * @param {Array<{ chunkId: string, name: string, entry: string, source?: string }>} entries
- * @param {Record<string, string> | undefined} explicit name → chunkId (no .client.js)
- * @returns {Array<{ chunkId: string, name: string, entry: string, source?: string }>}
- */
 export function mergeExplicitComponentEntries(entries, explicit) {
-    /** @type {Map<string, { chunkId: string, name: string, entry: string, source?: string }>} */
     const byTag = new Map(entries.map((e) => [e.name, e]));
     if (explicit) {
         for (const [name, chunk] of Object.entries(explicit)) {
@@ -109,19 +77,9 @@ export function mergeExplicitComponentEntries(entries, explicit) {
     }
     return [...byTag.values()].sort((a, b) => a.name.localeCompare(b.name));
 }
-/**
- * @param {string} distDir
- * @param {{
- *   strict?: boolean,
- *   closureRoots?: string[],
- *   explicit?: Record<string, string>,
- * }} [opts]
- * @returns {Promise<Array<{ chunkId: string, name: string, entry: string, source?: string }>>}
- */
 export async function loadComponentEntries(distDir, opts = {}) {
     const strict = opts.strict === true;
     const deployment = readDeploymentDocument(distDir, { strict });
-    /** @type {Array<{ chunkId: string, name: string, entry: string, source?: string }>} */
     let entries = [];
     if (deployment) {
         entries = componentEntriesFromDeployment(deployment);
@@ -133,22 +91,10 @@ export async function loadComponentEntries(distDir, opts = {}) {
     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
- * @param {Array<{ chunkId: string, name: string, entry: string }>} entries
- * @param {(map: Record<string, unknown>) => void} registerComponents
- * @param {{
- *   cacheBust?: string | number,
- *   loaded?: Set<string>,
- * }} [opts]
- * @returns {Promise<Record<string, unknown>>}
- */
 export async function importAndRegisterComponentEntries(distDir, entries, registerComponents, opts = {}) {
-    /** @type {Record<string, unknown>} */
     const map = {};
     const loaded = opts.loaded ?? null;
     for (const entry of entries) {
@@ -168,19 +114,6 @@ export async function importAndRegisterComponentEntries(distDir, entries, regist
         registerComponents(map);
     return map;
 }
-/**
- * Bootstrap component registry from deployment (all or closure — no directory fallback).
- * @param {string} distDir
- * @param {(map: Record<string, unknown>) => void} registerComponents
- * @param {{
- *   strict?: boolean,
- *   closureRoots?: string[],
- *   explicit?: Record<string, string>,
- *   cacheBust?: string | number,
- *   loaded?: Set<string>,
- *   preload?: 'all' | 'closure' | 'none',
- * }} [opts]
- */
 export async function bootstrapComponentRegistry(distDir, registerComponents, opts = {}) {
     const preload = opts.preload ?? (opts.closureRoots?.length ? 'closure' : 'all');
     if (preload === 'none')

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

@@ -0,0 +1,14 @@
+/**
+ * Discover compiled client component modules from Deployment Plan only.
+ * Shared by serve-host SSR, static emit, and test hosts (plan-only host).
+ */
+import type { ClientComponentListEntry, ComponentRegistryMap, ListClientComponentsOpts, PreloadComponentRegistryOpts } from '../shared/host.types.js';
+export { DEPLOYMENT_SCHEMA, readDeploymentDocument, componentEntriesFromDeployment, collectDependsOnClosure, dedupeComponentEntriesByTag, mergeExplicitComponentEntries, loadComponentEntries, importAndRegisterComponentEntries, bootstrapComponentRegistry, } from './deployment-registry.js';
+export { createRenderHost } from './render-host.js';
+export declare function listClientComponents(dir: string, opts?: ListClientComponentsOpts): Promise<ClientComponentListEntry[]>;
+export declare function listClientComponentsSync(dir: string, opts?: ListClientComponentsOpts): ClientComponentListEntry[];
+export declare function mergeComponentEntries(entries: ClientComponentListEntry[], explicit?: Record<string, string>): ClientComponentListEntry[];
+export declare function resolveComponentEntries(distDir: string, explicit?: Record<string, string>, opts?: ListClientComponentsOpts & {
+    closureRoots?: string[];
+}): Promise<ClientComponentListEntry[]>;
+export declare function preloadComponentRegistry(distDir: string, registerComponents: (map: ComponentRegistryMap) => void, opts?: PreloadComponentRegistryOpts): Promise<ComponentRegistryMap>;