site-check

サイトチェック

アニメーションページは、作成時に使ったブラウザーのタブでは完璧に見えても、ほかの環境ではうまく表示されないことがあります。Safariではキャンバスが真っ白になり、スマートフォンでは表示が切れ、スクロール動画には継ぎ目ができ、ノート PCではフレーム時間が 40 ms になる、といった具合です。このスキルでは、実際の訪問者と同じように、複数の実ブラウザーで複数のサイズを使ってページを確認し、問題箇所を画像付きで報告します。

ツール

scripts/check.py は Playwright を通じて、ヘッドレス Chromium（実際の GPU を使用）と WebKit を操作します。

python3 scripts/check.py http://127.0.0.1:8000/ --out shots \
  --widths 1440,768,390 --browser both \
  --query "view=front" "view=aerial&light=night" \
  --scroll-steps 6 --ready "window.__ready === true"

オプション	意味
--query	URL に追加するクエリー文字列です。各文字列について、すべての幅でスクリーンショットを撮影します。すべての状態にアクセスできるよう、ページのディープリンク（?view=、?light=、?step=）を指定してください
--widths	1440（ノート PC）、768（タブレット）、390（スマートフォン。タッチと DPR 2 をエミュレート）
--browser	chromium、webkit（Safari のエンジン）、または both
--scroll-steps N	スクロール連動ページ用に、等間隔のスクロール位置 N か所でも撮影します
--ready	ページが実際に描画されると true になる JS 式
--wait	測定前に、表示が落ち着くまで待つ秒数

出力は、撮影ごとの PNG、report.json、およびすべての撮影画像にラベルを付けた sheet.jpg です。問題のある撮影画像には赤いラベルが付きます。いずれかの撮影でページエラー、リクエストの失敗または 4xx/5xx エラー、空白のキャンバス、あるいは横方向のオーバーフローが発生すると、スクリプトは 1 で終了します。各撮影では、最も広い幅でモーション低減設定のチェックも行います。

Python 3.9 以降、pip install playwright pillow、および python3 -m playwright install chromium webkit が必要です。ページは HTTP で配信してください（ES モジュールと動画のシークに必要です）。scripts/serve.py DIR --port 8000 を使ってください。これは Range リクエストに応答しますが、python3 -m http.server は応答しません。

レポートの読み方

• ms per frame は、実際の 60 フレームにわたって測定されます。16.7 未満なら 60 fps です。ノート PC の GPU を使うヘッドレス環境では、16.7 付近（vsync）になるはずなので、それを上回る場合は実際の負荷が発生しています。実行結果同士を比較してください。レポートにレンダラーとして SwiftShader または llvmpipe と記載されている場合、GPU は使われていないため、フレーム時間に意味はありません。
• calls / triangles は window.__app.renderer（three.js）から取得し、すべてのポストプロセス処理を含む 1 フレーム全体について数えます。チェックで確認できるよう、レンダラーをここに公開してください。
• ready_s は、ページが ready フラグを設定するまでにかかった時間です。高速なマシンでも 3 秒を超える場合、スマートフォンではローダーが長く表示されすぎています。
• blank canvas は、表示されているキャンバスが単色だったことを意味します。WebGL コンテキストの失敗、そのブラウザーでシェーダーをコンパイルできなかったこと、またはアセットの読み込み前にフレームが描画されたことが原因です。

次に確認すること

数値で不具合を見つけ、見た目の問題は目視で確認します。sheet.jpg を開き、各画像で次の点を確認してください。

• スマートフォンの画像で、被写体が切れている、または小さすぎる。縦向き画面では 3D シーンの垂直視野を広げ、レイアウトは縦に並べ直す必要があります。
• 背景画像が複雑で、テキストのコントラストが足りない。
• UI が被写体を覆っている、またはスマートフォンのホームインジケーターの下に入り込んでいる。
• 照明の状態によって、画面が黒つぶれする、または白飛びする。
• WebKit の画像が Chromium と異なる。色（Safari は一部の色空間ヒントを無視します）、透明度の欠落（VP9 のアルファ付き動画は Safari で再生されません）、フォントなど。

スクリプトだけでは確認できないこと

次の項目は手作業で、または低フレームレート（--fps 8）の frame-capture を使って確認します。高速かつ正確に確認できます。

• 継ぎ目とループ。 スクロール動画をすべて上下に素早くスクラブし、各接続箇所とループのつなぎ目を確認します。scroll-film/scripts/prep.py seams を使うと、接続箇所を数値で評価できます。
• ピン留めの解除。 ピン留めされた各セクションの末尾で、ページが急に飛ぶことなくスクロールを続けられる必要があります。
• 長時間のセッション。 ページを 1 分間動かしたままにし、照明プリセットを何度か切り替え、ウィンドウのサイズも数回変更します。フレーム時間が増え続けないことを確認します（ジオメトリやテクスチャのリークは、report.json のカウントが増えることでわかります）。
• ネットワーク制限下での初回読み込み。 ネットワークを制限した状態でも、最初に描画されるのがヒーロー画像のポスターまたは最初のフレームであることを確認します。ページが真っ白になってはいけません。
• 操作。 オービット、ズーム、ホバー状態、すべてのコントロールのキーボードフォーカス、スマートフォンでのタッチ操作を確認します。

環境に関する注意点

• 非表示の埋め込みブラウザープレビューやバックグラウンドタブでは、requestAnimationFrame が制限されたり、停止したりします。そこでページが「アニメーションしない」場合でも、問題がないことがあります。ヘッドレスブラウザーではこの問題は発生しません。
• python3 -m http.server は Range リクエストを無視するため、動画のシークができず、スクロールに連動する動画の再生も停止します。Range リクエストに応答するサーバーを使用してください。
• アップグレード後に Playwright のブラウザービルドが見つからない場合、スクリプトは Playwright キャッシュ内の任意の Chromium にフォールバックします。CHROME_PATH を指定すると、そちらが優先されます。

報告内容

影響を受ける訪問者数の多い順に、まず問題点を報告してください。エラーと真っ白なキャンバスを最初に、次にスマートフォンでのレイアウト、Safari での違い、パフォーマンス、最後に細部の仕上がりを報告します。コンタクトシートを添付してください。実機のスマートフォン、Windows の GPU、低速なネットワークでは確認していない場合は、その旨を明記し、確認済みであるかのように伝えないでください。