waapi

FrameVideo 向け Web Animations API

使用する場面

次の場合は WAAPI を使用します。

• 依存関係のないアニメーション — 外部ライブラリは不要です
• 軽量な DOM の動き — シンプルな変形や不透明度の変更に適しています
• ブラウザーのネイティブなパフォーマンス — ブラウザーに最適化されたキーフレームエンジンを使用します
• 生成されるアニメーション — 構造化データからアニメーションを作成します
• バンドルサイズを最小限に抑えたい場合 — 数 KB も無駄にできない場合に適しています

使用しないでください

次の場合は WAAPI を避けてください。

• 複雑なタイムラインのシーケンス制御 — gsap を使用します（タイムラインをより適切に制御できます）
• デフォルトの選択肢 — 依存関係をなくすことが特に目的でなければ、gsap を使用します
• CSS のみで実現できる装飾 — css-animations を使用します（よりシンプルです）
• 3D／WebGL — three を使用します
• デザイナーによるエクスポート — lottie を使用します

---

クイックスタート

FrameVideo での基本的な WAAPI アニメーション：

<div id="orb" class="clip orb" data-start="2" data-duration="3">Animate me</div>

<script>
  const orb = document.getElementById("orb");
  const animation = orb.animate(
    [
      { transform: "translateX(-160px) scale(0.8)", opacity: 0 },
      { transform: "translateX(0) scale(1)", opacity: 1, offset: 0.35 },
      { transform: "translateX(120px) scale(1.08)", opacity: 1 },
    ],
    {
      duration: 3000,
      delay: 2000,
      easing: "cubic-bezier(0.2, 0, 0, 1)",
      fill: "both",        // REQUIRED for FrameVideo
      iterations: 1,
    },
  );

  animation.pause();     // Pause immediately
</script>

重要なポイント：

1. シークした状態を維持するには fill: "both" を使用します
2. 作成後に animation.pause() を呼び出します
3. 有限の iterations を使用します

---

契約

• コンポジションの初期化中に、アニメーションを同期的に作成します。
• 有限の duration と iterations を指定して element.animate(...) を使用します。
• シークした状態を維持するため、fill: "both" を使用します。
• 作成後にアニメーションを一時停止するか、アダプターによる最初のシーク時の一時停止に任せます。
• レンダリングに不可欠な状態には、コールバックやプロミスを使用しないでください。

アダプターは document.getAnimations() を呼び出し、各アニメーションの currentTime を FrameVideo のミリ秒単位の時間に設定してから、一時停止します。

基本パターン

<div id="orb" class="clip orb" data-start="2" data-duration="3" data-track-index="2"></div>

<script>
  const orb = document.getElementById("orb");
  const animation = orb.animate(
    [
      { transform: "translate3d(-160px, 0, 0) scale(0.8)", opacity: 0 },
      { transform: "translate3d(0, 0, 0) scale(1)", opacity: 1, offset: 0.35 },
      { transform: "translate3d(120px, 0, 0) scale(1.08)", opacity: 1 },
    ],
    {
      duration: 3000,
      delay: 2000,
      easing: "cubic-bezier(0.2, 0, 0, 1)",
      fill: "both",
      iterations: 1,
    },
  );

  animation.pause();
</script>

スタッガーパターン

document.querySelectorAll(".token").forEach((token, index) => {
  const animation = token.animate(
    [
      { transform: "translateY(24px)", opacity: 0 },
      { transform: "translateY(0)", opacity: 1 },
    ],
    {
      duration: 620,
      delay: index * 80,
      easing: "cubic-bezier(0.2, 0, 0, 1)",
      fill: "both",
      iterations: 1,
    },
  );
  animation.pause();
});

適切な用途

• CSS キーフレームでは柔軟性が足りず、GSAP を使うほどでもない場合の、軽量な DOM の動き。
• 構造化データから生成されるアニメーション。
• キーフレーム、遅延、オフセットで表現できるシンプルなタイムライン。

避けること

• 無限の iterations。
• animation.finished に依存して、レンダリングに不可欠な DOM を変更すること。
• requestAnimationFrame、タイマー、performance.now() を使って別の時計を動かすこと。
• 変形や不透明度で動きを表現できる場合に、レイアウトプロパティをアニメーションさせること。
• クリップのローカル開始時刻が自動的に設定されると想定すること。WAAPI アダプターはドキュメントレベルのアニメーション時間をシークします。クリップのオフセットは delay でモデル化するか、表示状態を FrameVideo のタイミングで制御する要素上にアニメーションを作成してください。

検証

WAAPI コンポジションを編集した後：

npx framevideo lint      # Check structure
npx framevideo validate  # Check runtime errors
npx framevideo preview   # Scrub timeline to verify seekability

手動確認：

1. フィルモード — すべてのアニメーションで fill: "both" を使用している
2. 一時停止状態 — 作成後にアニメーションが一時停止されている
3. 有限の繰り返し回数 — 無限ループがない
4. シーク可能性 — プレビューをスクラブすると、どのフレームでもアニメーションがその状態を維持する
5. パフォーマンス — レイアウトプロパティより変形や不透明度を優先する

クレジットと参考資料

• FrameVideo アダプターのソース：packages/core/src/runtime/adapters/waapi.ts。
• MDN Web Animations API ガイド：https://developer.mozilla.org/docs/Web/API/Web_Animations_API/Using_the_Web_Animations_API
• MDN Animation.currentTime：https://developer.mozilla.org/en-US/docs/Web/API/Animation/currentTime