diff --git a/CHANGELOG.md b/CHANGELOG.md index 413c0880..8107f15d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,11 @@ # 印度占星 Skill 更新日志 +## 2026-09-26 — 刷新后回到对话「跳到最新」不再乱出现，生时校正长回答停在开头（待验收） + +- 刷新页面、用链接直接打开或一打开就落到一个已有的普通对话时：先落到最新一条；再问一个短问题，回答下面不再冒出「跳到最新」；长回答照常出现这个按钮，点了之后回答继续变长也会一直跟到最后（BUG-1043）。 +- 生时校正里回答超过一屏时，本轮开头停在屏幕顶部，不再一到就跳到最后一个字；自己往下滑到底之后，再长出来的内容会继续跟随（BUG-1044）。 +- Skill 版本不 bump。只改聊天滚动逻辑，不改接口、数据库和样式；登录态真机与部署待验收。 + ## 2026-09-26 — 回答下面的点赞 / 踩 / 复制 / 重试紧贴正文（待验收） - 最后一轮回答很短时，点赞 / 踩 / 复制 / 重试那一排不再被推到屏幕下部，直接跟在正文下面；空白挪到按钮（和追问建议）之后。普通对话和生时校正一样。 diff --git a/docs/BUG_HISTORY.md b/docs/BUG_HISTORY.md index 73847c28..af434c18 100644 --- a/docs/BUG_HISTORY.md +++ b/docs/BUG_HISTORY.md @@ -13962,29 +13962,29 @@ ## BUG-1043 | 直接打开普通咨询会话后，滚动锚的监听从未挂上 -- 状态：investigating（仅诊断；本轮任务书禁止改 `useConversationScrollAnchor`，未修） +- 状态：investigating（已修复、本地真实浏览器验证通过；等待 Claude 验收与 staging 部署后真机复核） - 首次发现 / 最近更新：2026-09-26 / 2026-09-26 -- 影响面：`frontend/src/hooks/use-conversation-scroll-anchor.ts` 两个 effect（scroll 监听、ResizeObserver 跟随）与首页 `page.tsx` 的加载闸门；普通咨询面。生时校正面不受影响（组件在揭幕后才挂载）。 -- 用户现象（本地复现）：刷新页面或经 `?c=` / 启动落点直接进入一个已有的普通咨询会话后，发一个短问题，回答很短也会出现「跳到最新」；上下滚动该按钮不消失；点它之后回答继续变长也不会跟随。 -- 触发条件：首页揭幕时当前会话就是一条有消息的普通咨询（不是揭幕后再切换过去）。 -- 已确认事实：无头 Chrome 151、生产构建、虚构数据下给 `EventTarget.addEventListener` 与 `ResizeObserver.observe` 打点：该路径下 `.conversation` 上 scroll 监听 0 次、ResizeObserver 观察 0 次；先开 `/?new=1` 再点侧栏进入同一会话，则各挂上 1 次，短回答不再出现「跳到最新」。`pinLatestTurn` 走 rAF 不依赖 effect，所以钉顶本身正常，但 `latestBelowFold` 停在钉顶那一刻算出的值。 -- 推测根因（未证实）：加载闸门期间 `page.tsx` 早退渲染 `.app-loading`，`.conversation` 尚未挂载，effect 因 `container.current` 为空直接返回；揭幕后 `active` 与 `resetKey`（`activeSessionId`）都没变，effect 不会重跑。 -- 修复：未修。需要单独任务书授权改 hook（例如依赖里加入容器是否已挂载的状态）。 -- 验证：见上，复现脚本在执行方 scratchpad，未入库。 -- 防复发：待定。 -- 相关记录：BUG-930、BUG-932、BUG-1042。 +- 影响面：`frontend/src/hooks/use-conversation-scroll-anchor.ts` 的挂载逻辑（scroll 监听、ResizeObserver 跟随）；首页 `page.tsx` 的加载闸门之后才挂载的 `.conversation`。生时校正面不受影响（组件在揭幕后才挂载，容器从首帧就在）。 +- 用户现象：刷新页面、经 `?c=` 深链或启动落点直接进入一个已有的普通咨询会话后：没有落到最新一条（停在历史中段）；发一个短问题，回答很短也会出现「跳到最新」；上下滚动该按钮不消失；点它之后回答继续变长也不会跟随。 +- 触发条件：首页揭幕时当前会话就是一条有消息的普通咨询（不是揭幕后再切换过去）。先开 `/?new=1` 再点侧栏进入同一会话则正常。 +- 根因（已证实）：hook 的两个 effect 依赖 `[active, container, resetKey]`。加载闸门期间 `page.tsx` 早退渲染 `.app-loading`，`.conversation` 未挂载，两个 effect 因 `container.current` 为空直接返回；揭幕那次提交里 `active`（`!rectificationSurfaceOpen && !starterHomeVisible`）与 `resetKey`（`activeSessionId`）都没变，`container` 是同一个 ref 对象，effect 不重跑，于是 scroll 监听、ResizeObserver 与「打开会话先落底」三件事都没发生。`pinLatestTurn` 走 rAF 不依赖 effect，所以钉顶本身正常，但 `latestBelowFold` 停在钉顶那一刻（平滑滚动尚未开始时）算出的值。证据：新增的真实 React 生命周期测试（先渲染加载屏再揭幕）中 3 条 BUG-1043 用例对改前代码全部失败（scroll 监听 0、点「跳到最新」后不跟随、容器重挂载后旧元素仍挂着监听）；无头 Chrome 插桩改前 `.conversation` scroll 监听 0、ResizeObserver 观察 0、打开后距底 1819px。 +- 修复：挂载改由「滚动容器元素本身」驱动：一个每次提交后运行的 effect 比较 `container.current`、`active`、`resetKey` 与上次挂载时的记录，三者都没变就什么也不做；元素出现、换了、`active` 翻转或换会话时先卸下旧的，再对新元素挂 scroll 监听 + ResizeObserver/MutationObserver；卸载时另一个空依赖 effect 负责清理。调用处与 hook 签名不变（`page.tsx`、`rectification-agentic-chat.tsx` 未改）。选这一路而不是 callback ref，是因为两个调用处都把同一个 `RefObject` 另作他用，改 callback ref 必须改校正面组件（本轮并行任务在改）；也不用「effect 里 setState 记录元素」，那会触发 react-hooks 编译器规则。 +- 验证：`frontend/tests/conversation-scroll-anchor-lifecycle.test.tsx`（createRoot + act 真实生命周期，宿主节点只伪造几何与事件）：「加载屏 → 揭幕」后 scroll 监听 1 个、ResizeObserver 有观察、落到最新、重复渲染不重复挂载、短回答平滑滚动落定后不显示「跳到最新」；长回答显示按钮、点击后继续跟随；同一会话下容器重挂载会迁到新元素、旧元素监听被卸下；`active` 关开会卸下 / 重挂。无头 Chrome 151 + 生产构建 + 虚构数据（`?c=` 直接打开、打开后刷新、先 `?new=1` 再点侧栏三种进入方式）：改后 scroll 监听 1、观察 1、打开后距底 0；短回答「跳到最新」不出现（改前出现）；长回答按钮出现，点击后落底，再插入 400px 仍距底 0（改前 400）。全量前端测试失败名单与基线逐条一致。截图 `docs/testing/scroll-anchor-hook-fixes-20260926/consult-reload-short-375-{before,after}.png`。 +- 防复发：hook 不得再用只依赖 `active` / `resetKey` 的 effect 挂监听；生命周期测试锁住「加载屏 → 揭幕」路径。 +- 相关记录：BUG-930、BUG-932、BUG-1042、BUG-1044。 - 复发自：无。 -- 修复版本：无。 +- 修复版本：`codex/scroll-anchor-hook-fixes-20260926`，未部署。 ## BUG-1044 | 生时校正长回答钉顶后又被拉到底部 -- 状态：investigating（仅诊断；本轮任务书禁止改 `useConversationScrollAnchor`，未修） +- 状态：investigating（已修复、本地真实浏览器验证通过；等待 Claude 验收与 staging 部署后真机复核） - 首次发现 / 最近更新：2026-09-26 / 2026-09-26 -- 影响面：`useConversationScrollAnchor` 的 `holdUnpin` 解除条件 × 生时校正 `.message-list` 的底部留白（`padding-bottom: calc(var(--rectification-jump-clearance) + var(--space-3))`）。 -- 用户现象（本地复现）：生时校正里发一句话，回答超过一屏时，本轮开头先被钉到顶部，回答一到视口就跳到最后一个字（BUG-930 想解决的现象）。 -- 已确认事实：CDP 逐 100ms 采样：平滑滚动结束时本轮开头距顶 10px、`distanceFromBottom` = 94（≤ `conversationAnchorThreshold` 96），下一帧回答撑高后 `scrollTop` 直接到底。改动前（旧留白规则）表现完全相同（开头位置 −1323px，落底），与 BUG-1042 无关。普通咨询同一时刻距离约 198，不触发。 -- 推测根因（未证实）：钉顶后的静止距离等于该面底部留白 + 钉顶间距，校正面恰好 ≤ 96，`measure()` 把它当成「读者回到底部」，解除 `holdUnpin` 并把 `anchored` 翻回真，随后 ResizeObserver 贴底跟随。BUG-931 修的是留白坍塌导致的同一症状，这里留白正常但阈值判断仍然命中。 -- 修复：未修。需单独任务书决定改阈值判定还是改该面的留白口径。 -- 相关记录：BUG-930、BUG-931、BUG-1042。 +- 影响面：`useConversationScrollAnchor` 的 `holdUnpin` 解除条件；生时校正面（钉顶后静止距底 94px）。普通咨询静止距底约 198px，未触发，但同一逻辑也适用。 +- 用户现象：生时校正里发一句话，回答超过一屏时，本轮开头先被钉到顶部，回答一到视口就跳到最后一个字（BUG-930 想解决的现象）。 +- 根因（已证实）：钉顶后 `holdUnpin` 为真，`measure()` 在任何 scroll 事件里若 `distanceFromBottom ≤ 96` 就当作「读者回到底部」，解除 `holdUnpin` 并把 `anchored` 翻回真，随后 ResizeObserver 贴底跟随。钉顶平滑滚动自己产生的 scroll 事件落定时，校正面距底恰为 94（全视口留白 + `.message-list` 底部的跳到最新让位 56+12px − 钉顶间距），命中阈值。另一条同类路径：钉顶后任何向上的非用户滚动（内容收缩夹紧）也会解除 `holdUnpin`，再由几何距离翻回贴底。 +- 修复：钉顶后只有读者自己的滚动能解除钉住：hook 在滚动容器上记 `wheel`、`touchmove`、按在容器本身（滚动条）的 `pointerdown`，在 window 上记文本框 / 按钮之外的滚动键（方向、翻页、Home/End、空格），`measure()` 仅当距上次这类手势 1 秒内（`conversationGestureWindowMs`）才解除 `holdUnpin`，之后照旧：回到底部 96px 内恢复跟随，上滑则停在读者的位置。`pinLatestTurn` 在钉顶时清掉手势时间戳，发问那一下点按 / 回车不会解除自己的钉顶。消息里的按钮点按（复制、展开思考）不算。阈值 96 与留白口径都不改。 +- 验证：`conversation-scroll-anchor-lifecycle.test.tsx`：静止距底 94 且收到无手势 scroll 事件后回答撑长，仍钉在开头、`latestBelowFold` 为真（改前被拉到底）；滚轮滚到底后恢复跟随；触摸上拉解除钉住但不跟随（BUG-930 语义）；点按消息内按钮不算手势；滚动键过滤单测。无头 Chrome 151：375 宽改前开头位置 −1323px（落底），改后 10px 且 2 秒后仍是 10px、再插入 400px 仍是 10px（「跳到最新」出现）；随后真实滚轮（CDP `mouseWheel`）滚到底 → 距底 0，再插入 400px 仍距底 0（恢复跟随）；触摸拖动（CDP `dispatchTouchEvent`）同样到底后跟随。1280 宽改前 −482px，改后 10px，同样通过。截图 `docs/testing/scroll-anchor-hook-fixes-20260926/rectification-long-375-{before,after}.png`。 +- 防复发：钉顶的解除只能来自用户手势；生命周期测试用 94px 静止距离锁住。 +- 相关记录：BUG-930、BUG-931（同症状、留白坍塌触发）、BUG-1042、BUG-1043。 - 复发自：无（BUG-931 同症状、不同触发条件）。 -- 修复版本：无。 +- 修复版本：`codex/scroll-anchor-hook-fixes-20260926`，未部署。 diff --git a/docs/tasks/PROGRESS-scroll-anchor-hook-fixes-20260926.md b/docs/tasks/PROGRESS-scroll-anchor-hook-fixes-20260926.md new file mode 100644 index 00000000..4257a8dd --- /dev/null +++ b/docs/tasks/PROGRESS-scroll-anchor-hook-fixes-20260926.md @@ -0,0 +1,96 @@ +# PROGRESS · 滚动锚两处老问题（2026-09-26） + +任务书：`TASK-scroll-anchor-hook-fixes-20260926.md`。执行方：Claude 子代理（直接执行模式）。分支 `codex/scroll-anchor-hook-fixes-20260926`，worktree `.worktrees/scroll-anchor-hook-fixes-20260926`，本地提交未推送。 + +## 基线 + +- `origin/staging` = `509987b9`（BUG-1042 `080ea5ca` 已合入）。 +- 基线全量前端测试（Node 20.19.2）：3961 条，pass 3873 / fail 61（均为环境缺口：Node 20 `mock.module` 的 `ERR_MODULE_NOT_FOUND @/…`、无 Docker）。 +- 基线 rootMainFiles gzip 130933 B；`index.html` 引用的全部 js/css 合计 656748 B。 +- BUG 编号：沿用 BUG-1042 单已建的 BUG-1043、BUG-1044，本单不新增编号。 + +## 先复现（真实 React 生命周期测试） + +新增 `frontend/tests/conversation-scroll-anchor-lifecycle.test.tsx`，用仓内 `react-client-lifecycle-test-support.ts`（`createRoot` + `act`，effect / ref 都是 React 自己的），宿主节点只伪造几何（scrollTop 夹紧、scrollHeight、clientHeight）、事件表、ResizeObserver，以及「异步移动后再发 scroll」的平滑 `scrollTo`。测试组件照 `page.tsx` 的形状：hook 在闸门之上每次渲染都调用，加载时只渲染 `.app-loading`，揭幕后才渲染 `.conversation`。 + +对改前 hook 跑：9 条里 6 条失败（BUG-1043 三条：揭幕后 scroll 监听 0；点「跳到最新」后长大不跟随；容器重挂载后旧元素仍挂着监听。BUG-1044 三条：静止 94px 时被拉到底；滚轮到底后跟随断言因已提前贴底而位置不符；点消息内按钮后被拉到底）。「触摸上拉不跟随」「active 关开」「滚动键过滤」三条改前也通过（保持语义用）。改后 9/9 通过。 + +## 根因（均已证实） + +| BUG | 根因 | +| --- | --- | +| 1043 | 两个 effect 依赖 `[active, container, resetKey]`。加载闸门期间容器为 null，effect 早退；揭幕那次提交三个依赖都没变，effect 不重跑 → scroll 监听、ResizeObserver、「打开会话先落底」都没发生。浏览器插桩：改前监听 0 / 观察 0 / 打开后距底 1819px。 | +| 1044 | 钉顶后 `measure()` 在任何 scroll 事件里只要距底 ≤ 96 就解除 `holdUnpin` 并翻回贴底。钉顶平滑滚动自己的 scroll 事件落定时校正面距底 94（逐 100ms 采样：…99 → 94 后下一帧跳到底）。向上的非用户滚动也会解除 `holdUnpin`，是同类路径。 | + +## 改动 + +| 文件 | 内容 | +| --- | --- | +| `frontend/src/hooks/use-conversation-scroll-anchor.ts` | D1：原两个 `[active, container, resetKey]` effect 合为一个**每次提交后运行**的挂载 effect，比对 `container.current` / `active` / `resetKey` 与上次挂载记录，未变即空操作；变了先卸下旧挂载，再对当前元素挂 scroll 监听（`watchAnchor`）与 ResizeObserver + MutationObserver 跟随（`followContent`），两段内部逻辑与原来逐行一致；另有空依赖 effect 在卸载时清理。D2：钉顶期间 `measure()` 只有在 1 秒内出现过读者手势（容器上的 `wheel` / `touchmove` / 按在容器本身即滚动条的 `pointerdown`，window 上文本框与按钮之外的滚动键）时才解除 `holdUnpin`，之后照旧由 `nextAnchorState` 判断；`pinLatestTurn` 钉顶时清掉手势时间戳。新导出 `conversationGestureWindowMs`、`isScrollKeyGesture`。签名不变。 | +| 调用处 | **未改**（`page.tsx`、`rectification-agentic-chat.tsx` 一行未动）。不用 callback ref 的原因：两处都另用同一个 `RefObject`，校正面组件本轮由并行任务在改；也不用「effect 里 setState 记下元素」，会触发 react-hooks 编译器规则。 | +| `frontend/tests/conversation-scroll-anchor-lifecycle.test.tsx` | 新增 9 条（见上）。 | +| `frontend/DESIGN.md` | Answer start anchor：新增 **Release** 条目（只有读者滚动解除钉顶，94px 静止位置不算回到底部）；**History** 条目补「页面加载时的第一个会话同样落底、hook 随容器元素挂载」。 | +| 记录 | `docs/BUG_HISTORY.md`（BUG-1043 / 1044 根因、修复、验证，状态保持 investigating 等部署）、`CHANGELOG.md`、`docs/testing/scroll-anchor-hook-fixes-20260926.md` + 4 张截图、`docs/tasks/README.md`。 | + +### 改动既有断言 + +无。BUG-930 / 931 / 932 / 1042 的全部既有断言（`chat-notice-and-scroll-contract.test.ts` 的源码合同与假 DOM 行为、`starter-questions.test.ts`「Follow 段在 `if (!active || !element) return;` 之后才写 scrollTop」、`rectification-agentic-entry` / `rectification-timeline` / `rectification-mobile-timeline-readout` / `rectification-answer-choice` 对 hook 的断言）原样通过，一条未改。 + +## 测试 + +| 项 | 结果 | +| --- | --- | +| `tsc --noEmit` | 0 错 | +| `npm run lint` | 0 error（126 warning，与基线相同，均为既有） | +| 全量 `npm test` | 3970 条，pass 3882 / fail 61 | +| 失败名单 vs 基线 | 逐条一致（61 = 61，diff 为空），新增失败 0 | +| 测试名单 vs 基线 | +9 新名（本单新增），消失 0 | +| `npm run build -- --webpack` | 通过；`/`、`/_not-found`、`/chart`、`/ephemeris`、`/people` 均 ○ Static | +| gzip | rootMainFiles 130933 → 130933 B（0）；`index.html` 引用的 js/css 合计 656748 → 657114 B（+366 B，+0.06%） | + +构建经 node_modules 软链在 `frontend/frontend/` 下生成的杂散目录已删除，未提交。 + +## 真实浏览器验证 + +环境：本地 `next build --webpack` + `next start`（:3471 本分支；:3461 为 BUG-1042 工作树的构建，hook 与 `origin/staging` 相同，作「改前」），无头 Chrome 151（`--headless=new --disable-dev-shm-usage`），CDP `Fetch` 拦截 `/api/*` 回虚构数据（5 轮虚构历史；普通咨询 `/api/consult` 回纯文本，校正 `/api/rectification/agent` 回 ndjson）。输入框用 `Input.insertText` + Enter 真发问；滚轮用 `Input.dispatchMouseEvent mouseWheel`，触摸用 `Input.dispatchTouchEvent`。给 `EventTarget.addEventListener` / `ResizeObserver.observe` 打点计数 `.conversation` 上的监听。脚本在执行方 scratchpad `sa/sa.mjs`（由 BUG-1042 的 `gap.mjs` 改写），未入库。 + +「开头距顶」= 本轮用户行顶边 − 滚动容器顶边；「距底」= scrollHeight − scrollTop − clientHeight。 + +### (a) 普通咨询，直接打开已有会话（BUG-1043），375 宽 + +| 进入方式 | 版本 | 监听 / 观察 | 打开后距底 | 短回答结算后「跳到最新」 | 开头距顶 | +| --- | --- | --- | --- | --- | --- | +| `?c=` 直接打开 | 改前 | 0 / 0 | 1819 | **出现** | 14 | +| `?c=` 直接打开 | 改后 | 1 / 1 | 0 | 不出现 | 11 | +| 打开后刷新 | 改前 | 0 / 0 | 1819 | **出现**（上下滚动后仍在） | 11 | +| 打开后刷新 | 改后 | 1 / 1 | 0 | 不出现（上下滚动后仍不出现） | 13 | +| `?new=1` 再点侧栏 | 改后 | 1 / 1 | 0 | 不出现 | 10 | + +长回答（14 段），`?c=` 直接打开： + +| 宽度 | 版本 | 结算后 | 点「跳到最新」后 | 再插入 400px 后距底 | +| --- | --- | --- | --- | --- | +| 375 | 改前 | 开头距顶 10，按钮出现 | 距底 0，按钮消失 | **400**（不跟随） | +| 375 | 改后 | 开头距顶 12，按钮出现 | 距底 0，按钮消失 | 0（跟随） | +| 1280 | 改后 | 开头距顶 10，按钮出现 | 距底 0，按钮消失 | 0（跟随） | + +### (b) 生时校正长回答（BUG-1044），`?c=` 打开 + +| 宽度 | 版本 | 结算后开头距顶 / 距底 | 2 秒后 | 无手势 scroll 事件 + 插入 400px | 用户滚轮到底后 | 再插入 400px 后距底 | +| --- | --- | --- | --- | --- | --- | --- | +| 375 | 改前 | **−1323 / 0**（被拉到底） | 同 | 距底 0（贴底） | — | 0 | +| 375 | 改后 | 10 / 1333，按钮出现 | 10 | 开头仍 10，距底 1737 | 距底 0，按钮消失 | 0（恢复跟随） | +| 375 触摸 | 改后 | 10 / 1333 | 10 | 开头仍 10 | 触摸拖到底，距底 0 | 0（恢复跟随） | +| 1280 | 改前 | **−482 / 0** | 同 | 0 | — | 0 | +| 1280 | 改后 | 10 / 492，按钮出现 | 10 | 开头仍 10 | 距底 0 | 0（恢复跟随） | + +逐 100ms 采样（375，scrollTop,距底,开头距顶）：改前 `…2014,96,12 → 3349,0,-1323`；改后 `…2011,99,15 → 2016,1333,10` 并保持。校正短回答（375）静止距底 94、开头 10，插入 400px 后开头仍 10（不再因 94 ≤ 96 被判回到底部）。 + +截图（入库，375 宽）：`docs/testing/scroll-anchor-hook-fixes-20260926/consult-reload-short-375-{before,after}.png`（改前短回答下有「跳到最新」）、`rectification-long-375-{before,after}.png`。校正截图底部的「合盘历史暂时无法读取」是虚构数据没回合盘接口所致，与本单无关（BUG-1042 同）。 + +## 未做 / 环境缺口 + +- 登录态 iPhone Safari 真机：留给 `docs/testing/scroll-anchor-hook-fixes-20260926.md`。无头 Chrome 的触摸是 CDP 合成事件，不等于 iOS 的惯性滚动，真机第 6–8 条需要人看。 +- 键盘滚动（PageDown / 方向键）只有单测覆盖过滤规则，未在浏览器里实测。 +- 校正面「点选项」一轮（无用户行）未在浏览器里单独跑；生命周期测试覆盖的就是无用户行、头即尾的钉顶。 +- 未部署、未推送。 diff --git a/docs/tasks/README.md b/docs/tasks/README.md index 263c98f0..85da6632 100644 --- a/docs/tasks/README.md +++ b/docs/tasks/README.md @@ -121,7 +121,7 @@ | 任务书 | 进度 | 主题 | 状态 | 落点 | | --- | --- | --- | --- | --- | -| `TASK-scroll-anchor-hook-fixes-20260926.md` | — | **滚动锚两处老问题**：直接打开已有会话时监听未挂上（BUG-1043）、校正长回答钉顶后因 96px 阈值被拉到底（BUG-1044）。排在 BUG-1042 合入后 | 待领取 | — | +| `TASK-scroll-anchor-hook-fixes-20260926.md` | `PROGRESS-scroll-anchor-hook-fixes-20260926.md` | **滚动锚两处老问题**：直接打开已有会话时监听未挂上（BUG-1043）、校正长回答钉顶后因 96px 阈值被拉到底（BUG-1044）。排在 BUG-1042 合入后。挂载改由容器元素本身驱动（每次提交比对元素 / active / resetKey）；钉顶只由用户滚动手势解除 | 待验收 | `codex/scroll-anchor-hook-fixes-20260926`（BUG-1043/1044） | | `TASK-latest-turn-actions-gap-20260926.md` | — | **最后一轮正文与点赞 / 踩之间空大半屏**：BUG-930 钉顶留白（`min-height: 视口 − 本轮开头`）加在 `.message-assistant` 上，把兄弟节点 `.message-actions` 推到留白之后；改为加在整轮外层，按钮紧贴正文、空白落在后面；不动滚动 hook | 已验收（Claude 09-26 直接执行：子代理实现，Claude 独立复验 tsc/lint 0、全量 3961 条失败名单与基线逐条一致、四路由 ○、gzip 不变；CDP 实测间距 450–600px → 23px，钉顶仍在） | `080ea5ca`（已部署 `509987b9`，health 一致） | | `TASK-starter-home-polish-20260926.md` | `PROGRESS-starter-home-polish-20260926.md` | **首页开场小字与图标**：今日趋势（每日模型生成，非写死）移到问候下方副行；入口下方提示只在有未完成校正或非本人时出现，删两句固定文案并修正已校正仍显示首次文案的分支；今日星语图标 MoonStar、点数图标 Coins。排在 BUG-1038、1040 之后。分支误判实为入口摘要解析读错键名（BUG-1041） | 已验收（Claude 09-26 直接执行：子代理实现并查出 BUG-1041 入口摘要驼峰/下划线字段不一致；Claude 改恢复提示文案为「可以在历史对话里接着做」；独立复验 tsc/lint 0、全量 3960 条失败名单与基线逐条一致、四路由 ○、gzip 不变） | `f04da103`（已部署 `62d4c9c4`，health 一致） | | `TASK-latest-turn-actions-gap-20260926.md` | `PROGRESS-latest-turn-actions-gap-20260926.md` | **末轮回答与点赞一排之间大段空白**：BUG-930 的钉顶留白加在助手行上，把其后的 `.message-actions` 顶到留白之后；改加在整轮外层（`:last-child:has(.message-assistant)` + `align-content: start`），不改 hook。验证中另查出既有 BUG-1043（直接进入普通咨询会话时滚动锚监听未挂上）、BUG-1044（校正长回答钉顶后被拉到底），未修 | 待验收 | `codex/latest-turn-actions-gap-20260926`（BUG-1042） | diff --git a/docs/testing/scroll-anchor-hook-fixes-20260926.md b/docs/testing/scroll-anchor-hook-fixes-20260926.md new file mode 100644 index 00000000..a3c874d0 --- /dev/null +++ b/docs/testing/scroll-anchor-hook-fixes-20260926.md @@ -0,0 +1,20 @@ +# 滚动锚两处老问题 · 真机清单（2026-09-26） + +本轮在本地 `next start` + 无头 Chrome 里用虚构接口数据验证并截图（`scroll-anchor-hook-fixes-20260926/`，375 宽改动前后各两张），没有登录态真机。部署到 staging 后请用自己的账户照做，iPhone Safari 与桌面浏览器各一遍： + +## 普通对话（BUG-1043） + +1. 打开一个已有好几轮内容的普通对话，然后**刷新页面**。揭幕后画面停在最后一条回答（不是停在中间某条）。 +2. 问一个很短就能答完的问题。回答结束后：你的问题停在屏幕顶部附近，**底部没有「跳到最新」**。 +3. 手指往上滑一点再滑回来，「跳到最新」不会一直挂着。 +4. 再问一个会得到长回答的问题。回答超过一屏时底部出现「跳到最新」；点一下滚到最后，之后回答继续变长，画面**一直跟着最后一行**。 +5. 从侧栏复制这条对话的链接（带 `?c=`），在新标签页里直接打开，重复 2 和 4，表现一致。 + +## 生时校正（BUG-1044） + +6. 打开一个生时校正会话，打一段会让助手长篇回复的经历发出去。回复超过一屏时：**本轮开头停在屏幕顶部**，底部出现「跳到最新」，画面不会自己跳到最后一个字。 +7. 不碰屏幕等回复写完，开头仍在顶部。 +8. 用手指往下滑到最底。之后若回复还在变长（或下一段出现），画面跟着最后一行走。 +9. 点一个选项按钮（没有打字的那种一轮）：新回复的开头同样停在顶部，不被拉到底。 + +看到下面任一情况算不通过，请截图：刷新后短回答下仍有「跳到最新」；点了「跳到最新」后回答再变长画面不跟；校正长回复一到就滚到最后一个字；滑到底后不再跟随。 diff --git a/docs/testing/scroll-anchor-hook-fixes-20260926/consult-reload-short-375-after.png b/docs/testing/scroll-anchor-hook-fixes-20260926/consult-reload-short-375-after.png new file mode 100644 index 00000000..5a3769d7 Binary files /dev/null and b/docs/testing/scroll-anchor-hook-fixes-20260926/consult-reload-short-375-after.png differ diff --git a/docs/testing/scroll-anchor-hook-fixes-20260926/consult-reload-short-375-before.png b/docs/testing/scroll-anchor-hook-fixes-20260926/consult-reload-short-375-before.png new file mode 100644 index 00000000..b9e00e12 Binary files /dev/null and b/docs/testing/scroll-anchor-hook-fixes-20260926/consult-reload-short-375-before.png differ diff --git a/docs/testing/scroll-anchor-hook-fixes-20260926/rectification-long-375-after.png b/docs/testing/scroll-anchor-hook-fixes-20260926/rectification-long-375-after.png new file mode 100644 index 00000000..02d86850 Binary files /dev/null and b/docs/testing/scroll-anchor-hook-fixes-20260926/rectification-long-375-after.png differ diff --git a/docs/testing/scroll-anchor-hook-fixes-20260926/rectification-long-375-before.png b/docs/testing/scroll-anchor-hook-fixes-20260926/rectification-long-375-before.png new file mode 100644 index 00000000..d4543a2f Binary files /dev/null and b/docs/testing/scroll-anchor-hook-fixes-20260926/rectification-long-375-before.png differ diff --git a/frontend/DESIGN.md b/frontend/DESIGN.md index f31f77a3..5279c4f6 100644 --- a/frontend/DESIGN.md +++ b/frontend/DESIGN.md @@ -258,7 +258,8 @@ Both chat surfaces pin a new turn at its head instead of following the last stre - **Head:** the user row of this turn. When this turn has no user row (rectification choice tap, opening, auto-continue) the head is the new assistant row. - **Pin:** on send (and on those rectification new-turn entries) the scroller places that row at the top with a `space-4` gap and then holds still while the reply grows downward. - **Spacer:** the last turn's entry — the `.message-list` child that holds the assistant row, its `.message-actions`, follow-up chips and (rectification) delivery card — gets `min-height: calc(var(--conversation-viewport) - var(--latest-turn-head-height))` plus `align-content: start`, both variables written onto the scroller by `useConversationScrollAnchor`. The spacer trails the whole turn: the actions row sits right under the text at its own `margin: -4px 0 8px`, and the empty space comes after it (BUG-1042; the assistant row itself never carries the spacer — that pushed the actions half a screen down). `align-content: start` keeps the rectification wrap's grid rows from stretching into the space. Not sticky, and `.conversation`'s `padding-bottom` is unchanged. The spacer lasts until the next send; switching sessions clears it. -- **History:** opening another session still lands on the newest content once. +- **Release:** the pin holds until the reader scrolls — a wheel, a touch drag, a scroll key outside a text field, or a press on the scroller's own scrollbar, followed by a scroll within 1s. Scrolling back to within 96px of the bottom then resumes following; scrolling up leaves the viewport where they put it. Where the pin happens to rest never releases it: the rectification surface rests 94px from the bottom (its spacer plus the jump-chip clearance), inside the threshold, and treating that as "back at the bottom" dragged long rectification replies to their last line (BUG-1044). Taps on buttons inside a message do not count. +- **History:** opening another session still lands on the newest content once. That includes the first session on page load (refresh, `?c=` deep link, boot landing): the scroller only mounts after the loading screen, and the hook attaches its scroll listener and resize observer whenever the scroller element appears, not only when `active` or the session key changes (BUG-1043). Without that, a directly opened session showed “跳到最新” under a short reply and never followed. - **Jump to latest:** if the growing turn (or the reader scrolling) leaves more than 96px below the fold, the shared chip appears; pressing it sticks to the bottom for the rest of the turn. ### Jump to latest diff --git a/frontend/src/hooks/use-conversation-scroll-anchor.ts b/frontend/src/hooks/use-conversation-scroll-anchor.ts index 7b4f02bc..747619ed 100644 --- a/frontend/src/hooks/use-conversation-scroll-anchor.ts +++ b/frontend/src/hooks/use-conversation-scroll-anchor.ts @@ -116,6 +116,26 @@ export function latestContentBelowFold(overflow: number): boolean { return overflow > conversationAnchorThreshold; } +/** How long after a wheel / touch drag / scroll key / scrollbar press a scroll still counts as the reader's own. */ +export const conversationGestureWindowMs = 1_000; + +const scrollKeys = new Set(["ArrowUp", "ArrowDown", "PageUp", "PageDown", "Home", "End", " "]); + +export function isScrollKeyGesture(event: Pick): boolean { + if (!scrollKeys.has(event.key) || event.altKey || event.ctrlKey || event.metaKey) return false; + const target = event.target as { closest?: (selector: string) => unknown } | null; + if (typeof target?.closest !== "function") return true; + if (target.closest("input, textarea, select, [contenteditable]:not([contenteditable='false'])")) return false; + // Space on a button or link activates it instead of scrolling. + return !(event.key === " " && target.closest("button, a[href], summary, [role='button']")); +} + +type Attachment = { + readonly element: HTMLElement; + readonly resetKey: string; + readonly detach: () => void; +}; + /** * Owns both halves of "follow the conversation": whether the reader is * anchored to the bottom (a scroll listener), and landing the viewport on the @@ -123,8 +143,9 @@ export function latestContentBelowFold(overflow: number): boolean { * children, one frame per change). Both chat surfaces use this one hook. * * A new turn pins its head (the user row, or the new assistant when this turn - * has no user row) at the top and does not follow streamed growth. Switching - * conversations still lands on the newest content once. + * has no user row) at the top and does not follow streamed growth. Only the + * reader's own scrolling releases that pin (BUG-1044). Switching conversations + * still lands on the newest content once. */ export function useConversationScrollAnchor( container: RefObject, @@ -138,6 +159,8 @@ export function useConversationScrollAnchor( const shouldLand = useRef(true); const holdUnpin = useRef(false); const pinnedHeadRef = useRef(null); + const lastGestureAt = useRef(Number.NEGATIVE_INFINITY); + const attachment = useRef(null); const anchored = anchor.key === resetKey ? anchor.anchored : true; useEffect(() => { @@ -150,102 +173,150 @@ export function useConversationScrollAnchor( pinnedHeadRef.current = null; }, [resetKey]); - useEffect(() => { - const element = container.current; - if (!active || !element) return; - lastScrollTop.current = element.scrollTop; - let frame = 0; - const measure = () => { - frame = 0; - const overflow = turnTailOverflow(element); - const distance = conversationDistanceFromBottom(element); - const scrolledUp = element.scrollTop < lastScrollTop.current; - lastScrollTop.current = element.scrollTop; - setLatestBelowFold(latestContentBelowFold(overflow)); - if (holdUnpin.current) { - if (scrolledUp) { - holdUnpin.current = false; - } else if (distance <= conversationAnchorThreshold) { - holdUnpin.current = false; - } else { - return; - } - } - setAnchor((current) => { - const currentAnchored = current.key === resetKey ? current.anchored : true; - const next = nextAnchorState(currentAnchored, distance, scrolledUp); - return next === currentAnchored && current.key === resetKey ? current : { key: resetKey, anchored: next }; - }); - }; - const onScroll = () => { - if (frame) return; - frame = window.requestAnimationFrame(measure); - }; - element.addEventListener("scroll", onScroll, { passive: true }); - frame = window.requestAnimationFrame(measure); - return () => { - if (frame) window.cancelAnimationFrame(frame); - element.removeEventListener("scroll", onScroll); - }; - }, [active, container, resetKey]); - // Follow: while anchored, any change in the scroller's content height lands the // viewport on the bottom, at most once per frame. Switching conversations // (resetKey) lands there immediately. Unanchored turns only refresh the spacer. + // + // The anchor listener and this observer attach to the scroller element itself, + // whenever it appears. The home page mounts `.conversation` only after its + // loading screen, while `active` and `resetKey` stay the same, so an effect + // keyed on those alone ran once against a null ref and never again (BUG-1043). + // This effect therefore checks after every commit and is a no-op unless the + // element, `active` or `resetKey` changed. useEffect(() => { const element = container.current; + const current = attachment.current; + if (current && active && current.element === element && current.resetKey === resetKey) return; + current?.detach(); + attachment.current = null; if (!active || !element) return; - let frame = 0; - const follow = () => { - frame = 0; - if (shouldLand.current) { - element.scrollTop = element.scrollHeight; - shouldLand.current = false; - holdUnpin.current = false; - pinnedHeadRef.current = null; - clearTurnSpacer(element); - const atBottom = conversationDistanceFromBottom(element) <= conversationAnchorThreshold; - anchoredRef.current = atBottom; - setAnchor({ key: resetKey, anchored: atBottom }); - setLatestBelowFold(false); - return; - } - if (anchoredRef.current) { - element.scrollTop = element.scrollHeight; - } else if (pinnedHeadRef.current) { - applyTurnSpacer(element, pinnedHeadRef.current); - } - setLatestBelowFold(latestContentBelowFold(turnTailOverflow(element))); - }; - const requestFollow = () => { - if (frame) return; - frame = window.requestAnimationFrame(follow); - }; - requestFollow(); - if (typeof ResizeObserver === "undefined") { + + // Anchored or not: a scroll listener, plus the reader-gesture marks that alone may release a pin. + const watchAnchor = () => { + lastScrollTop.current = element.scrollTop; + let frame = 0; + const measure = () => { + frame = 0; + const overflow = turnTailOverflow(element); + const distance = conversationDistanceFromBottom(element); + const scrolledUp = element.scrollTop < lastScrollTop.current; + lastScrollTop.current = element.scrollTop; + setLatestBelowFold(latestContentBelowFold(overflow)); + if (holdUnpin.current) { + // A pinned turn rests wherever the pin and the spacer put it, which on + // the rectification surface is 94px from the bottom, inside the + // threshold. Geometry alone therefore never releases the pin; only a + // scroll the reader made does, up or down (BUG-1044). + const readerScrolled = performance.now() - lastGestureAt.current <= conversationGestureWindowMs; + if (!readerScrolled) return; + holdUnpin.current = false; + } + setAnchor((state) => { + const currentAnchored = state.key === resetKey ? state.anchored : true; + const next = nextAnchorState(currentAnchored, distance, scrolledUp); + return next === currentAnchored && state.key === resetKey ? state : { key: resetKey, anchored: next }; + }); + }; + const onScroll = () => { + if (frame) return; + frame = window.requestAnimationFrame(measure); + }; + const markGesture = () => { + lastGestureAt.current = performance.now(); + }; + // Pointer presses count only on the scroller itself (its scrollbar), not on + // a button or text inside a message. + const onPointerDown = (event: Event) => { + if (event.target === element) markGesture(); + }; + const onKeyDown = (event: KeyboardEvent) => { + if (isScrollKeyGesture(event)) markGesture(); + }; + element.addEventListener("scroll", onScroll, { passive: true }); + element.addEventListener("wheel", markGesture, { passive: true }); + element.addEventListener("touchmove", markGesture, { passive: true }); + element.addEventListener("pointerdown", onPointerDown, { passive: true }); + window.addEventListener("keydown", onKeyDown); + frame = window.requestAnimationFrame(measure); return () => { if (frame) window.cancelAnimationFrame(frame); + element.removeEventListener("scroll", onScroll); + element.removeEventListener("wheel", markGesture); + element.removeEventListener("touchmove", markGesture); + element.removeEventListener("pointerdown", onPointerDown); + window.removeEventListener("keydown", onKeyDown); }; - } - const sizes = new ResizeObserver(requestFollow); - const observeChildren = () => { - sizes.disconnect(); - for (const child of Array.from(element.children)) sizes.observe(child); }; - observeChildren(); - const children = typeof MutationObserver === "undefined" - ? null - : new MutationObserver(() => { - observeChildren(); - requestFollow(); - }); - children?.observe(element, { childList: true }); - return () => { - sizes.disconnect(); - children?.disconnect(); - if (frame) window.cancelAnimationFrame(frame); + + const followContent = () => { + let frame = 0; + const follow = () => { + frame = 0; + if (shouldLand.current) { + element.scrollTop = element.scrollHeight; + shouldLand.current = false; + holdUnpin.current = false; + pinnedHeadRef.current = null; + clearTurnSpacer(element); + const atBottom = conversationDistanceFromBottom(element) <= conversationAnchorThreshold; + anchoredRef.current = atBottom; + setAnchor({ key: resetKey, anchored: atBottom }); + setLatestBelowFold(false); + return; + } + if (anchoredRef.current) { + element.scrollTop = element.scrollHeight; + } else if (pinnedHeadRef.current) { + applyTurnSpacer(element, pinnedHeadRef.current); + } + setLatestBelowFold(latestContentBelowFold(turnTailOverflow(element))); + }; + const requestFollow = () => { + if (frame) return; + frame = window.requestAnimationFrame(follow); + }; + requestFollow(); + if (typeof ResizeObserver === "undefined") { + return () => { + if (frame) window.cancelAnimationFrame(frame); + }; + } + const sizes = new ResizeObserver(requestFollow); + const observeChildren = () => { + sizes.disconnect(); + for (const child of Array.from(element.children)) sizes.observe(child); + }; + observeChildren(); + const children = typeof MutationObserver === "undefined" + ? null + : new MutationObserver(() => { + observeChildren(); + requestFollow(); + }); + children?.observe(element, { childList: true }); + return () => { + sizes.disconnect(); + children?.disconnect(); + if (frame) window.cancelAnimationFrame(frame); + }; }; - }, [active, container, resetKey]); + + const stopWatching = watchAnchor(); + const stopFollowing = followContent(); + attachment.current = { + element, + resetKey, + detach: () => { + stopWatching(); + stopFollowing(); + }, + }; + }); + + useEffect(() => () => { + attachment.current?.detach(); + attachment.current = null; + }, []); return { anchored, @@ -268,6 +339,8 @@ export function useConversationScrollAnchor( const run = () => { shouldLand.current = false; holdUnpin.current = true; + // The gesture that sent this turn (tap, Enter) must not release its own pin. + lastGestureAt.current = Number.NEGATIVE_INFINITY; anchoredRef.current = false; if (!element) { setAnchor({ key: resetKey, anchored: false }); diff --git a/frontend/tests/conversation-scroll-anchor-lifecycle.test.tsx b/frontend/tests/conversation-scroll-anchor-lifecycle.test.tsx new file mode 100644 index 00000000..5dfc22ba --- /dev/null +++ b/frontend/tests/conversation-scroll-anchor-lifecycle.test.tsx @@ -0,0 +1,488 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import React, { useRef } from "react"; + +import { isScrollKeyGesture, useConversationScrollAnchor } from "../src/hooks/use-conversation-scroll-anchor.ts"; +import { createClientLifecycleHarness } from "./react-client-lifecycle-test-support.ts"; + +Object.assign(globalThis, { React }); + +/** + * Real React lifecycle (createRoot + act, effects and refs are React's own) + * around `useConversationScrollAnchor`. Only the scroller's geometry, its + * listeners and ResizeObserver are faked: the host node React mounts is + * decorated with scrollTop / scrollHeight / clientHeight, an event registry and + * an async `scrollTo` that fires `scroll` afterwards, as a browser's smooth + * scroll does. Numbers follow the CDP measurements in BUG-1042 / 1044 + * (consultation rests ~198px above the bottom after a pin, rectification 94px). + */ + +type Listener = (event: Record) => void; + +type FakeRow = { + offsetTop: number; + offsetHeight: number; + getBoundingClientRect: () => { top: number }; +}; + +type FakeScroller = { + scrollTop: number; + scrollHeight: number; + clientHeight: number; + tail: FakeRow; + children: unknown[]; + listeners: Map>; + scrollListenerAdds: number; + dispatch: (type: string, event?: Record) => void; + scrollTo: (options: { top: number }) => void; +}; + +type Anchor = ReturnType; + +let observeCalls = 0; +const observers = new Set(); + +class FakeResizeObserver { + readonly targets = new Set(); + constructor(readonly callback: () => void) { + observers.add(this); + } + observe(target: unknown) { + observeCalls += 1; + this.targets.add(target); + } + disconnect() { + this.targets.clear(); + } + unobserve() {} +} + +/** Content grew: every observer that still watches something fires. */ +function resizeAll() { + for (const observer of Array.from(observers)) { + if (observer.targets.size) observer.callback(); + } +} + +function row(offsetTop: number, offsetHeight: number, scroller: () => FakeScroller | null): FakeRow { + return { + offsetTop, + offsetHeight, + getBoundingClientRect() { + return { top: this.offsetTop - (scroller()?.scrollTop ?? 0) }; + }, + }; +} + +const decorated = new WeakMap(); + +// The inline ref callback below runs again on every render; decorate each host node once. +function decorate(node: Record, geometry: { scrollHeight: number; clientHeight: number; tail: FakeRow }): FakeScroller { + const existing = decorated.get(node); + if (existing) return existing; + const styles = new Map(); + const listeners = new Map>(); + let top = 0; + const scroller = node as unknown as FakeScroller; + Object.defineProperty(node, "style", { + configurable: true, + value: { + setProperty: (name: string, value: string) => styles.set(name, value), + getPropertyValue: (name: string) => styles.get(name) ?? "", + removeProperty: (name: string) => styles.delete(name), + }, + }); + Object.defineProperty(node, "scrollTop", { + configurable: true, + get: () => top, + set: (value: number) => { + top = Math.max(0, Math.min(value, scroller.scrollHeight - scroller.clientHeight)); + }, + }); + Object.assign(node, { + scrollHeight: geometry.scrollHeight, + clientHeight: geometry.clientHeight, + tail: geometry.tail, + children: [{ child: 1 }, { child: 2 }], + listeners, + scrollListenerAdds: 0, + addEventListener(type: string, listener: Listener) { + if (type === "scroll") scroller.scrollListenerAdds += 1; + if (!listeners.has(type)) listeners.set(type, new Set()); + listeners.get(type)!.add(listener); + }, + removeEventListener(type: string, listener: Listener) { + listeners.get(type)?.delete(listener); + }, + dispatch(type: string, event: Record = {}) { + for (const listener of Array.from(listeners.get(type) ?? [])) listener({ target: node, ...event }); + }, + // Smooth scroll: the position moves later, then `scroll` fires. + scrollTo({ top: next }: { top: number }) { + setTimeout(() => { + scroller.scrollTop = next; + scroller.dispatch("scroll"); + }, 0); + }, + getBoundingClientRect: () => ({ top: 0 }), + querySelector: () => scroller.tail, + querySelectorAll: () => [], + }); + decorated.set(node, scroller); + return scroller; +} + +function setup() { + const harness = createClientLifecycleHarness(); + const window = globalThis.window as unknown as Record; + window.matchMedia = () => ({ matches: false }); + const originalResizeObserver = Object.getOwnPropertyDescriptor(globalThis, "ResizeObserver"); + Object.defineProperty(globalThis, "ResizeObserver", { value: FakeResizeObserver, configurable: true, writable: true }); + observers.clear(); + observeCalls = 0; + return { + harness, + async close() { + await harness.close(); + if (originalResizeObserver) Object.defineProperty(globalThis, "ResizeObserver", originalResizeObserver); + else Reflect.deleteProperty(globalThis, "ResizeObserver"); + }, + }; +} + +type SurfaceProps = { + readonly loading: boolean; + readonly active?: boolean; + readonly resetKey: string; + readonly geometry: () => { scrollHeight: number; clientHeight: number; tail: FakeRow }; + readonly onScroller: (scroller: FakeScroller | null) => void; + readonly onAnchor: (anchor: Anchor) => void; + readonly generation?: number; +}; + +/** + * Mirrors the home page: while bootstrapping it renders only the loading + * screen, then reveals `.conversation` with the same `active` and `resetKey`. + * The hook is called above the gate on every render, as `page.tsx` does. + */ +function Surface({ loading, active = true, resetKey, geometry, onScroller, onAnchor, generation = 0 }: SurfaceProps) { + const conversation = useRef(null); + const anchor = useConversationScrollAnchor(conversation, active, resetKey); + onAnchor(anchor); + if (loading) return
; + return ( +
{ + const scroller = node ? decorate(node as unknown as Record, geometry()) : null; + conversation.current = scroller as unknown as HTMLDivElement | null; + onScroller(scroller); + }} + /> + ); +} + +const VIEWPORT = 600; +const PIN_SPACE = 16; + +test("an existing conversation revealed after the loading screen attaches the anchor (BUG-1043)", async () => { + const { harness, close } = setup(); + try { + let scroller: FakeScroller | null = null; + let anchor!: Anchor; + const history = row(1700, 276, () => scroller); + const props = { + resetKey: "session-1", + geometry: () => ({ scrollHeight: 2000, clientHeight: VIEWPORT, tail: history }), + onScroller: (value: FakeScroller | null) => { scroller = value; }, + onAnchor: (value: Anchor) => { anchor = value; }, + }; + + // Given: the page boots behind the loading screen, then reveals the same session. + await harness.render(); + await harness.idle(); + assert.equal(scroller, null); + await harness.render(); + await harness.idle(); + + // Then: the scroll listener and the resize observer are attached to the revealed scroller, + // and opening the session landed on its newest content once. + const element = scroller as unknown as FakeScroller; + assert.equal(element.scrollListenerAdds, 1); + assert.ok(observeCalls > 0, "ResizeObserver never observed the scroller's children"); + assert.equal(element.scrollTop, 2000 - VIEWPORT); + + // Re-rendering (every streamed token re-renders the page) does not attach twice. + await harness.render(); + await harness.render(); + await harness.idle(); + assert.equal(element.scrollListenerAdds, 1); + assert.equal(element.listeners.get("scroll")?.size, 1); + + // When: a short question is sent. The user row lands at 2000, the reply is 80px, and the + // spacer makes room for the pin; consultation rests ~198px above the bottom. + const user = row(2000, 48, () => scroller); + element.tail = row(2064, 80, () => scroller); + element.scrollHeight = 2000 - PIN_SPACE + VIEWPORT + 198; + await harness.update(() => anchor.pinLatestTurn(user as unknown as HTMLElement)); + await harness.idle(); + await harness.idle(); + + // Then: the head is pinned and, once the smooth scroll lands, a short reply shows no jump chip. + assert.equal(element.scrollTop, 2000 - PIN_SPACE); + assert.equal(anchor.latestBelowFold, false); + assert.equal(anchor.anchored, false); + } finally { + await close(); + } +}); + +test("a long reply after reveal shows the jump chip and following works once pressed (BUG-1043)", async () => { + const { harness, close } = setup(); + try { + let scroller: FakeScroller | null = null; + let anchor!: Anchor; + const history = row(1700, 276, () => scroller); + const props = { + resetKey: "session-1", + geometry: () => ({ scrollHeight: 2000, clientHeight: VIEWPORT, tail: history }), + onScroller: (value: FakeScroller | null) => { scroller = value; }, + onAnchor: (value: Anchor) => { anchor = value; }, + }; + await harness.render(); + await harness.render(); + await harness.idle(); + const element = scroller as unknown as FakeScroller; + + const user = row(2000, 48, () => scroller); + element.tail = row(2064, 1400, () => scroller); + element.scrollHeight = 2064 + 1400 + 198; + await harness.update(() => anchor.pinLatestTurn(user as unknown as HTMLElement)); + await harness.idle(); + await harness.idle(); + assert.equal(element.scrollTop, 2000 - PIN_SPACE); + assert.equal(anchor.latestBelowFold, true); + + // When: the reader presses 跳到最新. + await harness.update(() => anchor.anchorToLatest()); + await harness.idle(); + await harness.idle(); + assert.equal(element.scrollTop, element.scrollHeight - VIEWPORT); + assert.equal(anchor.latestBelowFold, false); + assert.equal(anchor.anchored, true); + + // Then: further growth keeps the viewport on the bottom. + element.tail.offsetHeight += 400; + element.scrollHeight += 400; + await harness.update(() => resizeAll()); + await harness.idle(); + assert.equal(element.scrollTop, element.scrollHeight - VIEWPORT); + } finally { + await close(); + } +}); + +test("a scroller that remounts under the same key re-attaches to the new element (BUG-1043)", async () => { + const { harness, close } = setup(); + try { + const seen: FakeScroller[] = []; + let anchor!: Anchor; + const props = { + loading: false, + resetKey: "session-1", + geometry: () => ({ scrollHeight: 1200, clientHeight: VIEWPORT, tail: row(900, 276, () => null) }), + onScroller: (value: FakeScroller | null) => { if (value && !seen.includes(value)) seen.push(value); }, + onAnchor: (value: Anchor) => { anchor = value; }, + }; + await harness.render(); + await harness.idle(); + await harness.render(); + await harness.idle(); + assert.equal(seen.length, 2); + const [first, second] = seen; + assert.equal(first.listeners.get("scroll")?.size ?? 0, 0, "the detached scroller kept its listener"); + assert.equal(second.listeners.get("scroll")?.size, 1); + assert.ok(anchor); + + // Unmounting the page releases the listener. + await harness.render(); + await harness.idle(); + assert.equal(second.listeners.get("scroll")?.size ?? 0, 0); + } finally { + await close(); + } +}); + +async function pinnedRectificationTurn() { + const env = setup(); + let scroller: FakeScroller | null = null; + let anchor!: Anchor; + const history = row(1700, 276, () => scroller); + const props = { + loading: false, + resetKey: "case-1", + geometry: () => ({ scrollHeight: 2000, clientHeight: VIEWPORT, tail: history }), + onScroller: (value: FakeScroller | null) => { scroller = value; }, + onAnchor: (value: Anchor) => { anchor = value; }, + }; + // The rectification surface mounts after reveal, so its scroller exists from the first render. + await env.harness.render(); + await env.harness.idle(); + const element = scroller as unknown as FakeScroller; + assert.equal(element.scrollTop, 2000 - VIEWPORT); + + // A choice tap: no user row, the new assistant is the head and the tail. The full-viewport + // spacer plus the rectification list's bottom padding leave the pin resting 94px above the + // bottom, i.e. inside the 96px threshold (CDP measurement, BUG-1044). + const head = row(2000, 80, () => scroller); + element.tail = head; + element.scrollHeight = 2000 - PIN_SPACE + VIEWPORT + 94; + await env.harness.update(() => anchor.pinLatestTurn(head as unknown as HTMLElement)); + await env.harness.idle(); + await env.harness.idle(); + return { ...env, element, head, anchor: () => anchor }; +} + +test("a rectification pin resting within the threshold is not pulled to the bottom (BUG-1044)", async () => { + const { harness, close, element, head, anchor } = await pinnedRectificationTurn(); + try { + const pinned = 2000 - PIN_SPACE; + assert.equal(element.scrollTop, pinned); + assert.equal(element.scrollHeight - element.scrollTop - element.clientHeight, 94); + assert.equal(anchor().anchored, false); + + // A scroll event nobody made (layout, scroll anchoring) at the same resting position. + await harness.update(() => element.dispatch("scroll")); + await harness.idle(); + assert.equal(anchor().anchored, false); + + // When: the reply streams past the viewport. + head.offsetHeight = 1400; + element.scrollHeight = 2000 + 1400 + 94; + await harness.update(() => resizeAll()); + await harness.idle(); + + // Then: the head stays at the top and the jump chip appears instead. + assert.equal(element.scrollTop, pinned); + assert.equal(anchor().anchored, false); + assert.equal(anchor().latestBelowFold, true); + } finally { + await close(); + } +}); + +test("after a pin only a reader's own scroll to the bottom resumes following (BUG-1044)", async () => { + const { harness, close, element, head, anchor } = await pinnedRectificationTurn(); + try { + head.offsetHeight = 1400; + element.scrollHeight = 2000 + 1400 + 94; + await harness.update(() => resizeAll()); + await harness.idle(); + assert.equal(element.scrollTop, 2000 - PIN_SPACE); + + // When: the reader wheels down to the bottom. + await harness.update(() => { + element.dispatch("wheel", { deltaY: 900 }); + element.scrollTop = element.scrollHeight; + element.dispatch("scroll"); + }); + await harness.idle(); + assert.equal(anchor().anchored, true); + assert.equal(anchor().latestBelowFold, false); + + // Then: further growth is followed. + head.offsetHeight += 400; + element.scrollHeight += 400; + await harness.update(() => resizeAll()); + await harness.idle(); + assert.equal(element.scrollTop, element.scrollHeight - VIEWPORT); + } finally { + await close(); + } +}); + +test("after a pin a touch drag upward releases the pin without following (BUG-930 kept)", async () => { + const { harness, close, element, head, anchor } = await pinnedRectificationTurn(); + try { + await harness.update(() => { + element.dispatch("touchmove"); + element.scrollTop -= 300; + element.dispatch("scroll"); + }); + await harness.idle(); + assert.equal(anchor().anchored, false); + const readingAt = element.scrollTop; + + head.offsetHeight = 1400; + element.scrollHeight = 2000 + 1400 + 94; + await harness.update(() => resizeAll()); + await harness.idle(); + assert.equal(element.scrollTop, readingAt); + assert.equal(anchor().latestBelowFold, true); + } finally { + await close(); + } +}); + +test("clicking inside the transcript is not a scroll gesture (BUG-1044)", async () => { + const { harness, close, element, head, anchor } = await pinnedRectificationTurn(); + try { + // A tap on a button in a message (copy, thinking toggle) bubbles pointerdown to the scroller. + await harness.update(() => { + element.dispatch("pointerdown", { target: head }); + element.dispatch("scroll"); + }); + await harness.idle(); + head.offsetHeight = 1400; + element.scrollHeight = 2000 + 1400 + 94; + await harness.update(() => resizeAll()); + await harness.idle(); + assert.equal(element.scrollTop, 2000 - PIN_SPACE); + assert.equal(anchor().anchored, false); + } finally { + await close(); + } +}); + +test("switching the hook off and on (starter home, rectification surface) detaches and re-attaches", async () => { + const { harness, close } = setup(); + try { + let scroller: FakeScroller | null = null; + const props = { + loading: false, + resetKey: "session-1", + geometry: () => ({ scrollHeight: 1200, clientHeight: VIEWPORT, tail: row(900, 276, () => null) }), + onScroller: (value: FakeScroller | null) => { scroller = value; }, + onAnchor: () => undefined, + }; + await harness.render(); + await harness.idle(); + const element = scroller as unknown as FakeScroller; + assert.equal(element.listeners.get("scroll")?.size ?? 0, 0); + await harness.render(); + await harness.idle(); + assert.equal(element.listeners.get("scroll")?.size, 1); + await harness.render(); + await harness.idle(); + assert.equal(element.listeners.get("scroll")?.size ?? 0, 0); + } finally { + await close(); + } +}); + +test("scroll keys count as a reader gesture only outside text fields and buttons", () => { + const target = (match: string | null) => ({ closest: (selector: string) => (match && selector.includes(match) ? {} : null) }); + const key = (value: string, over: Partial = {}) => ({ + key: value, target: target(null), altKey: false, ctrlKey: false, metaKey: false, ...over, + }) as unknown as KeyboardEvent; + assert.equal(isScrollKeyGesture(key("PageDown")), true); + assert.equal(isScrollKeyGesture(key("End")), true); + assert.equal(isScrollKeyGesture(key(" ")), true); + assert.equal(isScrollKeyGesture(key("a")), false); + assert.equal(isScrollKeyGesture(key("Enter")), false); + assert.equal(isScrollKeyGesture(key("ArrowDown", { target: target("textarea") as unknown as EventTarget })), false); + assert.equal(isScrollKeyGesture(key(" ", { target: target("button") as unknown as EventTarget })), false); + assert.equal(isScrollKeyGesture(key("PageDown", { target: target("button") as unknown as EventTarget })), true); + assert.equal(isScrollKeyGesture(key("ArrowDown", { metaKey: true })), false); +});