@deepseek-ai/dsh-host-frontend-static 0.1.0-rc.8 → 0.1.1-rc.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/host/frontend-static/README.md
-README.md: e53a369384fb8d7fe020e99da0d2cacca59e8afd
-README.zh.md: 7018d80182d477f2bdff7b1d8510971dc98c71d5
+README.md: e4f3765a0471566dfb2f6780b1072d3e79788dc5
+README.zh.md: 7672478480f07b760634fef0c8640fcbdc0e6e7e

package/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-SPA dist server for the Web shell: a function plugin (config `{distIndex}`) that claims the [webserver](../webserver/README.md)'s single fallback seat and serves the built frontend directory with the shell's locked semantics — traversal outside the dist root is 403, any miss falls back to `index.html` with HTTP 200 (SPA routing), unknown extensions ship as `application/octet-stream`, and non-GET/HEAD without a matching named route is 405. Every index response runs through the webserver's registered index taps (`applyIndexTaps`), which is how the boot manifest reaches the page. `distIndex` is an assembly fact of the composing application: [`dsh-web-app`](../../bundle/web-app/README.md) resolves it through the frontend package's exports and mounts this plugin; a deployment never hardcodes it.
+SPA dist server for the Web shell: a function plugin (config `{distIndex}`) that claims the [webserver](../webserver/README.md)'s single fallback seat and serves the built frontend directory with explicit index entry points. While `distIndex` is readable, the dist root and configured index path render `index.html` with HTTP 200; other existing files are served directly. An absent or non-file target inside the dist root, including a missing configured index, returns an empty 404; traversal outside the dist root returns 403, unknown extensions ship as `application/octet-stream`, and non-GET/HEAD without a matching named route returns 405. Every successful index response is rendered through the webserver's `renderIndex` — structured injection rows first, then the raw index taps — which is how the boot manifest reaches the page. `distIndex` is an assembly fact of the composing application: [`dsh-web-app`](../../bundle/web-app/README.md) resolves it through the frontend package's exports and mounts this plugin; a deployment never hardcodes it.
 
 The fallback seat is single-owner (a second claim throws) and effect-scoped: disposing the plugin's fiber releases the seat, after which the unclaimed webserver answers 404.
 
@@ -17,3 +17,4 @@ None; this package neither assembles nor sends a provider request.
 ## Known Limitations and Deferred Work
 
 - **The starter MIME table is minimal** — it covers the Vite-emitted asset set plus the shipped PWA manifest; other extensions fall back to `application/octet-stream` until an asset class actually ships.
+- **Pathname routing is explicit** — the current client enters through the root or configured index path and has no History API pathname routes. Adding one requires an explicit server rule and real-composition coverage rather than a broad fallback for every miss.

package/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Web 壳的 SPA dist 服务器：一个函数插件（配置为 `{distIndex}`），占据 [webserver](../webserver/README.md) 的唯一回退席位，并按壳层锁定的语义服务已构建的前端目录——越出 dist 根目录的遍历返回 403，任何未命中项都以 HTTP 200 回退到 `index.html`（SPA 路由），未知扩展名按 `application/octet-stream` 提供，GET／HEAD 之外的方法在没有匹配的具名路由时返回 405。每个 index 响应都会经过 webserver 已注册的 index 转换器（`applyIndexTaps`），启动 manifest（元数据清单）就是经这条路径送达页面的。`distIndex` 是组合应用的组装事实：[`dsh-web-app`](../../bundle/web-app/README.md) 通过前端包的 exports 解析它并挂载本插件；部署绝不硬编码它。
+Web 壳的 SPA dist 服务器：一个函数插件（配置为 `{distIndex}`），占据 [webserver](../webserver/README.zh.md) 的唯一回退席位，并通过显式 index 入口服务已构建的前端目录。`distIndex` 可读时，dist 根目录和配置的 index 路径以 HTTP 200 渲染 `index.html`；其他现有文件直接提供。dist 根目录内缺失或不是文件的目标——包括缺失的配置 index——返回空的 404；越出 dist 根目录的遍历返回 403，未知扩展名按 `application/octet-stream` 提供，GET／HEAD 之外的方法在没有匹配的具名路由时返回 405。每个成功的 index 响应都经 webserver 的 `renderIndex` 渲染——先结构化注入行、后原始 index 转换器——启动 manifest（元数据清单）就是经这条路径送达页面的。`distIndex` 是组合应用的组装事实：[`dsh-web-app`](../../bundle/web-app/README.zh.md) 通过前端包的 exports 解析它并挂载本插件；部署绝不硬编码它。
 
 回退席位只有单一所有者（第二次占据会抛错），并受 effect 作用域约束：dispose（资源释放）插件的 fiber 会释放席位，此后无人占据的 webserver 回答 404。
 
@@ -17,3 +17,4 @@ Web 壳的 SPA dist 服务器：一个函数插件（配置为 `{distIndex}`）
 ## 已知限制与延期工作
 
 - **初始 MIME 表很精简**：它覆盖 Vite 输出的资产集合及实际交付的 PWA manifest；其他扩展名在相应资产类别实际发布前都会回退到 `application/octet-stream`。
+- **pathname 路由是显式的**：当前客户端只从根路径或配置的 index 路径进入，没有 History API pathname 路由。添加这类路由时必须同时添加显式服务器规则和真实组合测试，不得为每个未命中项启用宽泛回退。

package/lib/index.js

@@ -4,14 +4,14 @@ import z from "@deepseek-ai/schemastery";
 //#region lib/types/index.js
 /**
 * @deepseek-ai/dsh-host-frontend-static — SPA dist server over the webserver
-* fallback seat: serves the built frontend directory with the semantics the
-* Web shell locked at step1 — traversal outside the dist root is 403, any
-* miss falls back to index.html with HTTP 200 (SPA routing), unknown
-* extensions ship as octet-stream, non-GET/HEAD is 405. Every index response
-* runs through the webserver's registered index taps (boot-manifest
-* injection). The dist location is workspace knowledge of the composing
-* application, so `distIndex` is typically supplied through a `!!js`
-* expression, never hardcoded by a deployment.
+* fallback seat: serves the built frontend directory with explicit index
+* entry points. A readable index renders at the dist root and configured index
+* path; missing paths return 404, traversal outside the dist root is 403,
+* unknown extensions ship as octet-stream, and non-GET/HEAD is 405. Every
+* index response runs through the webserver's index render (structured
+* injection rows, then raw taps). The dist location is workspace knowledge of
+* the composing application, so `distIndex` is typically supplied through a
+* `!!js` expression, never hardcoded by a deployment.
 * @module @deepseek-ai/dsh-host-frontend-static
 */
 /** Stable Cordis plugin name. */
@@ -19,8 +19,9 @@ const name = "frontend-static";
 /** Service required before the fallback seat can be claimed. */
 const inject = ["webServer"];
 const Config = z.object({ distIndex: z.string().required() });
+const HTML_MIME = "text/html; charset=utf-8";
 const MIME = {
-	".html": "text/html; charset=utf-8",
+	".html": HTML_MIME,
 	".js": "text/javascript; charset=utf-8",
 	".css": "text/css; charset=utf-8",
 	".svg": "image/svg+xml",
@@ -28,14 +29,19 @@ const MIME = {
 	".map": "application/json",
 	".webmanifest": "application/manifest+json"
 };
+const STATIC_MISS_CODES = new Set([
+	"ENOENT",
+	"EISDIR",
+	"ENOTDIR"
+]);
 /**
 * Serve one GET/HEAD static request from the dist root.
 * @param pathname - decoded URL pathname of the request.
 * @param res - the node:http response to write.
 * @param distRoot - absolute dist root directory (resolved by the caller).
 * @param distIndex - absolute path of index.html inside distRoot.
-* @param renderIndex - produces the index.html body (index-tap injection) for
-* `/` and every SPA fallback.
+* @param renderIndex - produces the index.html body (structured injection
+* rendering) for the dist root and configured index path.
 */
 async function serveStatic(pathname, res, distRoot, distIndex, renderIndex) {
 	const target = resolve(normalize(join(distRoot, pathname)));
@@ -44,22 +50,24 @@ async function serveStatic(pathname, res, distRoot, distIndex, renderIndex) {
 		res.end();
 		return;
 	}
-	const serveIndex = async () => {
-		const body = await renderIndex();
-		res.writeHead(200, { "content-type": MIME[".html"] });
-		res.end(body);
-	};
-	if (target === distRoot || target === distIndex) {
-		await serveIndex();
-		return;
-	}
+	let body;
+	let type;
 	try {
-		const body = await readFile(target);
-		res.writeHead(200, { "content-type": MIME[extname(target)] ?? "application/octet-stream" });
-		res.end(body);
-	} catch {
-		await serveIndex();
+		if (target === distRoot || target === distIndex) {
+			body = await renderIndex();
+			type = HTML_MIME;
+		} else {
+			body = await readFile(target);
+			type = MIME[extname(target)] ?? "application/octet-stream";
+		}
+	} catch (error) {
+		if (!STATIC_MISS_CODES.has(error.code)) throw error;
+		res.writeHead(404);
+		res.end();
+		return;
 	}
+	res.writeHead(200, { "content-type": type });
+	res.end(body);
 }
 /**
 * Claim the webserver fallback seat and serve the dist.
@@ -69,7 +77,7 @@ async function serveStatic(pathname, res, distRoot, distIndex, renderIndex) {
 function apply(ctx, config) {
 	const distIndex = config.distIndex;
 	const distRoot = dirname(distIndex);
-	const renderIndex = async () => ctx.webServer.applyIndexTaps(await readFile(distIndex, "utf8"));
+	const renderIndex = async () => ctx.webServer.renderIndex(await readFile(distIndex, "utf8"));
 	ctx.effect(() => ctx.webServer.registerFallback(async (req, res) => {
 		if (req.method !== "GET" && req.method !== "HEAD") {
 			res.writeHead(405);

package/lib/types/index.d.ts

@@ -1,13 +1,13 @@
 /**
  * @deepseek-ai/dsh-host-frontend-static — SPA dist server over the webserver
- * fallback seat: serves the built frontend directory with the semantics the
- * Web shell locked at step1 — traversal outside the dist root is 403, any
- * miss falls back to index.html with HTTP 200 (SPA routing), unknown
- * extensions ship as octet-stream, non-GET/HEAD is 405. Every index response
- * runs through the webserver's registered index taps (boot-manifest
- * injection). The dist location is workspace knowledge of the composing
- * application, so `distIndex` is typically supplied through a `!!js`
- * expression, never hardcoded by a deployment.
+ * fallback seat: serves the built frontend directory with explicit index
+ * entry points. A readable index renders at the dist root and configured index
+ * path; missing paths return 404, traversal outside the dist root is 403,
+ * unknown extensions ship as octet-stream, and non-GET/HEAD is 405. Every
+ * index response runs through the webserver's index render (structured
+ * injection rows, then raw taps). The dist location is workspace knowledge of
+ * the composing application, so `distIndex` is typically supplied through a
+ * `!!js` expression, never hardcoded by a deployment.
  * @module @deepseek-ai/dsh-host-frontend-static
  */
 import type { ServerResponse } from 'node:http';
@@ -29,8 +29,8 @@ export declare const Config: z<Config>;
  * @param res - the node:http response to write.
  * @param distRoot - absolute dist root directory (resolved by the caller).
  * @param distIndex - absolute path of index.html inside distRoot.
- * @param renderIndex - produces the index.html body (index-tap injection) for
- * `/` and every SPA fallback.
+ * @param renderIndex - produces the index.html body (structured injection
+ * rendering) for the dist root and configured index path.
  */
 export declare function serveStatic(pathname: string, res: ServerResponse, distRoot: string, distIndex: string, renderIndex: () => Promise<string>): Promise<void>;
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-host-frontend-static",
-  "description": "SPA dist server for the Web shell: owns the webserver fallback seat, serving the built frontend with index-tap injection, traversal rejection, and SPA index fallback",
-  "version": "0.1.0-rc.8",
+  "description": "SPA dist server for the Web shell: owns the webserver fallback seat, serving explicit index entries and static assets with traversal rejection and 404 misses",
+  "version": "0.1.1-rc.2",
   "publishConfig": {
     "access": "public"
   },
@@ -32,17 +32,17 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.1-rc.2"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "devDependencies": {
     "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
-    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.8",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8",
+    "@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"
   }
 }