@deepseek-ai/dsh-client-modules 0.1.6-alpha.1 → 0.1.7-alpha.1

package/lib/index.js

@@ -1,5 +1,5 @@
 import { createRequire } from "node:module";
-import { createHash, randomBytes } from "node:crypto";
+import { createHash } from "node:crypto";
 import { existsSync, readFileSync, statSync } from "node:fs";
 import { dirname, isAbsolute, join } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -165,6 +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)?$/;
+/** 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;
@@ -177,27 +179,58 @@ function clientExportOf(pkgName, exportsField) {
 	}
 	throw new Error(`client-modules: ${pkgName} exports["./client"] must be a string or an object with a string default`);
 }
-/** sha1 content hash shortened to 12 hex chars (combo / graph / rebuilt-artifact rev). */
+/** sha1 metadata hash shortened to 12 hex chars. */
 function shortHash(input) {
 	return createHash("sha1").update(input).digest("hex").slice(0, HASH_REVISION_LENGTH);
 }
 /** Hash several response fields without allowing bytes to move across field boundaries. */
 function framedHash(domain, parts) {
 	const hash = createHash("sha1").update(domain).update("\0");
-	for (const part of parts) hash.update(`${String(part.byteLength)}:`).update(part);
+	for (const part of parts) hash.update(`${String(Buffer.byteLength(part))}:`).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]);
+/** Identify an entry's build from filesystem metadata without hashing its contents. */
+function artifactRevision(baseline) {
+	return framedHash("plugin-artifact", [
+		String(baseline.mtimeMs),
+		String(baseline.ctimeMs),
+		String(baseline.size)
+	]);
 }
-/** Address one ordered plugin-file list through the shared combo route. */
+/** Absolute route prefix serving every plugin resource. */
+const PLUGIN_ROUTE = "/plugins";
+/** Combo query addressing one ordered plugin-file list. */
+function comboSearch(ids, rev, sourceMap = false) {
+	return `??${ids.map((id) => `${id}/client.js${sourceMap ? ".map" : ""}`).join(",")}&rev=${rev}`;
+}
+/** Absolute route URL for one combo resource. */
 function comboUrl(ids, rev, sourceMap = false) {
-	return `/plugins/??${ids.map((id) => `${id}/client.js${sourceMap ? ".map" : ""}`).join(",")}&rev=${rev}`;
+	return `${PLUGIN_ROUTE}/${comboSearch(ids, rev, sourceMap)}`;
+}
+/**
+* Browser reference to one combo resource: app-owned browser routes are
+* document-relative, so the route key's leading slash is stripped here, at the
+* boundary between the two halves. The rule and its reasons are owned by
+* .agents/notes/implemented/architecture/2026-09-14-web-document-relative-app-routes.md.
+*/
+function comboReference(ids, rev, sourceMap = false) {
+	return comboUrl(ids, rev, sourceMap).slice(1);
+}
+/** Absolute route URL for one package-local chunk. */
+function chunkUrl(id, fileName, rev, sourceMap = false) {
+	return `${PLUGIN_ROUTE}/${id}/${fileName}${sourceMap ? ".map" : ""}?rev=${rev}`;
+}
+/**
+* Source-map reference stamped into one chunk script. A script's map reference
+* resolves against that script's own directory rather than the document, so
+* this is the bare map file name, not the document-relative route.
+*/
+function chunkMapReference(fileName, rev) {
+	return `${fileName}.map?rev=${rev}`;
 }
-/** Measure the longer map-form URL used to partition a startup resource list. */
+/** Measure the longest browser-facing combo 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));
+	return Buffer.byteLength(comboReference(records.map((record) => record.entry.id), COMBO_REVISION_PLACEHOLDER, true));
 }
 /** Partition one phase in graph order without allowing a generated URL above the protocol limit. */
 function partitionComboRecords(records) {
@@ -218,23 +251,23 @@ 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
 	};
 }
-/** Stamp a combo script's absolute indexed-map URL onto its executable bytes. */
+/** Stamp a combo script's source-map reference onto its executable bytes. */
 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`);
@@ -245,10 +278,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) {
@@ -257,13 +287,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);
@@ -287,14 +314,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) => [resource.id, 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,
@@ -302,47 +350,52 @@ 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);
-	const url = comboUrl(entries, rev);
-	const sourceMapUrl = comboUrl(entries, rev, true);
+}
+/** 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);
 	return {
-		url,
+		url: comboUrl(entries, rev),
 		rev,
 		entries,
-		script: comboScript(source, sourceMapUrl),
-		sourceMap,
-		sourceMapUrl
+		sourceMapUrl: comboUrl(entries, rev, true),
+		scriptBody: lazyBody(() => buildComboScript(resources, comboSearch(entries, rev, true))),
+		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: {
 			phase,
-			url: artifact.url,
+			url: artifact.url.slice(1),
 			rev: artifact.rev,
 			entries: artifact.entries
 		}
 	};
 }
-/** Graph row for one bundle rev (url carries the rev as its cache-busting query). */
+/** Graph row for one bundle rev (the reference carries the rev as its cache-busting query). */
 function graphRow(id, rev, fields) {
 	return {
 		id,
-		url: comboUrl([id], rev),
+		url: comboReference([id], rev),
 		rev,
 		...fields.inject !== void 0 ? { inject: fields.inject } : {},
 		...fields.immediately ? { immediately: true } : {},
@@ -458,8 +511,6 @@ var ClientModuleRegistry = class extends Service {
 	rebuildListeners = /* @__PURE__ */ new Set();
 	graphListeners = /* @__PURE__ */ new Set();
 	dirty = /* @__PURE__ */ new Set();
-	initialRevisionNonce = randomBytes(8).toString("hex");
-	nextInitialRevision = 0;
 	responses = /* @__PURE__ */ new Map();
 	batchResponses = /* @__PURE__ */ new Map();
 	/** One prior graph generation covers a request racing the HMR recomposition that replaced its URL. */
@@ -494,7 +545,7 @@ var ClientModuleRegistry = class extends Service {
 		const registerWebCarrier = (webCtx) => {
 			webCtx.effect(() => webCtx.webServer.register({
 				kind: "prefix",
-				path: "/plugins",
+				path: PLUGIN_ROUTE,
 				handler: this.serveBundle
 			}), "client-modules: bundle route");
 		};
@@ -521,12 +572,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,
@@ -546,24 +598,22 @@ 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).
+	* Unchanged mtime, ctime and size preserve the graph without reading the bundle.
 	* @param id - entry id (package name).
-	* @returns the new rev, or undefined for an unknown id.
+	* @returns the current artifact rev, or undefined for an unknown id.
 	*/
 	rebuilt(id) {
 		const record = this.table.get(id);
 		if (record === void 0) return void 0;
 		const baseline = this.captureArtifactBaseline(record.meta.clientPath);
+		const rev = artifactRevision(baseline);
+		if (rev === record.entry.rev) return rev;
 		const bundle = readFileSync(record.meta.clientPath);
-		const sourceMap = this.readSourceMapSnapshot(record.meta.clientPath);
-		const rev = artifactRevision(bundle, sourceMap);
 		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);
@@ -574,7 +624,7 @@ var ClientModuleRegistry = class extends Service {
 		return rev;
 	}
 	/**
-	* Subscribe to bundle rebuilds; fires only when the re-hash changed the rev.
+	* Subscribe to bundle rebuilds; fires only when artifact metadata changes the rev.
 	* @param listener - receives the entry id and its new bundle rev.
 	* @returns the unsubscriber.
 	*/
@@ -602,31 +652,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.url, this.responses.get(artifact.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;
@@ -746,15 +797,12 @@ var ClientModuleRegistry = class extends Service {
 		return {
 			path: clientPath,
 			mtimeMs: bundle.mtimeMs,
+			ctimeMs: bundle.ctimeMs,
 			size: bundle.size
 		};
 	}
-	/** Allocate an opaque initial row revision without inspecting artifact bytes. */
-	allocateInitialRevision() {
-		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.
@@ -763,27 +811,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();
@@ -834,15 +879,14 @@ var ClientModuleRegistry = class extends Service {
 		if (source === void 0) return this.table.delete(packageName);
 		if (this.table.get(packageName)?.sourceKey === source.sourceKey) return false;
 		const snapshot = this.initialBundleSnapshot(packageName, source.meta.clientPath);
-		const rev = this.allocateInitialRevision();
+		const rev = artifactRevision(snapshot.baseline);
 		this.table.set(packageName, {
 			entry: graphRow(packageName, rev, source.meta),
 			loaderName: source.loaderName,
 			sourceKey: source.sourceKey,
 			meta: source.meta,
 			bundle: snapshot.bundle,
-			baseline: snapshot.baseline,
-			...snapshot.sourceMap === void 0 ? {} : { sourceMap: snapshot.sourceMap }
+			baseline: snapshot.baseline
 		});
 		return true;
 	}
@@ -867,24 +911,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 = chunkMapReference(fileName, record.entry.rev);
+		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/invariant.js

@@ -11,8 +11,8 @@ const inject = ["invariants"];
 /**
 * Owned relation: the node half's boot entry graph must stay self-consistent
 * — every row must resolve a clientPath under the same id (the
-* /plugins/<id>/client.js URL it advertises would otherwise 404 on a browser
-* that just received the graph). Checked on every scan trigger (cordis
+* `plugins/<id>/client.js` reference it advertises would otherwise 404 in the
+* browser that just received the graph). Checked on every scan trigger (cordis
 * 'internal/plugin'): graph() and clientPath() read the same table object,
 * so the relation holds at any instant — no need to wait out the node half's
 * own microtask-debounced flush.

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

@@ -14,6 +14,8 @@ import type { Context } from '@deepseek-ai/cordis';
 import { ClientModuleSystem } from './system.ts';
 import type { ClientBootstrapModule, ClientModuleCreateOptions, ClientModuleLoaderTarget } from './manifest.ts';
 export { ClientModuleSystem };
+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';
 /**