From 409b208928031c275b335c3c2ff655b717a317e6 Mon Sep 17 00:00:00 2001
From: Yaojia Wang <yaojia.wang@billo.life>
Date: Tue, 16 Jun 2026 07:36:01 +0200
Subject: [PATCH] =?UTF-8?q?build:=20adopt=20esbuild=20for=20frontend=20bun?=
 =?UTF-8?q?dling=20(build:web=20=E2=86=92=20public/build/)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- esbuild dev dep; build:web/dev:web bundle public/main.ts → public/build/main.js
- gitignore public/build/; tsconfig.web.json now typecheck-only
- frontend build convention documented in PLAN §1, DISPATCH, ARCHITECTURE §5
- resolves the T1 deferred decision
---
 .gitignore           |  3 +--
 docs/ARCHITECTURE.md |  3 +++
 docs/DISPATCH.md     | 11 ++++++-----
 docs/PLAN.md         | 12 +++++++++---
 docs/PROGRESS_LOG.md | 19 +++++++++++++------
 package-lock.json    |  2 ++
 package.json         |  4 +++-
 tsconfig.web.json    |  2 +-
 8 files changed, 38 insertions(+), 18 deletions(-)

diff --git a/.gitignore b/.gitignore
index 4b6eb44..238d683 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,8 +3,7 @@ node_modules/
 
 # build output
 dist/
-public/*.js
-public/*.js.map
+public/build/
 
 # local Claude Code settings (not shared)
 .claude/settings.local.json
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 4e978c3..b6d8962 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -360,6 +360,9 @@ client → {resize, cols, rows}  // 独立消息,不混进 input
 
 ## 5. 前端架构(`public/`)
 
+**构建**:打包器 = esbuild(T1 定)。入口 `public/main.ts` → `npm run build:web` → `public/build/main.js`(+ `main.css`);
+`index.html` 以 `<script type="module" src="./build/main.js">` 加载;server 静态托管 `public/`。`tsconfig.web.json` 仅类型检查。
+
 | 文件 | 职责 | 关键点 |
 |------|------|--------|
 | `main.ts` | xterm + FitAddon 初始化、WS 客户端、重连 | WS URL 同源,**scheme 随页面协议**:`(location.protocol === 'https:' ? 'wss' : 'ws') + '://' + location.host + '/term'`(M6:HTTPS 页面下硬写 `ws://` 会被浏览器 mixed-content 拦截,而 Tailscale/TLS 部署正是 HTTPS);`term.onData → ws.send {input}`;`onmessage → term.write(output)` |
diff --git a/docs/DISPATCH.md b/docs/DISPATCH.md
index 8b065bb..aff1540 100644
--- a/docs/DISPATCH.md
+++ b/docs/DISPATCH.md
@@ -129,8 +129,9 @@ Accept:vitest run origin 全绿。歧义则 [!] BLOCKED;不写 LOG;结尾给日
 ### T8 — index.html  ·  `Agent(module-builder, model:"haiku", isolation:"worktree")`
 ```
 执行 PLAN 任务 T8(public/index.html)。先读 PLAN 任务 T8、ARCHITECTURE §5。
-硬边界 —— 只创建:public/index.html。要点:终端容器 #term、键栏挂载点 #keybar、引 main.ts/style.css、
-移动端 viewport meta。Accept:浏览器打开无控制台报错。歧义则 [!] BLOCKED;不写 LOG;结尾给日志条目。
+硬边界 —— 只创建:public/index.html。要点:终端容器 #term、键栏挂载点 #keybar、移动端 viewport meta;
+**按 PLAN §1 前端构建约定**用 `<script type="module" src="./build/main.js">` 加载(及 `<link>` 引 ./build/main.css 与 style.css)。
+Accept:浏览器打开无控制台报错。歧义则 [!] BLOCKED;不写 LOG;结尾给日志条目。
 ```
 
 ### T9 — style.css  ·  `Agent(module-builder, model:"haiku", isolation:"worktree")`
@@ -152,8 +153,8 @@ Accept:vitest run keybar 全绿。歧义则 [!] BLOCKED;不写 LOG;结尾给日
 ### T11 — main.ts  ·  `Agent(module-builder, model:"sonnet", isolation:"worktree")`
 ```
 执行 PLAN 任务 T11(public/main.ts)。先读 PLAN 任务 T11、ARCHITECTURE §5/§6,搜 "M6" 照做;背景 TECH_DOC §6/§9。
-依赖 src/types.ts 的 mountKeybar 签名(仅签名,可并行)。硬边界 —— 只创建:public/main.ts。
-要点:xterm + FitAddon,fit() 必须在容器有真实尺寸后调用(display:none 得 NaN);
+依赖 src/types.ts 的 mountKeybar 签名(仅签名,可并行)。硬边界 —— 只创建:public/main.ts。本文件是 **esbuild 打包入口**(PLAN §1 约定)。
+要点:xterm + FitAddon + `import '@xterm/xterm/css/xterm.css'`,fit() 必须在容器有真实尺寸后调用(display:none 得 NaN);
 **WS scheme 随页面协议 https→wss(M6)**,URL …/term,首帧发 attach(localStorage 取 sessionId);
 term.onData→ws.send {input};onmessage 按 type 处理(attached 存 id、output→term.write、exit→提示重连);
 ResizeObserver→fit→发 resize(防抖 100ms);断线指数退避重连 1/2/4…≤30s 携带 sessionId;mountKeybar(d=>ws.send)。
@@ -194,7 +195,7 @@ Accept:vitest run manager 全绿。歧义则 [!] BLOCKED;不写 LOG;结尾给日
 ```
 执行 PLAN 任务 T14(server.ts)。先读 PLAN 任务 T14、ARCHITECTURE §3.6,逐条搜 "M4" "M5" "L3" "L5" 照做;
 用 config/protocol/origin/manager。硬边界 —— 只创建:src/server.ts。
-要点:Express 托管 public/;**WebSocketServer({noServer:true})**;HTTP upgrade:非 /term→destroy、Origin 不过→
+要点:Express 静态托管 public/(含 esbuild 产物 public/build/);**WebSocketServer({noServer:true})**;HTTP upgrade:非 /term→destroy、Origin 不过→
 socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n')+destroy、通过→handleUpgrade→emit connection(L3);
 connection 等首帧 attach→try handleAttach 回 attached,**catch→send exit(-1,reason)+close 仅此连接,不 fail-fast(M4)**;
 message:parse,ok:false 丢弃记日志,否则路由 writeInput/resize;close→detach;SIGINT/SIGTERM→shutdown;
diff --git a/docs/PLAN.md b/docs/PLAN.md
index 3bc2f19..d895f5c 100644
--- a/docs/PLAN.md
+++ b/docs/PLAN.md
@@ -64,6 +64,12 @@ W5 验收与收尾(按 F# 并行)  T16–T20 F1–F9 实测 · T21 安全+README
 
 > ARCH §6 的 S1–S8 是线性视角;本计划是其**并行重排**。每个任务标了 `ARCH:` 做溯源。
 
+**前端构建约定(T1 已定,T8/T11/T14 遵守)**:打包器 = **esbuild**。
+- 入口 `public/main.ts`;`npm run build:web` → 打包到 **`public/build/main.js`**(若 main.ts `import '@xterm/xterm/css/xterm.css'`,
+  esbuild 同时出 `public/build/main.css`)。开发用 `npm run dev:web`(--watch)。`public/build/` 已 gitignore。
+- `index.html` 以 `<script type="module" src="./build/main.js">` 加载,并 `<link rel="stylesheet" href="./build/main.css">`(若有)+ 自己的 `style.css`。
+- `server.ts` 静态托管整个 `public/`(含 `public/build/`)。`tsconfig.web.json` 仅类型检查(noEmit)。
+
 ---
 
 ## 2. 任务清单
@@ -160,7 +166,7 @@ W5 验收与收尾(按 F# 并行)  T16–T20 F1–F9 实测 · T21 安全+README
 #### T8 · `public/index.html` `[ ]`
 - **Wave/ARCH**: W1 / S7 §5 · **Owns**: `public/index.html`
 - **Depends**: 无(可在 T2 前都行) · **Parallel-safe**: 全部
-- **Steps**: [ ] 终端容器 `#term`、键栏挂载点 `#keybar`、引 main.ts/style.css;viewport meta(移动端)
+- **Steps**: [ ] 终端容器 `#term`、键栏挂载点 `#keybar`;`<script type="module" src="./build/main.js">` + `style.css`(及 `./build/main.css` 若有);viewport meta(移动端)。**按§1 前端构建约定**
 - **Accept**: 浏览器打开无控制台报错(静态)
 
 #### T9 · `public/style.css` `[ ]`
@@ -183,7 +189,7 @@ W5 验收与收尾(按 F# 并行)  T16–T20 F1–F9 实测 · T21 安全+README
 - **Wave/ARCH**: W1 / S7 §5/§6 · **Owns**: `public/main.ts`
 - **Depends**: T2 + T10(仅 `mountKeybar` 签名,可并行) · **Parallel-safe**: 后端全部
 - **Steps**:
-  - [ ] xterm + FitAddon 初始化;`fit()` 在容器有真实尺寸后调用(§9 坑)
+  - [ ] (本文件是 esbuild 打包入口,见§1 约定)xterm + FitAddon 初始化 + `import '@xterm/xterm/css/xterm.css'`;`fit()` 在容器有真实尺寸后调用(§9 坑)
   - [ ] WS:**scheme 随页面协议** `https→wss`(M6),URL `…/term`,首帧发 `attach`(localStorage 取 sessionId)
   - [ ] `term.onData → ws.send {input}`;`onmessage` 按 type 处理(attached 存 id、output→`term.write`、exit→提示重连)
   - [ ] `ResizeObserver`/resize → `fit()` → 发 `resize`(防抖 100ms)
@@ -234,7 +240,7 @@ W5 验收与收尾(按 F# 并行)  T16–T20 F1–F9 实测 · T21 安全+README
 - **Wave/ARCH**: W4 / S6 §3.6 · **Owns**: `src/server.ts`
 - **Depends**: T4、T5、T7、T13 · **Parallel-safe**: T15 可并行起草用例
 - **Steps**:
-  - [ ] Express 托管 `public/` + 编译产物
+  - [ ] Express 托管 `public/`(含 esbuild 产物 `public/build/`,见§1 约定);提示:start 前需 `npm run build:web`(或 `dev:web` 监听)
   - [ ] `WebSocketServer({ noServer:true })`(L3);HTTP `upgrade`:非 `/term`→destroy、Origin 不过→`401\r\n\r\n`+destroy、通过→`handleUpgrade`→emit connection
   - [ ] `connection`:等首帧 attach→`try handleAttach` 回 attached;`catch`→send `exit(-1,reason)`+close(仅此连接,不 fail-fast)(M4)
   - [ ] `message`:parse→ok:false 丢弃记日志,否则路由 writeInput/resize
diff --git a/docs/PROGRESS_LOG.md b/docs/PROGRESS_LOG.md
index 81b9b48..f26c75b 100644
--- a/docs/PROGRESS_LOG.md
+++ b/docs/PROGRESS_LOG.md
@@ -27,9 +27,7 @@
 - **Wave**: W0(T1 ✓)→ 下一步 **T2**(冻结 `src/types.ts`)
 - **任务**: T2 — 共享类型契约,完成后 W0 全部 commit,即可放开 W1 并行
 - **下一步**: 派 `module-builder`(sonnet)执行 T2,或主会话直接做;依据 ARCHITECTURE §3
-- **阻塞**: 无。但有 1 个待决项(非阻塞):**前端浏览器打包策略未定**(tsconfig.web 当前只类型检查,
-  不产出可被浏览器加载的 JS;main.ts 引 @xterm 裸导入需 bundler/import-map/CDN)。需在 **T11/T14 前**决定,
-  建议加 esbuild 作为 `build:web`。
+- **阻塞**: 无。(前端打包待决项**已解决**:选 esbuild,已装好并接好 `build:web`/`dev:web`,约定写入 PLAN §1。)
 - **最后更新**: 2026-06-16
 
 ---
@@ -117,11 +115,20 @@
   2. 依赖解析到较新主版本(express 5 / xterm 6 / typescript 6 / vitest 4):**T7/T11/T14/T15 注意 API 差异**
      (express 5 路由、xterm 6 import 形态)。
   3. 加了 PLAN 未列的脚本 `dev`/`typecheck` 与 `postinstall`(便利 + 必需修复),属合理补充,未改 PLAN 意图。
-- **遗留 / 待办**(非阻塞,需在 **T11/T14 前**决):**前端浏览器打包未定**。`tsconfig.web.json` 现为 `noEmit`(仅类型检查);
-  `public/main.ts` 裸导入 `@xterm/xterm`,浏览器无法直接解析,需 bundler(建议 esbuild,加 `build:web`)/import-map/CDN 三选一。
-  建议下一波前由 orchestrator 拍板,若选 esbuild 则**现在补装**(避免后续并发 install)。
+- **遗留 / 待办**: 无(原前端打包待决项已解决,见下补记)。
 - **commit**: `b126cf0`
 
+### 2026-06-16 · T1 补记 — 前端打包定为 esbuild
+
+- **状态**: `[x]` DONE
+- **改动**: 装 `esbuild`(dev);`package.json` 接 `build:web`/`dev:web`(打包 `public/main.ts` → `public/build/main.js`);
+  `.gitignore` 改忽略 `public/build/`;`tsconfig.web.json` 注释更新为"仅类型检查";前端构建约定写入
+  `PLAN §1` 并更新 T8/T11/T14 与 `DISPATCH.md`、`ARCHITECTURE §5`。
+- **验证**: esbuild 0.28.1;临时入口 `--bundle --format=esm --outdir=public/build` 出 `main.js`+`.map`,smoke 通过。
+- **决策**: 三选一中选 **esbuild**(极快、零配置、与 node-pty/tsx 生态一致);**现在装好**避免 W1 并发 install。
+  约定:入口 main.ts、产物 public/build/(已 gitignore)、index.html 用 `<script type=module src=./build/main.js>`、server 静态托管 public/。
+- **commit**: (见下次提交)
+
 ### 2026-06-15 · T0 项目记录起点(计划就绪)
 
 - **状态**: `[x]` DONE
diff --git a/package-lock.json b/package-lock.json
index e893892..2ff190d 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -7,6 +7,7 @@
     "": {
       "name": "web-terminal",
       "version": "0.1.0",
+      "hasInstallScript": true,
       "dependencies": {
         "@xterm/addon-fit": "^0.11.0",
         "@xterm/xterm": "^6.0.0",
@@ -18,6 +19,7 @@
         "@types/express": "^5.0.6",
         "@types/node": "^25.9.3",
         "@types/ws": "^8.18.1",
+        "esbuild": "^0.28.1",
         "tsx": "^4.22.4",
         "typescript": "^6.0.3",
         "vitest": "^4.1.9"
diff --git a/package.json b/package.json
index 79dc0e8..61574b6 100644
--- a/package.json
+++ b/package.json
@@ -12,7 +12,8 @@
     "start": "tsx src/server.ts",
     "dev": "tsx watch src/server.ts",
     "build": "tsc -p tsconfig.json",
-    "build:web": "tsc -p tsconfig.web.json",
+    "build:web": "esbuild public/main.ts --bundle --format=esm --outdir=public/build --sourcemap",
+    "dev:web": "esbuild public/main.ts --bundle --format=esm --outdir=public/build --sourcemap --watch",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.web.json",
     "test": "vitest run",
     "test:watch": "vitest"
@@ -28,6 +29,7 @@
     "@types/express": "^5.0.6",
     "@types/node": "^25.9.3",
     "@types/ws": "^8.18.1",
+    "esbuild": "^0.28.1",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9"
diff --git a/tsconfig.web.json b/tsconfig.web.json
index 3346681..5db65e4 100644
--- a/tsconfig.web.json
+++ b/tsconfig.web.json
@@ -1,5 +1,5 @@
 {
-  "// note": "Frontend (browser) config for public/*.ts. moduleResolution Bundler lets bare imports (@xterm/xterm) type-check. NOTE: emits nothing — the actual browser bundle strategy (esbuild/import-map/CDN) is unresolved; see T1 log entry. This config currently serves as type-check for the frontend.",
+  "// note": "Frontend (browser) config for public/*.ts — TYPE-CHECK ONLY (noEmit). moduleResolution Bundler lets bare imports (@xterm/xterm) resolve. The browser bundle is produced by esbuild: `npm run build:web` bundles public/main.ts → public/build/main.js. index.html loads ./build/main.js (type=module).",
   "compilerOptions": {
     "target": "ES2022",
     "module": "ESNext",