hyperframes-keyframes

HyperFrames キーフレーム

キーフレームはポーズ契約です。可視状態、連続する被写体の同一性、シーク安全なランタイム、検証済みピクセルを定義します。

広範なシーンレシピには hyperframes-animation を使用します。完全なコマンドドキュメントには hyperframes-cli を使用します。references/keyframe-patterns.md は、視覚スタイルではなく実装メカニズムを選択する場合にのみ参照してください。

クリエイター編集境界

キーフレームは視覚的なモーションを担当し、クリップアセンブリは担当しません。ソース範囲のハードカット、トリム、スプライス、並べ替えは /hyperframes-core に属します。保持する範囲ごとに1つのメディア要素を作成し、data-start と data-duration で配置し、data-media-start でソースオフセットを選択します。隣接する範囲はハードカットを形成します。クロスフェードは、異なるトラック上のオーバーラップするクリップと視覚的な不透明度キーフレームを使用します。サウンドフェードは /hyperframes-audio を使用します。

クリエイターリクエスト	真実のメカニズム
パンチイン / パンチアウト	クリップ内の非タイミングのビジュアル/クロップラッパー上で、scale と x/y またはパーセント変換を使用したキーフレーム。ハードパンチにはショート/セットトゥイーン、スムーズな移動にはトゥイーンを使用します。
スムーズなマルチステートズームまたはリフレーム	1つの被写体ラッパーを生かしたまま、複数のズーム/リフレーム状態を、セグメントごとのイージングを持つポーズラダーとして作成します。
パン、リフレーム、またはケンバーンズカメラ移動	ラッパーの平行移動とスケールをアニメーション化します。ジオメトリは作成者が指定します。これは顔追跡や自動セマンティックリフレームではありません。
連鎖カメラ移動	1つの登録済みシーク安全タイムライン上で、ラベル付けされたトランスフォームビートを連鎖させます。
マッチカットまたはホイップパン	/hyperframes-animation がビジュアルの受け渡しを担当します。/hyperframes-registry がプリミティブを提供します。キーフレームは作成者が指定したジオメトリ、方向、速度を保持します。自動マッチングフレーム検出はありません。
クロップとマスクリフレーム	内部ビジュアルラッパー上で clip-path またはマスクを補間して、ソース時間を変更せずにクロップ/リフレームします。ポリゴンキーフレームはポリゴン/マスク遷移を形成できます。
方向性ワイプカットまたはアイリス/リビールカット	オーバーラップするビジュアルクリップ間でマスク/クリップ境界をアニメーション化します。/hyperframes-animation が受け渡しの振り付けを担当します。
スプリットスクリーン受け渡し	両方のビジュアルクリップをコアが配置したまま維持し、内部のクロップ/マスクラッパーと仕切りジオメトリをキーフレーム化します。
一定ソースリタイム	/hyperframes-core が、レンダーセーフなピクチャーとピッチ保持サウンドのために正規化された data-playback-rate（0.1..5）を所有します。これはメディア要素全体で一定です。
ソーススピードランプ	未サポート：時間変化する再生速度エンベロープはありません。派生メディアアセットを事前処理し、コアを通して配置します。
フリーズ / ホールド	ビジュアルポーズ、最終ソースフレーム、または完了したサブコンポジションをホールドできます。任意のソース途中でのフリーズは未サポートです。静止画/派生セグメントを事前処理し、独自のクリップとして配置し、別のソース範囲で再開します。

画像と音声を一緒に編集する場合、/hyperframes-core、このスキル（ビジュアルモーション用）、および /hyperframes-audio（フェード、クロスフェード、ボリュームオートメーション、ダッキング/カービング、または配置済みトラックへのエフェクト用）をロードします。

ビジュアル遷移またはクロッピング処理は、時間的なソーストリムやスプライスではありません。/hyperframes-core がタイムライン、クリップタイミング、およびソース範囲を所有します。キーフレームは、それらのクリップ内のラッパー上での可視的な受け渡しまたはクロップのみをアニメーション化します。コピー可能な画像/音声結合レシピについては、/hyperframes-core → references/creator-editing-recipes.md を使用します。

手順

1. アニメーション化する被写体、可視状態、最終状態、およびランタイムを特定します。
2. プロンプトを証明する最小のメカニズムを選択します。メカニズムが不明な場合のみ references/keyframe-patterns.md を読みます。
3. 宣言されたランタイム内でシーク安全なキーフレームを作成します。同期的に構築し、ランタイムインスタンスを登録します。
4. hyperframes lint、hyperframes check、hyperframes keyframes、1つのフォーカスされた --shot、および証明時点でのスナップショットで検証します。
5. 証明が失敗した場合、ソースキーフレームを修正し、レンダリング前に最小の失敗診断を再実行します。

契約

• 動く被写体に名前を付けます。
• 意図された動き（最終状態を含む）を証明するために必要なポーズに名前を付けます。
• 可視チャンネルのみをキーフレーム化し、隠れたヘルパー状態はキーフレーム化しません。
• 連続性が重要な場合は、オブジェクトの同一性を保持します。
• 意図された動きが置換またはディゾルブである場合にのみクロスフェードします。
• 読み取り可能な状態または意味のある状態を、見るのに十分な時間だけ保持します。
• 最終フレームはアニメーションの一部であり、クリーンアップではありません。
• 要求がない限り、静止状態にリセットしないでください。
• 要求がない限り、黒で終了しないでください。
• スターターシーンを編集する場合、再設計を要求されない限り、レイアウト、コピー、アセット、色、および最終状態を保持します。

ランタイムルール

GSAP:

• ページ読み込み時に同期的に構築します
• 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時間からレンダリングします。マーカーボックスは内部のキャンバスモーションを見ることができないため、--ghost を使用します。

CLI 証明

npx hyperframes lint
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	キャンバス、WebGL、シェーダーモーション、レンダリングされた3D
snapshot --at	マスク、テキスト可読性、フル状態、最終ロックアップ、黒/リセットテール

セレクター証明が間違って見える場合:

1. --json を再実行します
2. 実際のアニメーションターゲットを見つけます
3. そのターゲットを撮影します
4. フルフレームをスナップショットします
5. ログよりもペイントされたピクセルを信頼します

診断読み取り

flat は明示的な中間ポーズがないことを意味します。keyframes は明示的な停止が存在することを意味します。`m

…

[翻訳のために切り詰められました]