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

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/modules/README.md
-README.md: c99293b1f7a26a86279c4d71d9d6f41c6452b13e
-README.zh.md: f6057204e1a039cecb824a3c355f4d7b906abac9
+README.md: 3388eb2ae421b303df6709f0bfc656fe67e3a866
+README.zh.md: 3cbc600ee5ed211640070773efb72f58b91d4669

package/README.md

@@ -35,7 +35,7 @@ A browser plugin package declares `dsh.client` in its `package.json` with `platf
 
 ### What the browser loads
 
-The application combo scripts carry only each plugin's `client.js` entry and register those factories once during boot; module bodies remain lazy and run only at first import or materialization. A source `import()` split by tsdown compiles to `require.async("./client.<name>.js")`; its versioned sibling script arrives only when that expression runs. Rows that share a combo URL share one in-flight script task. HMR switches one changed row to its revisioned one-resource combo URL. `<id>/client` and the bare id resolve to the same exports, because a plugin bundle is its package's client half.
+The application combo scripts carry only each plugin's `client.js` entry and register those factories once during boot; module bodies remain lazy and run only at first import or materialization. A source `import()` split by tsdown compiles to `require.async("./client.<name>.js")`; its versioned sibling script arrives only when that expression runs. Rows that share a combo URL share one in-flight script task. A combo whose `<script>` fails to load is requested once more; a combo that loads without registering a row is never re-executed, because the batch script registers its packages in sequence and a replay would stop at the first duplicate registration. In both cases each still-missing row then loads its own one-resource combo URL, so one failed batch costs at most three requests per missing row and leaves the rows it did register untouched. The module system records the last import failure per row (transport, registration, dependency cascade, or factory execution); the Web boot audit reports that text per entry. HMR switches one changed row to its revisioned one-resource combo URL. `<id>/client` and the bare id resolve to the same exports, because a plugin bundle is its package's client half.
 
 ### Live plugin composition
 

package/README.zh.md

@@ -35,7 +35,7 @@ kind: "package-reference"
 
 ### 浏览器加载什么
 
-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 就是其包的客户端半侧。
+application combo 脚本只携带每个插件的 `client.js` 入口，并在启动时仅注册一次这些 factory；模块主体仍保持惰性，只在首次 import 或物化时运行。经 tsdown 拆分的源码 `import()` 会编译为 `require.async("./client.<name>.js")`；只有执行该表达式时，对应的带版本同级脚本才会到达。共享 combo URL 的 row 共用一个进行中的脚本任务。`<script>` 加载失败的 combo 会再请求一次；加载成功但没有注册某条 row 的 combo 绝不会重新执行，因为批量脚本按顺序注册各个包，重放会在第一个重复注册处停止。两种情况下，每条仍缺失的 row 随后加载自己的单资源 combo URL，因此一个失败的 batch 对每条缺失 row 最多花费三次请求，且不影响它已经注册的 row。模块系统按 row 记录最后一次 import 失败（传输、注册、依赖级联或 factory 执行）；Web 启动审计按条目报告该文本。HMR（热模块替换）会让一条发生变化的 row 改用带 revision 的单资源 combo URL。`<id>/client` 与裸 id 解析到同一组导出，因为插件 bundle 就是其包的客户端半侧。
 
 ### 插件动态组合
 

package/lib/client.js

@@ -468,6 +468,10 @@ window.__ModuleLoader__.load({
 			return url.replace(/([?&]rev=)[^&#]*/, `$1${encodeURIComponent(rev)}`);
 		}
 		const CLIENT_CHUNK = /^client\.[A-Za-z0-9][A-Za-z0-9._-]*\.js$/;
+		/** The message of a thrown value: an Error's message, anything else stringified. */
+		function describeError(error) {
+			return error instanceof Error ? error.message : String(error);
+		}
 		/** Internal module-table key for one package-local chunk. */
 		function chunkId(ownerId, fileName) {
 			return `${ownerId}/${fileName}`;
@@ -517,6 +521,12 @@ window.__ModuleLoader__.load({
 			materializing = /* @__PURE__ */ new Set();
 			graphRows = /* @__PURE__ */ new Map();
 			loadBundle;
+			/** Last import or prefetch failure per graph row, cleared by a later success or invalidation. */
+			importErrors = /* @__PURE__ */ new Map();
+			/** Batch URLs whose transport or execution already failed; rows still missing from them go straight to their one-resource URL. */
+			failedBundleUrls = /* @__PURE__ */ new Set();
+			/** Every URL whose script has executed once; a batch among them is never requested again. */
+			executedBundleUrls = /* @__PURE__ */ new Set();
 			/**
 			* Build the module system over the parsed boot rows.
 			* @param options - Parsed graph, platform seed, bootstrap module, registration facade, and transport.
@@ -569,23 +579,66 @@ window.__ModuleLoader__.load({
 					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 reload = this.reloadTargets.get(id);
-				const url = reload?.url ?? row.initialUrl;
+			/** Run one bundle transport per URL; every row waiting on the same URL shares the in-flight request. */
+			loadShared(url) {
 				let transport = this.pendingArrival.get(url);
 				if (transport === void 0) {
-					transport = this.loadBundle(url).finally(() => {
+					transport = this.loadBundle(url).then(() => {
+						this.executedBundleUrls.add(url);
+					}).finally(() => {
 						this.pendingArrival.delete(url);
 					});
 					this.pendingArrival.set(url, transport);
 				}
-				return transport.then(() => {
-					if (!this.factories.has(id)) throw new Error(`client-modules: bundle ${url} loaded without registering "${id}" via __ModuleLoader__.load`);
-					if (reload !== void 0 && this.reloadTargets.get(id) === reload) this.reloadTargets.delete(id);
-				});
+				return transport;
+			}
+			/**
+			* Load one graph row so its factory is registered (idempotent per in-flight
+			* arrival). A batch script is one classic script that registers every
+			* package in sequence, and {@link register} rejects a second registration,
+			* so the two failure kinds differ: a transport failure (`error` event, nothing
+			* executed) is retried once on the same URL; a script that loaded without
+			* registering this row (a parse error registered nothing, or a runtime throw
+			* stopped it after registering others) is never re-executed, because a replay
+			* would stop again at the first duplicate registration; that holds even when
+			* the row that first imports from the batch is one it did register, because
+			* every executed batch URL is remembered. Either way the row then falls back
+			* to its own one-resource URL, which the Host serves for every package, so one
+			* failed batch costs at most three requests per missing row and never fails
+			* the rows that were registered.
+			*/
+			async arrive(row) {
+				const { id } = row;
+				if (this.loadCache.has(id) || this.factories.has(id)) return;
+				const reload = this.reloadTargets.get(id);
+				const preferred = reload?.url ?? row.initialUrl;
+				const fallback = reload === void 0 && row.url !== preferred ? row.url : void 0;
+				const failures = [];
+				const attempt = async (url) => {
+					try {
+						await this.loadShared(url);
+					} catch (error) {
+						failures.push(`${url}: ${describeError(error)}`);
+						return "transport-failed";
+					}
+					if (this.factories.has(id)) return "registered";
+					failures.push(`${url}: loaded without registering "${id}" via __ModuleLoader__.load`);
+					return "not-registered";
+				};
+				let outcome = "transport-failed";
+				if (this.failedBundleUrls.has(preferred)) failures.push(`${preferred}: skipped after an earlier failure of this bundle`);
+				else if (fallback !== void 0 && this.executedBundleUrls.has(preferred)) {
+					failures.push(`${preferred}: already executed without registering "${id}"`);
+					outcome = "not-registered";
+					this.failedBundleUrls.add(preferred);
+				} else {
+					outcome = await attempt(preferred);
+					if (outcome === "transport-failed") outcome = await attempt(preferred);
+					if (outcome !== "registered" && fallback !== void 0) this.failedBundleUrls.add(preferred);
+				}
+				if (outcome !== "registered" && fallback !== void 0) outcome = await attempt(fallback);
+				if (outcome !== "registered") throw new Error(`client-modules: could not load "${id}": ${failures.join("; ")}`);
+				if (reload !== void 0 && this.reloadTargets.get(id) === reload) this.reloadTargets.delete(id);
 			}
 			/** Register each injected package and unresolved dynamic request before its consumer. */
 			async arriveGraphRow(row, open = [], visited = /* @__PURE__ */ new Set()) {
@@ -598,14 +651,22 @@ window.__ModuleLoader__.load({
 					const id = stripClientSuffix(request);
 					if (this.seed.has(request) || this.loadCache.has(id)) continue;
 					const dependency = this.graphRows.get(id);
-					if (dependency !== void 0) await this.arriveGraphRow(dependency, next, visited);
+					if (dependency !== void 0) await this.arriveDependency(row.id, dependency, next, visited);
 				}
 				for (const packageName of row.inject) {
 					const dependency = this.graphRows.get(packageName);
-					if (dependency !== void 0) await this.arriveGraphRow(dependency, [], visited);
+					if (dependency !== void 0) await this.arriveDependency(row.id, dependency, [], visited);
 				}
 				await this.arrive(row);
 			}
+			/** Arrive one dependency, naming the consumer it failed for so a cascade reads as a chain, not as 44 unrelated failures. */
+			async arriveDependency(consumerId, dependency, open, visited) {
+				try {
+					await this.arriveGraphRow(dependency, open, visited);
+				} catch (error) {
+					throw new Error(`client-modules: "${consumerId}" not loaded because dependency "${dependency.id}" failed: ${describeError(error)}`, { cause: error });
+				}
+			}
 			/** Materialize a registered factory (synchronous; memoized in loadCache). */
 			materialize(id, ownerId = id) {
 				const existing = this.loadCache.get(id);
@@ -685,16 +746,40 @@ window.__ModuleLoader__.load({
 				const existing = this.loadCache.get(id);
 				if (existing !== void 0) return existing.exports;
 				const row = this.graphRows.get(id);
-				if (row !== void 0) await this.arriveGraphRow(row);
-				else if (!this.factories.has(id)) throw new Error(`client-modules: cannot resolve "${specifier}" — not a seed word, not a materialized module, and not a row in the boot graph (the runtime mirror of the bundle purity gate)`);
-				return this.materialize(id).exports;
+				if (row === void 0) {
+					if (this.factories.has(id)) return this.materialize(id).exports;
+					throw new Error(`client-modules: cannot resolve "${specifier}" — not a seed word, not a materialized module, and not a row in the boot graph (the runtime mirror of the bundle purity gate)`);
+				}
+				return this.recordingImportError(id, async () => {
+					await this.arriveGraphRow(row);
+					return this.materialize(id).exports;
+				});
 			}
 			async prefetch(id) {
 				const normalized = stripClientSuffix(id);
 				if (this.loadCache.has(normalized)) return;
 				const row = this.graphRows.get(normalized);
 				if (row === void 0) throw new Error(`client-modules: prefetch("${id}") — not a graph entry`);
-				await this.arriveGraphRow(row);
+				await this.recordingImportError(normalized, () => this.arriveGraphRow(row));
+			}
+			importError(id) {
+				return this.importErrors.get(stripClientSuffix(id));
+			}
+			/**
+			* Run one graph-row operation, recording its failure for the boot audit and
+			* clearing the record on success. Arrival and materialization both run in
+			* here, so a factory that throws is recorded as well as a bundle that never
+			* arrived; the Loader only sees a missing fiber either way.
+			*/
+			async recordingImportError(id, operation) {
+				try {
+					const result = await operation();
+					this.importErrors.delete(id);
+					return result;
+				} catch (error) {
+					this.importErrors.set(id, error instanceof Error ? error : new Error(describeError(error)));
+					throw error;
+				}
 			}
 			/** Refresh descriptors and unowned factory revisions before any entry imports its dependencies. */
 			updateManifest(manifest, managed) {
@@ -739,6 +824,7 @@ window.__ModuleLoader__.load({
 			invalidate(id, rev) {
 				const normalized = stripClientSuffix(id);
 				if (this.bootstrapIds.has(normalized)) return;
+				this.importErrors.delete(normalized);
 				this.generations.set(normalized, (this.generations.get(normalized) ?? 0) + 1);
 				const row = this.graphRows.get(normalized);
 				if (row !== void 0) {

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

@@ -92,7 +92,7 @@ export interface WebBootGraph {
 export interface BootModuleRow {
     /** Entry name == package name (module-table key). */
     id: string;
-    /** Revisioned single-resource combo reference used after HMR invalidation. */
+    /** Revisioned single-resource combo reference: the fallback when the row's batch fails and the reload target after HMR invalidation. */
     url: string;
     /** Content-addressed combo reference used before the first HMR invalidation. */
     initialUrl: string;
@@ -266,6 +266,15 @@ export interface ClientModuleLoader {
      * @param id - graph entry name.
      */
     prefetch(id: string): Promise<void>;
+    /**
+     * The last failure of {@link import} or {@link prefetch} for one graph row:
+     * transport, registration, dependency cascade, or factory execution. Cleared
+     * by a later success and by {@link invalidate}. The boot audit reads it to
+     * report why a Loader entry has no fiber.
+     * @param id - graph entry name.
+     * @returns the recorded failure, or `undefined` when the row never failed or succeeded since.
+     */
+    importError(id: string): Error | undefined;
     /**
      * 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

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

@@ -25,6 +25,12 @@ export declare class ClientModuleSystem implements ClientModuleLoader {
     private readonly materializing;
     private readonly graphRows;
     private readonly loadBundle;
+    /** Last import or prefetch failure per graph row, cleared by a later success or invalidation. */
+    private readonly importErrors;
+    /** Batch URLs whose transport or execution already failed; rows still missing from them go straight to their one-resource URL. */
+    private readonly failedBundleUrls;
+    /** Every URL whose script has executed once; a batch among them is never requested again. */
+    private readonly executedBundleUrls;
     /**
      * Build the module system over the parsed boot rows.
      * @param options - Parsed graph, platform seed, bootstrap module, registration facade, and transport.
@@ -32,10 +38,28 @@ export declare class ClientModuleSystem implements ClientModuleLoader {
     constructor(options: ClientModuleSystemOptions);
     /** Register one bundle factory, rejecting a script that executes twice without invalidation. */
     private register;
-    /** Load one graph row so its factory is registered (idempotent per in-flight arrival). */
+    /** Run one bundle transport per URL; every row waiting on the same URL shares the in-flight request. */
+    private loadShared;
+    /**
+     * Load one graph row so its factory is registered (idempotent per in-flight
+     * arrival). A batch script is one classic script that registers every
+     * package in sequence, and {@link register} rejects a second registration,
+     * so the two failure kinds differ: a transport failure (`error` event, nothing
+     * executed) is retried once on the same URL; a script that loaded without
+     * registering this row (a parse error registered nothing, or a runtime throw
+     * stopped it after registering others) is never re-executed, because a replay
+     * would stop again at the first duplicate registration; that holds even when
+     * the row that first imports from the batch is one it did register, because
+     * every executed batch URL is remembered. Either way the row then falls back
+     * to its own one-resource URL, which the Host serves for every package, so one
+     * failed batch costs at most three requests per missing row and never fails
+     * the rows that were registered.
+     */
     private arrive;
     /** Register each injected package and unresolved dynamic request before its consumer. */
     private arriveGraphRow;
+    /** Arrive one dependency, naming the consumer it failed for so a cascade reads as a chain, not as 44 unrelated failures. */
+    private arriveDependency;
     /** Materialize a registered factory (synchronous; memoized in loadCache). */
     private materialize;
     /** Build the synchronous module-table require and its asynchronous chunk operation. */
@@ -44,6 +68,14 @@ export declare class ClientModuleSystem implements ClientModuleLoader {
     private importChunk;
     import(specifier: string): Promise<unknown>;
     prefetch(id: string): Promise<void>;
+    importError(id: string): Error | undefined;
+    /**
+     * Run one graph-row operation, recording its failure for the boot audit and
+     * clearing the record on success. Arrival and materialization both run in
+     * here, so a factory that throws is recorded as well as a bundle that never
+     * arrived; the Loader only sees a missing fiber either way.
+     */
+    private recordingImportError;
     /** 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. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-modules",
   "description": "Client module system, dual-face: node half composes the __DSH_BOOT__ entry graph (incremental dsh.client scan, bundle route, index tap, webPlugins service); browser half is the lazy-CJS module table the vendored cordis Loader consumes as its internal seam",
-  "version": "0.1.7-alpha.1",
+  "version": "0.1.7-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -38,12 +38,12 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@deepseek-ai/cordis-plugin-loader": "^1.0.4",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.7-alpha.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.7-alpha.1",
-    "@deepseek-ai/cordis": "^4.0.3",
-    "@deepseek-ai/dsh-package-manifest": "^0.1.7-alpha.1",
-    "@deepseek-ai/dsh-client-store": "^0.1.7-alpha.1"
+    "@deepseek-ai/cordis-plugin-loader": "~1.0.5",
+    "@deepseek-ai/dsh-host-webserver": "0.1.7-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.4",
+    "@deepseek-ai/dsh-package-manifest": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-client-store": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-invariants": "0.1.7-alpha.2"
   },
   "files": [
     "lib/index.js",
@@ -52,7 +52,7 @@
     "lib/types/**/*.d.ts"
   ],
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.3"
+    "@deepseek-ai/cordis": "~4.0.4"
   },
   "scripts": {
     "bundle": "tsdown",