hyperframes-cli

HyperFrames CLI

プロジェクトの指示でローカルラッパーが指定されていない限り、すべての操作は npx hyperframes で実行します。ローカルラッパーの指示には必ず従ってください。Node.js >= 22 と FFmpeg が必要です。

ワークフロー

1. ひな形を作成 — npx hyperframes init my-video（または URL から capture）。init はインストール済みのスキルも GitHub 上の最新バージョンと照合し、古くなっているものがあればグローバルセットを更新します。--skip-skills フラグは現在機能しません（skills.sh レジストリが追いつくまでの一時的な措置です）。そのため、すべての init でこのチェックが実行され、最新のスキルが取得されます。
2. 作成 — HTML コンポジションを作成します（hyperframes-core スキルを参照）。
3. Lint — npx hyperframes lint
4. 検証 — npx hyperframes validate（実行時エラーとコントラスト）
5. 視覚的に確認 — npx hyperframes inspect
6. プレビュー — npx hyperframes preview で Studio が開きます。Studio はタイムラインエディターで、ユーザーは動画を見るだけでなく、手動で自由に編集できます。Studio で確認してから、レンダリングの前にユーザーに確認してください。
7. レンダリング — 用途に応じて選びます。
   • 反復作業：npx hyperframes render --quality draft
   • 納品：npx hyperframes render --quality high --output out.mp4
   • CI／ホスト間の再現：npx hyperframes render --docker --strict --output out.mp4
   • クラウド（長尺／大容量）：npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait（下記の Lambda を参照）

プレビューの前に lint、validate、inspect を実行してください。lint は data-composition-id の不足、トラックの重複、タイムラインの未登録を検出します。validate はヘッドレス Chrome でコンポジションを読み込み、実行時のコンソールエラーと WCAG コントラストの問題を報告します。inspect はタイムライン内をシークし、テキストが吹き出し／コンテナからはみ出したり、キャンバスの外に出たりしていないかを報告します。また、*.motion.json サイドカーがある場合は、同じシーク済みタイムラインを使ってモーションの意図（シーク中に再生される入場アニメーション、スタガーの順序、フレーム内への収まり、ライブ性）を検証します。

モーションの多い作業では、スナップショットを使った反復作業と *.motion.json サイドカーを推奨します。手順とモーション検証の仕様については、references/lint-validate-inspect.md を参照してください。

エージェントの規約

すべてのコマンドに適用される共通ルール：

• --json は render、preview、play 以外のすべてのコマンドで使用できます。 対応コマンドをエージェント／CI から呼び出す場合は必ず使用してください。出力には _meta エンベロープ（CLI バージョン、利用可能な最新バージョン、更新に関するアドバイス）が含まれます。render は標準出力と終了コードのみでステータスを報告するため、下記のレンダリング後チェックで成功を確認してください。preview／play はサーバーなので、JSON は出力されません。
• doctor --json は環境に問題があっても常に終了コード 0 を返します。 ペイロードの ok フィールドで判定してください：npx hyperframes doctor --json | jq -e '.ok' > /dev/null。これにより、CLI のリリースによるパイプラインへの影響を防げます。
• 非 TTY モードは自動検出されます。 stdout が TTY でない場合（CI、エージェント、パイプ経由の出力）、CLI は自動的に非対話モードに切り替わり、その場合 init には --example が必須です。TTY 環境でもこのモードを強制するには、--non-interactive を指定してください。
• CI でのレンダリング判定：--strict は lint エラーで失敗し、--strict-all は警告でも失敗し、--strict-variables は宣言されていない --variables のキーで失敗します。
• --json 内のパスはマスキングされます — $HOME はリテラルの $HOME になり、出力をバグ報告やエージェントのコンテキストに安全に貼り付けられます。
• レンダリングにはユーザーの承認が必要です。 チェックに合格しても、自動でレンダリングしてはいけません。preview で一旦止め、Studio で動画を編集できることをユーザーに伝え、承認を得てからレンダリングしてください。
• レンダリング後の検証。 render が終了コード 0 を返したら、成功を報告する前に出力ファイルが存在し、妥当なサイズであることを確認してください：[ -s "$OUTPUT" ] || echo "render produced no output"。成功時、CLI は ◇ <path> と表示します。長尺のレンダリングでは、ffprobe -i "$OUTPUT" -show_format -v error で長さも妥当か確認してください。

ルーティング

やりたいこと…	参照先
プロジェクトをスキャフォールドする（init、capture、skills）	references/init-and-scaffold.md
正しさを確認する（lint、validate、inspect、snapshot）	references/lint-validate-inspect.md
プレビューまたはレンダリングする（preview、play、render、publish）	references/preview-render.md
環境を診断する（doctor、browser）	references/doctor-browser.md
AWS Lambda でクラウドレンダリングする（lambda deploy / sites / render / progress / destroy / policies）	references/lambda.md
その他すべて（info、upgrade、compositions、docs、benchmark、telemetry、アセットの前処理）	references/upgrade-info-misc.md

スキル間の引き継ぎ

• Tailwind プロジェクト（init --tailwind）→ クラスやテーマトークンを編集する前に、hyperframes-core（Tailwind リファレンス）を使用してください。
• レジストリのブロック／コンポーネント（hyperframes add、hyperframes catalog）→ インストール先、サブコンポジションの接続、スニペットのマージについては、hyperframes-registry を使用してください。
• アセットの前処理（tts、transcribe、remove-background）→ 音声の選択、Whisper モデルのルール、字幕、TTS から字幕への処理については、hyperframes-media を使用してください。
• パラメーター化されたレンダリング（--variables）→ <html> の data-composition-variables で宣言します。スキーマ全体については、hyperframes-core を参照してください。

Lambda（クラウドレンダリング）

hyperframes lambda は、分散レンダリングを AWS Lambda にデプロイし、ノート PC または CI からレンダリングを実行します。最初から最後まで、3 つのコマンドで完了します。

npx hyperframes lambda deploy                                             # provision SAM stack (Lambda + Step Functions + S3)
npx hyperframes lambda render ./my-project --width 1920 --height 1080 --wait
npx hyperframes lambda destroy                                            # tear down (S3 bucket is retained)

1 台のホストではレンダリングに時間がかかりすぎる、またはサイズが大きすぎる場合（数分間の動画、4K、大規模な並列バッチ）で、AWS 認証情報を設定済みの場合に Lambda を使用してください。開発ループでの反復作業には、ローカルの render を使用してください。

前提条件、6 つのサブコマンド（deploy、sites create、render、progress、destroy、policies）、IAM ポリシーの検証、状態ファイル、コストとクリーンアップのルールについては、references/lambda.md を参照してください。

最低限の完了基準

静的ゲート

npx hyperframes lint
npx hyperframes validate

レイアウトに影響する作業では inspect を追加し、CI では render --strict を使用して、lint エラーがあれば失敗するようにしてください。

ビジュアルスモークテスト — サブコンポジションを使用するプロジェクトでは必須

lint／validate／inspect は各コンポジションを個別に評価します。index.html を読み込んで data-composition-src 経由でサブコンポジションをマウントすることはないため、ファイルをまたぐマウントの失敗は検出できません（hyperframes-core → references/sub-compositions.md の「よくある落とし穴」を参照）。この問題を検出できるのは、実際に index.html を読み込み、タイムラインを探すゲートだけです。

hyperframes snapshot を使用してください。render と同じ方法でプロジェクトを読み込むため（同じマウント経路をテストできます）、指定したタイムスタンプだけをキャプチャします。フルレンダリングではなく、数秒で完了します。

# Capture one frame at the midpoint of every sub-composition.
# Midpoints = data-start + data-duration/2 for each host slot in index.html.
npx hyperframes snapshot --at <t1>,<t2>,<t3>,...

# Or, if you don't need per-scene targeting, an evenly-spaced sample:
npx hyperframes snapshot --frames 9

出力は snapshots/frame-NN-at-Xs.png に保存されます。各フレームをシーンプランと見比べて確認してください。

フレームごとの危険信号（それぞれ、静的ゲートでは検出できない特定の障害モードに対応します）：

表示されるもの	根本原因
テキストが左上に小さく、スタイルなしで表示される	<style> ブロックが <template> の外側、<head> 内に残っている（落とし穴 1）— ライブ DOM に CSS が届いていない
SVG／アイコン要素がキャンバスサイズにまで拡大されている	上記と同じ — 幅／高さの制約が適用されていない
シーンのヒーロー要素がまったく表示されず、背景とウォーターマークだけが見える	ホスト ID ≠ テンプレート ID（落とし穴 2）— タイムラインが実行されず、初期状態のフレームがキャプチャされた
スナップショットコマンドに Sub-composition timelines not registered after 45000ms と記録される	落とし穴 2 — 直接的な確認

目視確認後は snapshots/ を削除できます。ユーザー向けの最終レンダリングは、npx hyperframes render による別工程です。