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

package/lib/client.js

@@ -172,6 +172,274 @@ window.__ModuleLoader__.load({
 			};
 		}
 		//#endregion
+		//#region lib/types/client/entry-lifecycle.js
+		/**
+		* 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.
+		*/
+		async function tearDownEntryFiber(entry) {
+			const fiber = entry.fiber;
+			if (fiber === void 0) return;
+			const runtime = fiber.runtime;
+			/* v8 ignore next -- Loader entries own plugin fibers; only the root context has a null runtime. */
+			if (runtime !== null) entry.ctx.registry.delete(runtime.callback);
+			while (fiber.inertia !== void 0) await fiber.inertia;
+			delete entry.fiber;
+		}
+		/**
+		* Remove styles after their plugin's effect cleanup has settled.
+		* @param id - Package whose factory owns the style tags.
+		*/
+		function removeOwnedStyles(id) {
+			if (typeof document === "undefined") return;
+			for (const el of document.querySelectorAll("style[data-plugin]")) if (el.getAttribute("data-plugin") === id) el.remove();
+		}
+		//#endregion
+		//#region lib/types/client/entries.js
+		/** Numeric values mirror Cordis's const enum, which bundle loaders cannot import as a runtime object. */
+		const ACTIVE = 2;
+		const FAILED = 3;
+		/** Revisions and requests identify desired code; URLs only select its immutable delivery resource. */
+		function entryTargets(manifest) {
+			return JSON.stringify(manifest.modules.map((row) => [
+				row.id,
+				row.rev,
+				row.inject,
+				row.external
+			]));
+		}
+		/** Manages only entries created from the Host manifest; other Loader contributors retain ownership. */
+		var ClientEntries = class {
+			modules;
+			index;
+			/** Stable observable consumed by page diagnostics through the renderer's injected hook. */
+			state = {
+				getSnapshot: () => this.snapshot,
+				subscribe: (listener) => {
+					this.listeners.add(listener);
+					return () => {
+						this.listeners.delete(listener);
+					};
+				}
+			};
+			snapshot = {
+				syncing: false,
+				failures: []
+			};
+			listeners = /* @__PURE__ */ new Set();
+			managed = /* @__PURE__ */ new Map();
+			revisions = /* @__PURE__ */ new Map();
+			loader;
+			queue = Promise.resolve();
+			desired;
+			generation = 0;
+			stopped = false;
+			/**
+			* 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, index) {
+				this.modules = modules;
+				this.index = index;
+				this.desired = modules.manifest;
+			}
+			/**
+			* 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, manifest) {
+				if (this.loader !== void 0) throw new Error("client-modules: entries already started");
+				this.loader = loader;
+				this.desired = manifest;
+				loader.ctx.effect(() => () => {
+					this.stopped = true;
+					this.generation++;
+					return this.queue;
+				}, "client-modules: entry reconciliation");
+				return this.enqueue(async () => {
+					await Promise.all(this.desired.plugins.map(async ({ id }) => {
+						await this.create(loader, id);
+					}));
+					await loader.await();
+					for (const row of this.modules.manifest.modules) this.revisions.set(row.id, row.rev);
+				});
+			}
+			/**
+			* 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) {
+				const manifest = parseBootManifest(graph);
+				if (entryTargets(manifest) !== entryTargets(this.desired)) this.generation++;
+				this.desired = manifest;
+				const generation = this.generation;
+				return this.enqueue(() => this.reconcile(generation));
+			}
+			/**
+			* Retry failed entries against the latest graph, including an unchanged revision.
+			* @returns after retry settlement, with remaining errors in {@link state}.
+			*/
+			retry() {
+				const generation = ++this.generation;
+				return this.enqueue(() => this.reconcile(generation));
+			}
+			/**
+			* 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, rev) {
+				this.desired = {
+					...this.desired,
+					modules: this.desired.modules.map((row) => row.id === id ? {
+						...row,
+						rev
+					} : row)
+				};
+				return this.enqueue(async () => {
+					const desired = this.desired.modules.find((row) => row.id === id);
+					if (this.stopped || desired === void 0) return;
+					const entry = this.managed.get(id);
+					if (entry === void 0) {
+						this.modules.invalidate(id, desired.rev);
+						removeOwnedStyles(id);
+						await this.reconcile(this.generation);
+						return;
+					}
+					if (this.revisions.get(id) === rev) return;
+					this.publish({
+						syncing: true,
+						failures: this.snapshot.failures.filter((failure) => failure.id !== id)
+					});
+					await this.replace(entry, id, rev, this.generation);
+					this.publish({
+						syncing: false,
+						failures: this.snapshot.failures
+					});
+				}, id);
+			}
+			publish(snapshot) {
+				this.snapshot = snapshot;
+				for (const listener of [...this.listeners]) try {
+					listener();
+				} catch (error) {
+					console.error("client-modules: synchronization subscriber failed", error);
+				}
+			}
+			enqueue(task, subject = "graph") {
+				const run = this.queue.then(task);
+				this.queue = run.then(() => void 0, (error) => {
+					this.publish({
+						syncing: false,
+						failures: [...this.snapshot.failures.filter((failure) => failure.id !== subject), {
+							id: subject,
+							message: String(error)
+						}]
+					});
+				});
+				return run;
+			}
+			current(generation) {
+				return !this.stopped && generation === this.generation;
+			}
+			/** Keep ownership even when Loader rejects a module's plugin exports after inserting its entry. */
+			async create(loader, id) {
+				const options = { name: id };
+				const entryId = loader.ensureId(options);
+				try {
+					await loader.create(options);
+				} finally {
+					this.managed.set(id, loader.resolve(entryId));
+				}
+			}
+			async replace(entry, id, rev, generation) {
+				this.index.invalidateForReplacement(id, rev);
+				await this.modules.prefetch(id);
+				if (!this.current(generation)) return;
+				await tearDownEntryFiber(entry);
+				removeOwnedStyles(id);
+				if (!this.current(generation)) return;
+				await this.modules.import(id, "", {});
+				if (!this.current(generation)) return;
+				await entry.refresh();
+				await entry.fiber?.await();
+				if (entry.fiber === void 0) throw new Error(`client-modules: ${id} import failed (see console)`);
+				this.revisions.set(id, rev);
+			}
+			async reconcile(generation) {
+				if (!this.current(generation)) return;
+				const loader = this.loader;
+				if (loader === void 0) throw new Error("client-modules: entries have not started");
+				const manifest = this.desired;
+				this.publish({
+					syncing: true,
+					failures: []
+				});
+				const failures = [];
+				this.index.update(manifest, this.managed.keys());
+				const wanted = new Set(manifest.plugins.map((row) => row.id));
+				for (const [id, entry] of this.managed) {
+					if (wanted.has(id)) continue;
+					const fiber = entry.fiber;
+					loader.remove(entry.id);
+					this.managed.delete(id);
+					this.revisions.delete(id);
+					while (fiber?.inertia !== void 0) await fiber.inertia;
+				}
+				for (const row of manifest.modules) {
+					if (!this.current(generation)) break;
+					try {
+						const entry = this.managed.get(row.id);
+						if (entry === void 0) {
+							await this.modules.prefetch(row.id);
+							if (!this.current(generation)) break;
+							await this.modules.import(row.id, "", {});
+							if (!this.current(generation)) break;
+							await this.create(loader, row.id);
+							this.revisions.set(row.id, row.rev);
+						} else if (this.revisions.get(row.id) !== row.rev) await this.replace(entry, row.id, row.rev, generation);
+						else if (entry.fiber === void 0) await this.replace(entry, row.id, row.rev, generation);
+						else if (entry.fiber.state === FAILED) entry.fiber.update(entry.options.config);
+					} catch (error) {
+						failures.push({
+							id: row.id,
+							message: String(error)
+						});
+					}
+				}
+				await loader.await();
+				for (const [id, entry] of this.managed) {
+					if (failures.some((failure) => failure.id === id)) continue;
+					if (entry.fiber?.state === ACTIVE) continue;
+					try {
+						if (entry.fiber === void 0) throw new Error(`client-modules: ${id} import failed (see console)`);
+						await entry.fiber.await();
+						failures.push({
+							id,
+							message: `client-modules: ${id} is waiting for activation`
+						});
+					} catch (error) {
+						failures.push({
+							id,
+							message: String(error)
+						});
+					}
+				}
+				this.index.prune([...loader.entries()].map((entry) => entry.options.name));
+				if (this.current(generation)) this.publish({
+					syncing: false,
+					failures
+				});
+			}
+		};
+		//#endregion
 		//#region lib/types/client/system.js
 		/**
 		* ClientModuleSystem — the implementation behind the {@link ClientModuleLoader}
@@ -199,6 +467,19 @@ window.__ModuleLoader__.load({
 			if (!/[?&]rev=[^&#]*/.test(url)) throw new Error(`client-modules: bundle URL ${url} has no revision`);
 			return url.replace(/([?&]rev=)[^&#]*/, `$1${encodeURIComponent(rev)}`);
 		}
+		const CLIENT_CHUNK = /^client\.[A-Za-z0-9][A-Za-z0-9._-]*\.js$/;
+		/** Internal module-table key for one package-local chunk. */
+		function chunkId(ownerId, fileName) {
+			return `${ownerId}/${fileName}`;
+		}
+		/** Resolve a sibling chunk against the package's one-resource URL and current revision. */
+		function chunkUrl(row, fileName, rev) {
+			const url = atRevision(row.url, rev);
+			const resourceStart = url.indexOf("/??");
+			const revisionStart = url.indexOf("&rev=", resourceStart + 3);
+			if ((resourceStart < 0 || revisionStart < 0 ? void 0 : url.slice(resourceStart + 3, revisionStart)) !== `${row.id}/client.js`) throw new Error(`client-modules: cannot resolve chunk ${JSON.stringify(fileName)} from bundle URL ${url}`);
+			return `${url.slice(0, resourceStart)}/${row.id}/${fileName}?${url.slice(revisionStart + 1)}`;
+		}
 		/**
 		* Claim and inventory the <style> tags a factory injected during
 		* materialization: preset-emitted tags arrive pre-tagged with data-plugin;
@@ -221,14 +502,17 @@ window.__ModuleLoader__.load({
 		var ClientModuleSystem = class {
 			version = "client";
 			manifest;
+			entries;
 			loadCache = /* @__PURE__ */ new Map();
 			seed;
 			factories = /* @__PURE__ */ new Map();
 			bootstrapIds = /* @__PURE__ */ new Set();
 			/** In-flight script transport per URL; every row in one batch shares it. */
 			pendingArrival = /* @__PURE__ */ new Map();
+			/** Owner generation captured by in-flight chunk requests and advanced on invalidation. */
+			generations = /* @__PURE__ */ new Map();
 			/** Single-resource combo URL selected by HMR after invalidating one row. */
-			reloadUrls = /* @__PURE__ */ new Map();
+			reloadTargets = /* @__PURE__ */ new Map();
 			/** Materialization re-entrancy guard: factory-form CJS cannot deliver partial exports, so a cycle is fatal. */
 			materializing = /* @__PURE__ */ new Set();
 			graphRows = /* @__PURE__ */ new Map();
@@ -239,12 +523,21 @@ window.__ModuleLoader__.load({
 			*/
 			constructor(options) {
 				this.manifest = options.manifest;
+				this.entries = new ClientEntries(this, {
+					update: (manifest, managed) => {
+						this.updateManifest(manifest, managed);
+					},
+					invalidateForReplacement: (id, rev) => {
+						if (this.bootstrapIds.has(id)) throw new Error(`client-modules: replacing bootstrap module ${id} requires a page reload`);
+						this.invalidate(id, rev);
+					},
+					prune: (roots) => {
+						this.prune(roots);
+					}
+				});
 				this.seed = new Map(Object.entries(options.staticModules));
 				this.loadBundle = options.loadBundle ?? defaultLoadBundle;
-				for (const row of options.manifest.modules) {
-					if (this.graphRows.has(row.id)) throw new Error(`client-modules: duplicate graph entry "${row.id}"`);
-					this.graphRows.set(row.id, row);
-				}
+				for (const row of options.manifest.modules) this.graphRows.set(row.id, row);
 				const bootstrapId = stripClientSuffix(options.bootstrapModule.id);
 				this.bootstrapIds.add(bootstrapId);
 				this.loadCache.set(bootstrapId, {
@@ -264,16 +557,24 @@ window.__ModuleLoader__.load({
 			}
 			/** Register one bundle factory, rejecting a script that executes twice without invalidation. */
 			register(registration) {
-				const id = stripClientSuffix(registration.id);
-				if (this.bootstrapIds.has(id) || this.factories.has(id)) throw new Error(`client-modules: duplicate factory registration for "${registration.id}" (bundle executed twice without invalidate?)`);
-				this.factories.set(id, registration.factory);
+				const ownerId = stripClientSuffix(registration.id);
+				if (registration.chunk !== void 0 && !CLIENT_CHUNK.test(registration.chunk)) throw new Error(`client-modules: invalid package-local chunk ${JSON.stringify(registration.chunk)}`);
+				const id = registration.chunk === void 0 ? ownerId : chunkId(ownerId, registration.chunk);
+				if (this.bootstrapIds.has(id) || this.factories.has(id)) {
+					const registrationName = registration.chunk === void 0 ? registration.id : id;
+					throw new Error(`client-modules: duplicate factory registration for "${registrationName}" (bundle executed twice without invalidate?)`);
+				}
+				this.factories.set(id, {
+					factory: registration.factory,
+					rev: this.reloadTargets.get(ownerId)?.rev ?? this.graphRows.get(ownerId)?.rev
+				});
 			}
 			/** Load one graph row so its factory is registered (idempotent per in-flight arrival). */
 			arrive(row) {
 				const { id } = row;
 				if (this.loadCache.has(id) || this.factories.has(id)) return Promise.resolve();
-				const reloadUrl = this.reloadUrls.get(id);
-				const url = reloadUrl ?? row.initialUrl;
+				const reload = this.reloadTargets.get(id);
+				const url = reload?.url ?? row.initialUrl;
 				let transport = this.pendingArrival.get(url);
 				if (transport === void 0) {
 					transport = this.loadBundle(url).finally(() => {
@@ -283,7 +584,7 @@ window.__ModuleLoader__.load({
 				}
 				return transport.then(() => {
 					if (!this.factories.has(id)) throw new Error(`client-modules: bundle ${url} loaded without registering "${id}" via __ModuleLoader__.load`);
-					if (reloadUrl !== void 0 && this.reloadUrls.get(id) === reloadUrl) this.reloadUrls.delete(id);
+					if (reload !== void 0 && this.reloadTargets.get(id) === reload) this.reloadTargets.delete(id);
 				});
 			}
 			/** Register each injected package and unresolved dynamic request before its consumer. */
@@ -306,7 +607,7 @@ window.__ModuleLoader__.load({
 				await this.arrive(row);
 			}
 			/** Materialize a registered factory (synchronous; memoized in loadCache). */
-			materialize(id) {
+			materialize(id, ownerId = id) {
 				const existing = this.loadCache.get(id);
 				if (existing !== void 0) return existing;
 				const registered = this.factories.get(id);
@@ -318,24 +619,22 @@ window.__ModuleLoader__.load({
 					const edges = /* @__PURE__ */ new Set();
 					const record = {
 						id,
-						exports: registered(this.makeRequire(edges)),
-						styles: claimStyles(id),
+						exports: registered.factory(this.makeRequire(ownerId, edges)),
+						styles: claimStyles(ownerId),
 						edges
 					};
 					this.loadCache.set(id, record);
 					return record;
+				} catch (error) {
+					removeOwnedStyles(ownerId);
+					throw error;
 				} finally {
 					this.materializing.delete(id);
 				}
 			}
-			/**
-			* 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.
-			*/
-			makeRequire(edges) {
-				return (spec) => {
+			/** Build the synchronous module-table require and its asynchronous chunk operation. */
+			makeRequire(ownerId, edges) {
+				const require = (spec) => {
 					edges.add(spec);
 					if (this.seed.has(spec)) return this.seed.get(spec);
 					const id = stripClientSuffix(spec);
@@ -344,6 +643,41 @@ window.__ModuleLoader__.load({
 					if (this.factories.has(id)) return this.materialize(id).exports;
 					throw new Error(`client-modules: require("${spec}") missed the module table — not a platform seed word, not a materialized module, and no registered package factory (a build-time externals drift, or a dynamic dependency that did not arrive)`);
 				};
+				require.async = async (spec) => {
+					edges.add(spec);
+					if (!spec.startsWith("./")) return await this.import(spec);
+					const fileName = spec.slice(2);
+					if (!CLIENT_CHUNK.test(fileName)) throw new Error(`client-modules: invalid relative chunk request ${JSON.stringify(spec)}`);
+					return await this.importChunk(ownerId, fileName);
+				};
+				return require;
+			}
+			/** Load, register, and materialize one package-local dynamic chunk. */
+			async importChunk(ownerId, fileName) {
+				const id = chunkId(ownerId, fileName);
+				const existing = this.loadCache.get(id);
+				if (existing !== void 0) return existing.exports;
+				if (!this.factories.has(id)) {
+					const generation = this.generations.get(ownerId) ?? 0;
+					const row = this.graphRows.get(ownerId);
+					if (row === void 0) throw new Error(`client-modules: chunk owner "${ownerId}" is not a boot graph entry`);
+					const url = chunkUrl(row, fileName, this.factories.get(ownerId)?.rev ?? this.reloadTargets.get(ownerId)?.rev ?? row.rev);
+					let transport = this.pendingArrival.get(url);
+					if (transport === void 0) {
+						transport = this.loadBundle(url).finally(() => {
+							this.pendingArrival.delete(url);
+						});
+						this.pendingArrival.set(url, transport);
+					}
+					await transport;
+					if ((this.generations.get(ownerId) ?? 0) !== generation) {
+						this.factories.delete(id);
+						this.loadCache.delete(id);
+						return await this.importChunk(ownerId, fileName);
+					}
+					if (!this.factories.has(id)) throw new Error(`client-modules: bundle ${url} loaded without registering "${id}" via __ModuleLoader__.load`);
+				}
+				return this.materialize(id, ownerId).exports;
 			}
 			async import(specifier) {
 				if (this.seed.has(specifier)) return this.seed.get(specifier);
@@ -362,14 +696,60 @@ window.__ModuleLoader__.load({
 				if (row === void 0) throw new Error(`client-modules: prefetch("${id}") — not a graph entry`);
 				await this.arriveGraphRow(row);
 			}
+			/** Refresh descriptors and unowned factory revisions before any entry imports its dependencies. */
+			updateManifest(manifest, managed) {
+				for (const id of this.bootstrapIds) if (this.manifest.modules.some((row) => row.id === id) && !manifest.modules.some((row) => row.id === id)) throw new Error(`client-modules: removing bootstrap module ${id} requires a page reload`);
+				const owned = new Set(managed);
+				for (const row of manifest.modules) {
+					this.graphRows.set(row.id, {
+						...row,
+						initialUrl: row.url
+					});
+					const cachedRevision = this.factories.get(row.id)?.rev ?? this.reloadTargets.get(row.id)?.rev;
+					if (!owned.has(row.id) && cachedRevision !== void 0 && cachedRevision !== row.rev) {
+						this.invalidate(row.id, row.rev);
+						removeOwnedStyles(row.id);
+					}
+				}
+				this.manifest = manifest;
+			}
+			/** Retain live Loader modules and their transitive requests before evicting unreferenced graph records. */
+			prune(roots) {
+				const retained = new Set(this.bootstrapIds);
+				const visit = (specifier) => {
+					const id = stripClientSuffix(specifier);
+					if (retained.has(id)) return;
+					retained.add(id);
+					const row = this.graphRows.get(id);
+					for (const request of [
+						...row?.external ?? [],
+						...row?.inject ?? [],
+						...this.loadCache.get(id)?.edges ?? []
+					]) visit(request);
+				};
+				for (const row of this.manifest.modules) visit(row.id);
+				for (const id of roots) visit(id);
+				for (const id of this.graphRows.keys()) {
+					if (retained.has(id)) continue;
+					this.graphRows.delete(id);
+					this.invalidate(id);
+					removeOwnedStyles(id);
+				}
+			}
 			invalidate(id, rev) {
 				const normalized = stripClientSuffix(id);
 				if (this.bootstrapIds.has(normalized)) return;
+				this.generations.set(normalized, (this.generations.get(normalized) ?? 0) + 1);
 				const row = this.graphRows.get(normalized);
-				if (row !== void 0) this.reloadUrls.set(normalized, atRevision(row.url, rev ?? row.rev));
-				else this.reloadUrls.delete(normalized);
-				this.factories.delete(normalized);
-				this.loadCache.delete(normalized);
+				if (row !== void 0) {
+					const revision = rev ?? row.rev;
+					this.reloadTargets.set(normalized, {
+						url: atRevision(row.url, revision),
+						rev: revision
+					});
+				} else this.reloadTargets.delete(normalized);
+				for (const key of this.factories.keys()) if (key === normalized || key.startsWith(`${normalized}/client.`)) this.factories.delete(key);
+				for (const key of this.loadCache.keys()) if (key === normalized || key.startsWith(`${normalized}/client.`)) this.loadCache.delete(key);
 			}
 		};
 		//#endregion
@@ -410,6 +790,7 @@ window.__ModuleLoader__.load({
 		exports.parseBootManifest = parseBootManifest;
 		exports.parseDshClient = parseDshClient;
 		exports.stripClientSuffix = stripClientSuffix;
+		exports.tearDownEntryFiber = tearDownEntryFiber;
 		return module.exports;
 	}
 });