SuperAPI AI 工具集

history-scroll-restoration-contracts

通用与其它

查看项目

更新于 10-16 06:15

技能介绍

用途:该技能面向 SPA 历史与滚动恢复(history/scroll restoration)故障排查。当后退/前进、navigate(-1) 或同文档 hash 遍历恢复了错误的滚动位置(跳到顶部、在异步内容创建滚动高度之前就恢复)时使用。

主要能力:以清单方式定位问题,包括:在真实浏览器中复现确切导航形态并记录 URL、历史条目标识或路由 key、导航动作、滚动归属容器、保存/应用/最终偏移;决定由浏览器(history.scrollRestoration = auto)还是应用/路由(manual)负责恢复;按历史条目语义(唯一 location key 与 pathname key)保存位置;区分 window 与嵌套 overflow: auto 容器等实际滚动归属;仅当目标能表示保存位置时恢复,绑定到可观察的路由/数据/布局就绪边界,而非任意延时或无界重试;把 fragment 视为导航状态并单独验证焦点;默认保留滚动锚定(overflow-anchor)。

使用与验证:提供快速探针日志字段(pathname、search、hash、entryKey、navigationType、owner、savedOffset、appliedOffset、finalOffset);建议最小浏览器回归流程,断言目标 URL 与历史 key、等待显式就绪信号、在一个小的容差内断言正确滚动容器到达保存偏移,并检查是否存在第二次跳动。附带 Playwright 夹具在 Chromium、Firefox、WebKit 中运行,覆盖重复同 URL 历史条目、异步布局就绪、精确偏移与两帧稳定性;不覆盖品牌 Safari 行为、跨文档 bfcache 或虚拟列表锚定。输出形态为 Disposition、Sequence、Evidence、Boundary、Smallest fix、Verification,并列出来源(MDN、Playwright、Next.js、React Router 文档与公开 issue)。

限制:不替代 bfcache、冷启动深链水合、虚拟列表锚定、遮罩焦点滚动或 SSR 水合不匹配等相关技能;拒绝无失败遍历的弱发现,也不主张从源码检查就规定 manual、全局 overflow-anchor: none、任意超时或重复滚动写入。