| 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
