wsl-chrome-bridge 0.1.0 → 0.3.0

package/README-zh.md

@@ -0,0 +1,270 @@
+# wsl-chrome-bridge
+
+本專案主要提供一支 CLI `wsl-chrome-bridge`。
+
+在 [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) 眼中，`wsl-chrome-bridge` 將會是一個可執行的 Chrome。
+`wsl-chrome-bridge` 會在 WSL 端提供 DevTools 連線入口，並把 CDP 訊息橋接到 Windows Chrome。
+
+原有 `chrome-devtools-mcp` 的設定方式，只需調整 `--executablePath` 並增加特定參數，即可讓 WSL 下的 Agent 調用 Windows Chrome，且無須做任何系統層級的設定(如 portproxy 轉發 , WSL2 Mirrored Mode)。
+
+此構想是看到 [wsl-chrome-mcp](https://github.com/477174/wsl-chrome-mcp) 實作方式是利用 `powershell` 繞過限制，但由於此專案是以 MCP Server 方式提供服務，但我想繼續使用比較多人維護的 `chrome-devtools-mcp`，所以才寫了本專案作為橋接手段。
+
+## 0.2.0 重大變更（支援 Playwright）
+
+`0.2.0` 新增對 `playwright-mcp` 的支援，並且調整多項 bridge 參數行為與設定方式。
+
+若你是從 `0.1.0` 升級，請先閱讀升級說明文件：[UPGRADE-zh.md](./UPGRADE-zh.md)。
+
+## 基本運作方式
+
+```text
+[Chrome DevTools MCP]             [Playwright MCP]
+         |                              |
+      stdio pipe                remote-debugging-port
+         |                              |
+         +------[wsl-chrome-bridge]-----+
+                         |
+            PowerShell websocket relay
+                         |
+                 [Windows Chrome]
+```
+
+wsl-chrome-bridge 會：
+
+- 接收 `chrome-devtools-mcp` 與 `playwright-mcp` 傳入的 Chrome 啟動參數
+- 啟動 Windows Chrome（透過PowerShell）
+- 在 `chrome-devtools-mcp` 模式下，透過 stdio pipe（OS pipe）接收/回傳 CDP 訊息
+- 在 `playwright-mcp` 模式下，於本機建立對應 port 的 WebSocket proxy 後轉發 CDP 訊息
+- 透過 PowerShell WebSocket relay 雙向轉發 CDP 訊息到 Windows Chrome
+
+
+## 使用環境需求
+- Windows 11 安裝最新版 chrome。
+- Windows 11 需要有 powershell.exe 可供 WSL2 執行。
+- WSL2 需要有 Node 20+
+
+
+## 安裝與使用方式
+
+### 安裝方式
+
+於 WSL 環境下用以下方式擇一安裝 :
+
+1. 透過 `npm install -g wsl-chrome-bridge` 安裝。
+2. 下載原始碼後自行編譯，再以 `npm link` 安裝：
+
+```bash
+git clone https://github.com/pigochu/wsl-chrome-bridge.git
+cd wsl-chrome-bridge
+npm install
+npm run build
+npm link
+```
+
+### 使用方式 (以 codex 為例子)
+
+1. 找出 wsl-chrome-bridge 實際位置 , 假設是 `/home/pigochu/.local/share/mise/shims/wsl-chrome-bridge`。
+2. 設定檔撰寫，如以下範例 `.codex/config.toml`。
+
+`chrome-devtools-mcp` 最小可運作設定：
+
+```toml
+[sandbox_workspace_write]
+network_access = true
+
+[mcp_servers.chrome-devtools]
+command = "npx"
+args = [
+    "-y",
+    "chrome-devtools-mcp@latest",
+    "--executablePath",
+    "/home/pigochu/.local/share/mise/shims/wsl-chrome-bridge"
+]
+enabled = true
+```
+
+這是最小可運作設定。`wsl-chrome-bridge` 會啟動 Windows Chrome，並為 `chrome-devtools-mcp` 橋接 CDP 流量，不需要額外 bridge 專用參數。
+
+`playwright-mcp` 最小可運作設定（含 sandbox）：
+
+```toml
+[sandbox_workspace_write]
+network_access = true
+
+[mcp_servers.playwright]
+command = "npx"
+args = [
+    "-y",
+    "@playwright/mcp@latest",
+    "--browser",
+    "chrome",
+    "--sandbox",
+    "--executable-path",
+    "/home/pigochu/.local/share/mise/shims/wsl-chrome-bridge"
+]
+enabled = true
+
+[mcp_servers.playwright.env]
+DISPLAY = ":9999"
+```
+
+在 bridge + Windows 系統 Chrome 的情境下，加上 `--browser chrome` 可避免常見的上游 `--no-sandbox` 警告行為，並維持 Playwright 啟動行為穩定。
+
+> [!NOTE]
+> FAQ 章節有介紹 `--executablePath` 的路徑尋找的方式。
+> 其他設定寫法可參考 `agent-config-sample/.codex/`。
+
+## 安裝與建置
+
+```bash
+npm install
+npm run build
+```
+
+## 本地測試
+
+```bash
+npm test
+```
+
+測試分成兩層：
+
+- 單元測試：路徑轉換、參數標準化、bridge 啟動規劃
+- 情境測試：CLI 對 bridge runner 的參數傳遞整合
+
+
+## FAQ
+
+### `--executablePath` 如何找
+
+`chrome-devtools-mcp` 的 `--executablePath` 必須是「檔案路徑」，不能只填指令名（例如 `wsl-chrome-bridge`）。
+
+#### 情境 A: 未使用 Node 版本管理工具（僅系統 Node）
+
+這種情境下，通常就是用 `command` 找出絕對路徑再填入設定：
+
+```bash
+command -v wsl-chrome-bridge
+```
+
+把輸出結果直接填進 `--executablePath`。
+
+#### 情境 B: 使用 mise 管理多版本 Node（建議做法）
+
+若你使用 [mise](https://mise.jdx.dev/) 且可能切換多個 Node 版本，不建議把 `command -v` 找到的版本化路徑（例如 `.../installs/node/<version>/bin/...`）直接寫死在設定檔。
+
+建議改用 mise shim 固定入口：
+
+如以下命令所印出的絕對路徑
+```bash
+echo $HOME/.local/share/mise/shims/wsl-chrome-bridge
+```
+或直接檢查：
+
+```bash
+ls -la ~/.local/share/mise/shims/wsl-chrome-bridge
+```
+
+#### 差異總結
+
+- 不使用版本管理工具時，透過 `command -v` 找絕對路徑是可行且直接的方法。
+- 使用 mise 多版本 Node 時，建議使用 `/home/<user>/.local/share/mise/shims/wsl-chrome-bridge`，避免 Node 版本切換後路徑失效。
+
+### 為什麼 Playwright 需要設定 `DISPLAY`
+
+在 WSL/Linux 環境下，`playwright-mcp` 啟動瀏覽器時會先判斷圖形顯示環境。  
+若 `DISPLAY` 沒有設定，Playwright 通常會改成 headless 行為（即使你沒有手動指定 `--headless`）。
+
+而這個判斷是在 bridge 之前就完成，所以 `wsl-chrome-bridge` 無法在後段覆蓋該決策。  
+如果你希望在 Windows 看到實際 Chrome 視窗，請於 MCP `env` 額外設定 `DISPLAY`（例如 `DISPLAY=:999`）。
+
+### 上游 MCP 結束時，Headless 與非 Headless 行為
+
+`wsl-chrome-bridge` 在上游 MCP（例如 `chrome-devtools-mcp` / `playwright-mcp`）結束時，採用以下生命週期策略：
+
+- 若 Chrome 是以 headless 啟動，bridge 一律會結束該 Chrome 行程。
+- 若 Chrome 不是以 headless 啟動（headed / non-headless），bridge 一律保留該 Chrome 行程。
+
+這是刻意設計的行為，與原生 Playwright 在部分流程下的預設行為可能不同。
+
+### 為什麼 Playwright 可能出現 `--no-sandbox` 警告
+
+`playwright-mcp` 若未明確指定 browser channel，可能會產生含 `--no-sandbox` 的啟動參數。  
+在有視窗的 Chrome 中，會看到這類警告列：
+`你正在使用不受支援的命令列標幟: --no-sandbox`
+
+建議在 Playwright MCP args 明確加入：
+
+```text
+--browser chrome
+```
+
+這樣在常見 bridge 設定下可避免上游傳入 `--no-sandbox`。
+
+
+### `--user-data-dir` 說明
+
+`wsl-chrome-bridge` 現在支援上游 MCP 直接傳入 `--user-data-dir` / `--userDataDir`。
+
+Playwright 可能會把原本的 Windows 風格路徑先 resolve 成 Linux 路徑，並在本地先建立一個空目錄再交給 bridge。  
+bridge 目前會檢查該路徑，且僅在「空目錄」時才會安全刪除；非空目錄不會刪除。
+
+`chrome-devtools-mcp` 一般不會有這個本地空目錄副作用。
+
+另外，bridge 只會把「Windows 風格」的 user-data-dir 傳給 Windows Chrome。像 `/cwd/%TEMP%\\...` 這種被 resolve 過的形式會先嘗試還原。
+
+若上游沒有送出 `--user-data-dir`，或送出的值最後無法還原為 Windows 風格路徑（被過濾），bridge 會自動使用預設值：
+
+```text
+%TEMP%\wsl-chrome-bridge\profile-default
+```
+
+這可確保 Windows Chrome 啟動時一律有可用的 profile 目錄，避免因未帶 profile 導致的啟動行為差異。
+
+為了避免 Playwright 差異，並統一 `chrome-devtools-mcp` / `playwright-mcp` 的設定風格，建議優先使用：
+
+```toml
+WSL_CHROME_BRIDGE_USER_DATA_DIR = "%TEMP%\\wsl-chrome-bridge\\chrome-profile-xxx"
+```
+
+`--user-data-dir` 仍可使用，但建議把 `WSL_CHROME_BRIDGE_USER_DATA_DIR` 當成預設寫法。
+
+
+## 設定參數重要說明
+
+- `--user-data-dir` / `--userDataDir` : 僅當最終值為 Windows 風格（包含 `%TEMP%\\...` 還原成功）才會帶入啟動參數。
+- 若 `--user-data-dir` 未提供，或被過濾（非 Windows 風格），bridge 會回退到 `%TEMP%\\wsl-chrome-bridge\\profile-default`。
+- `playwright-mcp --browser chrome` : 建議搭配 bridge 使用，可避免上游送出 `--no-sandbox` 警告列。
+
+## 環境變數重要說明
+
+- `WSL_CHROME_BRIDGE_USER_DATA_DIR=%TEMP%\\...` : 建議預設使用。可固定指定 Windows Chrome profile 路徑，且優先於上游 `--user-data-dir`，可避開 Playwright 本地空目錄副作用，並統一兩種 MCP 設定風格。
+- `WSL_CHROME_BRIDGE_EXECUTABLE_PATH=C:\\...` : 可選環境變數，用於覆蓋 Windows Chrome 的執行檔路徑。
+- `WSL_CHROME_BRIDGE_REMOTE_DEBUG_PORT=9222` : 以環境變數指定 Windows Chrome debug port。若都沒指定，bridge 改為隨機 port，不再固定 9222。
+- bridge 會在 Windows 端先探測 port 可用性。若是固定 port 模式且該 port 已被占用，會在啟動前直接報錯。
+- `WSL_CHROME_BRIDGE_DEBUG_FILE=/tmp/xxx.log` : 以環境變數指定 bridge debug log 輸出路徑。
+- `WSL_CHROME_BRIDGE_DEBUG_LEVEL=all|important` : 可選 debug 詳細度。`important`（預設）只記錄 session / 開頁導覽 / 斷線相關的重要 method 與錯誤回應；`all` 會記錄全部 CDP relay 訊息。
+- `WSL_CHROME_BRIDGE_DEBUG_RAW_DIR=/tmp/wsl-chrome-bridge-raw` : 以環境變數指定 raw CDP 內容輸出目錄。每筆 request/response/event 會獨立寫入一個 `raw-<timestamp>.log` 檔案，且 `WSL_CHROME_BRIDGE_DEBUG_FILE` 的 relay log 會包含對應的 `rawPath`。
+
+### 已確認無法使用的參數
+
+以下列表為搭配本程式確定無法使用 `chrome-devtools-mcp` 原始參數
+
+- `--browser-url` : 這是遠端連線設定，一旦啟用就會讓 `chrome-devtools-mcp` 走 remote mode 而非 pipe mode，無法與 `wsl-chrome-bridge` 配合。
+
+
+> 其他 `chrome-devtools-mcp` 提供的原始參數未必全部能使用，本程式尚在開發中，也沒有完全測試過所有原始參數，故只列出目前已經測試過的。
+
+## For Developer
+
+開發者可參考 bridge 連線生命週期與恢復策略文件：
+
+- [docs/BRIDGE_CONNECTION_LIFECYCLE-zh.md](./docs/BRIDGE_CONNECTION_LIFECYCLE-zh.md)
+
+開發時所用技術棧：
+
+- Node 24
+- TypeScript v6
+- Commander v14
+- ws v8.20
+- 測試框架: Vitest v4.1

package/README.md

@@ -8,51 +8,70 @@
 
 This project provides a CLI tool: `wsl-chrome-bridge`.
 
-From `chrome-devtools-mcp`'s perspective, `wsl-chrome-bridge` behaves like a Chrome executable.
+From [`chrome-devtools-mcp`](https://github.com/ChromeDevTools/chrome-devtools-mcp)'s perspective, `wsl-chrome-bridge` behaves like a Chrome executable.
 It provides a DevTools connection entry in WSL and bridges CDP messages to Windows Chrome.
 
 With the original `chrome-devtools-mcp` setup, you only need to change `--executablePath` and add a few bridge-specific arguments to let WSL agents control Windows Chrome, without system-level setup (for example `netsh interface portproxy` forwarding or WSL2 mirrored mode).
 
 This idea came from [wsl-chrome-mcp](https://github.com/477174/wsl-chrome-mcp), which uses PowerShell to work around the same limitation. That project provides MCP server capability itself, while this project keeps using the widely maintained `chrome-devtools-mcp` and adds a bridge layer.
 
+## Breaking Changes in 0.2.0 (Playwright Support)
+
+`0.2.0` adds `playwright-mcp` compatibility and includes multiple bridge argument/configuration adjustments.
+
+If you are upgrading from `0.1.0`, read the upgrade guide first: [UPGRADE.md](./UPGRADE.md).
+
 ## How It Works
 
 ```text
-[chrome-devtools-mcp]
-       |
-    stdio pipe
-       |
-[wsl-chrome-bridge]
-       |
- PowerShell websocket relay
-       |
-[Windows Chrome]
+[Chrome DevTools MCP]             [Playwright MCP]
+         |                              |
+      stdio pipe                remote-debugging-port
+         |                              |
+         +------[wsl-chrome-bridge]-----+
+                         |
+            PowerShell websocket relay
+                         |
+                 [Windows Chrome]
 ```
 
 `wsl-chrome-bridge` will:
 
-- Accept Chrome launch arguments from `chrome-devtools-mcp`
+- Accept Chrome launch arguments from both `chrome-devtools-mcp` and `playwright-mcp`
 - Launch Windows Chrome via PowerShell
-- Receive/return CDP messages through stdio pipe (OS pipe)
+- In `chrome-devtools-mcp` mode, receive/return CDP messages through stdio pipe (OS pipe)
+- In `playwright-mcp` mode, create a local WebSocket proxy on the mapped port and forward CDP traffic through it
 - Relay CDP messages bidirectionally to Windows Chrome through PowerShell websocket relay
 
 ## Requirements
 
 - Windows 11 with the latest Chrome installed
 - `powershell.exe` available for WSL2
-- Node 20+
+- WSL2 with Node 20+
 
 ## Install and Use
 
 ### Install
 
+In WSL, choose one of the following installation methods:
+
 1. Install globally with `npm install -g wsl-chrome-bridge`.
-2. Or clone source and install with `npm link`.
+2. Or clone source, build it, then install with `npm link`:
+
+```bash
+git clone https://github.com/pigochu/wsl-chrome-bridge.git
+cd wsl-chrome-bridge
+npm install
+npm run build
+npm link
+```
 
 ### Example (Codex)
 
 1. Find the actual path of `wsl-chrome-bridge`, for example `/home/pigochu/.local/share/mise/shims/wsl-chrome-bridge`.
-2. Configure `.codex/config.toml` like this:
+2. Configure `.codex/config.toml` like this.
+
+Minimal working `chrome-devtools-mcp` setup:
 
 ```toml
 [sandbox_workspace_write]
@@ -64,28 +83,41 @@ args = [
     "-y",
     "chrome-devtools-mcp@latest",
     "--executablePath",
-    "/home/pigochu/.local/share/mise/shims/wsl-chrome-bridge",
-    "--chrome-arg=--window-size=720,400",
-    "--chrome-arg=--new-window",
-    "--chrome-arg=--user-data-dir=%TEMP%\\wsl-chrome-bridge\\chrome-profile-test",
-    "--chrome-arg=--bridge-remote-debugging-port=9222",
-    "--chrome-arg=--bridge-debug-file=/tmp/wsl-chrome-bridge-debug.log",
-    "--no-sandbox"
+    "/home/pigochu/.local/share/mise/shims/wsl-chrome-bridge"
 ]
 enabled = true
 ```
 
-In this example, Windows Chrome is launched with port `9222`, and `wsl-chrome-bridge` relays traffic between Windows Chrome and `chrome-devtools-mcp`.
+This is the minimum working setup. `wsl-chrome-bridge` launches Windows Chrome and relays CDP traffic for `chrome-devtools-mcp` without extra bridge-specific arguments.
 
-> See the FAQ for how to locate `--executablePath`.
+Minimal working `playwright-mcp` setup (with sandbox):
 
-## Development Stack
+```toml
+[sandbox_workspace_write]
+network_access = true
 
-- Node 24
-- TypeScript v6
-- Commander v14
-- ws v8.20
-- Test framework: Vitest v4.1
+[mcp_servers.playwright]
+command = "npx"
+args = [
+    "-y",
+    "@playwright/mcp@latest",
+    "--browser",
+    "chrome",
+    "--sandbox",
+    "--executable-path",
+    "/home/pigochu/.local/share/mise/shims/wsl-chrome-bridge"
+]
+enabled = true
+
+[mcp_servers.playwright.env]
+DISPLAY = ":9999"
+```
+
+In bridge + system Chrome usage, `--browser chrome` helps avoid upstream `--no-sandbox` warning behavior while keeping Playwright launch behavior stable.
+
+> [!NOTE]
+> See the FAQ for how to locate `--executablePath`.
+> For more configuration patterns, see `agent-config-sample/.codex/`.
 
 ## Build
 
@@ -123,7 +155,7 @@ Then paste that output into `--executablePath`.
 
 #### Scenario B: Using mise for multiple Node versions (recommended)
 
-If you use mise and switch Node versions, do not hardcode a versioned path from `command -v` (for example `.../installs/node/<version>/bin/...`).
+If you use [mise](https://mise.jdx.dev/) and switch Node versions, do not hardcode a versioned path from `command -v` (for example `.../installs/node/<version>/bin/...`).
 
 Prefer the mise shim entry:
 
@@ -142,23 +174,97 @@ ls -la ~/.local/share/mise/shims/wsl-chrome-bridge
 - Without a version manager, `command -v` is a direct and valid way to get an absolute path.
 - With mise multi-version Node, prefer `/home/<user>/.local/share/mise/shims/wsl-chrome-bridge` so path does not break when Node versions change.
 
-### Why `--user-data-dir` is not recommended
+### Why Playwright needs `DISPLAY`
+
+In WSL/Linux, `playwright-mcp` checks display availability before launching the browser.  
+If `DISPLAY` is not set, Playwright often switches to headless behavior (even when you did not explicitly pass `--headless`).
+
+That decision happens upstream before bridge logic starts, so `wsl-chrome-bridge` cannot override it later.  
+If you want to see a visible Chrome window on Windows, set `DISPLAY` in MCP `env` (for example `DISPLAY=:999`).
+
+### Headless vs headed behavior on upstream MCP exit
+
+`wsl-chrome-bridge` applies the following lifecycle policy when upstream MCP exits (for example `chrome-devtools-mcp` / `playwright-mcp`):
+
+- If Chrome was started in headless mode, bridge always terminates that Chrome process.
+- If Chrome was started in headed mode (non-headless), bridge always keeps that Chrome process.
 
-`chrome-devtools-mcp` checks whether `--user-data-dir` is an absolute path (starts with `/`). If not, it may be treated as relative, which does not work well with `%TEMP%\\...` style values. Use `--chrome-arg=--user-data-dir=...` instead.
+This behavior is intentional and can differ from native Playwright defaults in some workflows.
+
+### Why Playwright may show `--no-sandbox` warning
+
+When `playwright-mcp` is launched without an explicit browser channel, it may resolve to launch args that include `--no-sandbox`. In headed Chrome, this shows the warning banner:
+`You are using an unsupported command-line flag: --no-sandbox`.
+
+For bridge usage with system Chrome, recommend adding:
+
+```text
+--browser chrome
+```
+
+This keeps Playwright on the Chrome channel and avoids passing `--no-sandbox` in the common setup.
+
+### About `--user-data-dir`
+
+`wsl-chrome-bridge` accepts direct `--user-data-dir` / `--userDataDir` values from upstream MCP.
+
+Playwright may resolve a Windows-style path into a Linux path and pre-create a local empty directory before bridge logic starts.  
+Bridge checks that local path and removes it only when it is an empty directory. Non-empty directories are never removed.
+
+`chrome-devtools-mcp` typically does not create this local empty-directory artifact.
+
+Bridge only passes Windows-style user-data-dir values to Windows Chrome. Path-resolved forms like `/cwd/%TEMP%\\...` are restored back to the original Windows-style path when possible.
+
+If upstream does not send `--user-data-dir`, or the final value cannot be restored as a Windows-style path (and gets filtered), bridge automatically falls back to:
+
+```text
+%TEMP%\wsl-chrome-bridge\profile-default
+```
+
+This ensures Windows Chrome always starts with a usable profile directory and avoids launch behavior differences when no profile is provided.
+
+To avoid Playwright-specific differences and keep a unified config style across `chrome-devtools-mcp` and `playwright-mcp`, prefer setting:
+
+```toml
+WSL_CHROME_BRIDGE_USER_DATA_DIR = "%TEMP%\\wsl-chrome-bridge\\chrome-profile-xxx"
+```
+
+`--user-data-dir` still works, but `WSL_CHROME_BRIDGE_USER_DATA_DIR` is recommended as the default style.
 
 ## Important Argument Notes
 
-- `--user-data-dir`: this original `chrome-devtools-mcp` option is not recommended here. It may pass an unexpected path and should be avoided.
-- `--chrome-arg=--user-data-dir=...`: set Chrome profile path.
-- `--chrome-arg=--bridge-chrome-executablePath=...`: optionally set the Chrome executable absolute path (Windows format required, for example `C:\\...`).
-- `--chrome-arg=--bridge-remote-debugging-port=9222`: optionally set the Windows Chrome debug port. Default is `9222` if omitted. This is a bridge-only argument, not a native Chrome flag.
-- `--chrome-arg=--bridge-debug-file=/tmp/xxx.log`: optional debug output file in WSL.
+- `--user-data-dir` / `--userDataDir`: Bridge only forwards this flag when the final value is Windows-style (including restored `%TEMP%\\...` forms).
+- If `--user-data-dir` is missing or filtered (non-Windows-style), bridge falls back to `%TEMP%\\wsl-chrome-bridge\\profile-default`.
+- `playwright-mcp --browser chrome`: recommended for bridge usage to avoid upstream `--no-sandbox` banner in headed Chrome.
+
+## Important Environment Variables
+
+- `WSL_CHROME_BRIDGE_USER_DATA_DIR=%TEMP%\\...`: recommended default profile setting. It forces the Windows Chrome profile path, takes precedence over upstream `--user-data-dir`, avoids Playwright local empty-dir artifacts, and keeps a unified config style across MCP servers.
+- `WSL_CHROME_BRIDGE_EXECUTABLE_PATH=C:\\...`: optional environment variable to override the Windows Chrome executable path.
+- `WSL_CHROME_BRIDGE_REMOTE_DEBUG_PORT=9222`: optional environment variable for Windows Chrome debug port. If no port is specified, bridge uses a random port instead of fixed `9222`.
+- Bridge now probes port availability on Windows before launching Chrome. In fixed-port mode, startup fails fast if that port is already occupied.
+- `WSL_CHROME_BRIDGE_DEBUG_FILE=/tmp/xxx.log`: optional debug output file in WSL.
+- `WSL_CHROME_BRIDGE_DEBUG_LEVEL=all|important`: optional debug verbosity level. `important` (default) logs only important session/navigation/disconnect-related CDP methods and error responses. `all` logs all CDP relay traffic.
+- `WSL_CHROME_BRIDGE_DEBUG_RAW_DIR=/tmp/wsl-chrome-bridge-raw`: optional directory to store full raw CDP payload files. Each request/response/event payload is written as a separate `raw-<timestamp>.log` file, and `WSL_CHROME_BRIDGE_DEBUG_FILE` includes the corresponding `rawPath` for each relay log entry.
 
 ### Known incompatible original arguments
 
-The following original `chrome-devtools-mcp` options are currently known as incompatible in this bridge setup:
+The following original `chrome-devtools-mcp` option is currently known as incompatible in this bridge setup:
 
-- `--user-data-dir`: internal handling in `chrome-devtools-mcp` may turn an intended Windows-style path into Linux-style behavior, so this option is filtered out by this bridge and is not recommended for profile path configuration.
-- `--browser-url`: this enables remote-connection mode in `chrome-devtools-mcp` instead of pipe mode, so it cannot work with `wsl-chrome-bridge`. Use `--chrome-arg=--bridge-remote-debugging-port=...` instead.
+- `--browser-url`: this enables remote-connection mode in `chrome-devtools-mcp` instead of pipe mode, so it cannot work with `wsl-chrome-bridge`.
 
 > Other original `chrome-devtools-mcp` arguments are not all fully validated yet. This project is still under development, so only currently tested limitations are listed here.
+
+## For Developer
+
+Developer lifecycle and recovery reference:
+
+- [docs/BRIDGE_CONNECTION_LIFECYCLE.md](./docs/BRIDGE_CONNECTION_LIFECYCLE.md)
+
+Development stack:
+
+- Node 24
+- TypeScript v6
+- Commander v14
+- ws v8.20
+- Test framework: Vitest v4.1

package/UPGRADE-zh.md

@@ -0,0 +1,122 @@
+# Upgrade Guide: 0.1.0 -> 0.2.0
+
+本文件說明從 `wsl-chrome-bridge` `0.1.0` 升級到 `0.2.0` 需要調整的設定。
+
+## 1. 必做變更
+
+### 1.1 改用環境變數設定 debug log
+
+`0.2.0` 開始，以下舊寫法已棄用且會報錯：
+
+- `--chrome-arg=--bridge-debug-file=/tmp/xxx.log`
+
+請改為 MCP `env`：
+
+```toml
+WSL_CHROME_BRIDGE_DEBUG_FILE = "/tmp/debug-bridge.log"
+```
+
+### 1.2 改用環境變數設定 Chrome 執行檔路徑
+
+`0.2.0` 開始，以下舊寫法已棄用且會報錯：
+
+```text
+--bridge-chrome-executablePath=C:\Custom\Chrome\chrome.exe
+```
+
+若你是透過 `chrome-devtools-mcp` 包一層傳入，常見會是：
+
+```text
+--chrome-arg=--bridge-chrome-executablePath=C:\Custom\Chrome\chrome.exe
+```
+
+請改為 MCP `env`：
+
+```toml
+WSL_CHROME_BRIDGE_EXECUTABLE_PATH = "C:\\Custom\\Chrome\\chrome.exe"
+```
+
+### 1.3 正式支援 `--user-data-dir`，並新增建議環境變數
+
+`0.2.0` 會只把「Windows 風格」路徑帶給 Windows Chrome。  
+像 `/cwd/%TEMP%\\...` 這種被 resolve 過的形式會嘗試還原回 Windows 路徑。
+
+另外，Playwright 可能先建立本地端目錄（Linux 路徑）再交給 bridge。  
+bridge 現在會檢查該路徑，若是空目錄就安全刪除；非空目錄則保留。  
+`chrome-devtools-mcp` 一般不會有這個空目錄副作用。
+
+因此，雖然 `--user-data-dir` 仍可用，仍建議優先在 MCP `env` 設定：
+
+```toml
+WSL_CHROME_BRIDGE_USER_DATA_DIR = "%TEMP%\\wsl-chrome-bridge\\chrome-profile-xxx"
+```
+
+`--user-data-dir` 仍可使用，但建議作為次要方式，並以 `WSL_CHROME_BRIDGE_USER_DATA_DIR` 統一兩種 MCP 的設定風格。
+
+若你原本使用舊寫法：
+
+```text
+--chrome-arg=--user-data-dir=%TEMP%\wsl-chrome-bridge\chrome-profile-xxx
+```
+
+升級到 `0.2.0` 建議改成上方 `WSL_CHROME_BRIDGE_USER_DATA_DIR`。
+
+## 2. 建議變更
+
+### 2.1 以環境變數指定固定 debug port（可選）
+
+若你需要固定 port（例如防火牆、除錯工具綁定），可設定：
+
+```toml
+WSL_CHROME_BRIDGE_REMOTE_DEBUG_PORT = "9222"
+```
+
+若你原本使用舊寫法：
+
+```text
+--chrome-arg=--bridge-remote-debugging-port=9222
+```
+
+升級到 `0.2.0` 建議改成 MCP `env` 的 `WSL_CHROME_BRIDGE_REMOTE_DEBUG_PORT`。  
+建議統一用環境變數管理，避免不同 MCP 設定方式造成混用。
+
+若未指定，`0.2.0` 預設改為「隨機可用 port」，不再固定 `9222`。
+
+### 2.2 chrome-devtools 與 playwright 請用不同 profile（可選但強烈建議）
+
+若兩者共用同一個 profile（不論是 `--user-data-dir` 或 `WSL_CHROME_BRIDGE_USER_DATA_DIR`），可能互相影響同一個 Windows Chrome 實例。  
+建議各自指定不同 profile 目錄。
+
+### 2.3 Playwright 建議加上 `--browser chrome`
+
+在 bridge + Windows Chrome 情境下，`playwright-mcp` 若未明確指定 browser channel，可能出現上游傳入 `--no-sandbox`，並在 Chrome 顯示警告列。
+
+建議於 Playwright MCP args 額外加入：
+
+```text
+--browser chrome
+```
+
+這是設定層級的建議，不影響 bridge 功能，但可避免常見的 `--no-sandbox` UI 警告。
+
+## 3. 驗證清單
+
+升級後可用以下方式快速驗證：
+
+1. 啟動 `chrome-devtools-mcp`，確認 bridge 可正常開頁。
+2. 啟動 `playwright-mcp`，確認可正常導頁（例如 `https://www.google.com`）。
+3. 檢查 debug log（`WSL_CHROME_BRIDGE_DEBUG_FILE`）：
+   - 有 `launchPlan` / `windowsArgs` 記錄
+   - `windowsUserDataDir` 或 `windowsArgs` 中的 `--user-data-dir` 為預期 Windows 路徑
+
+## 4. 範例（MCP env）
+
+```toml
+env = {
+  WSL_CHROME_BRIDGE_DEBUG_FILE = "/tmp/debug-bridge.log",
+  WSL_CHROME_BRIDGE_REMOTE_DEBUG_PORT = "9222",
+  WSL_CHROME_BRIDGE_USER_DATA_DIR = "%TEMP%\\wsl-chrome-bridge\\chrome-profile-bridge"
+}
+```
+
+`WSL_CHROME_BRIDGE_REMOTE_DEBUG_PORT` 可省略；省略時 bridge 會自動使用隨機可用 port。