@vmz/core 0.1.32 → 0.2.1

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

@@ -1,44 +1,22 @@
-// @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.
+ * 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.
@@ -47,21 +25,17 @@ export async function callServer(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 Ctor = mod.default ?? mod[exportGuess(moduleId)];
-    if (typeof Ctor !== 'function') {
+    const mod = (await import(typeof spec === 'string' ? spec : spec.href));
+    const exported = mod.default ?? mod[exportGuess(moduleId)];
+    if (typeof exported !== 'function') {
         throw new Error(`vmz:runtime: no class export for ${moduleId}`);
     }
+    const Ctor = exported;
     const instance = new Ctor();
     const fn = instance[method];
     if (typeof fn !== 'function') {
@@ -69,11 +43,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 +73,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();
@@ -126,9 +89,6 @@ export function matchRoute(verb, pathname) {
  * 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 +107,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
+        // 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,15 +140,13 @@ 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);
     const verb = (request.method || 'GET').toUpperCase();
     try {
         if (verb === 'POST' && url.pathname === DEFAULT_RPC_PATH) {
-            const body = await request.json();
+            const body = (await request.json());
             const result = await handleRpc(body);
             return Response.json(result);
         }
@@ -209,9 +167,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';
@@ -227,9 +182,9 @@ export async function handleNodeRequest(req, res, opts = {}) {
         }
         // 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).
+        // 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 nodePath = (await import('node:path'));
             const { readFile, stat } = await import('node:fs/promises');
             const file = await resolveDistStatic(opts.distDir, url.pathname, nodePath, stat, {
                 cookieHeader: String(req.headers.cookie || ''),
@@ -244,7 +199,8 @@ export async function handleNodeRequest(req, res, opts = {}) {
                     return sendBytes(res, 200, body, contentType(file, nodePath));
                 }
                 catch (err) {
-                    if (err && (err.code === 'ENOENT' || err.code === 'EISDIR')) {
+                    const code = err && typeof err === 'object' && 'code' in err ? err.code : undefined;
+                    if (code === 'ENOENT' || code === 'EISDIR') {
                         /* fall through */
                     }
                     else {
@@ -272,7 +228,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'] || '');
@@ -292,7 +247,7 @@ export async function handleNodeRequest(req, res, opts = {}) {
                         body,
                     });
                     if (rendered) {
-                        if (typeof rendered === 'object' && rendered.redirect) {
+                        if (typeof rendered === 'object' && 'redirect' in rendered && rendered.redirect) {
                             const status = Number(rendered.status) || 302;
                             const headers = {
                                 Location: String(rendered.redirect),
@@ -303,7 +258,7 @@ export async function handleNodeRequest(req, res, opts = {}) {
                             return;
                         }
                         const status = rendered && typeof rendered === 'object' && 'status' in rendered ? Number(rendered.status) || 200 : 200;
-                        const stream = rendered && typeof rendered === 'object' && rendered.stream ? rendered.stream : rendered;
+                        const stream = rendered && typeof rendered === 'object' && 'stream' in rendered && rendered.stream ? rendered.stream : rendered;
                         return await sendHtmlStream(res, status, stream, ac.signal);
                     }
                 }
@@ -329,7 +284,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 +312,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 +327,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 +341,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] || '/');
@@ -418,9 +359,6 @@ 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
  */
 function isWebStaticHtmlShadow(file, pathname, nodePath) {
     const ext = nodePath.extname(file).toLowerCase();
@@ -437,13 +375,8 @@ function isWebStaticHtmlShadow(file, pathname, nodePath) {
 /**
  * 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>}
  */
-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 +399,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 +426,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,13 +451,12 @@ function contentType(filePath, nodePath) {
             return 'application/octet-stream';
     }
 }
-/**
- * @param {import('node:http').IncomingMessage} req
- */
 function readJson(req) {
     return new Promise((resolve, reject) => {
         const chunks = [];
-        req.on('data', (c) => chunks.push(c));
+        req.on('data', (c) => {
+            chunks.push(typeof c === 'string' ? Buffer.from(c) : c);
+        });
         req.on('end', () => {
             try {
                 const raw = Buffer.concat(chunks).toString('utf8') || '{}';
@@ -547,14 +469,12 @@ 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));
+        req.on('data', (c) => {
+            chunks.push(typeof c === 'string' ? Buffer.from(c) : c);
+        });
         // Buffer — never utf8-string: multipart File bytes must survive (Upload binary gate).
         req.on('end', () => resolve(Buffer.concat(chunks)));
         req.on('error', reject);
@@ -562,9 +482,6 @@ function readRawBody(req) {
 }
 /**
  * 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 +490,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)
@@ -629,11 +545,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,31 +557,23 @@ function indexOfBuffer(hay, needle, from) {
     }
     return -1;
 }
-/**
- * @param {string} raw
- * @param {string} contentType
- * @returns {Record<string, string> | string}
- */
 function parseFormBody(raw, contentType) {
-    if (!raw)
+    const text = typeof raw === 'string' ? raw : raw.toString('utf8');
+    if (!text)
         return {};
     if (contentType.includes('application/x-www-form-urlencoded')) {
         const out = {};
-        for (const [k, v] of new URLSearchParams(raw))
+        for (const [k, v] of new URLSearchParams(text))
             out[k] = v;
         return out;
     }
     try {
-        return JSON.parse(raw);
+        return JSON.parse(text);
     }
     catch {
-        return { raw };
+        return { raw: text };
     }
 }
-/**
- * @param {import('node:http').IncomingMessage} req
- * @returns {boolean}
- */
 function wantsBrowserHtml(req) {
     const accept = String(req.headers?.accept || '');
     const method = String(req.method || 'GET').toUpperCase();
@@ -698,10 +601,6 @@ 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]
  */
 function browserErrorHtml(status, title, message, stack) {
     const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
@@ -734,11 +633,6 @@ function browserErrorHtml(status, title, message, stack) {
 </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 +641,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 +652,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);
@@ -821,14 +706,7 @@ async function sendHtmlStream(res, status, source, signal) {
         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,

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>;