Waapi

Web Animations API for HyperFrames

HyperFrames can seek Web Animations API animations through its waapi runtime adapter. WAAPI is useful when you want native browser keyframes with JavaScript-created timing and no GSAP dependency.

Contract

• Create animations synchronously during composition initialization.
• Use element.animate(...) with finite duration and iterations.
• Use fill: "both" so seeked states persist.
• Pause animations after creation or let the adapter pause them on first seek.
• Avoid callbacks and promises for render-critical state.

The adapter calls document.getAnimations(), sets each animation's currentTime to HyperFrames time in milliseconds, then pauses it.

Basic Pattern

htmlCopy code
<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>

Stagger Pattern

jsCopy code
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();
});

Good Uses

• Lightweight DOM motion where CSS keyframes are too rigid and GSAP is unnecessary.
• Generated animations from structured data.
• Simple timelines that can be represented as keyframes, delays, and offsets.

Avoid

• Infinite iterations.
• Depending on animation.finished to mutate render-critical DOM.
• Running separate clocks with requestAnimationFrame, timers, or performance.now().
• Animating layout properties when transforms and opacity can express the motion.
• Assuming clip-local start time is automatic. WAAPI adapter seeks document-level animation time; model clip offsets with delay or create the animation on an element whose visibility is controlled by HyperFrames timing.

Validation

After editing a WAAPI composition:

bashCopy code
npx hyperframes lint
npx hyperframes validate

Credits And References

• HyperFrames adapter source: packages/core/src/runtime/adapters/waapi.ts.
• MDN Web Animations API guide: 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