@deepseek-ai/dsh-host-webserver 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/webserver/README.md
-README.md: 7927c791a809ad272edce1310b3c50bbe30720a5
-README.zh.md: 82252adb3945f22c83abddbd3bbdd11556383add
+README.md: b6424262305b062f4c57774c446ac1d50e490a03
+README.zh.md: ea5fd0129c121b227e4d8dbd0a8dcc162acc5f7b

package/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Web HTTP and upgrade-route registration plugin (default-exported `WebServer`, config `{host, port}`): a `node:http` server that listens on activation and provides `ctx.webServer`. `register(route)` adds a named `exact`/`prefix` HTTP route; `registerUpgrade(route)` adds an upgrade route for an exact pathname. A duplicate path within either table throws because route patterns are a composition-level contract and a collision is a misconfiguration; both methods return a disposer that removes the registration. `registerFallback(handler)` registers the one handler for requests that match no named route. A second registration throws; the SPA dist server [`dsh-host-frontend-static`](../frontend-static/README.md) is the shipped owner, and the server returns 404 while none is registered. `tapIndex(transform)` adds an index.html transform, and `applyIndexTaps(html)` runs a body through the registered transforms in order; the fallback handler calls it on every index response. `port` reads the listening port (the OS-assigned value when `port` is 0), and `host` reads the configured bind host (composition-time facts other plugins adapt to, e.g. the directory-picker chooser). HTTP match order is fixed: exact over the whole table, then longest prefix, then the fallback handler. Upgrades match exactly and unmatched connections are closed; registration order carries no request-facing semantics.
+Web HTTP and upgrade-route registration plugin (default-exported `WebServer`, config `{host, port}`): a `node:http` server that listens on activation and provides `ctx.webServer`. `register(route)` adds a named `exact`/`prefix` HTTP route; `registerUpgrade(route)` adds an upgrade route for an exact pathname. A duplicate path within either table throws because route patterns are a composition-level contract and a collision is a misconfiguration; both methods return a disposer that removes the registration. `registerFallback(handler)` registers the one handler for requests that match no named route. A second registration throws; the SPA dist server [`dsh-host-frontend-static`](../frontend-static/README.md) is the shipped owner, and the server returns 404 while none is registered. Index startup inputs are structured rows: `collectIndexInjections()` gathers a fresh `IndexInjection` table over one `webserver/index-inject` emit per call, and `renderIndex(html)` renders the rows into an index.html body before applying the raw `tapIndex(transform)` transforms in registration order (`applyIndexTaps(html)`, the escape hatch for markup no row expresses); the fallback handler calls `renderIndex` on every index response, and a static deployment ships the same rows over its boot payload, rendering with the exported `renderIndexInjections`. `port` reads the listening port (the OS-assigned value when `port` is 0), and `host` reads the configured bind host (composition-time facts other plugins adapt to, e.g. the directory-picker chooser). HTTP match order is fixed: exact over the whole table, then longest prefix, then the fallback handler. Upgrades match exactly and unmatched connections are closed; registration order carries no request-facing semantics.
 
 The package knows no harness concepts and serves no files: the `/api` HTTP bridge and downlink WebSockets are routes owned by the connection plugin, plugin bundles and the HMR event stream are routes owned by the modules/hmr plugins, and dist serving belongs to the fallback owner. The upgrade handler owns the protocol handshake and connection contents; the webserver only delivers the raw socket and request. `host` accepts only `127.0.0.1` (default posture) and `0.0.0.0` (deliberate network exposure). This server serves browsers only; Electron loads dist over `file://` and carries fetch over an IPC bridge. This package never prints; the URL line belongs to the shell.
 

package/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-Web HTTP 与 upgrade route 注册插件（默认导出 `WebServer`，配置为 `{host, port}`）：一个在激活时开始监听的 `node:http` 服务器，提供 `ctx.webServer`。`register(route)` 添加具名的 `exact`／`prefix` HTTP route；`registerUpgrade(route)` 添加精确 pathname 的 upgrade route；同一张表内的重复路径会抛错，因为 route 模式是组合层约定，冲突即配置错误；两者返回的 disposer 都会移除注册。`registerFallback(handler)` 注册一个 handler，处理所有未被具名 route 命中的请求。第二次注册会抛错；随附的 SPA dist 服务器 [`dsh-host-frontend-static`](../frontend-static/README.md) 是该 handler 的所有者，没有注册 handler 时服务器返回 404。`tapIndex(transform)` 添加一个 index.html 转换，`applyIndexTaps(html)` 按注册顺序对一段响应体运行已注册的转换；fallback handler 在每次 index 响应时调用它。`port` 读取正在监听的端口（当 `port` 为 0 时读取 OS 分配的值），`host` 读取配置的绑定宿主（这些是其他插件据以自适应的组合期事实，例如 directory-picker 选择器）。HTTP 匹配顺序固定不变：先在整张表中匹配精确 route，再匹配最长前缀，最后交给 fallback handler。upgrade 只做精确匹配，未命中连接直接关闭；注册顺序不影响请求处理。
+Web HTTP 与 upgrade route 注册插件（默认导出 `WebServer`，配置为 `{host, port}`）：一个在激活时开始监听的 `node:http` 服务器，提供 `ctx.webServer`。`register(route)` 添加具名的 `exact`／`prefix` HTTP route；`registerUpgrade(route)` 添加精确 pathname 的 upgrade route；同一张表内的重复路径会抛错，因为 route 模式是组合层约定，冲突即配置错误；两者返回的 disposer 都会移除注册。`registerFallback(handler)` 注册一个 handler，处理所有未被具名 route 命中的请求。第二次注册会抛错；随附的 SPA dist 服务器 [`dsh-host-frontend-static`](../frontend-static/README.zh.md) 是该 handler 的所有者，没有注册 handler 时服务器返回 404。index 的启动输入是结构化行：`collectIndexInjections()` 每次调用经一次 `webserver/index-inject` emit 现收一张全新的 `IndexInjection` 表，`renderIndex(html)` 先把行渲染进 index.html 响应体，再按注册顺序应用原始的 `tapIndex(transform)` 转换（`applyIndexTaps(html)`，行无法表达的标记的逃生口）；fallback handler 在每次 index 响应时调用 `renderIndex`，静态部署则把同一批行经 boot 载荷下发，用导出的 `renderIndexInjections` 渲染。`port` 读取正在监听的端口（当 `port` 为 0 时读取 OS 分配的值），`host` 读取配置的绑定宿主（这些是其他插件据以自适应的组合期事实，例如 directory-picker 选择器）。HTTP 匹配顺序固定不变：先在整张表中匹配精确 route，再匹配最长前缀，最后交给 fallback handler。upgrade 只做精确匹配，未命中连接直接关闭；注册顺序不影响请求处理。
 
 该包不了解任何 harness 概念，也不提供任何文件服务：`/api` HTTP 桥接与下行 WebSocket 是 connection 插件的 route，插件 bundle 与 HMR（热模块替换）事件流是 modules／hmr 插件的 route，dist 服务则属于 fallback 持有者。upgrade handler 拥有协议握手与连接内容；webserver 只交付原始 socket 与 request。`host` 只接受 `127.0.0.1`（默认安全姿态）和 `0.0.0.0`（有意向网络开放）。该服务器只服务浏览器；Electron 通过 `file://` 加载 dist，并经 IPC 桥接承载 fetch。该包从不打印内容；URL 行属于 shell。
 

package/lib/index.js

@@ -1,12 +1,87 @@
 import { createServer } from "node:http";
 import { Service } from "@deepseek-ai/cordis";
 import z from "@deepseek-ai/schemastery";
+//#region lib/types/injections.js
+/**
+* Structured index injections: the typed rows plugins contribute to the boot
+* HTML instead of raw `tapIndex` string transforms. Rows are pure
+* JSON-serializable data because one table feeds two renderers: the served
+* form renders rows into the index.html text ({@link renderIndexInjections}),
+* and a static worker deployment ships the same rows over its boot payload
+* for a page-side interpreter. Anything not expressible as a row stays on
+* `tapIndex`, which runs after row rendering.
+*/
+/** Escape a row value before placing it in a quoted HTML attribute. */
+function escapeHtmlAttribute(value) {
+	return value.replaceAll("&", "&amp;").replaceAll("\"", "&quot;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+function assertNever(row) {
+	throw new Error(`webserver: unknown index injection row ${JSON.stringify(row)}`);
+}
+/** Render one row to markup with its placement. */
+function renderRow(row) {
+	switch (row.kind) {
+		case "global": return {
+			placement: "head",
+			markup: `<script>globalThis[${JSON.stringify(row.name).replaceAll("<", "\\u003c")}] = ${row.value === void 0 ? "undefined" : JSON.stringify(row.value).replaceAll("<", "\\u003c")}<\/script>`
+		};
+		case "script": return {
+			placement: row.placement,
+			markup: `<script>${row.text}<\/script>`
+		};
+		case "script-src": return {
+			placement: row.placement,
+			markup: `<script src="${escapeHtmlAttribute(row.src)}"><\/script>`
+		};
+		case "style": return {
+			placement: "head",
+			markup: `<style>${row.text}</style>`
+		};
+		case "html": return {
+			placement: row.placement,
+			markup: row.html
+		};
+		default: return assertNever(row);
+	}
+}
+/** Insert `markup` into `html` at `at`. */
+function splice(html, at, markup) {
+	return `${html.slice(0, at)}${markup}${html.slice(at)}`;
+}
+/**
+* Render rows into an index.html body: head rows immediately after the
+* opening head tag, body rows immediately after the opening body tag, each
+* group in table order.
+* @param html - the raw index.html body.
+* @param rows - the collected injection table.
+* @returns the html with every row rendered.
+*/
+function renderIndexInjections(html, rows) {
+	let head = "";
+	let body = "";
+	for (const row of rows) {
+		const rendered = renderRow(row);
+		if (rendered.placement === "head") head += rendered.markup;
+		else body += rendered.markup;
+	}
+	let out = html;
+	if (head !== "") {
+		const open = /<head(?:\s[^>]*)?>/i.exec(out);
+		out = open === null ? `${head}${out}` : splice(out, open.index + open[0].length, head);
+	}
+	if (body !== "") {
+		const open = /<body(?:\s[^>]*)?>/i.exec(out);
+		out = open === null ? `${out}${body}` : splice(out, open.index + open[0].length, body);
+	}
+	return out;
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * @deepseek-ai/dsh-host-webserver — Web route-registration plugin: a node:http
-* server plus the `webServer` service (HTTP and upgrade route registries,
-* index transform taps, and the single fallback seat for everything no route
-* claims). Knows no harness concepts and serves no files; the composing
+* server plus the `webServer` service (HTTP and upgrade route registries, the
+* structured index injection table with raw transform taps behind it, and the
+* single fallback seat for everything no route claims). Knows no harness concepts and serves no files; the composing
 * application's frontend plugin owns dist serving through the fallback hook.
 * Web shape only — Electron loads dist over file:// and carries fetch over an
 * IPC bridge. This package never prints: the URL line belongs to the shell.
@@ -87,8 +162,9 @@ var WebServer = class extends Service {
 		};
 	}
 	/**
-	* Register an index.html transform, applied by the fallback owner to every
-	* index response ({@link applyIndexTaps}) in registration order.
+	* Register a raw-HTML index transform, the escape hatch for markup no
+	* {@link IndexInjection} row expresses: {@link renderIndex} applies taps in
+	* registration order after rendering the structured rows.
 	* @param transform - pure html-to-html function.
 	* @returns the disposer removing the transform.
 	*/
@@ -212,6 +288,26 @@ var WebServer = class extends Service {
 		for (const transform of this.indexTaps) out = transform(out);
 		return out;
 	}
+	/**
+	* Gather the structured injection table: one `webserver/index-inject` emit,
+	* every subscriber pushes its current rows. Fresh per call, so subscribers
+	* read live state (module graph, theme preference) at emit time.
+	* @returns rows in subscriber activation order.
+	*/
+	collectIndexInjections() {
+		const table = [];
+		this.ctx.emit("webserver/index-inject", table);
+		return table;
+	}
+	/**
+	* Render one index.html body: the structured injection table first, then
+	* the raw `tapIndex` transforms over the result.
+	* @param html - the raw index.html body.
+	* @returns the transformed body.
+	*/
+	renderIndex(html) {
+		return this.applyIndexTaps(renderIndexInjections(html, this.collectIndexInjections()));
+	}
 };
 //#endregion
-export { WebServer, WebServer as default };
+export { WebServer, WebServer as default, renderIndexInjections };

package/lib/types/index.d.ts

@@ -1,8 +1,8 @@
 /**
  * @deepseek-ai/dsh-host-webserver — Web route-registration plugin: a node:http
- * server plus the `webServer` service (HTTP and upgrade route registries,
- * index transform taps, and the single fallback seat for everything no route
- * claims). Knows no harness concepts and serves no files; the composing
+ * server plus the `webServer` service (HTTP and upgrade route registries, the
+ * structured index injection table with raw transform taps behind it, and the
+ * single fallback seat for everything no route claims). Knows no harness concepts and serves no files; the composing
  * application's frontend plugin owns dist serving through the fallback hook.
  * Web shape only — Electron loads dist over file:// and carries fetch over an
  * IPC bridge. This package never prints: the URL line belongs to the shell.
@@ -11,10 +11,23 @@ import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Duplex } from 'node:stream';
 import { Context, Service } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
+import { type IndexInjection } from './injections.ts';
+export { renderIndexInjections } from './injections.ts';
+export type { IndexInjection, IndexInjectionPlacement } from './injections.ts';
 declare module '@deepseek-ai/cordis' {
     interface Context {
         webServer: WebServer;
     }
+    interface Events {
+        /**
+         * Collect the structured index injection table. Emitted on every index
+         * render and every worker boot-payload request; listeners push their
+         * current rows, so a row's data is read fresh at emit time.
+         * @param table - Mutable row table; listeners append in activation order.
+         * @mode emit
+         */
+        'webserver/index-inject'(table: IndexInjection[]): void;
+    }
 }
 /** Route match kind: 'exact' matches the pathname verbatim; 'prefix' p matches p and p/<anything>. */
 export type WebRouteKind = 'exact' | 'prefix';
@@ -87,8 +100,9 @@ export declare class WebServer extends Service {
      */
     registerFallback(handler: WebRoute['handler']): () => void;
     /**
-     * Register an index.html transform, applied by the fallback owner to every
-     * index response ({@link applyIndexTaps}) in registration order.
+     * Register a raw-HTML index transform, the escape hatch for markup no
+     * {@link IndexInjection} row expresses: {@link renderIndex} applies taps in
+     * registration order after rendering the structured rows.
      * @param transform - pure html-to-html function.
      * @returns the disposer removing the transform.
      */
@@ -104,6 +118,20 @@ export declare class WebServer extends Service {
      * @returns the transformed body.
      */
     applyIndexTaps(html: string): string;
+    /**
+     * Gather the structured injection table: one `webserver/index-inject` emit,
+     * every subscriber pushes its current rows. Fresh per call, so subscribers
+     * read live state (module graph, theme preference) at emit time.
+     * @returns rows in subscriber activation order.
+     */
+    collectIndexInjections(): IndexInjection[];
+    /**
+     * Render one index.html body: the structured injection table first, then
+     * the raw `tapIndex` transforms over the result.
+     * @param html - the raw index.html body.
+     * @returns the transformed body.
+     */
+    renderIndex(html: string): string;
 }
 export default WebServer;
 //# sourceMappingURL=index.d.ts.map

package/lib/types/injections.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Structured index injections: the typed rows plugins contribute to the boot
+ * HTML instead of raw `tapIndex` string transforms. Rows are pure
+ * JSON-serializable data because one table feeds two renderers: the served
+ * form renders rows into the index.html text ({@link renderIndexInjections}),
+ * and a static worker deployment ships the same rows over its boot payload
+ * for a page-side interpreter. Anything not expressible as a row stays on
+ * `tapIndex`, which runs after row rendering.
+ */
+/** Document region a rendered row lands in: after the opening head or body tag. */
+export type IndexInjectionPlacement = 'head' | 'body';
+/** One structured index injection row. */
+export type IndexInjection = 
+/** Assign a JSON-serializable value to a `globalThis` property, ahead of later script rows. */
+{
+    kind: 'global';
+    name: string;
+    value: unknown;
+}
+/** Inline classic script. `text` must not contain `</script`, which would close the element early. */
+ | {
+    kind: 'script';
+    placement: IndexInjectionPlacement;
+    text: string;
+}
+/**
+ * External classic script, executed in table order: a parser-blocking tag
+ * when served, an awaited fetch-and-execute in the worker form (whose
+ * loader resolves worker-only URLs such as `/plugins/...`).
+ */
+ | {
+    kind: 'script-src';
+    placement: IndexInjectionPlacement;
+    src: string;
+}
+/** A `<style>` element in the head. `text` must not contain `</style`, which would close the element early. */
+ | {
+    kind: 'style';
+    text: string;
+}
+/** Raw markup fragment. */
+ | {
+    kind: 'html';
+    placement: IndexInjectionPlacement;
+    html: string;
+};
+/**
+ * Render rows into an index.html body: head rows immediately after the
+ * opening head tag, body rows immediately after the opening body tag, each
+ * group in table order.
+ * @param html - the raw index.html body.
+ * @param rows - the collected injection table.
+ * @returns the html with every row rendered.
+ */
+export declare function renderIndexInjections(html: string, rows: readonly IndexInjection[]): string;
+//# sourceMappingURL=injections.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-host-webserver",
   "description": "Web route-registration plugin: HTTP and upgrade routes, index transform taps, and static dist fallback; knows no harness concepts",
-  "version": "0.1.0-rc.8",
+  "version": "0.1.1-rc.2",
   "publishConfig": {
     "access": "public"
   },
@@ -32,14 +32,14 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8"
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-invariants": "^0.1.0-rc.8"
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2"
   }
 }