@vmz/core 0.1.8 → 0.1.10

package/dist/deployment-registry.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Deployment graph → component registry bootstrap (shared by all SSR/DOM hosts).
+ * Replaces ad-hoc registerComponents calls with an explicit preload contract.
+ */
+export declare const DEPLOYMENT_SCHEMA = "vmz.deployment.v0";
+/**
+ * @param {string} distDir
+ * @param {{ strict?: boolean }} [opts]
+ * @returns {any | null}
+ */
+export declare function readDeploymentDocument(distDir: any, opts?: {}): any;
+/**
+ * @param {any} deployment
+ * @returns {Array<{ chunkId: string, name: string, entry: string, source: string }>}
+ */
+export declare function componentEntriesFromDeployment(deployment: any): any[];
+/**
+ * @param {any} deployment
+ * @param {string[]} rootChunkIds
+ * @returns {Set<string>}
+ */
+export declare function collectDependsOnClosure(deployment: any, rootChunkIds: any): Set<unknown>;
+/**
+ * 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 declare function dedupeComponentEntriesByTag(entries: any, opts?: {}): any[];
+/**
+ * @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 declare function mergeExplicitComponentEntries(entries: any, explicit: any): unknown[];
+/**
+ * @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 declare function loadComponentEntries(distDir: any, opts?: {}): Promise<any[]>;
+/**
+ * @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 declare function importAndRegisterComponentEntries(distDir: any, entries: any, registerComponents: any, opts?: {}): Promise<{}>;
+/**
+ * Bootstrap component registry from deployment (all, closure, or 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 declare function bootstrapComponentRegistry(distDir: any, registerComponents: any, opts?: {}): Promise<{}>;

package/dist/deployment-registry.js

@@ -0,0 +1,256 @@
+// @ts-nocheck
+/**
+ * Deployment graph → component registry bootstrap (shared by all SSR/DOM hosts).
+ * Replaces ad-hoc registerComponents calls with an explicit preload contract.
+ */
+import fs from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+export const DEPLOYMENT_SCHEMA = 'vmz.deployment.v0';
+/**
+ * @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');
+    if (!fs.existsSync(filePath)) {
+        if (strict) {
+            throw new Error(`vmz: missing vmz-deployment.json under ${distDir} (strict deployment mode)`);
+        }
+        return null;
+    }
+    let raw;
+    try {
+        raw = fs.readFileSync(filePath, 'utf8');
+    }
+    catch (e) {
+        if (strict)
+            throw new Error(`vmz: cannot read vmz-deployment.json: ${e instanceof Error ? e.message : e}`);
+        return null;
+    }
+    let doc;
+    try {
+        doc = JSON.parse(raw);
+    }
+    catch (e) {
+        if (strict)
+            throw new Error(`vmz: invalid vmz-deployment.json: ${e instanceof Error ? e.message : e}`);
+        return null;
+    }
+    if (doc.schema !== DEPLOYMENT_SCHEMA) {
+        if (strict)
+            throw new Error(`vmz: unsupported deployment schema ${doc.schema}`);
+        return null;
+    }
+    return doc;
+}
+/**
+ * @param {any} deployment
+ * @returns {Array<{ chunkId: string, name: string, entry: string, source: string }>}
+ */
+export function componentEntriesFromDeployment(deployment) {
+    /** @type {Array<{ chunkId: string, name: string, entry: string, source: string }>} */
+    const out = [];
+    for (const unit of deployment.units || []) {
+        if (unit?.kind !== 'component')
+            continue;
+        const chunkId = String(unit.chunkId || '').replace(/\\/g, '/');
+        const name = chunkId.split('/').pop();
+        if (!name)
+            continue;
+        const entry = String(unit.clientEntry || `${chunkId}.client.js`).replace(/\\/g, '/');
+        out.push({
+            chunkId,
+            name,
+            entry,
+            source: String(unit.source || ''),
+        });
+    }
+    return out.sort((a, b) => a.chunkId.localeCompare(b.chunkId));
+}
+/**
+ * @param {any} deployment
+ * @param {string[]} rootChunkIds
+ * @returns {Set<string>}
+ */
+export function collectDependsOnClosure(deployment, rootChunkIds) {
+    /** @type {Map<string, any>} */
+    const byId = new Map();
+    for (const unit of deployment.units || []) {
+        byId.set(String(unit.chunkId || '').replace(/\\/g, '/'), unit);
+    }
+    /** @type {Set<string>} */
+    const out = new Set();
+    /** @type {string[]} */
+    const stack = rootChunkIds.map((id) => String(id).replace(/\\/g, '/')).filter(Boolean);
+    while (stack.length) {
+        const id = stack.pop();
+        if (!id || out.has(id))
+            continue;
+        out.add(id);
+        const unit = byId.get(id);
+        if (!unit)
+            continue;
+        for (const dep of unit.dependsOn || []) {
+            const d = String(dep).replace(/\\/g, '/');
+            if (!out.has(d))
+                stack.push(d);
+        }
+    }
+    return out;
+}
+/**
+ * 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);
+        if (prev && prev.chunkId !== e.chunkId) {
+            const msg = `vmz: component tag <${e.name}> maps to both ${prev.chunkId} and ${e.chunkId}`;
+            if (strict)
+                throw new Error(msg);
+            console.warn(`${msg}; using ${e.chunkId}`);
+        }
+        byTag.set(e.name, e);
+    }
+    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)) {
+            const chunkId = String(chunk).replace(/\\/g, '/');
+            byTag.set(name, {
+                chunkId,
+                name,
+                entry: `${chunkId}.client.js`,
+                source: '',
+            });
+        }
+    }
+    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);
+        if (opts.closureRoots?.length) {
+            const closure = collectDependsOnClosure(deployment, opts.closureRoots);
+            entries = entries.filter((e) => closure.has(e.chunkId));
+        }
+    }
+    else if (!strict) {
+        entries = await listComponentEntriesFromDirectory(distDir);
+    }
+    entries = mergeExplicitComponentEntries(entries, opts.explicit);
+    return dedupeComponentEntriesByTag(entries, { strict });
+}
+/**
+ * @param {string} distDir
+ * @returns {Promise<Array<{ chunkId: string, name: string, entry: string }>>}
+ */
+async function listComponentEntriesFromDirectory(distDir) {
+    const folder = path.join(distDir, 'components');
+    /** @type {string[]} */
+    let files = [];
+    try {
+        files = await readdir(folder);
+    }
+    catch {
+        return [];
+    }
+    return files
+        .filter((name) => name.endsWith('.client.js'))
+        .map((f) => {
+        const name = f.replace(/\.client\.js$/, '');
+        const chunkId = `components/${name}`;
+        return { chunkId, name, entry: `components/${name}.client.js` };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * @param {string} distDir
+ * @param {Array<{ chunkId: string, name: string, entry: string }>} entries
+ * @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) {
+        if (loaded && loaded.has(entry.chunkId))
+            continue;
+        const abs = path.join(distDir, entry.entry);
+        let href = pathToFileURL(abs).href;
+        if (opts.cacheBust != null && opts.cacheBust !== '') {
+            href = `${href}?t=${encodeURIComponent(String(opts.cacheBust))}`;
+        }
+        const mod = await import(href);
+        map[entry.name] = mod.default;
+        if (loaded)
+            loaded.add(entry.chunkId);
+    }
+    if (Object.keys(map).length)
+        registerComponents(map);
+    return map;
+}
+/**
+ * Bootstrap component registry from deployment (all, closure, or 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')
+        return {};
+    const loadOpts = {
+        strict: opts.strict,
+        explicit: opts.explicit,
+        closureRoots: preload === 'closure' ? opts.closureRoots : undefined,
+    };
+    const entries = await loadComponentEntries(distDir, loadOpts);
+    return importAndRegisterComponentEntries(distDir, entries, registerComponents, {
+        cacheBust: opts.cacheBust,
+        loaded: opts.loaded,
+    });
+}

package/dist/dom-core.d.ts

@@ -39,7 +39,7 @@ export declare function __vmzPrecisionSnapshot(): {
     patchesByBinding: any;
 };
 export declare function noteDomCreate(): void;
-/** @param {Record<string, any>} map */
+/** @param {Record<string, any>} map — Prefer createRenderHost().ensureComponents(); process-global registry. */
 export declare function registerComponents(map: any): void;
 /** Sync registry lookup (SSR serialize / client). */
 export declare function getRegisteredComponent(name: any): any;

package/dist/dom-core.js

@@ -144,7 +144,7 @@ function noteDomMove() {
     if (precision.enabled)
         precision.domMoves++;
 }
-/** @param {Record<string, any>} map */
+/** @param {Record<string, any>} map — Prefer createRenderHost().ensureComponents(); process-global registry. */
 export function registerComponents(map) {
     Object.assign(components, map);
 }

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

@@ -0,0 +1,62 @@
+/**
+ * Discover compiled client component modules from dist (deployment graph or components/).
+ * Shared by serve-host SSR, static emit, and test hosts.
+ */
+export { DEPLOYMENT_SCHEMA, readDeploymentDocument, componentEntriesFromDeployment, collectDependsOnClosure, dedupeComponentEntriesByTag, mergeExplicitComponentEntries, loadComponentEntries, importAndRegisterComponentEntries, bootstrapComponentRegistry, } from './deployment-registry.js';
+export { createRenderHost } from './render-host.js';
+/**
+ * @param {string} dir
+ * @param {{ strict?: boolean }} [opts]
+ * @returns {Promise<Array<{ name: string, entry: string, chunkId?: string }>>}
+ */
+export declare function listClientComponents(dir: any, opts?: {}): Promise<{
+    name: any;
+    entry: any;
+    chunkId: any;
+}[]>;
+/**
+ * Sync variant for callers that already use fs sync (legacy static-emit helpers).
+ * @param {string} dir
+ * @param {{ strict?: boolean }} [opts]
+ * @returns {Array<{ name: string, entry: string, chunkId?: string }>}
+ */
+export declare function listClientComponentsSync(dir: any, opts?: {}): {
+    name: any;
+    entry: any;
+    chunkId: any;
+}[];
+/**
+ * @param {Array<{ name: string, entry: string, chunkId?: string }>} entries
+ * @param {Record<string, string> | undefined} explicit
+ * @returns {Array<{ name: string, entry: string, chunkId?: string }>}
+ */
+export declare function mergeComponentEntries(entries: any, explicit: any): {
+    name: any;
+    entry: any;
+    chunkId: any;
+}[];
+/**
+ * @param {string} distDir
+ * @param {Record<string, string> | undefined} [explicit]
+ * @param {{ strict?: boolean, closureRoots?: string[] }} [opts]
+ * @returns {Promise<Array<{ name: string, entry: string, chunkId?: string }>>}
+ */
+export declare function resolveComponentEntries(distDir: any, explicit: any, opts?: {}): Promise<{
+    name: any;
+    entry: any;
+    chunkId: any;
+}[]>;
+/**
+ * Import all (or filtered) client components and register for SSR / static emit / test hosts.
+ * @param {string} distDir
+ * @param {(map: Record<string, unknown>) => void} registerComponents
+ * @param {{
+ *   cacheBust?: string | number,
+ *   include?: (entry: { name: string, entry: string, chunkId?: string }) => boolean,
+ *   explicit?: Record<string, string>,
+ *   strict?: boolean,
+ *   closureRoots?: string[],
+ *   preload?: 'all' | 'closure' | 'none',
+ * }} [opts]
+ */
+export declare function preloadComponentRegistry(distDir: any, registerComponents: any, opts?: {}): Promise<{}>;

package/dist/list-client-components.js

@@ -0,0 +1,142 @@
+// @ts-nocheck
+/**
+ * Discover compiled client component modules from dist (deployment graph or components/).
+ * Shared by serve-host SSR, static emit, and test hosts.
+ */
+import fs from 'node:fs';
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { componentEntriesFromDeployment, mergeExplicitComponentEntries, readDeploymentDocument, } from './deployment-registry.js';
+export { DEPLOYMENT_SCHEMA, readDeploymentDocument, componentEntriesFromDeployment, collectDependsOnClosure, dedupeComponentEntriesByTag, mergeExplicitComponentEntries, loadComponentEntries, importAndRegisterComponentEntries, bootstrapComponentRegistry, } from './deployment-registry.js';
+export { createRenderHost } from './render-host.js';
+/**
+ * @param {string} dir
+ * @param {{ strict?: boolean }} [opts]
+ * @returns {Promise<Array<{ name: string, entry: string, chunkId?: string }>>}
+ */
+export async function listClientComponents(dir, opts = {}) {
+    const deployment = readDeploymentDocument(dir, { strict: opts.strict === true });
+    if (deployment) {
+        return componentEntriesFromDeployment(deployment).map((e) => ({
+            name: e.name,
+            entry: e.entry,
+            chunkId: e.chunkId,
+        }));
+    }
+    const folder = path.join(dir, 'components');
+    /** @type {string[]} */
+    let files = [];
+    try {
+        files = await readdir(folder);
+    }
+    catch {
+        return [];
+    }
+    return files
+        .filter((name) => name.endsWith('.client.js'))
+        .map((f) => {
+        const name = f.replace(/\.client\.js$/, '');
+        return { name, entry: `components/${name}.client.js`, chunkId: `components/${name}` };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * Sync variant for callers that already use fs sync (legacy static-emit helpers).
+ * @param {string} dir
+ * @param {{ strict?: boolean }} [opts]
+ * @returns {Array<{ name: string, entry: string, chunkId?: string }>}
+ */
+export function listClientComponentsSync(dir, opts = {}) {
+    const deployment = readDeploymentDocument(dir, { strict: opts.strict === true });
+    if (deployment) {
+        return componentEntriesFromDeployment(deployment).map((e) => ({
+            name: e.name,
+            entry: e.entry,
+            chunkId: e.chunkId,
+        }));
+    }
+    const folder = path.join(dir, 'components');
+    /** @type {string[]} */
+    let files = [];
+    try {
+        files = fs.readdirSync(folder);
+    }
+    catch {
+        return [];
+    }
+    return files
+        .filter((name) => name.endsWith('.client.js'))
+        .map((f) => {
+        const name = f.replace(/\.client\.js$/, '');
+        return { name, entry: `components/${name}.client.js`, chunkId: `components/${name}` };
+    })
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+/**
+ * @param {Array<{ name: string, entry: string, chunkId?: string }>} entries
+ * @param {Record<string, string> | undefined} explicit
+ * @returns {Array<{ name: string, entry: string, chunkId?: string }>}
+ */
+export function mergeComponentEntries(entries, explicit) {
+    const normalized = entries.map((e) => ({
+        chunkId: e.chunkId || `components/${e.name}`,
+        name: e.name,
+        entry: e.entry,
+    }));
+    return mergeExplicitComponentEntries(normalized, explicit).map((e) => ({
+        name: e.name,
+        entry: e.entry,
+        chunkId: e.chunkId,
+    }));
+}
+/**
+ * @param {string} distDir
+ * @param {Record<string, string> | undefined} [explicit]
+ * @param {{ strict?: boolean, closureRoots?: string[] }} [opts]
+ * @returns {Promise<Array<{ name: string, entry: string, chunkId?: string }>>}
+ */
+export async function resolveComponentEntries(distDir, explicit, opts = {}) {
+    const { loadComponentEntries } = await import('./deployment-registry.js');
+    const entries = await loadComponentEntries(distDir, {
+        strict: opts.strict,
+        closureRoots: opts.closureRoots,
+        explicit,
+    });
+    return entries.map((e) => ({ name: e.name, entry: e.entry, chunkId: e.chunkId }));
+}
+/**
+ * Import all (or filtered) client components and register for SSR / static emit / test hosts.
+ * @param {string} distDir
+ * @param {(map: Record<string, unknown>) => void} registerComponents
+ * @param {{
+ *   cacheBust?: string | number,
+ *   include?: (entry: { name: string, entry: string, chunkId?: string }) => boolean,
+ *   explicit?: Record<string, string>,
+ *   strict?: boolean,
+ *   closureRoots?: string[],
+ *   preload?: 'all' | 'closure' | 'none',
+ * }} [opts]
+ */
+export async function preloadComponentRegistry(distDir, registerComponents, opts = {}) {
+    let entries = await resolveComponentEntries(distDir, opts.explicit, {
+        strict: opts.strict,
+        closureRoots: opts.closureRoots,
+    });
+    if (opts.include)
+        entries = entries.filter((e) => opts.include(e));
+    /** @type {Record<string, unknown>} */
+    const map = {};
+    for (const entry of entries) {
+        const abs = path.join(distDir, entry.entry);
+        let href = pathToFileURL(abs).href;
+        if (opts.cacheBust != null && opts.cacheBust !== '') {
+            href = `${href}?t=${encodeURIComponent(String(opts.cacheBust))}`;
+        }
+        const mod = await import(href);
+        map[entry.name] = mod.default;
+    }
+    if (Object.keys(map).length)
+        registerComponents(map);
+    return map;
+}

package/dist/render-host.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Unified SSR/DOM render host — explicit deployment bootstrap before renderToString/stream/mount.
+ * Hosts must not call renderToString until ensureComponents() has run for the active closure.
+ */
+/**
+ * @param {string} distDir
+ * @param {{
+ *   strictDeployment?: boolean,
+ *   strict?: boolean,
+ *   explicit?: Record<string, string>,
+ *   cacheBust?: string | number,
+ *   preload?: 'all' | 'closure' | 'none',
+ *   closureRoots?: string[],
+ * }} [opts]
+ */
+export declare function createRenderHost(distDir: any, opts?: {}): Promise<{
+    distDir: any;
+    deployment: any;
+    dom: any;
+    loadedChunkIds: Set<unknown>;
+    ensureComponents: (rootChunkIds: any) => Promise<{}>;
+    closureChunkIds: (rootChunkIds: any) => Set<unknown>;
+    renderToString: any;
+    renderToStream: any;
+    mount: any;
+    hydrate: any;
+    resume: any;
+    destroy: any;
+    flushPending: any;
+    /** @deprecated Prefer ensureComponents via createRenderHost; low-level escape hatch. */
+    registerComponents: any;
+}>;

package/dist/render-host.js

@@ -0,0 +1,81 @@
+// @ts-nocheck
+/**
+ * Unified SSR/DOM render host — explicit deployment bootstrap before renderToString/stream/mount.
+ * Hosts must not call renderToString until ensureComponents() has run for the active closure.
+ */
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { bootstrapComponentRegistry, collectDependsOnClosure, loadComponentEntries, readDeploymentDocument, importAndRegisterComponentEntries, } from './deployment-registry.js';
+/**
+ * @param {string} distDir
+ * @param {{
+ *   strictDeployment?: boolean,
+ *   strict?: boolean,
+ *   explicit?: Record<string, string>,
+ *   cacheBust?: string | number,
+ *   preload?: 'all' | 'closure' | 'none',
+ *   closureRoots?: string[],
+ * }} [opts]
+ */
+export async function createRenderHost(distDir, opts = {}) {
+    const strict = opts.strictDeployment === true || opts.strict === true;
+    const domPath = path.join(distDir, 'vmz-dom.js');
+    const dom = await import(pathToFileURL(domPath).href);
+    const deployment = readDeploymentDocument(distDir, { strict });
+    /** @type {Set<string>} */
+    const loadedChunkIds = new Set();
+    const bootstrapOpts = {
+        strict,
+        explicit: opts.explicit,
+        cacheBust: opts.cacheBust,
+        loaded: loadedChunkIds,
+        preload: opts.preload ?? 'none',
+        closureRoots: opts.closureRoots,
+    };
+    if (bootstrapOpts.preload !== 'none') {
+        await bootstrapComponentRegistry(distDir, dom.registerComponents, bootstrapOpts);
+    }
+    /**
+     * Load component closure for root chunk ids (page + layouts + fixture).
+     * @param {string[]} rootChunkIds
+     */
+    async function ensureComponents(rootChunkIds) {
+        if (!rootChunkIds?.length)
+            return {};
+        const entries = await loadComponentEntries(distDir, {
+            strict,
+            closureRoots: rootChunkIds,
+            explicit: opts.explicit,
+        });
+        return importAndRegisterComponentEntries(distDir, entries, dom.registerComponents, {
+            cacheBust: opts.cacheBust,
+            loaded: loadedChunkIds,
+        });
+    }
+    /**
+     * Union closure chunk ids (pages + layouts) without importing yet.
+     * @param {string[]} rootChunkIds
+     */
+    function closureChunkIds(rootChunkIds) {
+        if (!deployment || !rootChunkIds?.length)
+            return new Set(rootChunkIds || []);
+        return collectDependsOnClosure(deployment, rootChunkIds);
+    }
+    return {
+        distDir,
+        deployment,
+        dom,
+        loadedChunkIds,
+        ensureComponents,
+        closureChunkIds,
+        renderToString: dom.renderToString.bind(dom),
+        renderToStream: dom.renderToStream.bind(dom),
+        mount: dom.mount.bind(dom),
+        hydrate: dom.hydrate?.bind(dom),
+        resume: dom.resume?.bind(dom),
+        destroy: dom.destroy?.bind(dom),
+        flushPending: dom.flushPending?.bind(dom),
+        /** @deprecated Prefer ensureComponents via createRenderHost; low-level escape hatch. */
+        registerComponents: dom.registerComponents.bind(dom),
+    };
+}

package/dist/serve-host.mjs

@@ -23,6 +23,7 @@ import { createRequire, registerHooks } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { registerComponents, renderToStream, renderToString } from './vmz-dom.js';
+import { listClientComponents } from './list-client-components.js';
 import { handleNodeRequest, setRoutes, setServerModuleResolver } from './vmz-runtime.js';
 const require = createRequire(import.meta.url);
 const distDir = process.env.VMZ_DIST ? path.resolve(process.env.VMZ_DIST) : path.dirname(fileURLToPath(import.meta.url));
@@ -479,9 +480,7 @@ async function* emitPageHtml(Page, chunkId, eventOnlyShell, props = {}, opts = {
             `d.innerHTML="<div style='max-width:56rem;margin:0 auto'><p style='color:#f87171;font-weight:700'>Dev Error</p><pre style='white-space:pre-wrap'>"+String(e.message||e).replace(/[<>&]/g,function(c){return {"<":"&lt;",">":"&gt;","&":"&amp;"}[c]})+"</pre></div>";` +
             `document.documentElement.appendChild(d);})();</script>`
         : '';
-    const buildIdBoot = isDev && lastDevBuildId
-        ? `\n  <script>window.__VMZ_DEV_BUILD_ID__=${JSON.stringify(lastDevBuildId)};</script>`
-        : '';
+    const buildIdBoot = isDev && lastDevBuildId ? `\n  <script>window.__VMZ_DEV_BUILD_ID__=${JSON.stringify(lastDevBuildId)};</script>` : '';
     if (signal?.aborted)
         return;
     const themeId = resolveThemeId(opts.searchParams, opts.cookieHeader);
@@ -1075,46 +1074,6 @@ async function loadPageCtor(chunkId) {
     pageCtors.set(chunkId, mod.default);
     return mod.default;
 }
-/**
- * @param {string} dir
- * @returns {Promise<Array<{ name: string, entry: string }>>}
- */
-async function listClientComponents(dir) {
-    /** @type {Map<string, { name: string, entry: string }>} */
-    const byName = new Map();
-    try {
-        const raw = await readFile(path.join(dir, 'vmz-deployment.json'), 'utf8');
-        const dep = JSON.parse(raw);
-        for (const unit of dep.units || []) {
-            if (unit?.kind !== 'component')
-                continue;
-            const chunkId = String(unit.chunkId || '');
-            const name = chunkId.split('/').pop();
-            if (!name)
-                continue;
-            const entry = String(unit.clientEntry || `${chunkId}.client.js`).replace(/\\/g, '/');
-            byName.set(name, { name, entry });
-        }
-    }
-    catch {
-        /* fall through to directory scan */
-    }
-    if (byName.size === 0) {
-        const folder = path.join(dir, 'components');
-        let files = [];
-        try {
-            files = await readdir(folder);
-        }
-        catch {
-            return [];
-        }
-        for (const f of files.filter((name) => name.endsWith('.client.js'))) {
-            const name = f.replace(/\.client\.js$/, '');
-            byName.set(name, { name, entry: `components/${name}.client.js` });
-        }
-    }
-    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
-}
 /**
  * Discover compiled page modules. Prefer Route Graph `pathPattern` from
  * `vmz-deployment.json`; fall back to walking `pages/**` (file-route only).

package/dist/server.js

@@ -226,7 +226,7 @@ export async function handleNodeRequest(req, res, opts = {}) {
             return await writeFetchResponse(res, response);
         }
         // Static first for assets + DocumentMount (`/d/…`) so docs aren't swallowed by SSR 404 shells.
-        // web-static route HTML (`index.html`, `about/index.html`, …) is a CDN/deploy projection only —
+        // 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');
@@ -404,7 +404,7 @@ function safeDistFile(distDir, pathname, nodePath) {
     return full;
 }
 /**
- * web-static emits per-route HTML beside client assets. That HTML is for CDN / local-static
+ * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vmz/core",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "type": "module",
   "description": "VMZ production runtime core — DOM / SSR / HTTP / WriteBarrier (no compiler)",
   "exports": {
@@ -27,6 +27,14 @@
     "./client-nav": {
       "types": "./dist/client-nav.d.ts",
       "default": "./dist/client-nav.js"
+    },
+    "./component-registry": {
+      "types": "./dist/list-client-components.d.ts",
+      "default": "./dist/list-client-components.js"
+    },
+    "./render-host": {
+      "types": "./dist/render-host.d.ts",
+      "default": "./dist/render-host.js"
     }
   },
   "files": [