showrunner は何をしますか？
「このアプリのデモ動画を作って」という要求を、繰り返し可能でレビュー可能なファイルに変換します。CLI:
node ~/.showrunner/bin/showrunner.mjs（またはリンクされていればshowrunner）。リポジトリから
./install-skill.sh を一度実行してインストールします。
使用するタイミング
ユーザーがWeb UIの動画（製品デモ、機能ウォークスルー、「変更点を表示」する録画、チュートリアル）を ブラウザで開いて見られる形で欲しい場合。ネイティブデスクトップアプリや音声ナレーションが必要なものには 使用しません。
プロトコル：最初に考え、次に実行
- 録画が安全であることを確認します。 ローカル、ステージング、または使い捨てデータのみ。本番環境で実際の顧客データを録画しないでください。シナリオにトークンを決して入れないでください。
${env:NAME}を使用します。 - アプリを起動し、現実的なデータをシードします。 空の状態はデモとして貧弱です。ストーリーに必要なレコード（成功ケース、失敗ケース、進行中ケース）を作成します。
- JSONの前にストーリーボードを書きます。 4分未満のデモ：タイトルカード、8～12シーン（各8～20秒）、最後にサマリーカード。1シーン1アイデア。キャプションは視聴者が注目すべき点を説明し、マウスが何をしているかは説明しません。
probeでターゲットを見つけます。 各ページに対してshowrunner probe <url>を実行し、出力される{role,name}オブジェクトを貼り付けます。CSSよりもロールと表示名を優先します。- 検証してからドライランを実行します。
showrunner check s.json、次にshowrunner run s.json --fast --strictを実行します。ドライランは実際の長さの約4分の1です。本番撮影前に報告されるすべてのステップを修正します。 - 本番撮影を実行します（
showrunner run s.json --out out）。リアルタイムで実行されるため、バックグラウンドで開始して完了を待ちます。ツールコールを数分間ブロックしないでください。 - フレームをレビューします。
showrunner sheet out/<name>.mp4 --every 5を実行し、PNGを開きます。以下を確認します：キャプションが被写体を覆っていないか（"position": "left"を使用）、シーンがエラーになっていないか、ポップアップやツアーが漏れていないか、テーマが間違っていないか。 - 報告します。 パス、長さ、解像度、シーンリスト、および機能しなかった点を報告します。依頼がない限り、動画をコミットまたはプッシュしないでください。
実際の時間を浪費する落とし穴
| 症状 | 原因 | 修正 |
|---|---|---|
| 実行が数分間ハングする | 1つの間違ったセレクタが30秒のデフォルトタイムアウトで繰り返される | Showrunnerはデフォルトで8秒に設定され、シーンを破棄します。最初に --fast --strict を実行します |
| リンクまたはボタンが「表示されない」 | その状態でサイドバーが折りたたまれているか、メニューが閉じている | 既知のページに goto するか、ページURLを直接ターゲットにします |
| 初回実行ツアーが動画の途中でポップアップする | アプリが新規ユーザーにオンボーディングを表示する | アプリの「ツアー済み」キーを storage に設定するか、「スキップ」ボタンを dismiss にリストします |
getByText が非表示の重複に一致する | テキストが非表示ノードにも出現する | { "role": "button", "name": "/^ITEM-1\\b/" } を使用します |
| ドキュメントサイドバーの項目が何もしない | これらはリンクではなく <button> である | { "role": "button", ... } をターゲットにします |
| キャプションがドロワーやフォームを隠す | 下部中央のキャプションがサイドパネルと重なる | "position": "left" または "right" |
| シェルを終了すると撮影が停止する | バックグラウンドジョブがターミナルに結びついている | 適切なバックグラウンドタスクとして実行し、完了をポーリングします |
| 動画が空白またはタイル状になる | IDE埋め込みブラウザをキャプチャしている | Showrunner独自のヘッドレスChromeを使用し、WebViewは使用しません |
| 字幕がわずかにずれる | キューがページ作成からタイミングが取られている | レビューには問題ありません。フレーム正確ではありません |
シナリオチートシート
{
"name": "demo", "baseUrl": "http://127.0.0.1:3000", "viewport": {"width":1440,"height":900},
"storage": { "token": "${env:DEMO_TOKEN}" },
"dismiss": ["text=Skip"],
"scenes": [
{ "name": "Title", "steps": [ {"goto":"/"}, {"card":{"title":"Acme","text":"Demo","hold":3000}} ] },
{ "name": "Create", "steps": [
{"caption":{"title":"1 · Create","text":"One click.","position":"left","hold":1500}},
{"click":{"role":"button","name":"New"}},
{"type":{"into":{"label":"Name"},"text":"Launch plan"}},
{"press":"Enter"}, {"wait":1500}
]},
{ "name": "Summary", "steps": [ {"caption":null}, {"card":{"title":"Summary","items":["A","B"],"hold":4000,"keep":true}} ] }
]
}
アクション: goto click hover type press scroll wait waitFor caption card storage（任意のステップに "optional": true を追加可能）。
完全なリファレンスはリポジトリのREADMEを参照してください。
安全性
- シナリオはデータです。コード実行やシェルはありません。キャプションテキストはエスケープされます。
- 失敗したステップはそのシーンのみを破棄します。
--strictを指定すると終了コードが1になります。 - ユーザーが依頼しない限り、動画をコミット、プッシュ、共有しないでください。