PDF 页面阴影与 WebKitGTK 滚动停顿¶

关联：#798。2026-10-21。

现象与修复¶

Ubuntu 22.04.5 LTS 上，Agentero 0.12.0 阅读多篇本地论文时，纸面移动出现明显的停顿；重启后仍会发生。PDFium worker 正常运行。

正文与 translationOnly 译文的页面壳使用 shadow-sm，包含覆盖整张纸面的模糊阴影。独立 WebKitGTK 阅读器中，保留空白页壳、去掉栅格与瓦片后仍可复现长帧；仅移除该阴影、保留 ring-1 细边框即可明显改善。完整 0.12.0 应用的真实用户配置中，切换同一阴影规则也测到明显差异，用户随后确认手动阅读体验有所改善。

源码修复只从两个页面壳移除 shadow-sm，保留纸张主题、圆角和 ring-1；页内浮层的小阴影保持原样。该改动不需要平台分支、依赖升级或新增状态。

在受影响的旧版本上，可于开发者工具中用以下临时规则做单因素对照；规则只在当前页面存在，remove() 后恢复：

const paperShadowProbe = document.createElement("style");
paperShadowProbe.textContent =
    "[data-embed-pdf-page] { --tw-shadow: 0 0 #0000 !important; }";
document.head.append(paperShadowProbe);
// 在相同工作区和阅读位置对照滚动体验；移除此规则可恢复原阴影。
// paperShadowProbe.remove();

测量环境与结果¶

Ubuntu 22.04.5 LTS，WebKitGTK 4.1 / libsoup 3，WebKit 2.50.4。
Agentero 0.12.0，EmbedPDF 2.14.4，PDFium worker；独立阅读器使用生产模式 React 19.2.7。
每个条件约 8 秒，记录 requestAnimationFrame 回调间隔的 p95。它是滚动时的帧间隔指标，不是直接测得的光栅化耗时，也不是对整应用稳定帧率的承诺。

环境与输入	原模糊阴影 p95	去掉模糊阴影 p95
独立阅读器，GG-CNN，脚本滚动	191 ms	19 ms
独立阅读器，OpenVLA，脚本滚动	187 ms	24 ms
独立阅读器，GG-CNN，GDK 滚轮事件注入	193 ms	21 ms
独立阅读器，安装版真实 CSS，GDK 滚轮事件注入	203 ms	21 ms
完整应用，真实配置，先原样式后修补	469 ms	46 ms
完整应用，真实配置，先修补后原样式	499 ms	46 ms
完整应用，独立默认配置，GG-CNN	约 17 ms	约 17 ms

完整应用的真实配置使用 uiScale: 1.5。在同一进程中，只切换页面壳的阴影规则，脚本按时间计算滚动位置；每轮恢复原阅读位置和修补样式。正反顺序两组的视口、文档几何相同（1679 × 1380，文档高度 111781 px），倒序结果也显示原阴影下仍有长帧，排除了仅由首次缓存预热解释改善的可能。

默认配置对照没有复现停顿。其论文和工作区也与真实配置不同，不能单独认定 UI 缩放是原因。GDK 是向独立测试窗口注入原生事件；完整应用的数值来自脚本滚动，不能当作用户手动滚轮的采样。

与 main 上栅格优化的关系¶

上述性能结果来自 0.12.0 及其页面阴影单因素对照，不是对 main 新增 BMP / 底图 / 瓦片优化的性能复测。main 在准备本修复时仍保留两个页面壳的 shadow-sm。阴影修改与栅格优化涉及不同层，但它们组合后的 Linux 性能仍需实际验证，不能直接相加各项收益，也不据此关闭 #798 的其他排查。

后续版本回归检查¶

单元测试无法证明 WebKit 的绘制性能，本次没有增加只检查 class 字符串的测试。后续调整纸张外观或阅读器渲染时，应在 Linux 原生 WebKitGTK 中检查：

多篇本地论文连续滚动，尤其真实工作区和 150% UI 缩放；等待初始适应宽度完成后再测量。
正文、双栏译文及各纸张主题仍保留清晰边界，避免重新引入整页模糊阴影。
缩放、跳页、文字选择和批注编辑仍可用；PDFium 使用 worker。
对性能变化使用相同输入和几何做正反顺序对照，保留未复现的配置，不以默认配置单次无卡顿替代受影响工作区的验证。

独立阅读器已验证虚拟页更新、200% 缩放与跳至第 2 页。完整应用的全部纸张主题、双栏译文、选择和批注编辑尚未逐项验收；新的 main 组合仍需正式构建及 Linux 集成检查。