# 前端 TypeScript + esbuild 迁移计划

决策：Q1(a) 单文件 ESM `chat.js`；Q2 esbuild；Q3 构建产物入库；Q4 `node --test` + Node 原生 TS（禁 enum/namespace 等不可擦除语法）。

## 目标结构
```
frontend/
  package.json / tsconfig.json / esbuild.config.mjs
  src/{types,api,dom,state,ws,main}.ts
  tests/{state,ws}.test.ts
```
- 构建产物：`src/genesis/server/static/chat.js`（ESM，入库）。
- `chat_state.js` / `chat_ws.js` 删除（并入 bundle）。
- `chat.html`：`<script type="module" src="/static/chat.js?v=__ASSET_VER__">`。
- `app.py` `_asset_names` → `chat.html, chat.css, chat.js, favicon.svg`。
- Python 测试 `/static/chat_state.js`、`/static/chat_ws.js` → 改指向 `/static/chat.js`。
- 旧 `tests/test_chat_state.js`、`tests/test_chat_ws.js` → 迁移到 `frontend/tests/*.test.ts`。

## 任务
1. 工具链：package.json / tsconfig(strict) / esbuild.config.mjs。
2. 基础设施：types.ts / api.ts / dom.ts。
3. 迁移 state.ts（纯函数）+ tests/state.test.ts。
4. 迁移 ws.ts + tests/ws.test.ts。
5. 迁移 main.ts（业务 + DOM，类型化）。
6. 构建产物、改 chat.html、删旧 js、改 app.py `_asset_names`。
7. 改 Python 测试 + 删旧 Node 测试。
8. `npm run typecheck` + `npm test` + `python -m pytest`（≥99%）。
9. 文档/日志/提交。

## 风险
- `strict` 下 DOM 引用需类型化（用 `must`/`maybe` 助手）。
- Node 原生 TS 依赖 Node ≥23.6（本机 24）。