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>

docs/HANDOFF.md

@@ -286,6 +286,79 @@
 - **原生终端** → 状态胶囊 `direct | ssh | 原生窗口 · 不经 tmux`
 - **完整真实路径**（`-txOpenAsHost`）→ 首页「正在连接 192.168.99.83」→ 首页上弹选择器（标题「连接到 …」）→ 选 `main` → 进终端页 `tmux main` + 轨道 window `0/1/2/3/4`
 
+### 12.3h 质感走查：动效 / 阴影 / 圆角 / 安全区（用户第三轮走查，2026-07-25）
+
+用户反馈四类瑕疵（**风格保持不变，只修质感**）：浮层"特别难展开和消失"缺过渡、胶囊阴影太重不够扁平、终端小圆角与 iPad 屏幕大圆角打架（全屏时右上角被吃掉）、底部混乱没考虑安全区。逐条修完并补了同类问题：
+
+**1. 动效令牌化 + 补齐缺失过渡（`TX.Motion`）**
+- 新 `TX.Motion`：`standard`(0.24 easeOut) / `quick`(0.14) / `slide(edge)` / `pop`(0.96→1 缩放+淡入) / `pushBack`(首页推远)。**统一响应「减弱动态」**（`UIAccessibility.isReduceMotionEnabled` → 时长减半 + 位移退化为纯淡入淡出）。
+- **根因**：`AppRouter` 里只有侧边栏包了 `withAnimation`，`route` / `modal` 的变更**裸着改** → 视图上写好的 `.transition` 拿不到动画事务，全退化成硬切。现在 `enter`/`goHome`/`present`/`dismissModal`/`toggleSidebar`/`togglePin` **全部经 `animated{}`**，点击 / ⌘ 快捷键 / 无头 URL 三条入口自动同一手感。
+- `TXModalScrim` 拆成两段转场（遮罩 `.opacity` + 卡片 `TX.Motion.pop`）：整块套一个 `.transition(.opacity)` 只是一起变淡，没有弹出感。
+- 补：无 tmux 横幅显隐、`TmuxInstallSheet`、`TerminalStateOverlay`（连上后淡出）、提示条文案随三态切换、会话卡增减、选中态/状态点变色。
+- **按压反馈**：新 `TXPressStyle`（缩放 + 压暗 140ms），替换全部 `.buttonStyle(.plain)`。深色界面里 `.plain` 完全没有按下反馈，主机卡/会话卡这种"点下去要等几百毫秒"的入口尤其伤手感。
+- 会话卡改成**整张一个 Button**，卡脚「回到会话 →」退化为文字提示（同一动作做成嵌套 Button 只会抢命中区 + 两套按压反馈）。
+- **`-txSlowMotion 1`**（DEBUG）把所有动效 ×12：`simctl io screenshot` 自身要几百毫秒，抓不到 240ms 的中间帧，没这个开关就无法用截图证明"动效真的在跑"。验证方法：连发三张截图，采样同一像素应得到**三个不同的中间值**（硬切时三张完全一样）。
+
+**2. 阴影扁平化（`TX.Elevation`，刻意偏离设计初稿）**
+设计稿给的是 CSS 值（胶囊 `0 10px 30px rgba(0,0,0,.55)`、对话框 `0 30px 80px .7`），在深色底上会糊成一团脏斑 —— 半透胶囊叠重投影像"漏墨"，终端文字从投影里穿过去。改为：`floating`(.22/7/y2) · `panel`(.28/16/x4) · `dialog`(.34/16/y6) · `card`(.16/4/y2) · `cardFocused`(.24/8/y3)，分层交给描边与材质，胶囊底不透明度提到 .92 补偿。统一经 `View.txShadow(_:)`，视图里不许再手写 `.shadow`。
+顺带补上**遮罩态侧边栏浮层一直漏掉的投影**（设计要求 `24px 0`，故 `panel` 是唯一带 x 位移的）。
+
+**3. 圆角不再与屏幕圆角打架（`paneShape`）**
+终端右上角贴着屏幕物理边缘，那里设备本身是 ~22pt 大圆角 —— 再画 6pt 小圆角必然被"吃掉"（小圆角整段落在屏幕圆角之外，切口处露出底色三角）。改为 `UnevenRoundedRectangle`：**只在朝 chrome 的角收圆角**（左上/左下/右下 6pt），顶边与右边**直接铺到物理边缘、不收角不描边**，由屏幕自己的圆角收口（Stage Manager 小窗同理，窗圆角接管）。
+- 描边用负 padding（`top:-1, trailing:-1`）把顶边/右边那两条**推出屏外**：留着就是贴在屏幕边上的一圈多余框线。
+- 顺带取消顶边/右边的 2pt 缝（2pt 是**pane 之间**的缝，不该出现在屏幕边缘），终端格子从 163×48 涨到 164×50。
+
+**4. 安全区：chrome 铺满物理屏，底栏自己让位（`TX.Layout.footBand` / `capsuleTop`）**
+- 原来 `.ignoresSafeArea(edges: .top)` 只放开顶边 → 底部内容停在安全区上沿，屏幕最下面留一条 24pt 的空带（"没铺到底"），而**颜色型 `.background` 默认会溢进安全区**，于是轨道底色铺满、内容却停在 24pt 之上，一眼就是没对齐。
+- 现在整屏 `.ignoresSafeArea()`，底部区高度 = `footHeight(34) + safeBottom`，内容**在其中居中** → 既贴住物理底边又让开 home indicator。提示条 / 侧边栏脚 / 轨道齿轮三者中心线同一条 y（995），上方分割线仍同在 964。
+- **顺带修掉一个状态跳变**：遮罩态面板铺满全高、Pin 态被安全区推高 24pt，一钉住面板脚就跳一下。现在两态完全一致。
+- 安全区读数经新 `TXScreenMetrics`（`GeometryReader` 必须在 `ignoresSafeArea` **之前**，否则读到 0）。
+- 胶囊顶距：`capsuleTop(safeTop)` —— iPad 隐藏状态栏后无遮挡用设计值 14；灵动岛/刘海机型（safeTop>30）按硬件下移。**iPhone 17 Pro 模拟器实测**胶囊落在岛下方、底栏在 indicator 之上。
+
+**5. 同类问题（走查中发现，一并修）**
+- **会话卡不等高**（一排卡上下边对不齐）：`TXTerminalMirror` 的行堆叠有内容驱动的最小高度，外层 `.frame(height:)` 压不住它 —— `.frame(height:)` 只是给了个框，**不想撑满的子视图会按自身理想高度居中放进去**。改为把行堆叠放进 `Color.clear` 的 overlay（overlay 不参与父视图定尺），尺寸完全由外部决定，溢出的旧行被 `clipped()` 切掉（正是想要的：底对齐留最新输出）。
+- 会话卡从不换行的 `HStack` 改 `LazyVGrid`（最多 3 列）：第 4 条会话进来原先会把所有卡压扁。高度由死写 560 改为 `min(560, max(300, 可用高度×0.56))`，竖屏/分屏/小 iPad 上不再把「全部主机」挤出屏外。
+- 首页滚动内容铺到物理底边（`ignoresSafeArea(.bottom)` + 内容 padding 补 safeBottom），末行能完整滚到 indicator 之上。
+- 窄窗口适配：主机网格 4→2 列、左右留白 40→20、搜索框 220 固定改可伸缩、提示条只留 2 条（4 条在 iPhone 上折行把 34pt 带撑破，且强制单行 `lineLimit(1).fixedSize()`）。
+- 胶囊红/黄圆点命中区 22×30 → 26×34（13pt 视觉不变）：关闭这种误触代价高的动作不该给这么小的目标。
+- 搜索框补聚焦态描边（键盘焦点可见，无障碍底线）。
+- 删掉 `HomeView` 里**嵌套重复定义**的 `ConnectingRow`（与文件级那份一字不差，编译能过但是死代码）。
+- 遮罩浓度令牌化 `TX.Scrim`（对话框 .5 / 侧边栏 .42），不再散落 `Color(hex: 0x0A0B12)`。
+
+**验收**：iPad 13″ 横屏逐屏对拍（终端 / Pin / 遮罩 / 关闭确认 / 分屏菜单 / 首页）+ iPhone 17 Pro 竖屏（灵动岛 + indicator）；像素采样确认 —— 右上角 `(1365,0)` 为终端底色（不再是底色三角）、两态面板脚同在 964/982–991、三张会话卡同为 166..710、遮罩把终端文字亮度 185→97；TXCore 45 tests 绿。
+
+### 12.3i 触控化与标签规范（用户第四轮走查 + **真机部署**，2026-07-26）
+
+1. **首页会话卡固定 3 格 4:3**：`LazyVGrid` 列数写死 3（不再 `min(3, count)`），不足 3 条自然从左往右排、卡片尺寸不随会话数跳动；高度改 `.aspectRatio(4/3, contentMode: .fit)`，删掉按屏高算高度那段。
+2. **技术标签规范（新 `TXTech`）**：
+   - **拼写**：照各自官方写法 —— 缩写全大写（`SSH`）、项目名按作者写法（`mosh`/`tmux`/`tsnet` 本来小写）、产品名照抄（`macOS`/`TrueNAS`）。**`TXSectionLabel` 不再 `.uppercased()`** —— 它会嵌主机名/会话名，之前渲染成 `TMUX · MAC-STUDIO · DEV` 把名字全改错了；轨道标签同步改 `tmux`。
+   - **配色**：传输协议冷色区分（`mosh` teal / `SSH` blue，二者互斥所以一行只出现一个）；`tsnet` 用 app 强调色（招牌能力）；凭据名回中性（那是用户命的名，不是技术标签，避免一排全彩色）。主机卡图标染**发行版品牌色**（Ubuntu 橙→peach、Debian/树莓→red、Fedora/TrueNAS→blue、Arch→teal、macOS→中性银），认不出的回中性。徽标只染文字+描边、底色 12%。
+3. **关闭/最小化按钮重做**：原 macOS 交通灯式 13pt 纯色圆点三处不合适 —— 纯色块不说明自己干什么（mac 靠 hover 浮字形，触屏没有 hover）、13pt 命中目标太小、圆点是 mac 窗口语汇与本 app 圆角矩形语汇不搭。改 **22pt 圆角方块 + 常显字形**（`✕` / `⌄`），保留红=关闭、琥珀=最小化的颜色语义，底色 14% 不铺满，命中 26×34，间距放宽。`⌄` 而非双向内收箭头：后者在 9.5pt 下糊成一团，且向下正好对上设计的「下滑最小化」手势。
+4. **侧边栏自身的平移动画（新 `leadingColumn`）**：原来是 `if pinned { 面板 } else { 轨道 }` —— 两者**互换**只能硬切，用户看到面板"消失"、轨道"出现"，没有平移。改为轨道**常驻**在底、面板叠在上，列宽随三态动画（56/56/288）+ `clipped()`：收起时面板向左滑出并被裁掉、轨道从背后露出。慢放实测 1.2s 处列宽正处于中间态（≈140pt），确认逐帧插值而非硬切。
+5. **去掉命令面板**：底部 `⌘K 命令面板` 与首页搜索框的 `⌘K` 提示一并删除（快捷键体系属 UI-5，未实现的提示等于假承诺）。
+6. **底部改动作条 `TerminalActionBar`**（原 `TerminalHintBar`）：iPad 大概率没接键盘，「竖分屏 / 新建 window / 回首页」只写成 `⌘D` 文字提示等于这些功能对触控用户不存在 → 改成**常驻可点按钮**（图标 + 文案，26pt 高胶囊）。非 tmux 会话下前两个灰显但保留（不隐藏，免得布局跳）。左侧上下文文案改为**真实会话状态**（`mac-studio · tmux dev · 3 windows`）—— 此前写死「已连接妙控键盘 · 附加行已收起」，没接键盘时那是假话。措辞与侧边栏统一为「新建 window」。
+
+**真机部署（用户体验用）**：`-configuration Release -destination 'id=<iPad UDID>' -allowProvisioningUpdates` 自动签名（Apple Development: JIANKUAN YANG / Team J75A6S5938）→ `xcrun devicectl device install app` + `process launch`。**Release 里所有 `#if DEBUG` 的 fixture / `terminalx://ui` / `-txSlowMotion` 全部编译不进去**，所以真机跑的必然是真实数据路径（首次运行落在「还没有主机」空状态）；签名后 Keychain/Secure Enclave 可用，凭据走系统钥匙串而非文件回退。
+
+### 12.3j 侧边栏三态动画重构：统一视图身份（用户第五轮反馈「动画混乱」，2026-07-26）
+
+用户判词：三态切换动画混乱；收起态应理解为「展开态在左侧裁切一部分」，允许改 UI 让两态最左侧图标同尺寸同位置。
+
+**根源**（12.3i 的 leadingColumn 只修了一半）：① 轨道 `RailView` 与面板 `SidebarPanel` 是两套视图，元素尺寸/位置互不对应（logo 34/30、头像 38/26、徽标 34×30/26×22，纵向节奏也不同）→ 就算列宽在动画，内容仍是两张不相干的画面交叠；② 遮罩态面板挂全屏 overlay、Pin 态面板是 leadingColumn 里**另一个实例** → overlay⇄pinned 切换视图身份互换，一个滑出一个滑入互相打架；③ 遮罩/投影靠 `if` 插拔。
+
+**重构**（`RailSidebar.swift` 整文件重写为 `TerminalSidebar`，`ContentView.screen` 重组）：
+1. **三态唯一视图**：内容恒按 288pt 全宽排版；收起 = 容器宽度收到 railWidth + `clipped()`（字面实现「左侧裁切」）。最左 railWidth 为**图标列**：logo 30 / 裸图标 17pt / 头像 30 / window 徽标 26×22 / 状态点 / 开合键 / 齿轮，两态同尺寸同位置；右侧明细（标题/副行/快捷键/选中底）`opacity(expanded)` 淡入淡出。
+2. **行对应关系**：轨道的 24pt 短分隔线 ⇄ 面板的分组标题（同一行两种密度，交叉淡化）；轨道 `tmux` 迷你标签 ⇄ `tmux · 主机 · 会话` 分组标题；搜索裸图标 ⇄ 搜索框（放大镜位置几乎重合）；底部统一为「tailnet 状态行 / 开合键行 / 分割线+齿轮 footBand」，两态元素不增不减。
+3. **组合**：舞台前的占位列只在 Pin 态推到 288（保持「钉住/解除各 resize 一次」）；遮罩与侧边栏**常驻**在同一 overlay 里，遮罩动 opacity、投影(`Elevation.panel`)动 opacity —— 遮罩⇄Pin 时侧边栏本体**一动不动**，只有遮罩淡出+舞台平移。
+4. **新坑：`clipped()` 只裁绘制不裁触摸** —— 收起态下整行按钮被裁掉的明细区会伸进终端抢点击。整行按钮用 `LeadingHitShape`（Animatable `contentShape`，命中区=当前可见宽度）；纯明细控件（搜索框/Pin/新建 window）再加 `allowsHitTesting(expanded)`。
+5. **验证**（fixture + ×12 慢放 + 逐帧像素采样）：收起→遮罩（遮罩逐帧变暗 30→29→22）、遮罩→收起（面板前沿扫过采样点+遮罩渐浅）、遮罩→Pin（胶囊中间帧 709px vs 终值 826px，舞台平移中）、Pin→收起（427→362）均有中间帧，无硬切。
+
+**用户复核后追加裁决（同日）——砍掉悬浮态，只留两态**：Pin→收起的"明细淡出 + 终端从右盖上来"效果被点名保留，展开即反向。
+- `SidebarState` 只剩 `collapsed|pinned`；`togglePin`/`dismissOverlaySidebar`/遮罩/浮层投影全删；`TerminalSidebar` 直接进 HStack 参与布局（无占位列），开合就是它的宽度动画（56⇄288），各触发一次 resize；点终端**不再**收起侧边栏（固定是持久态）。
+- **开合入口收敛**（此前顶部/底部两个收起键冲突、底部那枚缩在左下角不协调）：Logo 位=开合主入口（收起态显 » 展开键、展开态还原 `›` Logo，同框同位交叉淡化——用户定稿：将来 App Logo 设计与展开按钮一体）；头部 « 收起键保留；底部开合行删除；Pin 键删除（两态下无意义）。`terminalx://ui/sidebar/pin` 兼容保留=toggle。
+- **顺带修掉暴露的旧缺陷**：标题胶囊的格子数读 `screenGrid.value` 却从不刷新（旧注释"首次布局后稳定，不必 @Published"在"开合即 resize"下不成立，表现为开合后数字停在旧值）→ `GridBox` 加 `onGridChange`（去重）、`TerminalSession` 转发 `objectWillChange`。验证：展开 135×50 / 收起 164×50 实时跟随。
+- 验证：展开动画 pane 左描边逐帧 58→198.5→261→290pt（easeOut 先快后慢），无硬切；收起态 Logo 位为 »、底部只剩状态点/分割线/齿轮；展开态头部仅 Logo+名称+«。
+
 ### 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>