feat: 侧边栏两态重构（统一视图身份）+ 第四轮触控化走查

侧边栏（真机验证）：
- 砍掉悬浮态，只留收起⇄固定展开；TerminalSidebar 单一视图身份，
  内容恒按 288pt 排版、收起=左侧裁切（clipped 宽度动画），
  图标列两态同尺寸同位置，明细淡入淡出，终端随宽度盖上/让开
- 开合入口收敛：Logo 位（收起态=»展开键/展开态=Logo）+ 头部«；
  删底部开合键与 Pin；LeadingHitShape 修 clipped 不裁触摸
- 修 GridBox 从不通知 UI：onGridChange→objectWillChange，
  标题胶囊格子数随开合实时刷新

触控化走查（上一轮，真机部署验证）：
- 窗口按钮 13pt 色点→22pt 圆角方块常显字形；动作条改可点按钮
- TXTech 拼写/配色规范（SSH/mosh/tmux 官方写法+品牌色映射）
- 首页会话卡固定 3 列 4:3；去掉未实现的 ⌘K 提示

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

CLAUDE.md

@@ -42,6 +42,18 @@ xcodebuild -project TerminalX.xcodeproj -scheme TerminalX \
   -clonedSourcePackagesDirPath /tmp/tx-spm build
 ```
 
+## 真机部署（用户体验用，iPad Pro 13″ M5）
+```sh
+IPAD=454D7605-FA87-51F4-BA62-5E58B640188E   # 变了用 xcrun devicectl list devices
+cd apps/TerminalX && xcodebuild -project TerminalX.xcodeproj -scheme TerminalX \
+  -configuration Release -destination "id=$IPAD" \
+  -clonedSourcePackagesDirPath /tmp/tx-spm -allowProvisioningUpdates build
+APP=~/Library/Developer/Xcode/DerivedData/TerminalX-*/Build/Products/Release-iphoneos/TerminalX.app
+xcrun devicectl device install app --device $IPAD "$APP"
+xcrun devicectl device process launch --device $IPAD --terminate-existing ai.athom.terminalx
+```
+自动签名已配好（Team J75A6S5938）。**Release 把所有 `#if DEBUG` 编译掉** → fixture/`terminalx://ui`/`-txSlowMotion` 都不存在，真机跑的必然是真实数据路径；签名后 Keychain/SE 可用（不再回退文件后端）。给用户体验用 Release（Debug 的 SwiftUI 开销会让动效发闷）。
+
 ## 无头验证（本环境无 GUI，用 simctl 截图取证）
 iPad Pro 13(M5) 模拟器 UDID：`2EA9055E-4557-4B20-82AF-56A68AC1D454`（变了用 `xcrun simctl list devices`）。
 ```sh
@@ -65,9 +77,10 @@ sleep N; xcrun simctl io $UDID screenshot /tmp/x.png     # 然后用 Read 工具
 **UI 改造期无头验证（推荐走脚本）**：`scripts/tx-shot.sh <out.png> [-- <启动参数>]` 一步完成装/启/截图/修正方向。
 - **`-txLandscape 1`**：app 侧 `requestGeometryUpdate` 转横屏（设计基准 iPad Pro 13″ 1366×1024）。无 GUI 时模拟器帧缓冲恒竖屏，故脚本截完 `sips -r 90` 转回来（内容已横向渲染）。
 - **`-txUIFixture 1`**：造 3 条**假会话**（mac-studio/ubuntu-cn2/nas-home，含 direct/relay/重连三种状态）灌示意输出进 in-memory 终端，**不建任何传输连接**。设计稿的首页会话卡/轨道多头像/状态徽标都要多会话才有内容，用真机连接验证太慢。见 `UIPreviewFixture.swift`（DEBUG only），与 `-txHost` 互斥。
-- **`terminalx://ui/<动作>`**（`xcrun simctl openurl`）：无头驱动导航与浮层——`home` / `minimize` / `close`(弹确认) / `close-now`(直接关) / `split/v|h`(分屏菜单) / `dismiss` / `session/<n>` / `sidebar/toggle|pin`。比坐标点击稳（不依赖 idb companion，不随布局失效）。模态状态放在 `AppRouter.modal` 而非视图 `@State`，快捷键与 URL 才能共用同一入口。
+- **`terminalx://ui/<动作>`**（`xcrun simctl openurl`）：无头驱动导航与浮层——`home` / `minimize` / `close`(弹确认) / `close-now`(直接关) / `split/v|h`(分屏菜单) / `dismiss` / `session/<n>` / `sidebar/toggle`（`sidebar/pin` 兼容保留=toggle，悬浮态已砍）。比坐标点击稳（不依赖 idb companion，不随布局失效）。模态状态放在 `AppRouter.modal` 而非视图 `@State`，快捷键与 URL 才能共用同一入口。
 - **对拍走查法（还原度靠这个，别靠目测）**：截图 → 用 python+PIL 把设计稿 PNG 与截图统一缩放到 1366×1024 → 裁同区域并排 → 再对元素列做垂直投影扫描量化 y 坐标。缩略图里 `#1E1E2E` 与 `#11121C` 目测分不出，必须采样像素。
 - **坑：`statusBarHidden` 不能挂在 `TerminalScreen`**（它常驻挂载，会连首页一起隐藏）→ 挂 `RootView` 按 `router.route` 判断。
+- **`-txSlowMotion 1`**：所有动效 ×12（DEBUG）。`simctl io screenshot` 自身要几百毫秒，抓不到 240ms 的过渡中间帧 —— 想用截图证明「动效真的在跑」（而不是又退化成硬切）必须先开它。判定法：连发 3 张截图采样同一像素，应得到**三个不同的中间值**；硬切时三张一模一样。
 - 设计稿本体在 `docs/design/`：`UI-DESIGN-HANDOFF.md`(token/规格/交互全表) + `terminalX-iPadOS.dc.html`(13 屏画板) + `render-screens.py`(拆屏，配 headless Chrome 逐屏截 PNG 对拍)。
 
 **M3 挂起→恢复无头验证**：退后台 `simctl openurl $UDID https://apple.com`；冻结 `kill -STOP $(pgrep -x TerminalX)`；解冻 `kill -CONT`；前台 `simctl openurl $UDID "terminalx://resume"`（URL scheme 已注册）。日志 `log stream | grep -E 'MOSHDBG|TXM3'` 看 `wake pulse`→`TXM3 recovered` 时间差判 <3s。**坑：模拟器看门狗会杀掉被 STOP 冻结过久(>~30s)的 app；且模拟器不复现 socket defunct/WG 过期，深挂起需真机锁屏补测。**
@@ -75,7 +88,7 @@ sleep N; xcrun simctl io $UDID screenshot /tmp/x.png     # 然后用 Read 工具
 ## 仓库结构
 - `packages/TXCore` — 零依赖纯逻辑：tmux 解析器/layout/`SessionMachine`(会话状态机+退避重连)/`TmuxControlSequence`(DCS 检测)。
 - `packages/TXTransport` — `SSHSession`(libssh2, 支持外部 fd)/`MoshSession`(mosh_main 桥)/`Transport` 协议；C shim: `CSSH`+`CSSHCore`(libssh2)、`CMosh`+`MoshCore`(mosh)。
-- `apps/TerminalX/iOS` — `TerminalSession`(**一实例=一条会话**：连接编排+tsnet+tmux 路由+mosh 编排+viewport 快照)/`SessionManager`(多会话持有+最小化/关闭语义+生命周期广播)/`AppRouter`(AppRoute .home|.terminal(id) + SidebarState 三态)/`ContentView`(RootView+**SessionCanvas 会话常驻挂载**+TerminalScreen 沉浸轨道页+TmuxStage)/`HomeView`(首页会话卡+主机网格)/`RailSidebar`(56pt 轨道+288pt 面板三态)/`TerminalChrome`(浮起标题/状态胶囊+提示条)/`TXParts`(设计令牌小件+终端文本镜像)/`TmuxController`(tmux 网关)/`TsnetProbe`(M1 自检)/`Theme`(TXAccent 恒定 blurple + TXChrome 中性阶×4 + TXFlavor 终端配色)/`HostStore`(主机列表 JSON 持久化)/`UIPreviewFixture`(DEBUG 无头 UI 验证脚手架)。
+- `apps/TerminalX/iOS` — `TerminalSession`(**一实例=一条会话**：连接编排+tsnet+tmux 路由+mosh 编排+viewport 快照)/`SessionManager`(多会话持有+最小化/关闭语义+生命周期广播)/`AppRouter`(AppRoute .home|.terminal(id) + SidebarState 两态 collapsed|pinned)/`ContentView`(RootView+**SessionCanvas 会话常驻挂载**+TerminalScreen 沉浸轨道页+TmuxStage)/`HomeView`(首页会话卡+主机网格)/`RailSidebar`(`TerminalSidebar` 两态唯一视图：288pt 全宽排版+railWidth 图标列，收起=左侧裁切)/`TerminalChrome`(浮起标题/状态胶囊+提示条)/`TXParts`(设计令牌小件+终端文本镜像)/`TmuxController`(tmux 网关)/`TsnetProbe`(M1 自检)/`Theme`(TXAccent 恒定 blurple + TXChrome 中性阶×4 + TXFlavor 终端配色)/`HostStore`(主机列表 JSON 持久化)/`UIPreviewFixture`(DEBUG 无头 UI 验证脚手架)。
 - UI 已从 Demo 转入**商业化改造**：设计定稿见 `docs/design/UI-DESIGN-HANDOFF.md`（Nocturne chrome + Catppuccin 终端 + 沉浸轨道），路线图与进度见 `docs/HANDOFF.md §12`。
 - `vendor/` — 所有非 Swift 依赖本地化：`libghostty-spm`(GhosttyKit)/`MSDisplayLink`/`libssh2`/`mbedtls`/`tsnet-bridge`(Go)/`mosh`(blinksh/ios 分支)/`protobuf`(3.21.12)；`build/mosh/`(手写 config.h+CMakeLists)。
 - `artifacts/` — 预编译 xcframework（**有意提交**，非 gitignore）：`CSSHCore`/`TsnetBridge`/`MoshCore`。
@@ -98,6 +111,13 @@ sleep N; xcrun simctl io $UDID screenshot /tmp/x.png     # 然后用 Read 工具
 - **tmux 多 pane 尺寸走"路线 b"**：app 按全屏格子发 `refresh-client -C WxH` 让 tmux 布局，pane surface 尺寸严格取 layout rect（%output 按 tmux pane 宽高排版，二者不一致必换行/清屏错乱）；pane surface 的 resize 回调**只断言不反向驱动 tmux**（防反馈环）。diff 用 full layout、渲染用 visible layout（zoom 免费）；SwiftUI identity 只用 paneID（布局变不重建 surface）。新 pane 在 `capture-pane` %end 前丢弃其 %output（tmux 单线程串行保证快照不缺不重）。
 - **tmux 网关字节必须单消费者保序**：多个 `Task{@MainActor}` 到主线程顺序无保证，多 pane 高吞吐会打碎 % 协议 → 用 `TmuxByteChannel`(AsyncStream) 单消费者。
 - **导航不得销毁会话**：终端**不能**走 `fullScreenCover`——① surface 一旦从视图树摘除，ghostty 释放 grid，内容全丢；② matchedGeometry（最小化缩回首页卡）要求两端同层级，独立 presentation 层做不到。故 `SessionCanvas` 把所有会话 ZStack 常驻挂载、只切 opacity + `allowsHitTesting`（沿用 tmux 切 tab 已验证的手法），画布恒全屏 → 切路由不触发 PTY resize。
+- **侧边栏两态（收起⇄固定展开，悬浮态已被用户裁决砍掉）必须是同一个视图身份**（`TerminalSidebar`）：内容恒按 288pt 全宽排版，收起只是容器宽度收到 railWidth + `clipped()`（"收起=展开在左侧裁切"）；最左 railWidth 是图标列，两态同尺寸同位置，明细随展开淡入；视图直接参与布局，收起=明细淡出+终端从右盖上来（用户定稿效果）。开合入口只有两个：**Logo 位**（收起态显 » 展开键，展开态还原 Logo——将来 App Logo 设计与展开按钮一体）与头部 « 收起键。曾经"轨道+面板两套视图 + overlay/pinned 两个面板实例"，三态切换视图身份互换 → 动画混乱硬切。
+- **终端格子数不是"首次布局后稳定"**：侧边栏开合就会 resize。读 `screenGrid` 的视图（标题胶囊 `164×50`）靠 `GridBox.onGridChange → session.objectWillChange` 转发刷新，否则数字停在旧值（嵌套可观察不冒泡这坑的又一面）。
+- **`clipped()` 只裁绘制不裁触摸**：收起态下侧边栏被裁掉的明细区（整行按钮）会伸进终端里抢点击 → 整行按钮用 `LeadingHitShape`（`contentShape` 限制命中区到当前可见宽度，Animatable），纯明细控件再加 `allowsHitTesting(expanded)`。
+- **状态变更必须包在 `TX.Motion` 的动画事务里**：`AppRouter` 的 route/modal/sidebar 全走 `animated{}`。裸改 `@Published` → 视图上写好的 `.transition` 拿不到事务，**静默退化成硬切**（首页⇄终端、关闭确认、分屏菜单都曾是这么"啪"地跳出来）。收在 router 里点击/⌘快捷键/无头 URL 才是同一手感。阴影同理只走 `View.txShadow(TX.Elevation.*)`，别手写 `.shadow`（深色底上大半径高透明度会糊成脏斑）。
+- **贴屏幕边缘的容器不许收小圆角**：设备屏幕本身是 ~22pt 大圆角，在那儿再画 6pt 小角必被"吃掉"（小角整段落在屏幕圆角之外，切口露出底色三角）。终端 pane 用 `UnevenRoundedRectangle` **只在朝 chrome 的角收圆角**，顶边/右边铺满物理边缘、不收角不描边（描边用负 padding `top:-1/trailing:-1` 推出屏外）。Stage Manager 小窗同理。
+- **沉浸页的安全区由底栏自己让位**：整屏 `ignoresSafeArea()`，底部区高 = `TX.Layout.footBand(safeBottom)` = 34 + 安全区，内容**居中**（贴住物理底边又让开 home indicator）。**坑**：只放开顶边时，颜色型 `.background` 会溢进底部安全区、内容却停在上沿 → 屏幕最下面一条 24pt 空带 + 轨道底色铺满，一眼没对齐；遮罩态/Pin 态面板脚还会差 24pt（一钉住就跳）。安全区读数用 `TXScreenMetrics`（`GeometryReader` 必须在 `ignoresSafeArea` **之前**，否则读到 0）。
+- **`.frame(height:)` 压不住内容驱动的最小高度**：它只是给了个框，不声明撑满的子视图按自身理想高度**居中**放进去 → 一排卡片高矮不齐。要么子视图自己 `.frame(maxHeight: .infinity)`，要么（内容天生比框高时，如 `TXTerminalMirror` 的行堆叠）把内容放进 `Color.clear` 的 `overlay` —— overlay 不参与父视图定尺，尺寸完全由外部决定，溢出交给 `clipped()`。
 - **首页缩略卡不许再开 surface**：一个 ghostty surface 只有一个 IOSurfaceLayer，同处两地/离屏 Metal 渲染是已修过的泄漏雷区。缩略卡走 `TerminalSession.captureSnapshot()`（`readViewportText()` 抓尾部若干行）+ `TXTerminalMirror` 文本渲染（底对齐），代价只是丢 ANSI 颜色。
 - **嵌套 ObservableObject 不冒泡**：`SessionManager` 的 `@Published sessions` 不会因某条会话内部 `@Published` 变化而发布。凡显示会话状态的行/卡片都要抽成独立视图用 `@ObservedObject var session:` 直接订阅（见 `SessionSidebarRow`/`SessionStatusRow`）。
 - SourceKit "No such module" 是索引噪声，**以 `swift build`/`xcodebuild` 为准**。