freecodego 0.1.7-alpha.2.2 → 0.1.7-rc.2.3

package/dist/assets/design/skills/remotion-to-hyperframes/references/sequencing.md

@@ -0,0 +1,251 @@
+# Sequencing translation: Sequence, Series, Composition root
+
+How Remotion's nested `Sequence` tree maps to one sub-composition host per
+scene in the root, each with its own paused GSAP timeline in local time.
+
+## 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 scene hosts on the same
+parent, each with its own time window; each scene's content lives in its
+own sub-composition file.
+
+## `<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>` → sub-composition host
+
+```tsx
+<Sequence from={0} durationInFrames={90}>
+  <TitleCard />
+</Sequence>
+```
+
+The root `#stage` only holds a host per scene; the scene's markup, styles
+and timeline live in their own sub-composition file, so the Studio timeline
+gets one readable row per scene and the lint has no nested structure to flag.
+
+```html
+<!-- index.html -->
+<div
+  id="scene-1"
+  class="clip"
+  data-composition-id="scene-1"
+  data-composition-src="compositions/scene-1.html"
+  data-start="0"
+  data-duration="3"
+  data-track-index="0"
+></div>
+```
+
+```html
+<!-- compositions/scene-1.html: TitleCard children inlined, timeline keyed "scene-1", local time starts at 0 -->
+<template id="scene-1-template">
+  <div data-composition-id="scene-1" data-width="1280" data-height="720" data-duration="3">
+    <!-- TitleCard children -->
+    <script>
+      const tl = gsap.timeline({ paused: true });
+      window.__timelines["scene-1"] = tl;
+    </script>
+  </div>
+</template>
+```
+
+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.
+Inside the sub-composition, time is local: a tween that started at `F/fps`
+in the root starts at `0` here. Asset paths are relative to the
+sub-composition file (`../assets/x.png`).
+
+## 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 host with the resolved
+window; the scene's children go in its sub-composition file:
+
+```html
+<div
+  data-composition-id="image-scene"
+  data-composition-src="compositions/image-scene.html"
+  data-start="3"
+  data-duration="2"
+  data-track-index="0"
+></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 (each host mounts its scene file):
+
+```html
+<div
+  data-composition-id="a"
+  data-composition-src="compositions/a.html"
+  data-start="0"
+  data-duration="2"
+  data-track-index="0"
+></div>
+<div
+  data-composition-id="b"
+  data-composition-src="compositions/b.html"
+  data-start="2"
+  data-duration="4"
+  data-track-index="0"
+></div>
+<div
+  data-composition-id="c"
+  data-composition-src="compositions/c.html"
+  data-start="6"
+  data-duration="3"
+  data-track-index="0"
+></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. A scene can
+hard-cut itself with `gsap.set` at its local end (the corpus fixtures do). A
+fade between two scenes goes on the scene hosts from the root timeline, since
+a scene's own timeline only sees its own file:
+
+```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 it to a bounded GSAP timeline using
+the time available at its insertion point:
+
+```js
+const cycleDuration = 1;
+const availableDuration = compositionDuration - 3;
+const repeat = Math.max(0, Math.floor(availableDuration / cycleDuration) - 1);
+const spinTl = gsap.timeline({ paused: true, repeat, 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.
+The finite count is required because HyperFrames seeks a bounded composition frame-by-frame.
+
+## `<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.

package/dist/assets/design/skills/remotion-to-hyperframes/references/timing.md

@@ -0,0 +1,165 @@
+# Timing translation: interpolate, spring, easing
+
+The single highest-leverage reference. Easings and timings are what readers
+notice; getting them wrong costs more SSIM than any other translation choice.
+Empirically validated against tiers T1–T3.
+
+## Conversion: frames → seconds
+
+HF's timeline is in seconds. Remotion is frame-based. Always:
+
+```
+time_seconds = frame / fps
+```
+
+So at fps=30:
+
+- frame 15 → 0.5 s
+- frame 30 → 1.0 s
+- frame 90 → 3.0 s
+
+Do this conversion once when translating, not at runtime.
+
+## interpolate — linear
+
+```tsx
+const opacity = interpolate(frame, [0, 30], [0, 1], { extrapolateRight: "clamp" });
+```
+
+Translates to:
+
+```js
+gsap.to(target, { opacity: 1, duration: 1.0, ease: "none" }, 0);
+// fromTo if the property starts at 0 and CSS doesn't already set it
+gsap.fromTo(target, { opacity: 0 }, { opacity: 1, duration: 1.0, ease: "none" }, 0);
+```
+
+`ease: "none"` matches Remotion's default linear interpolation. CSS sets the
+`from` value if your initial state is in CSS; otherwise use `fromTo`.
+
+`extrapolateLeft`/`extrapolateRight` defaults to `"extend"` in Remotion but
+`"clamp"` is what the agent will see most often. GSAP doesn't extend — values
+hold at the start and end of the tween. So for `clamp`, GSAP matches; for
+`extend`, you'd need to extend the input range manually before emitting.
+
+## interpolate — multi-segment
+
+```tsx
+const opacity = interpolate(frame, [0, 15, 75, 90], [0, 1, 1, 0]);
+```
+
+Three keyframed tweens at offsets `[0]/fps`, `[1]/fps`, `[2]/fps`:
+
+```js
+const tl = gsap.timeline({ paused: true });
+tl.to(target, { opacity: 1, duration: 0.5, ease: "none" }, 0);
+tl.to(target, { opacity: 1, duration: 2.0, ease: "none" }, 0.5);
+tl.to(target, { opacity: 0, duration: 0.5, ease: "none" }, 2.5);
+```
+
+Validated in T1 — mean SSIM 0.974 against Remotion baseline.
+
+## spring → GSAP back.out
+
+Remotion's `spring()` is the most lossy translation. The mapping is approximate
+but close enough that real-world compositions hold ≥ 0.92 SSIM (T2: 0.985, T3: 0.953).
+
+| Remotion `spring` config                          | GSAP equivalent                                      | Validated in                     |
+| ------------------------------------------------- | ---------------------------------------------------- | -------------------------------- |
+| `{damping: 12, stiffness: 100, mass: 1}` (snappy) | `back.out(1.4)` over ~0.7 s                          | T2, T3 (TitleScene)              |
+| `{damping: 14, stiffness: 90, mass: 1}` (calmer)  | `back.out(1.2)` over ~0.7 s                          | T3 (StatCard)                    |
+| `{damping: 8, stiffness: 200}` (very bouncy)      | `back.out(2.0)` or `elastic.out(1, 0.5)` over ~0.6 s | not validated; budget ~0.05 SSIM |
+| `{overshootClamping: true}`                       | `power3.out` over ~0.6 s (no overshoot)              | not validated                    |
+
+**Rule of thumb**: `back.out(N)` overshoot ratio ≈ `(stiffness / damping^2) * 1.4`. For
+`damping:12, stiffness:100` that gives `1.4 * 100/144 = 0.97`, which is close to
+the validated 1.4 (the formula is rough; tune by visual). Default duration is
+~0.7 s for the typical config.
+
+When the spring's `delay`/`from`/`to` are non-default, scale the duration
+proportionally.
+
+## interpolate with custom easing
+
+```tsx
+import { Easing } from "remotion";
+interpolate(frame, [0, 30], [0, 1], { easing: Easing.out(Easing.cubic) });
+```
+
+| Remotion                     | GSAP                                                                                   |
+| ---------------------------- | -------------------------------------------------------------------------------------- |
+| `Easing.in(Easing.linear)`   | `ease: "none"`                                                                         |
+| `Easing.out(Easing.cubic)`   | `ease: "power3.out"`                                                                   |
+| `Easing.inOut(Easing.cubic)` | `ease: "power3.inOut"`                                                                 |
+| `Easing.out(Easing.poly(N))` | `ease: "power<N>.out"` (N=2 quad, 3 cubic, 4 quart, 5 quint)                           |
+| `Easing.bezier(a,b,c,d)`     | `CustomEase.create("c", "M0,0 C${a},${b} ${c},${d} 1,1")` (requires CustomEase plugin) |
+| `Easing.elastic(bounciness)` | `ease: "elastic.out(${bounciness}, 0.3)"`                                              |
+| `Easing.bounce`              | `ease: "bounce.out"`                                                                   |
+| `Easing.back(overshoot)`     | `ease: "back.out(${overshoot * 1.7})"` (Remotion's overshoot scale differs)            |
+
+## interpolate driving non-numeric properties
+
+```tsx
+const color = interpolateColors(frame, [0, 30], ["#ff0000", "#0000ff"]);
+```
+
+GSAP does color tweens natively:
+
+```js
+gsap.to(target, { color: "#0000ff", duration: 1.0, ease: "none" }, 0);
+```
+
+Same for `backgroundColor`, `borderColor`. The `from` value is read from CSS
+or the inline style.
+
+## Custom count-up / number tweens
+
+When Remotion uses a frame-driven number ramp (`Math.round(value * eased)`):
+
+```tsx
+const t = interpolate(frame, [0, 45], [0, 1]);
+const eased = 1 - (1 - t) ** 3; // cubic ease-out
+const value = Math.round(target * eased);
+return <div>{value.toLocaleString()}</div>;
+```
+
+GSAP equivalent — tween a counter object, write `textContent` on update:
+
+```js
+const counter = { v: 0 };
+tl.to(
+  counter,
+  {
+    v: target,
+    duration: 1.5,
+    ease: "power3.out",
+    onUpdate: () => {
+      el.textContent = Math.round(counter.v).toLocaleString();
+    },
+  },
+  0,
+);
+```
+
+`power3.out` matches `1 - (1-t)^3` exactly. Validated in T3 (mean SSIM 0.953).
+Per-frame digit mismatches occur on sub-frame timing offsets but final values
+converge — no SSIM impact above the noise floor.
+
+## Stagger via per-instance prop
+
+When custom subcomponents take a `delayInFrames` prop:
+
+```tsx
+<StatCard delayInFrames={i * 12} value={...} />
+```
+
+Translate to GSAP timeline offsets:
+
+```js
+cards.forEach((card, i) => {
+  const start = base + i * (12 / fps); // i * 0.4s at fps=30
+  tl.to(card, { ... }, start);
+});
+```
+
+Validated in T3 — three StatCards staggered at 0.0/0.4/0.8 s.

package/dist/assets/design/skills/remotion-to-hyperframes/references/transitions.md

@@ -0,0 +1,113 @@
+# Transitions translation: @remotion/transitions → HF crossfades / shader-transitions
+
+The `@remotion/transitions` package is Remotion's library of pre-built
+scene-to-scene transitions. HF has two paths to translate them:
+
+1. **Manual GSAP crossfade** — for simple opacity/transform transitions. Free, no extra package.
+2. **HF shader-transitions package** — for visually-rich transitions that match the @remotion/transitions presets.
+
+## Pattern: `<TransitionSeries>` is `<Series>` with overlap
+
+```tsx
+<TransitionSeries>
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneA />
+  </TransitionSeries.Sequence>
+  <TransitionSeries.Transition
+    presentation={fade()}
+    timing={linearTiming({ durationInFrames: 15 })}
+  />
+  <TransitionSeries.Sequence durationInFrames={60}>
+    <SceneB />
+  </TransitionSeries.Sequence>
+</TransitionSeries>
+```
+
+Translates to scenes that overlap by the transition duration:
+
+- SceneA: [0, 60] = `data-start="0" data-duration="2"`
+- SceneB: [60-15, 60-15+60] = `data-start="1.5" data-duration="2"` (the transition window overlaps the end of A and start of B)
+
+Then drive the transition with GSAP:
+
+```js
+// Manual fade (presentation={fade()})
+tl.to(sceneA, { opacity: 0, duration: 0.5, ease: "none" }, 1.5);
+tl.fromTo(sceneB, { opacity: 0 }, { opacity: 1, duration: 0.5, ease: "none" }, 1.5);
+```
+
+## Presentation table
+
+| Remotion `presentation`            | HF translation                                                                            |
+| ---------------------------------- | ----------------------------------------------------------------------------------------- |
+| `fade()`                           | manual `gsap.to(opacity)` crossfade                                                       |
+| `slide({direction: "from-right"})` | `gsap.fromTo(translateX: "100%" → 0)` on incoming + `to(translateX: "-100%")` on outgoing |
+| `wipe({direction: "from-left"})`   | `gsap.fromTo(clip-path: inset(0 100% 0 0) → inset(0 0 0 0))` on incoming                  |
+This plugin ships no hosted block registry, so the effect is built from the local materials this skill carries.
+| `flip()`                           | `gsap.to(rotateY)` 180° split between scenes                                              |
+| `cube()`                           | use HF's `cinematic-zoom` or build manually with `rotateY` + `transform-origin`           |
+| `iris()`                           | use HF's `sdf-iris` shader-transition                                                     |
+| `none()`                           | no transition; hard cut at the boundary                                                   |
+
+## Timing translations
+
+```tsx
+linearTiming({durationInFrames: 15})              → ease: "none"
+linearTiming({durationInFrames: 15, easing: ...}) → ease per the easing table in timing.md
+springTiming({config: {damping: 12}})             → ease: "back.out(1.4)" (~0.7 s)
+```
+
+Convert `durationInFrames` to seconds (`/fps`).
+
+## When to use HF shader-transitions
+
+For transitions Remotion presets that have visually-rich GLSL equivalents
+(iris, ripple, zoom, glitch), use HF's [shader-transitions](https://hyperframes.heygen.com/catalog/blocks)
+package. They produce richer output than manual GSAP transforms.
+
+```bash
+```
+
+Then in the composition:
+
+```html
+<div id="iris-transition" class="hf-shader-transition" data-start="1.5" data-duration="0.5">
+  <!-- bound scenes via the shader-transition's data-from / data-to -->
+</div>
+```
+
+Each shader-transition has its own data attributes; see the catalog page
+for the specific block.
+
+## When the source uses a custom Presentation
+
+Remotion supports custom `presentation` implementations:
+
+```tsx
+const customPresentation: PresentationComponent = ({
+  children,
+  presentationProgress,
+  presentationDirection,
+}) => {
+  return (
+    <div
+      style={
+        {
+          /* compute transform from progress */
+        }
+      }
+    >
+      {children}
+    </div>
+  );
+};
+```
+
+Translation: extract the math from the `style={...}` block and emit
+equivalent GSAP tweens. Specifically the transform formula maps directly
+to a `gsap.to(target, { transform: ... })` parameterized by `progress`.
+
+If the custom presentation uses `useCurrentFrame()` internally to
+animate something _outside_ the simple progress curve, treat the source
+as untranslatable and bow out to the runtime interop pattern (see
+[escape-hatch.md](escape-hatch.md)).