@deepseek-ai/dsh-client-modules 0.1.0-rc.7 → 0.1.1-rc.1

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: efaff699839b977cc45f89f3c164402241b90dc2
-README.zh.md: 6ab3c8494d7ea902e8b891008f236aec41301a35
+README.md: eaf64599bc5fc5d9663d00c3b341764a4ccd38c8
+README.zh.md: ea051338bb7837cb49f7a5ecd4cdad5b6b3ad71d

package/README.md

@@ -4,11 +4,15 @@ 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).
+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; graph composition places declared dynamic requests before their consumers, and require cycles throw because 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 Host installs `window.__ModuleLoader__` before parser preloads run. Its queue-mode `load()` retains early registrations; `create()` materializes this package's factory with an external-rejecting bootstrap require and calls its `createClientModuleSystem` export. Construction caches those same exports as the modules row, switches the same facade to live registration, and drains the remaining queue. The bundle retains the resulting system in a module closure, so its later Cordis `apply()` provides the identical instance as `ctx.modules` without another page global.
 
-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.
+Resolution branch order (`import(specifier)`): platform seed word → shell instance; memoized record → exports; graph row (`window.__DSH_BOOT__`) → register its classic-script factory; registered factory → 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 graph-row load 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 a non-bootstrap 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, carries package-specific `dsh.client.external` requests, orders dynamic providers before consumers, and serves each bundle 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.
+
+`dsh.client.external` is an optional exact-specifier request list beyond the implicit baseline: shell-seeded React, Cordis, and static UI libraries plus parser-preloaded runtime. A request is answered by the dynamic package row it names or an exact static-table key; only a trailing `/client` aliases a package row, and there is no provider-alias declaration. Type-only imports are erased and create no request. Composition rejects malformed requests, missing suppliers, self-requests, and synchronous request cycles; import and prefetch recursively register dynamic suppliers before their consumers materialize. See [shared modules and the module graph](../AGENTS.md#shared-modules-and-the-module-graph).
 
 ## Model Experience
 

package/README.zh.md

@@ -4,11 +4,15 @@
 
 客户端模块系统：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 就是其包的客户端侧）。
+惰性 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（热模块替换）钩子。
+Host 会在 parser preload 运行前安装 `window.__ModuleLoader__`。其 queue 模式的 `load()` 保存提前到达的 registration；`create()` 使用拒绝 external 的 bootstrap require 物化本包 factory，并调用其 `createClientModuleSystem` 导出。构造过程把同一组导出缓存为 modules row，把同一个 facade 切换到 live registration，再排空余下 queue。Bundle 通过模块闭包保留生成的系统，因此随后 Cordis `apply()` 能把同一实例提供为 `ctx.modules`，无需另一个页面全局变量。
 
-Node 侧会扫描已启用的 Loader 配置项以发现 web `dsh.client` 包，解析每个 `exports["./client"]`，把构建后的 bundle 哈希写入启动图，并通过 `/plugins` 提供该文件及其 sourcemap。源码启动会把宿主侧导入映射到 TypeScript 源码，但仍消费这一构建后的客户端导出；缺失文件共享一条构建说明，随后以包／路径列表列出各项，而无关的文件系统错误仍是独立故障。
+解析分支顺序（`import(specifier)`）：平台种子词 → 外壳实例；记忆化记录 → 导出；模块图记录（`window.__DSH_BOOT__`）→ 登记其 classic-script factory；已登记 factory → 物化；其他情况一律抛出异常。这是构建时 bundle 纯度门禁的运行时镜像。交给 factory 的同步 `require` 采用相同顺序，但不含异步 graph-row 加载分支，并把观察到的边记录到模块记录中。`prefetch` 是第一阶段到达钩子（只加载脚本并登记 factory；并发调用共享一个进行中的任务）；`invalidate` 会丢弃非 bootstrap factory 与物化记录，使下一次 prefetch/import 重新加载脚本；它是 HMR（热模块替换）钩子。
+
+Node 侧会扫描已启用的 Loader 配置项以发现 web `dsh.client` 包，解析每个 `exports["./client"]`，把构建后的 bundle 哈希和包专属 `dsh.client.external` 请求写入启动图，把动态提供方排在消费者之前，并通过 `/plugins` 提供该文件及其 sourcemap。源码启动会把宿主侧导入映射到 TypeScript 源码，但仍消费这一构建后的客户端导出；缺失文件共享一条构建说明，随后以包／路径列表列出各项，而无关的文件系统错误仍是独立故障。
+
+`dsh.client.external` 是统一基座之外的可选精确 specifier 请求列表。统一基座包括外壳播种的 React、Cordis 和静态 UI 库，以及由 HTML parser 预载的 runtime。请求由其命名的动态 package row 或精确静态表键回答；只有末尾 `/client` 会别名到 package row，并且不存在 provider 别名声明。纯类型 import 会被擦除，不产生请求。组合阶段会拒绝畸形请求、缺失提供方、自请求和同步请求环；import 与 prefetch 会在消费者物化前递归登记动态提供方。参见[共享模块与模块图](../AGENTS.md#shared-modules-and-the-module-graph)。
 
 ## 模型体验
 

package/lib/client.js

@@ -4,7 +4,112 @@ window.__ModuleLoader__.load({
 		var module = { exports: {} };
 		var exports = module.exports;
 		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		//#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; graph row → register its dependency factories and own
+		* factory; registered factory → 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 a requested dynamic package must have
+		* registered its factory before a consumer materializes.
+		*
+		* 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.
+		*/
+		/**
+		* Validate an optional string-array field read from a `dsh.client` declaration
+		* or from the boot wire.
+		* @param subject - diagnostic prefix naming the package or the wire row.
+		* @param field - field name as it appears in the diagnostic.
+		* @param value - the raw field value.
+		* @returns the validated array, or undefined when the field is absent.
+		* @throws {Error} when the value is present but is not an array of strings.
+		*/
+		function optionalStringArray(subject, field, value) {
+			if (value === void 0) return void 0;
+			if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) throw new Error(`client-modules: ${subject} ${field} must be a string array`);
+			return value;
+		}
+		/**
+		* Normalize a module specifier onto the graph row that owns it: a plugin bundle
+		* IS its package's client half, so `<id>/client` (the exports subpath external
+		* bundles emit) and the bare package name resolve to the same exports. Both the
+		* require path and graph composition normalize here, which is what lets each
+		* importing package request the subpath its own code imports.
+		* @param spec - module specifier as a bundle requires it or a declaration spells it.
+		* @returns the specifier with a trailing `/client` removed.
+		*/
+		function stripClientSuffix(spec) {
+			return spec.endsWith("/client") ? spec.slice(0, -7) : spec;
+		}
+		/**
+		* 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`);
+				const subject = `boot manifest entry ${where}`;
+				const inject = optionalStringArray(subject, "inject", row.inject);
+				const external = optionalStringArray(subject, "external", row.external);
+				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,
+					external: external === void 0 ? [] : [...external]
+				});
+				plugins.push({
+					id: row.id,
+					inject: inject === void 0 ? [] : [...inject],
+					immediately: row.immediately === true
+				});
+			}
+			return {
+				rev: graph.rev,
+				modules,
+				plugins
+			};
+		}
+		//#endregion
 		//#region lib/types/client/system.js
+		/**
+		* 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.
+		*/
 		/** Default bundle-load hook: same-origin external classic script. */
 		const defaultLoadBundle = (url) => new Promise((resolve, reject) => {
 			const el = document.createElement("script");
@@ -21,12 +126,6 @@ window.__ModuleLoader__.load({
 			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).
@@ -41,15 +140,17 @@ window.__ModuleLoader__.load({
 		/**
 		* 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.
+		* contract documentation). Construction indexes the boot rows, retains the
+		* already-materialized bootstrap module, and switches the HTML-installed
+		* loader facade from its pending queue to live registration.
 		*/
 		var ClientModuleSystem = class {
 			version = "client";
+			manifest;
 			loadCache = /* @__PURE__ */ new Map();
 			seed;
-			statics = /* @__PURE__ */ new Map();
 			factories = /* @__PURE__ */ new Map();
+			bootstrapIds = /* @__PURE__ */ new Set();
 			/** 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. */
@@ -58,28 +159,45 @@ window.__ModuleLoader__.load({
 			loadBundle;
 			/**
 			* Build the module system over the parsed boot rows.
-			* @param options - Module rows, module-table staticModules, and bundle-load hook.
+			* @param options - Parsed graph, platform seed, bootstrap module, registration facade, and transport.
 			*/
 			constructor(options) {
+				this.manifest = options.manifest;
 				this.seed = new Map(Object.entries(options.staticModules));
 				this.loadBundle = options.loadBundle ?? defaultLoadBundle;
-				for (const row of options.modules) {
+				for (const row of options.manifest.modules) {
 					if (this.graphRows.has(row.id)) throw new Error(`client-modules: duplicate graph entry "${row.id}"`);
 					this.graphRows.set(row.id, row);
 				}
-				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);
-				} };
+				const bootstrapId = stripClientSuffix(options.bootstrapModule.id);
+				this.bootstrapIds.add(bootstrapId);
+				this.loadCache.set(bootstrapId, {
+					id: bootstrapId,
+					exports: options.bootstrapModule.exports,
+					styles: [],
+					edges: /* @__PURE__ */ new Set()
+				});
+				const target = options.registrationTarget;
+				if (target.mode !== "queue") throw new Error("client-modules: window.__ModuleLoader__.create called after module-system boot");
+				const pending = target.pendingQueue.splice(0);
+				target.mode = "live";
+				target.load = (registration) => {
+					this.register(registration);
+				};
+				for (const registration of pending) target.load(registration);
+			}
+			/** Register one bundle factory, rejecting a script that executes twice without invalidation. */
+			register(registration) {
+				const id = stripClientSuffix(registration.id);
+				if (this.bootstrapIds.has(id) || this.factories.has(id)) throw new Error(`client-modules: duplicate factory registration for "${registration.id}" (bundle executed twice without invalidate?)`);
+				this.factories.set(id, registration.factory);
 			}
 			/** 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();
+				if (this.loadCache.has(id) || 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(() => {
@@ -88,6 +206,19 @@ window.__ModuleLoader__.load({
 				this.pendingArrival.set(id, task);
 				return task;
 			}
+			/** Register each unresolved dynamic request before registering its consumer. */
+			async arriveGraphRow(row, open = []) {
+				const cycleStart = open.indexOf(row.id);
+				if (cycleStart !== -1) throw new Error(`client-modules: module arrival cycle ${[...open.slice(cycleStart), row.id].join(" -> ")} (the host must reject this graph before serving it)`);
+				const next = [...open, row.id];
+				for (const request of row.external) {
+					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);
+				}
+				await this.arrive(row);
+			}
 			/** Materialize a registered factory (synchronous; memoized in loadCache). */
 			materialize(id) {
 				const existing = this.loadCache.get(id);
@@ -112,146 +243,80 @@ window.__ModuleLoader__.load({
 				}
 			}
 			/**
-			* 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).
+			* The synchronous require answered to factories: seed → memoized record →
+			* registered factory. Fetching is async and therefore unreachable
+			* from here; an external dynamic package must have arrived before its
+			* consumer materializes.
 			*/
 			makeRequire(edges) {
 				return (spec) => {
 					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)`);
+					throw new Error(`client-modules: require("${spec}") missed the module table — not a platform seed word, not a materialized module, and no registered package factory (a build-time externals drift, or a dynamic dependency that did not arrive)`);
 				};
 			}
 			async import(specifier) {
 				if (this.seed.has(specifier)) return this.seed.get(specifier);
-				const existing = this.loadCache.get(specifier);
+				const id = stripClientSuffix(specifier);
+				const existing = this.loadCache.get(id);
 				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);
+				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;
 			}
 			async prefetch(id) {
-				if (this.statics.has(id)) return;
-				const row = this.graphRows.get(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.arrive(row);
+				await this.arriveGraphRow(row);
 			}
 			invalidate(id) {
-				this.factories.delete(id);
-				this.loadCache.delete(id);
+				const normalized = stripClientSuffix(id);
+				if (this.bootstrapIds.has(normalized)) return;
+				this.factories.delete(normalized);
+				this.loadCache.delete(normalized);
 			}
 		};
 		//#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.
-		*/
+		//#region lib/types/client/index.js
+		let moduleSystem;
 		/**
-		* 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.
+		* Build the live module system from the HTML facade's materialized modules bundle.
+		* @param target - Stable registration facade whose pending queue becomes the live sink.
+		* @param bootstrapModule - This bundle's id and already-materialized exports.
+		* @param options - Raw boot graph, platform seed, and optional bundle transport.
+		* @returns The created module system, also published for this package's Cordis plugin face.
 		*/
-		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
-			};
+		function createClientModuleSystem(target, bootstrapModule, options) {
+			moduleSystem = new ClientModuleSystem({
+				manifest: parseBootManifest(options.boot),
+				staticModules: options.staticModules,
+				registrationTarget: target,
+				bootstrapModule,
+				...options.loadBundle === void 0 ? {} : { loadBundle: options.loadBundle }
+			});
+			return moduleSystem;
 		}
-		//#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);
+			if (moduleSystem === void 0) throw new Error("client-modules: createClientModuleSystem must run before plugin boot");
+			ctx.reflect.provide("modules", moduleSystem);
 		}
 		//#endregion
 		exports.ClientModuleSystem = ClientModuleSystem;
 		exports.apply = apply;
+		exports.createClientModuleSystem = createClientModuleSystem;
 		exports.parseBootManifest = parseBootManifest;
+		exports.stripClientSuffix = stripClientSuffix;
 		return module.exports;
 	}
 });

package/lib/index.js

@@ -4,15 +4,74 @@ 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/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; graph row → register its dependency factories and own
+* factory; registered factory → 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 a requested dynamic package must have
+* registered its factory before a consumer materializes.
+*
+* 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.
+*/
+/**
+* Validate an optional string-array field read from a `dsh.client` declaration
+* or from the boot wire.
+* @param subject - diagnostic prefix naming the package or the wire row.
+* @param field - field name as it appears in the diagnostic.
+* @param value - the raw field value.
+* @returns the validated array, or undefined when the field is absent.
+* @throws {Error} when the value is present but is not an array of strings.
+*/
+function optionalStringArray(subject, field, value) {
+	if (value === void 0) return void 0;
+	if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) throw new Error(`client-modules: ${subject} ${field} must be a string array`);
+	return value;
+}
+/**
+* Normalize a module specifier onto the graph row that owns it: a plugin bundle
+* IS its package's client half, so `<id>/client` (the exports subpath external
+* bundles emit) and the bare package name resolve to the same exports. Both the
+* require path and graph composition normalize here, which is what lets each
+* importing package request the subpath its own code imports.
+* @param spec - module specifier as a bundle requires it or a declaration spells it.
+* @returns the specifier with a trailing `/client` removed.
+*/
+function stripClientSuffix(spec) {
+	return spec.endsWith("/client") ? spec.slice(0, -7) : spec;
+}
+//#endregion
 //#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).
+* in `./client/manifest.ts`) in module-graph order, serves
+* `/plugins/<id>/client.js` and its source map, contributes the boot manifest
+* plus the parser-blocking bootstrap preloads to the webserver's index
+* injection table, 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
@@ -63,11 +122,13 @@ function parseDshClient(pkgName, value) {
 	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`);
+	const inject = optionalStringArray(pkgName, "dsh.client.inject", decl.inject);
+	const external = optionalStringArray(pkgName, "dsh.client.external", decl.external);
 	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 } : {},
+		...inject !== void 0 ? { inject } : {},
+		...external !== void 0 ? { external } : {},
 		...decl.immediately !== void 0 ? { immediately: decl.immediately } : {}
 	};
 }
@@ -88,32 +149,108 @@ 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) {
+function graphRow(id, rev, fields) {
 	return {
 		id,
 		url: `/plugins/${id}/client.js?rev=${rev}`,
 		rev,
-		...injectEdges !== void 0 ? { inject: injectEdges } : {},
-		...immediately ? { immediately: true } : {}
+		...fields.inject !== void 0 ? { inject: fields.inject } : {},
+		...fields.immediately ? { immediately: true } : {},
+		...fields.external.length > 0 ? { external: fields.external } : {}
 	};
 }
 /**
-* 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.
+* Order composed rows so every requested dynamic package precedes its
+* consumers. An `external` specifier is either the package row it names
+* (`<pkg>/client` aliases the bare package) or a static-table name that adds no
+* graph edge.
+* @param entries - composed rows in scan order.
+* @returns the same rows reordered; scan order breaks every tie.
+* @throws {Error} when a row requests itself or when the module graph has a
+* cycle; the message lists the packages on it.
+*/
+function orderByModuleGraph(entries) {
+	const rowsById = /* @__PURE__ */ new Map();
+	for (const entry of entries) rowsById.set(entry.id, entry);
+	const ordered = [];
+	const placed = /* @__PURE__ */ new Set();
+	const open = [];
+	const visit = (entry) => {
+		if (placed.has(entry.id)) return;
+		const cycleStart = open.indexOf(entry.id);
+		if (cycleStart !== -1) throw new Error(`client-modules: module graph cycle ${[...open.slice(cycleStart), entry.id].join(" -> ")} — a requested package row must precede its consumers, and factory-form CJS cannot deliver partial exports`);
+		open.push(entry.id);
+		for (const name of entry.external ?? []) {
+			const dependency = rowsById.get(name) ?? rowsById.get(stripClientSuffix(name));
+			if (dependency === entry) throw new Error(`client-modules: "${entry.id}" requests module "${name}" that it answers itself — a row must not declare its own package in dsh.client.external`);
+			if (dependency !== void 0) visit(dependency);
+		}
+		open.pop();
+		placed.add(entry.id);
+		ordered.push(entry);
+	};
+	for (const entry of entries) visit(entry);
+	return ordered;
+}
+/** Bootstrap package whose ordinary client bundle supplies the module-system implementation. */
+const CLIENT_MODULES_ID = "@deepseek-ai/dsh-client-modules";
+/** Ordinary dynamic bundles the HTML parser executes before the Vite shell. */
+const PARSER_PRELOAD_IDS = [CLIENT_MODULES_ID, "@deepseek-ai/dsh-client-runtime"];
+/**
+* The boot protocol as index injection rows. The inline registration queue
+* precedes blocking classic scripts for modules' and runtime's ordinary
+* `lib/client.js` artifacts. Its `create()` method materializes the modules
+* bundle, delegates construction to that bundle, and leaves the same facade
+* in live-registration mode. The graph global follows before the shell reads
+* it.
 * @param graph - the composed entry graph.
-* @returns the html with the graph script injected.
+* @returns head rows in execution order: queue script, preload scripts, graph global.
 */
-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}`;
+function bootInjections(graph) {
+	const queue = `(()=>{
+const pendingQueue=[]
+window.__ModuleLoader__={
+  mode:"queue",
+  pendingQueue,
+  load(registration){pendingQueue.push(registration)},
+  create(options){
+    if(this.mode!=="queue")throw new Error("client-modules: window.__ModuleLoader__.create called after module-system boot")
+    const index=pendingQueue.findIndex(registration=>registration.id===${JSON.stringify(CLIENT_MODULES_ID)})
+    const registration=pendingQueue[index]
+    if(registration===undefined)throw new Error("client-modules: HTML did not preload ${CLIENT_MODULES_ID}/client.js")
+    pendingQueue.splice(index,1)
+    const exports=registration.factory(specifier=>{
+      throw new Error('client-modules: ${CLIENT_MODULES_ID}/client.js requested external "'+specifier+'" before the module system existed')
+    })
+    if(typeof exports!=="object"||exports===null||typeof exports.createClientModuleSystem!=="function"||typeof exports.apply!=="function"){
+      throw new Error("client-modules: ${CLIENT_MODULES_ID}/client.js did not export the bootstrap module face")
+    }
+    return exports.createClientModuleSystem(this,{id:registration.id,exports},options)
+  }
+}
+})()`;
+	const preload = PARSER_PRELOAD_IDS.map((id) => graph.entries.find((entry) => entry.id === id)).filter((entry) => entry !== void 0).map((entry) => ({
+		kind: "script-src",
+		placement: "head",
+		src: entry.url
+	}));
+	return [
+		{
+			kind: "script",
+			placement: "head",
+			text: queue
+		},
+		...preload,
+		{
+			kind: "global",
+			name: "__DSH_BOOT__",
+			value: graph
+		}
+	];
 }
 /**
 * The web plugin table service: incremental `dsh.client` scan + wire composition
-* + bundle route + index tap. Construction runs the activation scan
+* + bundle route + index injection rows. 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).
@@ -160,7 +297,9 @@ var ClientModuleRegistry = class extends Service {
 			path: "/plugins",
 			handler: this.serveBundle
 		}), "client-modules: bundle route");
-		ctx.effect(() => ctx.webServer.tapIndex((html) => injectBootManifest(html, this.composed)), "client-modules: boot manifest injection");
+		ctx.on("webserver/index-inject", (table) => {
+			table.push(...bootInjections(this.composed));
+		});
 	}
 	/**
 	* Current composed entry graph (stable object between changes).
@@ -175,7 +314,7 @@ var ClientModuleRegistry = class extends Service {
 	* @returns the path, or undefined for an unknown id.
 	*/
 	clientPath(id) {
-		return this.table.get(id)?.clientPath;
+		return this.table.get(id)?.meta.clientPath;
 	}
 	/**
 	* Re-hash one bundle (the HMR watch's registration hook — the only entry
@@ -186,9 +325,9 @@ var ClientModuleRegistry = class extends Service {
 	rebuilt(id) {
 		const record = this.table.get(id);
 		if (record === void 0) return void 0;
-		const rev = shortHash(readFileSync(record.clientPath));
+		const rev = shortHash(readFileSync(record.meta.clientPath));
 		if (rev === record.entry.rev) return rev;
-		record.entry = graphRow(id, rev, record.entry.inject, record.entry.immediately === true);
+		record.entry = graphRow(id, rev, record.meta);
 		this.composed = this.compose();
 		for (const notify of this.rebuildListeners) try {
 			notify(id, rev);
@@ -222,7 +361,7 @@ var ClientModuleRegistry = class extends Service {
 		};
 	}
 	compose() {
-		const entries = [...this.table.values()].map((record) => record.entry);
+		const entries = orderByModuleGraph([...this.table.values()].map((record) => record.entry));
 		return {
 			rev: shortHash(JSON.stringify(entries)),
 			entries
@@ -257,6 +396,7 @@ var ClientModuleRegistry = class extends Service {
 		const meta = {
 			clientPath: join(dirname(pkgPath), clientRel),
 			...decl.inject !== void 0 ? { inject: decl.inject } : {},
+			external: decl.external ?? [],
 			immediately: decl.immediately === true
 		};
 		this.pkgMeta.set(pkgName, meta);
@@ -290,8 +430,8 @@ var ClientModuleRegistry = class extends Service {
 		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
+			entry: graphRow(entryName, rev, meta),
+			meta
 		});
 		return true;
 	}
@@ -305,10 +445,16 @@ var ClientModuleRegistry = class extends Service {
 				onError(error instanceof Error ? error : new Error(String(error)));
 			}
 		}
-		if (changed) {
-			this.composed = this.compose();
-			this.notifyGraphChanged();
+		if (!changed) return;
+		let composed;
+		try {
+			composed = this.compose();
+		} catch (error) {
+			onError(error);
+			return;
 		}
+		this.composed = composed;
+		this.notifyGraphChanged();
 	}
 	serveBundle = async (req, res) => {
 		if (req.method !== "GET" && req.method !== "HEAD") {
@@ -344,4 +490,4 @@ var ClientModuleRegistry = class extends Service {
 	};
 };
 //#endregion
-export { ClientModuleRegistry, ClientModuleRegistry as default, injectBootManifest };
+export { ClientModuleRegistry, ClientModuleRegistry as default, bootInjections, orderByModuleGraph, stripClientSuffix };

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

@@ -2,17 +2,28 @@
  * 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.
+ * the mechanism that loads plugins cannot arrive through itself). The host
+ * parser-preloads this ordinary client bundle into the pending registration
+ * queue. The HTML-installed loader facade materializes this bundle and calls
+ * its bootstrap export, which constructs the system and retains the same
+ * exports for this package's graph row. The plugin face only enrolls that
+ * pre-existing instance by providing it as `ctx.modules`.
  * @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';
+import { ClientModuleSystem } from './system.ts';
+import type { ClientBootstrapModule, ClientModuleCreateOptions, ClientModuleLoaderTarget } from './manifest.ts';
+export { ClientModuleSystem };
+export { parseBootManifest, stripClientSuffix } from './manifest.ts';
+export type { BootManifest, BootModuleRow, BootPluginRow, ClientBootstrapModule, ClientBundleRegistration, ClientModuleCreateOptions, ClientModuleLoader, ClientModuleLoaderTarget, ClientModuleRecord, ClientModuleSystemOptions, DshWindow, WebBootEntry, WebBootGraph, } from './manifest.ts';
+/**
+ * Build the live module system from the HTML facade's materialized modules bundle.
+ * @param target - Stable registration facade whose pending queue becomes the live sink.
+ * @param bootstrapModule - This bundle's id and already-materialized exports.
+ * @param options - Raw boot graph, platform seed, and optional bundle transport.
+ * @returns The created module system, also published for this package's Cordis plugin face.
+ */
+export declare function createClientModuleSystem(target: ClientModuleLoaderTarget, bootstrapModule: ClientBootstrapModule, options: ClientModuleCreateOptions): ClientModuleSystem;
 /**
  * Enroll the kernel-built module system as `ctx.modules`.
  * @param ctx - client root context.

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

@@ -16,13 +16,12 @@
  * 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.
+ * record → exports; graph row → register its dependency factories and own
+ * factory; registered factory → 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 a requested dynamic package must have
+ * registered its factory before a consumer materializes.
  *
  * This file is the browser-safe contract face (zero node imports): the
  * `__DSH_BOOT__` wire types, the boot-manifest parser, and the boundaries around
@@ -41,7 +40,9 @@ declare module '@deepseek-ai/cordis' {
  * 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).
+ * declaration and reach fibers through entry creation). `external` carries
+ * module-graph edges: unlike `inject`, they constrain code arrival because
+ * `require` is synchronous (see {@link WebBootGraph.entries}).
  */
 export interface WebBootEntry {
     /** Entry name == package name. */
@@ -54,12 +55,18 @@ export interface WebBootEntry {
     inject?: string[];
     /** Stage-one prefetch mark: load the script for factory registration during module-face boot. */
     immediately?: boolean;
+    /** Non-baseline module specifiers this row requests; omitted when it requests none. */
+    external?: string[];
 }
 /** 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). */
+    /**
+     * Composed entries in module-graph order — a dynamic package row precedes
+     * rows whose `external` requests that package. Cordis activation order is
+     * unrelated and remains owned by fiber service waiting.
+     */
     entries: WebBootEntry[];
 }
 /** The npm-package view of one boot row: what the module table needs to fetch the bundle. */
@@ -70,6 +77,8 @@ export interface BootModuleRow {
     url: string;
     /** Bundle content hash. */
     rev: string;
+    /** Module specifiers this row requests from the module table ([] when the wire omits them). */
+    external: string[];
 }
 /** The cordis-plugin view of one boot row: what entry composition needs (optional wire fields normalized). */
 export interface BootPluginRow {
@@ -89,6 +98,26 @@ export interface BootManifest {
     /** Rows as entry composition consumes them. */
     plugins: BootPluginRow[];
 }
+/**
+ * Validate an optional string-array field read from a `dsh.client` declaration
+ * or from the boot wire.
+ * @param subject - diagnostic prefix naming the package or the wire row.
+ * @param field - field name as it appears in the diagnostic.
+ * @param value - the raw field value.
+ * @returns the validated array, or undefined when the field is absent.
+ * @throws {Error} when the value is present but is not an array of strings.
+ */
+export declare function optionalStringArray(subject: string, field: string, value: unknown): string[] | undefined;
+/**
+ * Normalize a module specifier onto the graph row that owns it: a plugin bundle
+ * IS its package's client half, so `<id>/client` (the exports subpath external
+ * bundles emit) and the bare package name resolve to the same exports. Both the
+ * require path and graph composition normalize here, which is what lets each
+ * importing package request the subpath its own code imports.
+ * @param spec - module specifier as a bundle requires it or a declaration spells it.
+ * @returns the specifier with a trailing `/client` removed.
+ */
+export declare function stripClientSuffix(spec: string): string;
 /**
  * Parse `window.__DSH_BOOT__` into the two consumer views. Wire boundary:
  * a missing or malformed graph throws (the shell shows the loud failure —
@@ -97,8 +126,8 @@ export interface BootManifest {
  * @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 {
+/** One client bundle's factory registration submitted through `window.__ModuleLoader__.load`. */
+export interface ClientBundleRegistration {
     /** Plugin id (package name) — the registration key; must match the graph row being executed. */
     id: string;
     /**
@@ -108,27 +137,45 @@ export interface ClientPluginHandoff {
      */
     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. */
+/** Inputs passed by the web entry when it creates the client module system. */
+export interface ClientModuleCreateOptions {
+    /** Raw Host-injected boot graph; the modules bundle owns validation and projection. */
+    boot: unknown;
+    /** 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>;
+}
+/** The modules bundle after its factory has been materialized by the HTML bootstrap facade. */
+export interface ClientBootstrapModule {
+    /** Graph/module id carried by the modules bundle registration. */
+    id: string;
+    /** Materialized exports reused when Cordis later activates the modules entry. */
+    exports: Record<string, unknown>;
+}
+/** Stable page-global facade: queues early bundle registrations, then registers them live. */
+export interface ClientModuleLoaderTarget {
+    /** Queue before {@link create}; live registration after it returns. */
+    mode: 'queue' | 'live';
+    /** Registrations submitted by parser-preloaded scripts before the module system exists. */
+    pendingQueue: ClientBundleRegistration[];
+    /** Queue or immediately register one bundle factory according to {@link mode}. */
+    load(registration: ClientBundleRegistration): void;
+    /** Create the module system exactly once from the parser-preloaded modules bundle. */
+    create(options: ClientModuleCreateOptions): ClientModuleSystem;
+}
+/** Window API of the web boot protocol: the host-injected graph and registration facade. */
 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;
+    /** HTML-installed facade: a pending registration queue, then the live module-system target. */
+    __ModuleLoader__?: ClientModuleLoaderTarget;
 }
 /** 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). */
+    /** Materialized exports (`module.exports` from a factory or bootstrap registration). */
     exports: unknown;
     /** Owned `<style data-plugin>` tag ids (`data-plugin-css` values) injected during materialization. */
     styles: string[];
@@ -143,6 +190,8 @@ export interface ClientModuleRecord {
 export interface ClientModuleLoader {
     /** Discriminant against Node's internal loader shapes ('v1'/'v2'). */
     version: 'client';
+    /** Parsed Host boot graph shared with the web entry after module-system creation. */
+    manifest: BootManifest;
     /** Materialized-module registry: id → record. The governance-side read API for entry exports. */
     loadCache: Map<string, ClientModuleRecord>;
     /**
@@ -156,34 +205,34 @@ export interface ClientModuleLoader {
      */
     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.
+     * Stage-one arrival: load the entry's declared dynamic requests, then its
+     * own script, to register their factories (no materialization — module side
+     * effects wait for import).
+     * No-op for materialized bootstrap ids. A registered graph row still
+     * registers any unresolved declared requests before skipping its own script;
+     * concurrent arrivals 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).
+     * Full reset of one non-bootstrap module: drop its registered factory and
+     * materialized record so the next prefetch/import reloads it (the HMR
+     * invalidation hook). The bootstrap module remains materialized.
      * @param id - entry name to invalidate.
      */
     invalidate(id: string): void;
 }
-/** Options for {@link ClientModuleSystem} (assembled by the web shell kernel at boot). */
+/** Internal construction inputs assembled by the modules bundle's bootstrap export. */
 export interface ClientModuleSystemOptions {
-    /** Boot rows in the module-table view (from {@link parseBootManifest}). */
-    modules: BootModuleRow[];
+    /** Parsed boot graph owned by the resulting module system. */
+    manifest: BootManifest;
     /** Module-table seed: platform-singleton specifier → shell instance. */
     staticModules: Record<string, unknown>;
+    /** Stable HTML-installed registration facade to switch from queue to live mode. */
+    registrationTarget: ClientModuleLoaderTarget;
+    /** Already-materialized modules bundle consumed while creating the system. */
+    bootstrapModule: ClientBootstrapModule;
     /** Bundle-load hook. Defaults to a same-origin classic `<script src>` element. */
     loadBundle?: (url: string) => Promise<void>;
 }

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

@@ -1,22 +1,18 @@
-/**
- * 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';
+import type { BootManifest, 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.
+ * contract documentation). Construction indexes the boot rows, retains the
+ * already-materialized bootstrap module, and switches the HTML-installed
+ * loader facade from its pending queue to live registration.
  */
 export declare class ClientModuleSystem implements ClientModuleLoader {
     readonly version = "client";
+    readonly manifest: BootManifest;
     readonly loadCache: Map<string, ClientModuleRecord>;
     private readonly seed;
-    private readonly statics;
     private readonly factories;
+    private readonly bootstrapIds;
     /** 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. */
@@ -25,23 +21,25 @@ export declare class ClientModuleSystem implements ClientModuleLoader {
     private readonly loadBundle;
     /**
      * Build the module system over the parsed boot rows.
-     * @param options - Module rows, module-table staticModules, and bundle-load hook.
+     * @param options - Parsed graph, platform seed, bootstrap module, registration facade, and transport.
      */
     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). */
     private arrive;
+    /** Register each unresolved dynamic request before registering its consumer. */
+    private arriveGraphRow;
     /** 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).
+     * The synchronous require answered to factories: seed → memoized record →
+     * registered factory. Fetching is async and therefore unreachable
+     * from here; an external dynamic package must have arrived before its
+     * consumer materializes.
      */
     private makeRequire;
     import(specifier: string): Promise<unknown>;
-    registerStatic(id: string, module: unknown): void;
     prefetch(id: string): Promise<void>;
     invalidate(id: string): void;
 }

package/lib/types/index.d.ts

@@ -2,10 +2,11 @@
  * 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).
+ * in `./client/manifest.ts`) in module-graph order, serves
+ * `/plugins/<id>/client.js` and its source map, contributes the boot manifest
+ * plus the parser-blocking bootstrap preloads to the webserver's index
+ * injection table, 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
@@ -21,7 +22,9 @@
  */
 import { Service } from '@deepseek-ai/cordis';
 import type { Context } from '@deepseek-ai/cordis';
-import type { WebBootGraph } from './client/manifest.ts';
+import type { IndexInjection } from '@deepseek-ai/dsh-host-webserver';
+import type { WebBootEntry, WebBootGraph } from './client/manifest.ts';
+export { stripClientSuffix } from './client/manifest.ts';
 export type { BootManifest, BootModuleRow, BootPluginRow, WebBootEntry, WebBootGraph, } from './client/manifest.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -30,17 +33,30 @@ declare module '@deepseek-ai/cordis' {
     }
 }
 /**
- * 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.
+ * Order composed rows so every requested dynamic package precedes its
+ * consumers. An `external` specifier is either the package row it names
+ * (`<pkg>/client` aliases the bare package) or a static-table name that adds no
+ * graph edge.
+ * @param entries - composed rows in scan order.
+ * @returns the same rows reordered; scan order breaks every tie.
+ * @throws {Error} when a row requests itself or when the module graph has a
+ * cycle; the message lists the packages on it.
+ */
+export declare function orderByModuleGraph(entries: readonly WebBootEntry[]): WebBootEntry[];
+/**
+ * The boot protocol as index injection rows. The inline registration queue
+ * precedes blocking classic scripts for modules' and runtime's ordinary
+ * `lib/client.js` artifacts. Its `create()` method materializes the modules
+ * bundle, delegates construction to that bundle, and leaves the same facade
+ * in live-registration mode. The graph global follows before the shell reads
+ * it.
  * @param graph - the composed entry graph.
- * @returns the html with the graph script injected.
+ * @returns head rows in execution order: queue script, preload scripts, graph global.
  */
-export declare function injectBootManifest(html: string, graph: WebBootGraph): string;
+export declare function bootInjections(graph: WebBootGraph): IndexInjection[];
 /**
  * The web plugin table service: incremental `dsh.client` scan + wire composition
- * + bundle route + index tap. Construction runs the activation scan
+ * + bundle route + index injection rows. 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).

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.0-rc.7",
+  "version": "0.1.1-rc.1",
   "publishConfig": {
     "access": "public"
   },
@@ -39,8 +39,8 @@
   "license": "MIT",
   "devDependencies": {
     "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.7",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.7",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.1",
     "@deepseek-ai/cordis": "^4.0.1"
   },
   "files": [
@@ -50,8 +50,10 @@
     "lib/types/**/*.d.ts"
   ],
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.7",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.1-rc.1"
   },
   "scripts": {
     "bundle": "tsdown",