@vmz/core 0.1.9 → 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

@@ -1,25 +1,62 @@
 /**
  * Discover compiled client component modules from dist (deployment graph or components/).
- * Shared by serve-host SSR and static emit assemble.
+ * 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
- * @returns {Promise<Array<{ name: string, entry: string }>>}
+ * @param {{ strict?: boolean }} [opts]
+ * @returns {Promise<Array<{ name: string, entry: string, chunkId?: string }>>}
  */
-export declare function listClientComponents(dir: any): Promise<any[]>;
+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
- * @returns {Array<{ name: string, entry: string }>}
+ * @param {{ strict?: boolean }} [opts]
+ * @returns {Array<{ name: string, entry: string, chunkId?: string }>}
  */
-export declare function listClientComponentsSync(dir: any): any[];
+export declare function listClientComponentsSync(dir: any, opts?: {}): {
+    name: any;
+    entry: any;
+    chunkId: any;
+}[];
 /**
- * Import all (or filtered) client components and register for SSR / static emit.
+ * @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 }) => boolean,
+ *   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

@@ -1,111 +1,133 @@
 // @ts-nocheck
 /**
  * Discover compiled client component modules from dist (deployment graph or components/).
- * Shared by serve-host SSR and static emit assemble.
+ * Shared by serve-host SSR, static emit, and test hosts.
  */
 import fs from 'node:fs';
-import { readdir, readFile } from 'node:fs/promises';
+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
- * @returns {Promise<Array<{ name: string, entry: string }>>}
+ * @param {{ strict?: boolean }} [opts]
+ * @returns {Promise<Array<{ name: string, entry: string, chunkId?: string }>>}
  */
-export async function listClientComponents(dir) {
-    /** @type {Map<string, { name: string, entry: string }>} */
-    const byName = new Map();
+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 {
-        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 });
-        }
+        files = await readdir(folder);
     }
     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 [];
     }
-    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+    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
- * @returns {Array<{ name: string, entry: string }>}
+ * @param {{ strict?: boolean }} [opts]
+ * @returns {Array<{ name: string, entry: string, chunkId?: string }>}
  */
-export function listClientComponentsSync(dir) {
-    /** @type {Map<string, { name: string, entry: string }>} */
-    const byName = new Map();
-    const deploymentPath = path.join(dir, 'vmz-deployment.json');
-    if (fs.existsSync(deploymentPath)) {
-        try {
-            const dep = JSON.parse(fs.readFileSync(deploymentPath, 'utf8'));
-            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 */
-        }
+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,
+        }));
     }
-    if (byName.size === 0) {
-        const folder = path.join(dir, 'components');
-        let files = [];
-        try {
-            files = fs.readdirSync(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` });
-        }
+    const folder = path.join(dir, 'components');
+    /** @type {string[]} */
+    let files = [];
+    try {
+        files = fs.readdirSync(folder);
+    }
+    catch {
+        return [];
     }
-    return [...byName.values()].sort((a, b) => a.name.localeCompare(b.name));
+    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.
+ * 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 }) => boolean,
+ *   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 = {}) {
-    const entries = await listClientComponents(distDir);
+    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) {
-        if (opts.include && !opts.include(entry))
-            continue;
         const abs = path.join(distDir, entry.entry);
         let href = pathToFileURL(abs).href;
         if (opts.cacheBust != null && opts.cacheBust !== '') {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vmz/core",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "type": "module",
   "description": "VMZ production runtime core — DOM / SSR / HTTP / WriteBarrier (no compiler)",
   "exports": {
@@ -31,6 +31,10 @@
     "./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": [