@hydraharness/harness-client-modules 0.1.1-rc.6

package/LICENSE

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

package/README.md

@@ -0,0 +1,26 @@
+# @hydraharness/harness-client-modules
+
+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; 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).
+
+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.
+
+Resolution branch order (`import(specifier)`): platform seed word → shell instance; memoized record → exports; graph row (`window.__HYDRA_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 `hydra.client` packages, resolves each `exports["./client"]`, hashes the built bundle into the boot graph, carries package-specific `hydra.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.
+
+`hydra.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
+
+None, as the module loader is browser-side kernel machinery; nothing here reaches a model request.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Flat module graph by design** — every bundle is one module node whose edges point only at table leaves; the interface (`loadCache`/`edges`/`invalidate`) already supports a general module graph, so the externalization granularity can change without an interface change.
+- **No unload bookkeeping of its own** — style removal and fiber teardown ordering live with the HMR driver (`@hydraharness/harness-client-hmr`); the loader only inventories owned style tag ids per record.

package/lib/client.js

@@ -0,0 +1,324 @@
+window.__ModuleLoader__.load({
+	id: "@hydraharness/harness-client-modules",
+	factory: (require) => {
+		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
+		* `__HYDRA_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 `hydra.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.__HYDRA_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.__HYDRA_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.__HYDRA_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");
+			el.async = true;
+			el.src = url;
+			el.addEventListener("load", () => {
+				el.remove();
+				resolve();
+			}, { once: true });
+			el.addEventListener("error", () => {
+				el.remove();
+				reject(/* @__PURE__ */ new Error(`client-modules: bundle script ${url} failed to load`));
+			}, { once: true });
+			document.head.append(el);
+		});
+		/**
+		* Claim and inventory the <style> tags a factory injected during
+		* materialization: preset-emitted tags arrive pre-tagged with data-plugin;
+		* any untagged tag is claimed for the materializing plugin (HMR bookkeeping).
+		*/
+		const claimStyles = (id) => {
+			if (typeof document === "undefined") return [];
+			for (const el of document.querySelectorAll("style:not([data-plugin])")) el.setAttribute("data-plugin", id);
+			const owned = [];
+			for (const el of document.querySelectorAll(`style[data-plugin=${JSON.stringify(id)}]`)) owned.push(el.getAttribute("data-plugin-css") ?? id);
+			return owned;
+		};
+		/**
+		* The client module system: state tables plus the arrival/materialization
+		* machinery implementing {@link ClientModuleLoader} (whose members carry the
+		* contract documentation). Construction indexes the boot rows, 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;
+			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. */
+			materializing = /* @__PURE__ */ new Set();
+			graphRows = /* @__PURE__ */ new Map();
+			loadBundle;
+			/**
+			* Build the module system over the parsed boot rows.
+			* @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.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 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.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(() => {
+					this.pendingArrival.delete(id);
+				});
+				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);
+				if (existing !== void 0) return existing;
+				const registered = this.factories.get(id);
+				/* v8 ignore next -- callers check the factory branch before dispatching here. */
+				if (registered === void 0) throw new Error(`client-modules: no registered factory for "${id}"`);
+				if (this.materializing.has(id)) throw new Error(`client-modules: require cycle through "${id}" (factory-form CJS cannot deliver partial exports)`);
+				this.materializing.add(id);
+				try {
+					const edges = /* @__PURE__ */ new Set();
+					const record = {
+						id,
+						exports: registered(this.makeRequire(edges)),
+						styles: claimStyles(id),
+						edges
+					};
+					this.loadCache.set(id, record);
+					return record;
+				} finally {
+					this.materializing.delete(id);
+				}
+			}
+			/**
+			* The synchronous require answered to factories: seed → 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);
+					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 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 id = stripClientSuffix(specifier);
+				const existing = this.loadCache.get(id);
+				if (existing !== void 0) return existing.exports;
+				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) {
+				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.arriveGraphRow(row);
+			}
+			invalidate(id) {
+				const normalized = stripClientSuffix(id);
+				if (this.bootstrapIds.has(normalized)) return;
+				this.factories.delete(normalized);
+				this.loadCache.delete(normalized);
+			}
+		};
+		//#endregion
+		//#region lib/types/client/index.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.
+		*/
+		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;
+		}
+		/**
+		* Enroll the kernel-built module system as `ctx.modules`.
+		* @param ctx - client root context.
+		*/
+		function apply(ctx) {
+			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;
+	}
+});
+
+//# sourceMappingURL=client.js.map