@deepseek-ai/dsh-client-modules 0.0.1-rc.1 → 0.0.1-rc.3

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: a1d578850c2518a85dc32f048768b78caf5ffec4
-README.zh.md: 772a4870f7ef6730d9d3d4db434ed771d97984f0
+README.md: efaff699839b977cc45f89f3c164402241b90dc2
+README.zh.md: 6ab3c8494d7ea902e8b891008f236aec41301a35

package/README.md

@@ -4,7 +4,7 @@ English | [中文](README.zh.md)
 
 Client module system: the browser peer of Node's internal ESM loader, built as a lazy CJS table. The web shell mounts the vendored cordis Loader for entry governance (fiber lifecycle, inject waiting, update/refresh) and injects this package's `ClientModuleLoader` through its `internal` contract — the vendored side's only consumption point is `EntryTree.import`, so replacing `internal` replaces exactly "how plugin code arrives" and nothing else.
 
-Lazy CJS model (web2): executing a plugin bundle only REGISTERS its factory (`window.__ModuleLoader__.load({id, factory})`); every module body side effect — CSS injection included — lives in the factory closure and runs at materialization (`factory(require)` → export surface, memoized in `loadCache`), not at script execution. A factory that requires another registered-but-unmaterialized module materializes it recursively, so load order needs no external sequencing; require cycles throw (factory-form CJS cannot deliver partial exports). `<id>/client` and the bare id name the same surface (a plugin bundle IS its package's client half).
+Lazy CJS model (web2): executing a plugin bundle only REGISTERS its factory (`window.__ModuleLoader__.load({id, factory})`); every module body side effect — CSS injection included — lives in the factory closure and runs at materialization (`factory(require)` → exports, memoized in `loadCache`), not at script execution. A factory that requires another registered-but-unmaterialized module materializes it recursively, so load order needs no external sequencing; require cycles throw (factory-form CJS cannot deliver partial exports). `<id>/client` and the bare id resolve to the same exports (a plugin bundle IS its package's client half).
 
 Resolution branch order (`import(specifier)`): platform seed word → shell instance; memoized record → surface; shell-own static registry (`registerStatic`, app-shell) → module; registered factory → materialize; graph row (`window.__DSH_BOOT__`) → load its external classic script + materialize; anything else throws — the runtime mirror of the build-time bundle purity gate. The synchronous `require` handed to factories walks the same order minus the asynchronous load branch and records observed edges into the module record. `prefetch` is the stage-one arrival hook (script load and factory registration only; concurrent calls share one in-flight task); `invalidate` drops the factory and materialized record so the next prefetch/import reloads the script (the HMR hook).
 

package/README.zh.md

@@ -2,13 +2,13 @@
 
 [English](README.md) | 中文
 
-客户端模块系统：Node 内部 ESM loader 的浏览器端对等实现，以惰性 CJS 表实现。web 外壳挂载 vendored cordis Loader 来治理配置项（fiber 生命周期、inject 等待、update/refresh），并通过其 `internal` 约定注入该包（package）的 `ClientModuleLoader`；vendored 一侧唯一的消费点是 `EntryTree.import`，因此替换 `internal` 恰好只会替换「插件代码如何到达」，不会改变其他内容。
+客户端模块系统：Node 内部 ESM loader 的浏览器端对等实现，以惰性 CJS 表实现。web 外壳挂载 vendored cordis Loader 来治理配置项（fiber 生命周期、inject 等待、update/refresh），并通过其 `internal` 约定注入该包的 `ClientModuleLoader`；vendored 一侧唯一的消费点是 `EntryTree.import`，因此替换 `internal` 恰好只会替换「插件代码如何到达」，不会改变其他内容。
 
-惰性 CJS 模型（web2）：执行插件组合包只会注册其 factory（`window.__ModuleLoader__.load({id, factory})`）；每个模块主体的副作用（包括 CSS 注入）都位于 factory 闭包中，在物化时运行（`factory(require)` → 导出表层，并在 `loadCache` 中记忆化），不会在脚本执行时运行。如果 factory 依赖另一个已注册但尚未物化的模块，系统会递归物化它，因此加载顺序无需外部编排；require 循环会抛出异常（factory 形式的 CJS 无法提供部分导出）。`<id>/client` 与裸 id 指向同一表层（一个插件组合包就是其包的客户端侧）。
+惰性 CJS 模型（web2）：执行插件 bundle 只会注册其 factory（`window.__ModuleLoader__.load({id, factory})`）；每个模块主体的副作用（包括 CSS 注入）都位于 factory 闭包中，在物化时运行（`factory(require)` → 导出表层，并在 `loadCache` 中记忆化），不会在脚本执行时运行。如果 factory 依赖另一个已注册但尚未物化的模块，系统会递归物化它，因此加载顺序无需外部编排；require 循环会抛出异常（factory 形式的 CJS 无法提供部分导出）。`<id>/client` 与裸 id 指向同一表层（一个插件 bundle 就是其包的客户端侧）。
 
-解析分支顺序（`import(specifier)`）：平台种子词 → 外壳实例；记忆化记录 → 表层；外壳自身的静态注册表（`registerStatic`，app-shell）→ 模块；已注册 factory → 物化；模块图记录（`window.__DSH_BOOT__`）→ 加载外部 classic script + 物化；其他情况一律抛出异常。这是构建时组合包纯度门禁的运行时镜像。交给 factory 的同步 `require` 采用相同顺序，但不含异步加载分支，并把观察到的边记录到模块记录中。`prefetch` 是第一阶段到达钩子（只加载脚本并注册 factory；并发调用共享一个进行中的任务）；`invalidate` 会丢弃 factory 与物化记录，使下一次 prefetch/import 重新加载脚本；它是 HMR（热模块替换）钩子。
+解析分支顺序（`import(specifier)`）：平台种子词 → 外壳实例；记忆化记录 → 表层；外壳自身的静态注册表（`registerStatic`，app-shell）→ 模块；已注册 factory → 物化；模块图记录（`window.__DSH_BOOT__`）→ 加载外部 classic script + 物化；其他情况一律抛出异常。这是构建时 bundle 纯度门禁的运行时镜像。交给 factory 的同步 `require` 采用相同顺序，但不含异步加载分支，并把观察到的边记录到模块记录中。`prefetch` 是第一阶段到达钩子（只加载脚本并注册 factory；并发调用共享一个进行中的任务）；`invalidate` 会丢弃 factory 与物化记录，使下一次 prefetch/import 重新加载脚本；它是 HMR（热模块替换）钩子。
 
-Node 侧会扫描已启用的 Loader 配置项以发现 web `dsh.client` 包，解析每个 `exports["./client"]`，把构建后的组合包哈希写入启动图，并通过 `/plugins` 提供该文件及其 sourcemap。源码启动会把宿主侧导入映射到 TypeScript 源码，但仍消费这一构建后的客户端导出；缺失文件共享一条构建说明，随后以 package/path list 列出各项，而无关的文件系统错误仍是独立故障。
+Node 侧会扫描已启用的 Loader 配置项以发现 web `dsh.client` 包，解析每个 `exports["./client"]`，把构建后的 bundle 哈希写入启动图，并通过 `/plugins` 提供该文件及其 sourcemap。源码启动会把宿主侧导入映射到 TypeScript 源码，但仍消费这一构建后的客户端导出；缺失文件共享一条构建说明，随后以包／路径列表列出各项，而无关的文件系统错误仍是独立故障。
 
 ## 模型体验
 
@@ -20,5 +20,5 @@ Node 侧会扫描已启用的 Loader 配置项以发现 web `dsh.client` 包，
 
 ## 已知限制与暂缓事项
 
-- **有意采用扁平模块图**：每个组合包是一个模块节点，其边只指向表中的叶节点；接口（`loadCache`/`edges`/`invalidate`）已经支持通用模块图，因此可以改变 externalization 粒度而不更改接口。
-- **自身不记录卸载账目**：样式移除与 fiber 拆卸顺序属于 HMR 驱动器（`@deepseek-ai/dsh-client-hmr`）；loader 只在每条记录中登记其拥有的样式标签 id。
+- **有意采用扁平模块图**：每个 bundle 是一个模块节点，其边只指向表中的叶节点；接口（`loadCache`/`edges`/`invalidate`）已经支持通用模块图，因此可以改变 externalization 粒度而不更改接口。
+- **自身不维护卸载记录**：样式移除与 fiber 拆卸顺序属于 HMR 驱动器（`@deepseek-ai/dsh-client-hmr`）；loader 只在每条记录中登记其拥有的样式标签 id。

package/lib/client.js

@@ -23,7 +23,7 @@ window.__ModuleLoader__.load({
 		/**
 		* A plugin bundle IS its package's client half: `<id>/client` (the exports
 		* subpath external bundles emit) and the bare graph id name the same
-		* surface, so table lookups normalize the suffix away.
+		* exports, so table lookups normalize the suffix away.
 		*/
 		const stripClientSuffix = (spec) => spec.endsWith("/client") ? spec.slice(0, -7) : spec;
 		/**
@@ -101,7 +101,7 @@ window.__ModuleLoader__.load({
 					const edges = /* @__PURE__ */ new Set();
 					const record = {
 						id,
-						surface: registered(this.makeRequire(edges)),
+						exports: registered(this.makeRequire(edges)),
 						styles: claimStyles(id),
 						edges
 					};
@@ -125,31 +125,31 @@ window.__ModuleLoader__.load({
 					if (this.statics.has(spec)) return this.statics.get(spec);
 					const id = stripClientSuffix(spec);
 					const record = this.loadCache.get(id);
-					if (record !== void 0) return record.surface;
-					if (this.factories.has(id)) return this.materialize(id).surface;
+					if (record !== void 0) return record.exports;
+					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 shell-own module, and no registered factory (a build-time externals drift, or a forbidden cross-plugin value import)`);
 				};
 			}
 			async import(specifier) {
 				if (this.seed.has(specifier)) return this.seed.get(specifier);
 				const existing = this.loadCache.get(specifier);
-				if (existing !== void 0) return existing.surface;
+				if (existing !== void 0) return existing.exports;
 				if (this.statics.has(specifier)) {
-					const surface = this.statics.get(specifier);
+					const exports = this.statics.get(specifier);
 					this.loadCache.set(specifier, {
 						id: specifier,
-						surface,
+						exports,
 						styles: [],
 						edges: /* @__PURE__ */ new Set()
 					});
-					return surface;
+					return exports;
 				}
 				if (!this.factories.has(specifier)) {
 					const row = this.graphRows.get(specifier);
 					if (row === void 0) throw new Error(`client-modules: cannot resolve "${specifier}" — not a seed word, not a shell-own module, and not a row in the boot graph (the runtime mirror of the bundle purity gate)`);
 					await this.arrive(row);
 				}
-				return this.materialize(specifier).surface;
+				return this.materialize(specifier).exports;
 			}
 			registerStatic(id, module) {
 				if (this.statics.has(id)) throw new Error(`client-modules: shell-own module "${id}" registered twice`);
@@ -180,13 +180,13 @@ window.__ModuleLoader__.load({
 		* factory (`window.__ModuleLoader__.load({id, factory})`); every module body
 		* side effect — including CSS injection — lives inside the factory closure
 		* and runs at materialization, not at script execution. Materialization
-		* (factory(require) → export surface) happens on first import/require and is
+		* (factory(require) → exports) happens on first import/require and is
 		* memoized in {@link ClientModuleLoader.loadCache}; a factory that requires
 		* another registered-but-unmaterialized module materializes it recursively,
 		* so load order needs no external sequencing.
 		*
 		* Resolution branch order (import): seed word → shell instance; memoized
-		* record → surface; static registry (shell-own modules, e.g. app-shell) →
+		* record → exports; static registry (shell-own modules, e.g. app-shell) →
 		* module; registered factory → materialize; graph row → load + materialize;
 		* anything else → throw (loud — the runtime mirror of the
 		* build-time bundle purity gate). The synchronous `require` handed to

package/lib/index.js

@@ -23,7 +23,7 @@ import { Service } from "@deepseek-ai/cordis";
 * negative "not a client package" verdict) is cached per name and never
 * expires — plugin-set changes take effect on restart; bundle content
 * changes reach the graph only through
-* {@link ClientModuleHostService.rebuilt}.
+* {@link ClientModuleRegistry.rebuilt}.
 * @module @deepseek-ai/dsh-client-modules
 */
 /** Recovery instruction shared by grouped startup and steady-state bundle diagnostics. */
@@ -118,8 +118,8 @@ function injectBootManifest(html, graph) {
 * already-loaded entries aggregates into one loud throw (FAILED fiber; the
 * boot activation audit reports it).
 */
-var ClientModuleHostService = class extends Service {
-	static inject = ["httpServer", "loader"];
+var ClientModuleRegistry = class extends Service {
+	static inject = ["webServer", "loader"];
 	table = /* @__PURE__ */ new Map();
 	pkgMeta = /* @__PURE__ */ new Map();
 	rebuildListeners = /* @__PURE__ */ new Set();
@@ -130,10 +130,10 @@ var ClientModuleHostService = class extends Service {
 	composed;
 	/**
 	* Build the service: subscribe, seed, and run the activation flush.
-	* @param ctx - plugin context carrying httpServer and loader.
+	* @param ctx - plugin context carrying webServer and loader.
 	*/
 	constructor(ctx) {
-		super(ctx, "clientModuleHost");
+		super(ctx, "clientModules");
 		if (ctx.baseUrl === void 0) throw new Error("client-modules: ctx.baseUrl is unset — the node half needs the config-tree anchor to resolve plugin packages");
 		const require = createRequire(ctx.baseUrl);
 		this.resolvePkgJson = (spec) => require.resolve(`${spec}/package.json`);
@@ -155,12 +155,12 @@ var ClientModuleHostService = class extends Service {
 		const failures = [];
 		this.flush((err) => failures.push(err));
 		if (failures.length > 0) throw new ClientPackageCompositionError(failures);
-		ctx.effect(() => ctx.httpServer.register({
+		ctx.effect(() => ctx.webServer.register({
 			kind: "prefix",
 			path: "/plugins",
 			handler: this.serveBundle
 		}), "client-modules: bundle route");
-		ctx.effect(() => ctx.httpServer.tapIndex((html) => injectBootManifest(html, this.composed)), "client-modules: boot manifest injection");
+		ctx.effect(() => ctx.webServer.tapIndex((html) => injectBootManifest(html, this.composed)), "client-modules: boot manifest injection");
 	}
 	/**
 	* Current composed entry graph (stable object between changes).
@@ -344,4 +344,4 @@ var ClientModuleHostService = class extends Service {
 	};
 };
 //#endregion
-export { ClientModuleHostService, ClientModuleHostService as default, injectBootManifest };
+export { ClientModuleRegistry, ClientModuleRegistry as default, injectBootManifest };

package/lib/invariant.js

@@ -19,7 +19,7 @@ const inject = ["invariants"];
 */
 const install = (ctx, fail) => {
 	ctx.on("internal/plugin", () => {
-		const host = ctx.get("clientModuleHost");
+		const host = ctx.get("clientModules");
 		if (host === void 0) return;
 		for (const row of host.graph().entries) if (host.clientPath(row.id) === void 0) fail(`web plugin graph row "${row.id}" advertises ${row.url} but resolves no client bundle path — the served __DSH_BOOT__ would 404 on fetch`);
 	}, { global: true });

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

@@ -10,13 +10,13 @@
  * factory (`window.__ModuleLoader__.load({id, factory})`); every module body
  * side effect — including CSS injection — lives inside the factory closure
  * and runs at materialization, not at script execution. Materialization
- * (factory(require) → export surface) happens on first import/require and is
+ * (factory(require) → exports) happens on first import/require and is
  * memoized in {@link ClientModuleLoader.loadCache}; a factory that requires
  * another registered-but-unmaterialized module materializes it recursively,
  * so load order needs no external sequencing.
  *
  * Resolution branch order (import): seed word → shell instance; memoized
- * record → surface; static registry (shell-own modules, e.g. app-shell) →
+ * record → exports; static registry (shell-own modules, e.g. app-shell) →
  * module; registered factory → materialize; graph row → load + materialize;
  * anything else → throw (loud — the runtime mirror of the
  * build-time bundle purity gate). The synchronous `require` handed to
@@ -103,12 +103,12 @@ export interface ClientPluginHandoff {
     id: string;
     /**
      * Closure factory holding the whole bundle body: receives the synchronous
-     * require bound to the module table and returns the bundle's export
-     * surface. Runs once, at materialization.
+     * require bound to the module table and returns the bundle's exports. Runs
+     * once, at materialization.
      */
     factory: (require: (spec: string) => unknown) => Record<string, unknown>;
 }
-/** Window surface of the web boot protocol: the host-injected graph, the registration sink, and the kernel handoff slot. */
+/** Window API of the web boot protocol: the host-injected graph, registration sink, and kernel handoff slot. */
 export interface DshWindow {
     /** Host-composed entry graph, injected before the shell bundle runs; wire-boundary raw until {@link parseBootManifest}. */
     __DSH_BOOT__?: unknown;
@@ -128,8 +128,8 @@ export interface DshWindow {
 export interface ClientModuleRecord {
     /** Module id (entry name / package name). */
     id: string;
-    /** The materialized export surface (factory `module.exports`, or the shell module for static registrations). */
-    surface: unknown;
+    /** Materialized exports (`module.exports` from a factory, or a statically registered shell module). */
+    exports: unknown;
     /** Owned `<style data-plugin>` tag ids (`data-plugin-css` values) injected during materialization. */
     styles: string[];
     /** Observed `require()` edges (module-graph boundary; only table words can appear today). */
@@ -143,7 +143,7 @@ export interface ClientModuleRecord {
 export interface ClientModuleLoader {
     /** Discriminant against Node's internal loader shapes ('v1'/'v2'). */
     version: 'client';
-    /** Materialized-module registry: id → record. The governance-side read face for entry export surfaces. */
+    /** Materialized-module registry: id → record. The governance-side read API for entry exports. */
     loadCache: Map<string, ClientModuleRecord>;
     /**
      * Internal contract consumed by the vendored Loader's `tree.import`. Resolves
@@ -152,7 +152,7 @@ export interface ClientModuleLoader {
      * @param specifier - module specifier (entry name or table word).
      * @param parentURL - importer URL (unused — the client module graph is flat).
      * @param attrs - Import attributes (unused; interface parity with Node's loader contract).
-     * @returns the module's export surface.
+     * @returns the module's exports.
      */
     import(specifier: string, parentURL: string, attrs: Record<string, unknown>): Promise<unknown>;
     /**

package/lib/types/index.d.ts

@@ -16,7 +16,7 @@
  * negative "not a client package" verdict) is cached per name and never
  * expires — plugin-set changes take effect on restart; bundle content
  * changes reach the graph only through
- * {@link ClientModuleHostService.rebuilt}.
+ * {@link ClientModuleRegistry.rebuilt}.
  * @module @deepseek-ai/dsh-client-modules
  */
 import { Service } from '@deepseek-ai/cordis';
@@ -26,7 +26,7 @@ export type { BootManifest, BootModuleRow, BootPluginRow, WebBootEntry, WebBootG
 declare module '@deepseek-ai/cordis' {
     interface Context {
         /** The web plugin table (provided by the client-modules node half). */
-        clientModuleHost: ClientModuleHostService;
+        clientModules: ClientModuleRegistry;
     }
 }
 /**
@@ -45,7 +45,7 @@ export declare function injectBootManifest(html: string, graph: WebBootGraph): s
  * already-loaded entries aggregates into one loud throw (FAILED fiber; the
  * boot activation audit reports it).
  */
-export declare class ClientModuleHostService extends Service {
+export declare class ClientModuleRegistry extends Service {
     static inject: string[];
     private readonly table;
     private readonly pkgMeta;
@@ -57,7 +57,7 @@ export declare class ClientModuleHostService extends Service {
     private composed;
     /**
      * Build the service: subscribe, seed, and run the activation flush.
-     * @param ctx - plugin context carrying httpServer and loader.
+     * @param ctx - plugin context carrying webServer and loader.
      */
     constructor(ctx: Context);
     /**
@@ -107,5 +107,5 @@ export declare class ClientModuleHostService extends Service {
     private flush;
     private readonly serveBundle;
 }
-export default ClientModuleHostService;
+export default ClientModuleRegistry;
 //# sourceMappingURL=index.d.ts.map

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.0.1-rc.1",
+  "version": "0.0.1-rc.3",
   "publishConfig": {
     "access": "restricted"
   },
@@ -39,9 +39,9 @@
   "license": "BSD-3-Clause",
   "devDependencies": {
     "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
-    "@deepseek-ai/cordis": "^4.0.1-rc.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.0.1-rc.1"
+    "@deepseek-ai/dsh-host-webserver": "^0.0.1-rc.3",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.3",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
   },
   "files": [
     "lib/index.js",
@@ -50,8 +50,8 @@
     "lib/types/**/*.d.ts"
   ],
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
-    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.3"
   },
   "scripts": {
     "bundle": "tsdown",