feat: UI 商业化改造 + 连接前 tmux 会话选择（真机验证）

按 Claude Design 定稿（归档在 docs/design/）重做 UI，并把 tmux 从
「从不自动进」修成「连接前探测 → 让用户选会话」。

设计令牌与导航地基
- Theme 拆三层：TXAccent(恒定 blurple) / TXChrome(中性阶×4 表) / TXFlavor(Catppuccin 终端)
- vendor JetBrains Mono 四权重（附 OFL 许可）
- AppRouter + SessionManager：多会话并存，路由与会话生命周期解耦
- SessionCanvas 常驻挂载会话 surface（摘除即丢内容，也是缩回动画的前提）

按设计稿落地的屏
- 沉浸轨道页：56pt 轨道 + 浮起标题/状态胶囊 + 侧边栏三态（遮罩不 resize、Pin 各一次）
- 首页：活动会话卡（readViewportText 文本镜像）+ 主机网格 + 筛选 chips
- 关闭二次确认（tmux 仅断开 / 原生窗口两套文案）、分屏菜单、pane 拖拽条
- 空状态：首次运行 / 无会话 / 搜索无命中 / 连接中·失败·已关闭

tmux 真实链路（真机查出并修掉 4 个 bug）
- 全代码库从来没人发起 attach → 连接前探测 + 会话选择器（接回 / 新建 / 原生终端）
- format 分隔符 tab 经 PTY 变成下划线 → 改用 |:|
- controller 变化不冒泡到 session → Combine 转发（否则数据解析对了 UI 不刷新）
- 当前会话名不能靠 session_attached 反推 → 改用 display-message

传输层：SSH connect 加超时（原来阻塞到系统 TCP 超时 75s+）
无头验证设施：假会话 fixture · terminalx://ui/* 驱动 · 横屏截图脚本 · 对拍走查法
TXCore 45 tests 绿（新增 5 个会话探测单测）

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

docs/HANDOFF.md

@@ -115,4 +115,177 @@
 ### 10.3 待续（UI）
 - 会话缩略卡区（Moshi 首屏实时终端预览横滑，需会话管理）；设置页字体/工具栏配置；导航壳打磨；终端工具栏 accent tint（`inputAccessoryStyle` SwiftUI 未暴露需桥接）。
 - 无头 UI 测试：`idb ui tap x y`（Python3.14 需事件循环 shim `/tmp/idbrun.py`；坐标=屏幕像素×0.5，注意设备朝向）。诊断埋点(GKDBG/txDbg*)已清理；MOSHDBG/TMUXDBG/M4DBG 仍在(旧 cleanup-todo)。
+
+## 11. Hosts / Keychain / Tailscale 三分离管理（2026-07-24 本轮，对标 Termius）
+
+把连接拆成 **Hosts / Keychain(凭据) / Tailscale 连接** 三者分别管理，iPad 优先。设计阶段咨询 Fable 顾问（Q1–Q5 裁决）。**BUILD SUCCEEDED + 模拟器 idb 截图全流程验证 + TXCore 40 tests 绿。**
+
+### 11.1 数据模型（app 层新文件）
+- `Credential.swift`：`Credential`(凭据 meta，无机密) + `CredentialSecret`(自描述机密)。Kind: password / privateKey(source: pasted/imported/generated, publicKeyBlob) / secureEnclave(占位)。
+- `CredentialStore.swift`：`@MainActor protocol CredentialStore`(list/secret(for:)/upsert/delete，meta 与机密分离) + `FileCredentialStore`(沙盒 `credentials.json`，版本化信封 `{"scheme":"plaintext-v1"}`，0600+`isExcludedFromBackup`+`completeFileProtection`)。**不自造加密**：无根信任下伪安全；签名后换 Keychain 后端即可（协议已抽象）。
+- `TailscaleStore.swift`：`TailscaleConnection`(每个=一个常驻 tsnet 节点；`stateDirName="tsnet-<uuid>"` 创建即固化终身不变——tsnet 无文件锁，同 Dir 双 Up 损坏状态) + `TailscaleStore`(tailnets.json，无机密；authKey 注册后即弃)。
+- `HostStore.swift`：`SavedHost` 改为 `auth: AuthRef`(.inlinePassword / .credential(id)) + `tailscaleID: UUID?`；自定义 decoder 迁移旧 inline username/password 为 `.inlinePassword`（不造幽灵凭据）。
+
+### 11.2 签名映射 `CredentialAuth.swift`（复用既有三认证路径，传输层零改动）
+- password → `.password`；生成软件 P-256 → `SigningKeyProvider.from(x963:)` → `.publicKeyCallback`(路径A)；粘贴/导入 PEM → `.privateKey`(libssh2 `publickey_frommemory` 路径B)。
+- **关键：`SSHSession.authenticate()` 三分支(.password/.privateKey/.publicKeyCallback)早已全部实现**，本次无需动 TXTransport。
+- `SigningKeyProvider` 加 `from(x963:)`/`generateSoftwareP256()`/`secureEnclaveAvailable()`(非持久探测，签名真机自动点亮 Face ID UI)。openssh-key-v1 mbedTLS 不认 → UI 警告提示 `ssh-keygen -p -m PEM` 转换。
+
+### 11.3 多 tsnet 节点 `TsnetRegistry.swift`（替换旧单例 `TsnetManager`）
+- 单例 `@unchecked Sendable`+锁，按 connID **懒启动/Up 后常驻/LRU 限 3/in-flight 去重**。Fable 经 tsnet v1.102.0 源码确认一进程多 `tsnet.Server` 官方支持（dial 走具体 node 句柄无全局路由→重叠 100.x 不误连；红线仅 stateDir 唯一）。
+- **坑：`TsnetbridgeNode`/`MoshRelay` 非 Sendable**，不能在 `Task.detached` 捕获或跨 actor 传 → mosh relay/wakeUp 收进 registry 按 connID 操作，model 只留 `activeConnID`（不再持 node）。
+
+### 11.4 连接编排（`SSHTerminalModel`）
+- `connect(to:)` 解析 AuthRef+tailscaleID → `EgressPlan`(.direct/.tsnet(connID,stateDir,hostname,authKey))；`startConnect` 统一构造 config，host key pin 命名空间=`egressPlan.egressKey`(`direct`/`tsnet-<uuid>`)。删实例级 `tsnetAuthKey`/`TsnetManager` 单例。
+- 无头验证：`-txTsnetKey` 合成临时连接（固定 connID + stateDir `tsnet-main` 复用模拟器身份）→ 启动参数矩阵不回归（已验证直连 SSH 到 127.0.0.1:22 走通 host key 校验+密码认证）。
+- `model.bind(credentials:tailscale:)` 由 ContentView 注入两 Store。
+
+### 11.5 UI（`ContentView` + 4 个 View 文件 + `UIComponents.swift`）
+- `RootSplitView`=`NavigationSplitView` 侧栏(§连接:主机 / §保险库:Keychain·Known Hosts / §网络:Tailscale / 设置)+详情；iPhone 紧凑自动坍缩。终端改 `.fullScreenCover($model.showsTerminal)` 全屏盖（退出回列表，状态保留）。
+- `HostsView.swift`(列表+HostCard+HostEditorView：认证 segmented[直接输入/从 Keychain 选]+出口 Picker[Direct/各 Tailscale])、`KeychainView.swift`(列表+CredentialEditorView：密码/SSH密钥[生成·粘贴·导入]/Face ID 占位)、`TailscaleView.swift`(列表+编辑器 name/hostname/authKey+注册按钮经 registry Up+SelfIP)、`SettingsView.swift`(主题+关于 + `KnownHostsView` pin 查看/删除)。
+
+### 11.6 未验证（需用户实时资源）
+真 tsnet 多节点 Up（需 authkey）、密钥/凭据成功登录（需服务器信任 key）、mosh over 新 egress plan。这些在有凭据时按 §8 流程补测。
+
+---
+
+## 12. Demo → 商业化 UI/UE 改造（2026-07-25 起，按 Claude Design 定稿）
+
+**设计定稿**（hifi，含精确 token）：`docs/design/UI-DESIGN-HANDOFF.md` + `terminalX-iPadOS.dc.html`（13 屏画板）。
+渲染对拍：`python3 docs/design/render-screens.py` 拆屏 → headless Chrome 逐屏截 PNG。规划级裁决咨询 Fable 顾问。
+
+**总判断**：差距不在样式而在结构。三处必须先拆的地基——① chrome 从 Catppuccin 派生改为 Nocturne 中性阶 + 恒定 blurple；② `NavigationSplitView`+`fullScreenCover` 改路由 + 会话常驻画布；③ 单会话模型改多会话并存。
+
+### 12.1 路线图（6 阶段，UI-1/UI-2 已完成）
+| 阶段 | 内容 | 状态 |
+|---|---|---|
+| UI-1 | 设计令牌地基（Nocturne chrome + blurple + JetBrains Mono） | ✅ 完成 |
+| UI-2 | 导航与多会话状态模型（AppRouter/SessionManager/SessionCanvas） | ✅ 完成 |
+| UI-3 | 终端主界面：56pt 轨道 + 浮起双胶囊 + 侧边栏三态 | ✅ 完成（pane 缝拖拽待做） |
+| UI-4 | 首页会话卡 + 关闭确认 + 分屏菜单 + pane 拖拽 | ✅ 完成（pane 拖拽待真机 tmux 验证） |
+| UI-5 | 设置·外观 + 键盘体系（GCKeyboard 检测 + 全套 ⌘ 快捷键） | 待做 |
+| UI-6 | 竖屏参数化 + iPhone 首版 | 待做 |
+
+### 12.2 UI-1 设计令牌（`Theme.swift` 重写）
+- 三层分工：`TXAccent`（Nocturne blurple 8 档，**恒定不随主题变**，只做线/点/选中底/文字）· `TXChrome`（chrome 中性阶 14 档，**4 张预生成表**）· `TXFlavor`（Catppuccin flavor，驱动终端 + 状态语义色）。`TXPalette` 是门面，旧取色名（`p.accent`/`p.textPrimary`…）保留为 computed，逐屏重写时再换直通名。
+- chrome 表推导：**Mocha 用设计交付的精确锚点值**；Macchiato/Frappé 按 flavor base 相对 Mocha 的 HSL 差平移（文字阶抬升幅度收一半，保对比度）；Latte 是唯一浅色，整体反转手工写（仍不用纯黑纯白）。切 flavor → chrome 变阶、accent 不变。
+- JetBrains Mono 四权重 vendor 进 `apps/TerminalX/Resources/Fonts/`（附 OFL.txt，OFL-1.1 要求随分发）。**必须平铺 bundle 根**（`UIAppFonts` 值不带目录）→ project.yml 用 group 而非 folder reference。`TX.Font.mono` 按 weight 映射 PostScript 名，缺失时 SwiftUI 自动回退。
+
+### 12.3 UI-2 导航与多会话（新 `AppRouter.swift`/`SessionManager.swift`，`SSHTerminalModel`→`TerminalSession`）
+- `AppRoute = .home | .terminal(UUID)`；`SidebarState = .collapsed|.overlay|.pinned`（overlay 不占位、不 resize；pinned 钉住各 resize 一次）。
+- `TerminalSession` 加身份：`id`/`host`/`isLive`(原 showsTerminal，**不再驱动导航**)/`isMinimized`/`lastActiveAt`/`link`(LinkState 五态，由 phase+egress 推导)/`displayName`/`initials`/`isTmuxSession`。**TXCore、传输层零改动**（50 tests 保持绿）。
+- `SessionManager`：多实例持有、`open(host:)` 复用同主机会话、`focus`/`minimize`/`close`、前后台广播、⌘1…9 索引、首页排序（最小化置顶 + 最近活跃）。
+- `ContentView` → `RootView(ZStack{SessionCanvas, HomeShell})`。**SessionCanvas 常驻挂载所有会话**（详见 CLAUDE.md 坑：摘除即丢内容 + matchedGeometry 要求同层级）。host key alert 下移到 `TerminalScreen`（每会话一份，后台会话也能弹安全告警）。
+- 无头验证脚手架（DEBUG）：`UIPreviewFixture` 假会话 + `terminalx://ui/*` 导航驱动 + `scripts/tx-shot.sh` 截图定向。**坑**：假会话必须 `isSyntheticFixture=true` 从生命周期广播里排除，否则 scenePhase→active 广播经 `syncUI()` 把注入状态覆盖回 idle。
+- **验收**（四步截图取证，全通过）：A 终端会话1 → B `ui/minimize` 回首页（3 会话并存 + mac-studio 标「最小化中」置顶）→ C `ui/session/2` 切会话2（独立内容 + tsnet 徽标）→ D `ui/session/1` 回会话1 **内容原样**。
+
+### 12.3b UI-3/UI-4 两屏还原（新文件 `TXParts` / `RailSidebar` / `TerminalChrome` / `HomeView`）
+- **`TXParts.swift`** — 设计稿反复出现的小件：`TXStatusDot`(8pt + 2pt 挖底描边) · `TXInitialsAvatar`(26/38pt 两字缩写 + 右上状态点) · `TXSectionLabel`(600 10px ls .09em uppercase) · `TXBadge` · `TXChip` · `TXSearchField`(32pt) · `TXButton` · `TXIconButton`(视觉 34、命中 44) · **`TXTerminalMirror`**(终端文本镜像，底对齐)。
+- **`RailSidebar.swift`** — `RailView`(56pt/竖屏 48pt 轨道：logo 不可点 → 搜索 → 首页 → 主机头像+状态点 → 虚线+ → TMUX 段 window 数字 → 状态点 → »展开 → 齿轮) + `SidebarPanel`(288pt，遮罩/Pin 共用同一套内容) + `SidebarSessionRow`/`SidebarWindowRow`。**开合语义唯一**：logo 不可点，折叠态»展开在轨道底、展开态«收起在标题右，Pin 是独立按钮只在展开态出现。
+- **`TerminalChrome.swift`** — 浮起胶囊（`.ultraThinMaterial` + 半透底 + 描边 + 圆角 11）：左上标题胶囊（红黄点/竖分隔/状态点/主机名/window title）+ 右上三格状态胶囊（`tsnet | mosh | tmux`，**只染出问题的那层**）+ 底部 34pt 提示条（文案随侧边栏三态切换）。
+- **`HomeView.swift`** — 页头（34px 标题 + 副行 + 220pt 搜索 + 新建连接 + 齿轮）→ 活动会话 3 列 `SessionCard`（卡头状态/主机名/tmux/链路 · 文本镜像 · 卡脚 windows·panes·上次活跃 + ⌘n + 回到会话）→ 全部主机 4 列 `HostTile` + 筛选 chips + 添加卡。重连/离线卡：镜像 `blur(1.5)` + `rgba(24,26,40,.72)` 遮罩 + 转圈 + 「屏幕内容已缓存，恢复后原样接回」。
+- 舞台：pane 区顶部留 `TX.Layout.capsuleInset`(86pt) 预留带 + `clipped()` 防溢出；pane 之间 2pt 缝（各让 1pt）；`TmuxStage` 去掉 tab 条（window 切换移到轨道/侧边栏），保留「全 window 常驻挂载 + opacity」与容器几何单一来源。
+- **缩略卡的「真实回滚」**：`TerminalSession.captureSnapshot()` 用 `readViewportText()` 抓尾部 32 行（剔尾部空行），首页可见时每 1.5s 轮询 + 最小化前抓一次。**没有第二个 surface**。
+- fixture 扩展：`UIPreviewFixture.hosts`(7 台 + 分组/os)、`tailnets`、每条会话的 `TmuxSummary` 注入；`HostStore.injectFixtureHosts`/`TailscaleStore.injectFixtureConnections` 只进内存**不写盘**。
+- **验收**：四态截图对拍设计稿 —— 折叠轨道(08) · 遮罩态(00) · Pin 态(01，终端真的变窄) · 首页(09)。TXCore 50 tests 保持绿。
+
+### 12.3c 像素级走查修正（用户走查 + 逐屏对拍，2026-07-25 二轮）
+走查方法（**后续每屏都照这个来**）：`scripts/tx-shot.sh` 截图 → `python3` 把设计稿 PNG 与截图统一缩放到 1366×1024 → 裁同一区域上下/左右并排 → 再对元素列做**垂直投影扫描**（逐行找与底色不同的段），把元素 y 坐标量化对比。目测靠不住（缩略图里 `#1E1E2E` 与 `#11121C` 分不出）。
+
+修正项：
+1. **沉浸不彻底（最严重）**：原来把 86pt 预留带做成"pane 容器整体下移"，胶囊浮在舞台底色上。改为 **pane 容器从舞台顶部就开始**（终端底色 + 边框铺满），只把 surface 内容 `padding(.top, 86)` —— 预留带铺的是 `flavor.terminalBg`，故与终端内容视觉连续，胶囊真正"悬浮在终端之上"。像素采样验证：预留带与内容区同为 `#1E1E2E`。
+2. **终端页隐藏系统状态栏**（设计稿 `1b`/`3a` 顶部就是胶囊/logo，`1e`/`1g` 才有状态栏）+ `ignoresSafeArea(edges: .top)`。**坑**：`statusBarHidden` 不能挂在 `TerminalScreen` 上——它常驻挂载（SessionCanvas），会连首页一起隐藏；要挂在 `RootView` 上按 `router.route` 判断。
+3. **侧边栏动画**：三态切换统一走 `AppRouter.sidebarAnimation`（`.easeOut(0.24)`，设计要求 200–260ms），面板 `.move(edge: .leading)` 滑入 + 遮罩 `.opacity` 淡入。
+4. **底部两区同高**：侧边栏脚与舞台提示条共用 `TX.Layout.footHeight`(34pt)，故两侧分割线落在同一 y；侧边栏脚原来的深色块 + 齿轮**去掉**，改 1pt `divider`（设计稿如此）。
+5. 轨道结构：**搜索/首页/设置是裸图标**（无底无框），只有 logo 与展开键有框（`TXIconButton(bare:)`）；纵向节奏按扫描到的设计坐标写死（logo 28 · 头像 174/220/266 · TMUX 标签 388 · 数字 408 起）；TMUX 段标签用 accent-500 而非中性灰。
+6. 侧边栏面板：logo 30pt、会话行 48pt、window 行 44pt（实测值）；分组分隔线改**渐隐** LinearGradient；占位分支补回漏掉的「新建 window ⌘T」行。对齐后与设计稿偏差 ≤9pt（window 区完全重合）。
+7. 缩略卡：卡头/卡脚分隔线用 1pt `Rectangle`（`Divider().overlay()` 压不住默认色）；行距 `fontSize×0.6`（设计 11px/1.5）；**启发式着色** —— `readViewportText()` 只给纯文本，故按行首符号/关键字上色（`✓`绿 `error`红 `◇▸`青 `[..]`灰 提示符行亮），逼近真实终端密度。
+
+### 12.3d UI-4 交互闭环（关闭确认 / 分屏菜单 / pane 拖拽）
+- **`TmuxController` 新增命令**（纯追加，未动既有链路）：`detach()`(`detach-client`) · `killSession()` · `splitWindow(vertical:joinSession:)`（`split-window` / 跨会话用 `join-pane -s`，**不嵌套 tmux**）· `splitIntoNewSession()`（`new-session -d` + `join-pane`）· `resizePane(cols:rows:)` · `listSessions()`（新 `PendingKind.listSessions`，结果进 `@Published sessions: [TmuxSessionInfo]`）。
+- **`AppModal` 提到 `AppRouter`**（不是视图 `@State`）：⌘W/⌘D 快捷键与无头 URL 驱动都要能打开浮层，视图内部状态触达不到。
+- **关闭确认 `CloseConfirmDialog`**（3c，436/404pt）：tmux → 推荐「仅断开 ⏎」(`detach-client`，服务端继续跑) + 次要红字「结束会话」(`kill-session`，**再点一次才执行**)；原生窗口 → 琥珀警告 + 危险按钮（设计精确色 `#8d5560` / `rgba(92,58,63,.35)` / `#f5a0ac`）。`closeSession(kill:)` 先发 tmux 命令、延迟 250ms 再 teardown 传输层（让 `%exit` 走既有 `onExit`）。
+- **分屏菜单 `SplitMenuView`**（3b，360pt）：**不问方向**（⌘D/⌘⇧D 本就是两个入口），只列「分到哪里」——当前会话（选中底 + 「当前」）· detached 会话（绿点，因为进程仍在服务端跑 + 上次活跃）· 新建 tmux 会话。前导列统一 20pt 使各行文字左缘一致。**原生窗口项灰显标「二期」**（需要一台主机多条 SSH channel，见 §12.4），不装作能用。
+- **pane 拖拽 `PaneSplitter`**：从布局树内部节点算出相邻子节点边界 → 热区 12pt + 把手 44×3pt。**拖动中只动视觉**（把手位移 + 转强调色），不改 pane frame、不发命令；**松手才发一次 `resize-pane`**，等 `%layout-change` 回来更新真实 frame（与"路线 b"一致：客户端不自行重排）。
+- **最小化过渡**：离开终端时 `opacity + scaleEffect(0.97)`（240ms easeOut）。用 `scaleEffect` 而非 frame 动画 —— 前者只是渲染变换**不触发 PTY resize**，后者会让 tmux 反复重排。完整 matchedGeometry 缩回卡片未做（fable 裁决：不对 `TerminalSurfaceView` 本体做 matchedGeometry）。
+- **验收**：三个浮层逐个对拍设计稿（3c 两套文案 + 3b 菜单）；最小化往返内容原样、日志无 crash；TXCore 50 tests 绿。**pane 拖拽只做了静态编译与逻辑走查，没有真实 tmux 多 pane 会话验证过**（fixture 没有 controller）——有测试主机时必须补。
+
+### 12.3e 接真实数据 + 空状态（UI-5 之前的必要一步）
+之前几轮都靠 `-txUIFixture` 假会话对拍设计稿，真实路径下有数据缺口和裸露的空白屏。本轮补齐：
+
+**真实数据打通**
+- **tmux 会话名**：kickoff 时顺带 `listSessions()`，`currentSessionName` = list-sessions 里 attached 的那个 → 状态胶囊/侧边栏标题显示真实 `tmux <会话名>`（拿不到就只显示 `tmux`，不编造）。
+- **cwd**：`list-windows` format 追加 `#{pane_current_path}` → `TmuxWindow.cwd`；标题胶囊显示「window title · ~/src/x」，侧边栏 window 行副行显示「cwd · n panes」。`abbreviate()` 把 `/home/u/x`、`/Users/u/x` 收成 `~/x`。
+- **主机的分组 / 系统**：`HostEditorView` 新增「归类」区（分组输入 + 已有分组一键选 chips + 系统描述）。此前 `SavedHost.group/os` 只有 fixture 在写，真实主机永远没有分组 → 首页 chips 恒只有「全部」。
+- IP 主机名的缩写：`10.255.255.1` 按字母规则会得到无意义的 `11` → 纯 IP 取首段前两位（`10`）。
+
+**空状态（真实路径必经）**
+- 首页首次运行（0 主机 0 会话）：终端图标 + 「还没有主机」+ 能力说明 + 「新建连接 / 先配置 Tailscale」。
+- 有主机无会话：虚线提示条「还没有在跑的会话 —— 点下面任意主机即可连接」。
+- 搜索/筛选无命中：说明是分组还是搜索造成的 + 「清除筛选」。
+- 缩略卡无输出：「等待输出…」占位（真实会话刚连上时 `readViewportText()` 还是空的）。
+- 侧边栏无会话：「没有在跑的会话」。
+- **终端区 `TerminalStateOverlay`**：连接中（转圈 + 分阶段文案 + **已等待 Ns** + ≥5s 后出「取消连接」）/ 连接失败（错误详情 + 返回首页 + 重试）/ 已关闭（重新连接）。已连接与重连中**不渲染此层**，不遮挡终端内容。
+- 路由兜底：`route` 指向的会话已被关闭 → 自动回首页，不停在空画布上黑屏。
+
+**传输层修一处真实可用性问题（`TXTransport`）**
+- `SSHSession.connect()` 原来用裸 `Darwin.connect`，**阻塞到系统 TCP 超时（75s+）**，连不上的主机会让用户对着「连接中」干等。改为 `connectWithTimeout()`：置非阻塞 → connect → `poll(POLLOUT)` 等超时 → **查 `SO_ERROR`**（可写≠成功，拒绝连接也会变可写）→ 恢复阻塞（libssh2 用阻塞模式）。超时值走新增的 `SSHConfig.connectTimeoutSec`（默认 12s）。tsnet 路径（`preconnectedFD`）不经此处，不受影响。
+- 验证：不可达地址 12s 后报「失败：socket("连接失败（12s 超时）…")」，失败态覆盖层给出重试/返回。
+
+### 12.3f tmux 自动进入（真机反馈修复：连上永远显示「无 tmux」）
+**根因**：全代码库没有任何地方发起 `tmux -CC attach`。`TmuxRouter` 只被动检测传输字节流里的 DCS 前导，之前所有 tmux 端到端验证都靠 `-txAutoCommand "tmux -CC …"` 手动触发 → 真实点击连接只有 raw shell，状态胶囊第三格恒为「无 tmux · 客户端窗口」。不是检测坏了，是从来没人发起。
+
+**修复**
+- `SavedHost` 加 `useTmux: Bool = true`（旧数据迁移也默认 true）+ `tmuxSession: String?`（默认 `main`）；主机编辑器新增「会话」区（tmux 开关 + 会话名 + mosh 开关，带说明）。
+- `TerminalSession.scheduleTmuxBootstrap()`：连接建立后（mosh 模式则等 mosh 接管后）延迟 **2.5s** 等 shell 提示符 → 发 `tmux -CC new -A -s <名>`。`-A` = 同名会话存在就接回（断线原样恢复的关键）。
+- **探测降级**：4s 内没进 control mode → `tmuxUnavailable = true` → 终端顶部行内横幅（设计 2c：说明「关掉 App 后服务端不会继续跑」+「安装并启用 tmux」+ 可关闭）。装完自动重试一次。
+- `exitTmux()` 重置引导标记 → 重连后重新 attach。
+- 无头参数：`-txTmux 0|1`、`-txTmuxSession <名>`。
+
+**真机端到端验证通过**（192.168.99.83，macOS + fish + tmux 3.7b）。过程中查出 3 个真实 bug：
+
+1. **tab 分隔符被 PTY 吃掉**：`list-windows -F "…\t…"` 的 tab 经 PTY 到 tmux 后变成**下划线**，整行 `components(separatedBy:)` 分不开（`count=1`）→ title/cwd/会话名全丢、UI 显示兜底名「窗口 N」。改用 `TmuxController.fieldSep = "|:|"`。**排查坑**：`os_log` 把控制字符显示成 `_`，光看日志无法区分「真下划线」与「被显示替换的 tab」，我因此先误判为 os_log 显示问题——最后靠打印 `parts.count` 才确诊。
+2. **UI 不刷新**（正是 CLAUDE.md 里「嵌套 ObservableObject 不冒泡」那条坑的另一面）：`tmuxSummary`/window 列表是读 controller 的 computed property，而轨道/胶囊/侧边栏只订阅 session → 数据解析对了 UI 也不动。修法：`TerminalSession` 用 Combine 订阅 `controller.objectWillChange` 并转发自己的 `objectWillChange`（一处解决所有读 controller 的视图）。
+3. **会话名猜错**：`currentSessionName` 原来取 `list-sessions` 里 `session_attached==1` 的那个，结果把用户自己终端 attach 的 `demo` 当成了当前会话。改用 `display-message -p "#{session_name}"`（权威：本客户端所在会话）。分屏菜单的「当前」判定也随之改为按会话名比较。
+4. 顺带修正：轨道/侧边栏的 window 编号用 `#{window_index}`（用户可见的 0/1/2…）而非内部 `window_id`（@2/@3…）。
+
+**验证结果**（服务器侧交叉验证）：
+- tmux 自动进入 ✓ 状态胶囊 `direct | ssh | tmux main`、标题胶囊 `fish · ~ 163×50`、轨道 window `0/1/2/3/4`（与服务器 `idx=0..4 active=@3/idx=1` 完全吻合）
+- **⌘D 分屏 ✓**：`split-window -h` 后服务器 `list-panes` 从 `%7 164x50` 变为 `%7 82x50 + %8 81x50`；app 端双 pane 左右并排渲染、2pt 缝、拖拽把手、活动 pane blurple 边框
+- **`resize-pane` ✓**：`ui/resize/110` 后服务器 pane 宽度变为 `110`（另一侧自动收缩到 53）——拖拽条的命令链路已验证（手势本身是标准 `DragGesture`）
+- **会话服务端持久 ✓**：app 退出后 `tmux ls` 里测试会话仍在（验证完已 kill 清理）
+- 新增无头验证命令：`ui/split-now/v|h`（跳过菜单直接分屏）、`ui/resize/<cols>`
+
+### 12.3g 连接后的会话选择器（用户定稿交互，替换掉「自动 attach 固定会话」）
+**为什么改**：之前实现是连上就 `tmux -CC new -A -s main` —— 替用户决定了 attach 哪个会话。真实运维里服务器上常有多个会话各跑不同任务，必须让用户挑。
+
+**新流程**：SSH 连上 → 普通 shell 里跑探测 → 弹选择器 sheet → 按选择 attach。**没装 tmux 时不弹框**（直接原生终端 + 安装引导横幅，不打扰）。
+
+- **`TXCore/Tmux/TmuxSessionProbe.swift`**（纯逻辑 + 5 个单测）：流式扫描 `BEGIN…END` 标记块，产出 `.available(version:sessions:)` / `.unavailable`。三个坑都在注释里：
+  1. **PTY 回显**：命令本身会被回显，标记若字面出现在命令里，回显行会被当成结果起点 → 写成相邻字符串拼接 `"__TX""_SESSIONS_BEGIN"`（shell 输出完整标记，回显的是拼接前的样子）。
+  2. **三态要分开**：「没装 tmux」和「装了但没会话」的 stderr 都被 `2>/dev/null` 吞掉、标记之间同样是空的，只能靠 `tmux -V` 的版本行区分 —— 两者的正确 UI 完全不同（安装引导 vs 让用户新建）。
+  3. **别脏屏**：探测命令与输出会打在用户屏幕上 → 命令末尾接 `printf '\033[H\033[2J\033[3J'`（归位+清屏+清 scrollback，不依赖 terminfo）。刚连上时清掉的只有 motd/shell 欢迎语，首屏反而更干净。
+- **`OutputTap`**：raw 字节的旁路（同时喂终端渲染与探测扫描器）。抽 `RawOutputSink` 协议让 `TmuxRouter` 能接受 gate 或 tap —— **不动 `OutputGate` 的缓冲/flush 语义**（那是修白屏的关键）。
+- **`SessionPickerSheet.swift`**（按用户给的设计图）：分段控件 `>_ Tmux` | `Herdr`(置灰) | `最近`(置灰) + 右侧「跳过 ▷|」；会话行 = 大字会话名 + 「活跃」徽标（被别的客户端占用时另标「已被接入」）+ 副行「N 个窗口 · M 分钟前」；底部「+ 新建 tmux 会话…」（点开就地输入名字）。`.presentationDetents([.medium, .large])`。
+- `TerminalSession`：`pendingSessionChoice` / `attachTmuxSession` / `createTmuxSession` / `skipTmux`（`tmuxSkipped` 让状态胶囊显示「原生窗口 · 不经 tmux」而不是谎报「无 tmux」）；探测 6s 超时兜底按无 tmux 处理。
+- 无头命令：`ui/pick/<会话名>` · `ui/pick-new/<名>` · `ui/pick-skip`。
+
+**时机修正（用户第二轮反馈）**：选择器属于**连接流程的一部分** —— 点主机后**留在首页**探测、在首页弹选择器、选完才进终端页；不是先把用户丢进空终端再弹框。
+- `SessionManager`：`open(host:)` 不再立刻 `router.enter`；改为 `awaitingEnter` 集合 + `@Published enterRequest`（视图层消费后进终端）。`evaluateEnter` 的就绪条件：不等选择 ∧ 不在探测 ∧（已建立 / 无 tmux / 选了原生 / 失败）。失败也进终端 —— 那里有「重试 / 返回首页」，比留在首页只有一行错误更有出路。
+- **坑**：`isProbingTmux` 必须在 `.connected` 那一刻就置位。否则「连接建立」与「探测开始（延迟 2.5s）」之间有空窗，`evaluateEnter` 看到 `isLive == true` 就把人送进终端页 —— 第一次改完就是这个症状（选择器弹在终端页上）。
+- `SessionManager` 也要转发每条会话的 `objectWillChange`（同 `TerminalSession` 转发 controller 那条坑），否则首页/选择器不会因会话内部变化刷新。
+- 首页新增 `ConnectingRow`（正在连接 / 等待选择 / 失败+重试+取消）；`liveSessions` 排除正在连接的会话，避免同一会话既有进度行又有卡片（且卡片里的 tmux 信息此刻还没定，会先显示成「原生窗口」再跳变）。
+- 无头验证真实路径：`-txOpenAsHost 1`（把启动参数造成一台内存主机后走 `open(host:)`，即探测→选择→进终端；与老的 `-txHost` 直连路径互斥）。
+
+**措辞修正**：右上不再是「跳过」（读起来像"跳过某个步骤"、含义模糊），改为**「原生终端」**+ terminal 图标 —— 它是与 tmux 并列的一种连接方式。`skipTmux()` → `useNativeTerminal()`，状态胶囊第三格显示「原生窗口 · 不经 tmux」。首版只有 Tmux 与原生两种，所以不做别的出口。
+
+**真机验证（192.168.99.83）三条出路全过**：
+- 探测 → `probe: tmux 3.7b sessions=["demo", "main"]`，选择器如设计图渲染，终端首屏干净（清屏生效）
+- **attach 已有** → `attach -t demo` → `currentSession=demo`
+- **新建** → `new -A -s uitest` → `currentSession=uitest`，服务器 `tmux ls` 出现 `uitest: 1 windows (attached)`（验完已 kill）
+- **原生终端** → 状态胶囊 `direct | ssh | 原生窗口 · 不经 tmux`
+- **完整真实路径**（`-txOpenAsHost`）→ 首页「正在连接 192.168.99.83」→ 首页上弹选择器（标题「连接到 …」）→ 选 `main` → 进终端页 `tmux main` + 轨道 window `0/1/2/3/4`
+
+### 12.4 首版明确推迟（Fable 裁决，勿在 UI-3~6 里偷偷做）
+`mosh <RTT>` 实时数字（需改 vendor/mosh iosclient 导出 SRTT，属传输层）· ⌘K 命令面板 · 无 tmux 主机的多客户端窗口（保留横幅引导）· iPad 竖屏 pane 强制上下堆叠（会推翻「路线 b」，交给 tmux relayout）· 缩略卡 ANSI 彩色（用 `readViewportText()` 文本镜像，**绝不做离屏 Metal/双 surface**——IOSurfaceLayer 泄漏史）· 设置页连字/CJK 开关（ghostty 无运行时 mutation，灰显占位）。
 </content>

docs/design/UI-DESIGN-HANDOFF.md

@@ -0,0 +1,241 @@
+# Handoff: terminalX — iPadOS 终端 App（沉浸轨道方案）
+
+## Overview
+
+terminalX 是面向 iPadOS / iOS 的原生终端运维工具，解决 iPad 远程运维 macOS / Linux 的痛点。技术选型：**libghostty**（终端引擎）· **mosh**（抗断线传输）· **Tailscale tsnet**（用户态入网）· **tmux control mode**（会话复用）。平台优先级 **iPadOS > iOS > macOS(Apple Silicon)**。
+
+本包描述的是**终端主界面（沉浸轨道）+ 首页（主机管理）+ 设置**这一套已定稿的 UI，含侧边栏三态、分屏模型、关闭/最小化语义、竖屏与 iPhone 降级规则。
+
+## About the Design Files
+
+`terminalX iPadOS.dc.html` 是**设计稿**，不是生产代码。它用 HTML/CSS 表达最终视觉与交互意图（1:1 像素尺寸），目的是让你在**目标工程里用原生技术重建**——本项目的目标环境是 **SwiftUI（iPadOS 26 / iOS 26）**，请使用工程已有的架构与组件模式实现，不要移植 HTML/CSS。
+
+打开方式：浏览器直接打开该文件即可，画板可自由缩放平移。每块屏幕都带 `data-screen-label`，便于对照本文档。
+
+## Fidelity
+
+**High-fidelity（hifi）**。颜色、字号、圆角、间距、行高均为最终值，可按本文档的精确数值实现。文案（简体中文，技术术语保留英文）也是最终稿。
+
+唯一例外：终端内容区的命令输出是**示意数据**，用于验证排版密度与配色，不必照搬。
+
+---
+
+## Design Tokens
+
+### 颜色 — App chrome（Nocturne 设计系统）
+
+| 用途 | Hex | Nocturne token |
+| --- | --- | --- |
+| 画布底 / 屏幕底 | `#161826` | `--color-bg` |
+| 侧边栏 / 轨道 / 卡片底 | `#1b1d2b` | surface-dark |
+| 控件底（输入框、次要按钮、徽标） | `#232532` | `--color-surface` |
+| 舞台底（pane 之间的缝） | `#11121c` | bg-deep |
+| 分隔线（弱） | `#2c2f3d` | neutral-800 |
+| 描边（常规） | `#3f424d` | neutral-700 |
+| 描边（强调 / 对话框） | `#595d6c`、`#4a4d5e` | neutral-600 |
+| 强调色（唯一） | `#9184d9` | `--color-accent` |
+| 强调 - 边框 | `#796cbf` | accent-600 |
+| 强调 - 选中底 | `#2b2741` | accent-900 |
+| 强调 - 选中描边 | `#423a6a` | accent-800 |
+| 强调 - 文字 | `#b5abfc` / `#d2cefd` | accent-400 / -300 |
+| 强调 - 弱化文字 | `#5d5294`、`#968ae0` | accent-700 / -500 |
+| 主文字 | `#e9e9ed` | `--color-text` |
+| 次文字 | `#cfd3e5` / `#b2b6ca` | neutral-300 / -400 |
+| 三级文字 | `#9397ab` | neutral-500 |
+| 弱文字 / 占位 | `#75798c` | neutral-600 |
+| 极弱（提示、注脚） | `#4a4d5e` | neutral-700 |
+
+**规则**：强调色只做线、点、选中底和文字，**绝不大面积铺色**；不使用纯黑纯白。
+
+### 颜色 — 终端内容区（Catppuccin Mocha，libghostty 渲染）
+
+`base #1e1e2e`（pane 底）· `mantle #181825` · `surface0 #313244`（vim 状态栏）· `text #cdd6f4` · `subtext #a6adc8` · `overlay #6c7086`（次要输出）· `surface2 #585b70`（禁用/缓存态）
+语义色：`green #a6e3a1`（成功、提示符）· `red #f38ba8`（error）· `yellow #f9e2af`（warning、git 标记）· `blue #89b4fa`（路径、字段）· `mauve #cba6f7`（关键字）· `teal #94e2d5`（勾选）· `peach #fab387`（重连中）· `pink #f5c2e7`
+
+设置页可切换 Mocha / Macchiato / Frappé / Latte，**chrome 的中性阶随之推导，强调色恒为 Nocturne blurple `#9184d9`**。
+
+macOS 窗口按钮沿用系统色：关闭 `#ff5f57`，最小化 `#febc2e`（13pt 圆点，`inset 0 0 0 .5px rgba(0,0,0,.25)`，仅悬停/触摸时显出符号）。
+
+### 字体
+
+全局 **JetBrains Mono**（400 / 500 / 600 / 700），chrome 与终端同源。中文走系统回退（PingFang SC）。
+
+| 场景 | 规格 |
+| --- | --- |
+| 屏幕主标题（首页 terminalX） | 500 34px, letter-spacing -.025em |
+| 页面标题（设置、总览） | 500 24–28px, ls -.02em |
+| 分区标题 | 500 22px, ls -.02em |
+| 分组小标题（活动会话 / TMUX） | 600 10px, ls .09em, uppercase, `#75798c` |
+| 列表主行 | 400–500 13px |
+| 列表副行 / 元信息 | 400 10.5–11px, `#75798c` |
+| 徽标 / 胶囊 | 500 11.5–12px |
+| 终端正文（主 pane） | 400 13.5px / 1.55 |
+| 终端正文（次 pane / 缩略） | 400 11–12px / 1.5 |
+| 终端 pane 头 | 500 11px, `#6c7086` |
+| 底部提示条 | 400 11.5px, `#75798c` |
+
+### 间距 / 圆角 / 阴影
+
+- 间距：2 / 6 / 8 / 9 / 10 / 12 / 14 / 16 / 18 / 20 / 26 / 34 / 40（px）
+- 圆角：徽标 5–7 · 控件 8–9 · 卡片 11–13 · 对话框 14–15 · 屏幕卡 18 · 手机卡 38
+- 阴影：浮起胶囊 `0 10px 30px rgba(0,0,0,.55)`；侧边栏浮层 `24px 0 60px rgba(0,0,0,.55)`；对话框 `0 30px 80px rgba(0,0,0,.7)`；卡片 `0 6px 18px rgba(0,0,0,.4)`
+- 遮罩：`rgba(10,11,18,.42–.5)`，浮层用 `backdrop-filter: blur(20px)`
+
+### 图标
+
+**Phosphor Icons**（regular）。用到：`magnifying-glass` `house` `plus` `gear-six` `caret-double-left` `caret-double-right` `caret-down` `caret-left` `push-pin` `columns` `terminal-window` `hard-drives` `desktop-tower` `cpu` `key` `shield-check` `lightning` `paint-brush` `text-aa` `keyboard` `export` `info` `warning` `x` `minus` `arrow-right` `arrow-left` `lightbulb` `moon` `check-circle` `wifi-high` `battery-high` `browsers` `rows` `git-branch` `plugs` `trash` `arrows-in-simple` `textbox` `sidebar-simple` `globe-hemisphere-west`。
+
+SwiftUI 实现请换成等义 **SF Symbols**（例如 `house` / `magnifying-glass` → `house`、`magnifyingglass`；`caret-double-left` → `chevron.compact.left` 或 `sidebar.left`；`push-pin` → `pin`）。
+
+---
+
+## Layout 基准
+
+- 画板尺寸：iPad Pro 13″ 横屏 **1366×1024pt**；竖屏 **1024×1366pt**；iPhone **393×852pt**
+- 折叠轨道宽 **56pt**（竖屏 48pt），元素中心线统一在 28pt（竖屏 24pt）
+- 展开侧边栏宽 **288pt**
+- pane 之间的缝 **2pt**（拖拽热区 **12pt**，把手 44×3pt 圆角 2pt）
+- 触控命中区不低于 **44pt**（键盘附加行按键高 38–40pt + 6pt 间距 = 44pt 节距）
+- 终端主 pane 顶部预留 **86pt** 给浮起胶囊（2c 因多一条横幅为 122pt）；预留带用 padding-top 实现，内容容器 `min-height:0; overflow:hidden` 防止向上溢出
+- Home indicator 条：200×4pt（iPhone 140×5pt）
+
+---
+
+## Screens / Views
+
+### 1) 终端主界面 · 沉浸轨道 — `1b 终端-沉浸轨道`
+
+**Purpose**：真正干活的界面，终端面积最大化。
+
+**Layout**：`HStack`：左 56pt 轨道 + 右舞台。舞台是 `VStack`：pane 区（flex）+ 硬件键盘提示条 34pt + home 区 14pt。pane 区 padding 2pt，上下两个 pane 比例 1.7 : 1，中间 12pt 拖拽条。
+
+**轨道自上而下**：Logo 方块（34×34，圆角 11，底 `#232532`，inset 描边 `#3f424d`，字形 `›` 700 16px `#b5abfc`，**不可点**）→ 搜索图标 → 首页图标 → 1pt 分隔 → 主机头像（38×38 圆角 11，两字缩写；选中底 `#2b2741` + inset 描边 `#5d5294`；右上角 8pt 状态点，`box-shadow: 0 0 0 2px #1b1d2b` 挖底）→ 虚线 + 号 → 分隔 → `TMUX` 标签（600 9px ls .1em）+ window 数字（34×30，选中底 `#232532` + inset 描边 `#4a4d5e`）→ `Spacer` → 连接状态点 8pt → 展开键（`caret-double-right`，34×34 底 `#232532` 描边 `#3f424d`）→ 设置齿轮。
+
+**浮起 chrome**（`position: absolute`，`backdrop-filter: blur(20px)`，底 `rgba(27,29,43,.86–.9)`，描边 `#3f424d`，圆角 11）：
+- 左上标题胶囊 `top 14, left 16`：红/黄圆点 → 1pt 竖分隔 → 6pt 绿点 → 主机名（500 12.5px）→ 「当前 window title · cwd」（400 11.5px `#75798c`）
+- 右上状态胶囊 `top 14, right 16`：三格分层徽标 `tsnet` | `mosh 41ms` | `tmux dev`，格间 1×16pt 竖线
+
+**底部提示条**：接硬件键盘时只留 34pt 提示条（快捷键清单）；触控时替换为键盘附加行（两行，见 iPhone / 竖屏）。
+
+### 2) 侧边栏三态 — `3a 侧边栏-遮罩态`、`3a 侧边栏-Pin 态`
+
+同一条栏的三个状态，**元素不增不减**，只是展示密度不同：
+
+| 状态 | 宽度 | 行为 |
+| --- | --- | --- |
+| 折叠 | 56pt | 只显图标与两字缩写 |
+| 遮罩（默认展开） | 288pt | 面板**盖住**轨道（`left: 0`，不并排，避免两套入口），右侧终端压 `rgba(10,11,18,.5)` 遮罩，**点终端任意处收起**；终端不 reflow，不触发 PTY resize |
+| Pin | 288pt | 点面板右上 `push-pin` 后钉住：遮罩消失，终端变窄，**只在钉住/解除时各 resize 一次**；再点解除回遮罩态 |
+
+**开合语义（务必唯一、不歧义）**：`›` 方块是 App logo，不可点。开合只有一枚按钮，两态方向相反——折叠态在轨道底部 `caret-double-right`（展开），展开态在标题右侧 `caret-double-left`（收起）。Pin 是独立按钮，只在展开态出现。快捷键 `⌘\` 开合。
+
+**面板内容自上而下**：Logo + `terminalX`（500 14px）+ Pin + 收起 → 搜索框（32pt 高，圆角 8）→ **首页**行（`house` + 「首页」+ `⌘⇧H`）→ 分组「活动会话 n」→ 会话行 → 1pt 渐隐分隔 → 分组「TMUX · <主机> · <会话>」→ window 行 + 「新建 window ⌘T」→ `Spacer` → Tailscale 状态脚（绿点 + tailnet + 设备 IP + 齿轮）。
+
+**行规格（左缘必须对齐）**：会话行 = 26pt 头像列 + 10pt gap；window 行 = 26×22pt 徽标列 + 10pt gap；两者标题左缘同为 **x=53**。选中态用 `box-shadow: inset 0 0 0 1px #423a6a` 而非 `border`，避免选中时内容位移 1pt。
+
+### 3) 首页 · 主机管理（落地页）— `1e 主机-会话卡`
+
+**Purpose**：App 冷启动落点；「回到刚才那个会话」是首要动作。
+
+**Layout**：状态栏 24pt → 页头（terminalX 500 34px + 副行）+ 右侧搜索 220pt / 新建连接 / 设置 → 分组「活动会话」→ **3 列会话缩略卡（flex:1）** → 分组「全部主机」+ 筛选 chips → **4 列主机卡（按内容高度）** → home 区。左右留白 40pt。
+
+**会话缩略卡**（圆角 13，选中卡描边 `#423a6a` + `0 6px 18px rgba(0,0,0,.4)`）：卡头 36pt（状态点 + 主机名 + tmux 会话 + RTT）→ 终端缩略（`#1e1e2e`，11px/1.5，**内容底对齐**，真实回滚）→ 卡脚 38pt（「n windows · 上次活跃」+ `⌘1/2/3` + 主动作「回到会话 →」）。离线卡加 `rgba(24,26,40,.72)` + `blur(1.5px)` 遮罩，内含 26pt 转圈 + 两行说明；**遮罩必须是 pane 的最后一个子节点**（pane 为 `position: relative`）。
+
+**最小化回来的卡**：置顶并标「最小化中」，转场是从终端缩回该卡的动画。
+
+### 4) 新建分屏 — `3b 新建分屏菜单`
+
+**不问方向**（竖分 `⌘D` / 横分 `⌘⇧D` 本来就是两个入口）。菜单只问「分到哪里」：
+
+- 分组「tmux 会话」：当前会话（带「当前」标签）、其余 detached 会话（title · n windows · 上次活跃）、「新建 tmux 会话…」
+- 分隔线
+- 「原生窗口 / 不经 tmux · 关 App 即结束」
+
+选完**立即分屏**。菜单 360pt 宽，圆角 14，`#1b1d2b` + 描边 `#595d6c`；行高 ~40pt，前导列统一 20pt（状态点也要包在 20pt 居中列里，保证五行文字左缘一致 x=50）。
+
+**模型约束**：分屏只发生在**同一台主机内**。卡片内部的分割 = 真 tmux pane（`split-window`，服务端持有，断线原样恢复）；跨主机分屏**已取消**（层级过深），要同时看两台机器就切会话或 Pin 侧边栏。
+
+### 5) 关闭 / 最小化 — `3c 关闭确认`
+
+标题胶囊左侧 macOS 红黄圆点：
+
+- **黄点（最小化）**：**不确认**，直接回首页，会话继续跑；卡片置顶标「最小化中」。手势：终端下滑。快捷键 `⌘M`。
+- **红点（关闭）**：**弹一次确认**，按主机能力分两套文案：
+  - tmux 会话 → 主按钮「仅断开 ⏎」（`detach`，服务端继续跑）；左侧次要文字按钮「结束会话」（`kill-session`，需再确认）
+  - 原生窗口 → 琥珀警告「没有 tmux 兜底，前台进程会随之结束」；推荐「取消」，危险按钮「关闭窗口」（描边 `#8d5560`，底 `rgba(92,58,63,.35)`，字 `#f5a0ac`）
+  - 快捷键 `⌘W`；`esc` 取消；`⏎` 选推荐项
+
+对话框 436pt / 404pt 宽，圆角 15。
+
+### 6) 首页 ⇄ 终端 跳转关系 — `3d 页面跳转关系`
+
+**进入终端（2 条）**：点活动会话卡 / 会话行 → 恢复到**上一个焦点 pane**；新建连接或主机 + → 建好即进终端，侧边栏同步出现该会话。
+**离开终端（3 条）**：侧边栏首页行（`⌘⇧H`，会话完全不动）· 黄点最小化（同上但语义是"待会儿还回来"）· 红点关闭（二次确认，tmux detach / 原生窗口结束）。
+换会话不必回首页——侧边栏直接切；回首页表示"换任务"。会话总览层（原 `⌘O` 缩放）**已取消**。
+
+### 7) 无 tmux 主机 — `2c 无 tmux 主机`
+
+轨道下半段的 `TMUX` 段换成「窗口」段（客户端窗口，每个 = 一条独立 SSH channel / mosh 会话，可随意新建）。状态胶囊第三格写「无 tmux · 客户端窗口」而非报错。终端顶部一条可关闭的行内横幅：说明窗口由 App 维持、mosh 兜底，但**关掉 App 不会在服务端继续跑**，右侧给「安装并启用 tmux」次要按钮。不弹窗、不强推。
+
+### 8) 竖屏与 iPhone — `2d iPad 竖屏`、`2d iPhone 竖屏`、`1h iPhone-终端`、`1h iPhone-主机`
+
+- **iPad 竖屏（1024×1366）**：轨道降到 48pt（元素中心 24pt，同样含搜索/首页/展开键）；pane 由左右平铺改为**上下堆叠，最多两层**，多余 pane 折成顶部段控；状态胶囊压缩为「主机名 + RTT」两枚；底部常驻单行键盘附加行。
+- **iPhone（393×852）**：轨道下沉为**底部主机条**（ms / u2 / nh 胶囊）；单 pane 全屏，顶部 3 段进度式 pane 指示 +「左右轻扫切 pane」；下拉标题打开会话列表；键盘附加行两行（esc/ctrl/tab/~///| 与 ↑↓←→/⌘K）；主机页用底部 tab（主机 / 会话 / 密钥 / 设置）。
+
+### 9) 设置 · 外观 — `1g 设置-外观`
+
+左 280pt 类别栏（外观与主题 / 终端与字体 / Tailscale / 密钥与安全 / mosh 与重连 / tmux 集成 / 键盘与手势 / 诊断日志，脚注版本行），右内容区 padding 28/40。内容：标题 + 说明 → 4 张 Catppuccin 主题卡（88pt 预览 + 5 色点 + 名称，选中描边 `#796cbf` + `check-circle`）→ 两栏（左「实时预览」终端框，右「排版」面板：字体、字号 13.5pt、行高 1.50、连字、CJK 等宽补偿、跟随系统深浅色）。
+
+---
+
+## Interactions & Behavior
+
+| 交互 | 行为 |
+| --- | --- |
+| 侧边栏开合 | `⌘\` 或开合键；遮罩态点终端收起；Pin 切换推挤/浮层 |
+| 切会话 | 轨道主机头像 / 侧边栏会话行 / `⌘1…9`；恢复到该会话上一个焦点 pane |
+| 切 window | 轨道数字 / 侧边栏 window 行 / `⌃⇥` |
+| 分屏 | `⌘D` 竖分、`⌘⇧D` 横分 → 弹会话选择菜单 → 立即分屏 |
+| 新建 | `⌘T` 新 tmux window；`⌘⌥T` 原生窗口 |
+| 调整 pane 比例 | 拖 12pt 分隔条（把手 44×3pt）；松手才向 tmux 发 `resize-pane` |
+| 回首页 | `⌘⇧H` / 侧边栏首页行 |
+| 最小化 | 黄点 / `⌘M` / 终端下滑；无确认 |
+| 关闭 | 红点 / `⌘W`；二次确认，`⏎` = 推荐项，`esc` 取消 |
+| 命令面板 | `⌘K`（模糊匹配主机、会话、动作） |
+| 硬件键盘 | 检测到即收起附加行，只留 34pt 提示条；拔掉恢复附加行 |
+| 长按 `⌘` | 显示全部快捷键面板（iPadOS 系统行为） |
+
+**动效**：状态切换 200–260ms `easeOut`；侧边栏浮层从左滑入 + 遮罩淡入；最小化 = 终端缩回首页卡片（matched geometry）；重连转圈 1s 线性循环。
+
+**状态徽标规则（分层，只染出问题的那层）**：
+1. `tsnet` — 网络可达；断则本格转灰/琥珀
+2. `mosh <RTT>` — 数字实时跳动；`≤120ms` 绿 `#a6e3a1`，`120–200ms` 中性，`>200ms` 琥珀 `#fab387`
+3. `tmux <会话名>` / 「无 tmux · 客户端窗口」
+
+**重连**：指数退避，上限 30s；卡片/胶囊显示「重连中 · 第 n 次 · ms 后」；屏幕内容本地缓存，恢复后原样接回（目标 <3s）。
+
+**安全**：host key TOFU 固定在钥匙串；不匹配时**拦截连接**并告警；私钥存 Secure Enclave（不可导出），密码回退默认关闭。
+
+## State Management
+
+```
+AppRoute          = .home | .terminal(sessionID)
+SidebarState      = .collapsed | .overlay | .pinned
+Session           { id, host, kind: .tmux(name) | .nativeWindow, windows[], focusedPaneID,
+                    transport: .ssh | .sshOverTsnet | .mosh | .moshOverTsnet,
+                    link: .direct(rtt) | .relay(derp, rtt) | .reconnecting(attempt, nextIn) | .offline,
+                    lastActiveAt, isMinimized }
+TmuxWindow        { index, title, cwd, panes[] }        // title 为 shell 默认值时 UI 回退显示 cwd
+Host              { id, name, group, user, addr, port, os, tsnetIP, hasTmux, hostKeyPinnedAt }
+```
+
+关键转换：`选择会话 → .terminal`；`首页/最小化 → .home`（会话保留）；`关闭 → detach 或 kill → .home`；`Pin → .pinned`（触发一次 PTY resize）。
+
+## Files
+
+- `terminalX iPadOS.dc.html` — 全部 13 块屏幕的设计稿（画板，可缩放平移）
+- `CLAUDE.md` / `README.md`（源项目文档，若已在仓库中则以仓库版本为准）
+
+## Assets
+
+无位图资产。图标全部来自 Phosphor（实现时换 SF Symbols），字体 JetBrains Mono（Google Fonts），终端配色 Catppuccin。

docs/design/render-screens.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""把设计稿画板拆成每屏一个独立 HTML，便于 headless chrome 逐屏截图。"""
+import re, os, sys
+from html.parser import HTMLParser
+
+#   python3 docs/design/render-screens.py && \
+#   for f in /tmp/tx-screens/*.html; do "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" \
+#     --headless=new --window-size=1366,1024 --screenshot="${f%.html}.png" "file://$f"; done
+SRC = os.path.join(os.path.dirname(os.path.abspath(__file__)), "terminalX-iPadOS.dc.html")
+OUT = "/tmp/tx-screens"
+os.makedirs(OUT, exist_ok=True)
+html = open(SRC, encoding="utf-8").read()
+
+# 提取 <style>…</style>（helmet 内的全局样式）
+style = "\n".join(re.findall(r"<style>(.*?)</style>", html, re.S))
+
+VOID = {"br", "img", "hr", "input", "meta", "link", "source", "area", "base", "col", "embed", "param", "track", "wbr"}
+
+class Finder(HTMLParser):
+    def __init__(self):
+        super().__init__(convert_charrefs=False)
+        self.stack = []          # 当前打开的 tag 名
+        self.capture = None      # (label, depth, start_offset)
+        self.results = []        # (label, start, end)
+
+    def cur_off(self):
+        line, col = self.getpos()
+        return self.line_starts[line - 1] + col
+
+    def handle_starttag(self, tag, attrs):
+        if tag in VOID:
+            return
+        d = dict(attrs)
+        if self.capture is None and "data-screen-label" in d:
+            self.capture = (d["data-screen-label"], len(self.stack), self.cur_off())
+        self.stack.append(tag)
+
+    def handle_startendtag(self, tag, attrs):
+        pass
+
+    def handle_endtag(self, tag):
+        if tag in VOID:
+            return
+        while self.stack and self.stack[-1] != tag:
+            self.stack.pop()
+        if self.stack:
+            self.stack.pop()
+        if self.capture and len(self.stack) == self.capture[1]:
+            label, _, start = self.capture
+            end = self.cur_off() + len(f"</{tag}>")
+            self.results.append((label, start, end))
+            self.capture = None
+
+f = Finder()
+f.line_starts = [0]
+for line in html.splitlines(keepends=True):
+    f.line_starts.append(f.line_starts[-1] + len(line))
+f.feed(html)
+
+HEAD = """<!DOCTYPE html><html><head><meta charset="utf-8">
+<link rel="stylesheet" href="https://unpkg.com/@phosphor-icons/web@2.1.1/src/regular/style.css">
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&display=swap">
+<style>%s
+html,body{margin:0;padding:0;background:#11121c}</style></head><body>"""
+
+manifest = []
+for i, (label, s, e) in enumerate(f.results):
+    frag = html[s:e]
+    m = re.search(r"width:(\d+)px;height:(\d+)px", frag)
+    w, h = (m.group(1), m.group(2)) if m else ("1366", "1024")
+    slug = re.sub(r"[^\w一-鿿]+", "_", label).strip("_")
+    path = f"{OUT}/{i:02d}_{slug}.html"
+    open(path, "w", encoding="utf-8").write(HEAD % style + frag + "</body></html>")
+    manifest.append((path, w, h, label))
+    print(f"{i:02d}\t{label}\t{w}x{h}\t{path}")
+
+with open(f"{OUT}/manifest.tsv", "w") as fh:
+    for p, w, h, l in manifest:
+        fh.write(f"{p}\t{w}\t{h}\t{l}\n")
+print(f"total {len(manifest)}")