mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-05 17:30:50 +00:00
Miguel Angel Simon Sierra
cf7c1d7609
Scaffolded projects' npm run check now invokes the single check command instead of chaining lint, validate, and inspect (three Chrome boots become one). The CLI skill, its correctness reference, the entry skill's capability map, README/docs catalog rows, the Mintlify CLI page (new check section, deprecation banner on inspect), template CLAUDE/AGENTS (byte-identical), root CLAUDE/AGENTS, and every creation-workflow skill that taught the old sequence all point at check. snapshot keeps its standalone sections; validate/inspect stay documented as deprecated aliases with their check equivalents.
102 lines
4.1 KiB
Markdown
102 lines
4.1 KiB
Markdown
---
|
|
name: hyperframes-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
|
|
|
|
```html
|
|
<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
|
|
|
|
```js
|
|
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:
|
|
|
|
```bash
|
|
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
|