npm - @songtonyli/dsh-cli - Versions diffs - 0.1.11 → 0.1.13 - Mend

@songtonyli/dsh-cli 0.1.11 → 0.1.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1723) hide show

package/node_modules/@deepseek-ai/dsh-client-modules/README.zh.md CHANGED Viewed

@@ -35,7 +35,11 @@ kind: "package-reference"
 ### 浏览器加载什么
-application combo 脚本在启动时仅注册一次插件 factory；模块主体仍保持惰性，只在首次 import 或物化时运行。共享 combo URL 的 row 共用一个进行中的脚本任务。HMR（热模块替换）会让一条发生变化的 row 改用带 revision 的单资源 combo URL。`<id>/client` 与裸 id 解析到同一组导出，因为插件 bundle 就是其包的客户端半侧。
+application combo 脚本只携带每个插件的 `client.js` 入口，并在启动时仅注册一次这些 factory；模块主体仍保持惰性，只在首次 import 或物化时运行。经 tsdown 拆分的源码 `import()` 会编译为 `require.async("./client.<name>.js")`；只有执行该表达式时，对应的带版本同级脚本才会到达。共享 combo URL 的 row 共用一个进行中的脚本任务。HMR（热模块替换）会让一条发生变化的 row 改用带 revision 的单资源 combo URL。`<id>/client` 与裸 id 解析到同一组导出，因为插件 bundle 就是其包的客户端半侧。
+### 插件动态组合
+已打开的 Web 页面通过 HMR 传输跟随 Host 的完整模块图。启用普通插件会添加其 Loader 条目；停用会移除条目，并在其异步 effect 完成清理后回收未使用的模块与样式。再次启用会加载一个带样式的实例。其他 Loader 贡献方的条目及活动条目仍需使用的共享模块会保留。「设置 → 插件 → 插件列表」显示当前页面的同步失败，并提供不改变 Host 启用状态的重试。
 ### 共享模块
@@ -61,13 +65,13 @@ application combo 脚本在启动时仅注册一次插件 factory；模块主体
 ### 惰性 CJS 模型
-执行插件 bundle 只注册其 factory；每个模块主体副作用（包括 CSS 注入）都位于 factory 闭包中，在物化时运行（`factory(require)` → 导出，在 `loadCache` 中记忆化）。factory 依赖另一个已注册但未物化的模块时会递归物化它；require 循环会抛出异常，因为 factory 形式的 CJS 无法提供部分导出。解析会依次检查平台 seed 表、已记忆记录、启动图 row 与已注册 factory；其他情况一律抛错。交给 factory 的同步 `require` 使用相同顺序，但不含异步图 row 加载，并把观察到的边记录到模块记录中。
+执行插件 bundle 只注册其 factory；每个模块主体副作用（包括 CSS 注入）都位于 factory 闭包中，在物化时运行（`factory(require)` → 导出，在 `loadCache` 中记忆化）。factory 依赖另一个已注册但未物化的模块时会递归物化它；require 循环会抛出异常，因为 factory 形式的 CJS 无法提供部分导出。解析会依次检查平台 seed 表、已记忆记录、启动图 row 与已注册 factory；其他情况一律抛错。交给 factory 的同步 `require` 使用相同顺序，但不含异步图 row 加载，并把观察到的边记录到模块记录中。它的 `require.async` 操作返回 Promise，并在一次性物化编译器生成的包内 chunk 前先获取该 chunk。该协议只支持自包含 chunk：入口与 chunk 产物不能同步 require 另一个相对 `client*.js` 产物。
 ### 增量组合
 Node 半侧逐包增量扫描——没有全量重扫路径。每次发出 `internal/plugin` 事件时，系统都会把该 fiber 的 entry 名标脏；微任务 flush 会把每个脏名与当前 loader 条目对账，激活 pass 会初始化同一个脏集合并同步 flush，因此首次扫描与稳态共用同一实现。包元数据按 Loader specifier 与所属 tree base URL 缓存至重启，解析出的 manifest（元数据清单）包名作为浏览器模块身份。若不同的 active Loader source 解析到同一包名，组合会失败；移除冲突来源后，剩余来源无需重启 fiber 即可接替。bundle 内容变更只能通过 `rebuilt()`（HMR 钩子）进入图。
-Node 半侧会在发布前快照每个客户端 bundle，并在不构建响应 body 的情况下创建 combo descriptor。它把资源分组到 `/plugins/??...&rev=...` combo URL：modules row 使用一个 bootstrap combo，其余 row 使用一个或多个 application combo；每个阶段都会在 URL 超过 3 KiB 之前分区。脚本 body 在首次 `GET` 时只组合一次，并以对应 map URL 结尾；map 文件则在首次 map `GET` 时单独读取、校验并组合，`HEAD` 不会物化任一 body。每个 combo map 都是 Indexed Source Map v3，并在可用时使用作者提供的 section，否则为已打包 bundle 生成 identity section。初始逐插件 revision 使用进程 nonce，HMR 只哈希变化的 bundle，combo revision 从有序 row revision 派生。已公告响应在首次物化后保持不可变；未知组合或 revision 返回 404。
+Node 半侧会在发布前快照每个 `client.js` 入口，并在不构建响应 body 的情况下创建 combo descriptor。它把资源分组到 `/plugins/??...&rev=...` combo URL：modules row 使用一个 bootstrap combo，其余 row 使用一个或多个 application combo；每个阶段都会在 URL 超过 3 KiB 之前分区。脚本 body 在首次 `GET` 时只组合一次，并以对应 map URL 结尾；map 文件则在首次 map `GET` 时单独读取、校验并组合，`HEAD` 不会物化任一 body。Host 不扫描也不预加载同级 chunk：精确的 `/plugins/<package>/client.<name>.js?rev=<rev>` 请求会读取并缓存该脚本，其 map 仍会等到 map URL 被请求后才计算。每个 combo 或 chunk map 都是 Indexed Source Map v3，并在可用时使用作者提供的 section，否则为已打包 bundle 生成 identity section。初始逐插件 revision 使用进程 nonce。开发期间，共享预设会在该包所有输出写完后标记 `client.js`；HMR 从入口字节和该构建完成标记派生下一 revision，因此仅 chunk 发生重建也会更换 owner revision，无需 Host 扫描 chunk。combo revision 从有序 row revision 派生。已公告的 combo 响应与已请求的 chunk 响应会跨无关图重组保持不可变；未知资源或 revision 返回 404。
 ### 启动 manifest 注入
@@ -75,6 +79,10 @@ bundle 路由随注入的 `webServer` 生命周期注册：服务就绪时注册
 宿主贡献结构化 index 行，并向 `<head>` 注入：`window.__ModuleLoader__` queue facade、每个 application combo 的提示性 preload、阻塞 parser 的 bootstrap combo 脚本，然后才是外壳读取前的启动图。Web 载体把这些行渲染进 index 响应；由 shell 持有的载体则可以在没有 Web server 时渲染同一批行。facade 的 `create()` 物化 modules bundle、把构造委托给其 `createClientModuleSystem` 导出，并让同一 facade 进入 live registration 模式。外壳把返回的系统装成自身 Loader 的 `internal`；modules 插件将该实例发布为 `ctx.modules`，因此不同 Cordis 树不会通过模块级全局状态选择实例。
+### 条目所有权
+`ClientEntries` 记录启动时创建的条目，并在同一个 Loader 上串行执行完整图更新、重试和代码重载。本地代际阻止旧下载在目标条目或代码变化后挂载；目标相同的快照共用进行中的加载。新增模块使用单资源 URL，不会重新执行可能重复注册现有 factory 的启动 batch。Factory 在条目创建前就保留产物 revision；图更新会在导入消费者前丢弃未归属条目的陈旧 factory、其样式和失败的到达目标。清理会保留每个剩余 Loader 条目的已声明及已观察到的传递模块依赖。其可观察状态不导入运行时库，因为 modules bootstrap 在平台种子可用之前物化。
 ### 源码索引
 | 文件 | 职责 |
@@ -82,6 +90,8 @@ bundle 路由随注入的 `webServer` 生命周期注册：服务就绪时注册
 | [`src/index.ts`](src/index.ts) | Node 半侧：`ClientModuleRegistry`、扫描、产物快照、可选 combo 路由、结构化 index 行 |
 | [`src/client/index.ts`](src/client/index.ts) | 浏览器半侧：bootstrap 导出、`ctx.modules` 登记 |
 | [`src/client/system.ts`](src/client/system.ts) | `ClientModuleSystem`：加载／物化／失效机制 |
+| [`src/client/entries.ts`](src/client/entries.ts) | 页面条目对账、重试与代码替换 |
+| [`src/client/entry-lifecycle.ts`](src/client/entry-lifecycle.ts) | 通过注册表清理 Loader fiber，回收模块自身样式 |
 | [`src/client/manifest.ts`](src/client/manifest.ts) | 协议类型、启动清单解析与 `dsh.client` 声明解析器 |
 </details>
@@ -118,7 +128,7 @@ bundle 路由随注入的 `webServer` 生命周期注册：服务就绪时注册
 这些限制说明模块系统不做什么。它们是当前包约束，不是任务积压。
 - **有意采用扁平模块图**——每个 bundle 是一个模块节点，其边只指向表中的叶节点；接口（`loadCache`/`edges`/`invalidate`）已经支持通用模块图，因此可以改变 externalization 粒度而不更改接口。
-- **自身不维护卸载记录**——样式移除与 fiber 拆卸顺序属于 HMR 驱动器（`@deepseek-ai/dsh-client-hmr`）；loader 只在每条记录中登记其拥有的样式标签 id。
+- **Bootstrap 与代码替换限制**——页面保留 modules bootstrap 和静态平台模块的身份。移除或替换 bootstrap 需要刷新页面；动态替换请求会报告页面本地错误，并保留其 fiber 与导出；替换包代码及其所有现有消费者不属于普通启停同步。
 - **惰性提供会保留已请求的 body**——Host 在内存中保留每个 bundle 与惰性响应计划；脚本或 map body 在首次 `GET` 后保留缓存，HMR 还会保留上一代启动响应。内存仅随客户端实际请求的响应 body 增长，同时保留一代竞态容忍。
 - **从未请求的上一代 map 会读取当前 map 文件**——combo revision 跟踪可执行 bundle，而不跟踪调试产物。若 HMR 在保留的旧 URL 首次收到 map `GET` 前重建 map，该响应会把当前 authored map 与旧 bundle offset 组合；在重建前请求 map 会固定该 URL 的响应。

package/node_modules/@deepseek-ai/dsh-client-modules/lib/client.js CHANGED Viewed

@@ -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;
 	}
 });