@nomix-ai/nomix-harness 0.2.4 → 0.2.6

package/dist/kernel/client-modules/lib/index.js

@@ -3,16 +3,75 @@ 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 "@nomix-ai/cordis";
+import { Service } from "../../cordis/lib/index.js";
+//#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
+* `__NOMIX_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 `nomix.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 (`nomix.client` dual-face package): scans
 * the host Loader's entries for packages declaring `nomix.client`, composes the
 * `window.__NOMIX_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 parseNomixClient(pkgName, value) {
 	if (typeof value !== "object" || value === null) throw new Error(`client-modules: ${pkgName} has a non-object nomix.client declaration`);
 	const decl = value;
 	if (typeof decl.platform !== "string") throw new Error(`client-modules: ${pkgName} nomix.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} nomix.client.inject must be a string array`);
+	const inject = optionalStringArray(pkgName, "nomix.client.inject", decl.inject);
+	const external = optionalStringArray(pkgName, "nomix.client.external", decl.external);
 	if (decl.immediately !== void 0 && typeof decl.immediately !== "boolean") throw new Error(`client-modules: ${pkgName} nomix.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.__NOMIX_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 nomix.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 = "@nomix-ai/nomix-client-modules";
+/** Ordinary dynamic bundles the HTML parser executes before the Vite shell. */
+const PARSER_PRELOAD_IDS = [CLIENT_MODULES_ID, "@nomix-ai/nomix-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.__NOMIX_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: "__NOMIX_BOOT__",
+			value: graph
+		}
+	];
 }
 /**
 * The web plugin table service: incremental `nomix.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/dist/kernel/client-modules/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 @nomix-ai/nomix-client-modules/client
  */
-import type { Context } from '@nomix-ai/cordis';
-export { ClientModuleSystem } from './system.ts';
-export { parseBootManifest } from './manifest.ts';
-export type { BootManifest, BootModuleRow, BootPluginRow, ClientModuleLoader, ClientModuleRecord, ClientModuleSystemOptions, ClientPluginHandoff, NomixWindow, WebBootEntry, WebBootGraph, } from './manifest.ts';
+import type { Context } from '../../../../cordis/lib/index.js';
+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, NomixWindow, 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/dist/kernel/client-modules/lib/types/client/index.js

@@ -1,16 +1,33 @@
-export { ClientModuleSystem } from "./system.js";
-export { parseBootManifest } from "./manifest.js";
+import { ClientModuleSystem } from "./system.js";
+import { parseBootManifest } from "./manifest.js";
+export { ClientModuleSystem };
+export { parseBootManifest, stripClientSuffix } from "./manifest.js";
+let moduleSystem;
+/**
+ * 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 function createClientModuleSystem(target, bootstrapModule, options) {
+    moduleSystem = new ClientModuleSystem({
+        manifest: parseBootManifest(options.boot),
+        staticModules: options.staticModules,
+        registrationTarget: target,
+        bootstrapModule,
+        ...(options.loadBundle === undefined ? {} : { loadBundle: options.loadBundle }),
+    });
+    return moduleSystem;
+}
 /**
  * Enroll the kernel-built module system as `ctx.modules`.
  * @param ctx - client root context.
  */
 export function apply(ctx) {
-    const modules = globalThis.__NOMIX_MODULES__;
-    // The kernel writes the slot right after constructing the instance, before
-    // any cordis entry exists — a missing slot means the kernel sequencing broke.
-    if (modules === undefined) {
-        throw new Error('client-modules: window.__NOMIX_MODULES__ missing — the shell kernel must construct the module system before plugin boot');
+    if (moduleSystem === undefined) {
+        throw new Error('client-modules: createClientModuleSystem must run before plugin boot');
     }
-    ctx.reflect.provide('modules', modules);
+    ctx.reflect.provide('modules', moduleSystem);
 }
 //# sourceMappingURL=index.js.map

package/dist/kernel/client-modules/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
  * `__NOMIX_BOOT__` wire types, the boot-manifest parser, and the boundaries around
@@ -41,7 +40,9 @@ declare module '@nomix-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 `nomix.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.__NOMIX_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 `nomix.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.__NOMIX_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 NomixWindow {
     /** Host-composed entry graph, injected before the shell bundle runs; wire-boundary raw until {@link parseBootManifest}. */
     __NOMIX_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.
-     */
-    __NOMIX_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>;
 }