## HTML Transform
HTML Transform 是 prototype evidence 工具。現行 MVP 只做兩件事：
- `doctor`：檢查執行 `scan` 需要的前置條件。
- `scan`：讀取 HTML prototype，產生瀏覽器證據與頁面級 UI Contract。
- `app-map.json`：推論每個 prototype 的頁面角色與 layout 使用策略，並用 `prototype/*.md` 的人工 domain guide 輔助補上舊系統對照。
不提供 `plan`、`run`、`diff`、`verify`、`go`、`status`。這些舊骨架已移除，避免把尚未完成的自動化流程誤認成可用功能。
## MVP 範圍
`scan` 會執行：
```text
Stage 1 Capture
Stage 3-lite Page Contract
Stage 4-lite Contract Validation
```
Stage 2 decomposition 不執行。現有 prototype 主要是後台系統頁面，重點是表單、查詢條件、表格、actions 與資訊架構；切 region screenshot 對 MVP 價值不高。
目前沒有 Codex slash command。也就是說，在 repo 根目錄輸入 `/scan` 不會自動執行本工具。
## 指令
在 `packages/html-transform` 目錄內：
```bash
node src/cli.js doctor
node src/cli.js scan
```
在 repo 根目錄：
```bash
node packages/html-transform/src/cli.js doctor
node packages/html-transform/src/cli.js scan
```
若要在根目錄用簡短指令，建議由根目錄 `package.json` 包一層：
```json
{
"scripts": {
"scan": "node packages/html-transform/src/cli.js doctor && node packages/html-transform/src/cli.js scan"
}
}
```
之後即可執行：
```bash
pnpm scan
```
## 前置需求
需要 Node.js 20 以上。
```bash
node --version
pnpm --version
```
安裝相依套件：
```bash
pnpm install
```
確認 `playwright-cli` 可用：
```bash
pnpm --filter html-transform exec playwright-cli --version
```
若環境還沒有 Chromium：
```bash
pnpm --filter html-transform exec playwright-cli install-browser chromium
```
## 設定檔
設定檔不是工具執行的絕對必要條件；沒有設定檔時，工具會使用內建預設並讀取：
```text
packages/prototype/
```
本 repo 的 HTML prototype 位於根目錄 `./prototype`，不是 `./packages/prototype`。因此從 repo 根目錄執行 `node packages/html-transform/src/cli.js scan` 時，需要根目錄 `ht.config.mjs` 覆寫 `prototype` 路徑。
本 repo 根目錄目前使用最小設定：
```js
export default {
prototype: './prototype'
}
```
目前 MVP 只使用 `prototype`。`scan` 會讀取其中的 HTML prototype，也會讀取 `prototype/*.md` 作為 app-map 的輔助 domain guide。`frontend`、`backend`、`output`、`plan` 等欄位不會被 `doctor` 或 `scan` 使用，不需要為本 MVP 加入設定檔。
## Doctor
```bash
node packages/html-transform/src/cli.js doctor
```
檢查項目：
- `prototype` directory
- package-local `vite`
- `playwright-cli`
- `pnpm`
## Scan
```bash
node packages/html-transform/src/cli.js scan
```
`scan` 會自動：
- 用 Vite static server 提供 prototype。
- 用 `playwright-cli` 開啟每個 HTML。
- 等待 `networkidle`，再等待 500ms。
- 截取 desktop `1440 x 900` full-page screenshot。
- 產生 DOM summary。
- 產生 accessibility snapshot。
- 記錄 resource failure 與 console error/warning。
- 建立頁面級 `pageContract`。
- 驗證 contract 與 DOM evidence 是否明顯衝突。
- 讀取 `prototype/*.md` 的對照表，擷取 prototype 檔、舊 JSP、舊 PB、對應 Vue view 或功能描述。
- 產出 `.ht/app-map.json`，供通用 prompt 判斷 auth、legacy shell、feature page、layout 策略與舊系統對照。
## 產物
每個 HTML 的 capture artifact：
```text
.ht/cache/prototype/{page}/desktop-default.png
.ht/cache/prototype/{page}/dom-summary.json
.ht/cache/prototype/{page}/accessibility-tree.json
.ht/cache/prototype/{page}/capture-metadata.json
```
每個 HTML 的 contract artifact：
```text
.ht/app-map.json
.ht/spec/{page}.spec.json
.ht/spec/{page}.validation.json
.ht/spec/{page}.ui-contract.md
```
`.spec.json` 會包含 `pageContract`。`regions` 欄位目前仍保留，目的是相容既有資料形狀；不要把它視為 Stage 2 decomposition。
`.ht/app-map.json` 是跨頁面的應用結構推論。通用 prompt 應先讀它，再決定每個 prototype 是 `auth`、`legacy-shell-reference`、`feature-page` 或其他角色。MVP 固定策略是 template layout/style 優先，prototype 只提供內容與功能證據。
若 `prototype/*.md` 內有 markdown table 對照 prototype HTML，例如 `venue/query-room.html`，`scan` 會把匹配結果寫進 route：
```json
{
"prototype": "venue/query-room.html",
"guide": {
"source": "venue.md",
"legacyJsp": "zte_pro/zte451_02.jsp + zte451_02_1.jsp",
"legacyPb": "n_zte451.of_zte451_02 / of_zte451_02_1",
"targetView": "RoomQueryView.vue",
"description": null
},
"evidence": {
"prototypeGuide": "venue.md"
}
}
```
這些 guide 欄位只輔助 route 與舊系統對照理解；HTML capture、DOM summary、UI contract 與 screenshot 仍是畫面內容的主要 evidence。
## 驗證
修改本 package 後至少執行：
```bash
pnpm --filter html-transform typecheck
pnpm --filter html-transform test
node packages/html-transform/src/cli.js doctor
node packages/html-transform/src/cli.js scan
```