@deepseek-ai/dsh-client-hmr 0.1.6-alpha.2 → 0.1.7-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/client/hmr/README.md
-README.md: e459da10332ffdb3af422b75f639ce25df512487
-README.zh.md: 54e2f3af63472dedbfc75c5b4400b5d93e14f311
+README.md: a0c658ea059dbd9f5b7862225baa0831218c4c9f
+README.zh.md: 7f6b7d17b764f7506ae7f203436a648667ac21ab

package/README.md

@@ -29,7 +29,7 @@ The shipped Web composition mounts this transport for live plugin changes. Durin
 
 ### Starting the reload chain
 
-Run `pnpm run dev:web` (or a watch process using the shared Client tsdown preset) against the same host; rebuilt plugins are then swapped into the running browser automatically, one at a time. The preset stamps `lib/client.js` after all package-local chunks are written, so a chunk-only rebuild also advances the package revision without Host-side chunk scanning.
+Run `pnpm run dev:web`, which starts the host and the rebuild watchers together (`--no-serve` attaches only the watchers to a host started elsewhere, as does any watch process using the shared Client tsdown preset); rebuilt plugins are then swapped into the running browser automatically, one at a time. The preset stamps `lib/client.js` after all package-local chunks are written, so a chunk-only rebuild also advances the package revision without Host-side chunk scanning.
 
 ### What a reload does
 
@@ -59,7 +59,7 @@ This section explains how the reload chain is built; observable behavior is cove
 
 ### Design concept
 
-The Host half watches each package's stamped entry artifact and serves `/plugins/events`. It forwards existing graph-change and rebuilt notifications; every new connection receives the current full graph. A graph describes the browser’s desired entries and carries no Host cleanup-completion guarantee. Host activation and cleanup remain owned by the Host lifecycle. The entry bytes plus completed-build timestamp identify the revision; unchanged artifacts require no content read. The browser half delegates both frame kinds to Client Modules, which serializes entry changes and waits for browser resource cleanup.
+The Host half watches each package's stamped entry artifact and serves `/plugins/events`. It forwards existing graph-change and rebuilt notifications; every new connection receives the current full graph. A graph describes the browser’s desired entries and carries no Host cleanup-completion guarantee. Host activation and cleanup remain owned by the Host lifecycle. The entry's mtime, ctime, and size identify the revision without hashing its contents; unchanged metadata requires no content read. Host restarts over unchanged artifacts keep the same revisions, so reconnecting the graph stream does not replace browser plugins. The browser half delegates both frame kinds to Client Modules, which serializes entry changes and waits for browser resource cleanup.
 
 ### The browser swap
 

package/README.zh.md

@@ -29,7 +29,7 @@ kind: "package-reference"
 
 ### 启动重载链路
 
-对同一个宿主运行 `pnpm run dev:web`（或使用共享 Client tsdown 预设的 watch 进程）；重建后的插件随后会被自动逐个替换进运行中的浏览器。该预设会在所有包内 chunk 写完后标记 `lib/client.js`，因此仅 chunk 发生重建也会推进包 revision，无需 Host 扫描 chunk。
+运行 `pnpm run dev:web`，它会同时启动宿主与重建 watcher（`--no-serve` 则只把 watcher 接到别处启动的宿主上，使用共享 Client tsdown 预设的任何 watch 进程亦然）；重建后的插件随后会被自动逐个替换进运行中的浏览器。该预设会在所有包内 chunk 写完后标记 `lib/client.js`，因此仅 chunk 发生重建也会推进包 revision，无需 Host 扫描 chunk。
 
 ### 一次重载做什么
 
@@ -59,7 +59,7 @@ kind: "package-reference"
 
 ### 设计理念
 
-Host 半侧监听每个包带完成标记的入口产物，并提供 `/plugins/events`。它转发现有的图变化与重建通知；每个新连接都会收到当前完整图。图描述浏览器的目标条目，不保证 Host 清理已经完成。Host 的激活与清理仍由 Host 生命周期管理。入口字节与构建完成时间戳共同标识 revision；未变化的产物无需读取内容。浏览器半侧将两种帧都交给 Client Modules，由它串行处理条目变更并等待浏览器资源清理。
+Host 半侧监听每个包带完成标记的入口产物，并提供 `/plugins/events`。它转发现有的图变化与重建通知；每个新连接都会收到当前完整图。图描述浏览器的目标条目，不保证 Host 清理已经完成。Host 的激活与清理仍由 Host 生命周期管理。入口的 mtime、ctime 和大小共同标识 revision，无需对其内容求哈希；元数据未变时无需读取内容。Host 重启时若产物未变，revision 保持不变，因此图流重连不会替换浏览器插件。浏览器半侧将两种帧都交给 Client Modules，由它串行处理条目变更并等待浏览器资源清理。
 
 ### 浏览器侧替换
 

package/lib/client.js

@@ -38,8 +38,11 @@ window.__ModuleLoader__.load({
 				default: return typeof record.type === "string" ? { kind: "unknown" } : { kind: "invalid" };
 			}
 		}
-		/** System SSE endpoint pushing graph/rebuilt frames (wire protocol constant). */
-		const EVENTS_ENDPOINT = "/plugins/events";
+		/**
+		* Document-relative form of {@link EVENTS_ENDPOINT} used by the browser half.
+		* See .agents/notes/implemented/architecture/2026-09-14-web-document-relative-app-routes.md.
+		*/
+		const EVENTS_ROUTE = "/plugins/events".slice(1);
 		//#endregion
 		//#region lib/types/client/index.js
 		/** Cordis plugin name. */
@@ -58,7 +61,7 @@ window.__ModuleLoader__.load({
 				});
 			};
 			ctx.effect(() => {
-				const source = new EventSource(EVENTS_ENDPOINT);
+				const source = new EventSource(EVENTS_ROUTE);
 				source.addEventListener("message", (event) => {
 					let value;
 					try {
@@ -77,7 +80,6 @@ window.__ModuleLoader__.load({
 			}, "client-hmr: event source");
 		}
 		//#endregion
-		exports.EVENTS_ENDPOINT = EVENTS_ENDPOINT;
 		exports.apply = apply;
 		exports.inject = inject;
 		exports.name = name;

package/lib/index.js

@@ -3,6 +3,7 @@ import z from "@deepseek-ai/schemastery";
 //#region lib/types/events.js
 /** System SSE endpoint pushing graph/rebuilt frames (wire protocol constant). */
 const EVENTS_ENDPOINT = "/plugins/events";
+EVENTS_ENDPOINT.slice(1);
 //#endregion
 //#region lib/types/index.js
 /**
@@ -28,12 +29,13 @@ function bundleStat(path) {
 	const bundle = statSync(path);
 	return {
 		mtimeMs: bundle.mtimeMs,
+		ctimeMs: bundle.ctimeMs,
 		size: bundle.size
 	};
 }
-/** Whether the executable bundle is unchanged since the last successful re-hash. */
+/** Whether the executable bundle metadata is unchanged since its last publication. */
 function sameBundleStat(left, right) {
-	return left.mtimeMs === right.mtimeMs && left.size === right.size;
+	return left.mtimeMs === right.mtimeMs && left.ctimeMs === right.ctimeMs && left.size === right.size;
 }
 /**
 * Mount bundle watches and graph/rebuilt SSE delivery.
@@ -43,7 +45,7 @@ function sameBundleStat(left, right) {
 function apply(ctx, config) {
 	const pollIntervalMs = config.pollIntervalMs;
 	const watched = /* @__PURE__ */ new Map();
-	const rehash = (id, watch, current) => {
+	const publish = (id, watch, current) => {
 		try {
 			ctx.clientModules.rebuilt(id);
 		} catch (error) {
@@ -54,6 +56,7 @@ function apply(ctx, config) {
 			ctx.logger.warn(error);
 		}
 		watch.mtimeMs = current.mtimeMs;
+		watch.ctimeMs = current.ctimeMs;
 		watch.size = current.size;
 		watch.dirty = false;
 	};
@@ -71,7 +74,7 @@ function apply(ctx, config) {
 			if (error.code !== "ENOENT") ctx.logger.warn(error);
 			return;
 		}
-		if (!sameBundleStat(current, watch)) rehash(id, watch, current);
+		if (!sameBundleStat(current, watch)) publish(id, watch, current);
 	};
 	const pollWatches = () => {
 		for (const [id, watch] of watched) {
@@ -84,7 +87,7 @@ function apply(ctx, config) {
 				continue;
 			}
 			if (!watch.dirty && sameBundleStat(current, watch)) continue;
-			rehash(id, watch, current);
+			publish(id, watch, current);
 		}
 	};
 	const syncWatches = () => {

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

@@ -1,7 +1,6 @@
 /** Web SSE transport for page-owned client entry reconciliation and rebuilt code replacement. */
 import type { Context } from '@deepseek-ai/cordis';
 export type { PluginsEventFrame } from '../events.ts';
-export { EVENTS_ENDPOINT } from '../events.ts';
 /** Cordis plugin name. */
 export declare const name = "client-hmr";
 /** Required service: the client module system whose entry controller handles received frames. */

package/lib/types/events.d.ts

@@ -36,4 +36,9 @@ export type PluginsEventParseResult = {
 export declare function parsePluginsEventFrame(value: unknown): PluginsEventParseResult;
 /** System SSE endpoint pushing graph/rebuilt frames (wire protocol constant). */
 export declare const EVENTS_ENDPOINT = "/plugins/events";
+/**
+ * Document-relative form of {@link EVENTS_ENDPOINT} used by the browser half.
+ * See .agents/notes/implemented/architecture/2026-09-14-web-document-relative-app-routes.md.
+ */
+export declare const EVENTS_ROUTE: string;
 //# sourceMappingURL=events.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-client-hmr",
   "description": "Web client graph synchronization and rebuilt-bundle reload transport",
-  "version": "0.1.6-alpha.2",
+  "version": "0.1.7-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -40,17 +40,17 @@
   },
   "license": "MIT",
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.2"
+    "@deepseek-ai/schemastery": "~3.18.4"
   },
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis": "~4.0.4"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
-    "@deepseek-ai/dsh-client-modules": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.6-alpha.2",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/cordis-plugin-loader": "~1.0.5",
+    "@deepseek-ai/dsh-client-modules": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-host-webserver": "0.1.7-alpha.2",
+    "@deepseek-ai/dsh-invariants": "0.1.7-alpha.2",
+    "@deepseek-ai/cordis": "~4.0.4"
   },
   "files": [
     "lib/index.js",