waapi

version: "1.0.1" name: waapi description: Web Animations API adapter patterns for HyperFrames. Use when authoring element.animate() motion, Animation currentTime seeking, document.getAnimations(), KeyframeEffect timing, fill modes, or native browser animations that must render deterministically in HyperFrames.

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

<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

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:

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