stitched-full-page-capture

name	stitched-full-page-capture
description	为懒加载、滚动动画、Framer、WebGL/canvas 或大量 reveal 的网页捕获或修复可靠的整页截图。当整页截图空白、灰屏、白屏、内容稀疏、只显示一小条内容、与能正常工作的滚动视频不一致，或者当文章证据/分区裁剪必须从可信的整页图像中导出时使用。

拼接式整页捕获

概述

使用稳定后的视口截图，而不是信任一次性的浏览器 fullPage 捕获。这对 Framer 页面以及其他懒加载/滚动动画站点尤其重要——这些站点的 MP4 可能看起来正确，而高的截图却大部分空白。

核心工作流程

1. 打开真实的页面 URL，而不是市场缩略图、封面图、remix 页面或资产 URL。
2. 通过从上到下滚动一次来预热页面，让懒加载媒体和 reveal 分区挂载。
3. 回到顶部。
4. 以视口大小或略微重叠的步长向下滚动。
5. 每次滚动停下后等待约 2 秒。
6. 捕获稳定后的视口。
7. 把这些视口捕获纵向拼接成一张整页图像。
8. 从这张拼接图像中切分区裁剪，而不是从浏览器原生的 fullPage 截图中切。
9. 用代表性静帧、MP4 和运动帧来验证拼接图像。

当整页候选图存在空白/灰/白色带、视觉内容极少、缺失懒加载分区、内容列极窄、或与滚动视频明显不一致时，拒绝它。

脚本

对于每日 UI 灵感文章，在可用时使用本技能目录中的辅助脚本：

node <skills-root>/stitched-full-page-capture/scripts/stitch_full_page_capture.mjs \
  --manifest articles/YYYY-MM-DD-ui-inspiration-capture/manifest.json

该脚本会：

• 读取 items[].pageUrl、fullPageImage 和 sectionImages；
• 用 Playwright Chromium 打开每个实时页面；
• 通过滚动一次预热懒加载内容；
• 捕获稳定后的视口切片；
• 把切片拼接成 fullPageImage；
• 从拼接图像中重新生成每个已有的分区裁剪；
• 用 fullPageCaptureMethod: "stitchedViewportScreenshots"、视口、步长、片段数和修正后的裁剪坐标更新 manifest.json。

有用的选项：

--item 4              # repair only item 4, 1-based
--viewport 1440x1100 # default
--step 950           # default; use less than viewport height for overlap
--wait 2000          # ms to wait after each scroll stop
--quality 3          # ffmpeg JPEG quality, lower is better

验证

捕获或修复之后：

• 至少检查此前明显出错的那个页面。
• 确认 sips -g pixelWidth -g pixelHeight full-page/*.jpg 报告出预期的宽/高尺寸。
• 确认整页图像不是大部分空白，且包含页面下部的内容。
• 确认分区裁剪坐标是连续的，且在整页图像高度处结束。
• 运行项目的常规检查，例如：

git diff --check -- articles/YYYY-MM-DD-ui-inspiration-capture/content.md articles/YYYY-MM-DD-ui-inspiration-capture/manifest.json
node scripts/check-ui-inspiration-duplicates.mjs articles/YYYY-MM-DD-ui-inspiration-capture/manifest.json
for f in articles/YYYY-MM-DD-ui-inspiration-capture/videos/*.mp4; do ffprobe -v error "$f" >/dev/null; done

备注

• 滚动视频是页面在真实滚动时能够渲染的证据，但它不能替代整页静帧证据。
• 原生 fullPage 截图仍可保存作为对比候选，但除非它在视觉上与拼接捕获相符，否则不要把它当作事实来源。
• 对于每日 UI 文章，更新 manifest 并只提交修复过的文章资产和元数据。