# Notch 动作与状态转场

## 弹性收纳预览（2026-09-21，完整外壳修订）

2026-09-23 正式安装后修订：隐藏的窄条必须始终贴住物理屏幕右边缘。屏幕工作区变化不得把完整窗口坐标与隐藏裁切坐标混算，也不能把右侧系统 Dock 的工作区边界当成屏幕边缘。普通运行、计数或尺寸更新保持隐藏。新未读完成、新错误、新审批/问题按请求或结果身份识别，沿现有弹簧完整恢复到正常紧凑状态；重复轮询和已有提醒不能反复打断手动收纳。拖动时收到新提醒，先保留跟手，再于松手时恢复；减少动态效果直接到位。此规则取代旧版“隐藏期间阻止所有自动恢复”，已获得安装授权，修复验收后更新正式 Notch。

2026-09-23 左端修正：用户明确要被拉着的左端越拉越细，上一版“两端不压扁、只收腰”的理解作废。右侧固定端保持接触，向左侧自由端连续收窄，自由端及里面的机器人/内容一起按拉力的垂直方向压缩；不再保留原粗细的头部。厚度随距离单调变化，回程同步恢复，隐藏终点仍是原来的外壳裁切。保留 128 pt 前段跟手、240 pt 单次手势软上限和解析回弹，不引入每帧排版。验证绑定：motion-language → 位置、图层形变和释放速度同一时间轴；motion-contract → 左端厚度确实下降、沿长度不先窄后粗、内容与外壳一致、端点恢复和原生回归。继续只更新独立预览。

刷新修订：用户反馈回弹闪烁、似乎不足 60 fps。本轮保留已接受的轮廓与物理曲线，检查显示同步、原生窗口重排和裁切层更新。验收同时记录真实回调间隔、每帧提交耗时、窗口改尺寸次数和裁切层分配次数；不能把定时器频率或离线生成 60 张图片当作屏幕实际帧率。交互仍须保留可打断、单击提交与拖动不误提交。

算法修订：弹簧改用阻尼振子的解析解，以同一条绝对时间轨迹供状态与合成器读取，避免卡顿时累积积分误差或慢放；重定向接住当前位置与速度。连续圆角数据采用有容量上限的局部缓存，凸包复用已排序的局部轮廓。尾段采样只在误差预算内合并，所有图层使用同一份时间表；真实端点仍使用原始贝塞尔轮廓。验收比较相同输入的计算耗时，另测 30/60/120 Hz 与不规则时间步、速度连续性、轮廓等价性和采样误差，不把算法基准当作屏幕帧率。

Request Anchor：整块外壳像一块橡胶，不能像方块拖着弯曲细尾巴；收纳后保留原来外壳的一小截，宽高及圆角不另做变形。保留二维跟手、速度继承和可打断回弹。此约定替换上一版的细尾巴与 6×28 pt 新造凸起，继续使用独立原生预览，不调用模型、不替换正式 DSH.app。执行方式为 single-agent。

视觉沿用现有黑色外壳和 16 pt 连续圆角。拉伸轮廓基于原外壳与完整边缘接触面的凸包，再沿拉力轴连续收腰，受力边沿着拉力展开；只有一条封闭外轮廓，没有另外拼上的尾巴。短距离抓取点二维 1:1 跟手，远距离增加径向阻力，释放后继承映射后的双轴速度。垂直回位保留弹性，向屏幕内收纳的阻尼更大，避免残留部分甩出画面。收纳只平移原外壳，保留原高度及连续圆角，露出左侧 8 pt；悬停只多露出到 14 pt，不拉伸宽高。收纳时用同一条轮廓直接绘制黑色橡胶，暂停玻璃背景，正文和机器人保留独立的小型圆角裁切；恢复后回到玻璃材质。释放时固定原生画布尺寸，恒定尺寸回弹的轮廓与内容图层采用同一物理轨迹的 120 Hz 采样，由系统合成器连续播放；状态回调目标节拍 60 Hz，尺寸变化时才继续显示同步排版。禁止逐帧重建蒙版或发布姿态触发 SwiftUI 重排，重新抓取须接住当前呈现位置。

| Active concept | 决策 | 实现位置 | 验证 |
| --- | --- | --- | --- |
| motion-language | 抓取点、双轴速度和中途打断连续；松手同位置事件不能清零速度 | EdgeDockModel / EdgePanGesture | 八方向、松手第一帧、长暂停后释放、反向抓取 |
| motion-contract | 同一个外壳贯穿拉伸、收纳、探出；自由端与内容同步变细 | EdgeDockGeometry / EdgeDockSurface / Panel | 左端厚度、内容仿射变换、60 帧回弹及原形端点对比 |
| necessary-design-judgment | 收纳是原物体移出画面；拉力不能变成另一条装饰曲线 | EdgeDockPose / EdgeSpring | 单一封闭轮廓、完整接触面、保留原高度和曲率 |

Motion id：`elastic-edge-dock`。4 pt 二维距离识别拖动；24 pt 位移提交收纳/恢复，小幅拖动回原位，快速短甩按释放速度投影判断。松手后主要位移约 0.2–0.4 秒，细小余动在约一秒内完全收敛。中途可重新抓取，不等待动画结束；减少动态效果时直接到终点。滚轮和原生文本选择保留原行为，拖动选项不会提交答案。隐藏期间普通更新保持收纳，新关注事件完整恢复紧凑状态；问题正文随后由悬停或点击展开。

Apple 参考：[Designing Fluid Interfaces](https://developer.apple.com/videos/play/wwdc2018/803/)，采用直接响应、双轴重新定向、速度继承和可打断原则；原生 Swift/AppKit 验收替代网页专用验证器，不宣称通过 Apple 认证。

验证覆盖八方向抓取、释放速度、回弹、反向打断、任务尺寸变化、单一轮廓及接触宽度；收纳和探出阶段与 RootView 的原始连续圆角逐点对比。原生鼠标与实际玻璃窗口另外验收，详见 [实现和验证记录](docs/elastic-edge-dock.md)。

## 当前材质试用：暗色 Liquid Glass（2026-09-18）

用户希望加强毛玻璃的视觉表现，同时保持问答文字清晰。采用 macOS 26+ 原生 Regular Liquid Glass、深色外观和轻度黑色着色；旧系统保留 HUD 背景。现有字形、机器人、状态转场和自适应高度保持原有逻辑。原生玻璃负责边缘折射与交互反馈，文字放在 contentView 中，选项说明使用更清楚的次要文字色。内部按钮不再叠加独立玻璃。

玻璃右侧圆角延伸到面板裁切边界之外，左侧保留 16 pt 连续圆角；同一个原生窗口的 0.4 秒尺寸动画驱动材质与内容边界，不能出现第二套外壳缩放。减少透明度时使用不透明正文底色，减少动态效果沿用原来的即时尺寸变化。`DSH_NOTCH_MATERIAL=hud` 可启动原有材质作为对照。

| Active concept | 决策 | 实现位置 | 验证 |
| --- | --- | --- | --- |
| accessibility-usability | 正文不折射；次要文字提高明度；保留系统减少透明度路径 | RootView / NotchTokens | 原生浅色、深色及彩色背景预览，长选项与输入框检查 |
| motion-contract | 材质和正文共用窗口尺寸，不重置现有状态动画 | NotchGlassSurface / NotchPanel | 原生展开、收起、快速反转；右边缘与四角逐帧检查 |

视觉重点是深烟灰弧面与原生高光；正文和字体保持安静。此节是当前工作约定，下方动效验收记录属于此前迭代。

展开列表配色修正：玻璃上的小字不用饱和品牌蓝。数量标签改为 95% 白色，运行文字用 `#C2D4FF`、状态点用 `#8FB0FF`，完成色用 `#A3E8B8`、失败点用 `#FFA899`。状态文字从 9 pt 提到 11 pt medium，状态点取消蓝色模糊光晕。紧凑状态动画仍保留原有品牌色。已用生产 RootView 在浅色、深色及彩色背景上检查运行/完成列表，并通过内容高度回归。

试用验证：13 个高度场景、滚动条回归和原生窗口几何检查通过。使用生产材质与 RootView 的离线窗口，已查看浅色、深色和彩色背景上的标题、正文与选项说明，单次点击提交并收起通过。独立 NSPanel 的材质类型、伸缩边界及右侧裁切有自动检查；CUA 对子窗口的截图返回缩小组合图，不能作为该模式的清晰度证据。审美强度仍以用户在正式 Notch 中试用反馈为准。

本次范围：运行转为审核、成功或失败；分别覆盖只有一个任务，以及两个任务中一个改变状态。保留用户最近同步的玻璃外壳、排版和机器人资源；候选效果先在独立原生预览中验收，不安装到 DSH。

## 动效规则

由当前蓝色弧线出发，头部沿路径前进、尾部跟随，途中连续变色。黄色审核和绿色成功向上，红色失败向下。到达目标后沿圆周画线，再出现实心圆及符号。有其他任务运行时，线条从目标色连续回到蓝色运行弧；最后一个任务结束或等待审核时，笔画收在目标圈，源槽随之收起。不得用整圈平移或同时淡入两个圆代替笔画移动。

沿用已接受的 0.95 秒笔画时间轴和 19 pt 圆直径，颜色、字形与坐标使用现有定义。自动展开审核面板等待笔画结束，主动交互不因动画被禁用；重复轮询不重播，旧回调不能覆盖新状态。减少动态效果直接显示最终状态。

## 设计依据与验证

| Active concept | 决策 | 实现位置 | 验证 |
| --- | --- | --- | --- |
| motion-language | 三种结果共用有方向的笔画语义；保留当前弧线作为起点 | StatusFlight / StatusOrbitView | 原速六场景原生预览与逐帧截图 |
| motion-contract | 同一时间轴约束路程、颜色、填充、布局；只在有剩余工作时返回 | BoardModel / OrbitLayout / OrbitMotionFrame | OutcomeProbe、MotionProbe、取消和重复事件检查 |

视觉沿用纯黑紧凑外壳、细线与圆角字形；本轮不增加装饰。主要识别特征是线条本身连续转移。原生 AppKit/SwiftUI 使用原生渲染证据，浏览器 motion validator 不适用。

## 本轮验证

黄色已使用 StatusFlight 的 decision 结果类别，沿红绿共享的路径、时间轴和填充顺序绘制。单任务中源数字与黑底在线条离开时淡出，避免收缩时压住结果圆。自动展开推迟到审核笔画完成，取消审核会取消待展开请求。

OutcomeProbe 六场景与重复事件、快速取消、连续结果检查通过；项目原 MotionProbe（含减少动态效果静止检查）通过。原生渲染器采样六场景的逐帧图像并人工检查，证据位于 `本地 motion proof 输出目录`。六场景本地预览已展示；运行中 DSH 未安装此候选，用户对自然程度的验收仍以预览反馈为准。

## 决策回复回程（本轮）

覆盖完整的 `蓝 1 → 黄 → 蓝 1` 与 `蓝 2 → 蓝 1＋黄 → 蓝 2`。单灯保留已接受的清空填充、从顶部画蓝环的回程；双灯由黄圈抽出笔画，沿既有路径的返回段汇入蓝环，再把数字从 1 渐变到 2。黄灯、线条与外壳使用同一进度，源填充消失后才收起槽位。若面板正在折叠，回程从折叠完成时开始，使线条可见。回复很快时接在去程后播放；取消且没有恢复运行时不制造蓝灯；轮询不重播，旧回调不覆盖新回程。

Active motion-language 绑定：回复恢复同一任务的可见因果 → DecisionReturn / StatusOrbitView → 两条往返原速预览。Active motion-contract 绑定：数字在汇入时更新、路径及旋转速度连续、折叠不吞动画 → BoardModel / DecisionReturnFrame → OutcomeProbe 和确定时间逐帧渲染。沿用当前颜色、19 pt 灯、0.95–0.98 秒时间轴、系统减少动态效果设置。

## 双语录屏

录屏标题使用中文在上、英文在下，只呈现同一个转换名称。六格与单景均保留固定标题区，英文不挤占动画空间。36 个场景由同一份生产源构建，录屏工具仅替换传输层并发送定向待机动作，不重写状态曲线。