zilmate 1.9.3 → 1.10.1

package/.agents/skills/remotion-to-hyperframes/references/lottie.md

@@ -0,0 +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).

package/.agents/skills/remotion-to-hyperframes/references/media.md

@@ -0,0 +1,149 @@
+# Media translation: Audio, Video, Img, IFrame, staticFile
+
+## Asset paths
+
+Remotion's `staticFile("x.png")` resolves to the project's `public/` directory.
+HF uses relative paths from the composition's `index.html`, conventionally
+`assets/`:
+
+```tsx
+<Img src={staticFile("logo.png")} />
+```
+
+```html
+<img src="assets/logo.png" />
+```
+
+When translating, copy the asset from `remotion-src/public/x` to
+`hf-src/assets/x`. Multiple files can be batched with a setup script;
+see T2's `setup.sh` for an example pattern.
+
+## `<Audio>`
+
+```tsx
+<Audio src={staticFile("music.wav")} volume={0.5} />
+```
+
+```html
+<audio
+  data-start="0"
+  data-duration="6"
+  data-track-index="2"
+  data-volume="0.5"
+  src="assets/music.wav"
+></audio>
+```
+
+`data-start` and `data-duration` are required — the runtime needs them to
+schedule the audio. Default to the composition's full duration if Remotion
+didn't specify trim.
+
+### Volume ramps
+
+```tsx
+<Audio src={staticFile("music.wav")} volume={(f) => interpolate(f, [0, 30], [0, 1])} />
+```
+
+HF supports static `data-volume` only for now. Volume ramps need to be
+applied to the audio file at translation time (with ffmpeg `afade`) or the
+ramp is dropped with a translation note.
+
+### Trim / playbackRate
+
+```tsx
+<Audio src={staticFile("music.wav")} startFrom={60} endAt={180} playbackRate={1.5} />
+```
+
+```html
+<audio
+  data-start="0"
+  data-duration="<resolved from trim>"
+  data-trim-start="2"
+  data-trim-end="6"
+  data-playback-rate="1.5"
+  src="assets/music.wav"
+></audio>
+```
+
+`startFrom` / `endAt` are frame indexes; convert to seconds.
+
+## `<Video>` and `<OffthreadVideo>`
+
+```tsx
+<Video src={staticFile("intro.mp4")} muted playsInline />
+<OffthreadVideo src={staticFile("intro.mp4")} muted />
+```
+
+```html
+<video
+  muted
+  playsinline
+  data-start="0"
+  data-duration="5"
+  data-track-index="0"
+  src="assets/intro.mp4"
+></video>
+```
+
+`<OffthreadVideo>` is a Remotion-specific optimization for headless
+rendering. HF runs in headless Chrome already, so the off-thread variant
+collapses to a regular `<video>`.
+
+`muted` and `playsinline` are required for the runtime to autoplay
+(browser policy). Always emit them.
+
+## `<Img>`
+
+```tsx
+<Img src={staticFile("logo.png")} style={{ width: 200, height: 200 }} />
+```
+
+```html
+<img src="assets/logo.png" style="width: 200px; height: 200px;" />
+```
+
+Width/height get rounded to integer px. If the original style has
+animated dimensions, the GSAP tween animates them — see [timing.md](timing.md).
+
+## `<IFrame>`
+
+```tsx
+<IFrame src="https://example.com" />
+```
+
+```html
+<iframe src="https://example.com"></iframe>
+```
+
+When HF detects a nested iframe in a composition, it auto-falls back to
+**screenshot mode** rather than the deterministic BeginFrame mode. This
+costs render performance but produces visibly-correct output. See
+[hyperframes-vs-remotion.mdx](https://github.com/heygen-com/hyperframes/blob/main/docs/guides/hyperframes-vs-remotion.mdx)
+for details.
+
+## `delayRender()` / `continueRender()`
+
+```tsx
+const handle = delayRender();
+useEffect(() => {
+  loadAsset().then(() => continueRender(handle));
+}, []);
+```
+
+Drop. HF waits on asset readiness via the [Frame Adapter pattern](https://hyperframes.heygen.com/concepts/frame-adapters)
+— images, videos, fonts, and Lottie animations all signal load
+completion natively. There's nothing to do at the application level.
+
+## When the asset isn't a file
+
+If Remotion's media source is a Buffer, dataURL, or URL.createObjectURL,
+the asset doesn't exist on disk and can't be copied via setup.sh. Two
+options:
+
+1. Materialize the asset at translation time — write the buffer to a file
+   in `hf-src/assets/`.
+2. Embed as a data URL directly in the HTML (`src="data:image/png;base64,..."`)
+   for small assets (< 100 KB).
+
+For audio/video Buffers, option 1 is preferred — base64-encoded media
+bloats the HTML and slows the renderer.

package/.agents/skills/remotion-to-hyperframes/references/parameters.md

@@ -0,0 +1,167 @@
+# Parameter translation: Zod schemas, defaultProps, calculateMetadata
+
+How a typed Remotion `<Composition schema={...} defaultProps={...} />`
+turns into a parameterized HF composition.
+
+## Sync calculateMetadata (translatable)
+
+```tsx
+<Composition
+  id="MyVideo"
+  component={MyVideo}
+  schema={z.object({ title: z.string(), duration: z.number() })}
+  defaultProps={{ title: "Hello", duration: 90 }}
+  calculateMetadata={({ props }) => ({
+    durationInFrames: props.duration,
+    fps: 30,
+  })}
+/>
+```
+
+When `calculateMetadata` is synchronous and only uses `props`, **resolve
+it at translation time** — call it with `defaultProps` (or whatever the
+caller specifies) and write the concrete result into the HTML:
+
+```html
+<div
+  id="stage"
+  data-composition-id="MyVideo"
+  data-start="0"
+  data-duration="3"          <!-- 90/30 -->
+  data-fps="30"
+  data-title="Hello"
+></div>
+```
+
+The `data-title` attribute carries the value through. Code that originally
+read `props.title` reads `document.getElementById("stage").dataset.title`
+in HF.
+
+## Async calculateMetadata (NOT translatable)
+
+```tsx
+<Composition
+  calculateMetadata={async ({ props }) => {
+    const res = await fetch(...);
+    return { durationInFrames: res.duration };
+  }}
+/>
+```
+
+**Refuse + interop**. HF needs composition metadata up-front to seed the
+HTML. Resolving network calls at translation time defeats the purpose
+of having dynamic metadata. See [escape-hatch.md](escape-hatch.md).
+
+The lint rule `r2hf/async-metadata` catches this. T4 case 03 tests it.
+
+## Default props
+
+```tsx
+defaultProps={{
+  title: "Hello",
+  subtitle: "World",
+  count: 42,
+}}
+```
+
+Translate to `data-*` attributes on the root `#stage` div:
+
+```html
+<div id="stage" data-title="Hello" data-subtitle="World" data-count="42">...</div>
+```
+
+Convention: `propName` → `data-prop-name` (kebab-case). Inside the GSAP
+script, read via `document.getElementById("stage").dataset.propName`.
+
+## Nested object / array props
+
+```tsx
+defaultProps={{
+  stats: [
+    { label: "Stars", value: 1247, color: "#fbbf24" },
+    { label: "Forks", value: 312, color: "#60a5fa" },
+  ],
+}}
+```
+
+Don't try to encode the array as a JSON `data-` attribute — HF's runtime
+doesn't parse those. Materialize the array as **repeated HTML markup**:
+
+```html
+<div id="scene-stats">
+  <div class="stat-card" data-stat-index="0" data-stat-value="1247" style="--card-color:#fbbf24">
+    <div class="number">0</div>
+    <div class="label">Stars</div>
+  </div>
+  <div class="stat-card" data-stat-index="1" data-stat-value="312" style="--card-color:#60a5fa">
+    <div class="number">0</div>
+    <div class="label">Forks</div>
+  </div>
+</div>
+```
+
+The component template (`StatCard.tsx`) becomes the markup template;
+each instance gets its scalar props rendered as `data-*` and CSS
+custom properties.
+
+Validated in T3 — three StatCards reused with different props,
+mean SSIM 0.953.
+
+## Numeric props that need typed parsing
+
+`document.getElementById("stage").dataset.count` is a string. Convert at
+read time:
+
+```js
+const count = Number(stage.dataset.count);
+```
+
+Or inline values directly into the GSAP script when the data is known
+at translation time and doesn't need to vary per render.
+
+## Boolean props
+
+```tsx
+defaultProps={{ darkMode: true }}
+```
+
+Two conventions:
+
+- `data-dark-mode="true"` — read as string, compare `=== "true"`
+- `data-dark-mode` (presence/absence) — `<div data-dark-mode>` for true, omit for false
+
+Pick one and be consistent. The presence/absence form is HTML-idiomatic
+and pairs well with CSS attribute selectors:
+
+```css
+[data-dark-mode] .scene {
+  background: #000;
+}
+```
+
+## Zod runtime validation
+
+Remotion's `schema` validates props at composition load. HF doesn't have
+an equivalent — by the time the HTML is in the renderer, the schema is
+already gone.
+
+Validate at translation time instead. If the user passes invalid data,
+fail with a translation error before emitting HTML. This matches Zod's
+"fail loud" intent without requiring the runtime dependency.
+
+## When the composition uses props for computed prop derivation
+
+```tsx
+const Composition: React.FC<Props> = ({ stats }) => {
+  const total = stats.reduce((acc, s) => acc + s.value, 0);
+  return <div>{total}</div>;
+};
+```
+
+Compute the derived value at translation time and bake it into the HTML
+or a `data-` attribute. Don't try to express the computation in JS in the
+HF composition — that adds runtime overhead and makes the HTML stateful
+in ways that complicate human editing.
+
+If the derivation is non-trivial (involves the array itself, not just
+scalars), materialize it as static text in the HTML.

package/.agents/skills/remotion-to-hyperframes/references/sequencing.md

@@ -0,0 +1,195 @@
+# Sequencing translation: Sequence, Series, Composition root
+
+How Remotion's nested `Sequence` tree maps to HF's flat `data-start` /
+`data-duration` markup with a single paused GSAP timeline.
+
+## The core idea
+
+Remotion's `<Sequence from={F} durationInFrames={D}>` is a coordinate
+transform: it shifts `useCurrentFrame()` by `F` and clips the child
+component to the window `[F, F+D]`. HF doesn't have a per-element
+"current frame" — there's a single composition seek time and the
+runtime hides/shows elements based on their `data-start` / `data-duration`.
+
+Result: the nested tree flattens into a list of siblings on the same
+parent, each with their own time window.
+
+## `<Composition>` → root `#stage`
+
+```tsx
+<Composition
+  id="MyVideo"
+  component={MyVideo}
+  durationInFrames={300}
+  fps={30}
+  width={1280}
+  height={720}
+/>
+```
+
+```html
+<div
+  id="stage"
+  data-composition-id="MyVideo"
+  data-start="0"
+  data-duration="10"      <!-- 300/30 -->
+  data-fps="30"
+  data-width="1280"
+  data-height="720"
+>
+  <!-- composition content -->
+</div>
+```
+
+`data-start="0"` is required on `#stage` (the runtime needs it to anchor
+playback; missing it triggers a lint warning).
+
+## `<AbsoluteFill>` → positioned div
+
+```tsx
+<AbsoluteFill style={{ backgroundColor: "#0a0a0a" }}>...children...</AbsoluteFill>
+```
+
+```html
+<div style="position:absolute;inset:0;background-color:#0a0a0a;">...children...</div>
+```
+
+`AbsoluteFill` is just a styled div in Remotion. Translate to a div with
+`position:absolute; inset:0` and copy through any other style props.
+
+## `<Sequence>` → time-windowed div
+
+```tsx
+<Sequence from={0} durationInFrames={90}>
+  <TitleCard />
+</Sequence>
+```
+
+```html
+<div data-start="0" data-duration="3" data-track-index="0">
+  <!-- TitleCard children inlined -->
+</div>
+```
+
+Convert frames to seconds: `from/fps`, `durationInFrames/fps`. Pick a
+`data-track-index` per parallel rendering layer (background = 0,
+overlays = 1, audio = 2, etc.). Sequential scenes can share an index.
+
+## Nested `<Sequence>` flattens
+
+Remotion adds offsets when sequences nest:
+
+```tsx
+<Sequence from={60} durationInFrames={120}>
+  <Sequence from={30} durationInFrames={60}>
+    <ImageScene />
+  </Sequence>
+</Sequence>
+```
+
+The inner sequence's effective window is `[60+30, 60+30+60] = [90, 150]`.
+
+Translate by computing the sum and emitting one HF div with the resolved
+window:
+
+```html
+<div data-start="3" data-duration="2" data-track-index="0">
+  <!-- ImageScene children -->
+</div>
+```
+
+## `<Series>` → siblings with sequential offsets
+
+```tsx
+<Series>
+  <Series.Sequence durationInFrames={60}>
+    <A />
+  </Series.Sequence>
+  <Series.Sequence durationInFrames={120}>
+    <B />
+  </Series.Sequence>
+  <Series.Sequence durationInFrames={90}>
+    <C />
+  </Series.Sequence>
+</Series>
+```
+
+Each `Sequence.Sequence` lives in the next time slot. Emit siblings
+with `data-start` accumulating:
+
+```html
+<div data-start="0" data-duration="2" data-track-index="0">A</div>
+<div data-start="2" data-duration="4" data-track-index="0">B</div>
+<div data-start="6" data-duration="3" data-track-index="0">C</div>
+```
+
+## Crossfading scene boundaries
+
+Remotion `<Sequence>` shows/hides at hard boundaries by default. HF does
+the same — but if your composition needs a smooth fade between scenes,
+you have to drive opacity explicitly with GSAP at the boundary:
+
+```js
+const tl = gsap.timeline({ paused: true });
+tl.set(scene1, { opacity: 1 }, 0);
+tl.set(scene1, { opacity: 0 }, 2); // hard cut at 2s
+tl.set(scene2, { opacity: 1 }, 2);
+```
+
+For a 0.5 s crossfade:
+
+```js
+tl.to(scene1, { opacity: 0, duration: 0.5 }, 1.5);
+tl.to(scene2, { opacity: 1, duration: 0.5 }, 1.5);
+```
+
+For Remotion `<TransitionSeries>` translations see [transitions.md](transitions.md).
+
+## `<Loop>`
+
+```tsx
+<Loop durationInFrames={30}>
+  <Spinner />
+</Loop>
+```
+
+HF doesn't have a `<Loop>` primitive. Translate to a GSAP timeline with
+`repeat: -1`:
+
+```js
+const spinTl = gsap.timeline({ paused: true, repeat: -1, repeatRefresh: false });
+spinTl.to(spinner, { rotate: 360, duration: 1.0, ease: "none" });
+// Embed in the main composition timeline at the right offset:
+mainTl.add(spinTl, 3);
+```
+
+This is fragile — Remotion's `<Loop>` resets internal state every iteration,
+which GSAP repeat does too, but if the looped child has its own animation,
+you need to be careful that GSAP's `repeatRefresh` is on or off as needed.
+For most simple "spin forever" cases this is fine.
+
+## `<Freeze>`
+
+```tsx
+<Freeze frame={30}>
+  <Animated />
+</Freeze>
+```
+
+Drop the wrapper. `<Freeze>` pins `useCurrentFrame()` at a constant for
+the children — but in HF, the children's animation is already driven by
+explicit GSAP tweens, so freeze translates to "don't tween this element".
+
+## Multiple parallel tracks
+
+When you have a background video + overlay text + audio playing
+simultaneously, use distinct `data-track-index` values:
+
+```html
+<div data-track-index="0">background video</div>
+<div data-track-index="1">overlay text</div>
+<audio data-track-index="2" ...></audio>
+```
+
+The runtime picks track ordering from the index. See [media.md](media.md)
+for media-specific track conventions.