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

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

@@ -0,0 +1,239 @@
+/**
+ * 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.
+ */
+import type { ClientModuleSystem } from './system.ts';
+declare module '@hydraharness/cordis' {
+    interface Context {
+        /** The client module system the web shell builds at boot (provided by the `./client` wrapper plugin). */
+        modules: ClientModuleLoader;
+    }
+}
+/**
+ * One composed client entry pushed by the host (a graph row). Wire
+ * single source: the host node half (package root) produces this same shape.
+ * `immediately` marks stage-one prefetch; `inject` is informational graph
+ * metadata (the authoritative edges live in each package's `hydra.client`
+ * 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. */
+    id: string;
+    /** Bundle endpoint, '/plugins/<id>/client.js?rev=<rev>'. */
+    url: string;
+    /** Bundle content hash (cache-busting consistency anchor). */
+    rev: string;
+    /** Package-name dependency edges, informational (preflight display / HMR diffing). */
+    inject?: string[];
+    /** Stage-one prefetch mark: load the script for factory registration during module-face boot. */
+    immediately?: boolean;
+    /** Non-baseline module specifiers this row requests; omitted when it requests none. */
+    external?: string[];
+}
+/** The composed client entry graph the host injects as `window.__HYDRA_BOOT__`. */
+export interface WebBootGraph {
+    /** Consistency anchor over the whole graph (content + bundle hashes). */
+    rev: string;
+    /**
+     * 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. */
+export interface BootModuleRow {
+    /** Entry name == package name (module-table key). */
+    id: string;
+    /** Bundle endpoint, '/plugins/<id>/client.js?rev=<rev>'. */
+    url: string;
+    /** Bundle content hash. */
+    rev: string;
+    /** 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 {
+    /** Entry name == package name. */
+    id: string;
+    /** Package-name dependency edges ([] when the wire omits them). */
+    inject: string[];
+    /** Stage-one prefetch tier (false when the wire omits it). */
+    immediately: boolean;
+}
+/** The parsed boot manifest: one wire, two consumer views. */
+export interface BootManifest {
+    /** Consistency anchor over the whole graph. */
+    rev: string;
+    /** Rows as the module table consumes them. */
+    modules: BootModuleRow[];
+    /** Rows as entry composition consumes them. */
+    plugins: BootPluginRow[];
+}
+/**
+ * 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.
+ */
+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.__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.
+ */
+export declare function parseBootManifest(wire: unknown): BootManifest;
+/** 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;
+    /**
+     * Closure factory holding the whole bundle body: receives the synchronous
+     * require bound to the module table and returns the bundle's exports. Runs
+     * once, at materialization.
+     */
+    factory: (require: (spec: string) => unknown) => Record<string, unknown>;
+}
+/** 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 HydraWindow {
+    /** Host-composed entry graph, injected before the shell bundle runs; wire-boundary raw until {@link parseBootManifest}. */
+    __HYDRA_BOOT__?: unknown;
+    /** 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 bootstrap registration). */
+    exports: unknown;
+    /** Owned `<style data-plugin>` tag ids (`data-plugin-css` values) injected during materialization. */
+    styles: string[];
+    /** Observed `require()` edges (module-graph boundary; only table words can appear today). */
+    edges: Set<string>;
+}
+/**
+ * The internal-contract subset the vendored Loader and the client HMR plugin
+ * consume. Mounted on `ctx.loader.internal` by the shell boot and provided
+ * as `ctx.modules`.
+ */
+export interface ClientModuleLoader {
+    /** Discriminant against Node's internal loader shapes ('v1'/'v2'). */
+    version: 'client';
+    /** 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>;
+    /**
+     * Internal contract consumed by the vendored Loader's `tree.import`. Resolves
+     * `specifier` through the branch order documented on the module, fetching
+     * and executing a bundle when needed.
+     * @param specifier - module specifier (entry name or table word).
+     * @param parentURL - importer URL (unused — the client module graph is flat).
+     * @param attrs - Import attributes (unused; interface parity with Node's loader contract).
+     * @returns the module's exports.
+     */
+    import(specifier: string, parentURL: string, attrs: Record<string, unknown>): Promise<unknown>;
+    /**
+     * 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 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;
+}
+/** Internal construction inputs assembled by the modules bundle's bootstrap export. */
+export interface ClientModuleSystemOptions {
+    /** 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>;
+}
+//# sourceMappingURL=manifest.d.ts.map

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

@@ -0,0 +1,46 @@
+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, 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 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. */
+    private readonly materializing;
+    private readonly graphRows;
+    private readonly loadBundle;
+    /**
+     * Build the module system over the parsed boot rows.
+     * @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 → 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>;
+    prefetch(id: string): Promise<void>;
+    invalidate(id: string): void;
+}
+//# sourceMappingURL=system.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Node half of the client module system (`hydra.client` dual-face package): scans
+ * the host Loader's entries for packages declaring `hydra.client`, composes the
+ * `window.__HYDRA_BOOT__` entry graph (wire single source: {@link WebBootEntry}
+ * 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
+ * the fiber's entry name dirty; a microtask flush reconciles each dirty name
+ * against the live loader entries. The activation pass seeds the same dirty
+ * set with all current entries and flushes synchronously, so first scan and
+ * steady state share one implementation. Package metadata (including the
+ * negative "not a client package" verdict) is cached per name and never
+ * expires — plugin-set changes take effect on restart; bundle content
+ * changes reach the graph only through
+ * {@link ClientModuleRegistry.rebuilt}.
+ * @module @hydraharness/harness-client-modules
+ */
+import { Service } from '@hydraharness/cordis';
+import type { Context } from '@hydraharness/cordis';
+import type { IndexInjection } from '@hydraharness/harness-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 '@hydraharness/cordis' {
+    interface Context {
+        /** The web plugin table (provided by the client-modules node half). */
+        clientModules: ClientModuleRegistry;
+    }
+}
+/**
+ * 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 head rows in execution order: queue script, preload scripts, graph global.
+ */
+export declare function bootInjections(graph: WebBootGraph): IndexInjection[];
+/**
+ * The web plugin table service: incremental `hydra.client` scan + wire composition
+ * + 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).
+ */
+export declare class ClientModuleRegistry extends Service {
+    static inject: string[];
+    private readonly table;
+    private readonly pkgMeta;
+    private readonly rebuildListeners;
+    private readonly graphListeners;
+    private readonly dirty;
+    private readonly resolvePkgJson;
+    private flushQueued;
+    private composed;
+    /**
+     * Build the service: subscribe, seed, and run the activation flush.
+     * @param ctx - plugin context carrying webServer and loader.
+     */
+    constructor(ctx: Context);
+    /**
+     * Current composed entry graph (stable object between changes).
+     * @returns the graph served as `window.__HYDRA_BOOT__`.
+     */
+    graph(): WebBootGraph;
+    /**
+     * Absolute path of an entry's client bundle.
+     * @param id - entry id (package name).
+     * @returns the path, or undefined for an unknown id.
+     */
+    clientPath(id: string): string | undefined;
+    /**
+     * Re-hash one bundle (the HMR watch's registration hook — the only entry
+     * point through which bundle content changes reach the graph).
+     * @param id - entry id (package name).
+     * @returns the new rev, or undefined for an unknown id.
+     */
+    rebuilt(id: string): string | undefined;
+    /**
+     * Subscribe to bundle rebuilds; fires only when the re-hash changed the rev.
+     * @param listener - receives the entry id and its new bundle rev.
+     * @returns the unsubscriber.
+     */
+    onRebuilt(listener: (id: string, rev: string) => void): () => void;
+    /**
+     * Fires after any flush that recomposed the graph (row added/removed, or a
+     * rebuilt rev change). Pull model: listeners re-read {@link graph}.
+     * @param listener - notified with no payload.
+     * @returns the unsubscriber.
+     */
+    onGraphChanged(listener: () => void): () => void;
+    private compose;
+    private notifyGraphChanged;
+    private resolveMeta;
+    /**
+     * Read the activation-time bundle revision.
+     * @param pkgName - package that declares the client bundle.
+     * @param clientPath - absolute path of the built client artifact.
+     * @returns the bundle content's short hash for use as its revision.
+     * @throws {MissingClientBundleError} when the read fails with `ENOENT`; other filesystem errors are rethrown unchanged.
+     */
+    private initialBundleRevision;
+    /** Reconcile one entry name against the live loader entries. @returns whether the table changed. */
+    private processOne;
+    private flush;
+    private readonly serveBundle;
+}
+export default ClientModuleRegistry;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

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

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@hydraharness/harness-client-modules",
+  "description": "Client module system, dual-face: node half composes the __HYDRA_BOOT__ entry graph (incremental hydra.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.1-rc.6",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MaiHongPhong1902/Hydra-Harness.git",
+    "directory": "packages/client/modules"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "hydra": {
+    "plugin": {
+      "application": "Load the browser plugins declared by the active profile and serve their built code."
+    },
+    "client": {
+      "platform": "web",
+      "inject": [],
+      "immediately": true
+    }
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@hydraharness/harness-host-webserver": "^0.1.1-rc.6",
+    "@hydraharness/cordis-plugin-loader": "^1.0.3",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/cordis": "^4.0.2"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "peerDependencies": {
+    "@hydraharness/cordis": "^4.0.2",
+    "@hydraharness/harness-invariants": "^0.1.1-rc.6",
+    "@hydraharness/cordis-plugin-loader": "^1.0.3",
+    "@hydraharness/harness-host-webserver": "^0.1.1-rc.6"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}