From 2bb4e4596694320fbfad63f007c6babae47dc021 Mon Sep 17 00:00:00 2001
From: Kiyeon Jeon <kiyeon.jeon.21@gmail.com>
Date: Mon, 1 Jun 2026 02:38:11 +0900
Subject: [PATCH] docs(skills): align Lottie guidance with runtime adapter

---
 skills/hyperframes/references/techniques.md   | 45 +++++++------------
 .../references/api-map.md                     | 10 ++---
 .../references/lottie.md                      | 10 +++--
 3 files changed, 26 insertions(+), 39 deletions(-)

diff --git a/skills/hyperframes/references/techniques.md b/skills/hyperframes/references/techniques.md
index 5102cf703..80bc13779 100644
--- a/skills/hyperframes/references/techniques.md
+++ b/skills/hyperframes/references/techniques.md
@@ -181,38 +181,23 @@ The slide distance DECAYS per word (80→12px) — mimics a camera settling.
 Vector animations that play inside a composition. Use for logos, character animations, icons.
 
 ```html
-<!-- The web-component package is `@lottiefiles/dotlottie-wc` (the SDK
-     `@lottiefiles/dotlottie-web` does NOT expose a custom element).
-     The element tag is <dotlottie-wc>. -->
-<script
-  src="https://cdn.jsdelivr.net/npm/@lottiefiles/dotlottie-wc/dist/dotlottie-wc.js"
-  type="module"
-></script>
-<dotlottie-wc
-  class="lottie"
-  src="capture/assets/lottie/animation-0.json"
-  autoplay
-  loop
-  speed="1.5"
-  style="width:500px;height:500px;"
->
-</dotlottie-wc>
+<div id="anim" class="lottie"></div>
+<script src="https://cdnjs.cloudflare.com/ajax/libs/bodymovin/5.12.2/lottie.min.js"></script>
 <script>
-  gsap.set(".lottie", { scale: 0.3, opacity: 0 });
-  tl.to(".lottie", { scale: 1, opacity: 1, duration: 0.35, ease: "back.out(1.6)" }, 0.2);
-</script>
-```
-
-Or use lottie-web for more control:
+  window.__hfLottie = window.__hfLottie || [];
+
+  const anim = lottie.loadAnimation({
+    container: document.getElementById("anim"),
+    renderer: "svg",
+    loop: false,
+    autoplay: false,
+    path: "capture/assets/lottie/animation-0.json",
+  });
+  window.__hfLottie.push(anim);
 
-```javascript
-var anim = lottie.loadAnimation({
-  container: document.getElementById("anim"),
-  renderer: "svg",
-  loop: false,
-  autoplay: false,
-  path: "capture/assets/lottie/animation-0.json",
-});
+  gsap.set("#anim", { scale: 0.3, opacity: 0 });
+  tl.to("#anim", { scale: 1, opacity: 1, duration: 0.35, ease: "back.out(1.6)" }, 0.2);
+</script>
 ```
 
 ---
diff --git a/skills/remotion-to-hyperframes/references/api-map.md b/skills/remotion-to-hyperframes/references/api-map.md
index 906d7957e..23481216e 100644
--- a/skills/remotion-to-hyperframes/references/api-map.md
+++ b/skills/remotion-to-hyperframes/references/api-map.md
@@ -79,11 +79,11 @@ See [transitions.md](transitions.md).
 
 See [lottie.md](lottie.md).
 
-| Remotion                        | HyperFrames                                                                                               |
-| ------------------------------- | --------------------------------------------------------------------------------------------------------- |
-| `<Lottie animationData={data}>` | `<div id="lottie-N">` + `<script>lottie.loadAnimation(...).then(a => window.__hfLottie.push(a))</script>` |
-| `loop` / `playbackRate` props   | translate to `loop` / lottie playback options; HF adapter seeks via `goToAndStop`                         |
-| `@remotion/lottie` runtime      | `lottie-web` from CDN — drop the React wrapper                                                            |
+| Remotion                        | HyperFrames                                                                                                       |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `<Lottie animationData={data}>` | `<div id="lottie-N">` + `<script>const anim = lottie.loadAnimation({...}); window.__hfLottie.push(anim)</script>` |
+| `loop` / `playbackRate` props   | translate only after checking player seek behavior; HF adapter seeks absolute time via `goToAndStop`              |
+| `@remotion/lottie` runtime      | `lottie-web` from CDN — drop the React wrapper                                                                    |
 
 ## Fonts
 
diff --git a/skills/remotion-to-hyperframes/references/lottie.md b/skills/remotion-to-hyperframes/references/lottie.md
index 22c103520..2fdb2e7d1 100644
--- a/skills/remotion-to-hyperframes/references/lottie.md
+++ b/skills/remotion-to-hyperframes/references/lottie.md
@@ -105,10 +105,12 @@ for the full supported feature list.
 ## Loop behavior
 
 Remotion's `loop={true}` plays the animation continuously. Translate to
-the lottie-web `loop: true` setting AND rely on the adapter's natural
-seek behavior (it'll seek modulo the animation's duration). For
-non-default playback rates, set `playbackRate` in `loadAnimation` and HF
-will respect it during seek.
+the player option only after checking the generated frames. The HF
+adapter seeks absolute composition time; it does not add modulo looping
+or playback-rate scaling on top of the player. For exact repeating
+cycles or non-default playback rates, bake the timing into the Lottie
+asset or author an explicit timeline around the Lottie layer and verify
+the rendered output.
 
 ## Performance note