hyperframes-keyframes

プラグインのインストール： このスキルが HyperFrames プラグイン内にある場合、セットアップコマンドや最新状態の確認コマンドを実行する前に、プラグインの実行ルールに従ってください。スタンドアロンでインストールしている場合は、以下の更新手順に従ってください。

HyperFrames キーフレーム

キーフレームはポーズの契約です。目に見える状態、被写体の一貫した同一性、シークに安全なランタイム、検証済みのピクセルを定めます。

幅広いシーンのレシピには hyperframes-animation を使用してください。コマンドの全ドキュメントには hyperframes-cli を使用してください。実装方法を選ぶ場合に限り references/keyframe-patterns.md を参照し、ビジュアルスタイルの選択には使用しないでください。

クリエイターの編集範囲

キーフレームが担うのはビジュアルモーションであり、クリップの組み立てではありません。ソース範囲のハードカット、トリミング、 スプライス、並べ替えは /hyperframes-core の範囲です。保持する範囲ごとにメディア要素を1つ作成し、 data-start と data-duration で配置し、data-media-start でソース内の開始位置を指定してください。隣接する範囲はハードカットになります。クロスフェードには、異なるトラック上でクリップを重ね、ビジュアルの不透明度キーフレームを使用してください。サウンドのフェードには /hyperframes-audio を使用してください。

クリエイターのリクエスト	実現方法
パンチイン／パンチアウト	クリップ内の、タイミングに依存しないビジュアル／クロップ用ラッパーで、x／y またはパーセンテージ指定の移動とともに scale をキーフレーム化します。強いパンチにはセット／短いトゥイーン、滑らかな移動にはトゥイーンを使用します。
滑らかな複数状態のズームまたはリフレーム	1つの被写体ラッパーを維持し、セグメントごとのイージングを設定したポーズの段階列として、複数のズーム／リフレーム状態を作成します。
パン、リフレーム、またはケン・バーンズ風のカメラ移動	ラッパーの移動とスケールをアニメーション化します。ジオメトリは手動で設定するものであり、顔追跡や自動セマンティックリフレームではありません。
連続するカメラ移動	1つのシークセーフなタイムライン上で、ラベル付きの変形ビートを連結します。
マッチカットまたはウィップパン	/hyperframes-animation がビジュアルの切り替えを管理し、/hyperframes-registry がプリミティブを提供します。キーフレームによって、設定したジオメトリ、方向、速度を維持します。マッチするフレームを自動検出する機能はありません。
クロップおよびマスクによるリフレーム	内側のビジュアルラッパーに clip-path またはマスクを補間適用し、ソース時間を変更せずにクロップ／リフレームします。ポリゴンのキーフレームで、ポリゴン／マスクのトランジションを作成できます。
方向ワイプカットまたはアイリス／リビールカット	重なり合うビジュアルクリップ間でマスク／クリップ境界をアニメーション化します。切り替えの振り付けは /hyperframes-animation が管理します。
スプリットスクリーンの切り替え	両方のビジュアルクリップをコアで配置し、内側のクロップ／マスク用ラッパーと仕切りのジオメトリをキーフレーム化します。
一定のソースリタイム	/hyperframes-core が、レンダーセーフな映像とピッチを保持した音声のための正規化された data-playback-rate（0.1..10）を管理します。メディア要素全体で一定です。
ソースのスピードランプ	<video>／<audio> の data-automation にある rate レーン（クリップ秒単位の t、0.1～10 の v、対数補間）を使用します。一定の速度設定より優先されます。
フリーズ／ホールド	ビジュアルのポーズ、ソースの最終フレーム、または完成したサブコンポジションは保持できます。ソース途中の任意の位置でフリーズする機能には対応していません。静止画／派生セグメントを前処理して独立したクリップとして配置し、その後、別のソース範囲から再開してください。

映像と音声を同時に編集する場合は、/hyperframes-core と、このビジュアルモーション用スキルに加え、配置したトラックのフェード、クロスフェード、音量オートメーション、ダッキング／カーブ、エフェクトには /hyperframes-audio を読み込んでください。 視覚的なトランジションやクロップ処理は、ソースの時間的なトリムやスプライスではありません。タイムライン、クリップのタイミング、ソース範囲は /hyperframes-core が管理します。キーフレームは、クリップ内のラッパーで、画面上の切り替えやクロップだけをアニメーション化します。 コピーして使える映像と音声を組み合わせたレシピについては、/hyperframes-core → references/creator-editing-recipes.md をご覧ください。

手順

1. アニメーション化する対象、画面上の状態、最終状態、再生時間を特定します。
2. プロンプトの意図を示すために必要な、最小限の仕組みを選びます。仕組みが不明な場合にのみ、references/keyframe-patterns.md を読みます。
3. 宣言された再生時間内で、シークに安全なキーフレームを作成します。ビルドが完了してからランタイムインスタンスを登録します。document.fonts.ready 内でのビルドは問題ありません。
4. hyperframes check（lint を実行します）、hyperframes keyframes、対象を絞った --shot 1 回、および検証時点のスナップショットで確認します。
5. 検証に失敗した場合は、ソースのキーフレームを修正し、レンダリングの前に、失敗した診断のうち最小のものを再実行します。

契約

• 動かす対象を明示します。
• 意図した動きを示すために必要なポーズを、最終状態も含めて明示します。
• 非表示のヘルパー状態ではなく、画面に表示されるチャンネルをキーフレーム化します。
• 連続性が重要な場合は、オブジェクトの同一性を維持します。
• 意図した動きが置き換えまたはディゾルブの場合に限り、クロスフェードを使います。
• 読み取り可能な状態や意味のある状態は、認識できるだけの時間表示します。
• 最終フレームもアニメーションの一部であり、後片付けではありません。
• 指示がない限り、静止状態に戻しません。
• 指示がない限り、黒画面で終わらせません。
• スターターシーンを編集する場合、再デザインの依頼がない限り、レイアウト、コピー、アセット、色、最終状態を維持します。

ランタイムのルール

GSAP：

• ページ読み込み時または document.fonts.ready 内でビルドし、ビルド完了後にのみ登録します
• gsap.timeline({ paused: true }) を使います
• window.__timelines[compositionId] として登録します
• レジストリキーは data-composition-id と一致させます
• レンダリング上重要な動きには tl.play() を呼び出しません
• リピートは有限回にします

CSS キーフレーム：

• 再生時間と反復回数を有限にします
• 遅延を決定的にします
• animation-fill-mode: both を使います
• タイミングがクリップに属する場合は data-start を使います

Anime.js：

• 同期的に作成します
• autoplay: false にします
• 再生時間とループ回数を有限にします
• すべてのインスタンスを window.__hfAnime に追加します

WAAPI：

• duration を有限にします
• fill: "both" を指定します
• 決定的に構築します
• テキストには WAAPI が一覧されていません。--shot（WAAPI のシークに対応）とスナップショットで検証します

レンダリング上重要な動きには、以下を決して使用しないでください。

• Date.now()
• performance.now()
• シードを指定しない Math.random()
• ホバーやスクロールをトリガーにする処理
• タイマー
• 非同期ビルドの完了前に登録したタイムライン
• 登録されていない requestAnimationFrame
• 無限ループ

GSAP のひな形

const root = document.querySelector("[data-composition-id]");
const compositionId = root.dataset.compositionId;
const tl = gsap.timeline({ paused: true });

tl.addLabel("state-a", 0);
tl.to(".subject", {
  keyframes: [
    { x: 0, opacity: 1, duration: 0.2 },
    { x: 120, opacity: 1, duration: 0.4, ease: "power2.out" },
    { x: 100, opacity: 1, duration: 0.2, ease: "power2.inOut" },
  ],
  ease: "none",
});

window.__timelines = window.__timelines || {};
window.__timelines[compositionId] = tl;

意味のある状態にはラベルを使います。遅延を連鎖させるのではなく、位置パラメーターを使います。同じプロパティに触れる後続の from()／fromTo() トゥイーンには immediateRender: false を使います。

キーフレームの形式

• 配列キーフレーム：ステップごとに再生時間とイージングを指定するポーズの段階的な配列です。
• パーセンテージキーフレーム：1 つのトゥイーン内で正確なタイミングを指定します。
• プロパティ配列：複数の停止点での変化を簡潔に指定します。
• 各停止点に独自のイージングを指定する場合は、親要素に ease: "none" を指定します。
• すべてのセグメントで同じ動きにする場合は、easeEach を使います。

例の数値や距離、タイミングをそのままコピーしないでください。実際のコンポジションの形状と再生時間に基づいて決めます。

1 つの対象を 2 つのボックス間で移動させる場合は、1 つの連続したトランスフォームトゥイーンまたは FLIP を優先します。視聴者に明確な拍を感じさせる場合に限り、x/y/scale を複数のイージング付きキーフレームに分割します。各セグメントで速度が変わるため、ぎくしゃくした動きに見えることがあります。

チャネル

コンポジター／ビジュアル系のチャネルを優先します：x/y/z、xPercent/yPercent、scale、rotationX/Y/Z、skew、transformOrigin、svgOrigin、opacity、autoAlpha、clip-path、マスク、CSS 変数、SVG のパス／ダッシュ値、カメラのトランスフォーム、シェーダーのユニフォーム。

レイアウト／ライフサイクル系のチャネルは避けます：top/left/right/bottom、width/height、margin/padding、display、visibility、遅延 DOM 作成、対象の動きを担う補助オーバーレイ。

表示状態を変更する場合は、登録済みのシーク可能な GSAP タイムライン上で autoAlpha を使用するか、明示的な境界でゼロ時間の tl.set() を使用します。対象にするのはクリップされていない要素、またはクリップ内のラッパーのみです。.clip自体を対象にしてはいけません。生のvisibility を時間補間してはいけません。また、display` を時間補間してはいけません。

メカニズムの選択

プロンプトを実証できる、最小限のメカニズムを選びます：

必要なこと	メカニズム
同じ対象のボックスまたは階層が変わる	共有要素／FLIP
対象が見える経路を移動する	パスに沿った移動
線が伸びる、または描画される	線の描画
形状が別の形状になる	形状の補間
境界による表示が見える	クリップ、マスク、またはシェーダーのユニフォーム
多数の項目が順番に動く	スタガー／インデックス付き遅延
テキスト自体が動く	行、単語、文字、または帯状への分割
表面が曲がる、伸びる、または切り抜かれる	親／子のカウンタートランスフォーム
UI に状態がある	明示的なステートマシン
シーンに奥行きがある	DOM 3D、Three.js、または WebGL のカメラ／オブジェクトのキーフレーム

複数のメカニズムを組み合わせてもかまいませんが、それぞれがアイデアを明確にする必要があります。装飾だけでは実証になりません。

タイミング

• 予備動作は、原因や方向を明確にする場合にのみ使います。
• 加速では静止状態から始めます。
• ピークでは、メカニズムがはっきりと分かるようにします。
• フォロースルーで、エネルギーと方向を表現します。
• 対象に弾力や触感を持たせたい場合にのみ、オーバーシュートを使います。
• 一定速度のパス移動には、通常 ease: "none" が必要です。
• 離散的な UI 状態には、通常、切れのよいイーズアウトが必要です。
• 繰り返し要素には、同一のタイミングではなく、順序に沿ったオフセットが必要です。
• 最終的なロックアップは、トランジション中のポーズより長く表示します。
• 滑らかさとは、同じ対象の速度が連続していることです。
• 同じトランスフォームプロパティに値を書き込むトゥイーンは、重ねないでください。重ねる場合は、意図的に行い、動作を検証してください。
• 同じヒーローサーフェスの拡大縮小や移動と同時に、大きな clip-path／マスクの変更をアニメーションさせるのは避けてください。メインの移動が落ち着いてから、ネストしたリビールを使用します。

テキスト

行ボックス、単語間隔、読みやすさ、最終的な収まりを保ちます。テキスト内部を動かす場合は、テキストの周囲の装飾だけでなく、グリフまたはマスクされた帯を動かします。読みやすいフレームをスナップショットします。

SVG

線を伸ばす場合は DrawSVGPlugin を優先し、次に stroke-dasharray／stroke-dashoffset を使用します。形状の補間には MorphSVGPlugin を優先します。必要に応じてプリミティブをパスに変換し、複雑なシルエットはより単純なパーツに分割します。

3D

拡大縮小だけでは、奥行きは表現できません。安定した親要素にパースペクティブを適用し、transform-style: preserve-3d、z 軸方向の移動、回転、カメラ／ワールドの動き、オクルージョン、オブジェクトが交差する際のレイヤー順を使います。

奥行きの関係が分かる診断用アングルを 1 つか 2 つ使います。斜めからの検証で奥行き方向の交差が分からない場合は、z 軸、カメラ、オクルージョンを改善します。

Canvas／WebGL

決定論的な状態を通じて、カメラ位置、カメラのターゲット、オブジェクトのトランスフォーム、マテリアルの不透明度、シェーダーのユニフォーム、ポストプロセスの強度をキーフレーム化します。HyperFrames の時間からレンダリングします。マーカーのボックスでは Canvas 内部の動きを確認できないため、--ghost を使用します。

CLI による証明

npx hyperframes check
npx hyperframes keyframes .
npx hyperframes keyframes . --json
npx hyperframes keyframes . --runtime all
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --samples <n>
npx hyperframes keyframes . --selector "<selector>" --shot "<file>" --layout strip --from <t0> --to <t1>
npx hyperframes keyframes . --shot "<file>" --ghost --angle <angle>
npx hyperframes snapshot . --at <times>

実際にアニメーションする対象には <selector> を選びます。最初のフレーム、証明用ポーズ、ホールド直前の最終状態、正確な最終状態には <times> を選びます。奥行きを証明する必要がある場合に限り、<angle> を選びます。

ツール	証明できること
keyframes	対象、明示的な停止位置、パス、トレース、親子の合成モーション、CSS の停止位置、Anime の登録
--shot	ゴースト、経路の形状、時間間隔、DOM の 3D 投影、セレクターを絞った証明
--layout strip	その場でのモーション、重なり、接触、微妙なスケールや不透明度、テキストの波形
--ghost	canvas、WebGL、シェーダーのモーション、レンダリングされた 3D
snapshot --at	マスク、テキストの読みやすさ、全状態、最終ロックアップ、黒画面やリセット後の末尾

セレクターによる証明がおかしく見える場合：

1. --json を再実行します
2. 実際にアニメーションする対象を特定します
3. その対象を撮影します
4. フレーム全体をスナップショットします
5. ログより描画されたピクセルを信頼します

診断結果の読み方

flat は明示的な中間ポーズがないことを意味します。keyframes は明示的な停止位置があることを意味します。motionPath は経路があることを意味します。trace は複数ストロークの描画を意味します。composed with は子のモーションが親のモーションを継承することを意味します。

ゴーストの間隔が均等なら速度は一定です。ゴーストが密集していれば、始動が遅いか、収束していることを示します。間隔が大きければ、移動が速いことを示します。

補助セレクターのショットは証明になりません。フレーム全体が壊れている状態でのオニオンショットも証明になりません。

エラーへの対処

失敗	対処
終点のみ	中間ポーズを追加し、ピークの状態をホールドして証明し、--shot を再実行します
同一性の崩れ	要素を同一のものとして維持し、ソースと最終状態で共通のボックスを使い、代替要素とのクロスフェードを削除します
偽の 3D	z 軸やカメラの移動、オクルージョン、角度を付けた証明を追加します
最終状態が誤り	最終状態のホールドを追加し、ホールド直前の最終状態と正確な最終状態をスナップショットします
シークできないランタイム	自動再生を一時停止し、タイマーを削除して、ビルド完了後にインスタンスを登録します
読みにくいテキスト	行ボックスを維持し、移動量を減らして、最終状態のホールドを追加し、テキストのフレームをスナップショットします

完了

hyperframes check（lint を実行します）、hyperframes keyframes、対象を絞った --shot を 1 回、そしてスナップショットを実行します。最初のフレーム、証明用ポーズ、ホールド直前の最終状態、正確な最終状態、対象自身が持つモーションを確認し、デバッグ用オーバーレイがないことを確認します。