/hyperframes-animation

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.

Composition Duration

The render engine needs the composition's total length to know how many frames to capture. GSAP timelines report duration automatically; a WAAPI-only composition has no timeline object, so the runtime infers duration from every animation's effect.getComputedTiming().endTime (offset by when the animation was created relative to composition start). data-duration on the root element is optional as long as every element.animate() call uses finite duration and iterations — which the contract above already requires.

Infinite iterations has no finite endTime, so it can't be auto-inferred — that's one more reason to avoid it (see Avoid below). If you must use it, add data-duration="<seconds>" to the root [data-composition-id] element or npx hyperframes lint will error (root_composition_missing_duration_source).

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 check

Credits And References

• HyperFrames adapter source: packages/core/src/runtime/adapters/waapi.ts.
• Duration auto-inference: packages/core/src/runtime/init.ts (resolveAdapterDurationFloorSeconds), getInferredDurationSeconds in the adapter above.
• 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