docs: add runtime adapter skills (#572)

* docs: add runtime adapter skills * docs: address adapter skill review comments
2026-09-11 06:30:03 +00:00 · 2026-04-30 16:08:43 +02:00
parent 2045e21f70
commit 8662598a3a
15 changed files with 625 additions and 27 deletions
@@ -0,0 +1,94 @@
+---
+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
+
+```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.
+
+## 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 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