takomi 2.5.1 → 2.5.4

package/assets/.agent/skills/remotion-to-hyperframes/references/limitations.md

@@ -1,136 +1,136 @@
-# Translation limitations
-
-What the skill explicitly cannot translate, separated from the
-blocker-list (which is enforced by `lint_source.py`). These are
-_known_ gaps — surface them to the user as translation notes
-when translating the surrounding composition.
-
-## React patterns the skill refuses
-
-See [escape-hatch.md](escape-hatch.md). Any of these triggers
-a bow-out:
-
-- `useState`, `useReducer` driving animation
-- `useEffect` / `useLayoutEffect` with non-empty deps (side effects)
-- async `calculateMetadata`
-- Third-party React UI libraries (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI)
-
-`@remotion/lambda` is no longer in this list — it's a warning, not a
-blocker, because Lambda config is orthogonal to composition rendering.
-The skill drops the imports and `renderMediaOnLambda(...)` calls and
-writes a `TRANSLATION_NOTES.md` entry. See
-[escape-hatch.md](escape-hatch.md).
-
-## Patterns that work with caveats
-
-### Volume ramps on `<Audio>`
-
-Remotion accepts a function for `volume`:
-
-```tsx
-<Audio src={...} volume={(f) => interpolate(f, [0, 30], [0, 1])} />
-```
-
-HF supports static `data-volume` only. Translation: bake the ramp into
-the audio file at translation time using `ffmpeg afade`, OR drop the
-ramp with a note. The dropped-ramp path produces audibly different
-output but visually-identical video, so SSIM passes — just flag it.
-
-### `<Loop>` with stateful children
-
-```tsx
-<Loop durationInFrames={30}>
-  <CounterThatIncrementsViaUseRef />
-</Loop>
-```
-
-Loop with `repeat: -1` works for _visual_ repetition. If the looped
-child has cross-iteration state (a counter, a randomness seed), HF
-won't reproduce it identically per iteration. Bow out unless the
-child is fully deterministic per-iteration.
-
-### Remotion's `<Img>` with crossOrigin
-
-```tsx
-<Img src="https://other-domain.com/x.png" crossOrigin="anonymous" />
-```
-
-HF's renderer doesn't enforce CORS the same way Remotion does. Most
-public images work; private images served with auth headers won't.
-If the source uses `crossOrigin="use-credentials"`, the asset needs
-to be downloaded and inlined at translation time.
-
-### Custom `presentation` in `<TransitionSeries>`
-
-```tsx
-const customPresentation: PresentationComponent = ({ children, presentationProgress }) => {
-  return <div style={{ filter: `blur(${(1 - presentationProgress) * 20}px)` }}>{children}</div>;
-};
-```
-
-Pure presentations (transform/filter/opacity computed from progress)
-translate to GSAP tweens cleanly. Presentations that read
-`useCurrentFrame()` internally or have stateful children don't —
-bow out.
-
-### Code-split components (`React.lazy`)
-
-```tsx
-const HeavyChart = React.lazy(() => import("./HeavyChart"));
-```
-
-`React.lazy` is async and doesn't fit the deterministic-render model.
-Translate to a regular import; the resulting HF composition will
-just include all the code upfront.
-
-## Patterns that always work
-
-- `<AbsoluteFill>` and `<Sequence>` (any nesting)
-- `useCurrentFrame()` derivations: `interpolate`, `spring`, `Easing`,
-  `interpolateColors`, manual math
-- `<Audio>`, `<Video>`, `<Img>`, `<IFrame>` with simple props
-- `staticFile()` references
-- Custom React subcomponents that are pure functions of props
-- Custom hooks that are pure derivations of `useCurrentFrame`
-- `@remotion/lottie` (translates to HF's Lottie adapter)
-- `@remotion/google-fonts/<Family>` (translates to `<link>` or `@font-face`)
-- Sync `calculateMetadata` (resolved at translation time)
-- `<TransitionSeries>` with built-in presentations (`fade`, `slide`,
-  `wipe`, `clockWipe`, `flip`, `iris`)
-
-## What the skill never tries to translate
-
-These are out-of-scope by design:
-
-- **HDR rendering** — HF supports HDR but Remotion doesn't, so there's
-  nothing to translate from.
-- **Variable frame rate** — both tools assume constant fps.
-- **Multi-composition `<Composition>` lists** — translate one at a
-  time. The skill prompts the user to choose which composition.
-- **Remotion Studio props panel** — visual prop editing in HF Studio
-  needs different infrastructure; out of scope.
-
-## Reporting gaps to the user
-
-When translation produces _something_ but the something has gaps, write
-a `TRANSLATION_NOTES.md` next to the output:
-
-```markdown
-# Translation notes
-
-The following Remotion patterns were translated with caveats:
-
-- `<Audio volume={(f) => ...}>` (line 15): volume ramp dropped — added
-  static `data-volume="0.5"`. To preserve the ramp, run
-  `ffmpeg -i music.wav -af "afade=t=in:st=0:d=1" music.faded.wav` and
-  swap the source file.
-- `<HeavyChart>` (line 30): translated as inline HTML. The original
-  React.lazy boundary was dropped — bundle size unchanged because HF
-  serves a single HTML file.
-
-If any of these caveats matter, consider the runtime interop pattern
-instead.
-```
-
-This file is also generated by the skill alongside the HF output, not
-held in the corpus.
+# Translation limitations
+
+What the skill explicitly cannot translate, separated from the
+blocker-list (which is enforced by `lint_source.py`). These are
+_known_ gaps — surface them to the user as translation notes
+when translating the surrounding composition.
+
+## React patterns the skill refuses
+
+See [escape-hatch.md](escape-hatch.md). Any of these triggers
+a bow-out:
+
+- `useState`, `useReducer` driving animation
+- `useEffect` / `useLayoutEffect` with non-empty deps (side effects)
+- async `calculateMetadata`
+- Third-party React UI libraries (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI)
+
+`@remotion/lambda` is no longer in this list — it's a warning, not a
+blocker, because Lambda config is orthogonal to composition rendering.
+The skill drops the imports and `renderMediaOnLambda(...)` calls and
+writes a `TRANSLATION_NOTES.md` entry. See
+[escape-hatch.md](escape-hatch.md).
+
+## Patterns that work with caveats
+
+### Volume ramps on `<Audio>`
+
+Remotion accepts a function for `volume`:
+
+```tsx
+<Audio src={...} volume={(f) => interpolate(f, [0, 30], [0, 1])} />
+```
+
+HF supports static `data-volume` only. Translation: bake the ramp into
+the audio file at translation time using `ffmpeg afade`, OR drop the
+ramp with a note. The dropped-ramp path produces audibly different
+output but visually-identical video, so SSIM passes — just flag it.
+
+### `<Loop>` with stateful children
+
+```tsx
+<Loop durationInFrames={30}>
+  <CounterThatIncrementsViaUseRef />
+</Loop>
+```
+
+Loop with `repeat: -1` works for _visual_ repetition. If the looped
+child has cross-iteration state (a counter, a randomness seed), HF
+won't reproduce it identically per iteration. Bow out unless the
+child is fully deterministic per-iteration.
+
+### Remotion's `<Img>` with crossOrigin
+
+```tsx
+<Img src="https://other-domain.com/x.png" crossOrigin="anonymous" />
+```
+
+HF's renderer doesn't enforce CORS the same way Remotion does. Most
+public images work; private images served with auth headers won't.
+If the source uses `crossOrigin="use-credentials"`, the asset needs
+to be downloaded and inlined at translation time.
+
+### Custom `presentation` in `<TransitionSeries>`
+
+```tsx
+const customPresentation: PresentationComponent = ({ children, presentationProgress }) => {
+  return <div style={{ filter: `blur(${(1 - presentationProgress) * 20}px)` }}>{children}</div>;
+};
+```
+
+Pure presentations (transform/filter/opacity computed from progress)
+translate to GSAP tweens cleanly. Presentations that read
+`useCurrentFrame()` internally or have stateful children don't —
+bow out.
+
+### Code-split components (`React.lazy`)
+
+```tsx
+const HeavyChart = React.lazy(() => import("./HeavyChart"));
+```
+
+`React.lazy` is async and doesn't fit the deterministic-render model.
+Translate to a regular import; the resulting HF composition will
+just include all the code upfront.
+
+## Patterns that always work
+
+- `<AbsoluteFill>` and `<Sequence>` (any nesting)
+- `useCurrentFrame()` derivations: `interpolate`, `spring`, `Easing`,
+  `interpolateColors`, manual math
+- `<Audio>`, `<Video>`, `<Img>`, `<IFrame>` with simple props
+- `staticFile()` references
+- Custom React subcomponents that are pure functions of props
+- Custom hooks that are pure derivations of `useCurrentFrame`
+- `@remotion/lottie` (translates to HF's Lottie adapter)
+- `@remotion/google-fonts/<Family>` (translates to `<link>` or `@font-face`)
+- Sync `calculateMetadata` (resolved at translation time)
+- `<TransitionSeries>` with built-in presentations (`fade`, `slide`,
+  `wipe`, `clockWipe`, `flip`, `iris`)
+
+## What the skill never tries to translate
+
+These are out-of-scope by design:
+
+- **HDR rendering** — HF supports HDR but Remotion doesn't, so there's
+  nothing to translate from.
+- **Variable frame rate** — both tools assume constant fps.
+- **Multi-composition `<Composition>` lists** — translate one at a
+  time. The skill prompts the user to choose which composition.
+- **Remotion Studio props panel** — visual prop editing in HF Studio
+  needs different infrastructure; out of scope.
+
+## Reporting gaps to the user
+
+When translation produces _something_ but the something has gaps, write
+a `TRANSLATION_NOTES.md` next to the output:
+
+```markdown
+# Translation notes
+
+The following Remotion patterns were translated with caveats:
+
+- `<Audio volume={(f) => ...}>` (line 15): volume ramp dropped — added
+  static `data-volume="0.5"`. To preserve the ramp, run
+  `ffmpeg -i music.wav -af "afade=t=in:st=0:d=1" music.faded.wav` and
+  swap the source file.
+- `<HeavyChart>` (line 30): translated as inline HTML. The original
+  React.lazy boundary was dropped — bundle size unchanged because HF
+  serves a single HTML file.
+
+If any of these caveats matter, consider the runtime interop pattern
+instead.
+```
+
+This file is also generated by the skill alongside the HF output, not
+held in the corpus.

package/assets/.agent/skills/remotion-to-hyperframes/references/lottie.md

@@ -1,121 +1,121 @@
-# Lottie translation: @remotion/lottie → HF lottie adapter
-
-Lottie animations are a clean translation case — HF has a built-in
-[Lottie adapter](https://github.com/heygen-com/hyperframes/blob/main/packages/core/src/runtime/adapters/lottie.ts)
-that supports both `lottie-web` and `@lottiefiles/dotlottie-web`. The
-adapter auto-discovers animations registered on `window.__hfLottie`
-and seeks them per-frame via `goToAndStop`.
-
-## Pattern
-
-```tsx
-import { Lottie } from "@remotion/lottie";
-import animationData from "./hello.json";
-
-export const MyComp = () => (
-  <AbsoluteFill>
-    <Lottie animationData={animationData} loop={false} />
-  </AbsoluteFill>
-);
-```
-
-Translates to:
-
-```html
-<div id="stage" ...>
-  <div id="lottie-anim" style="width:100%;height:100%"></div>
-  <script src="https://cdnjs.cloudflare.com/ajax/libs/bodymovin/5.12.2/lottie.min.js"></script>
-  <script>
-    const anim = lottie.loadAnimation({
-      container: document.getElementById("lottie-anim"),
-      renderer: "svg",
-      loop: false,
-      autoplay: false,
-      path: "assets/hello.json",
-    });
-    window.__hfLottie = window.__hfLottie || [];
-    window.__hfLottie.push(anim);
-  </script>
-</div>
-```
-
-Key differences from a typical Lottie embed:
-
-- `autoplay: false` — HF drives playback by seeking
-- `loop: false` typically (unless Remotion's `loop={true}`)
-- `window.__hfLottie.push(anim)` is what hooks the animation into HF's
-  per-frame seek
-
-## Asset handling
-
-Remotion bundles the animation JSON via webpack import. HF needs the JSON
-on disk under `assets/` and references it via path:
-
-1. Copy `hello.json` from the Remotion project into `hf-src/assets/`.
-2. Reference as `path: "assets/hello.json"` in `loadAnimation`.
-
-For dotlottie (binary) format, swap in `@lottiefiles/dotlottie-web`:
-
-```html
-<script src="https://unpkg.com/@lottiefiles/dotlottie-web"></script>
-<canvas id="anim" style="width:100%;height:100%"></canvas>
-<script>
-  const player = new DotLottie({
-    canvas: document.getElementById("anim"),
-    src: "assets/hello.lottie",
-    autoplay: false,
-  });
-  window.__hfLottie = window.__hfLottie || [];
-  window.__hfLottie.push(player);
-</script>
-```
-
-The HF adapter handles both player APIs (it duck-types `goToAndStop`
-vs `setCurrentRawFrameValue` / `seek`).
-
-## Multiple Lottie animations
-
-Multiple `<Lottie>` instances in one composition work — push each one
-onto `window.__hfLottie` and the adapter will seek all of them in sync:
-
-```js
-window.__hfLottie.push(anim1);
-window.__hfLottie.push(anim2);
-window.__hfLottie.push(anim3);
-```
-
-## Lottie source isn't actually translation-blocking
-
-Lottie animations encode their own deterministic timeline. They're the
-_easiest_ part of a Remotion composition to translate because the
-animation logic is already self-contained — neither Remotion nor HF
-"animate" them, both just seek them. Translation cost is near-zero.
-
-## After Effects → Lottie limitations
-
-Lottie supports a subset of After Effects features. Expressions, most
-Effects (drop shadow, color overlay), all blend modes beyond Normal/Add/
-Multiply, luma mattes, and most 3D parameters are not supported. If the
-Remotion composition uses a Lottie file that depends on these, the
-animation will break in BOTH Remotion and HF — this isn't a translation
-problem, it's a Lottie limitation. See
-[airbnb/lottie/after-effects.md](https://github.com/airbnb/lottie/blob/master/after-effects.md)
-for the full supported feature list.
-
-## Loop behavior
-
-Remotion's `loop={true}` plays the animation continuously. Translate to
-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
-
-Per the [Lottie adapter](https://github.com/heygen-com/hyperframes/blob/main/packages/core/src/runtime/adapters/lottie.ts)
-docs: lottie-web's `goToAndStop(time, isFrame=false)` takes time in ms;
-the adapter passes `time * 1000` for precision. This is more accurate
-than passing frame numbers (especially for animations whose internal
-fps doesn't match the HF render fps).
+# Lottie translation: @remotion/lottie → HF lottie adapter
+
+Lottie animations are a clean translation case — HF has a built-in
+[Lottie adapter](https://github.com/heygen-com/hyperframes/blob/main/packages/core/src/runtime/adapters/lottie.ts)
+that supports both `lottie-web` and `@lottiefiles/dotlottie-web`. The
+adapter auto-discovers animations registered on `window.__hfLottie`
+and seeks them per-frame via `goToAndStop`.
+
+## Pattern
+
+```tsx
+import { Lottie } from "@remotion/lottie";
+import animationData from "./hello.json";
+
+export const MyComp = () => (
+  <AbsoluteFill>
+    <Lottie animationData={animationData} loop={false} />
+  </AbsoluteFill>
+);
+```
+
+Translates to:
+
+```html
+<div id="stage" ...>
+  <div id="lottie-anim" style="width:100%;height:100%"></div>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/bodymovin/5.12.2/lottie.min.js"></script>
+  <script>
+    const anim = lottie.loadAnimation({
+      container: document.getElementById("lottie-anim"),
+      renderer: "svg",
+      loop: false,
+      autoplay: false,
+      path: "assets/hello.json",
+    });
+    window.__hfLottie = window.__hfLottie || [];
+    window.__hfLottie.push(anim);
+  </script>
+</div>
+```
+
+Key differences from a typical Lottie embed:
+
+- `autoplay: false` — HF drives playback by seeking
+- `loop: false` typically (unless Remotion's `loop={true}`)
+- `window.__hfLottie.push(anim)` is what hooks the animation into HF's
+  per-frame seek
+
+## Asset handling
+
+Remotion bundles the animation JSON via webpack import. HF needs the JSON
+on disk under `assets/` and references it via path:
+
+1. Copy `hello.json` from the Remotion project into `hf-src/assets/`.
+2. Reference as `path: "assets/hello.json"` in `loadAnimation`.
+
+For dotlottie (binary) format, swap in `@lottiefiles/dotlottie-web`:
+
+```html
+<script src="https://unpkg.com/@lottiefiles/dotlottie-web"></script>
+<canvas id="anim" style="width:100%;height:100%"></canvas>
+<script>
+  const player = new DotLottie({
+    canvas: document.getElementById("anim"),
+    src: "assets/hello.lottie",
+    autoplay: false,
+  });
+  window.__hfLottie = window.__hfLottie || [];
+  window.__hfLottie.push(player);
+</script>
+```
+
+The HF adapter handles both player APIs (it duck-types `goToAndStop`
+vs `setCurrentRawFrameValue` / `seek`).
+
+## Multiple Lottie animations
+
+Multiple `<Lottie>` instances in one composition work — push each one
+onto `window.__hfLottie` and the adapter will seek all of them in sync:
+
+```js
+window.__hfLottie.push(anim1);
+window.__hfLottie.push(anim2);
+window.__hfLottie.push(anim3);
+```
+
+## Lottie source isn't actually translation-blocking
+
+Lottie animations encode their own deterministic timeline. They're the
+_easiest_ part of a Remotion composition to translate because the
+animation logic is already self-contained — neither Remotion nor HF
+"animate" them, both just seek them. Translation cost is near-zero.
+
+## After Effects → Lottie limitations
+
+Lottie supports a subset of After Effects features. Expressions, most
+Effects (drop shadow, color overlay), all blend modes beyond Normal/Add/
+Multiply, luma mattes, and most 3D parameters are not supported. If the
+Remotion composition uses a Lottie file that depends on these, the
+animation will break in BOTH Remotion and HF — this isn't a translation
+problem, it's a Lottie limitation. See
+[airbnb/lottie/after-effects.md](https://github.com/airbnb/lottie/blob/master/after-effects.md)
+for the full supported feature list.
+
+## Loop behavior
+
+Remotion's `loop={true}` plays the animation continuously. Translate to
+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
+
+Per the [Lottie adapter](https://github.com/heygen-com/hyperframes/blob/main/packages/core/src/runtime/adapters/lottie.ts)
+docs: lottie-web's `goToAndStop(time, isFrame=false)` takes time in ms;
+the adapter passes `time * 1000` for precision. This is more accurate
+than passing frame numbers (especially for animations whose internal
+fps doesn't match the HF render fps).