@deepseek-ai/dsh-client-modules 0.1.1-rc.2 → 0.1.2-alpha.3

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

@@ -38,26 +38,38 @@ declare module '@deepseek-ai/cordis' {
 /**
  * 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 `dsh.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}).
+ * `immediately` marks stage-one prefetch. `inject` names package rows whose
+ * factories must arrive before this row materializes, while Cordis separately
+ * uses the same package edges to compose entries. `external` carries exact
+ * non-inject module requests (see {@link WebBootGraph.entries}).
  */
 export interface WebBootEntry {
     /** Entry name == package name. */
     id: string;
-    /** Bundle endpoint, '/plugins/<id>/client.js?rev=<rev>'. */
+    /** Revisioned single-resource combo endpoint used by HMR. */
     url: string;
-    /** Bundle content hash (cache-busting consistency anchor). */
+    /** Opaque plugin-artifact revision used for HMR cache busting. */
     rev: string;
-    /** Package-name dependency edges, informational (preflight display / HMR diffing). */
+    /** Package-name dependency edges used for factory arrival and plugin composition. */
     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[];
 }
+/** Initial scheduling phase for one content-addressed combo script. */
+export type WebBootBatchPhase = 'bootstrap' | 'application';
+/** One initial combo script; a scheduling phase may span several descriptors. */
+export interface WebBootBatch {
+    /** Parser-blocking bootstrap or preloaded application scheduling. */
+    phase: WebBootBatchPhase;
+    /** Content-addressed combo script endpoint. */
+    url: string;
+    /** Revision over the combined plugin script bytes and indexed source map. */
+    rev: string;
+    /** Graph entry ids whose factories the script registers, in execution order. */
+    entries: string[];
+}
 /** The composed client entry graph the host injects as `window.__DSH_BOOT__`. */
 export interface WebBootGraph {
     /** Consistency anchor over the whole graph (content + bundle hashes). */
@@ -68,15 +80,21 @@ export interface WebBootGraph {
      * unrelated and remains owned by fiber service waiting.
      */
     entries: WebBootEntry[];
+    /** Initial combo descriptors; every entry belongs to exactly one descriptor. */
+    batches: WebBootBatch[];
 }
 /** 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>'. */
+    /** Revisioned single-resource combo endpoint used after HMR invalidation. */
     url: string;
-    /** Bundle content hash. */
+    /** Content-addressed combo endpoint used before the first HMR invalidation. */
+    initialUrl: string;
+    /** Opaque plugin-artifact revision used after HMR invalidation. */
     rev: string;
+    /** Injected package rows whose factories arrive before this row materializes. */
+    inject: string[];
     /** Module specifiers this row requests from the module table ([] when the wire omits them). */
     external: string[];
 }
@@ -171,7 +189,7 @@ export interface DshWindow {
     /** 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). */
+/** Per-module bookkeeping in {@link ClientModuleLoader.loadCache} (flat module-graph boundary). */
 export interface ClientModuleRecord {
     /** Module id (entry name / package name). */
     id: string;
@@ -179,7 +197,7 @@ export interface ClientModuleRecord {
     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). */
+    /** Observed `require()` edges (module-graph boundary; only table words can appear). */
     edges: Set<string>;
 }
 /**
@@ -217,11 +235,14 @@ export interface ClientModuleLoader {
     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.
+     * materialized record so the next prefetch/import loads its one-resource
+     * combo script rather than the initial multi-resource request. The bootstrap
+     * module remains materialized.
      * @param id - entry name to invalidate.
+     * @param rev - New content revision from the HMR frame; omitted to reuse
+     * the graph revision or for page-local modules that register directly.
      */
-    invalidate(id: string): void;
+    invalidate(id: string, rev?: string): void;
 }
 /** Internal construction inputs assembled by the modules bundle's bootstrap export. */
 export interface ClientModuleSystemOptions {

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

@@ -13,8 +13,10 @@ export declare class ClientModuleSystem implements ClientModuleLoader {
     private readonly seed;
     private readonly factories;
     private readonly bootstrapIds;
-    /** In-flight prefetch (script load) per id; concurrent callers share it. */
+    /** In-flight script transport per URL; every row in one batch shares it. */
     private readonly pendingArrival;
+    /** Single-resource combo URL selected by HMR after invalidating one row. */
+    private readonly reloadUrls;
     /** Materialization re-entrancy guard: factory-form CJS cannot deliver partial exports, so a cycle is fatal. */
     private readonly materializing;
     private readonly graphRows;
@@ -28,7 +30,7 @@ export declare class ClientModuleSystem implements ClientModuleLoader {
     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. */
+    /** Register each injected package and unresolved dynamic request before its consumer. */
     private arriveGraphRow;
     /** Materialize a registered factory (synchronous; memoized in loadCache). */
     private materialize;
@@ -41,6 +43,6 @@ export declare class ClientModuleSystem implements ClientModuleLoader {
     private makeRequire;
     import(specifier: string): Promise<unknown>;
     prefetch(id: string): Promise<void>;
-    invalidate(id: string): void;
+    invalidate(id: string, rev?: string): void;
 }
 //# sourceMappingURL=system.d.ts.map

package/lib/types/index.d.ts

@@ -2,11 +2,12 @@
  * Node half of the client module system (`dsh.client` dual-face package): scans
  * the host Loader's entries for packages declaring `dsh.client`, composes the
  * `window.__DSH_BOOT__` entry graph (wire single source: {@link WebBootEntry}
- * in `./client/manifest.ts`) 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).
+ * in `./client/manifest.ts`) in module-graph order, serves one-or-more-plugin
+ * combo scripts plus their source maps,
+ * contributes the registration facade, application preloads, bootstrap scripts,
+ * and graph 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
@@ -14,9 +15,10 @@
  * 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
+ * negative "not a client package" verdict) is cached per Loader specifier and
+ * owning-tree base URL until restart. The manifest package name identifies
+ * the browser module; distinct active Loader sources for that package are a
+ * composition error. Bundle content changes reach the graph only through
  * {@link ClientModuleRegistry.rebuilt}.
  * @module @deepseek-ai/dsh-client-modules
  */
@@ -25,13 +27,22 @@ import type { Context } from '@deepseek-ai/cordis';
 import type { IndexInjection } from '@deepseek-ai/dsh-host-webserver';
 import type { WebBootEntry, WebBootGraph } from './client/manifest.ts';
 export { stripClientSuffix } from './client/manifest.ts';
-export type { BootManifest, BootModuleRow, BootPluginRow, WebBootEntry, WebBootGraph, } from './client/manifest.ts';
+export type { BootManifest, BootModuleRow, BootPluginRow, WebBootBatch, WebBootBatchPhase, WebBootEntry, WebBootGraph, } from './client/manifest.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         /** The web plugin table (provided by the client-modules node half). */
         clientModules: ClientModuleRegistry;
     }
 }
+/** Filesystem baseline captured before a client artifact snapshot is read. */
+export interface ClientArtifactBaseline {
+    /** Absolute path of the client bundle. */
+    readonly path: string;
+    /** Bundle modification time in milliseconds. */
+    readonly mtimeMs: number;
+    /** Bundle size in bytes. */
+    readonly size: number;
+}
 /**
  * Order composed rows so every requested dynamic package precedes its
  * consumers. An `external` specifier is either the package row it names
@@ -45,13 +56,14 @@ declare module '@deepseek-ai/cordis' {
 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
+ * precedes the application-batch preload and the blocking bootstrap batch. 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.
+ * @returns head rows in execution order: queue script, application preloads,
+ * blocking bootstrap scripts, graph global.
  */
 export declare function bootInjections(graph: WebBootGraph): IndexInjection[];
 /**
@@ -64,11 +76,17 @@ export declare function bootInjections(graph: WebBootGraph): IndexInjection[];
 export declare class ClientModuleRegistry extends Service {
     static inject: string[];
     private readonly table;
+    private readonly sources;
     private readonly pkgMeta;
     private readonly rebuildListeners;
     private readonly graphListeners;
     private readonly dirty;
-    private readonly resolvePkgJson;
+    private readonly initialRevisionNonce;
+    private nextInitialRevision;
+    private responses;
+    private batchResponses;
+    /** One prior graph generation covers a request racing the HMR recomposition that replaced its URL. */
+    private previousBatchResponses;
     private flushQueued;
     private composed;
     /**
@@ -87,6 +105,15 @@ export declare class ClientModuleRegistry extends Service {
      * @returns the path, or undefined for an unknown id.
      */
     clientPath(id: string): string | undefined;
+    /**
+     * Filesystem baseline captured before an entry's current bytes were read.
+     * HMR compares it with the live files when installing a watch, so a write
+     * between startup composition and watch installation cannot disappear into
+     * the watcher's initial state.
+     * @param id - entry id (package name).
+     * @returns the path and baseline, or undefined for an unknown id.
+     */
+    artifactBaseline(id: string): ClientArtifactBaseline | undefined;
     /**
      * Re-hash one bundle (the HMR watch's registration hook — the only entry
      * point through which bundle content changes reach the graph).
@@ -111,15 +138,37 @@ export declare class ClientModuleRegistry extends Service {
     private notifyGraphChanged;
     private resolveMeta;
     /**
-     * Read the activation-time bundle revision.
+     * Locate the manifest of the package the Loader mounts for a row. The row's
+     * module location is authoritative: the specifier resolves through the same
+     * Loader resolution that imported the row's host half — including any
+     * active ESM hooks — and the nearest ancestor manifest declaring the name
+     * owns the module. Tree-anchored `require` resolution remains only for
+     * runtimes without Node internals.
+     * @param loaderName - module specifier of the loader row.
+     * @param baseUrl - resolution base of the tree that owns the row.
+     * @returns the manifest path, or `undefined` when the name resolves to no package root.
+     */
+    private locatePkgJson;
+    private nearestPackage;
+    private sourceKey;
+    /** Capture the bundle stats before reading its bytes. */
+    private captureArtifactBaseline;
+    /** Allocate an opaque initial row revision without inspecting artifact bytes. */
+    private allocateInitialRevision;
+    /**
+     * Read the activation-time bundle and optional source-map snapshots.
      * @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.
+     * @returns the immutable bytes plus the pre-read filesystem baseline.
      * @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 initialBundleSnapshot;
+    /** Treat a missing, torn, or malformed development map as an identity-mapped artifact revision. */
+    private readSourceMapSnapshot;
+    /** Reconcile one entry name against the live Loader sources. @returns whether the table changed. */
     private processOne;
+    private resolveSource;
+    private reconcilePackage;
     private flush;
     private readonly serveBundle;
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-modules",
   "description": "Client module system, dual-face: node half composes the __DSH_BOOT__ entry graph (incremental dsh.client scan, bundle route, index tap, webPlugins service); browser half is the lazy-CJS module table the vendored cordis Loader consumes as its internal seam",
-  "version": "0.1.1-rc.2",
+  "version": "0.1.2-alpha.3",
   "publishConfig": {
     "access": "public"
   },
@@ -38,10 +38,10 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.2-alpha.3",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.3",
+    "@deepseek-ai/cordis": "^4.0.2"
   },
   "files": [
     "lib/index.js",
@@ -50,10 +50,7 @@
     "lib/types/**/*.d.ts"
   ],
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.1-rc.2"
+    "@deepseek-ai/cordis": "^4.0.2"
   },
   "scripts": {
     "bundle": "tsdown",