@nomix-ai/nomix-harness 0.2.5 → 0.2.6

package/dist/kernel/client-modules/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
+		* `__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;
+		}
+		/**
+		* Parse `window.__NOMIX_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.__NOMIX_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.__NOMIX_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
-		* `__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.
-		*/
+		//#region lib/types/client/index.js
+		let moduleSystem;
 		/**
-		* Parse `window.__NOMIX_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.__NOMIX_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.__NOMIX_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.__NOMIX_MODULES__;
-			if (modules === void 0) throw new Error("client-modules: window.__NOMIX_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;
 	}
 });