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

package/lib/index.js

@@ -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;
@@ -187,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));
@@ -218,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
@@ -233,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`);
@@ -245,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) {
@@ -257,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);
@@ -287,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,
@@ -302,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: {
@@ -521,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,
@@ -546,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.
 	*/
@@ -556,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);
@@ -602,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;
@@ -754,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.
@@ -763,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();
@@ -841,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;
 	}
@@ -867,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

@@ -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';
 /**

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

@@ -29,6 +29,7 @@
  * composes the wire.
  */
 import type { DshClientManifest } from '@deepseek-ai/dsh-package-manifest';
+import type { ClientEntries } from './entries.ts';
 import type { ClientModuleSystem } from './system.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -58,22 +59,22 @@ export interface WebBootEntry {
     /** Non-baseline module specifiers this row requests; omitted when it requests none. */
     external?: string[];
 }
-/** Initial scheduling phase for one content-addressed combo script. */
+/** Initial scheduling phase for one revisioned combo script. */
 export type WebBootBatchPhase = 'bootstrap' | 'application';
 /** One initial combo script; a scheduling phase may span several descriptors. */
 export interface WebBootBatch {
     /** Parser-blocking bootstrap or preloaded application scheduling. */
     phase: WebBootBatchPhase;
-    /** Content-addressed combo script endpoint. */
+    /** Revisioned combo script endpoint. */
     url: string;
-    /** Revision over the combined plugin script bytes and indexed source map. */
+    /** Revision derived from the ordered entry revisions. */
     rev: string;
     /** Graph entry ids whose factories the script registers, in execution order. */
     entries: string[];
 }
 /** The composed client entry graph the host injects as `window.__DSH_BOOT__`. */
 export interface WebBootGraph {
-    /** Consistency anchor over the whole graph (content + bundle hashes). */
+    /** Consistency anchor over the current entry and batch descriptors. */
     rev: string;
     /**
      * Composed entries in module-graph order — a dynamic package row precedes
@@ -90,7 +91,7 @@ export interface BootModuleRow {
     id: string;
     /** Revisioned single-resource combo endpoint used after HMR invalidation. */
     url: string;
-    /** Content-addressed combo endpoint used before the first HMR invalidation. */
+    /** Revisioned combo endpoint used before the first HMR invalidation. */
     initialUrl: string;
     /** Opaque plugin-artifact revision used after HMR invalidation. */
     rev: string;
@@ -162,16 +163,25 @@ export declare function stripClientSuffix(spec: string): string;
  * @returns the manifest with optional plugin-view fields normalized.
  */
 export declare function parseBootManifest(wire: unknown): BootManifest;
+/** Module resolver passed into a registered Client bundle factory. */
+export interface ClientBundleRequire {
+    /** Resolve a module-table dependency synchronously. */
+    (specifier: string): unknown;
+    /** Load and resolve a package-local dynamic chunk asynchronously. */
+    async(specifier: string): Promise<unknown>;
+}
 /** One client bundle's factory registration submitted through `window.__ModuleLoader__.load`. */
 export interface ClientBundleRegistration {
     /** Plugin id (package name) — the registration key; must match the graph row being executed. */
     id: string;
+    /** Package-local chunk filename; absent for the package's `client.js` entry. */
+    chunk?: string;
     /**
-     * Closure factory holding the whole bundle body: receives the synchronous
-     * require bound to the module table and returns the bundle's exports. Runs
-     * once, at materialization.
+     * Closure factory holding the whole bundle body: receives the module-table
+     * require whose `async` operation loads generated chunks, and returns the
+     * bundle's exports. The factory runs once, at materialization.
      */
-    factory: (require: (spec: string) => unknown) => Record<string, unknown>;
+    factory: (require: ClientBundleRequire) => Record<string, unknown>;
 }
 /** Inputs passed by the web entry when it creates the client module system. */
 export interface ClientModuleCreateOptions {
@@ -226,9 +236,11 @@ export interface ClientModuleRecord {
 export interface ClientModuleLoader {
     /** Discriminant against Node's internal loader shapes ('v1'/'v2'). */
     version: 'client';
-    /** Parsed Host boot graph shared with the web entry after module-system creation. */
+    /** Latest parsed Host graph, updated by live entry reconciliation. */
     manifest: BootManifest;
-    /** Materialized-module registry: id → record. The governance-side read API for entry exports. */
+    /** Page-owned entry reconciliation, shared by boot, graph updates and HMR. */
+    entries: ClientEntries;
+    /** Materialized-module registry: entry or package-local chunk id → record. */
     loadCache: Map<string, ClientModuleRecord>;
     /**
      * Internal contract consumed by the vendored Loader's `tree.import`. Resolves
@@ -252,8 +264,8 @@ export interface ClientModuleLoader {
      */
     prefetch(id: string): Promise<void>;
     /**
-     * Full reset of one non-bootstrap module: drop its registered factory and
-     * materialized record so the next prefetch/import loads its one-resource
+     * Full reset of one non-bootstrap package: drop its entry and chunk factories
+     * and materialized records so the next prefetch/import loads its one-resource
      * combo script rather than the initial multi-resource request. The bootstrap
      * module remains materialized.
      * @param id - entry name to invalidate.
@@ -264,7 +276,7 @@ export interface ClientModuleLoader {
 }
 /** Internal construction inputs assembled by the modules bundle's bootstrap export. */
 export interface ClientModuleSystemOptions {
-    /** Parsed boot graph owned by the resulting module system. */
+    /** Boot graph validated by {@link parseBootManifest}, owned by the resulting module system. */
     manifest: BootManifest;
     /** Module-table seed: platform-singleton specifier → shell instance. */
     staticModules: Record<string, unknown>;

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

@@ -1,3 +1,4 @@
+import { ClientEntries } from './entries.ts';
 import type { BootManifest, ClientModuleLoader, ClientModuleRecord, ClientModuleSystemOptions } from './manifest.ts';
 /**
  * The client module system: state tables plus the arrival/materialization
@@ -8,15 +9,18 @@ import type { BootManifest, ClientModuleLoader, ClientModuleRecord, ClientModule
  */
 export declare class ClientModuleSystem implements ClientModuleLoader {
     readonly version = "client";
-    readonly manifest: BootManifest;
+    manifest: BootManifest;
+    readonly entries: ClientEntries;
     readonly loadCache: Map<string, ClientModuleRecord>;
     private readonly seed;
     private readonly factories;
     private readonly bootstrapIds;
     /** In-flight script transport per URL; every row in one batch shares it. */
     private readonly pendingArrival;
+    /** Owner generation captured by in-flight chunk requests and advanced on invalidation. */
+    private readonly generations;
     /** Single-resource combo URL selected by HMR after invalidating one row. */
-    private readonly reloadUrls;
+    private readonly reloadTargets;
     /** Materialization re-entrancy guard: factory-form CJS cannot deliver partial exports, so a cycle is fatal. */
     private readonly materializing;
     private readonly graphRows;
@@ -34,15 +38,16 @@ export declare class ClientModuleSystem implements ClientModuleLoader {
     private arriveGraphRow;
     /** Materialize a registered factory (synchronous; memoized in loadCache). */
     private materialize;
-    /**
-     * The synchronous require answered to factories: seed → memoized record →
-     * registered factory. Fetching is async and therefore unreachable
-     * from here; an external dynamic package must have arrived before its
-     * consumer materializes.
-     */
+    /** Build the synchronous module-table require and its asynchronous chunk operation. */
     private makeRequire;
+    /** Load, register, and materialize one package-local dynamic chunk. */
+    private importChunk;
     import(specifier: string): Promise<unknown>;
     prefetch(id: string): Promise<void>;
+    /** Refresh descriptors and unowned factory revisions before any entry imports its dependencies. */
+    private updateManifest;
+    /** Retain live Loader modules and their transitive requests before evicting unreferenced graph records. */
+    private prune;
     invalidate(id: string, rev?: string): void;
 }
 //# sourceMappingURL=system.d.ts.map