textual-ui-developer

Textual UI 開発者

このスキルを使って、再現が不安定になることや API コストを最小限に抑えながら、MassGen Textual UI を改善します。

このスキルを使う場面

• タイムラインの描画や順序に関する問題をデバッグする必要がある場合。
• 実際の Textual シェルでレイアウトやスタイルの変更を検証する必要がある場合。
• TUI の回帰テスト（スナップショット／ゴールデン／トランスクリプト）を更新または追加する必要がある場合。
• events.jsonl から UI の動作を決定的に再現する必要がある場合。

デフォルトの戦略

ライブモデルの実行よりも、決定的なワークフローを優先します。

1. 記録済み／合成イベント（events.jsonl）から再現し、API 呼び出しを行わないようにします。
2. --tui-real を使って実際のシェルで動作を確認します。
3. 調査結果をテスト（ユニット、トランスクリプトのゴールデン、スナップショット）に反映します。
4. 必要な場合に限り、ライブの massgen --display textual または --textual-serve を使います。

クイックコマンド

# Full frontend/TUI test suite
uv run pytest massgen/tests/frontend -q

# Timeline transcript goldens
uv run pytest massgen/tests/frontend/test_timeline_transcript_golden.py -q
UPDATE_GOLDENS=1 uv run pytest massgen/tests/frontend/test_timeline_transcript_golden.py -q

# Snapshot scaffold tests
uv run pytest massgen/tests/frontend/test_timeline_snapshot_scaffold.py -q
uv run pytest massgen/tests/frontend/test_timeline_snapshot_scaffold.py --snapshot-update -q
uv run pytest massgen/tests/frontend/test_timeline_snapshot_scaffold.py -q --snapshot-report snapshot_report.html
uv run python scripts/render_snapshot_svgs.py --real-tui-only

# Event replay (no API cost)
uv run python scripts/dump_timeline_from_events.py /path/to/events.jsonl [agent_id]
uv run python scripts/dump_timeline_from_events.py --tui /path/to/events.jsonl [agent_id]
uv run python scripts/dump_timeline_from_events.py --tui-real /path/to/events.jsonl [agent_id]

# Example synthetic fixture
uv run python scripts/dump_timeline_from_events.py --tui-real massgen/tests/frontend/fixtures/synthetic_tui_events.jsonl agent_a

ワークフロー

1) イベントのリプレイで再現する（API コストなし）

まず、トランスクリプトのリプレイでタイムラインの意味をすばやく検証します。

uv run python scripts/dump_timeline_from_events.py /path/to/events.jsonl agent_a

次に、視覚的に確認します。

# Lightweight timeline-focused view
uv run python scripts/dump_timeline_from_events.py --tui /path/to/events.jsonl agent_a

# Full runtime TextualApp shell
uv run python scripts/dump_timeline_from_events.py --tui-real /path/to/events.jsonl agent_a

実際のリプレイ速度を調整する場合は、オプションで次を使います。

MASSGEN_TUI_REPLAY_SPEED=8 uv run python scripts/dump_timeline_from_events.py --tui-real /path/to/events.jsonl agent_a

q でリプレイを終了します。

2) 調査結果をテストに反映する

バグを捉えられる最も限定的なレイヤーを選びます。

• ユニットロジック：test_tool_batch_tracker.py、test_content_processor.py、ヘルパー。
• トランスクリプト／ゴールデンの動作：test_timeline_transcript_golden.py + massgen/tests/frontend/golden/。
• ウィジェット／シェルのスナップショット：test_timeline_snapshot_scaffold.py + massgen/tests/frontend/__snapshots__/。
• リプレイスクリプトの動作：test_dump_timeline_from_events_script.py。

最終表示に焦点を当てた反復ループ

最終回答の視覚化に特化して反復する場合：

1. test_timeline_section_widget.py のユニットテストで、ヘッダーの意味（勝者の行、同点判定マーカー、投票行の書式）を検証します。
2. 意図した UI の変更がある場合に限り、最終表示のスナップショットだけを再生成します。
   • uv run pytest massgen/tests/frontend/test_timeline_snapshot_scaffold.py --snapshot-update -q
3. API コストをかけずに、実行時のシェル表示を確認します。
   • uv run python scripts/dump_timeline_from_events.py --tui-real massgen/tests/frontend/fixtures/synthetic_tui_events.jsonl agent_a
4. 最終確定前に、フロントエンドのテストスイート全体を実行します。
   • uv run pytest massgen/tests/frontend -q

3) スナップショットのワークフロー

スナップショットテストが一致しない場合：

1. snapshot_report.html を開きます。
2. Show difference トグルの表示を確認します。
   • ON = 差分をブレンド表示（紫や黒に見えることがあります）。
   • OFF = 現在のスナップショットと過去のスナップショットをそのまま表示します。
3. 変更が意図したものなら、--snapshot-update を使って再生成します。
4. フロントエンドのテストスイートを再実行し、安定性を確認します。

3.1) 必須のスクリーンショット確認

視覚／UI タスクでは、テストの合否だけに頼らないでください。最終確定前に、スクリーンショットを直接確認する必要があります。

1. snapshot_report.html のスナップショット画像（現在と過去）を確認します。
2. まず Show difference を OFF にしてそのままの描画を検証し、その後、必要に応じて ON にしてピクセル単位の差異を確認します。
3. チャット／タスクのコンテキストでスクリーンショットが提供されている場合は、その画像を直接確認し、期待される実行時の表示と比較します。
4. 使用しているビューアーで .svg を開けない場合は、ブラウザーエンジンでレンダリングします。
   • npx playwright screenshot "file:///ABS/PATH/to/snapshot.svg" /tmp/snapshot.png
   • すべて（または実際の TUI のみ）を一括処理：uv run python scripts/render_snapshot_svgs.py [--real-tui-only]
   • Textual のスナップショットでは、誤ったアーティファクトを避けるため、ImageMagick による変換よりこちらを優先します。
5. テストに合格していても、レンダリングされたスナップショットと実際の TUI に期待される表示との不一致があれば、必ず指摘します。
6. スクリーンショットを明示的に確認した後に限り、「視覚的な変更を検証済み」と結論づけます。

4) ライブでの視覚的検証（任意）

決定的なチェックに合格した後に限り、ライブ実行を使います。

# Native terminal TUI
uv run massgen --display textual

# Browser-hosted Textual
uv run massgen --textual-serve

主要なファイル

• scripts/dump_timeline_from_events.py：テキスト再生、--tui、--tui-real モード。
• massgen/frontend/displays/textual_terminal_display.py：TextualApp、シェルのレイアウト、実行時のイベントルーティング。
• massgen/frontend/displays/tui_event_pipeline.py：タイムラインイベントアダプターとフィルタリングロジック。
• massgen/frontend/displays/timeline_event_recorder.py：決定論的なテキストトランスクリプトレコーダー。
• massgen/tests/frontend/test_timeline_snapshot_scaffold.py：スナップショット用スキャフォールド（ウィジェットと実際のシェル状態）。
• massgen/tests/frontend/test_timeline_transcript_golden.py：トランスクリプトのゴールデン回帰テスト。
• docs/modules/testing.md：標準のテストコマンドと同等性に関する注記。

完了条件

TUI の変更は、次の条件を満たした時点で完了です。

1. 関連する決定論的テストを、先に追加または更新している。
2. uv run pytest massgen/tests/frontend -q が成功する。
3. スナップショット／ゴールデンの更新が意図的なものであり、レビューされている。
4. --tui-real で再生し、対象のシナリオについて期待される実際のシェルの動作を確認している。