dsh-smooth-scroll 0.1.1-rc.2 → 0.1.2-alpha.3

package/README.md

@@ -1,75 +1,71 @@
-# dsh-smooth-scroll
-
-## 简介
-
-让 DSH 的会话滚底从"官方瞬时跳变"变成**流畅顺滑的跟随滚动**：会话装载与"回到最新"
-保持瞬时（这是"跳"的正确语义），而流式内容增长期间，消息列以**恒定速度平滑跟随**，
-起步轻柔、收尾绵软。
-
-实现上**不触碰任何 transform**——直接对原生 `scrollTop` 做有节奏的动画，并用一个
-**合成 getter** 在动画期间向 DSH 报告"目标值"，因此它的跟随状态机（是否在底部、
-是否用户滚动）完全不受影响：不会误判脱钩、不会重复钉底、输入栏等 UI 丝毫不被扰动。
-系统开启"减少动效"（`prefers-reduced-motion`）时自动回退官方瞬时行为。
-
-## 行为（最终架构：无 transform）
-
-直接在**原生 scrollTop** 上做有节奏的平滑滚动，配合**合成 getter**：平滑期间
-`scrollTop` 读到"目标值"，DSH 自身的状态机（movedByReader/atBottom）永远看不到中间
-位置——不会误判脱钩、不会重复钉底。
-
-- **速度剖面（velocity chase + 缓启动 + 软尾）**
-  - 起步：0 → 0.9px/ms，240ms smoothstep 爬升；
-  - 巡航：恒速 0.9px/ms（内容增长只更新目标点，曲线永不逐段重启）；
-  - 收尾：停止增长 >240ms 且剩余 ≤120px 时，220ms ease-out 软着陆；
-- **同目标兜底写入**（DSH 每滚动事件重跑 `toBottom`，目标不变）→ 忽略，动画不被逐帧重启；
-- **用户滚动接管**：真实位置偏离动画自身写入（唯一只能来自用户）→ 立即停动画、
-  getter 恢复真实、DSH 正常脱钩（"回到最新"按钮照常）；
-- `prefers-reduced-motion: reduce`：完全回退官方瞬时行为；
-- **不应用任何 transform**：输入栏 overlay/sticky 永不受扰（无瞬移、无毛边、无飞出）。
-
-## 历史教训（为什么不是 transform/rAF 手写）
-
-1. transform 补偿方案与 DSH 的输入栏 overlay 测量偶发交错 → 输入栏瞬移/毛边（已弃）；
-2. JS rAF 手写动画会冻结/重启问题（已弃）——最终版由 getter 掩盖中间态 + 恒速模型。
-
-## 构建
-
-```sh
-pnpm install        # 安装 esbuild devDependency
-pnpm run build      # 产出 lib/index.js + lib/client.js
-```
-
-`lib/` 已随仓库提交，克隆后可直接安装使用；改源码才需要重新构建。
-
-## 安装（永久生效）
-
-```sh
-bash install-real-profile.sh    # Windows 用 Git Bash / WSL；Linux/macOS 直接 bash
-```
-
-脚本执行：`pnpm add link:<本目录>`（~/.dsh/profiles/web/package.json）+ 向
-`cordis.patch.yml` 追加 `- insert: [{ id: smooth-scroll, name: 'dsh-smooth-scroll' }]`。
-然后**重启 dsh web**。注意：源目录为 link 安装，改 `src/client.js` 后重建即可热更到下次启动。
-
-## 卸载
-
-删除 `cordis.patch.yml` 对应 insert 块 + `pnpm remove dsh-smooth-scroll`，重启。
-
-## 调参
-
-所有参数都在 `src/client.js` 顶部常量区：
-
-| 常量 | 默认 | 含义 |
-|---|---|---|
-| `VEL` | 0.9 | 巡航速度（px/ms） |
-| `RAMP_MS` | 240 | 起步缓加速时长（smoothstep） |
-| `QUIET_MS` | 240 | 判定"停止增长"的静默窗口 |
-| `TAIL_PX` | 120 | 进入软尾的剩余距离阈值 |
-| `TAIL_MS` | 220 | 软尾缓动时长 |
-
-改完：`pnpm run build` → 重启 dsh web。
-
-## 源码
-
-- `src/client.js` — 浏览器半部（核心逻辑）
-- `src/index.ts` — 宿主半部（空 apply，仅为组合可见）
+<div align="center">
+
+# dsh-smooth-scroll
+
+**让 DSH 会话滚底从瞬时跳变变成恒速平滑跟随**
+
+装上后，流式内容增长时消息列平滑跟随到底部，回到最新仍保持瞬时。
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/dsh-smooth-scroll">
+    <img src="https://img.shields.io/npm/v/dsh-smooth-scroll/alpha?style=flat&colorA=000000&colorB=000000" />
+  </a>
+  <a href="https://github.com/VinciBeans/dsh-smooth-plugin/blob/main/LICENSE">
+    <img src="https://img.shields.io/github/license/VinciBeans/dsh-smooth-plugin?style=flat&colorA=000000&colorB=000000" />
+  </a>
+</p>
+
+</div>
+
+## Install
+
+从 npm 安装（`alpha` dist-tag 指向 0.1.2-alpha.3，适配 dsh v0.1.2-alpha.1 ~ alpha.3）：
+
+```sh
+dsh plugin --profile web add dsh-smooth-scroll@alpha
+```
+
+需要已安装 DSH，并至少成功启动过一次 Web GUI。
+
+npm `latest`（0.1.1-rc.2）仍是旧 client-runtime 代，仅适配 dsh 0.1.1-rc.2；安装它的命令为 `dsh plugin --profile web add dsh-smooth-scroll`。源码安装：`dsh plugin --profile web add .`。
+
+## Quickstart
+
+```sh
+dsh plugin --profile web add dsh-smooth-scroll@alpha
+dsh --profile web --dump-config          # 看到 dsh-smooth-scroll 层即安装成功
+# 重启 dsh web，打开会话，流式内容平滑滚到底部
+```
+
+## 滚动行为
+
+直接在原生 `scrollTop` 上做有节奏的平滑滚动，配合合成 getter：平滑期间 `scrollTop` 读到目标值，DSH 自身状态机看不到中间位置，不误判脱钩、不重复钉底。
+
+- **速度剖面:** 起步 0 到 0.9px/ms 用 240ms 缓升，巡航恒速 0.9px/ms，收尾 220ms 软着陆。
+- **用户滚动接管:** 真实位置连续偏离动画写入 ≥2 帧才停动画，DSH 正常脱钩，回到最新按钮照常；单帧偏差（浏览器滚动锚定等一次性非用户位移）自动重基后继续钉底跟随——发送消息等操作引发的非用户位移不会导致误判脱钩或停在信息处；内容收窄导致的夹紧则在 2 帧内停止于新底部（同样不掉队）。与之对称，孤立的一次性小幅定位（如滚动条点一格）也会被当作非用户位移吸收、随后被跟随回底部；只有持续 ≥2 帧的偏离才视为用户接管。另：主机内（输入栏除外）的**指针按下立即停动画**并让 getter 回落真实值——alpha.3 的 turn 导轨跳转（`landOnRow` 复合读改写）由此读到真实位置，落点不被合成目标偏移。
+- **同目标兜底:** DSH 每滚动事件重跑 toBottom 而目标不变时忽略，动画不被逐帧重启。
+- **减少动效:** prefers-reduced-motion 时完全回退官方瞬时行为。
+- **无 transform:** 不应用任何 transform，输入栏 overlay/sticky 永不受扰。
+
+## 参数
+
+| 常量 | 默认 | 含义 |
+| --- | --- | --- |
+| VEL | 0.9 | 巡航速度（px/ms） |
+| RAMP_MS | 240 | 起步缓加速时长 |
+| QUIET_MS | 240 | 判定停止增长的静默窗口 |
+| TAIL_PX | 120 | 进入软尾的剩余距离阈值 |
+| TAIL_MS | 220 | 软尾缓动时长 |
+| DIVERGE_STOP_FRAMES | 2 | 真实位置连续偏离动画写入的帧数阈值（≥2 帧判定读者接管） |
+
+改参数：编辑 `src/client.js` 顶部常量区，`pnpm run build` 后重启 dsh web。
+
+## 兼容性
+
+- **dsh v0.1.2-alpha.1 ~ alpha.3（支持）:** 插件的唯一 DOM 锚点 `[data-conversation-scroll]`（会话滚动容器）与宿主跟随状态机（`observedTopRef` / `movedByReader` / ResizeObserver follow、`el.scrollTop` 读写面）在 `dsh-v0.1.2-alpha.1`、`dsh-v0.1.2-alpha.2`、`dsh-v0.1.2-alpha.3` 三个 tag 上一致——alpha.3 只在滚动容器外多包了一层 `.body`，属性与滚动语义未变。alpha.3 新增的 turn 导轨跳转（`landOnRow` 的 `el.scrollTop += flowTop - 24` 复合读改写）遇到插件追击时会被 pointerdown 接管先停动画，复合写读到真实位置，落点不被合成 getter 偏移；该接管在三个版本上同样生效。
+- **0.1.1-rc.2 及更早（不支持）:** 该代使用 `@deepseek-ai/dsh-client-runtime`，滚动宿主结构不同，不兼容。
+- 验证：`pnpm test`（契约冒烟，bundle 自包含）+ `node test/scroll-follow.test.mjs`（15 个 e2e 场景，含「追击中点击导轨」回归点；需 Playwright 与 Chromium）。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -1,6 +1,6 @@
 # dsh 组合包层（bundle layer）：把 dsh-smooth-scroll 插入 web 配置树。
 #
-# `name` 必须是包名（而非源码相对路径）；dsh 的 client-modules 节点半部扫描到这一行，
+# `name` 必须是包名（而非源码相对路径）；client-modules 节点半部扫描到这一行，
 # 读到 dsh.client 声明后把浏览器 bundle 挂到 /plugins/dsh-smooth-scroll/client.js。
 - insert:
     - id: 'smooth-scroll'

package/lib/client.js

@@ -28,6 +28,7 @@ var RAMP_MS = 240;
 var QUIET_MS = 240;
 var TAIL_PX = 120;
 var TAIL_MS = 220;
+var DIVERGE_STOP_FRAMES = 2;
 var easeOut = (t) => 1 - Math.pow(1 - t, 3);
 var smooth = (t) => t * t * (3 - 2 * t);
 var now = () => typeof performance === "object" && performance !== null && typeof performance.now === "function" ? performance.now() : Date.now();
@@ -38,15 +39,13 @@ function apply(ctx) {
     if (typeof MutationObserver !== "function" || typeof requestAnimationFrame !== "function") return;
     const reduced = typeof matchMedia === "function" && matchMedia("(prefers-reduced-motion: reduce)").matches;
     const states = /* @__PURE__ */ new Map();
-    let announced = false;
     const readTop = (state) => state.chase || state.settle !== null ? state.target : state.desc.get.call(state.el);
     const stopAll = (state) => {
       state.chase = false;
       state.settle = null;
-      state.rafId = 0;
+      state.farN = 0;
     };
     const tick = (state, ts) => {
-      state.rafId = 0;
       if (!state.el.isConnected) {
         stopAll(state);
         return;
@@ -54,6 +53,27 @@ function apply(ctx) {
       if (state.lastTs === 0) state.lastTs = ts;
       const dt = Math.min(50, ts - state.lastTs);
       state.lastTs = ts;
+      const pos = state.desc.get.call(state.el);
+      if (state.settle === null && !state.chase) {
+        state.farN = 0;
+        return;
+      }
+      if (Math.abs(pos - state.lastWrite) > 0.5) {
+        state.farN += 1;
+        if (state.farN >= DIVERGE_STOP_FRAMES) {
+          state.farN = 0;
+          stopAll(state);
+          return;
+        }
+        state.lastWrite = pos;
+        if (state.settle !== null) {
+          state.settle = null;
+          state.chase = true;
+          state.chaseStart = ts;
+        }
+      } else {
+        state.farN = 0;
+      }
       if (state.settle !== null) {
         const s = state.settle;
         const t = Math.min(1, (ts - s.start) / s.ms);
@@ -65,15 +85,14 @@ function apply(ctx) {
           state.lastTs = 0;
           return;
         }
-        state.rafId = requestAnimationFrame((t2) => tick(state, t2));
+        requestAnimationFrame((t2) => tick(state, t2));
         return;
       }
-      if (!state.chase || state.target === null) {
+      if (!state.chase) {
         state.chase = false;
         state.lastTs = 0;
         return;
       }
-      const pos = state.desc.get.call(state.el);
       const remaining = Math.max(0, state.target) - pos;
       if (Math.abs(remaining) <= 0.5) {
         state.desc.set.call(state.el, Math.max(0, state.target));
@@ -84,7 +103,7 @@ function apply(ctx) {
       if (Math.abs(remaining) <= TAIL_PX && now() - state.lastPinTs > QUIET_MS) {
         state.settle = { from: pos, to: state.target, start: ts, ms: TAIL_MS };
         state.chase = false;
-        state.rafId = requestAnimationFrame((t2) => tick(state, t2));
+        requestAnimationFrame((t2) => tick(state, t2));
         return;
       }
       const ramp = Math.min(1, Math.max(0, (ts - state.chaseStart) / RAMP_MS));
@@ -93,19 +112,23 @@ function apply(ctx) {
       const nv = pos + step;
       state.lastWrite = nv;
       state.desc.set.call(state.el, nv);
-      state.rafId = requestAnimationFrame((t2) => tick(state, t2));
+      requestAnimationFrame((t2) => tick(state, t2));
     };
     const writeScrollTop = (state, desc, value) => {
       const el = state.el;
-      const current = desc.get.call(el);
       const max = Math.max(0, el.scrollHeight - el.clientHeight);
+      const current = desc.get.call(el);
       const target = Math.min(value, max);
-      state.pinnedTop = target;
-      const isPin = value >= max - 1 && Math.abs(target - current) > 0.5;
+      const pinIntent = value >= max - 1;
+      const isPin = pinIntent && Math.abs(target - current) > 0.5;
       if (!isPin) {
         if (Math.abs(target - current) > 0.5) {
           stopAll(state);
           desc.set.call(el, value);
+        } else if (pinIntent && (state.chase || state.settle !== null)) {
+          state.target = target;
+          stopAll(state);
+          state.lastWrite = current;
         }
         return;
       }
@@ -130,7 +153,9 @@ function apply(ctx) {
         state.chase = true;
         state.chaseStart = now();
         state.lastTs = 0;
-        state.rafId = requestAnimationFrame((t2) => tick(state, t2));
+        state.lastWrite = current;
+        state.farN = 0;
+        requestAnimationFrame((t2) => tick(state, t2));
       }
     };
     const attach = (el) => {
@@ -149,18 +174,25 @@ function apply(ctx) {
       const state = {
         el,
         desc,
-        flow: null,
-        pinnedTop: -1,
         firstPin: true,
         chase: false,
         settle: null,
         target: null,
         lastPinTs: 0,
         lastTs: 0,
-        rafId: 0,
         lastWrite: 0,
-        chaseStart: 0
+        chaseStart: 0,
+        farN: 0
+      };
+      const stopOnPointerDown = (event) => {
+        if (!state.chase && state.settle === null) return;
+        const target = event.target;
+        if (!(target instanceof Element)) return;
+        if (target.closest("[data-composer-seat]") !== null) return;
+        stopAll(state);
       };
+      state.stopOnPointerDown = stopOnPointerDown;
+      el.addEventListener("pointerdown", stopOnPointerDown, true);
       states.set(el, state);
       Object.defineProperty(el, "scrollTop", {
         configurable: true,
@@ -172,20 +204,14 @@ function apply(ctx) {
           writeScrollTop(state, desc, value);
         }
       });
-      if (!announced) {
-        announced = true;
-        console.log("[dsh-smooth-scroll] attached to the conversation scroller");
-      }
     };
     const disposeState = (state) => {
       stopAll(state);
-      if (Object.prototype.hasOwnProperty.call(state.el, "scrollTop")) {
-        try {
-          delete state.el.scrollTop;
-        } catch (e) {
-        }
+      state.el.removeEventListener("pointerdown", state.stopOnPointerDown, true);
+      const scrollDesc = Object.getOwnPropertyDescriptor(state.el, "scrollTop");
+      if (scrollDesc !== void 0 && scrollDesc.configurable) {
+        delete state.el.scrollTop;
       }
-      state.flow = null;
       states.delete(state.el);
     };
     const scan = () => {
@@ -201,23 +227,11 @@ function apply(ctx) {
         scan();
       });
     };
-    const onDocScroll = (event) => {
-      const target = event.target;
-      if (target === null || target === void 0) return;
-      const state = states.get(target);
-      if (state === void 0) return;
-      const real = state.desc.get.call(state.el);
-      if ((state.chase || state.settle !== null) && Math.abs(real - state.lastWrite) > 0.5) {
-        stopAll(state);
-      }
-    };
-    doc.addEventListener("scroll", onDocScroll, { capture: true, passive: true });
     const observer = new MutationObserver(queueScan);
     observer.observe(root, { childList: true, subtree: true });
     queueScan();
     return () => {
       observer.disconnect();
-      doc.removeEventListener("scroll", onDocScroll, true);
       for (const state of [...states.values()]) disposeState(state);
     };
   });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-smooth-scroll",
-  "version": "0.1.1-rc.2",
-  "description": "DSH 平滑滚底插件：会话装载与“回到最新”瞬时钉底，流式内容以恒速平滑跟随（缓启动/软尾）；无 transform、不扰动输入栏等 UI、不干扰 DSH 自身跟随状态机，prefers-reduced-motion 自动回退官方行为。适配 dsh-0.1.1-rc.2。",
+  "version": "0.1.2-alpha.3",
+  "description": "DSH 平滑滚底插件：会话装载与“回到最新”瞬时钉底，流式内容以恒速平滑跟随（缓启动/软尾）；无 transform、不扰动输入栏等 UI、不干扰 DSH 自身跟随状态机，prefers-reduced-motion 自动回退官方行为。适配 dsh-v0.1.2-alpha.1 ~ alpha.3。",
   "type": "module",
   "main": "lib/index.js",
   "exports": {
@@ -17,9 +17,6 @@
     "lib",
     "cordis.patch.yml"
   ],
-  "publishConfig": {
-    "access": "public"
-  },
   "dsh": {
     "client": {
       "platform": "web"
@@ -28,10 +25,6 @@
       "patch": "./cordis.patch.yml"
     }
   },
-  "scripts": {
-    "build": "node scripts/build.mjs",
-    "prepublishOnly": "node scripts/build.mjs"
-  },
   "devDependencies": {
     "esbuild": "^0.25.0"
   },
@@ -42,5 +35,10 @@
     "smooth-scroll",
     "scroll"
   ],
-  "license": "MIT"
-}
+  "license": "MIT",
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "node test/smoke.test.mjs",
+    "test:e2e": "node test/scroll-follow.test.mjs"
+  }
+}