dsh-hyperframes 0.9.1 → 0.9.3

package/skills/remotion-to-hyperframes/SKILL.md

@@ -1,132 +1,49 @@
 ---
 name: remotion-to-hyperframes
-description: 'Port an existing Remotion (React) composition''s source to HyperFrames HTML. Use ONLY on an explicit ask to port/convert/migrate/translate a Remotion source — one-way, Remotion-only. A passing Remotion mention, reference-only code, or "make something like my Remotion video" is a fresh build (/general-video). Unclear → /hyperframes.'
+description: Bring existing video code or footage into HyperFrames and verify it frame by frame against the original - Remotion first, also Motion Canvas, Lottie, Three.js, p5.js, canvas or plain HTML/CSS animation, or renders from Manim, After Effects or Blender. Use to port, convert, migrate or reuse work made with another tool.
 ---
 
-**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin. Standalone installs keep the update instructions below.
+**Plugin installs:** Before setup or freshness commands, follow [plugin execution rules](../hyperframes/references/plugin-installation.md) when this skill is inside a HyperFrames plugin.
 
-> **First, keep this skill fresh — confirm with the user before running:** `npx hyperframes skills update remotion-to-hyperframes`. A fast no-op when everything is current; otherwise it refreshes this skill plus the core domain skills it depends on before you rely on them.
+# Import into HyperFrames
 
-# Remotion to HyperFrames
+HyperFrames is the container: its tracks, sub-compositions and variables are editable in Studio whatever runs inside a clip. Bring each part in at the highest level it supports and record which level you used.
 
-> **The front door is `/hyperframes`.** Use this **only** to port an existing **Remotion** (React) composition's source into HyperFrames, one way. Authoring a **new** composition, re-creating from a non-Remotion source (After Effects, Framer Motion, plain React / CSS — there is no Remotion source to translate), a passing Remotion mention, or any uncertainty → read `/hyperframes` first: the intent layer owns every route decision.
+| Level | For | How | Editable in Studio afterwards |
+| --- | --- | --- | --- |
+| Native | code that can become HTML + GSAP: most Remotion, HTML/CSS/GSAP animation, simple Motion Canvas | translate it, then verify frame by frame | every element; variables, catalog, presets apply |
+| Hosted | code that can draw any requested frame in a browser: canvas, p5.js, Three.js, Lottie, WebGL, other JS animation | keep the code and drive it from HyperFrames time | timing, position, exposed parameters |
+| Media | anything that outputs video or frames: Manim, After Effects, Blender, PIL, moviepy | render to a file and use it as a clip | cut, place, layer; not the pixels inside |
 
-## Overview
+Code that depends on wall-clock time, live physics or the network can only come in as media.
 
-Translate Remotion (React-based) video compositions into HyperFrames (HTML + GSAP) compositions. Most Remotion idioms have direct HyperFrames equivalents — the translation is mechanical for ~80% of typical compositions. This skill encodes the mapping and guards against the lossy 20% by refusing to translate patterns that don't fit HF's seek-driven model and recommending the runtime interop pattern from [PR #214](https://github.com/heygen-com/hyperframes/pull/214) instead.
+## Native: translate, then verify
 
-The skill ships with a **tiered test corpus** (T1–T4, 4 fixtures total) that grades translations against measured SSIM thresholds. Don't translate without running the eval — a translation that "looks right" but renders 0.05 SSIM lower than the validated baseline is silently wrong.
+1. For Remotion, run `python3 <SKILL_DIR>/scripts/lint_source.py <source dir>` first. Blockers (`useState`, `useReducer`, `useEffect` with dependencies, async `calculateMetadata`, React UI kits such as MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI) don't translate: host them or refactor them out, never approximate (`references/escape-hatch.md`). Warnings (`@remotion/lambda` config, `delayRender`, `useMemo`, custom hooks) are dropped and noted.
+2. Translate to the `/hyperframes` contract: one sub-composition per scene, times in seconds (`frame / fps`), asset paths root-relative. Each Remotion API's equivalent is in `references/api-map.md`. Put Remotion's render-page rule `* { box-sizing: border-box; }` once in the root `index.html` `<style>`: without it every bordered or padded element grows by its border and padding.
+3. Keep it editable: the source's props become `data-composition-variables` bound with `data-var-text`, `data-var-src` or `var(--id)`; each `Sequence` becomes a timed clip or a sub-composition; a reused component becomes one sub-composition mounted several times with `data-variable-values`.
+4. Compare frame by frame: `npx hyperframes snapshot --at <t,…> --against <original.mp4>` saves the original's frame at each time next to yours. Sample every scene and both sides of every cut; look for one late or recoloured element, not only the overall picture. For a scored check, `scripts/render_diff.sh <original.mp4> <hf.mp4> <out>` gives SSIM per frame and `scripts/frame_strip.sh` shows which frames diverged (thresholds per complexity tier in `references/eval.md`). Render the Remotion side with `Config.setVideoImageFormat("png")` and `Config.setColorSpace("bt709")`, or the diff measures the encoders (about 0.05 SSIM).
+5. Write what didn't translate cleanly (dropped volume ramps, approximated presentations, substituted fonts) to `TRANSLATION_NOTES.md`.
 
-## When to use
+| Remotion | Read |
+| --- | --- |
+| `Composition`, `defaultProps`, `schema`, `calculateMetadata` | `references/parameters.md` |
+| `Sequence`, `Series`, `Loop`, `AbsoluteFill`, `Freeze` | `references/sequencing.md` |
+| `useCurrentFrame`, `interpolate`, `spring`, `Easing`, `interpolateColors` | `references/timing.md` |
+| `Audio`, `Video`, `Img`, `IFrame`, `staticFile`, `delayRender` | `references/media.md` |
+| `TransitionSeries`, `@remotion/transitions` | `references/transitions.md` |
+| `@remotion/lottie` | `references/lottie.md` |
+| `@remotion/google-fonts`, `Font.loadFont`, `@font-face` | `references/fonts.md` |
+| What can't be ported | `references/limitations.md` |
 
-**Use this skill ONLY when the user explicitly asks to migrate from Remotion.** Example trigger phrases:
+Before hand-building a named visual the source used, search `npx hyperframes catalog --query "<the visual, in English>" --json`: it ranks the whole registry with nothing installed.
 
-- "port my Remotion project to HyperFrames"
-- "convert this Remotion code to HyperFrames"
-- "migrate from Remotion"
-- "translate this Remotion comp"
-- "rewrite this as HyperFrames HTML"
+## Hosted
 
-**Do NOT use this skill when:**
+Keep the code and let HyperFrames own the clock: it draws the frame for the time it is given. The seek protocol and the built-in adapters for Lottie, Three.js, anime.js, WAAPI and CSS animations are in `../hyperframes/references/runtimes.md`. No `requestAnimationFrame` loop or timer as the time source, seeded randomness only, and `data-duration` on the root when nothing else defines the length.
 
-- (a) The user is authoring a **new** HyperFrames composition, even if they have or are A/B-testing a similar Remotion video.
-- (b) The user mentions Remotion in passing without asking for migration.
-- (c) The user shares Remotion code as reference material rather than asking for a translation.
-- (d) The user asks for "the same video as my Remotion one" without explicitly asking to migrate the source — treat that as a fresh HyperFrames build.
+## Media
 
-**NOT SUPPORTED (decline — this is not what this skill does):**
+`<video class="clip" data-has-audio="true" src="assets/x.mp4" ...>`, or `muted` when it is silent. Nothing else is needed.
 
-- **The reverse direction.** Exporting a HyperFrames composition back out _to_ Remotion (or to any other framework) is not a workflow — the translation is Remotion → HyperFrames only. Say so plainly.
-- **Non-Remotion sources.** An After Effects project (`.aep`), a Framer Motion / plain-React / CSS animation, or any other tool's source is not a Remotion composition — there is no Remotion source to translate. Re-create it natively via `/general-video`, or decline if HyperFrames can't represent it.
-
-When in doubt, default to authoring a native HyperFrames composition with `/general-video` (the general HyperFrames authoring flow) instead.
-
-## Workflow
-
-### Step 1: Lint the source
-
-Run [`scripts/lint_source.py`](scripts/lint_source.py) over the Remotion source directory. The lint detects patterns that can't translate cleanly:
-
-- **Blockers** (refuse + recommend interop): `useState`, `useReducer`, `useEffect`/`useLayoutEffect` with non-empty deps, async `calculateMetadata`, third-party React UI libraries (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI).
-- **Warnings** (translate after dropping the construct): `@remotion/lambda` config, `delayRender`, `useCallback`, `useMemo`, custom hooks.
-- **Info** (translate with note): `staticFile`, `interpolateColors`.
-
-If any blocker fires, **stop**. Read [`references/escape-hatch.md`](references/escape-hatch.md) and surface the recommendation message. Warnings don't stop translation — drop the offending construct in step 3 and note the gap in `TRANSLATION_NOTES.md`. `@remotion/lambda` config is the canonical warning case: the skill drops the import + `renderMediaOnLambda(...)` calls but translates the rest of the composition.
-
-### Step 2: Plan the translation
-
-Read [`references/api-map.md`](references/api-map.md) — the index of every Remotion API and its HF equivalent or per-topic reference. Identify which topic references you'll need based on what the source uses:
-
-| Source contains                                                           | Load reference                                |
-| ------------------------------------------------------------------------- | --------------------------------------------- |
-| `Composition`, `defaultProps`, `schema`, `calculateMetadata`              | [`parameters.md`](references/parameters.md)   |
-| `Sequence`, `Series`, `Loop`, `AbsoluteFill`, `Freeze`                    | [`sequencing.md`](references/sequencing.md)   |
-| `useCurrentFrame`, `interpolate`, `spring`, `Easing`, `interpolateColors` | [`timing.md`](references/timing.md)           |
-| `Audio`, `Video`, `Img`, `IFrame`, `staticFile`, `delayRender`            | [`media.md`](references/media.md)             |
-| `TransitionSeries`, `@remotion/transitions`                               | [`transitions.md`](references/transitions.md) |
-| `@remotion/lottie`                                                        | [`lottie.md`](references/lottie.md)           |
-| `@remotion/google-fonts/<Family>`, `Font.loadFont`, `@font-face`          | [`fonts.md`](references/fonts.md)             |
-
-Don't load all of them — load only what the specific source needs.
-
-**Search the live catalog for any visual effect the table does not map.** When the source paints a look with no HF API equivalent — a scanline/CRT overlay, a glitch or chromatic-aberration pass, a shader wipe, a film-grain treatment — run `npx hyperframes catalog --query "<the effect, in plain English>" --json` before hand-writing it in GSAP. The search needs **nothing installed**: no project, no prior `add`, no account. It ranks the whole hosted registry (~400 blocks and components) from any directory, and `transitions.md` already takes this route for `clockWipe()` / `iris()` via `npx hyperframes add sdf-iris`. A real component is closer to the source than a hand-approximation, so it usually raises the SSIM rather than lowering it — but the render diff in Step 4 is still the arbiter. Hand-write the effect when a search returns nothing that fits, and record the substitution in `TRANSLATION_NOTES.md` either way.
-
-### Step 3: Generate the HF composition
-
-Emit `index.html` with:
-
-- Root `<div id="stage">` carrying the composition's `data-composition-id`, `data-start="0"`, `data-duration` (in seconds), `data-fps`, `data-width`, `data-height`, plus one `data-*` per scalar prop.
-- One host `<div>` per scene with `data-composition-src="compositions/<scene>.html"` and `data-start` / `data-duration` / `data-track-index`. The root holds no nested layout.
-- One `compositions/<scene>.html` per scene (a `<template>` sub-composition): its inline `<style>` for layout (CSS sets the `from` state of every animated property), its markup, and one paused `gsap.timeline({paused: true})` in the scene's local time. Every Remotion `useCurrentFrame()` derivation becomes a tween on that timeline at the offset within the scene.
-- `window.__timelines["<scene-id>"] = tl;` in each scene file, and `window.__timelines["<composition-id>"]` for the root's own (possibly empty) timeline.
-
-Custom React subcomponents inline as repeated HTML using the prop interface as the template (see [`parameters.md`](references/parameters.md) for the per-instance `data-*` pattern).
-
-### Step 4: Validate
-
-Run the eval harness — [`references/eval.md`](references/eval.md) for the full guide. Quick path:
-
-```bash
-# Render Remotion baseline (after npm install in the fixture)
-cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4
-
-# Render HF translation
-cd ../hf-src && npx hyperframes render --skill=remotion-to-hyperframes --output ../hf.mp4
-
-# SSIM diff
-../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff
-```
-
-Threshold: ~0.02 below `p05` of the source's complexity tier (see `eval.md`'s validated thresholds table). If the diff fails, run [`scripts/frame_strip.sh`](scripts/frame_strip.sh) to see _which_ frames diverged, then re-read the relevant timing/sequencing/media reference.
-
-**Critical**: both renders must use matching pixel format. Set `Config.setVideoImageFormat("png")` + `Config.setColorSpace("bt709")` in the Remotion source's `remotion.config.ts` — otherwise the diff measures encoder differences (~0.05 SSIM hit), not translation fidelity.
-
-### Step 5: Document gaps
-
-Anything that didn't translate cleanly (volume ramps dropped, custom presentations approximated, fonts substituted) gets a `TRANSLATION_NOTES.md` written next to the HF output. See [`references/limitations.md`](references/limitations.md) for the format.
-
-## What this skill explicitly does NOT do
-
-- **Translate React state machines.** Compositions that drive animation via `useState` + `useEffect` are not deterministic frame-capture targets in HyperFrames' seek-driven model. Recommend the runtime interop pattern.
-- **Run Remotion's render pipeline alongside HyperFrames.** That's the runtime interop pattern from [PR #214](https://github.com/heygen-com/hyperframes/pull/214) — a separate solution for compositions that fail this skill's lint.
-
-(`@remotion/lambda` is _not_ a blocker — Lambda config is deployment, not animation. The skill drops it as a warning and translates the rest. See [`references/escape-hatch.md`](references/escape-hatch.md).)
-
-## How to grade your own translation
-
-Run the test corpus orchestrator:
-
-```bash
-./assets/test-corpus/run.sh
-```
-
-It runs T1, T2, T3 (render + diff) and T4 (lint validation), prints a per-tier pass/fail table, and emits an aggregate JSON report. Use this to verify the skill is working end-to-end on a clean checkout — and as a regression check after editing any reference.
-
-Validated baseline (as of 2026-04-27):
-
-| Tier | Composition shape                           | Mean SSIM | Threshold |
-| ---- | ------------------------------------------- | --------- | --------- |
-| T1   | single-element fade-in                      | 0.974     | 0.95      |
-| T2   | multi-scene + spring + audio + image        | 0.985     | 0.95      |
-| T3   | data-driven, custom subcomponents, count-up | 0.953     | 0.90      |
-| T4   | escape-hatch (8 lint cases)                 | 8/8 pass  | n/a       |
+In the final message, list each imported part with its level, what a person can change in Studio, and how the frame-by-frame comparison came out.

package/skills/remotion-to-hyperframes/assets/test-corpus/tier-1-title-card/hf-src/index.html

@@ -5,6 +5,9 @@
     <title>tier-1-title-card</title>
     <script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js"></script>
     <style>
+      * {
+        box-sizing: border-box;
+      }
       html,
       body {
         margin: 0;

package/skills/remotion-to-hyperframes/assets/test-corpus/tier-2-multi-scene/hf-src/index.html

@@ -5,6 +5,9 @@
     <title>tier-2-multi-scene</title>
     <script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js"></script>
     <style>
+      * {
+        box-sizing: border-box;
+      }
       html,
       body {
         margin: 0;

package/skills/remotion-to-hyperframes/assets/test-corpus/tier-3-data-driven/README.md

@@ -44,10 +44,10 @@ value from `useCurrentFrame()` + a manual `1 - (1 - t)^3` ease.
    exactly — costs ~0.03 mean SSIM per spring instance.
 
 2. **Count-up easing**: `AnimatedNumber` uses `1 - (1 - t)^3` (cubic ease-out)
-   manually computed in the component. GSAP's `power3.out` is the same curve
-   shape — should match closely. The displayed integer is rounded each frame
-   in both renderers; minor mismatches occur when the rounded value flips
-   between two numbers on a sub-frame timing difference.
+   manually computed in the component. GSAP's `power2.out` matches that cubic curve
+   exactly (`power3.out` is quartic). Compare the rounded integers at matching
+   frame times in both renderers; matching final values alone does not validate
+   the easing curve.
 
 3. **Font rendering**: same caveat as T1/T2. System Helvetica/Arial fallback
    produces minor anti-aliasing differences between renderers. Affects the
@@ -55,8 +55,9 @@ value from `useCurrentFrame()` + a manual `1 - (1 - t)^3` ease.
 
 A mean SSIM below 0.90 in T3 indicates a _structural_ mismatch (wrong scene
 durations, wrong stagger timing, missing prop wiring), not approximation
-drift. That's the failure signal we care about. The calibrated mean against
-Remotion @ 4.0 with PNG/BT.709 output is 0.953.
+drift. That's the failure signal we care about. The September 18 measurement
+against Remotion @ 4.0 with PNG/BT.709 output was 0.953 for the quartic
+translation; it does not measure the corrected cubic count-up.
 
 ## Translation walk-through (skill cheat sheet)
 
@@ -65,7 +66,7 @@ Remotion @ 4.0 with PNG/BT.709 output is 0.953.
 | `<Composition schema={z.object({...})} defaultProps={...} />`               | data-\* attributes on root `#stage` div                                               |
 | nested array prop (`stats[]`)                                               | repeated HTML markup with per-instance `data-*` attrs                                 |
 | custom React subcomponent                                                   | inline repeated HTML using the component's prop interface as the template             |
-| `<AnimatedNumber from={0} to={value} dur={45} />` (cubic ease-out count-up) | tween on `{ v: 0 }` object with `onUpdate` rewriting `textContent`, ease `power3.out` |
+| `<AnimatedNumber from={0} to={value} dur={45} />` (cubic ease-out count-up) | tween on `{ v: 0 }` object with `onUpdate` rewriting `textContent`, ease `power2.out` |
 | `spring({damping:12, stiffness:100})`                                       | `back.out(1.4)` over ~0.7 s                                                           |
 | `spring({damping:14, stiffness:90})`                                        | `back.out(1.2)` over ~0.7 s                                                           |
 | `delayInFrames={i * 12}` (per-instance)                                     | GSAP timeline offset `(i * 0.4)` s                                                    |

package/skills/remotion-to-hyperframes/assets/test-corpus/tier-3-data-driven/expected.json

@@ -15,7 +15,7 @@
     "measured_p95_ssim": 0.978,
     "measured_at": "2026-09-18",
     "measured_against": "remotion@4.0 (PNG output, BT.709) vs hyperframes@0.7.71 (sub-composition fixtures)",
-    "notes": "Count-up timing in StatsScene shows a few-frame offset between Remotion's manual 1-(1-t)^3 and GSAP's power3.out — both formulas are identical, so the offset comes from sub-frame timing of when the seek + onUpdate fire. Final values converge correctly. Visible only as transient digit mismatches mid-animation; no SSIM impact above the noise floor."
+    "notes": "The September 18 SSIM measurements describe the quartic power3.out translation. The count-up fixture uses power2.out to match the cubic 1-(1-t)^3 curve exactly; those historical scores do not measure the corrected curve. Check rounded counts at matching frame times in addition to SSIM."
   },
   "remotion_apis_exercised": [
     "Composition with z.object schema and typed defaultProps",
@@ -32,10 +32,10 @@
   "translation_notes": [
     "Zod schema + defaultProps → data-* attributes on the root #stage div. The skill emits one data attribute per scalar prop; nested arrays (stats[]) get materialized as repeated HTML markup with per-instance data attributes (data-stat-index, data-stat-value, --card-color).",
     "Custom React subcomponents inline as repeated HTML divs. The component prop interface becomes the repeated markup template. This is lossy for components with internal state — fine here because StatCard, AnimatedNumber, UnderlinedText all derive from props alone.",
-    "AnimatedNumber's frame-driven count-up → a GSAP tween on a { v: 0 } counter object with onUpdate rewriting textContent. GSAP's power3.out is cubic easeOut, matching the Remotion 1-(1-t)^3 manual ease.",
+    "AnimatedNumber's frame-driven count-up → a GSAP tween on a { v: 0 } counter object with onUpdate rewriting textContent. GSAP's power2.out is cubic easeOut, matching the Remotion 1-(1-t)^3 manual ease.",
     "Two different springs in this composition: damping:12 → back.out(1.4) (snappy), damping:14 → back.out(1.2) (calmer). The 1.4 vs 1.2 overshoot ratio approximates the damping difference.",
     "Per-instance stagger via delayInFrames prop translates to a GSAP timeline offset of (i * 0.4)s.",
-    "Threshold 0.90 reflects: spring → back.out approximation (×2 different configs), the count-up easing curve match (very close but not identical due to sub-frame seek timing), font/AA differences on body text. SSIM well below 0.90 indicates a structural mismatch, not approximation drift."
+    "Threshold 0.90 allows spring → back.out approximation (two different configs) and font/AA differences on body text. The cubic count-up curve matches exactly; evaluate rounded counts at matching frame times separately from SSIM."
   ],
   "rationale": "Threshold 0.90 sits ~0.04 below measured p05 (0.938). The wider gap vs T1/T2 reflects T3's bigger approximation budget (2 spring instances + count-up timing + font fallback on multiple text sizes). Mean SSIM below 0.90 = structural mismatch (wrong durations, wrong stagger, missing prop wiring), not approximation drift."
 }

package/skills/remotion-to-hyperframes/assets/test-corpus/tier-3-data-driven/hf-src/compositions/scene-1.html

@@ -16,7 +16,6 @@
         font-size: 160px;
         font-weight: 900;
         letter-spacing: 0.05em;
-        transform: scale(0);
       }
       .scene-1 .subtitle {
         font-size: 36px;
@@ -36,7 +35,12 @@
       const scene = document.querySelector(".scene-1");
       tl.set(scene, { opacity: 1 }, 0);
       // spring({damping:12, stiffness:100, mass:1}) -> back.out(1.4) ~0.7s
-      tl.to(scene.querySelector(".title"), { scale: 1, duration: 0.7, ease: "back.out(1.4)" }, 0);
+      tl.fromTo(
+        scene.querySelector(".title"),
+        { scale: 0 },
+        { scale: 1, duration: 0.7, ease: "back.out(1.4)" },
+        0,
+      );
       // interpolate(frame, [20,40], [0,1]) -> 0.667s..1.333s linear
       tl.fromTo(
         scene.querySelector(".subtitle"),

package/skills/remotion-to-hyperframes/assets/test-corpus/tier-3-data-driven/hf-src/compositions/scene-2.html

@@ -23,7 +23,6 @@
         justify-content: center;
         align-items: center;
         opacity: 0;
-        transform: scale(0);
       }
       .stat-card .number {
         font-size: 72px;
@@ -74,16 +73,16 @@
         const value = Number(card.dataset.statValue);
         const numberEl = card.querySelector(".number");
         // spring({damping:14, stiffness:90, mass:1}) -> back.out(1.2) ~0.7s; opacity 0..0.4s linear
-        tl.to(card, { scale: 1, duration: 0.7, ease: "back.out(1.2)" }, start);
+        tl.fromTo(card, { scale: 0 }, { scale: 1, duration: 0.7, ease: "back.out(1.2)" }, start);
         tl.to(card, { opacity: 1, duration: 0.4, ease: "none" }, start);
-        // AnimatedNumber: easeOutCubic over 45 frames (1.5s) is GSAP power3.out on a counter.
+        // AnimatedNumber: easeOutCubic over 45 frames (1.5s) is GSAP power2.out on a counter.
         const counter = { v: 0 };
         tl.to(
           counter,
           {
             v: value,
             duration: 1.5,
-            ease: "power3.out",
+            ease: "power2.out",
             onUpdate: () => {
               numberEl.textContent = Math.round(counter.v).toLocaleString();
             },

package/skills/remotion-to-hyperframes/assets/test-corpus/tier-3-data-driven/hf-src/compositions/scene-3.html

@@ -26,7 +26,6 @@
         height: 6px;
         background: #fbbf24;
         border-radius: 3px;
-        transform: scaleX(0);
         transform-origin: left center;
       }
     </style>
@@ -43,8 +42,9 @@
       tl.set(scene, { opacity: 1 }, 0);
       tl.to(scene.querySelector(".outro-wrap"), { opacity: 1, duration: 0.4, ease: "none" }, 0);
       // interpolate(frame, [10,40], [0,1]) for the underline -> starts 0.333s, 1s long
-      tl.to(
+      tl.fromTo(
         scene.querySelector(".outro-underline"),
+        { scaleX: 0 },
         { scaleX: 1, duration: 1.0, ease: "none" },
         0.333,
       );

package/skills/remotion-to-hyperframes/assets/test-corpus/tier-3-data-driven/hf-src/index.html

@@ -5,6 +5,9 @@
     <title>tier-3-data-driven</title>
     <script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js"></script>
     <style>
+      * {
+        box-sizing: border-box;
+      }
       html,
       body {
         margin: 0;

package/skills/remotion-to-hyperframes/references/api-map.md

@@ -13,15 +13,27 @@ details (timing, transitions, etc.).
 
 ## Composition root
 
-| Remotion                                             | HyperFrames                                                                                                          |
-| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
-| `<Composition id durationInFrames fps width height>` | root `<div id="stage" data-composition-id data-start="0" data-duration="<dur/fps>" data-fps data-width data-height>` |
-| `defaultProps={...}`                                 | `data-*` attributes on `#stage` (one per scalar prop). Nested objects/arrays — see [parameters.md](parameters.md)    |
-| `schema={z.object(...)}`                             | not represented in HTML; the schema lives in the agent's translation step only                                       |
-| `calculateMetadata` (sync)                           | resolve at translation time, write concrete values into `data-*`                                                     |
-| `calculateMetadata` (async)                          | **refuse + interop** — see [escape-hatch.md](escape-hatch.md)                                                        |
-| `registerRoot(RemotionRoot)`                         | drop                                                                                                                 |
-| `<AbsoluteFill style>`                               | `<div style="position:absolute;inset:0;{style}">`                                                                    |
+| Remotion                                               | HyperFrames                                                                                                          |
+| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `<Composition id durationInFrames fps width height>`   | root `<div id="stage" data-composition-id data-start="0" data-duration="<dur/fps>" data-fps data-width data-height>` |
+| `defaultProps={...}`                                   | `data-*` attributes on `#stage` (one per scalar prop). Nested objects/arrays — see [parameters.md](parameters.md)    |
+| `schema={z.object(...)}`                               | not represented in HTML; the schema lives in the agent's translation step only                                       |
+| `calculateMetadata` (sync)                             | resolve at translation time, write concrete values into `data-*`                                                     |
+| `calculateMetadata` (async)                            | **refuse + interop** — see [escape-hatch.md](escape-hatch.md)                                                        |
+| `registerRoot(RemotionRoot)`                           | drop                                                                                                                 |
+| `<AbsoluteFill style>`                                 | `<div style="position:absolute;inset:0;{style}">`                                                                    |
+| Remotion's render page: `* { box-sizing: border-box }` | the same rule, once, in the root `index.html` `<style>` (see below)                                                  |
+
+Remotion's render page sets `* { box-sizing: border-box }`, so a `width` there already includes the border and padding. A browser's own default is `content-box`, so a port without the rule draws every bordered or padded element larger. This box is 200 by 100 in Remotion and with the rule; without it, it is 260 by 160:
+
+```html
+<style>
+  * {
+    box-sizing: border-box;
+  }
+</style>
+<div style="width:200px;height:100px;padding:20px;border:10px solid #fff">…</div>
+```
 
 ## Sequencing
 
@@ -38,31 +50,31 @@ See [sequencing.md](sequencing.md) for nesting and stagger details.
 
 See [timing.md](timing.md) — this is the highest-leverage section.
 
-| Remotion                                                   | HyperFrames                                                                                                        |
-| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
-| `useCurrentFrame()`                                        | drop — HF seeks the timeline. The math derived from `frame` becomes an animatable property of a paused GSAP tween. |
-| `useVideoConfig()` for `fps` / `durationInFrames`          | drop — read from `data-fps` / `data-duration` on `#stage`                                                          |
-| `interpolate(frame, [a,b], [x,y])` (linear)                | `gsap.fromTo(t, {p:x}, {p:y, duration:(b-a)/fps, ease:"none"})` at offset `a/fps`                                  |
-| `interpolate(frame, [a,b,c,d], [x,y,y,z])` (multi-segment) | three `gsap.to` calls at offsets `a/fps`, `b/fps`, `c/fps`                                                         |
-| `interpolate(..., {easing: Easing.bezier})`                | GSAP `CustomEase.create("c", "M0,0 C${a},${b} ${c},${d} 1,1")`                                                     |
-| `spring({frame, fps, config: {damping, stiffness, mass}})` | GSAP `back.out(N)` — see [timing.md](timing.md) for damping → overshoot table                                      |
-| `interpolateColors(frame, range, colors)`                  | `gsap.to({...}, { backgroundColor, color, duration, ease })` — GSAP handles color tweens natively                  |
-| `Easing.in / .out / .inOut(power)`                         | GSAP `power<N>.in` / `power<N>.out` / `power<N>.inOut`                                                             |
+| Remotion                                                   | HyperFrames                                                                                                                    |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `useCurrentFrame()`                                        | drop — HF seeks the timeline. The math derived from `frame` becomes an animatable property of a paused GSAP tween.             |
+| `useVideoConfig()` for `fps` / `durationInFrames`          | drop — read from `data-fps` / `data-duration` on `#stage`                                                                      |
+| `interpolate(frame, [a,b], [x,y])` (linear)                | `gsap.fromTo(t, {p:x}, {p:y, duration:(b-a)/fps, ease:"none"})` at offset `a/fps`                                              |
+| `interpolate(frame, [a,b,c,d], [x,y,y,z])` (multi-segment) | three `gsap.to` calls at offsets `a/fps`, `b/fps`, `c/fps`                                                                     |
+| `interpolate(..., {easing: Easing.bezier})`                | GSAP `CustomEase.create("c", "M0,0 C${a},${b} ${c},${d} 1,1")`                                                                 |
+| `spring({frame, fps, config: {damping, stiffness, mass}})` | GSAP `back.out(N)` — see [timing.md](timing.md) for damping → overshoot table                                                  |
+| `interpolateColors(frame, range, colors)`                  | `gsap.to({...}, { backgroundColor, color, duration, ease })` — GSAP handles color tweens natively                              |
+| `Easing.in / .out / .inOut(Easing.poly(N))`                | GSAP `power<N-1>.in` / `power<N-1>.out` / `power<N-1>.inOut` for integer N=1–5; see [timing.md](timing.md) for other exponents |
 
 ## Media
 
 See [media.md](media.md) for trim, volume ramps, and decoder notes.
 
-| Remotion                               | HyperFrames                                                                                                                                      |
-| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `<Audio src volume>`                   | `<audio data-start data-duration data-track-index data-volume src>`                                                                              |
-| `<Audio playbackRate startFrom endAt>` | `data-playback-rate`, `data-trim-start`, `data-trim-end`                                                                                         |
-| `<Video src>`                          | `<video muted playsinline data-start data-duration data-track-index src>`                                                                        |
-| `<OffthreadVideo>`                     | `<video>` — HF doesn't need the off-thread variant (uses headless Chrome)                                                                        |
-| `<Img src>`                            | `<img>`                                                                                                                                          |
-| `<IFrame src>`                         | `<iframe>` — HF auto-falls back to screenshot mode for nested iframes                                                                            |
-| `staticFile("x.png")`                  | `"assets/x.png"` in the root, `"../assets/x.png"` inside a `compositions/` scene file — copy the file into `hf-src/assets/` next to `index.html` |
-| `delayRender()` / `continueRender()`   | drop — HF waits on asset readiness via the Frame Adapter pattern                                                                                 |
+| Remotion                               | HyperFrames                                                                                                                                                                                                                                                                                                                                  |
+| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `<Audio src volume>`                   | `<audio data-start data-duration data-track-index data-volume src>`                                                                                                                                                                                                                                                                          |
+| `<Audio playbackRate startFrom endAt>` | `data-playback-rate`, `data-trim-start`, `data-trim-end`                                                                                                                                                                                                                                                                                     |
+| `<Video src>`                          | `<video playsinline data-has-audio="true" data-start data-duration data-track-index src>` only when the file has an audio stream (check with `ffprobe -v error -select_streams a -show_entries stream=codec_type -of csv=p=0 <file>`: non-empty means it has audio) and the source is not `muted` or `volume={0}`; otherwise `muted` instead |
+| `<OffthreadVideo>`                     | `<video>` — HF doesn't need the off-thread variant (uses headless Chrome)                                                                                                                                                                                                                                                                    |
+| `<Img src>`                            | `<img>`                                                                                                                                                                                                                                                                                                                                      |
+| `<IFrame src>`                         | `<iframe>` — HF auto-falls back to screenshot mode for nested iframes                                                                                                                                                                                                                                                                        |
+| `staticFile("x.png")`                  | `"assets/x.png"` in the root, `"../assets/x.png"` inside a `compositions/` scene file — copy the file into `hf-src/assets/` next to `index.html`                                                                                                                                                                                             |
+| `delayRender()` / `continueRender()`   | drop — HF waits on asset readiness via the Frame Adapter pattern                                                                                                                                                                                                                                                                             |
 
 ## Transitions
 

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

@@ -32,7 +32,7 @@ Remotion accepts a function for `volume`:
 ```
 
 HF ramps volume with a `data-automation` volume lane on the `<audio>`
-(form in `hyperframes-core/references/creator-editing-recipes.md`).
+(form in `/media-use` → `references/mixing.md`).
 Translation: write the lane from the `interpolate` points, OR bake the ramp
 into the audio file with `ffmpeg afade`. The dropped-ramp path produces audibly different
 output but visually-identical video, so SSIM passes — just flag it.
@@ -48,7 +48,7 @@ output but visually-identical video, so SSIM passes — just flag it.
 A bounded GSAP repeat can reproduce _visual_ repetition when its finite count is derived
 from the visible duration. 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; never use `repeat: -1`.
+is fully deterministic per-iteration; use `repeat: -1` only when the root declares a finite `data-duration`.
 
 ### Remotion's `<Img>` with crossOrigin
 
@@ -122,7 +122,7 @@ a `TRANSLATION_NOTES.md` next to the output:
 The following Remotion patterns were translated with caveats:
 
 - `<Audio volume={(f) => ...}>` (line 15): volume ramp written as a
-  `data-automation` volume lane (see `creator-editing-recipes.md`); the
+  `data-automation` volume lane (see the media-use skill's mixing reference); the
   ffmpeg `afade` bake-in is the alternative.
 - `<HeavyChart>` (line 30): translated as inline HTML. The original
   React.lazy boundary was dropped — bundle size unchanged because HF

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

@@ -4,7 +4,7 @@ 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`.
+and seeks lottie-web via `goToAndStop` and current dotLottie players via `setFrame`.
 
 ## Pattern
 
@@ -51,27 +51,40 @@ Key differences from a typical Lottie embed:
 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`.
+1. Copy the animation JSON from the Remotion project into the HyperFrames project’s assets folder.
+2. Pass that local path to `loadAnimation`, as shown in the example above.
 
-For dotlottie (binary) format, swap in `@lottiefiles/dotlottie-web`:
+For dotlottie (binary) format, use the ESM build of `@lottiefiles/dotlottie-web`.
+Before rendering, copy `dist/index.js` and `dist/dotlottie-player.wasm` from the
+same pinned release into `hf-src/lib/dotlottie-web/`. Version 0.81.0 provides:
+
+- https://unpkg.com/@lottiefiles/dotlottie-web@0.81.0/dist/index.js
+- https://unpkg.com/@lottiefiles/dotlottie-web@0.81.0/dist/dotlottie-player.wasm
+
+The package's CommonJS entry cannot run as a classic browser script. Set the
+local WASM URL before constructing the player; the render then loads the SDK,
+WASM and animation from project files.
 
 ```html
-<script src="https://unpkg.com/@lottiefiles/dotlottie-web"></script>
 <canvas id="anim" style="width:100%;height:100%"></canvas>
-<script>
+<script type="module">
+  import { DotLottie } from "./lib/dotlottie-web/index.js";
+
+  DotLottie.setWasmUrl(new URL("./lib/dotlottie-web/dotlottie-player.wasm", import.meta.url).href);
   const player = new DotLottie({
     canvas: document.getElementById("anim"),
     src: "assets/hello.lottie",
     autoplay: false,
+    loop: false,
+    renderConfig: { autoResize: false, freezeOnOffscreen: false },
   });
   window.__hfLottie = window.__hfLottie || [];
   window.__hfLottie.push(player);
 </script>
 ```
 
-The HF adapter handles both player APIs (it duck-types `goToAndStop`
-vs `setCurrentRawFrameValue` / `seek`).
+The HF adapter supports `goToAndStop` for lottie-web, `setFrame` for current
+dotLottie players, and `setCurrentRawFrameValue` / `seek` for older player shapes.
 
 ## Multiple Lottie animations
 

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

@@ -45,7 +45,7 @@ didn't specify trim.
 ```
 
 Volume ramps become a `data-automation` volume lane on the `<audio>`
-(form in `hyperframes-core/references/creator-editing-recipes.md`); `data-volume`
+(form in `/media-use` → `references/mixing.md`); `data-volume`
 is the static baseline.
 
 ### Trim / playbackRate
@@ -70,14 +70,25 @@ is the static baseline.
 ## `<Video>` and `<OffthreadVideo>`
 
 ```tsx
-<Video src={staticFile("intro.mp4")} muted playsInline />
-<OffthreadVideo src={staticFile("intro.mp4")} muted />
+<Video src={staticFile("intro.mp4")} playsInline />
+<OffthreadVideo src={staticFile("intro.mp4")} />
 ```
 
 ```html
+<!-- intro.mp4 has an audio stream -->
+<video
+  playsinline
+  data-has-audio="true"
+  data-start="0"
+  data-duration="5"
+  data-track-index="0"
+  src="assets/intro.mp4"
+></video>
+
+<!-- intro.mp4 is silent (or the Remotion element is muted) -->
 <video
-  muted
   playsinline
+  muted
   data-start="0"
   data-duration="5"
   data-track-index="0"
@@ -89,8 +100,14 @@ is the static baseline.
 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.
+`playsinline` is required for the runtime to autoplay (browser policy); always
+emit it. Check the source file for an audio stream first:
+`ffprobe -v error -select_streams a -show_entries stream=codec_type -of csv=p=0 <file>`
+(non-empty output means it has audio). Remotion `<Video>` maps to
+`<video playsinline>` + `data-has-audio="true"` only when the file has an audio
+stream and the Remotion source does not set `muted` or `volume={0}`; otherwise
+emit `muted`. Silent b-roll with `data-has-audio="true"` aborts the render
+(`ASSET_MEDIA_TYPE_MISMATCH`).
 
 ## `<Img>`