stitched-full-page-capture

スクロール画像をつないだ全ページキャプチャ

概要

ブラウザーの一度きりの fullPage キャプチャを過信せず、表示が安定したビューポートのスクリーンショットを使います。これは、MP4 は正しく見えても縦長のスクリーンショットがほぼ空白になることがある、Framer のページや遅延読み込み・スクロールアニメーションを使うサイトで特に重要です。

基本的なワークフロー

1. マーケットプレイスのサムネイル、カバー画像、リミックスページ、アセット URL ではなく、実際のページ URL を開きます。
2. 上から下まで一度スクロールしてページを読み込み、遅延メディアやスクロールに応じて表示されるセクションをマウントします。
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 を作成します。
• 既存のセクションの切り抜きを、つないだ画像から再生成します。
• manifest.json を更新し、fullPageCaptureMethod: "stitchedViewportScreenshots"、ビューポート、ステップ、セグメント数、修正後の切り抜き座標を記録します。

便利なオプション：

--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

検証

キャプチャまたは修復の後に、次の項目を確認します。

• 修正前に明らかに問題があったページを少なくとも 1 つ確認します。
• 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 記事では、マニフェストを更新し、修復した記事のアセットとメタデータのみをコミットします。