@deepseek-ai/dsh-client-modules 0.1.5-rc.2 → 0.1.6-alpha.2

package/lib/index.js

@@ -50,6 +50,43 @@ function optionalStringArray(subject, field, value) {
 	return value;
 }
 /**
+* Narrow an unknown parsed JSON value to the `dsh.client` declaration. Shared
+* by the node half's Loader scan and the roster generator, so both read a
+* package's browser declaration through one validator.
+* @param pkgName - package name used as the diagnostic prefix.
+* @param value - the raw `dsh.client` field of the package manifest.
+* @returns the validated declaration, or undefined when the field is absent.
+* @throws {Error} when the field is present but any member is malformed.
+*/
+function parseDshClient(pkgName, value) {
+	if (value === void 0) return void 0;
+	if (typeof value !== "object" || value === null) throw new Error(`client-modules: ${pkgName} has a non-object dsh.client declaration`);
+	const decl = value;
+	if (typeof decl.platform !== "string") throw new Error(`client-modules: ${pkgName} dsh.client.platform must be a string`);
+	const inject = optionalStringArray(pkgName, "dsh.client.inject", decl.inject);
+	const external = optionalStringArray(pkgName, "dsh.client.external", decl.external);
+	if (decl.immediately !== void 0 && typeof decl.immediately !== "boolean") throw new Error(`client-modules: ${pkgName} dsh.client.immediately must be a boolean`);
+	return {
+		platform: decl.platform,
+		...inject !== void 0 ? { inject } : {},
+		...external !== void 0 ? { external } : {},
+		...decl.immediately !== void 0 ? { immediately: decl.immediately } : {}
+	};
+}
+/**
+* The bare package-root specifier `specifier` names, or undefined for a subpath, a path, or any scheme-qualified
+* specifier (`cordis:` builtins, `node:` modules, URLs).
+* @param specifier - Loader row name.
+* @returns the package name, or undefined.
+*/
+function exactPackageSpecifier(specifier) {
+	if (specifier.startsWith("@")) {
+		const parts = specifier.split("/");
+		return parts.length === 2 && parts.every(Boolean) ? specifier : void 0;
+	}
+	return specifier.length > 0 && !specifier.includes("/") && !specifier.includes(":") ? specifier : void 0;
+}
+/**
 * Normalize a module specifier onto the graph row that owns it: a plugin bundle
 * IS its package's client half, so `<id>/client` (the exports subpath external
 * bundles emit) and the bare package name resolve to the same exports. Both the
@@ -71,7 +108,7 @@ function stripClientSuffix(spec) {
 * combo scripts plus their source maps,
 * contributes the registration facade, application preloads, bootstrap scripts,
 * and graph to the webserver's index injection table, and provides the
-* `clientModuleHost` service (the HMR node half's registration/notification
+* `clientModules` service (the HMR node half's registration/notification
 * face).
 *
 * Scanning is incremental per package — there is no full-rescan code path.
@@ -128,30 +165,8 @@ const COMBO_REVISION_PLACEHOLDER = "0".repeat(HASH_REVISION_LENGTH);
 const SOURCE_MAP_TRAILER = /(?:\r?\n)?\/\/# sourceMappingURL=[^\r\n]*(?:\r?\n)?$/;
 /** Debugger source name appended to page bundles in the WebWorker image. */
 const SOURCE_URL_TRAILER = /(?:\r?\n)?\/\/# sourceURL=([^\r\n]+)(?:\r?\n)?$/;
-/** Return a bare package-root specifier, excluding package subpaths and path-like entries. */
-function exactPackageSpecifier(specifier) {
-	if (specifier.startsWith("@")) {
-		const parts = specifier.split("/");
-		return parts.length === 2 && parts.every(Boolean) ? specifier : void 0;
-	}
-	return specifier.length > 0 && !specifier.includes("/") ? specifier : void 0;
-}
-/** Narrow an unknown parsed JSON value to the `dsh.client` declaration, throwing on malformed fields. */
-function parseDshClient(pkgName, value) {
-	if (value === void 0) return void 0;
-	if (typeof value !== "object" || value === null) throw new Error(`client-modules: ${pkgName} has a non-object dsh.client declaration`);
-	const decl = value;
-	if (typeof decl.platform !== "string") throw new Error(`client-modules: ${pkgName} dsh.client.platform must be a string`);
-	const inject = optionalStringArray(pkgName, "dsh.client.inject", decl.inject);
-	const external = optionalStringArray(pkgName, "dsh.client.external", decl.external);
-	if (decl.immediately !== void 0 && typeof decl.immediately !== "boolean") throw new Error(`client-modules: ${pkgName} dsh.client.immediately must be a boolean`);
-	return {
-		platform: decl.platform,
-		...inject !== void 0 ? { inject } : {},
-		...external !== void 0 ? { external } : {},
-		...decl.immediately !== void 0 ? { immediately: decl.immediately } : {}
-	};
-}
+/** Published package-local client chunk names accepted by the on-demand route. */
+const CLIENT_CHUNK = /^client\.[A-Za-z0-9][A-Za-z0-9._-]*\.js$/;
 /** Resolve `exports["./client"]` to a relative path, accepting the string and one-level conditional forms. */
 function clientExportOf(pkgName, exportsField) {
 	if (typeof exportsField !== "object" || exportsField === null) return void 0;
@@ -174,14 +189,18 @@ function framedHash(domain, parts) {
 	for (const part of parts) hash.update(`${String(part.byteLength)}:`).update(part);
 	return hash.digest("hex").slice(0, HASH_REVISION_LENGTH);
 }
-/** Hash every artifact input served after HMR observes one plugin change. */
-function artifactRevision(bundle, sourceMap) {
-	return framedHash("plugin-artifact", sourceMap === void 0 ? [bundle] : [bundle, sourceMap.body]);
+/** Hash one completed build generation observed through its entry artifact. */
+function artifactRevision(bundle, baseline) {
+	return framedHash("plugin-artifact", [bundle, Buffer.from(String(baseline.mtimeMs))]);
 }
 /** Address one ordered plugin-file list through the shared combo route. */
 function comboUrl(ids, rev, sourceMap = false) {
 	return `/plugins/??${ids.map((id) => `${id}/client.js${sourceMap ? ".map" : ""}`).join(",")}&rev=${rev}`;
 }
+/** Address one package-local chunk through the same revision as its entry. */
+function chunkUrl(id, fileName, rev, sourceMap = false) {
+	return `/plugins/${id}/${fileName}${sourceMap ? ".map" : ""}?rev=${rev}`;
+}
 /** Measure the longer map-form URL used to partition a startup resource list. */
 function projectedComboUrlBytes(records) {
 	return Buffer.byteLength(comboUrl(records.map((record) => record.entry.id), COMBO_REVISION_PLACEHOLDER, true));
@@ -205,12 +224,12 @@ function partitionComboRecords(records) {
 	return chunks;
 }
 /** Remove bundle-local debug directives and retain their stable generated-file name. */
-function comboSource(record) {
-	let source = record.bundle.toString("utf8");
+function prepareSource(resource) {
+	let source = resource.bundle.toString("utf8");
 	const sourceUrl = SOURCE_URL_TRAILER.exec(source)?.[1];
 	source = source.replace(SOURCE_URL_TRAILER, "").replace(SOURCE_MAP_TRAILER, "");
 	if (!source.endsWith("\n")) source += "\n";
-	const fallbackSource = sourceUrl === void 0 ? `/plugins/${record.entry.id}/client.js` : /^(?:[A-Za-z][A-Za-z\d+.-]*:|\/)/.test(sourceUrl) ? sourceUrl : `/${sourceUrl}`;
+	const fallbackSource = sourceUrl === void 0 ? `/plugins/${resource.id}/${resource.fileName}` : /^(?:[A-Za-z][A-Za-z\d+.-]*:|\/)/.test(sourceUrl) ? sourceUrl : `/${sourceUrl}`;
 	return {
 		source,
 		fallbackSource
@@ -220,8 +239,8 @@ function comboSource(record) {
 function comboScript(input, sourceMapUrl) {
 	return Buffer.from(sourceMapUrl === void 0 ? input : `${input}//# sourceMappingURL=${sourceMapUrl}\n`);
 }
-/** Parse an optional source-map artifact; missing maps do not prevent plugin execution. */
-function sourceMapSnapshot(clientPath) {
+/** Read and parse an optional source map when its combo-map endpoint is requested. */
+function readSourceMap(clientPath) {
 	let body;
 	try {
 		body = readFileSync(`${clientPath}.map`);
@@ -232,10 +251,7 @@ function sourceMapSnapshot(clientPath) {
 	const value = JSON.parse(body.toString("utf8"));
 	const parsed = typeof value === "object" && value !== null ? value : void 0;
 	if (parsed === void 0 || parsed.version !== 3 || !Array.isArray(parsed.sources) || parsed.sources.some((source) => typeof source !== "string") || !Array.isArray(parsed.names) || parsed.names.some((name) => typeof name !== "string") || typeof parsed.mappings !== "string") throw new Error(`client-modules: ${clientPath}.map is not a regular Source Map v3 object`);
-	return {
-		body,
-		parsed
-	};
+	return parsed;
 }
 /** Count generated lines while assembling indexed-map section offsets. */
 function newlineCount(value) {
@@ -244,13 +260,10 @@ function newlineCount(value) {
 	return count;
 }
 /** Resolve section sources against their original per-plugin map URL before combo relocation. */
-function comboSectionMap(record) {
-	const original = record.sourceMap?.parsed;
-	/* v8 ignore next -- callers add sections only for records with a source map. */
-	if (original === void 0) throw new Error(`client-modules: source map missing for ${record.entry.id}`);
+function comboSectionMap(resource, original) {
 	const sourcePaths = original.sources;
 	const sourceRoot = typeof original.sourceRoot === "string" ? original.sourceRoot : "";
-	const base = new URL(`/plugins/${record.entry.id}/client.js.map`, "http://dsh.invalid");
+	const base = new URL(`/plugins/${resource.id}/client.js.map`, "http://dsh.invalid");
 	const relocated = sourcePaths.map((source) => {
 		const separator = sourceRoot !== "" && !sourceRoot.endsWith("/") && !source.startsWith("/") ? "/" : "";
 		const resolved = new URL(`${sourceRoot}${separator}${source}`, base);
@@ -274,14 +287,35 @@ function identitySectionMap(source, sourceUrl) {
 		mappings
 	};
 }
-/** Concatenate one or more factory registrations and compose their maps as indexed sections. */
-function buildCombo(records, revision) {
+/** Run one producer in the first requester's microtask, not off-thread, and share its settlement. */
+function lazyBody(produce) {
+	let result;
+	return () => {
+		result ??= Promise.resolve().then(produce);
+		return result;
+	};
+}
+/** Derive one combo revision from the ordered immutable row revisions. */
+function comboRevision(resources) {
+	return framedHash("combo", resources.flatMap((resource) => [Buffer.from(resource.id), Buffer.from(resource.rev)]));
+}
+/** Concatenate one or more factory registrations without reading or composing source maps. */
+function buildComboScript(resources, sourceMapUrl) {
 	let source = "";
+	for (const resource of resources) source += `${prepareSource(resource).source};\n`;
+	return comboScript(source, sourceMapUrl);
+}
+/** Compose one indexed map from source-map files read only for this request. */
+function buildComboSourceMap(resources, sourceMapOf, fileName = "client.js") {
 	const sections = [];
 	let line = 0;
-	for (const record of records) {
-		const prepared = comboSource(record);
-		const section = record.sourceMap === void 0 ? identitySectionMap(prepared.source, prepared.fallbackSource) : comboSectionMap(record);
+	for (const resource of resources) {
+		const prepared = prepareSource(resource);
+		const sourceMap = sourceMapOf(resource.clientPath);
+		let section = identitySectionMap(prepared.source, prepared.fallbackSource);
+		if (sourceMap !== void 0) try {
+			section = comboSectionMap(resource, sourceMap);
+		} catch {}
 		sections.push({
 			offset: {
 				line,
@@ -289,32 +323,39 @@ function buildCombo(records, revision) {
 			},
 			map: section
 		});
-		const bundle = `${prepared.source};\n`;
-		source += bundle;
-		line += newlineCount(bundle);
+		line += newlineCount(`${prepared.source};\n`);
 	}
-	const sourceMap = Buffer.from(`${JSON.stringify({
+	return Buffer.from(`${JSON.stringify({
 		version: 3,
-		file: "client.js",
+		file: fileName,
 		sections
 	})}\n`);
-	const sourceBytes = Buffer.from(source);
-	const rev = revision ?? framedHash("combo", [sourceBytes, sourceMap]);
-	const entries = records.map((record) => record.entry.id);
+}
+/** Describe one combo and defer its executable and debug payloads independently. */
+function buildCombo(records, sourceMapOf, revision) {
+	const resources = records.map((record) => ({
+		id: record.entry.id,
+		rev: record.entry.rev,
+		clientPath: record.meta.clientPath,
+		fileName: "client.js",
+		bundle: record.bundle
+	}));
+	const rev = revision ?? comboRevision(resources);
+	const entries = resources.map((resource) => resource.id);
 	const url = comboUrl(entries, rev);
 	const sourceMapUrl = comboUrl(entries, rev, true);
 	return {
 		url,
 		rev,
 		entries,
-		script: comboScript(source, sourceMapUrl),
-		sourceMap,
-		sourceMapUrl
+		sourceMapUrl,
+		scriptBody: lazyBody(() => buildComboScript(resources, sourceMapUrl)),
+		sourceMapBody: lazyBody(() => buildComboSourceMap(resources, sourceMapOf))
 	};
 }
 /** Add initial-load scheduling metadata to a combo artifact. */
-function buildBatch(phase, records) {
-	const artifact = buildCombo(records);
+function buildBatch(phase, records, sourceMapOf) {
+	const artifact = buildCombo(records, sourceMapOf);
 	return {
 		...artifact,
 		descriptor: {
@@ -455,6 +496,7 @@ var ClientModuleRegistry = class extends Service {
 	composed;
 	/**
 	* Build the service: subscribe, seed, and run the activation flush.
+	* Bundle routes follow the optional Web carrier's injected lifecycle.
 	* @param ctx - plugin context carrying Loader and an optional Web carrier.
 	*/
 	constructor(ctx) {
@@ -484,8 +526,7 @@ var ClientModuleRegistry = class extends Service {
 				handler: this.serveBundle
 			}), "client-modules: bundle route");
 		};
-		if (ctx.get("webServer") === void 0) ctx.inject(["webServer"], registerWebCarrier);
-		else registerWebCarrier(ctx);
+		ctx.inject(["webServer"], registerWebCarrier);
 		ctx.on("webserver/index-inject", (table) => {
 			table.push(...bootInjections(this.composed));
 		});
@@ -508,12 +549,13 @@ var ClientModuleRegistry = class extends Service {
 	/**
 	* Serve an advertised revisioned bundle or source map without a Web server.
 	* Unknown URLs return 404, unsupported methods return 405, and `HEAD`
-	* returns the same immutable headers without a body.
+	* returns the same immutable headers without materializing a body. Each body
+	* is built once on its first `GET`; script construction never reads maps.
 	* @param request - shell-carrier request for a `/plugins` resource.
 	* @returns the exact response also exposed by the optional Web route.
 	*/
-	fetchBundle(request) {
-		const resource = this.bundleResource(request.method, request.url);
+	async fetchBundle(request) {
+		const resource = await this.bundleResource(request.method, request.url);
 		const body = resource.body === void 0 ? null : Uint8Array.from(resource.body);
 		return new Response(body, {
 			status: resource.status,
@@ -533,8 +575,8 @@ var ClientModuleRegistry = class extends Service {
 		return baseline === void 0 ? void 0 : { ...baseline };
 	}
 	/**
-	* Re-hash one bundle (the HMR watch's registration hook — the only entry
-	* point through which bundle content changes reach the graph).
+	* Publish one completed bundle generation (the HMR watch's registration
+	* hook — the only entry point through which build changes reach the graph).
 	* @param id - entry id (package name).
 	* @returns the new rev, or undefined for an unknown id.
 	*/
@@ -543,14 +585,11 @@ var ClientModuleRegistry = class extends Service {
 		if (record === void 0) return void 0;
 		const baseline = this.captureArtifactBaseline(record.meta.clientPath);
 		const bundle = readFileSync(record.meta.clientPath);
-		const sourceMap = this.readSourceMapSnapshot(record.meta.clientPath);
-		const rev = artifactRevision(bundle, sourceMap);
+		const rev = artifactRevision(bundle, baseline);
 		record.baseline = baseline;
 		if (rev === record.entry.rev) return rev;
 		record.entry = graphRow(id, rev, record.meta);
 		record.bundle = bundle;
-		if (sourceMap === void 0) delete record.sourceMap;
-		else record.sourceMap = sourceMap;
 		this.composed = this.compose();
 		for (const notify of this.rebuildListeners) try {
 			notify(id, rev);
@@ -589,31 +628,32 @@ var ClientModuleRegistry = class extends Service {
 		const bootstrapIds = new Set(bootstrap.map((record) => record.entry.id));
 		const application = entries.filter((entry) => !bootstrapIds.has(entry.id)).map((entry) => this.table.get(entry.id)).filter((record) => record !== void 0);
 		const artifacts = [];
-		for (const records of partitionComboRecords(bootstrap)) artifacts.push(buildBatch("bootstrap", records));
-		for (const records of partitionComboRecords(application)) artifacts.push(buildBatch("application", records));
+		for (const records of partitionComboRecords(bootstrap)) artifacts.push(buildBatch("bootstrap", records, this.readSourceMap));
+		for (const records of partitionComboRecords(application)) artifacts.push(buildBatch("application", records, this.readSourceMap));
 		const batchResponses = /* @__PURE__ */ new Map();
 		for (const artifact of artifacts) {
-			batchResponses.set(artifact.descriptor.url, {
-				body: artifact.script,
+			batchResponses.set(artifact.descriptor.url, this.responses.get(artifact.descriptor.url) ?? {
+				body: artifact.scriptBody,
 				contentType: "text/javascript; charset=utf-8"
 			});
-			batchResponses.set(artifact.sourceMapUrl, {
-				body: artifact.sourceMap,
+			batchResponses.set(artifact.sourceMapUrl, this.responses.get(artifact.sourceMapUrl) ?? {
+				body: artifact.sourceMapBody,
 				contentType: "application/json; charset=utf-8"
 			});
 		}
 		const responses = new Map(batchResponses);
 		for (const record of this.table.values()) {
-			const artifact = buildCombo([record], record.entry.rev);
-			responses.set(artifact.url, {
-				body: artifact.script,
+			const artifact = buildCombo([record], this.readSourceMap, record.entry.rev);
+			responses.set(artifact.url, responses.get(artifact.url) ?? this.responses.get(artifact.url) ?? {
+				body: artifact.scriptBody,
 				contentType: "text/javascript; charset=utf-8"
 			});
-			responses.set(artifact.sourceMapUrl, {
-				body: artifact.sourceMap,
+			responses.set(artifact.sourceMapUrl, responses.get(artifact.sourceMapUrl) ?? this.responses.get(artifact.sourceMapUrl) ?? {
+				body: artifact.sourceMapBody,
 				contentType: "application/json; charset=utf-8"
 			});
 		}
+		for (const [resourceUrl, response] of this.responses) if (this.chunkRequest(new URL(resourceUrl, "http://x")) !== void 0) responses.set(resourceUrl, response);
 		this.previousBatchResponses = this.batchResponses;
 		this.batchResponses = batchResponses;
 		this.responses = responses;
@@ -741,7 +781,7 @@ var ClientModuleRegistry = class extends Service {
 		return `${this.initialRevisionNonce}-${String(this.nextInitialRevision++)}`;
 	}
 	/**
-	* Read the activation-time bundle and optional source-map snapshots.
+	* Read the activation-time bundle snapshot.
 	* @param pkgName - package that declares the client bundle.
 	* @param clientPath - absolute path of the built client artifact.
 	* @returns the immutable bytes plus the pre-read filesystem baseline.
@@ -750,27 +790,24 @@ var ClientModuleRegistry = class extends Service {
 	initialBundleSnapshot(pkgName, clientPath) {
 		try {
 			const baseline = this.captureArtifactBaseline(clientPath);
-			const bundle = readFileSync(clientPath);
-			const sourceMap = this.readSourceMapSnapshot(clientPath);
 			return {
-				bundle,
-				baseline,
-				...sourceMap === void 0 ? {} : { sourceMap }
+				bundle: readFileSync(clientPath),
+				baseline
 			};
 		} catch (error) {
 			if (error.code !== "ENOENT") throw error;
 			throw new MissingClientBundleError(pkgName, clientPath, error);
 		}
 	}
-	/** Treat a missing, torn, or malformed development map as an identity-mapped artifact revision. */
-	readSourceMapSnapshot(clientPath) {
+	/** Treat a missing, torn, or malformed development map as an identity section. */
+	readSourceMap = (clientPath) => {
 		try {
-			return sourceMapSnapshot(clientPath);
+			return readSourceMap(clientPath);
 		} catch (error) {
 			this.ctx.logger.warn(error);
 			return;
 		}
-	}
+	};
 	/** Reconcile one entry name against the live Loader sources. @returns whether the table changed. */
 	processOne(entryName, onError) {
 		const nextSources = /* @__PURE__ */ new Map();
@@ -828,8 +865,7 @@ var ClientModuleRegistry = class extends Service {
 			sourceKey: source.sourceKey,
 			meta: source.meta,
 			bundle: snapshot.bundle,
-			baseline: snapshot.baseline,
-			...snapshot.sourceMap === void 0 ? {} : { sourceMap: snapshot.sourceMap }
+			baseline: snapshot.baseline
 		});
 		return true;
 	}
@@ -854,24 +890,68 @@ var ClientModuleRegistry = class extends Service {
 		this.composed = composed;
 		this.notifyGraphChanged();
 	}
-	bundleResource(method, url) {
+	/** Match an exact current-revision package-local chunk URL without reading its file. */
+	chunkRequest(requestUrl) {
+		const resourceUrl = `${requestUrl.pathname}${requestUrl.search}`;
+		for (const record of this.table.values()) {
+			const prefix = `/plugins/${record.entry.id}/`;
+			if (!requestUrl.pathname.startsWith(prefix)) continue;
+			const requested = requestUrl.pathname.slice(prefix.length);
+			const sourceMap = requested.endsWith(".map");
+			const fileName = sourceMap ? requested.slice(0, -4) : requested;
+			if (!CLIENT_CHUNK.test(fileName)) return void 0;
+			if (resourceUrl !== chunkUrl(record.entry.id, fileName, record.entry.rev, sourceMap)) return void 0;
+			return {
+				record,
+				fileName,
+				sourceMap,
+				resourceUrl
+			};
+		}
+	}
+	/** Build a package-local chunk response only when its URL is requested. */
+	chunkResponse(requestUrl) {
+		const request = this.chunkRequest(requestUrl);
+		if (request === void 0) return void 0;
+		const { record, fileName, sourceMap, resourceUrl } = request;
+		const clientPath = join(dirname(record.meta.clientPath), fileName);
+		if (!existsSync(clientPath)) return void 0;
+		const sourceMapUrl = chunkUrl(record.entry.id, fileName, record.entry.rev, true);
+		const resource = () => ({
+			id: record.entry.id,
+			rev: record.entry.rev,
+			clientPath,
+			fileName,
+			bundle: readFileSync(clientPath)
+		});
+		const response = sourceMap ? {
+			body: lazyBody(() => buildComboSourceMap([resource()], this.readSourceMap, fileName)),
+			contentType: "application/json; charset=utf-8"
+		} : {
+			body: lazyBody(() => buildComboScript([resource()], sourceMapUrl)),
+			contentType: "text/javascript; charset=utf-8"
+		};
+		this.responses.set(resourceUrl, response);
+		return response;
+	}
+	async bundleResource(method, url) {
 		if (method !== "GET" && method !== "HEAD") return { status: 405 };
 		const requestUrl = new URL(url, "http://x");
 		const resourceUrl = `${requestUrl.pathname}${requestUrl.search}`;
-		const response = this.responses.get(resourceUrl) ?? this.previousBatchResponses.get(resourceUrl);
+		const response = this.responses.get(resourceUrl) ?? this.previousBatchResponses.get(resourceUrl) ?? this.chunkResponse(requestUrl);
 		if (response !== void 0) return {
 			status: 200,
 			headers: {
 				"content-type": response.contentType,
 				"cache-control": IMMUTABLE_CACHE
 			},
-			...method === "HEAD" ? {} : { body: response.body }
+			...method === "HEAD" ? {} : { body: await response.body() }
 		};
 		return { status: 404 };
 	}
-	serveBundle = (req, res) => {
+	serveBundle = async (req, res) => {
 		/* v8 ignore next -- `?? '/'` arm: node:http always sets url on server requests. */
-		const response = this.bundleResource(req.method, req.url ?? "/");
+		const response = await this.bundleResource(req.method, req.url ?? "/");
 		res.writeHead(response.status, response.headers);
 		res.end(response.body);
 	};

package/lib/types/client/entries.d.ts

@@ -0,0 +1,76 @@
+import type { Loader } from '@deepseek-ai/cordis-plugin-loader';
+import type { ObservableSnapshot } from '@deepseek-ai/dsh-client-store';
+import type { BootManifest, ClientModuleLoader } from './manifest.ts';
+/** Page-local failures do not change the Host's bundle enablement. */
+export interface ClientEntryState {
+    /** True while a snapshot, retry or code replacement is being applied. */
+    readonly syncing: boolean;
+    /** Package ids and errors from the latest reconciliation. */
+    readonly failures: readonly {
+        readonly id: string;
+        readonly message: string;
+    }[];
+}
+/** Module-table capabilities used within serialized entry operations. */
+interface ModuleIndex {
+    update(manifest: BootManifest, managed: Iterable<string>): void;
+    invalidateForReplacement(id: string, rev: string): void;
+    prune(roots: Iterable<string>): void;
+}
+/** Manages only entries created from the Host manifest; other Loader contributors retain ownership. */
+export declare class ClientEntries {
+    private readonly modules;
+    private readonly index;
+    /** Stable observable consumed by page diagnostics through the renderer's injected hook. */
+    readonly state: ObservableSnapshot<ClientEntryState>;
+    private snapshot;
+    private readonly listeners;
+    private readonly managed;
+    private readonly revisions;
+    private loader;
+    private queue;
+    private desired;
+    private generation;
+    private stopped;
+    /**
+     * Construct the page controller before Cordis boot.
+     * @param modules - Module arrival and materialization owner.
+     * @param index - Private descriptor replacement and unused-module cleanup.
+     */
+    constructor(modules: ClientModuleLoader, index: ModuleIndex);
+    /**
+     * Create the initial roster and retain its entry identities for subsequent reconciliation.
+     * @param loader - Page Loader, already configured with the module system.
+     * @param manifest - Initial roster audited by the boot caller.
+     * @returns after initial entries and their activation settle; boot owns its activation audit.
+     */
+    start(loader: Loader, manifest: BootManifest): Promise<void>;
+    /**
+     * Validate and apply the latest full Host graph. Changed targets cancel obsolete mounts; identical targets share pending loads.
+     * @param graph - JSON-decoded graph received from the Host.
+     * @returns after the queued reconciliation; per-package failures remain available in {@link state}.
+     */
+    sync(graph: unknown): Promise<void>;
+    /**
+     * Retry failed entries against the latest graph, including an unchanged revision.
+     * @returns after retry settlement, with remaining errors in {@link state}.
+     */
+    retry(): Promise<void>;
+    /**
+     * Replace one entry's code in the same queue as graph updates; duplicate revisions are ignored.
+     * Entries missing after a failed import are reconciled; bootstrap replacement fails before teardown.
+     * @param id - Package id from a rebuilt frame.
+     * @param rev - Opaque revision selecting the rebuilt artifact.
+     * @returns after queued work; replacement errors reject, while per-package reconciliation errors remain in {@link state}.
+     */
+    reload(id: string, rev: string): Promise<void>;
+    private publish;
+    private enqueue;
+    private current;
+    /** Keep ownership even when Loader rejects a module's plugin exports after inserting its entry. */
+    private create;
+    private replace;
+    private reconcile;
+}
+export {};
+//# sourceMappingURL=entries.d.ts.map

package/lib/types/client/entry-lifecycle.d.ts

@@ -0,0 +1,14 @@
+/** Loader lifecycle operations shared by live graph reconciliation and code replacement. */
+import type { Entry } from '@deepseek-ai/cordis-plugin-loader';
+/**
+ * Release a runtime before clearing its entry fiber so Loader refresh can import new code.
+ * Registry deletion prevents Loader from treating replacement as a user disable.
+ * @param entry - Entry retained for code replacement.
+ */
+export declare function tearDownEntryFiber(entry: Entry): Promise<void>;
+/**
+ * Remove styles after their plugin's effect cleanup has settled.
+ * @param id - Package whose factory owns the style tags.
+ */
+export declare function removeOwnedStyles(id: string): void;
+//# sourceMappingURL=entry-lifecycle.d.ts.map

package/lib/types/client/index.d.ts

@@ -6,24 +6,28 @@
  * parser-preloads this ordinary client bundle into the pending registration
  * queue. The HTML-installed loader facade materializes this bundle and calls
  * its bootstrap export, which constructs the system and retains the same
- * exports for this package's graph row. The plugin face only enrolls that
- * pre-existing instance by providing it as `ctx.modules`.
+ * exports for this package's graph row. The plugin face enrolls the module
+ * system attached to its own Loader as `ctx.modules`.
  * @module @deepseek-ai/dsh-client-modules/client
  */
 import type { Context } from '@deepseek-ai/cordis';
 import { ClientModuleSystem } from './system.ts';
 import type { ClientBootstrapModule, ClientModuleCreateOptions, ClientModuleLoaderTarget } from './manifest.ts';
 export { ClientModuleSystem };
-export { parseBootManifest, stripClientSuffix } from './manifest.ts';
+export { tearDownEntryFiber } from './entry-lifecycle.ts';
+export type { ClientEntries, ClientEntryState } from './entries.ts';
+export { exactPackageSpecifier, parseBootManifest, parseDshClient, stripClientSuffix } from './manifest.ts';
 export type { BootManifest, BootModuleRow, BootPluginRow, ClientBootstrapModule, ClientBundleRegistration, ClientModuleCreateOptions, ClientModuleLoader, ClientModuleLoaderTarget, ClientModuleRecord, ClientModuleSystemOptions, DshWindow, WebBootEntry, WebBootGraph, } from './manifest.ts';
 /**
  * Build the live module system from the HTML facade's materialized modules bundle.
  * @param target - Stable registration facade whose pending queue becomes the live sink.
  * @param bootstrapModule - This bundle's id and already-materialized exports.
  * @param options - Raw boot graph, platform seed, and optional bundle transport.
- * @returns The created module system, also published for this package's Cordis plugin face.
+ * @returns The created module system.
  */
 export declare function createClientModuleSystem(target: ClientModuleLoaderTarget, bootstrapModule: ClientBootstrapModule, options: ClientModuleCreateOptions): ClientModuleSystem;
+/** Required service: the Loader whose internal module system this plugin publishes. */
+export declare const inject: string[];
 /**
  * Enroll the kernel-built module system as `ctx.modules`.
  * @param ctx - client root context.