@deepseek-ai/dsh-client-modules 0.1.1-rc.2 → 0.1.2-alpha.3

package/lib/index.js

@@ -1,8 +1,8 @@
 import { createRequire } from "node:module";
-import { createHash } from "node:crypto";
-import { readFileSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { createHash, randomBytes } from "node:crypto";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { Service } from "@deepseek-ai/cordis";
 //#region lib/types/client/manifest.js
 /**
@@ -67,11 +67,12 @@ function stripClientSuffix(spec) {
 * Node half of the client module system (`dsh.client` dual-face package): scans
 * the host Loader's entries for packages declaring `dsh.client`, composes the
 * `window.__DSH_BOOT__` entry graph (wire single source: {@link WebBootEntry}
-* in `./client/manifest.ts`) in module-graph order, serves
-* `/plugins/<id>/client.js` and its source map, contributes the boot manifest
-* plus the parser-blocking bootstrap preloads to the webserver's index
-* injection table, and provides the `clientModuleHost` service (the HMR node
-* half's registration/notification face).
+* in `./client/manifest.ts`) in module-graph order, serves one-or-more-plugin
+* 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
+* face).
 *
 * Scanning is incremental per package — there is no full-rescan code path.
 * Every cordis `internal/plugin` emission (fiber construction/disposal) marks
@@ -79,9 +80,10 @@ function stripClientSuffix(spec) {
 * against the live loader entries. The activation pass seeds the same dirty
 * set with all current entries and flushes synchronously, so first scan and
 * steady state share one implementation. Package metadata (including the
-* negative "not a client package" verdict) is cached per name and never
-* expires — plugin-set changes take effect on restart; bundle content
-* changes reach the graph only through
+* negative "not a client package" verdict) is cached per Loader specifier and
+* owning-tree base URL until restart. The manifest package name identifies
+* the browser module; distinct active Loader sources for that package are a
+* composition error. Bundle content changes reach the graph only through
 * {@link ClientModuleRegistry.rebuilt}.
 * @module @deepseek-ai/dsh-client-modules
 */
@@ -116,6 +118,24 @@ var ClientPackageCompositionError = class extends AggregateError {
 		super(failures, lines.join("\n"));
 	}
 };
+/** Versioned code is immutable; mismatched revisions are rejected instead of serving newer bytes. */
+const IMMUTABLE_CACHE = "public, max-age=31536000, immutable";
+/** Generated request URLs stay below conservative browser and intermediary request-target limits. */
+const MAX_COMBO_URL_BYTES = 3 * 1024;
+const HASH_REVISION_LENGTH = 12;
+const COMBO_REVISION_PLACEHOLDER = "0".repeat(HASH_REVISION_LENGTH);
+/** Source-map trailer emitted by tsdown at the end of every client bundle. */
+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;
@@ -144,15 +164,172 @@ 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 (bundle rev / graph rev). */
+/** sha1 content hash shortened to 12 hex chars (combo / graph / rebuilt-artifact rev). */
 function shortHash(input) {
-	return createHash("sha1").update(input).digest("hex").slice(0, 12);
+	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);
+	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]);
+}
+/** 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}`;
+}
+/** 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));
+}
+/** Partition one phase in graph order without allowing a generated URL above the protocol limit. */
+function partitionComboRecords(records) {
+	const chunks = [];
+	let current = [];
+	for (const record of records) {
+		const candidate = [...current, record];
+		if (projectedComboUrlBytes(candidate) <= MAX_COMBO_URL_BYTES) {
+			current = candidate;
+			continue;
+		}
+		if (current.length === 0) throw new Error(`client-modules: ${record.entry.id} exceeds the ${String(MAX_COMBO_URL_BYTES)}-byte combo URL limit`);
+		chunks.push(current);
+		current = [record];
+		if (projectedComboUrlBytes(current) > MAX_COMBO_URL_BYTES) throw new Error(`client-modules: ${record.entry.id} exceeds the ${String(MAX_COMBO_URL_BYTES)}-byte combo URL limit`);
+	}
+	if (current.length > 0) chunks.push(current);
+	return chunks;
+}
+/** Remove bundle-local debug directives and retain their stable generated-file name. */
+function comboSource(record) {
+	let source = record.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}`;
+	return {
+		source,
+		fallbackSource
+	};
+}
+/** Stamp a combo script's absolute indexed-map URL 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) {
+	let body;
+	try {
+		body = readFileSync(`${clientPath}.map`);
+	} catch (error) {
+		if (error.code === "ENOENT") return void 0;
+		throw error;
+	}
+	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
+	};
+}
+/** Count generated lines while assembling indexed-map section offsets. */
+function newlineCount(value) {
+	let count = 0;
+	for (const char of value) if (char === "\n") count += 1;
+	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}`);
+	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 relocated = sourcePaths.map((source) => {
+		const separator = sourceRoot !== "" && !sourceRoot.endsWith("/") && !source.startsWith("/") ? "/" : "";
+		const resolved = new URL(`${sourceRoot}${separator}${source}`, base);
+		return resolved.origin === base.origin ? `${resolved.pathname}${resolved.search}${resolved.hash}` : resolved.href;
+	});
+	const section = {
+		...original,
+		sources: relocated
+	};
+	delete section.sourceRoot;
+	return section;
+}
+/** Map each generated line to the same line in a bundled JavaScript source. */
+function identitySectionMap(source, sourceUrl) {
+	const mappings = Array.from({ length: newlineCount(source) }, (_, index) => index === 0 ? "AAAA" : "AACA").join(";");
+	return {
+		version: 3,
+		names: [],
+		sources: [sourceUrl],
+		sourcesContent: [source],
+		mappings
+	};
+}
+/** Concatenate one or more factory registrations and compose their maps as indexed sections. */
+function buildCombo(records, revision) {
+	let source = "";
+	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);
+		sections.push({
+			offset: {
+				line,
+				column: 0
+			},
+			map: section
+		});
+		const bundle = `${prepared.source};\n`;
+		source += bundle;
+		line += newlineCount(bundle);
+	}
+	const sourceMap = Buffer.from(`${JSON.stringify({
+		version: 3,
+		file: "client.js",
+		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);
+	return {
+		url,
+		rev,
+		entries,
+		script: comboScript(source, sourceMapUrl),
+		sourceMap,
+		sourceMapUrl
+	};
+}
+/** Add initial-load scheduling metadata to a combo artifact. */
+function buildBatch(phase, records) {
+	const artifact = buildCombo(records);
+	return {
+		...artifact,
+		descriptor: {
+			phase,
+			url: artifact.url,
+			rev: artifact.rev,
+			entries: artifact.entries
+		}
+	};
 }
 /** Graph row for one bundle rev (url carries the rev as its cache-busting query). */
 function graphRow(id, rev, fields) {
 	return {
 		id,
-		url: `/plugins/${id}/client.js?rev=${rev}`,
+		url: comboUrl([id], rev),
 		rev,
 		...fields.inject !== void 0 ? { inject: fields.inject } : {},
 		...fields.immediately ? { immediately: true } : {},
@@ -194,17 +371,18 @@ function orderByModuleGraph(entries) {
 }
 /** Bootstrap package whose ordinary client bundle supplies the module-system implementation. */
 const CLIENT_MODULES_ID = "@deepseek-ai/dsh-client-modules";
-/** Ordinary dynamic bundles the HTML parser executes before the Vite shell. */
-const PARSER_PRELOAD_IDS = [CLIENT_MODULES_ID, "@deepseek-ai/dsh-client-runtime"];
+/** Dynamic bundles grouped into the parser bootstrap batch before the Vite shell. */
+const PARSER_PRELOAD_IDS = [CLIENT_MODULES_ID];
 /**
 * The boot protocol as index injection rows. The inline registration queue
-* precedes blocking classic scripts for modules' and runtime's ordinary
-* `lib/client.js` artifacts. Its `create()` method materializes the modules
+* precedes the application-batch preload and the blocking bootstrap batch. Its
+* `create()` method materializes the modules
 * bundle, delegates construction to that bundle, and leaves the same facade
 * in live-registration mode. The graph global follows before the shell reads
 * it.
 * @param graph - the composed entry graph.
-* @returns head rows in execution order: queue script, preload scripts, graph global.
+* @returns head rows in execution order: queue script, application preloads,
+* blocking bootstrap scripts, graph global.
 */
 function bootInjections(graph) {
 	const queue = `(()=>{
@@ -229,24 +407,28 @@ window.__ModuleLoader__={
   }
 }
 })()`;
-	const preload = PARSER_PRELOAD_IDS.map((id) => graph.entries.find((entry) => entry.id === id)).filter((entry) => entry !== void 0).map((entry) => ({
+	const bootstrap = graph.batches.filter((batch) => batch.phase === "bootstrap");
+	const application = graph.batches.filter((batch) => batch.phase === "application");
+	const rows = [{
+		kind: "script",
+		placement: "head",
+		text: queue
+	}];
+	for (const batch of application) rows.push({
+		kind: "script-preload",
+		src: batch.url
+	});
+	for (const batch of bootstrap) rows.push({
 		kind: "script-src",
 		placement: "head",
-		src: entry.url
-	}));
-	return [
-		{
-			kind: "script",
-			placement: "head",
-			text: queue
-		},
-		...preload,
-		{
-			kind: "global",
-			name: "__DSH_BOOT__",
-			value: graph
-		}
-	];
+		src: batch.url
+	});
+	rows.push({
+		kind: "global",
+		name: "__DSH_BOOT__",
+		value: graph
+	});
+	return rows;
 }
 /**
 * The web plugin table service: incremental `dsh.client` scan + wire composition
@@ -258,11 +440,17 @@ window.__ModuleLoader__={
 var ClientModuleRegistry = class extends Service {
 	static inject = ["webServer", "loader"];
 	table = /* @__PURE__ */ new Map();
+	sources = /* @__PURE__ */ new Map();
 	pkgMeta = /* @__PURE__ */ new Map();
 	rebuildListeners = /* @__PURE__ */ new Set();
 	graphListeners = /* @__PURE__ */ new Set();
 	dirty = /* @__PURE__ */ new Set();
-	resolvePkgJson;
+	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. */
+	previousBatchResponses = /* @__PURE__ */ new Map();
 	flushQueued = false;
 	composed;
 	/**
@@ -271,9 +459,6 @@ var ClientModuleRegistry = class extends Service {
 	*/
 	constructor(ctx) {
 		super(ctx, "clientModules");
-		if (ctx.baseUrl === void 0) throw new Error("client-modules: ctx.baseUrl is unset — the node half needs the config-tree anchor to resolve plugin packages");
-		const require = createRequire(ctx.baseUrl);
-		this.resolvePkgJson = (spec) => require.resolve(`${spec}/package.json`);
 		ctx.on("internal/plugin", (fiber) => {
 			const entryName = fiber.entry?.options.name;
 			if (entryName === void 0) return;
@@ -317,6 +502,18 @@ var ClientModuleRegistry = class extends Service {
 		return this.table.get(id)?.meta.clientPath;
 	}
 	/**
+	* Filesystem baseline captured before an entry's current bytes were read.
+	* HMR compares it with the live files when installing a watch, so a write
+	* between startup composition and watch installation cannot disappear into
+	* the watcher's initial state.
+	* @param id - entry id (package name).
+	* @returns the path and baseline, or undefined for an unknown id.
+	*/
+	artifactBaseline(id) {
+		const baseline = this.table.get(id)?.baseline;
+		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).
 	* @param id - entry id (package name).
@@ -325,9 +522,16 @@ var ClientModuleRegistry = class extends Service {
 	rebuilt(id) {
 		const record = this.table.get(id);
 		if (record === void 0) return void 0;
-		const rev = shortHash(readFileSync(record.meta.clientPath));
+		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);
+		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);
@@ -362,9 +566,46 @@ var ClientModuleRegistry = class extends Service {
 	}
 	compose() {
 		const entries = orderByModuleGraph([...this.table.values()].map((record) => record.entry));
+		const bootstrap = PARSER_PRELOAD_IDS.map((id) => this.table.get(id)).filter((record) => record !== void 0);
+		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));
+		const batchResponses = /* @__PURE__ */ new Map();
+		for (const artifact of artifacts) {
+			batchResponses.set(artifact.descriptor.url, {
+				body: artifact.script,
+				contentType: "text/javascript; charset=utf-8"
+			});
+			batchResponses.set(artifact.sourceMapUrl, {
+				body: artifact.sourceMap,
+				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,
+				contentType: "text/javascript; charset=utf-8"
+			});
+			responses.set(artifact.sourceMapUrl, {
+				body: artifact.sourceMap,
+				contentType: "application/json; charset=utf-8"
+			});
+		}
+		this.previousBatchResponses = this.batchResponses;
+		this.batchResponses = batchResponses;
+		this.responses = responses;
+		const batches = artifacts.map((artifact) => artifact.descriptor);
 		return {
-			rev: shortHash(JSON.stringify(entries)),
-			entries
+			rev: shortHash(JSON.stringify({
+				entries,
+				batches
+			})),
+			entries,
+			batches
 		};
 	}
 	notifyGraphChanged() {
@@ -374,64 +615,202 @@ var ClientModuleRegistry = class extends Service {
 			this.ctx.logger.error(error);
 		}
 	}
-	resolveMeta(pkgName) {
-		const cached = this.pkgMeta.get(pkgName);
+	resolveMeta(loaderName, baseUrl) {
+		const sourceKey = this.sourceKey(loaderName, baseUrl);
+		const cached = this.pkgMeta.get(sourceKey);
 		if (cached !== void 0) return cached;
-		let pkgPath;
-		try {
-			pkgPath = this.resolvePkgJson(pkgName);
-		} catch {
-			this.pkgMeta.set(pkgName, null);
+		const located = this.locatePkgJson(loaderName, baseUrl);
+		if (located === void 0) {
+			this.pkgMeta.set(sourceKey, null);
 			return null;
 		}
+		const { packageName, path: pkgPath } = located;
 		const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
 		const dsh = pkg.dsh;
-		const decl = parseDshClient(pkgName, dsh !== null && typeof dsh === "object" ? dsh.client : void 0);
+		const decl = parseDshClient(packageName, dsh !== null && typeof dsh === "object" ? dsh.client : void 0);
 		if (decl === void 0 || decl.platform !== "web") {
-			this.pkgMeta.set(pkgName, null);
+			this.pkgMeta.set(sourceKey, null);
 			return null;
 		}
-		const clientRel = clientExportOf(pkgName, pkg.exports);
-		if (clientRel === void 0) throw new Error(`client-modules: ${pkgName} declares dsh.client but exports no "./client" bundle`);
-		const meta = {
-			clientPath: join(dirname(pkgPath), clientRel),
-			...decl.inject !== void 0 ? { inject: decl.inject } : {},
-			external: decl.external ?? [],
-			immediately: decl.immediately === true
+		const clientRel = clientExportOf(packageName, pkg.exports);
+		if (clientRel === void 0) throw new Error(`client-modules: ${packageName} declares dsh.client but exports no "./client" bundle`);
+		const resolved = {
+			packageName,
+			meta: {
+				clientPath: join(dirname(pkgPath), clientRel),
+				...decl.inject !== void 0 ? { inject: decl.inject } : {},
+				external: decl.external ?? [],
+				immediately: decl.immediately === true
+			}
+		};
+		this.pkgMeta.set(sourceKey, resolved);
+		return resolved;
+	}
+	/**
+	* Locate the manifest of the package the Loader mounts for a row. The row's
+	* module location is authoritative: the specifier resolves through the same
+	* Loader resolution that imported the row's host half — including any
+	* active ESM hooks — and the nearest ancestor manifest declaring the name
+	* owns the module. Tree-anchored `require` resolution remains only for
+	* runtimes without Node internals.
+	* @param loaderName - module specifier of the loader row.
+	* @param baseUrl - resolution base of the tree that owns the row.
+	* @returns the manifest path, or `undefined` when the name resolves to no package root.
+	*/
+	locatePkgJson(loaderName, baseUrl) {
+		if (loaderName.startsWith("cordis:")) return void 0;
+		const pathLike = loaderName.startsWith(".") || loaderName.startsWith("file:") || isAbsolute(loaderName);
+		const expectedPackageName = pathLike ? void 0 : exactPackageSpecifier(loaderName);
+		if (!pathLike && expectedPackageName === void 0) return void 0;
+		const internal = this.ctx.loader.internal;
+		if (internal === void 0 || typeof Reflect.get(internal, "resolveSync") !== "function") {
+			if (expectedPackageName === void 0) {
+				const moduleUrl = loaderName.startsWith("file:") ? loaderName : isAbsolute(loaderName) ? pathToFileURL(loaderName).href : new URL(loaderName, baseUrl).href;
+				return this.nearestPackage(moduleUrl);
+			}
+			try {
+				return {
+					path: createRequire(baseUrl).resolve(`${expectedPackageName}/package.json`),
+					packageName: expectedPackageName
+				};
+			} catch {
+				return;
+			}
+		}
+		let moduleUrl;
+		try {
+			moduleUrl = internal.version === "v2" ? internal.resolveSync(baseUrl, {
+				specifier: loaderName,
+				attributes: {}
+			}).url : internal.resolveSync(loaderName, baseUrl, {}).url;
+		} catch {
+			return;
+		}
+		return this.nearestPackage(moduleUrl, expectedPackageName);
+	}
+	nearestPackage(moduleUrl, expectedPackageName) {
+		if (!moduleUrl.startsWith("file:")) return void 0;
+		let dir = dirname(fileURLToPath(moduleUrl));
+		while (true) {
+			const candidate = join(dir, "package.json");
+			if (existsSync(candidate)) try {
+				const name = JSON.parse(readFileSync(candidate, "utf8")).name;
+				if (typeof name === "string" && (expectedPackageName === void 0 || name === expectedPackageName)) return {
+					path: candidate,
+					packageName: name
+				};
+			} catch {}
+			const parent = dirname(dir);
+			if (parent === dir) break;
+			dir = parent;
+		}
+	}
+	sourceKey(loaderName, baseUrl) {
+		return `${baseUrl}\0${loaderName}`;
+	}
+	/** Capture the bundle stats before reading its bytes. */
+	captureArtifactBaseline(clientPath) {
+		const bundle = statSync(clientPath);
+		return {
+			path: clientPath,
+			mtimeMs: bundle.mtimeMs,
+			size: bundle.size
 		};
-		this.pkgMeta.set(pkgName, meta);
-		return meta;
+	}
+	/** Allocate an opaque initial row revision without inspecting artifact bytes. */
+	allocateInitialRevision() {
+		return `${this.initialRevisionNonce}-${String(this.nextInitialRevision++)}`;
 	}
 	/**
-	* Read the activation-time bundle revision.
+	* Read the activation-time bundle and optional source-map snapshots.
 	* @param pkgName - package that declares the client bundle.
 	* @param clientPath - absolute path of the built client artifact.
-	* @returns the bundle content's short hash for use as its revision.
+	* @returns the immutable bytes plus the pre-read filesystem baseline.
 	* @throws {MissingClientBundleError} when the read fails with `ENOENT`; other filesystem errors are rethrown unchanged.
 	*/
-	initialBundleRevision(pkgName, clientPath) {
+	initialBundleSnapshot(pkgName, clientPath) {
 		try {
-			return shortHash(readFileSync(clientPath));
+			const baseline = this.captureArtifactBaseline(clientPath);
+			const bundle = readFileSync(clientPath);
+			const sourceMap = this.readSourceMapSnapshot(clientPath);
+			return {
+				bundle,
+				baseline,
+				...sourceMap === void 0 ? {} : { sourceMap }
+			};
 		} catch (error) {
 			if (error.code !== "ENOENT") throw error;
 			throw new MissingClientBundleError(pkgName, clientPath, error);
 		}
 	}
-	/** Reconcile one entry name against the live loader entries. @returns whether the table changed. */
-	processOne(entryName) {
-		let qualifies = false;
-		for (const entry of this.ctx.loader.entries()) if (entry.options.name === entryName && entry.fiber !== void 0 && !entry.disabled) {
-			qualifies = true;
-			break;
+	/** Treat a missing, torn, or malformed development map as an identity-mapped artifact revision. */
+	readSourceMapSnapshot(clientPath) {
+		try {
+			return sourceMapSnapshot(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();
+		for (const entry of this.ctx.loader.entries()) {
+			if (entry.options.name !== entryName || entry.fiber === void 0 || entry.disabled) continue;
+			const source = this.resolveSource(entry);
+			if (source !== void 0) nextSources.set(source.sourceKey, source);
+		}
+		const affectedPackages = /* @__PURE__ */ new Set();
+		for (const [sourceKey, source] of this.sources) {
+			if (source.loaderName !== entryName) continue;
+			affectedPackages.add(source.packageName);
+			if (!nextSources.has(sourceKey)) this.sources.delete(sourceKey);
+		}
+		for (const [sourceKey, source] of nextSources) {
+			affectedPackages.add(source.packageName);
+			this.sources.set(sourceKey, source);
+		}
+		let changed = false;
+		for (const packageName of affectedPackages) try {
+			if (this.reconcilePackage(packageName)) changed = true;
+		} catch (error) {
+			onError(error instanceof Error ? error : new Error(String(error)));
+		}
+		return changed;
+	}
+	resolveSource(entry) {
+		const loaderName = entry.options.name;
+		const baseUrl = entry.parent.tree.ctx.baseUrl;
+		if (baseUrl === void 0) throw new Error(`client-modules: loader entry ${loaderName} has no resolution base URL`);
+		const resolved = this.resolveMeta(loaderName, baseUrl);
+		if (resolved === null) return void 0;
+		return {
+			...resolved,
+			loaderName,
+			baseUrl,
+			sourceKey: this.sourceKey(loaderName, baseUrl)
+		};
+	}
+	reconcilePackage(packageName) {
+		const sources = [];
+		for (const source of this.sources.values()) if (source.packageName === packageName) sources.push(source);
+		if (sources.length > 1) {
+			const locations = sources.map((source) => `${JSON.stringify(source.loaderName)} from ${source.baseUrl}`).join(", ");
+			throw new Error(`client-modules: package ${packageName} resolves from multiple active Loader sources: ${locations}; remove one entry`);
 		}
-		if (!qualifies) return this.table.delete(entryName);
-		if (this.table.has(entryName)) return false;
-		const meta = this.resolveMeta(entryName);
-		if (meta === null) return false;
-		const rev = this.initialBundleRevision(entryName, meta.clientPath);
-		this.table.set(entryName, {
-			entry: graphRow(entryName, rev, meta),
-			meta
+		const source = sources[0];
+		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();
+		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 }
 		});
 		return true;
 	}
@@ -440,7 +819,7 @@ var ClientModuleRegistry = class extends Service {
 		for (const entryName of [...this.dirty]) {
 			this.dirty.delete(entryName);
 			try {
-				if (this.processOne(entryName)) changed = true;
+				if (this.processOne(entryName, onError)) changed = true;
 			} catch (error) {
 				onError(error instanceof Error ? error : new Error(String(error)));
 			}
@@ -456,37 +835,26 @@ var ClientModuleRegistry = class extends Service {
 		this.composed = composed;
 		this.notifyGraphChanged();
 	}
-	serveBundle = async (req, res) => {
+	serveBundle = (req, res) => {
 		if (req.method !== "GET" && req.method !== "HEAD") {
 			res.writeHead(405);
 			res.end();
 			return;
 		}
 		/* v8 ignore next -- `?? '/'` arm: node:http always sets url on server requests. */
-		const pathname = decodeURIComponent(new URL(req.url ?? "/", "http://x").pathname);
-		const prefix = "/plugins/";
-		const mapSuffix = "/client.js.map";
-		const bundleSuffix = "/client.js";
-		const isSourceMap = pathname.startsWith(prefix) && pathname.endsWith(mapSuffix);
-		const suffix = isSourceMap ? mapSuffix : bundleSuffix;
-		const clientPath = pathname.startsWith(prefix) && pathname.endsWith(suffix) ? this.clientPath(pathname.slice(9, -suffix.length)) : void 0;
-		const path = clientPath === void 0 ? void 0 : `${clientPath}${isSourceMap ? ".map" : ""}`;
-		if (path === void 0) {
-			res.writeHead(404);
-			res.end();
-			return;
-		}
-		try {
-			const body = await readFile(path);
+		const requestUrl = new URL(req.url ?? "/", "http://x");
+		const resourceUrl = `${requestUrl.pathname}${requestUrl.search}`;
+		const response = this.responses.get(resourceUrl) ?? this.previousBatchResponses.get(resourceUrl);
+		if (response !== void 0) {
 			res.writeHead(200, {
-				"content-type": isSourceMap ? "application/json; charset=utf-8" : "text/javascript; charset=utf-8",
-				"cache-control": "no-cache"
+				"content-type": response.contentType,
+				"cache-control": IMMUTABLE_CACHE
 			});
-			res.end(body);
-		} catch {
-			res.writeHead(404);
-			res.end();
+			res.end(req.method === "HEAD" ? void 0 : response.body);
+			return;
 		}
+		res.writeHead(404);
+		res.end();
 	};
 };
 //#endregion