@crazx/dsh-client-modules 0.1.0-rc.7.zw.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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: efaff699839b977cc45f89f3c164402241b90dc2
+README.zh.md: 6ab3c8494d7ea902e8b891008f236aec41301a35

package/README.md

@@ -0,0 +1,24 @@
+# @deepseek-ai/dsh-client-modules
+
+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)` → 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).
+
+The Node half scans enabled Loader entries for web `dsh.client` packages, resolves each `exports["./client"]`, hashes the built bundle into the boot graph, and serves it with its source map under `/plugins`. Source launch maps host imports to TypeScript source but still consumes this built client export; missing files share one build instruction followed by a package/path list, while unrelated filesystem errors remain separate failures.
+
+## Model Experience
+
+None, as the module loader is browser-side kernel machinery; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Flat module graph by design** — every bundle is one module node whose edges point only at table leaves; the interface (`loadCache`/`edges`/`invalidate`) already supports a general module graph, so the externalization granularity can change without an interface change.
+- **No unload bookkeeping of its own** — style removal and fiber teardown ordering live with the HMR driver (`@deepseek-ai/dsh-client-hmr`); the loader only inventories owned style tag ids per record.

package/README.zh.md

@@ -0,0 +1,24 @@
+# @deepseek-ai/dsh-client-modules
+
+[English](README.md) | 中文
+
+客户端模块系统：Node 内部 ESM loader 的浏览器端对等实现，以惰性 CJS 表实现。web 外壳挂载 vendored cordis Loader 来治理配置项（fiber 生命周期、inject 等待、update/refresh），并通过其 `internal` 约定注入该包的 `ClientModuleLoader`；vendored 一侧唯一的消费点是 `EntryTree.import`，因此替换 `internal` 恰好只会替换「插件代码如何到达」，不会改变其他内容。
+
+惰性 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 + 物化；其他情况一律抛出异常。这是构建时 bundle 纯度门禁的运行时镜像。交给 factory 的同步 `require` 采用相同顺序，但不含异步加载分支，并把观察到的边记录到模块记录中。`prefetch` 是第一阶段到达钩子（只加载脚本并注册 factory；并发调用共享一个进行中的任务）；`invalidate` 会丢弃 factory 与物化记录，使下一次 prefetch/import 重新加载脚本；它是 HMR（热模块替换）钩子。
+
+Node 侧会扫描已启用的 Loader 配置项以发现 web `dsh.client` 包，解析每个 `exports["./client"]`，把构建后的 bundle 哈希写入启动图，并通过 `/plugins` 提供该文件及其 sourcemap。源码启动会把宿主侧导入映射到 TypeScript 源码，但仍消费这一构建后的客户端导出；缺失文件共享一条构建说明，随后以包／路径列表列出各项，而无关的文件系统错误仍是独立故障。
+
+## 模型体验
+
+无。模块 loader 属于浏览器侧内核机制；这里没有任何内容进入模型请求。
+
+#### KV Cache 影响
+
+无；该包既不组装也不发送提供方请求。
+
+## 已知限制与暂缓事项
+
+- **有意采用扁平模块图**：每个 bundle 是一个模块节点，其边只指向表中的叶节点；接口（`loadCache`/`edges`/`invalidate`）已经支持通用模块图，因此可以改变 externalization 粒度而不更改接口。
+- **自身不维护卸载记录**：样式移除与 fiber 拆卸顺序属于 HMR 驱动器（`@deepseek-ai/dsh-client-hmr`）；loader 只在每条记录中登记其拥有的样式标签 id。

package/lib/client.js

@@ -0,0 +1,259 @@
+window.__ModuleLoader__.load({
+	id: "@deepseek-ai/dsh-client-modules",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		//#region lib/types/client/system.js
+		/** Default bundle-load hook: same-origin external classic script. */
+		const defaultLoadBundle = (url) => new Promise((resolve, reject) => {
+			const el = document.createElement("script");
+			el.async = true;
+			el.src = url;
+			el.addEventListener("load", () => {
+				el.remove();
+				resolve();
+			}, { once: true });
+			el.addEventListener("error", () => {
+				el.remove();
+				reject(/* @__PURE__ */ new Error(`client-modules: bundle script ${url} failed to load`));
+			}, { once: true });
+			document.head.append(el);
+		});
+		/**
+		* 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
+		* exports, so table lookups normalize the suffix away.
+		*/
+		const stripClientSuffix = (spec) => spec.endsWith("/client") ? spec.slice(0, -7) : spec;
+		/**
+		* Claim and inventory the <style> tags a factory injected during
+		* materialization: preset-emitted tags arrive pre-tagged with data-plugin;
+		* any untagged tag is claimed for the materializing plugin (HMR bookkeeping).
+		*/
+		const claimStyles = (id) => {
+			if (typeof document === "undefined") return [];
+			for (const el of document.querySelectorAll("style:not([data-plugin])")) el.setAttribute("data-plugin", id);
+			const owned = [];
+			for (const el of document.querySelectorAll(`style[data-plugin=${JSON.stringify(id)}]`)) owned.push(el.getAttribute("data-plugin-css") ?? id);
+			return owned;
+		};
+		/**
+		* The client module system: state tables plus the arrival/materialization
+		* machinery implementing {@link ClientModuleLoader} (whose members carry the
+		* contract documentation). Construction indexes the boot rows and installs the
+		* `window.__ModuleLoader__` registration sink — once per page.
+		*/
+		var ClientModuleSystem = class {
+			version = "client";
+			loadCache = /* @__PURE__ */ new Map();
+			seed;
+			statics = /* @__PURE__ */ new Map();
+			factories = /* @__PURE__ */ new Map();
+			/** In-flight prefetch (script load) per id; concurrent callers share it. */
+			pendingArrival = /* @__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();
+			loadBundle;
+			/**
+			* Build the module system over the parsed boot rows.
+			* @param options - Module rows, module-table staticModules, and bundle-load hook.
+			*/
+			constructor(options) {
+				this.seed = new Map(Object.entries(options.staticModules));
+				this.loadBundle = options.loadBundle ?? defaultLoadBundle;
+				for (const row of options.modules) {
+					if (this.graphRows.has(row.id)) throw new Error(`client-modules: duplicate graph entry "${row.id}"`);
+					this.graphRows.set(row.id, row);
+				}
+				const win = globalThis;
+				if (win.__ModuleLoader__ !== void 0) throw new Error("client-modules: window.__ModuleLoader__ already installed (double boot?)");
+				win.__ModuleLoader__ = { load: (handoff) => {
+					if (this.factories.has(handoff.id)) throw new Error(`client-modules: duplicate factory registration for "${handoff.id}" (bundle executed twice without invalidate?)`);
+					this.factories.set(handoff.id, handoff.factory);
+				} };
+			}
+			/** Load one graph row so its factory is registered (idempotent per in-flight arrival). */
+			arrive(row) {
+				const { id, url } = row;
+				const pending = this.pendingArrival.get(id);
+				if (pending !== void 0) return pending;
+				if (this.factories.has(id)) return Promise.resolve();
+				const task = this.loadBundle(url).then(() => {
+					if (!this.factories.has(id)) throw new Error(`client-modules: bundle ${url} loaded without registering "${id}" via __ModuleLoader__.load`);
+				}).finally(() => {
+					this.pendingArrival.delete(id);
+				});
+				this.pendingArrival.set(id, task);
+				return task;
+			}
+			/** Materialize a registered factory (synchronous; memoized in loadCache). */
+			materialize(id) {
+				const existing = this.loadCache.get(id);
+				if (existing !== void 0) return existing;
+				const registered = this.factories.get(id);
+				/* v8 ignore next -- callers check the factory branch before dispatching here. */
+				if (registered === void 0) throw new Error(`client-modules: no registered factory for "${id}"`);
+				if (this.materializing.has(id)) throw new Error(`client-modules: require cycle through "${id}" (factory-form CJS cannot deliver partial exports)`);
+				this.materializing.add(id);
+				try {
+					const edges = /* @__PURE__ */ new Set();
+					const record = {
+						id,
+						exports: registered(this.makeRequire(edges)),
+						styles: claimStyles(id),
+						edges
+					};
+					this.loadCache.set(id, record);
+					return record;
+				} finally {
+					this.materializing.delete(id);
+				}
+			}
+			/**
+			* The synchronous require answered to factories: seed → static → memoized
+			* record → registered factory (recursive materialization — this is what
+			* makes load order self-resolving). Fetching is async and therefore
+			* unreachable from here; an unregistered plugin specifier is loud (and a
+			* cross-plugin value import is already a build error upstream).
+			*/
+			makeRequire(edges) {
+				return (spec) => {
+					edges.add(spec);
+					if (this.seed.has(spec)) return this.seed.get(spec);
+					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.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.exports;
+				if (this.statics.has(specifier)) {
+					const exports = this.statics.get(specifier);
+					this.loadCache.set(specifier, {
+						id: specifier,
+						exports,
+						styles: [],
+						edges: /* @__PURE__ */ new Set()
+					});
+					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).exports;
+			}
+			registerStatic(id, module) {
+				if (this.statics.has(id)) throw new Error(`client-modules: shell-own module "${id}" registered twice`);
+				this.statics.set(id, module);
+			}
+			async prefetch(id) {
+				if (this.statics.has(id)) return;
+				const row = this.graphRows.get(id);
+				if (row === void 0) throw new Error(`client-modules: prefetch("${id}") — not a graph entry`);
+				await this.arrive(row);
+			}
+			invalidate(id) {
+				this.factories.delete(id);
+				this.loadCache.delete(id);
+			}
+		};
+		//#endregion
+		//#region lib/types/client/manifest.js
+		/**
+		* Client module system: the browser peer of Node's internal ESM loader, built
+		* as a lazy CJS table. The vendored cordis Loader consumes this object
+		* through its `internal` contract (the only call site is `EntryTree.import` →
+		* `internal.import`), which keeps entry governance (fiber lifecycle, inject
+		* waiting, update/refresh) entirely on the vendored side while this package
+		* owns code arrival.
+		*
+		* Lazy CJS model: executing a plugin bundle only REGISTERS its
+		* 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) → 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 → 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
+		* factories walks the same order minus the load branch: loading is async,
+		* so only already-registered bundles can be required — and cross-plugin value
+		* imports are a build error anyway.
+		*
+		* This file is the browser-safe contract face (zero node imports): the
+		* `__DSH_BOOT__` wire types, the boot-manifest parser, and the boundaries around
+		* {@link ClientModuleSystem}. The package root is the host-side service that
+		* composes the wire.
+		*/
+		/**
+		* Parse `window.__DSH_BOOT__` into the two consumer views. Wire boundary:
+		* a missing or malformed graph throws (the shell shows the loud failure —
+		* a page without a valid manifest cannot boot anything).
+		* @param wire - the raw `window.__DSH_BOOT__` value.
+		* @returns the manifest with optional plugin-view fields normalized.
+		*/
+		function parseBootManifest(wire) {
+			if (typeof wire !== "object" || wire === null) throw new Error("client-modules: window.__DSH_BOOT__ is missing or not an object");
+			const graph = wire;
+			if (typeof graph.rev !== "string") throw new Error("client-modules: boot manifest rev must be a string");
+			if (!Array.isArray(graph.entries)) throw new Error("client-modules: boot manifest entries must be an array");
+			const modules = [];
+			const plugins = [];
+			for (const value of graph.entries) {
+				if (typeof value !== "object" || value === null) throw new Error("client-modules: boot manifest entry is not an object");
+				const row = value;
+				const where = typeof row.id === "string" ? `"${row.id}"` : JSON.stringify(row);
+				if (typeof row.id !== "string" || typeof row.url !== "string" || typeof row.rev !== "string") throw new Error(`client-modules: boot manifest entry ${where} must carry string id/url/rev`);
+				if (row.inject !== void 0 && (!Array.isArray(row.inject) || row.inject.some((i) => typeof i !== "string"))) throw new Error(`client-modules: boot manifest entry ${where} inject must be a string array`);
+				if (row.immediately !== void 0 && typeof row.immediately !== "boolean") throw new Error(`client-modules: boot manifest entry ${where} immediately must be a boolean`);
+				modules.push({
+					id: row.id,
+					url: row.url,
+					rev: row.rev
+				});
+				plugins.push({
+					id: row.id,
+					inject: row.inject === void 0 ? [] : [...row.inject],
+					immediately: row.immediately === true
+				});
+			}
+			return {
+				rev: graph.rev,
+				modules,
+				plugins
+			};
+		}
+		//#endregion
+		//#region lib/types/client/index.js
+		/**
+		* Enroll the kernel-built module system as `ctx.modules`.
+		* @param ctx - client root context.
+		*/
+		function apply(ctx) {
+			const modules = globalThis.__DSH_MODULES__;
+			if (modules === void 0) throw new Error("client-modules: window.__DSH_MODULES__ missing — the shell kernel must construct the module system before plugin boot");
+			ctx.reflect.provide("modules", modules);
+		}
+		//#endregion
+		exports.ClientModuleSystem = ClientModuleSystem;
+		exports.apply = apply;
+		exports.parseBootManifest = parseBootManifest;
+		return module.exports;
+	}
+});
+
+//# sourceMappingURL=client.js.map

package/lib/index.js

@@ -0,0 +1,348 @@
+import { createRequire } from "node:module";
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { Service } from "@deepseek-ai/cordis";
+//#region lib/types/index.js
+/**
+* Node half of the client module system (`dsh.client` dual-face package): scans
+* the host Loader's entries for packages declaring `dsh.client`, composes the
+* `window.__DSH_BOOT__` entry graph (wire single source: {@link WebBootEntry}
+* in `./client/manifest.ts`), serves `/plugins/<id>/client.js` and its source
+* map, taps the index render to inject the boot manifest, and provides the
+* `clientModuleHost` service (the HMR node half's registration/notification
+* face).
+*
+* Scanning is incremental per package — there is no full-rescan code path.
+* Every cordis `internal/plugin` emission (fiber construction/disposal) marks
+* the fiber's entry name dirty; a microtask flush reconciles each dirty name
+* against the live loader entries. The activation pass seeds the same dirty
+* set with all current entries and flushes synchronously, so first scan and
+* steady state share one implementation. Package metadata (including the
+* 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 ClientModuleRegistry.rebuilt}.
+* @module @deepseek-ai/dsh-client-modules
+*/
+/** Recovery instruction shared by grouped startup and steady-state bundle diagnostics. */
+const CLIENT_BUNDLE_BUILD_INSTRUCTION = "run `pnpm run build` before launch";
+/** Missing built client export, retained as structured data for activation-error grouping. */
+var MissingClientBundleError = class extends Error {
+	packageName;
+	clientPath;
+	constructor(packageName, clientPath, cause) {
+		super([
+			`client-modules: client bundle not found; ${CLIENT_BUNDLE_BUILD_INSTRUCTION}:`,
+			`  package: ${packageName}`,
+			`  path: ${clientPath}`
+		].join("\n"), { cause });
+		this.packageName = packageName;
+		this.clientPath = clientPath;
+	}
+};
+/** Activation failures grouped by actionable package-build errors and unrelated failures. */
+var ClientPackageCompositionError = class extends AggregateError {
+	constructor(failures) {
+		const missingBundles = failures.filter((error) => error instanceof MissingClientBundleError);
+		const otherFailures = failures.filter((error) => !(error instanceof MissingClientBundleError));
+		const packageNoun = failures.length === 1 ? "package" : "packages";
+		const lines = [`client-modules: ${String(failures.length)} client ${packageNoun} failed to compose:`];
+		if (missingBundles.length > 0) {
+			lines.push(`  client bundles not found; ${CLIENT_BUNDLE_BUILD_INSTRUCTION}:`);
+			for (const error of missingBundles) lines.push(`    - package: ${error.packageName}`, `      path: ${error.clientPath}`);
+		}
+		if (otherFailures.length > 0) lines.push("  other failures:", ...otherFailures.map((error) => `    - ${error.message}`));
+		super(failures, lines.join("\n"));
+	}
+};
+/** Narrow an unknown parsed JSON value to the `dsh.client` declaration, throwing on malformed fields. */
+function parseDshClient(pkgName, value) {
+	if (value === void 0) return void 0;
+	if (typeof value !== "object" || value === null) throw new Error(`client-modules: ${pkgName} has a non-object dsh.client declaration`);
+	const decl = value;
+	if (typeof decl.platform !== "string") throw new Error(`client-modules: ${pkgName} dsh.client.platform must be a string`);
+	if (decl.inject !== void 0 && (!Array.isArray(decl.inject) || decl.inject.some((i) => typeof i !== "string"))) throw new Error(`client-modules: ${pkgName} dsh.client.inject must be a string array`);
+	if (decl.immediately !== void 0 && typeof decl.immediately !== "boolean") throw new Error(`client-modules: ${pkgName} dsh.client.immediately must be a boolean`);
+	return {
+		platform: decl.platform,
+		...decl.inject !== void 0 ? { inject: decl.inject } : {},
+		...decl.immediately !== void 0 ? { immediately: decl.immediately } : {}
+	};
+}
+/** 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;
+	const client = exportsField["./client"];
+	if (client === void 0) return void 0;
+	if (typeof client === "string") return client;
+	if (typeof client === "object" && client !== null) {
+		const fallback = client.default;
+		if (typeof fallback === "string") return fallback;
+	}
+	throw new Error(`client-modules: ${pkgName} exports["./client"] must be a string or an object with a string default`);
+}
+/** sha1 content hash shortened to 12 hex chars (bundle rev / graph rev). */
+function shortHash(input) {
+	return createHash("sha1").update(input).digest("hex").slice(0, 12);
+}
+/** Graph row for one bundle rev (url carries the rev as its cache-busting query). */
+function graphRow(id, rev, injectEdges, immediately) {
+	return {
+		id,
+		url: `/plugins/${id}/client.js?rev=${rev}`,
+		rev,
+		...injectEdges !== void 0 ? { inject: injectEdges } : {},
+		...immediately ? { immediately: true } : {}
+	};
+}
+/**
+* Inject the boot entry graph into index.html: `window.__DSH_BOOT__` as the
+* first script in <head> (before the shell bundle reads it). `<` is escaped in
+* the JSON so plugin-controlled strings cannot break out of the script element.
+* @param html - the index.html source.
+* @param graph - the composed entry graph.
+* @returns the html with the graph script injected.
+*/
+function injectBootManifest(html, graph) {
+	const script = `<script>window.__DSH_BOOT__ = ${JSON.stringify(graph).replaceAll("<", "\\u003c")}<\/script>`;
+	const head = html.indexOf("<head>");
+	if (head !== -1) return `${html.slice(0, head + 6)}${script}${html.slice(head + 6)}`;
+	return `${script}${html}`;
+}
+/**
+* The web plugin table service: incremental `dsh.client` scan + wire composition
+* + bundle route + index tap. Construction runs the activation scan
+* synchronously — a malformed declaration or missing bundle among the
+* already-loaded entries aggregates into one loud throw (FAILED fiber; the
+* boot activation audit reports it).
+*/
+var ClientModuleRegistry = class extends Service {
+	static inject = ["webServer", "loader"];
+	table = /* @__PURE__ */ new Map();
+	pkgMeta = /* @__PURE__ */ new Map();
+	rebuildListeners = /* @__PURE__ */ new Set();
+	graphListeners = /* @__PURE__ */ new Set();
+	dirty = /* @__PURE__ */ new Set();
+	resolvePkgJson;
+	flushQueued = false;
+	composed;
+	/**
+	* Build the service: subscribe, seed, and run the activation flush.
+	* @param ctx - plugin context carrying webServer and loader.
+	*/
+	constructor(ctx) {
+		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`);
+		ctx.on("internal/plugin", (fiber) => {
+			const entryName = fiber.entry?.options.name;
+			if (entryName === void 0) return;
+			this.dirty.add(entryName);
+			if (this.flushQueued) return;
+			this.flushQueued = true;
+			queueMicrotask(() => {
+				this.flushQueued = false;
+				this.flush((err) => {
+					ctx.logger.warn(err);
+				});
+			});
+		});
+		for (const entry of ctx.loader.entries()) this.dirty.add(entry.options.name);
+		this.composed = this.compose();
+		const failures = [];
+		this.flush((err) => failures.push(err));
+		if (failures.length > 0) throw new ClientPackageCompositionError(failures);
+		ctx.effect(() => ctx.webServer.register({
+			kind: "prefix",
+			path: "/plugins",
+			handler: this.serveBundle
+		}), "client-modules: bundle route");
+		ctx.effect(() => ctx.webServer.tapIndex((html) => injectBootManifest(html, this.composed)), "client-modules: boot manifest injection");
+	}
+	/**
+	* Current composed entry graph (stable object between changes).
+	* @returns the graph served as `window.__DSH_BOOT__`.
+	*/
+	graph() {
+		return this.composed;
+	}
+	/**
+	* Absolute path of an entry's client bundle.
+	* @param id - entry id (package name).
+	* @returns the path, or undefined for an unknown id.
+	*/
+	clientPath(id) {
+		return this.table.get(id)?.clientPath;
+	}
+	/**
+	* Re-hash one bundle (the HMR watch's registration hook — the only entry
+	* point through which bundle content changes reach the graph).
+	* @param id - entry id (package name).
+	* @returns the new rev, or undefined for an unknown id.
+	*/
+	rebuilt(id) {
+		const record = this.table.get(id);
+		if (record === void 0) return void 0;
+		const rev = shortHash(readFileSync(record.clientPath));
+		if (rev === record.entry.rev) return rev;
+		record.entry = graphRow(id, rev, record.entry.inject, record.entry.immediately === true);
+		this.composed = this.compose();
+		for (const notify of this.rebuildListeners) try {
+			notify(id, rev);
+		} catch (error) {
+			this.ctx.logger.error(error);
+		}
+		this.notifyGraphChanged();
+		return rev;
+	}
+	/**
+	* Subscribe to bundle rebuilds; fires only when the re-hash changed the rev.
+	* @param listener - receives the entry id and its new bundle rev.
+	* @returns the unsubscriber.
+	*/
+	onRebuilt(listener) {
+		this.rebuildListeners.add(listener);
+		return () => {
+			this.rebuildListeners.delete(listener);
+		};
+	}
+	/**
+	* Fires after any flush that recomposed the graph (row added/removed, or a
+	* rebuilt rev change). Pull model: listeners re-read {@link graph}.
+	* @param listener - notified with no payload.
+	* @returns the unsubscriber.
+	*/
+	onGraphChanged(listener) {
+		this.graphListeners.add(listener);
+		return () => {
+			this.graphListeners.delete(listener);
+		};
+	}
+	compose() {
+		const entries = [...this.table.values()].map((record) => record.entry);
+		return {
+			rev: shortHash(JSON.stringify(entries)),
+			entries
+		};
+	}
+	notifyGraphChanged() {
+		for (const listener of this.graphListeners) try {
+			listener();
+		} catch (error) {
+			this.ctx.logger.error(error);
+		}
+	}
+	resolveMeta(pkgName) {
+		const cached = this.pkgMeta.get(pkgName);
+		if (cached !== void 0) return cached;
+		let pkgPath;
+		try {
+			pkgPath = this.resolvePkgJson(pkgName);
+		} catch {
+			this.pkgMeta.set(pkgName, null);
+			return null;
+		}
+		const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+		const dsh = pkg.dsh;
+		const decl = parseDshClient(pkgName, dsh !== null && typeof dsh === "object" ? dsh.client : void 0);
+		if (decl === void 0 || decl.platform !== "web") {
+			this.pkgMeta.set(pkgName, null);
+			return null;
+		}
+		const clientRel = clientExportOf(pkgName, pkg.exports);
+		if (clientRel === void 0) throw new Error(`client-modules: ${pkgName} declares dsh.client but exports no "./client" bundle`);
+		const meta = {
+			clientPath: join(dirname(pkgPath), clientRel),
+			...decl.inject !== void 0 ? { inject: decl.inject } : {},
+			immediately: decl.immediately === true
+		};
+		this.pkgMeta.set(pkgName, meta);
+		return meta;
+	}
+	/**
+	* Read the activation-time bundle revision.
+	* @param pkgName - package that declares the client bundle.
+	* @param clientPath - absolute path of the built client artifact.
+	* @returns the bundle content's short hash for use as its revision.
+	* @throws {MissingClientBundleError} when the read fails with `ENOENT`; other filesystem errors are rethrown unchanged.
+	*/
+	initialBundleRevision(pkgName, clientPath) {
+		try {
+			return shortHash(readFileSync(clientPath));
+		} catch (error) {
+			if (error.code !== "ENOENT") throw error;
+			throw new MissingClientBundleError(pkgName, clientPath, error);
+		}
+	}
+	/** Reconcile one entry name against the live loader entries. @returns whether the table changed. */
+	processOne(entryName) {
+		let qualifies = false;
+		for (const entry of this.ctx.loader.entries()) if (entry.options.name === entryName && entry.fiber !== void 0 && !entry.disabled) {
+			qualifies = true;
+			break;
+		}
+		if (!qualifies) return this.table.delete(entryName);
+		if (this.table.has(entryName)) return false;
+		const meta = this.resolveMeta(entryName);
+		if (meta === null) return false;
+		const rev = this.initialBundleRevision(entryName, meta.clientPath);
+		this.table.set(entryName, {
+			entry: graphRow(entryName, rev, meta.inject, meta.immediately),
+			clientPath: meta.clientPath
+		});
+		return true;
+	}
+	flush(onError) {
+		let changed = false;
+		for (const entryName of [...this.dirty]) {
+			this.dirty.delete(entryName);
+			try {
+				if (this.processOne(entryName)) changed = true;
+			} catch (error) {
+				onError(error instanceof Error ? error : new Error(String(error)));
+			}
+		}
+		if (changed) {
+			this.composed = this.compose();
+			this.notifyGraphChanged();
+		}
+	}
+	serveBundle = async (req, res) => {
+		if (req.method !== "GET" && req.method !== "HEAD") {
+			res.writeHead(405);
+			res.end();
+			return;
+		}
+		/* v8 ignore next -- `?? '/'` arm: node:http always sets url on server requests. */
+		const pathname = decodeURIComponent(new URL(req.url ?? "/", "http://x").pathname);
+		const prefix = "/plugins/";
+		const mapSuffix = "/client.js.map";
+		const bundleSuffix = "/client.js";
+		const isSourceMap = pathname.startsWith(prefix) && pathname.endsWith(mapSuffix);
+		const suffix = isSourceMap ? mapSuffix : bundleSuffix;
+		const clientPath = pathname.startsWith(prefix) && pathname.endsWith(suffix) ? this.clientPath(pathname.slice(9, -suffix.length)) : void 0;
+		const path = clientPath === void 0 ? void 0 : `${clientPath}${isSourceMap ? ".map" : ""}`;
+		if (path === void 0) {
+			res.writeHead(404);
+			res.end();
+			return;
+		}
+		try {
+			const body = await readFile(path);
+			res.writeHead(200, {
+				"content-type": isSourceMap ? "application/json; charset=utf-8" : "text/javascript; charset=utf-8",
+				"cache-control": "no-cache",
+				"content-length": body.length
+			});
+			res.end(body);
+		} catch {
+			res.writeHead(404);
+			res.end();
+		}
+	};
+};
+//#endregion
+export { ClientModuleRegistry, ClientModuleRegistry as default, injectBootManifest };

package/lib/invariant.js

@@ -0,0 +1,34 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-client-modules`.
+* @module @deepseek-ai/dsh-client-modules/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-client-modules";
+/** Cordis companion plugin name. */
+const name = "client-modules-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* Owned relation: the node half's boot entry graph must stay self-consistent
+* — every row must resolve a clientPath under the same id (the
+* /plugins/<id>/client.js URL it advertises would otherwise 404 on a browser
+* that just received the graph). Checked on every scan trigger (cordis
+* 'internal/plugin'): graph() and clientPath() read the same table object,
+* so the relation holds at any instant — no need to wait out the node half's
+* own microtask-debounced flush.
+*/
+const install = (ctx, fail) => {
+	ctx.on("internal/plugin", () => {
+		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 });
+};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

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

@@ -0,0 +1,21 @@
+/**
+ * Browser half (the standard `./client` export): the module-system class and
+ * wire contract, plus the enrollment plugin face. The module system itself is
+ * built by the shell kernel BEFORE cordis exists (the bootstrap exception —
+ * the mechanism that loads plugins cannot arrive through
+ * itself); the plugin face only enrolls that pre-existing instance by
+ * providing it as `ctx.modules`. The kernel statically registers this module,
+ * so the graph row for this package never triggers a real fetch — arrival is
+ * a no-op against the already-registered entry.
+ * @module @deepseek-ai/dsh-client-modules/client
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export { ClientModuleSystem } from './system.ts';
+export { parseBootManifest } from './manifest.ts';
+export type { BootManifest, BootModuleRow, BootPluginRow, ClientModuleLoader, ClientModuleRecord, ClientModuleSystemOptions, ClientPluginHandoff, DshWindow, WebBootEntry, WebBootGraph, } from './manifest.ts';
+/**
+ * Enroll the kernel-built module system as `ctx.modules`.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,190 @@
+/**
+ * Client module system: the browser peer of Node's internal ESM loader, built
+ * as a lazy CJS table. The vendored cordis Loader consumes this object
+ * through its `internal` contract (the only call site is `EntryTree.import` →
+ * `internal.import`), which keeps entry governance (fiber lifecycle, inject
+ * waiting, update/refresh) entirely on the vendored side while this package
+ * owns code arrival.
+ *
+ * Lazy CJS model: executing a plugin bundle only REGISTERS its
+ * 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) → 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 → 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
+ * factories walks the same order minus the load branch: loading is async,
+ * so only already-registered bundles can be required — and cross-plugin value
+ * imports are a build error anyway.
+ *
+ * This file is the browser-safe contract face (zero node imports): the
+ * `__DSH_BOOT__` wire types, the boot-manifest parser, and the boundaries around
+ * {@link ClientModuleSystem}. The package root is the host-side service that
+ * composes the wire.
+ */
+import type { ClientModuleSystem } from './system.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** The client module system the web shell builds at boot (provided by the `./client` wrapper plugin). */
+        modules: ClientModuleLoader;
+    }
+}
+/**
+ * One composed client entry pushed by the host (a graph row). Wire
+ * single source: the host node half (package root) produces this same shape.
+ * `immediately` marks stage-one prefetch; `inject` is informational graph
+ * metadata (the authoritative edges live in each package's `dsh.client`
+ * declaration and reach fibers through entry creation).
+ */
+export interface WebBootEntry {
+    /** Entry name == package name. */
+    id: string;
+    /** Bundle endpoint, '/plugins/<id>/client.js?rev=<rev>'. */
+    url: string;
+    /** Bundle content hash (cache-busting consistency anchor). */
+    rev: string;
+    /** Package-name dependency edges, informational (preflight display / HMR diffing). */
+    inject?: string[];
+    /** Stage-one prefetch mark: load the script for factory registration during module-face boot. */
+    immediately?: boolean;
+}
+/** The composed client entry graph the host injects as `window.__DSH_BOOT__`. */
+export interface WebBootGraph {
+    /** Consistency anchor over the whole graph (content + bundle hashes). */
+    rev: string;
+    /** Composed entries; order carries no semantics (activation order is fiber inject waiting). */
+    entries: WebBootEntry[];
+}
+/** The npm-package view of one boot row: what the module table needs to fetch the bundle. */
+export interface BootModuleRow {
+    /** Entry name == package name (module-table key). */
+    id: string;
+    /** Bundle endpoint, '/plugins/<id>/client.js?rev=<rev>'. */
+    url: string;
+    /** Bundle content hash. */
+    rev: string;
+}
+/** The cordis-plugin view of one boot row: what entry composition needs (optional wire fields normalized). */
+export interface BootPluginRow {
+    /** Entry name == package name. */
+    id: string;
+    /** Package-name dependency edges ([] when the wire omits them). */
+    inject: string[];
+    /** Stage-one prefetch tier (false when the wire omits it). */
+    immediately: boolean;
+}
+/** The parsed boot manifest: one wire, two consumer views. */
+export interface BootManifest {
+    /** Consistency anchor over the whole graph. */
+    rev: string;
+    /** Rows as the module table consumes them. */
+    modules: BootModuleRow[];
+    /** Rows as entry composition consumes them. */
+    plugins: BootPluginRow[];
+}
+/**
+ * Parse `window.__DSH_BOOT__` into the two consumer views. Wire boundary:
+ * a missing or malformed graph throws (the shell shows the loud failure —
+ * a page without a valid manifest cannot boot anything).
+ * @param wire - the raw `window.__DSH_BOOT__` value.
+ * @returns the manifest with optional plugin-view fields normalized.
+ */
+export declare function parseBootManifest(wire: unknown): BootManifest;
+/** The shape a client bundle hands to `window.__ModuleLoader__.load` (registration handoff). */
+export interface ClientPluginHandoff {
+    /** Plugin id (package name) — the registration key; must match the graph row being executed. */
+    id: 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.
+     */
+    factory: (require: (spec: string) => unknown) => Record<string, unknown>;
+}
+/** 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;
+    /** Bundle registration sink; installed once per page by the {@link ClientModuleSystem} constructor. */
+    __ModuleLoader__?: {
+        load(handoff: ClientPluginHandoff): void;
+    };
+    /**
+     * Kernel handoff slot: the shell kernel stores the instance here right
+     * after construction (before cordis exists) so the `./client` wrapper
+     * plugin can provide it as `ctx.modules`. Missing slot at wrapper apply
+     * time = kernel sequencing bug, thrown loud.
+     */
+    __DSH_MODULES__?: ClientModuleSystem;
+}
+/** Per-module bookkeeping in {@link ClientModuleLoader.loadCache} (module-graph boundary, flat today). */
+export interface ClientModuleRecord {
+    /** Module id (entry name / package name). */
+    id: string;
+    /** 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). */
+    edges: Set<string>;
+}
+/**
+ * The internal-contract subset the vendored Loader and the client HMR plugin
+ * consume. Mounted on `ctx.loader.internal` by the shell boot and provided
+ * as `ctx.modules`.
+ */
+export interface ClientModuleLoader {
+    /** Discriminant against Node's internal loader shapes ('v1'/'v2'). */
+    version: 'client';
+    /** 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
+     * `specifier` through the branch order documented on the module, fetching
+     * and executing a bundle when needed.
+     * @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 exports.
+     */
+    import(specifier: string, parentURL: string, attrs: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Register a shell-own module (app-shell — code that ships inside the shell
+     * bundle and never arrives as a plugin bundle).
+     * @param id - entry name (shell-owned pseudo id).
+     * @param module - the statically imported module namespace.
+     */
+    registerStatic(id: string, module: unknown): void;
+    /**
+     * Stage-one arrival: load the entry's script to register its factory (no
+     * materialization — module side effects wait for import).
+     * No-op for static-registered ids and ids whose factory is already
+     * registered; concurrent calls share one in-flight task. To force a fresh
+     * load (HMR), {@link invalidate} first.
+     * @param id - graph entry name.
+     */
+    prefetch(id: string): Promise<void>;
+    /**
+     * Full reset of one module: drop its registered factory and materialized
+     * record so the next prefetch/import reloads it (the HMR invalidation hook).
+     * @param id - entry name to invalidate.
+     */
+    invalidate(id: string): void;
+}
+/** Options for {@link ClientModuleSystem} (assembled by the web shell kernel at boot). */
+export interface ClientModuleSystemOptions {
+    /** Boot rows in the module-table view (from {@link parseBootManifest}). */
+    modules: BootModuleRow[];
+    /** Module-table seed: platform-singleton specifier → shell instance. */
+    staticModules: Record<string, unknown>;
+    /** Bundle-load hook. Defaults to a same-origin classic `<script src>` element. */
+    loadBundle?: (url: string) => Promise<void>;
+}
+//# sourceMappingURL=manifest.d.ts.map

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

@@ -0,0 +1,48 @@
+/**
+ * ClientModuleSystem — the implementation behind the {@link ClientModuleLoader}
+ * contract. The conceptual contract (lazy CJS model, resolution branch order) is
+ * documented on the public interfaces in `./manifest.ts`; this file owns the
+ * state tables and the load/materialize machinery.
+ */
+import type { ClientModuleLoader, ClientModuleRecord, ClientModuleSystemOptions } from './manifest.ts';
+/**
+ * The client module system: state tables plus the arrival/materialization
+ * machinery implementing {@link ClientModuleLoader} (whose members carry the
+ * contract documentation). Construction indexes the boot rows and installs the
+ * `window.__ModuleLoader__` registration sink — once per page.
+ */
+export declare class ClientModuleSystem implements ClientModuleLoader {
+    readonly version = "client";
+    readonly loadCache: Map<string, ClientModuleRecord>;
+    private readonly seed;
+    private readonly statics;
+    private readonly factories;
+    /** In-flight prefetch (script load) per id; concurrent callers share it. */
+    private readonly pendingArrival;
+    /** Materialization re-entrancy guard: factory-form CJS cannot deliver partial exports, so a cycle is fatal. */
+    private readonly materializing;
+    private readonly graphRows;
+    private readonly loadBundle;
+    /**
+     * Build the module system over the parsed boot rows.
+     * @param options - Module rows, module-table staticModules, and bundle-load hook.
+     */
+    constructor(options: ClientModuleSystemOptions);
+    /** Load one graph row so its factory is registered (idempotent per in-flight arrival). */
+    private arrive;
+    /** Materialize a registered factory (synchronous; memoized in loadCache). */
+    private materialize;
+    /**
+     * The synchronous require answered to factories: seed → static → memoized
+     * record → registered factory (recursive materialization — this is what
+     * makes load order self-resolving). Fetching is async and therefore
+     * unreachable from here; an unregistered plugin specifier is loud (and a
+     * cross-plugin value import is already a build error upstream).
+     */
+    private makeRequire;
+    import(specifier: string): Promise<unknown>;
+    registerStatic(id: string, module: unknown): void;
+    prefetch(id: string): Promise<void>;
+    invalidate(id: string): void;
+}
+//# sourceMappingURL=system.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Node half of the client module system (`dsh.client` dual-face package): scans
+ * the host Loader's entries for packages declaring `dsh.client`, composes the
+ * `window.__DSH_BOOT__` entry graph (wire single source: {@link WebBootEntry}
+ * in `./client/manifest.ts`), serves `/plugins/<id>/client.js` and its source
+ * map, taps the index render to inject the boot manifest, and provides the
+ * `clientModuleHost` service (the HMR node half's registration/notification
+ * face).
+ *
+ * Scanning is incremental per package — there is no full-rescan code path.
+ * Every cordis `internal/plugin` emission (fiber construction/disposal) marks
+ * the fiber's entry name dirty; a microtask flush reconciles each dirty name
+ * against the live loader entries. The activation pass seeds the same dirty
+ * set with all current entries and flushes synchronously, so first scan and
+ * steady state share one implementation. Package metadata (including the
+ * 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 ClientModuleRegistry.rebuilt}.
+ * @module @deepseek-ai/dsh-client-modules
+ */
+import { Service } from '@deepseek-ai/cordis';
+import type { Context } from '@deepseek-ai/cordis';
+import type { WebBootGraph } from './client/manifest.ts';
+export type { BootManifest, BootModuleRow, BootPluginRow, WebBootEntry, WebBootGraph, } from './client/manifest.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** The web plugin table (provided by the client-modules node half). */
+        clientModules: ClientModuleRegistry;
+    }
+}
+/**
+ * Inject the boot entry graph into index.html: `window.__DSH_BOOT__` as the
+ * first script in <head> (before the shell bundle reads it). `<` is escaped in
+ * the JSON so plugin-controlled strings cannot break out of the script element.
+ * @param html - the index.html source.
+ * @param graph - the composed entry graph.
+ * @returns the html with the graph script injected.
+ */
+export declare function injectBootManifest(html: string, graph: WebBootGraph): string;
+/**
+ * The web plugin table service: incremental `dsh.client` scan + wire composition
+ * + bundle route + index tap. Construction runs the activation scan
+ * synchronously — a malformed declaration or missing bundle among the
+ * already-loaded entries aggregates into one loud throw (FAILED fiber; the
+ * boot activation audit reports it).
+ */
+export declare class ClientModuleRegistry extends Service {
+    static inject: string[];
+    private readonly table;
+    private readonly pkgMeta;
+    private readonly rebuildListeners;
+    private readonly graphListeners;
+    private readonly dirty;
+    private readonly resolvePkgJson;
+    private flushQueued;
+    private composed;
+    /**
+     * Build the service: subscribe, seed, and run the activation flush.
+     * @param ctx - plugin context carrying webServer and loader.
+     */
+    constructor(ctx: Context);
+    /**
+     * Current composed entry graph (stable object between changes).
+     * @returns the graph served as `window.__DSH_BOOT__`.
+     */
+    graph(): WebBootGraph;
+    /**
+     * Absolute path of an entry's client bundle.
+     * @param id - entry id (package name).
+     * @returns the path, or undefined for an unknown id.
+     */
+    clientPath(id: string): string | undefined;
+    /**
+     * Re-hash one bundle (the HMR watch's registration hook — the only entry
+     * point through which bundle content changes reach the graph).
+     * @param id - entry id (package name).
+     * @returns the new rev, or undefined for an unknown id.
+     */
+    rebuilt(id: string): string | undefined;
+    /**
+     * Subscribe to bundle rebuilds; fires only when the re-hash changed the rev.
+     * @param listener - receives the entry id and its new bundle rev.
+     * @returns the unsubscriber.
+     */
+    onRebuilt(listener: (id: string, rev: string) => void): () => void;
+    /**
+     * Fires after any flush that recomposed the graph (row added/removed, or a
+     * rebuilt rev change). Pull model: listeners re-read {@link graph}.
+     * @param listener - notified with no payload.
+     * @returns the unsubscriber.
+     */
+    onGraphChanged(listener: () => void): () => void;
+    private compose;
+    private notifyGraphChanged;
+    private resolveMeta;
+    /**
+     * Read the activation-time bundle revision.
+     * @param pkgName - package that declares the client bundle.
+     * @param clientPath - absolute path of the built client artifact.
+     * @returns the bundle content's short hash for use as its revision.
+     * @throws {MissingClientBundleError} when the read fails with `ENOENT`; other filesystem errors are rethrown unchanged.
+     */
+    private initialBundleRevision;
+    /** Reconcile one entry name against the live loader entries. @returns whether the table changed. */
+    private processOne;
+    private flush;
+    private readonly serveBundle;
+}
+export default ClientModuleRegistry;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-modules`.
+ * @module @deepseek-ai/dsh-client-modules/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "client-modules-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@crazx/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.0-rc.7.zw.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aka-danielZhang/deepseek-harness.git",
+    "directory": "packages/client/modules"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "platform": "web",
+      "inject": [],
+      "immediately": true
+    }
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-loader": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.7",
+    "@deepseek-ai/cordis": "^0.1.0-rc.7"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.7",
+    "@deepseek-ai/cordis": "^0.1.0-rc.7"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}