capture

キャプチャ

オーケストレーターによってここに案内されました。このアトムは録画のライフサイクル全体を担います。対象を起動し、インタラクションスクリプトを実行して、未加工の出力を収集します。

すでに ドライバーアトム（terminal-use、true-input、browser-use、または desktop-use）が読み込まれている必要があります。また、必要に応じて ターゲットアトム（droid-cli）も読み込まれます。このアトムは、その上に録画の手順を重ねます。

入力

このアトムを呼び出したコマンドでは、次の内容が指定されているはずです。

• ターゲット：起動する対象と対象のブランチ
• インタラクションスクリプト：実行する一連の操作
• キャプチャする内容：録画（.cast/.mp4）、スクリーンショット、テキストスナップショット、バイト列
• キーストロークのログ記録：後で重ね合わせるキーストローク TSV を出力するかどうか

録画のライフサイクル

desktop-use の場合は、その録画コントラクトに従ってください。以下のターミナルコマンドをデスクトップコマンドに置き換えないでください。通常のデスクトップスナップショットは、ドライバーの観察・操作・検証ループで行います。

1. 事前確認

録画を開始する前に、次の点を確認してください。

• すべてのセッションでターミナルサイズが統一されていること（--cols 120 --rows 36）
• ブラウザーのビューポートサイズがコンポジションのレイアウトに合っていること（下記の「ブラウザーのビューポートサイズ」を参照）。アスペクト比が一致しないと、最終動画でレターボックスが発生します
• ブランチ／ワークツリーのパスと環境変数が正しいこと
• 録画形式がドライバーに合っていること：tuistory は .cast、true-input は .mp4、agent-browser はスクリーンショット、cua-driver はウィンドウ PNG／recording.mp4
• ブランチを比較する場合、両方のセッションでターミナル／ビューポートのサイズと起動パラメーターが同一であること
• droid-dev のキャプチャでは、--repo-root が必須であること。指定しないと tctl は起動を拒否します
• カラー環境変数が設定されていること（下記を参照）

ブラウザーのビューポートサイズ

最終コンポジションでのパネルのアスペクト比はレイアウトによって異なります。出力がデフォルトの 1920×1080 で、ファクトリープリセットのマージンを使用する場合、クリップをレンダリングするウィンドウ枠付きパネルはおおよそ次のサイズになります。

レイアウト	パネルのアスペクト比	推奨するブラウザーのビューポート
single	約1760×920（≈16:9 横長）	1280×720 または 1440×810
side-by-side	パネルあたり約872×920（≈8:9、ほぼ正方形／やや縦長）	960×1000、900×1000、または 1024×1080

16:9 の横長録画をほぼ正方形の side-by-side パネルに入力すると、objectFit: "contain" によるレターボックスが発生し、上下に大きな黒帯ができて、コンテンツが細い帯状に表示されます。これを避ける方法は2つあります。

1. キャプチャ時にアスペクト比を合わせる（推奨）— 確定したレイアウトに基づき、上の表からビューポートを選びます。
2. コンポジション時にクロップを有効にする — showcase の props に "objectFit": "cover" を指定します。レターボックスの代わりにクリップの端をクロップします。関連する UI が中央にあり、クリップの端を切り落としても問題ない場合に使用します。

キャプチャ時にレイアウトがわからない場合は、デフォルトで 960×1000 を使用してください。どちらのレイアウトでも実用的です（single ではわずかに横方向のレターボックスが発生し、side-by-side では発生しません）。

TCTL=${DROID_PLUGIN_ROOT}/bin/tctl
# RUN_ID and RUN_DIR should already be set by the parent (see droid-control ground rule 5)

2. 起動と録画

重要：tuistory の仮想 PTY は、デフォルトでカラーサポートを通知しません。 Node.js アプリ（Ink/chalk）はこれを検知して、すべてのカラーエスケープコードを無効にし、録画がモノクロになります。完全な 24 ビットカラー出力を強制するには、FORCE_COLOR=3 と COLORTERM=truecolor を必ず渡してください。これらを指定しないと、agg がテーマを適用する対象がなくなり、どの agg テーマを選んでも動画が灰色がかって色あせた見た目になります。

単一ブランチ：

$TCTL launch "droid-dev" -s ${RUN_ID}-demo --backend tuistory \
  --repo-root /path/to/worktree \
  --cols 120 --rows 36 --record ${RUN_DIR}/demo.cast \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor

比較（変更前／変更後）：

$TCTL launch "droid-dev" -s ${RUN_ID}-before --backend tuistory \
  --repo-root /path/to/baseline-worktree \
  --cols 120 --rows 36 --record ${RUN_DIR}/before.cast \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor

$TCTL launch "droid-dev" -s ${RUN_ID}-after --backend tuistory \
  --repo-root /path/to/candidate-worktree \
  --cols 120 --rows 36 --record ${RUN_DIR}/after.cast \
  --env FORCE_COLOR=3 --env COLORTERM=truecolor

ブラウザー： ビューポートのサイズをコンポジションのレイアウトに合わせてください（上の表を参照）。

# side-by-side layout → near-square panel
agent-browser open <url> --viewport 960x1000
agent-browser record start ${RUN_DIR}/demo.webm

# single layout → 16:9 panel
agent-browser open <url> --viewport 1280x720
agent-browser record start ${RUN_DIR}/demo.webm

3. インタラクションスクリプトを実行する

前提知識のない視聴者向けに撮影します。あなたはオペレーターではなく、ディレクターです。

• セットアップ前に記録する — ベースラインの状態が第 1 幕です。
• 状態が変わった後は待つ — テキストが読めるよう、2〜3 秒待ちます。自然な確認のタイミングとして snapshot --trim を使います。
• ステップ間で確認する — 次に進む前に、wait または snapshot で状態を確認します。次のキーをむやみに送信しないでください。
• 確認は証拠になります。 アクション後の実際の状態を、変化が見えない場合も含めて記録します。変化のないフレームが 1 つだけでは、セッションがフリーズしたことやキー入力が失われたことの証明にはなりません。タスクの事後条件とタイミングを確認してください。

比較用の録画では、両方の分岐で同一のインタラクションを実行します。異なるのは動作だけです。両方とも同じスクリプトのステップで終了させます。compose では最も長いクリップを最後まで再生し、短いクリップは再生が終わるまで最終フレームを保持します。

4. キーストロークのログ記録

ワークフローでキーストロークのオーバーレイが必要な場合は、録画中に TSV ファイルを出力します。すべてのインタラクションはスクリプト化されているため、タイミングデータはすでにわかっています。

各キーストロークのタイムスタンプ（録画開始からの秒数）と、人が読み取れるラベルを記録します。

0.5	droid --fork
1.2	Enter
2.8	Ctrl+C
4.0	Esc

読みやすいキー名（\x03 ではなく Ctrl+C）を使用します。録画ファイルと同じ場所（例：${RUN_DIR}/keys.tsv）に保存します。タイムスタンプは録画時の秒数のままにします。compose では speed を設定する際に出力時の秒数へ変換され、クリップに後からトリミングを適用するとタイムスタンプもずれます。ログ記録の前にトリミングするか、引き継ぎ時にオフセットを記録してください。

5. 生の出力を閉じて確認する

$TCTL -s "${RUN_ID}-demo" close    # terminal session owned by this run

引き継ぐ前に、想定されるすべての出力ファイルが存在し、空でないことを確認します。

• 録画ファイル（.cast、.mp4、.webm）
• スクリーンショットファイル（.png）
• キーストローク TSV（コミットする場合）
• テキストスナップショットのログ（レポートに必要な場合）

証拠を取得するパターン

証明の種類	取得方法
機能動作	テキストスナップショット：$TCTL -s <name> snapshot --trim
視覚的なレンダリング	スクリーンショット：$TCTL -s <name> screenshot -o ${RUN_DIR}/proof-N.png
キーボードのエンコード	PTY のバイト列：${DROID_PLUGIN_ROOT}/scripts/capture-terminal-bytes.py --backend <terminal> --combo <keys>
Web/Electron	スクリーンショット：agent-browser screenshot --annotate ${RUN_DIR}/proof-N.png
ネイティブのデスクトップ GUI	正確なウィンドウまたは許可されたデスクトップの状態とレコーダーの所有者については、desktop-use に従います
実行前後の比較	両方の分岐で、同じ取得ポイントにおいて同じシーケンスを実行します

出力

これらを compose ステージに引き渡します。

## Capture outputs
- clips: [${RUN_DIR}/before.cast, ${RUN_DIR}/after.cast]      # .cast / .mp4 / .webm only
- screenshots: [${RUN_DIR}/proof-1.png, ${RUN_DIR}/proof-2.png]  # stills go to compose's screenshot path, never as clips
- keys: ${RUN_DIR}/keys.tsv (if keystroke logging was requested; raw recording seconds)
- driver: tuistory | true-input | agent-browser | cua-driver
- terminal_size: 120x36          # for tuistory / true-input
- viewport: 960x1000             # for agent-browser; report so compose knows the clip aspect

復旧

録画中にセッションが停止した場合：

$TCTL -s <name> press esc         # bail out of stuck dialog
$TCTL -s <name> snapshot --trim   # check visible state
$TCTL -s <name> close             # hard reset

この実行が所有する分離されたブラウザーの場合：agent-browser close。

desktop-use の場合、中断後に状態を再取得し、レコーダーの所有者と連携します。共有デーモンを停止したり、個人用アプリを閉じたり、不確かな入力を再送信して録画を復旧したりしないでください。不完全な成果物は診断用の証拠として保持し、納品要件を満たしていると主張せず、不完全であることを明記してください。