シップデモは何をしますか？

scripts/demo は Web アプリを録画し、そのコーパスを ~/demo-reels-out/<workspace>/ に書き込みます（DEMO_OUT_ROOT で親ディレクトリを、DEMO_OUT で一回の実行ディレクトリを指定します）。各シーンはナレーション付きの mp4、ポスター、Retina 静止画、そして full-tour.mp4、manifest.json、index.html を含みます。すべてローカルで動作します。エンジンはこのスキルから実行され、録画対象のアプリに何もインストールされません。

譲れない条件

これらはそれぞれ、実行時間またはユーザーの忍耐を犠牲にします。

固定されたビルドを使用し、決して開発サーバーは使わないこと。 開発サーバーのモジュールグラフはソースを編集中の担当者に属します。プライベートな場所にコピーし、バンドルを読み込んで API ベースを確認してください。リポジトリのない URL は site モードです。localhost の URL は開発サーバーであり、絶対に録画しません。
build モードでは、すべてのリクエストをインプロセスでモックし、クロックを固定すること。 コーパスは公開されますが、実際のアカウントは実際の個人のアドレスを公開します。site モードでは、両方を承知の上で放棄します。公開ページのみです。
自分自身のポートと出力ディレクトリを管理すること。 スタジオは自分が起動しなかったサーバーを採用しません。パターンで pkill しないでください。
1080p60 の動画、2倍の静止画。 これらは別々の設定です。4K 動画は、スループットが固定のピクセル/秒の予算であるため、カクつきます。
操作を行い、その結果にズームインした状態でナレーションをする。 一行につき一つの主題。主題が存在する前にナレーションをしないこと。アプリに独自のタイマー（取り消し可能なウィンドウ、トーストなど）がある場合、操作はそのタイマー内で行い、ナレーションはその後に行います。そうしないと、機能しない機能を示す動画になります。
1シーン録画したら、停止して確認する（ステップ8）。 これにより、さらに26シーン録画する前に4つの欠陥を発見しました。
毎回、PNG を確認すること。 間違ったものをフレーミングしながらパスしたシーンは失敗であり、静止画を目で見て初めて気づきます。
ユーザーが OK と言うまでは、何も最終版ではない。 言葉、フレーミング、ペース、内容、声に関する指摘はすべて、交渉ではなく再撮影です。変更して再度録画してください。ユーザーにはあなたが見えるものが見えないため、「長すぎる」「もっとズームイン」「ズームしすぎないで」はすべて完全な指示であり、シーンを2回撮影するのは安価です。

ワークフロー

与えられた情報からモードを選択すること。質問しない。 公開ホスト上の http(s) URL は site モードで、ワークスペースは ~/.shipdemo/<host>/ です。localhost またはプライベートアドレスの URL は開発サーバーです。その背後にあるリポジトリを見つけ、そのリポジトリとしてリクエストを処理します。URL がない場合は、現在いるリポジトリを意味するので、上位に移動して Web アプリ（Vite、React Router、Next、Astro、SvelteKit、または Remix の設定ファイルの横にあるビルドスクリプトを持つ package.json）を探します。ちょうど1つ見つかれば build、複数あればどれか尋ね、なければ URL またはパスを尋ねます。build モードのワークスペースで、その .origin がすでにこのリポジトリを指定している場合は、再スキャフォールドせずに再利用します。モードとワークスペースパスを一行で伝え、続行します。
scripts/doctor.sh を実行し、ユーザーに他のことを尋ねる前に自分で準備を整えること。 ユーザーはスキルをインストールしたのであって、3つのスクリプトを実行するためにインストールしたわけではありません。不足しているものを一行で伝え、インストールするものを提案してそのサイズをおおよそ伝え、ユーザーが同意したら実行します。scripts/install.sh はエンジンと Chromium（約250MB）をカバーし、パッケージマネージャーが許可すれば ffmpeg もインストールします。scripts/install-voice.sh はボイス（約350MB）用で、ユーザーが望まなければ無声での録画でも問題ありません。許可なく何もインストールせず、ユーザーにドクターレポートを解釈させないでください。スクリプトが行わないこと、そしてあなたも行うべきでないことが2つあります。それは、Node のアップグレード（どのツールが所有するかはユーザー自身が知るべき）と、sudo の実行（誰も見ていないスクリプト内のパスワードプロンプトはハングするだけ）です。どちらの場合も、スクリプトは1つのコマンドを出力するので、それをユーザーに伝えてください。
発見し、何も書き込まない。 site モード：URL を開いて読み、ページの目的、表示する価値のある3つのこと、そして指し示すのに十分安定しているものを確認します。ログインページが表示されたら停止します。ログインが必要なアプリはリポジトリから録画するため、そのリポジトリか公開 URL を尋ねてください。build モード：package.json からそのままコピーしたビルドコマンド、フレームワーク設定からの出力ディレクトリ、.env* 内の絶対 API ホスト（build.forbid に追加）、テーマブートスクリプトが読み取るキー、既存のフィクスチャ API や MSW ハンドラー、data-testid の密度、資格情報不要のルート。
scripts/scaffold.mjs <appRoot> または scripts/scaffold.mjs --site <url> を実行します。どちらもアプリには何も書き込みません。
ワークスペースの demo.config.ts を埋める。 必須フィールドがまだ不明な場合は、発見が完了していないことを意味します。config.md
build モードのみ：mock.ts と seed/ を作成する。 リポジトリに独自のデータフィクスチャがあれば再利用しますが、@playwright/test をインポートするファイルは決して使用しないでください。1回の実行で2つのコピーがあると、Playwright が拒否するエラーとなり、そのシーンだけでなくコーパス全体が失敗します。その後、DEMO_VOICE=0 scripts/demo --grep smoke を実行します。リポジトリにフィクスチャ API があればそれを再利用してください（mocking.md）。静止画を確認します。ログイン済み、シードデータ、正しいテーマ、ログインページがないこと。キャプチャ行を確認します。両方が正しくなるまで修正し、smoke 実行で証明されたものだけを demo/ui.ts に記述します。
最初にスクリプトを書く。 ワークスペースの profile.json を埋めます（template/profile.json をコピー; 製品、対象者、締めの言葉、禁止ワード）。次に、script.md に従ってすべての行を書きます。フック、ステップ、ペイオフ、クローズ。フックはバリエーション用に hooks.json にも追加します。依頼された範囲で、依頼されたものを録画すること。 名前付き機能は1シーンです。それを書き、録画し、引き渡します。「ホームページの検索を録画して」という依頼に対して10シーンの提案をしてはいけません。また、製品にもっと機能があるからといって、静かに範囲を広げないでください。リクエストが製品全体の場合にのみ、6～10シーンを提案し、それぞれにタイトルと1行の概要をツアー順に並べ、どれから録画するか尋ねます。
停止。 その1シーンを音声付きで録画します。発話数が say 呼び出しと一致していること、オーバーランがないこと、レートが維持されていることを確認します。すべての静止画を確認します。ユーザーに mp4 のパスを渡し、文章のトーン、ズームのスケール、ペース、声について尋ねます。ユーザーが答えるまで、他には何も書かないこと。
その後、--grep を使って3～4シーンずつバッチ処理します。マニフェストはマージされます。シーンの調整中は DEMO_BUILD=0 scripts/demo で再ビルドをスキップします（4分の代わりに20秒）。コーパスを生成する実行ではこれを外します。
DEMO_CAPTIONS=1 DEMO_TRACE_FRAMES=1 でフル実行し、次に scripts/check.mjs <out> を実行して <out>/index.html を開きます。キャプチャテーブル、遅いクリップ、チェックで報告されたすべてのフラグを報告します。
バリエーション。 ユーザーが指定しない限り、希望するものを尋ねます。reel、wide-phone、wide-laptop、wide-laptop-zoom、web、または all（scripts/variants.mjs --list で各説明）。次に scripts/variants.mjs <out> --only <list>。Phone プリセットはポートレート録画、laptop プリセットはランドスケープ録画を取るため、両方が必要な場合は両方のサイズを録画します。引き渡す前に、バリエーションごとに1枚のポスターを確認します。

シーン

scene('tasks', { title: 'Your to-dos, beside your calendar', blurb: '...' },
  async ({ actor, page, shot }) => {
    await actor.click(page.getByRole('radio', { name: 'Today' }));
    await actor.settle();
    await actor.spotlight(
      row('Send Sam the feedback'),
      'And this one is from yesterday that I never got to, so it is flagged.',
      { scale: 1.8, stay: true }
    );
    await shot('overdue');
    await actor.unfocus();
  });

spotlight はナレーションマークを受け取り、行の最初の単語にカメラとカーソルを移動します。被写体に応じてスケールを調整します。パネルは約1.4、行は約1.7、単一のコントロールは約2。画面全体に関する行は、単純な say でズームはしません。unfocus は動きではなくヒントです。カメラはワイドショットが必要な時だけ動くため、同じ領域に関する連続したビートはバウンドせずに滑らかに移動します。 scenes.md · narration.md

絶対にしないこと

クラウド TTS（動画はプライベートデータのもの）。Playwright の recordVideo（レート、サイズ、開始を制御できず、レコーダーが置き換えます）。4K をデフォルトにすること。音楽、イントロカード、クロスフェード。ルートクロールから生成されたシーン。シーンは目的のある振り付けです。リトライ。リトライしたシーンは別の動画です。

キャプション、チェック、バリエーション

公開を意図したものにはキャプションをオンにします（DEMO_CAPTIONS=1）。.srt、.vtt、.lines.json、および .captioned.mp4 が生成され、スクリプト自体から切り出されるため、音声と一字一句一致します。焼き込みキャプションは下部に配置され、プレーヤーコントロールより上に設定されます（DEMO_CAPTION_MARGIN で上書き可能。上部には絶対に配置しません）。

scripts/check.mjs は3つのチェックを実行します。音声（各行を文字起こしし、スクリプトと比較）、画面（0.5秒ごとにプロファイルの neverOnScreen ワードを読み取り、赤で描画されたものを検出）、フレーム（遅いギャップを検出）。不足しているツールは、インストールコマンドとともにスキップされます（scripts/install-checks.sh）。期限切れバッジなど、そこにあるべき赤色もリストアップされます。リストを読み、カウントしないでください。

scripts/variants.mjs は variants/presets.json を読み取ります。新しいバリアントは、そこに新しいエントリとして追加します。キャンバス、アプリの配置、フックとキャプションの位置、ハイライトにズームインする場合は zoom。再録画は行わず、オリジナルは決して変更されません。

その他

DEMO_VOICE_VARIANTS=am_michael,bf_emma は、同じテイクを複数の声でミックスします（<scene>.<voice>.mp4）。再撮影せずに声を試聴するためです。

キャプチャ番号を変更する前に capture.md を参照してください。ビルド、分離、マニフェストについては runs.md を参照してください。実行が停止したり、ショットがおかしい場合は troubleshooting.md を参照してください。エンジンはこのスキルから実行されるため、engine/ の修正はマシン上のすべてのプロジェクトに一度に反映されます。そこで編集すれば、伝播の必要はありません。

シップデモ