@deepseek-ai/dsh-client-modules 0.1.6-alpha.1 → 0.1.7-alpha.1

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

@@ -29,6 +29,7 @@
  * 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 {
@@ -47,7 +48,10 @@ declare module '@deepseek-ai/cordis' {
 export interface WebBootEntry {
     /** Entry name == package name. */
     id: string;
-    /** Revisioned single-resource combo endpoint used by HMR. */
+    /**
+     * Revisioned single-resource combo reference used by HMR. It is relative to
+     * the document, so the browser resolves it under whatever mount served the page.
+     */
     url: string;
     /** Opaque plugin-artifact revision used for HMR cache busting. */
     rev: string;
@@ -58,22 +62,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. */
+    /** Content-addressed combo script reference, document-relative like {@link WebBootEntry.url}. */
     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
@@ -88,9 +92,9 @@ export interface WebBootGraph {
 export interface BootModuleRow {
     /** Entry name == package name (module-table key). */
     id: string;
-    /** Revisioned single-resource combo endpoint used after HMR invalidation. */
+    /** Revisioned single-resource combo reference used after HMR invalidation. */
     url: string;
-    /** Content-addressed combo endpoint used before the first HMR invalidation. */
+    /** Content-addressed combo reference used before the first HMR invalidation. */
     initialUrl: string;
     /** Opaque plugin-artifact revision used after HMR invalidation. */
     rev: string;
@@ -162,16 +166,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 {
@@ -226,9 +239,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
@@ -252,8 +267,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.
@@ -264,7 +279,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

@@ -40,6 +40,8 @@ export interface ClientArtifactBaseline {
     readonly path: string;
     /** Bundle modification time in milliseconds. */
     readonly mtimeMs: number;
+    /** Bundle status-change time in milliseconds, including writes that preserve mtime. */
+    readonly ctimeMs: number;
     /** Bundle size in bytes. */
     readonly size: number;
 }
@@ -81,8 +83,6 @@ export declare class ClientModuleRegistry extends Service {
     private readonly rebuildListeners;
     private readonly graphListeners;
     private readonly dirty;
-    private readonly initialRevisionNonce;
-    private nextInitialRevision;
     private responses;
     private batchResponses;
     /** One prior graph generation covers a request racing the HMR recomposition that replaced its URL. */
@@ -109,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
@@ -124,14 +125,15 @@ 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).
+     * Unchanged mtime, ctime and size preserve the graph without reading the bundle.
      * @param id - entry id (package name).
-     * @returns the new rev, or undefined for an unknown id.
+     * @returns the current artifact 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.
+     * Subscribe to bundle rebuilds; fires only when artifact metadata changes the rev.
      * @param listener - receives the entry id and its new bundle rev.
      * @returns the unsubscriber.
      */
@@ -162,23 +164,25 @@ export declare class ClientModuleRegistry extends Service {
     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.
+     * 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.6-alpha.1",
+  "version": "0.1.7-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -38,11 +38,12 @@
   },
   "license": "MIT",
   "devDependencies": {
-    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.6-alpha.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.6-alpha.1",
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-package-manifest": "^0.1.6-alpha.1"
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.4",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.7-alpha.1",
+    "@deepseek-ai/cordis": "^4.0.3",
+    "@deepseek-ai/dsh-package-manifest": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-client-store": "^0.1.7-alpha.1"
   },
   "files": [
     "lib/index.js",
@@ -51,7 +52,7 @@
     "lib/types/**/*.d.ts"
   ],
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "^4.0.3"
   },
   "scripts": {
     "bundle": "tsdown",