ui-recording-timeline

UI 記録タイムライン

index.html と動画を含む、自己完結型のフォルダーを生成します。動画はウィンドウいっぱいに表示されます。その下には、1 行のキャプションと細いタイムライン（フェーズごとの色、描画ティック、ホバー時のサムネイル、スクラブ操作）があります。各描画時に変更領域が動画上で点滅し、l キーを押すと描画リストのドロワーが開きます。

必要なものはすべてこのスキルのディレクトリにあります。

• scripts/timeline.py：すべての手順を実行する単一の CLI です。依存関係はインラインで宣言されており、uv run がインストールします。
• assets/template.html：ページです。build がデータを挿入します。

要件：ffmpeg／ffprobe と uv が PATH にあること。Chrome または Chromium が必要なのは preview の実行時のみです。

以下では、T は uv run <this skill dir>/scripts/timeline.py を意味します。変数ではなくシェル関数として定義してください。zsh では変数の単語分割が行われないためです。スキルのディレクトリには絶対パスを使用してください。

T(){ uv run "/abs/path/to/ui-recording-timeline/scripts/timeline.py" "$@"; }

WD は出力フォルダーです。ユーザーのプロジェクトに調査資料や関連資料の保存場所に関する規約がある場合は、それに従ってください。ない場合は、動画と同じ場所に <video-stem>-timeline/ として WD を置きます。

ワークフロー

1. 抽出して描画候補を見つける

T extract /path/to/recording.mp4 WD     # copies video, writes meta.json (frame timestamps; VFR is fine)
T candidates WD                         # table of frames that differ from the previous frame

各行には、フレームインデックス、時刻、変化率、種類（change／full／cursor?）、正規化された bbox が表示されます。カーソルのような小さな変化は非表示です（表示するには --all を使用します）。

2. フレームを確認して、何を描画として扱うか決める

表だけを見て判定しないでください。フレームを確認してください。

T sheet WD --frames 0,4,14,26,61 --name overview          # labelled contact sheets -> WD/sheets/*.jpg
T sheet WD --frames 18,19 --crop 0,0,0.25,0.15 --name zoom # zoom into a small change

画像ビューアーでシート画像を読み込みます。各候補の直前のフレームも必ず含め、何が変わったかを確認してください。

描画の選び方：

• 描画にあたるもの： 目に見えるコンテンツまたはレイアウトの変化です。スケルトンの表示、スケルトンから実際のコンテンツへの置き換わり、空白ページへの移動、新しいページの最初の描画、ラベルやボタン状態の変化、読み込み状態を示すブラウザーの UI（停止を示す X が再読み込みアイコンに置き換わるなど）が該当します。
• 描画にあたらないもの： カーソルの移動、ホバー時のハイライト、スピナーの回転、キャレットの点滅、すでに表示されているスケルトン上の滑らかなシマー効果です。bbox を確認してください。連続するフレームで移動する小さな領域はカーソルです。
• アニメーション： 複数フレームにわたるアニメーション（チェックマークのアニメーションやパネルのスライドインなど）は、最終フレームの 1 つの描画として扱います。差分がアニメーション全体を比較するように、アニメーション開始前のフレームを "base": <frame before the animation started> に指定します。
• 小さな描画： ラベル、ボタン状態、ブラウザーの UI など、その場で起きる小さな更新には minor: true を設定します。ティックが短くなり、テキストの色も控えめになります。
• フェーズ： 画面または URL ごとに描画をフェーズにまとめます（例：アプリシェル、SSO ゲート、IdP、空白のリダイレクト、サインイン済みアプリ、アイドル状態）。通常、フレーム内のアドレスバーで確認できます。フェーズは、記録の 0 秒から終了まで途切れなくカバーする必要があります。
• アイドルフェーズ： 画面上に変化がない区間には "idle": true を設定します。最後の描画後の末尾は必ず含めます。同じ画面のまま長時間待機する区間も含められます。アイドルフェーズはパレットの色ではなく、ハッチング付きのグレーで表示されます。鮮やかな色では動きがあるように見え、濃いグレーではバーが途中で終わっているように見えるためです。アイドル状態の末尾を切り詰めないでください。実際の時間であり、動画にも含まれます。
• 指標： 最初の 2 つはキャプションに表示されるため、特に重要なものを先に並べてください（例：「メインコンテンツ」と「視覚的な読み込み完了」）。IdP 上の時間や空白時間の合計など、それ以外の指標はドロワーに表示します。
• 注意点： t=0 は記録の最初のフレームであり、ナビゲーション開始時刻ではありません。最初のフレームにすでに UI が表示されている場合は、notes に記載してください。

3. WD/paints.json を作成する

{
  "title": "vercel.com/vercel-labs with an SSO redirect",
  "notes": "Recording starts mid-navigation: the dashboard shell is already on screen at t=0.",
  "metrics": [
    {"value": "6.50 s", "label": "main content"},
    {"value": "8.37 s", "label": "visually complete"},
    {"value": "2.53 s", "label": "on Okta"}
  ],
  "phases": [
    {"start": 0.0,   "end": 0.802,  "name": "Dashboard (unauthenticated)"},
    {"start": 0.802, "end": 2.002,  "name": "Vercel SSO gate"},
    {"start": 2.002, "end": 8.468,  "name": "Okta and back"},
    {"start": 8.468, "end": 10.935, "name": "Idle", "idle": true}
  ],
  "paints": [
    {"frame": 0,  "label": "Dashboard shell: sidebar nav and header skeleton (recording start)"},
    {"frame": 4,  "label": "Projects and usage skeleton cards"},
    {"frame": 19, "label": "Team switcher changes to \"Select Team\"", "minor": true},
    {"frame": 87, "label": "Okta Verify check badge (animates 2.668 to 3.068 s)", "minor": true, "base": 74}
  ]
}

• frame は candidates にあるデコード済みのフレームインデックスです。時刻はフレームの実際のタイムスタンプから取得されるため、手計算しないでください。フェーズ境界は秒単位です。各フェーズの開始には、そのフェーズの描画の t を使用し、最後のフェーズの終了には extract の再生時間を使用します。
• ラベルは短く、具体的にしてください。何が表示されたか、変化したか、消えたかを示し、画面上のテキストを引用してください。
• フェーズごとに "color": "#hex" を任意で指定できます。デフォルトではパレットから色が選ばれます。

4. 変更領域を計算して確認する

T regions WD     # move-aware diff for every paint -> regions.json
T check WD       # boxes drawn on every paint frame -> WD/sheets/check-*.jpg

すべてのチェックシートを確認します。ピンクは描画、青は移動、細いグレーの線はコンテンツの移動元を示します。差分の仕組みの詳細は compute_regions を参照してください。

• レイアウトが変化した図形は、単語、アイコン、入力欄、カードなど、要素全体に合わせて調整されます。かすかな光の揺らぎがある端も含まれます。
• 前のフレームの近くに同じ図形があり、元の位置が空いている場合は、移動として扱われます。たとえば、サイドバーの項目が挿入されると、その下の行が下にスライドします。同じオフセットの移動はまとめられます。
• 同一の山形アイコンや行など、繰り返し表示される図形が曖昧な場合、同じフレームですでに見つかったオフセットと揃っていれば、移動として扱われます。
• カーソルは大きさから推測するのではなく、学習して識別します。矢印、手、テキストカーソルなどのカーソルスプライトは、小さな要素だけが単独で動いた candidates フレームから取得します。既知のスプライトを含むボックスだけが、どちらかのフレームで除外されます。ロゴ、アイコン、ツールバーボタンなど、小さくても実際に描画されたものは残ります。そのため、regions の前に candidates を実行してください。
• それ以外はすべて描画として扱われます。新しい背景のような、単色の塗りつぶしも含まれます。

ボックスが不自然に見える場合：

• まず、描画の選択を確認してください。通常、原因は誤った base、または描画フレーム内のホバー状態です。
• その後で、compute_regions の冒頭にある定数の調整を検討してください。定数は幅 1710 px の画面に合わせて調整され、自動でスケーリングされます。対象は EDGE／CHG のしきい値、SEARCH の距離、カーソルのサイズ、拡張許容値です。

5. ビルド、プレビュー、表示

T build WD                    # paint thumbnails + WD/index.html
T preview WD --t 6.502        # headless screenshot with boxes frozen -> WD/preview.png
open WD/index.html

preview.png を確認し、レイアウトとオーバーレイが動画に重なっている位置を確かめます。paints.json または regions.json を変更した場合は、build を再実行します。描画フレームまたはベースを変更した場合に限り、regions を再実行します。

ページの使い方

• キー操作：←／→ で描画間を移動、space で再生、d で変更箇所の点滅を切り替え、l で描画リストのドロワーを開き、f で全画面表示にします。動画をクリックすると再生または一時停止します。タイムラインをクリックまたはドラッグすると再生位置を移動でき、ホバーするとサムネイルが表示されます。
• URL オプション：#t=6.502 で指定した時刻に直接移動し、?hold でボックスを固定します。スクリーンショットを撮る際に便利です。
• 「Shown」は、次の描画までの表示時間です。
• フォルダーはそのまま別の場所に移動できます：index.html、recording.*、paints/。meta.json、paints.json、regions.json、sheets/ は入力およびデバッグ出力なので、そのまま残しておいて問題ありません。

結果の報告

各フェーズ、主要な指標、特筆すべき点（空白画面、差分で移動として表示されたレイアウトの変化、長い待ち時間など）をまとめてください。index.html のパスを記載します。t=0 の注意点に触れ、時刻の精度が ±1 フレームであることも明記してください。