@deepseek-ai/dsh-client-modules 0.1.5-rc.2 → 0.1.6-alpha.2

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

@@ -28,6 +28,8 @@
  * {@link ClientModuleSystem}. The package root is the host-side service that
  * composes the wire.
  */
+import type { DshClientManifest } from '@deepseek-ai/dsh-package-manifest';
+import type { ClientEntries } from './entries.ts';
 import type { ClientModuleSystem } from './system.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
@@ -57,22 +59,22 @@ export interface WebBootEntry {
     /** Non-baseline module specifiers this row requests; omitted when it requests none. */
     external?: string[];
 }
-/** Initial scheduling phase for one content-addressed combo script. */
+/** Initial scheduling phase for one revisioned 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. */
+    /** Revisioned combo script endpoint. */
     url: string;
-    /** Revision over the combined plugin script bytes and indexed source map. */
+    /** Revision derived from the ordered entry revisions. */
     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). */
+    /** Consistency anchor over the current entry and batch descriptors. */
     rev: string;
     /**
      * Composed entries in module-graph order — a dynamic package row precedes
@@ -89,7 +91,7 @@ export interface BootModuleRow {
     id: string;
     /** Revisioned single-resource combo endpoint used after HMR invalidation. */
     url: string;
-    /** Content-addressed combo endpoint used before the first HMR invalidation. */
+    /** Revisioned combo endpoint used before the first HMR invalidation. */
     initialUrl: string;
     /** Opaque plugin-artifact revision used after HMR invalidation. */
     rev: string;
@@ -126,6 +128,23 @@ export interface BootManifest {
  * @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;
+/**
+ * Narrow an unknown parsed JSON value to the `dsh.client` declaration. Shared
+ * by the node half's Loader scan and the roster generator, so both read a
+ * package's browser declaration through one validator.
+ * @param pkgName - package name used as the diagnostic prefix.
+ * @param value - the raw `dsh.client` field of the package manifest.
+ * @returns the validated declaration, or undefined when the field is absent.
+ * @throws {Error} when the field is present but any member is malformed.
+ */
+export declare function parseDshClient(pkgName: string, value: unknown): DshClientManifest | undefined;
+/**
+ * The bare package-root specifier `specifier` names, or undefined for a subpath, a path, or any scheme-qualified
+ * specifier (`cordis:` builtins, `node:` modules, URLs).
+ * @param specifier - Loader row name.
+ * @returns the package name, or undefined.
+ */
+export declare function exactPackageSpecifier(specifier: string): 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
@@ -144,16 +163,25 @@ export declare function stripClientSuffix(spec: string): string;
  * @returns the manifest with optional plugin-view fields normalized.
  */
 export declare function parseBootManifest(wire: unknown): BootManifest;
+/** Module resolver passed into a registered Client bundle factory. */
+export interface ClientBundleRequire {
+    /** Resolve a module-table dependency synchronously. */
+    (specifier: string): unknown;
+    /** Load and resolve a package-local dynamic chunk asynchronously. */
+    async(specifier: string): Promise<unknown>;
+}
 /** 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;
+    /** Package-local chunk filename; absent for the package's `client.js` entry. */
+    chunk?: 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.
+     * Closure factory holding the whole bundle body: receives the module-table
+     * require whose `async` operation loads generated chunks, and returns the
+     * bundle's exports. The factory runs once, at materialization.
      */
-    factory: (require: (spec: string) => unknown) => Record<string, unknown>;
+    factory: (require: ClientBundleRequire) => Record<string, unknown>;
 }
 /** Inputs passed by the web entry when it creates the client module system. */
 export interface ClientModuleCreateOptions {
@@ -208,9 +236,11 @@ 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. */
+    /** Latest parsed Host graph, updated by live entry reconciliation. */
     manifest: BootManifest;
-    /** Materialized-module registry: id → record. The governance-side read API for entry exports. */
+    /** Page-owned entry reconciliation, shared by boot, graph updates and HMR. */
+    entries: ClientEntries;
+    /** Materialized-module registry: entry or package-local chunk id → record. */
     loadCache: Map<string, ClientModuleRecord>;
     /**
      * Internal contract consumed by the vendored Loader's `tree.import`. Resolves
@@ -234,8 +264,8 @@ 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 loads its one-resource
+     * Full reset of one non-bootstrap package: drop its entry and chunk factories
+     * and materialized records 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.
@@ -246,7 +276,7 @@ export interface ClientModuleLoader {
 }
 /** Internal construction inputs assembled by the modules bundle's bootstrap export. */
 export interface ClientModuleSystemOptions {
-    /** Parsed boot graph owned by the resulting module system. */
+    /** Boot graph validated by {@link parseBootManifest}, owned by the resulting module system. */
     manifest: BootManifest;
     /** Module-table seed: platform-singleton specifier → shell instance. */
     staticModules: Record<string, unknown>;

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

@@ -1,3 +1,4 @@
+import { ClientEntries } from './entries.ts';
 import type { BootManifest, ClientModuleLoader, ClientModuleRecord, ClientModuleSystemOptions } from './manifest.ts';
 /**
  * The client module system: state tables plus the arrival/materialization
@@ -8,15 +9,18 @@ import type { BootManifest, ClientModuleLoader, ClientModuleRecord, ClientModule
  */
 export declare class ClientModuleSystem implements ClientModuleLoader {
     readonly version = "client";
-    readonly manifest: BootManifest;
+    manifest: BootManifest;
+    readonly entries: ClientEntries;
     readonly loadCache: Map<string, ClientModuleRecord>;
     private readonly seed;
     private readonly factories;
     private readonly bootstrapIds;
     /** In-flight script transport per URL; every row in one batch shares it. */
     private readonly pendingArrival;
+    /** Owner generation captured by in-flight chunk requests and advanced on invalidation. */
+    private readonly generations;
     /** Single-resource combo URL selected by HMR after invalidating one row. */
-    private readonly reloadUrls;
+    private readonly reloadTargets;
     /** Materialization re-entrancy guard: factory-form CJS cannot deliver partial exports, so a cycle is fatal. */
     private readonly materializing;
     private readonly graphRows;
@@ -34,15 +38,16 @@ export declare class ClientModuleSystem implements ClientModuleLoader {
     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.
-     */
+    /** Build the synchronous module-table require and its asynchronous chunk operation. */
     private makeRequire;
+    /** Load, register, and materialize one package-local dynamic chunk. */
+    private importChunk;
     import(specifier: string): Promise<unknown>;
     prefetch(id: string): Promise<void>;
+    /** Refresh descriptors and unowned factory revisions before any entry imports its dependencies. */
+    private updateManifest;
+    /** Retain live Loader modules and their transitive requests before evicting unreferenced graph records. */
+    private prune;
     invalidate(id: string, rev?: string): void;
 }
 //# sourceMappingURL=system.d.ts.map

package/lib/types/index.d.ts

@@ -6,7 +6,7 @@
  * 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
+ * `clientModules` service (the HMR node half's registration/notification
  * face).
  *
  * Scanning is incremental per package — there is no full-rescan code path.
@@ -91,6 +91,7 @@ export declare class ClientModuleRegistry extends Service {
     private composed;
     /**
      * Build the service: subscribe, seed, and run the activation flush.
+     * Bundle routes follow the optional Web carrier's injected lifecycle.
      * @param ctx - plugin context carrying Loader and an optional Web carrier.
      */
     constructor(ctx: Context);
@@ -108,11 +109,12 @@ export declare class ClientModuleRegistry extends Service {
     /**
      * Serve an advertised revisioned bundle or source map without a Web server.
      * Unknown URLs return 404, unsupported methods return 405, and `HEAD`
-     * returns the same immutable headers without a body.
+     * returns the same immutable headers without materializing a body. Each body
+     * is built once on its first `GET`; script construction never reads maps.
      * @param request - shell-carrier request for a `/plugins` resource.
      * @returns the exact response also exposed by the optional Web route.
      */
-    fetchBundle(request: Request): Response;
+    fetchBundle(request: Request): Promise<Response>;
     /**
      * 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
@@ -123,8 +125,8 @@ export declare class ClientModuleRegistry extends Service {
      */
     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).
+     * Publish one completed bundle generation (the HMR watch's registration
+     * hook — the only entry point through which build changes reach the graph).
      * @param id - entry id (package name).
      * @returns the new rev, or undefined for an unknown id.
      */
@@ -164,20 +166,24 @@ export declare class ClientModuleRegistry extends Service {
     /** Allocate an opaque initial row revision without inspecting artifact bytes. */
     private allocateInitialRevision;
     /**
-     * Read the activation-time bundle and optional source-map snapshots.
+     * Read the activation-time bundle snapshot.
      * @param pkgName - package that declares the client bundle.
      * @param clientPath - absolute path of the built client artifact.
      * @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 initialBundleSnapshot;
-    /** Treat a missing, torn, or malformed development map as an identity-mapped artifact revision. */
-    private readSourceMapSnapshot;
+    /** Treat a missing, torn, or malformed development map as an identity section. */
+    private readonly readSourceMap;
     /** Reconcile one entry name against the live Loader sources. @returns whether the table changed. */
     private processOne;
     private resolveSource;
     private reconcilePackage;
     private flush;
+    /** Match an exact current-revision package-local chunk URL without reading its file. */
+    private chunkRequest;
+    /** Build a package-local chunk response only when its URL is requested. */
+    private chunkResponse;
     private bundleResource;
     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.5-rc.2",
+  "version": "0.1.6-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -38,11 +38,12 @@
   },
   "license": "MIT",
   "devDependencies": {
+    "@deepseek-ai/dsh-host-webserver": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.6-alpha.2",
     "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.5-rc.2",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-package-manifest": "^0.1.5-rc.2"
+    "@deepseek-ai/dsh-package-manifest": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-client-store": "^0.1.6-alpha.2"
   },
   "files": [
     "lib/index.js",