diff --git a/.agents/notes/proposed/feature/2026-10-21-floating-window-edge-recovery.i18n.yaml b/.agents/notes/proposed/feature/2026-10-21-floating-window-edge-recovery.i18n.yaml new file mode 100644 index 0000000000..d03ffbf82e --- /dev/null +++ b/.agents/notes/proposed/feature/2026-10-21-floating-window-edge-recovery.i18n.yaml @@ -0,0 +1,40 @@ +# Bilingual-pair consistency record for 2026-10-21-floating-window-edge-recovery.md (docs/i18n/README.md): per heading +# section, a hash of its English and Chinese blocks outside code blocks and generated regions. +# After editing either side, bring the other along and re-record with: +# pnpm run verify-translation-pairing --write .agents/notes/proposed/feature/2026-10-21-floating-window-edge-recovery.md +/agent-note-force-directed-edge-recovery-for-floating-dock-panels: + en: 7ba35ffa8515b87d + zh: 684a6bb16beb7742 +/agent-note-force-directed-edge-recovery-for-floating-dock-panels/problem: + en: a2b601d95a23d7bf + zh: f40f06ee37fae43f +/agent-note-force-directed-edge-recovery-for-floating-dock-panels/proposal: + en: 737f73d512805128 + zh: 1b7fc14d1effb2b8 +/agent-note-force-directed-edge-recovery-for-floating-dock-panels/proposal/legal-region-and-displayed-position: + en: 7ccc0a74c0fcae41 + zh: 516f19ece43a6c1e +/agent-note-force-directed-edge-recovery-for-floating-dock-panels/proposal/drag-with-resistance: + en: 2706e0ded33ca233 + zh: e4de8d0566101d61 +/agent-note-force-directed-edge-recovery-for-floating-dock-panels/proposal/release-and-spring: + en: 9fa63c723a756e0b + zh: 27f5b95a24619437 +/agent-note-force-directed-edge-recovery-for-floating-dock-panels/proposal/reduced-motion: + en: 9858426f655a4530 + zh: faac7f7c9cfe91e6 +/agent-note-force-directed-edge-recovery-for-floating-dock-panels/proposal/change-scope: + en: 930eea9ec6ba15c6 + zh: d4d2f40fd77a4c99 +/agent-note-force-directed-edge-recovery-for-floating-dock-panels/testing-plan: + en: 515b77c1a6073983 + zh: b4ff9be6d0204379 +/agent-note-force-directed-edge-recovery-for-floating-dock-panels/alternatives-considered: + en: c50b0c17a478178f + zh: 7bd46fedd967bd66 +/agent-note-force-directed-edge-recovery-for-floating-dock-panels/acceptance-criteria: + en: 51e57e5195c6b37d + zh: a5a5732c35415d81 +/agent-note-force-directed-edge-recovery-for-floating-dock-panels/risks: + en: b567ebe883f9d295 + zh: 7dc4d3cb72384b27 diff --git a/.agents/notes/proposed/feature/2026-10-21-floating-window-edge-recovery.md b/.agents/notes/proposed/feature/2026-10-21-floating-window-edge-recovery.md new file mode 100644 index 0000000000..f7f5dbb947 --- /dev/null +++ b/.agents/notes/proposed/feature/2026-10-21-floating-window-edge-recovery.md @@ -0,0 +1,120 @@ +# Agent Note: Force-directed edge recovery for floating dock panels + +Status: proposed + +English | [中文](2026-10-21-floating-window-edge-recovery.zh.md) + +## Problem + +The dock kit's floating panels are the client's floating windows. `FloatLayer` and the retained `DockLayout` renderer draw them in viewport coordinates through one shared gesture hook, `useFloatGestures`, and the right Sidebar embeds them, so the same panels run in the Web client and inside the Desktop window. Their drag follows the pointer one to one with only a top floor (`--dsh-dockkit-float-top`, which keeps the header below the Windows caption). A panel can therefore be dragged past the left, right or bottom edge until its header is out of reach; a viewport that shrinks leaves a panel outside it; and the creation cascade can place a new panel outside a small viewport. The required behavior is that a panel pushed past an edge visibly resists, and on release is pulled back inside with spring physics instead of being stopped by a wall or left outside. + +We reverse engineered Claude Desktop 2.42304.2 as a reference, and it has no such behavior. On macOS its Quick Entry surface is a native Swift `NSPanel`; its binary contains animation primitives, but no edge-recovery rule could be established from it. The Electron fallback used on Windows/Linux is static: after a 750 ms input debounce it makes one instantaneous `setPosition` that clamps only the right and bottom edges (trigger margin 0, target margin 30 DIP, so the first correction jumps by overflow + 30) and never clamps left or top. No `spring` symbol exists in its main bundle; its only window-motion utilities are a 240 ms `easeInOutCubic` bounds tween for main-window size changes, Electron's macOS-only `setBounds(bounds, true)`, and a 300 ms `cubic-bezier(0.16, 1, 0.3, 1)` CSS vocabulary. The behavior has to be designed, not ported. + +The change must keep these obligations: a panel header is always reachable; one gesture still records exactly one history entry; reduced motion is honored; the persisted Sidebar layout format and every embedder stay unchanged; and the motion is deterministic enough to test without a real browser clock. + +## Proposal + +The behavior lives entirely in `packages/client/ui-dockkit`, inside `useFloatGestures` and the pure engine helpers it calls. Because both float renderers already take their rectangles from that hook, Web and Desktop gain the behavior together, and no embedder, shell or persisted format changes. + +### Legal region and displayed position + +The legal region of a panel is the viewport (`window.innerWidth` by `window.innerHeight`) with the existing top floor: the Windows caption height plus 20 px when `data-windows-titlebar` is set (20 px in native fullscreen), otherwise 0. A rectangle is legal when `x` lies in `[0, viewportWidth - width]` and `y` in `[top, viewportHeight - height]`. When a panel is wider or taller than the region, the minimum edge is pinned, so the header and its grip stay on screen and the excess hangs off the right or bottom. + +The displayed rectangle is the per-axis projection of the stored rectangle onto the legal region, computed at render. The stored rectangle is not rewritten: a shrinking viewport pushes the panel in immediately without recording an operation, and when the viewport grows again the panel returns toward its stored position. Persisted layouts that hold off-screen rectangles from before this change display inside the viewport without migration. + +### Drag with resistance + +A move gesture computes the desired rectangle from the gesture's start rectangle and the pointer travel, as today, then splits it per axis into the legal projection and the overflow `o` beyond it. The preview rectangle draws at `legal + sign(o) * K * |o| / (K + |o|)` with `K = 120` px. The mapping is continuous, has slope 1 at the edge, and approaches `K`, so the panel moves past the edge at first and resists more the further the pointer goes: + +| pointer overflow (px) | panel displacement past the edge (px) | share of the overflow | +|---|---|---| +| 10 | 9.2 | 92.3% | +| 40 | 30.0 | 75.0% | +| 120 | 60.0 | 50.0% | +| 400 | 92.3 | 23.1% | + +A resize gesture clamps the bottom-right corner to the legal region and keeps `FLOAT_MIN_SIZE`; resizing has no resistance, because a corner that lags the pointer reads as a broken handle. + +### Release and spring + +On release the gesture records one `moveFloat` with the legal rectangle, so history and persistence always store a legal position. If the preview was outside the legal region, the hook keeps drawing a preview and animates it from the released position to the recorded one with a spring, then clears it. A release inside the legal region records the move and animates nothing. + +The spring is underdamped, because its bounce goes inward and is always legal: response 0.32 s and damping ratio 0.72 (`omega0 = 2 * pi / 0.32`). The initial velocity is the pointer velocity over the last 100 ms of the drag, capped at 1500 px/s, so a fling past the edge comes back faster than a slow push. Per axis the update is: + +``` +a = -omega0^2 * (x - target) - 2 * zeta * omega0 * v +v = v + a * h +x = x + v * h +``` + +The integrator uses a fixed substep `h = 1/480 s`. One `requestAnimationFrame` loop in the hook splits each frame's elapsed time into equal substeps of at most `h`, clamps a frame to 64 ms, and snaps to the target when a frame gap exceeds 250 ms. It stops and draws the exact target when each axis is within 1 px with speed below 60 px/s, or after 900 ms. Simulated from rest, a 200 px overflow settles in 367 ms with a 6.9 px (3.5%) inward overshoot, within the analytic bound `exp(-pi * zeta / sqrt(1 - zeta^2)) = 3.8%`; the resistance caps the released overflow at 120 px, so real releases settle faster. The integrator is pure and takes `dt`, so the engine keeps its rule of reading no clock. + +A press on a panel during its animation cancels the animation and starts the new gesture from the rectangle being drawn. At most one animation runs per panel, and unmounting the layer cancels its frame request. + +### Reduced motion + +When `matchMedia('(prefers-reduced-motion: reduce)')` matches, a move gesture clamps to the legal region with no resistance, and release records the legal rectangle with no animation. The rule only removes motion; it never removes the legality correction. + +### Change scope + +The implementation changes one package, `@deepseek-ai/dsh-client-ui-dockkit`, and leaves its exports and `DockIntents` unchanged. + +| File | Change | +|---|---| +| `packages/client/ui-dockkit/src/engine/geometry.ts` | add the legal projection and the resistance mapping | +| `packages/client/ui-dockkit/src/engine/` | new `spring.ts`: the pure spring integrator and its settle test | +| `packages/client/ui-dockkit/src/components/FloatLayer.tsx` | `useFloatGestures`: displayed projection, resistance, release spring, velocity sampling, reduced motion, frame loop and cancellation | +| `packages/client/ui-dockkit/src/components/TabLayout.tsx` | draw the hook's displayed rectangle instead of the stored one | +| `packages/client/ui-dockkit/tests/` | geometry, spring, `FloatLayer` and `TabLayout` specs | +| `packages/client/ui-dockkit/README.md` pair | the edge rule under the interaction rules | + +`ui-sidebar-right` and its persisted layout schema, `apps/web`, `apps/desktop`, the shared primitives and the theme are untouched. No dependency is added. + +## Testing plan + +Pure tests cover the projection (inside, each edge, corner, oversized panel, the Windows top floor), the resistance mapping (continuous, monotone, slope 1 at the edge, bounded by `K`), and the spring with fixed time steps (deterministic trajectories, exact final target, inward overshoot within one percentage point of the analytic bound, settling inside the 900 ms deadline, cadence robustness at 30, 60 and 120 Hz, and the 250 ms stall snap). + +Component tests run `FloatLayer` and `TabLayout` under jsdom with a fake `requestAnimationFrame` and clock: a drag past each edge draws the resisted preview; release records exactly one `moveFloat` with the legal rectangle; the preview animates to it and clears; a press mid-animation cancels it and starts from the drawn rectangle; reduced motion clamps and never schedules a frame; a viewport resize moves the displayed panel without calling any intent; unmounting cancels the frame. The per-file coverage gate applies to every changed source file. + +A browser check in the Web client drags a Sidebar floating panel past each edge and corner, flings it, resizes the window under it, and repeats with reduced motion; the PR records it as a GIF. Desktop loads the same client bundle, so one manual pass there confirms the Windows caption floor. + +No keyless recorded-session snapshot is required: nothing model-visible changes and no `SessionEventMap` member is added. Documentation gates: `doc-sync`. + +## Alternatives considered + +**Hard clamp at the edge.** Stopping the panel at the viewport edge is the cheapest correct rule, but it feels like hitting a wall and gives no sense of the boundary before contact. It remains as the reduced-motion path. + +**Clamp during the drag and rebound on release.** Clamping the drag at the edge and converting the outward pointer speed into an inward bounce keeps every frame inside the viewport. It hides how far the user pushed, so the bounce has no visible cause; the resistance mapping shows the push and still bounds the overflow at 120 px. + +**Eased tween on release.** A fixed 240-300 ms ease-out from the released position is predictable, but it carries no velocity, so a fling and a slow push return identically, and a press during it either jumps or restarts. The spring keeps velocity continuous and is interruptible. + +**Store the off-screen position and correct it later.** Recording the released rectangle and fixing it on the next render would persist off-screen positions and make undo restore them. Recording the legal rectangle keeps one history entry per gesture with a legal value. + +**Rewrite stored rectangles when the viewport shrinks.** Moving panels through operations on resize would add history entries the user never made and change persisted layouts on every window resize. Projecting at render achieves the same visible result without either. + +**Native always-on-top OS window.** A real Electron floating window could float above other applications, but only on Desktop; the Web client cannot do it at all, and native frameless dragging gives no per-frame control, so the resistance would be impossible and the spring could only start after release. It is a separate product decision with its own window, IPC and platform work, and this note does not preclude it. + +**Animation library dependency.** A spring library would replace a pure integrator of a few dozen lines and its tests with a new dependency in a statically linked package. The integrator also has to be clock-free for the engine's deterministic tests. + +**A shared primitive in `ui-primitives`.** Placing the hook in the primitives package would widen the change to a second package with no second consumer today. It can move there when another floating surface needs it. + +## Acceptance criteria + +- Dragging a floating panel past any viewport edge draws it at the resisted displacement, never more than 120 px beyond the edge; reduced motion clamps it at the edge instead. +- Releasing it outside the legal region records exactly one `moveFloat` whose rectangle is legal, and the panel springs to that rectangle within 900 ms, ending at the exact recorded position. +- Undo after such a gesture restores the pre-gesture position in one step, and the persisted layout never contains a rectangle that was illegal when it was recorded. +- Releasing inside the legal region behaves as today: one operation and no animation. +- Pressing a panel during its animation stops the animation and the new gesture starts from the rectangle on screen. +- Shrinking the viewport keeps every panel header on screen without recording an operation; growing it returns the panel toward its stored position. +- Under the Windows caption the header stays at least 20 px below the caption, as today. +- No package other than `@deepseek-ai/dsh-client-ui-dockkit` changes, and its exports and `DockIntents` are unchanged. + +## Risks + +**One render per animation frame.** The spring updates the preview through React state, which costs the same per frame as a drag does today, but a panel hosting heavy content re-renders for up to 900 ms after release. If measurement shows dropped frames, the loop can write a transform on the panel element directly without changing the rule. + +**Elastic return after the viewport grows.** A panel pushed in by a shrinking window returns toward its stored position when the window grows. That is the intended consequence of not rewriting stored rectangles, but a user who expects the panel to stay where it was pushed may find it surprising. + +**Embedded content under motion.** Panels can host a webview or an iframe that receives pointer events. The spring runs only after release and a press cancels it, but content that reacts to its own movement could observe up to 900 ms of motion. + +**Touch remains untuned.** The resistance and the velocity sample come from pointer events and work for touch input, but the constants are tuned for a mouse or trackpad; the README already lists touch as untuned. diff --git a/.agents/notes/proposed/feature/2026-10-21-floating-window-edge-recovery.zh.md b/.agents/notes/proposed/feature/2026-10-21-floating-window-edge-recovery.zh.md new file mode 100644 index 0000000000..4b73e4098a --- /dev/null +++ b/.agents/notes/proposed/feature/2026-10-21-floating-window-edge-recovery.zh.md @@ -0,0 +1,120 @@ +# Agent Note: 悬浮停靠面板的力导向边界收回 + +Status: proposed + +[English](2026-10-21-floating-window-edge-recovery.md) | 中文 + +## 问题 + +dock kit 的悬浮面板就是客户端里的悬浮窗。`FloatLayer` 与保留式 `DockLayout` 渲染器通过同一个手势 hook `useFloatGestures` 以视口坐标绘制它们,右侧 Sidebar 嵌入了它们,因此同一套面板既运行在 Web 客户端中,也运行在 Desktop 窗口内。它们的拖拽一比一跟随指针,只有一个顶部下限(`--dsh-dockkit-float-top`,让标题栏保持在 Windows 标题栏之下)。因此面板可以被拖过左、右或下边界,直到标题栏够不着;视口缩小会把面板留在外面;新建面板的级联位置也可能落在小视口之外。期望行为是:面板被推过边界时可见地受到阻力,松手后以弹簧物理被拉回视口内,而不是像撞墙一样被挡住或被留在外面。 + +我们逆向分析了参考实现 Claude Desktop 2.42304.2,它没有这种行为。在 macOS 上它的 Quick Entry 是原生 Swift `NSPanel`;其二进制包含动画原语,但无法从中确认任何边界收回规则。Windows/Linux 上使用的 Electron 回退是静态的:输入防抖 750 ms 后做一次瞬时 `setPosition`,只裁剪右边界和下边界(触发边距为 0、目标边距为 30 DIP,因此首次修正在溢出量之外再跳 30),从不裁剪左边界和上边界。其主 bundle 中不存在 `spring` 符号;仅有的窗口运动工具是用于主窗口尺寸变化的 240 ms `easeInOutCubic` 边界补间、Electron 仅 macOS 可用的 `setBounds(bounds, true)`,以及 300 ms `cubic-bezier(0.16, 1, 0.3, 1)` 的 CSS 运动语汇。该行为必须被设计,而不是移植。 + +变更必须维持以下义务:面板标题栏始终可达;一个手势仍然只记录一条历史;遵循减弱动态效果;Sidebar 的持久化布局格式与所有嵌入方保持不变;运动足够确定,无需真实浏览器时钟即可测试。 + +## 提案 + +该行为完全位于 `packages/client/ui-dockkit` 内,在 `useFloatGestures` 及其调用的纯 engine 辅助函数中实现。由于两个悬浮渲染器都已从该 hook 取得矩形,Web 与 Desktop 同时获得该行为,不改动任何嵌入方、壳或持久化格式。 + +### 合法区域与显示位置 + +面板的合法区域是视口(`window.innerWidth` × `window.innerHeight`)加上既有的顶部下限:设置了 `data-windows-titlebar` 时为 Windows 标题栏高度加 20 px(原生全屏时为 20 px),否则为 0。当 `x` 位于 `[0, viewportWidth - width]` 且 `y` 位于 `[top, viewportHeight - height]` 时矩形合法。面板比区域更宽或更高时钉住最小边,使标题栏及其抓手留在屏幕上,多余部分悬在右侧或下方。 + +显示矩形是存储矩形在合法区域上的逐轴投影,在渲染时计算。存储矩形不会被改写:视口缩小时面板立即被推入,且不记录操作;视口再次变大时面板回到存储位置。本变更之前持久化下来、包含屏幕外矩形的布局无需迁移即在视口内显示。 + +### 带阻力的拖拽 + +移动手势照旧由手势起始矩形和指针位移计算期望矩形,然后逐轴拆分为合法投影与超出它的溢出量 `o`。预览矩形绘制在 `legal + sign(o) * K * |o| / (K + |o|)`,其中 `K = 120` px。该映射连续、在边界处斜率为 1、渐近于 `K`,因此面板起初会越过边界,指针走得越远阻力越大: + +| 指针溢出(px) | 面板越过边界的位移(px) | 占溢出的比例 | +|---|---|---| +| 10 | 9.2 | 92.3% | +| 40 | 30.0 | 75.0% | +| 120 | 60.0 | 50.0% | +| 400 | 92.3 | 23.1% | + +缩放手势把右下角钳制在合法区域内并保持 `FLOAT_MIN_SIZE`;缩放不加阻力,因为落后于指针的角看起来像坏掉的手柄。 + +### 松手与弹簧 + +松手时手势以合法矩形记录一次 `moveFloat`,因此历史与持久化始终存储合法位置。如果预览在合法区域之外,hook 继续绘制预览,用弹簧把它从松手位置动画到记录的位置,然后清除预览。在合法区域内松手则记录移动且不播放动画。 + +弹簧是欠阻尼的,因为它的回弹朝向内侧,始终合法:响应时间 0.32 s、阻尼比 0.72(`omega0 = 2 * pi / 0.32`)。初速度取拖拽最后 100 ms 的指针速度,上限 1500 px/s,因此甩过边界的面板比慢慢推过去的回来得更快。每轴更新为: + +``` +a = -omega0^2 * (x - target) - 2 * zeta * omega0 * v +v = v + a * h +x = x + v * h +``` + +积分器使用固定子步 `h = 1/480 s`。hook 中唯一的 `requestAnimationFrame` 循环把每帧经过的时间拆成等长且不超过 `h` 的子步,单帧钳制到 64 ms,帧间隔超过 250 ms 时直接跳到目标。当每轴距离在 1 px 内且速度低于 60 px/s,或经过 900 ms 后,它停止并绘制精确目标。从静止开始仿真,200 px 溢出在 367 ms 内稳定,向内过冲 6.9 px(3.5%),在解析上限 `exp(-pi * zeta / sqrt(1 - zeta^2)) = 3.8%` 之内;阻力把松手时的溢出限制在 120 px 内,因此真实松手稳定得更快。积分器是纯函数并接收 `dt`,因此 engine 保持不读取时钟的规则。 + +动画期间按下面板会取消动画,并从正在绘制的矩形开始新手势。每个面板最多运行一个动画,卸载该层会取消其帧请求。 + +### 减弱动态效果 + +`matchMedia('(prefers-reduced-motion: reduce)')` 匹配时,移动手势钳制在合法区域内且无阻力,松手时记录合法矩形且不播放动画。该规则只移除运动,从不移除合法性修正。 + +### 改动范围 + +实现只修改一个包 `@deepseek-ai/dsh-client-ui-dockkit`,其导出与 `DockIntents` 保持不变。 + +| 文件 | 变更 | +|---|---| +| `packages/client/ui-dockkit/src/engine/geometry.ts` | 新增合法投影与阻力映射 | +| `packages/client/ui-dockkit/src/engine/` | 新增 `spring.ts`:纯弹簧积分器及其稳定判定 | +| `packages/client/ui-dockkit/src/components/FloatLayer.tsx` | `useFloatGestures`:显示投影、阻力、松手弹簧、速度采样、减弱动态效果、帧循环与取消 | +| `packages/client/ui-dockkit/src/components/TabLayout.tsx` | 绘制 hook 给出的显示矩形而不是存储矩形 | +| `packages/client/ui-dockkit/tests/` | 几何、弹簧、`FloatLayer` 与 `TabLayout` 测试 | +| `packages/client/ui-dockkit/README.md` 对 | 在交互规则下补充边界规则 | + +`ui-sidebar-right` 及其持久化布局 schema、`apps/web`、`apps/desktop`、共享基础组件与主题均不改动。不新增依赖。 + +## 测试计划 + +纯测试覆盖投影(内部、每条边、角、超尺寸面板、Windows 顶部下限)、阻力映射(连续、单调、边界处斜率为 1、以 `K` 为上界),以及固定时间步下的弹簧(轨迹确定、最终目标精确、向内过冲与解析上限相差不超过一个百分点、在 900 ms 截止时间内稳定、30/60/120 Hz 节奏鲁棒,以及 250 ms 停顿直接跳转)。 + +组件测试在 jsdom 中用假的 `requestAnimationFrame` 与时钟运行 `FloatLayer` 和 `TabLayout`:拖过每条边绘制带阻力的预览;松手恰好记录一次带合法矩形的 `moveFloat`;预览动画到该矩形后清除;动画中按下会取消动画并从绘制中的矩形开始;减弱动态效果下钳制且从不调度帧;视口缩放移动显示面板而不调用任何 intent;卸载取消帧请求。逐文件覆盖率门禁适用于每个改动的源文件。 + +在 Web 客户端中进行浏览器检查:把 Sidebar 悬浮面板拖过每条边与每个角、甩出去、在其下方缩放窗口,并在减弱动态效果下重复;PR 以 GIF 记录。Desktop 加载同一份客户端 bundle,因此在那里手动走一遍即可确认 Windows 标题栏下限。 + +不需要 keyless 录制会话快照:没有模型可见的变化,也没有新增 `SessionEventMap` 成员。文档门禁:`doc-sync`。 + +## 考虑过的替代方案 + +**在边界处硬钳制。** 在视口边界停住面板是成本最低的正确规则,但手感像撞墙,接触之前也感觉不到边界。它保留为减弱动态效果的路径。 + +**拖拽中钳制、松手时回弹。** 在边界处钳制拖拽,并把向外的指针速度转换为向内的回弹,能让每一帧都留在视口内。但它隐藏了用户推了多远,回弹因此没有可见的起因;阻力映射显示了推动,同时把溢出限制在 120 px 内。 + +**松手后的缓动补间。** 从松手位置开始的固定 240–300 ms 缓出补间可预测,但不携带速度,因此甩出与慢推的返回完全相同,补间中按下要么跳变要么重启。弹簧保持速度连续且可打断。 + +**存储屏幕外位置并在之后修正。** 记录松手矩形、在下一次渲染时修正,会持久化屏幕外位置,并让撤销恢复它们。记录合法矩形则保持每个手势一条历史且值合法。 + +**视口缩小时改写存储矩形。** 在缩放时通过操作移动面板会增加用户从未做过的历史条目,并在每次窗口缩放时改变持久化布局。渲染时投影无需二者即可得到相同的可见结果。 + +**原生始终置顶 OS 窗口。** 真正的 Electron 悬浮窗可以浮在其他应用之上,但只在 Desktop 上可行;Web 客户端完全无法做到,而且原生无边框拖拽不提供逐帧控制,因此阻力无法实现,弹簧只能在松手后启动。它是一个独立的产品决策,有自己的窗口、IPC 与平台工作,本 Note 不排斥它。 + +**动画库依赖。** 弹簧库会用一个静态链接包里的新依赖替换几十行的纯积分器及其测试。积分器还必须不依赖时钟,才能用于 engine 的确定性测试。 + +**放进 `ui-primitives` 的共享基础组件。** 把 hook 放进基础组件包会把改动扩大到第二个包,而目前没有第二个使用方。等另一个悬浮界面需要它时再迁移。 + +## 验收标准 + +- 把悬浮面板拖过任一视口边界时,它绘制在带阻力的位移处,越过边界不超过 120 px;减弱动态效果下改为钳制在边界处。 +- 在合法区域外松手恰好记录一次矩形合法的 `moveFloat`,面板在 900 ms 内弹到该矩形,最终停在精确的记录位置。 +- 这样的手势之后撤销一步即可恢复手势前的位置,持久化布局中从不包含记录时就不合法的矩形。 +- 在合法区域内松手的行为与现在相同:一次操作,无动画。 +- 动画期间按下面板会停止动画,新手势从屏幕上的矩形开始。 +- 视口缩小时每个面板标题栏都留在屏幕上且不记录操作;视口变大时面板回到存储位置。 +- 在 Windows 标题栏下,标题栏与现在一样至少保持在其下方 20 px。 +- 除 `@deepseek-ai/dsh-client-ui-dockkit` 外没有其他包改动,其导出与 `DockIntents` 不变。 + +## 风险 + +**每个动画帧一次渲染。** 弹簧通过 React state 更新预览,每帧成本与现在拖拽时相同,但承载重内容的面板在松手后最多会重渲染 900 ms。如果测量显示掉帧,循环可以直接在面板元素上写 transform,而不改变规则。 + +**视口变大后的弹性返回。** 被缩小窗口推入的面板会在窗口变大时回到存储位置。这是不改写存储矩形的预期结果,但期望面板留在被推到的位置的用户可能会感到意外。 + +**运动中的嵌入内容。** 面板可以承载接收指针事件的 webview 或 iframe。弹簧只在松手后运行,按下即取消,但会对自身移动作出反应的内容可能观察到最多 900 ms 的运动。 + +**触控仍未调优。** 阻力与速度采样来自 pointer 事件,适用于触控输入,但常量是针对鼠标或触控板调优的;README 已将触控列为未调优。