feat(skills): remotion-to-hyperframes references (6/7)

Adds 11 progressively-disclosed reference files that the skill loads on demand during translation. Total ~1500 LOC, every file under 200 lines (skill-creator's progressive-disclosure budget). api-map.md the comprehensive Remotion -> HF translation table (the index; loaded at start of translation) timing.md interpolate, spring (validated configs), easing, count-up, stagger sequencing.md Sequence, Series, Loop, Freeze, AbsoluteFill, Composition root media.md Audio, Video, Img, IFrame, OffthreadVideo, staticFile, asset paths transitions.md @remotion/transitions presentations -> manual GSAP crossfades or HF shader-transitions lottie.md @remotion/lottie -> HF lottie adapter (incl. AE feature limitations note) fonts.md Google Fonts loading, local @font-face, system fallback noise floor parameters.md Zod schemas, defaultProps, sync vs async calculateMetadata escape-hatch.md when to bow out + the runtime interop pattern from PR #214 limitations.md known caveat patterns (volume ramps, Loop with state, custom presentations, code-split components) eval.md how to run the validation harness, threshold rule of thumb, what the noise floor looks like The references are evidence-driven rather than speculative: every spring config, easing curve, and SSIM threshold is documented from the validated T1/T2/T3 calibration runs (mean 0.974 / 0.985 / 0.953). The escape-hatch boundaries match the lint blockers in PR 2 and the T4 fixtures in PR 5. Replaces the placeholder .gitkeep from PR 1.
2026-09-03 04:38:33 +00:00 · 2026-04-27 23:55:51 +00:00
parent 7509916227
commit 890f305cd1
12 changed files with 1554 additions and 0 deletions
@@ -0,0 +1,112 @@
+# Font translation
+
+Fonts are the dominant non-translation noise floor. Same `font-weight: 800`
+renders perceptibly bolder on HF's `chrome-headless-shell` than on
+Remotion's bundled Chromium when there's no real font installed. Validation
+showed this costs ~0.025 mean SSIM at the noise floor.
+
+## Pattern: `@remotion/google-fonts/<Family>`
+
+```tsx
+import { loadFont } from "@remotion/google-fonts/Inter";
+loadFont("normal", { weights: ["400", "800"] });
+```
+
+Translate to a `<link>` tag in `<head>`:
+
+```html
+<head>
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  <link
+    href="https://fonts.googleapis.com/css2?family=Inter:wght@400;800&display=swap"
+    rel="stylesheet"
+  />
+  <style>
+    body {
+      font-family: Inter, sans-serif;
+    }
+  </style>
+</head>
+```
+
+Pull the family name and weights from the import path and `loadFont`
+arguments. HF's compiler inlines the Google Fonts CSS at render time, so
+you don't pay a network round-trip per render.
+
+## Pattern: local fonts via `@font-face`
+
+```tsx
+import { Font } from "remotion";
+
+Font.loadFont("/MyFont.woff2", "MyFont");
+```
+
+Translate to a `@font-face` rule:
+
+```html
+<style>
+  @font-face {
+    font-family: "MyFont";
+    src: url("assets/MyFont.woff2") format("woff2");
+    font-weight: 400;
+    font-style: normal;
+  }
+</style>
+```
+
+Copy the font file into `hf-src/assets/` next to the HTML.
+
+## Pattern: system font fallback (no font load)
+
+```tsx
+<div style={{ fontFamily: "Helvetica, Arial, sans-serif" }}>...</div>
+```
+
+Same string in HF — but be aware: on Linux without a real Helvetica
+installed (typical CI environment), Remotion and HF fall back to
+_different_ sans-serif system fonts because they bundle different
+Chromium versions. This is the noise floor: ~0.025 mean SSIM cost,
+visible as different stroke widths at large font weights (800+).
+
+If matching the Remotion render exactly matters for a specific
+fixture, load the same font explicitly — don't rely on system
+fallback.
+
+## When in doubt: use Inter
+
+Inter renders identically across Chromium versions and is free.
+Translate any "system sans-serif" Remotion comp to Inter when you
+need to minimize font drift in the validation harness.
+
+## Font loading and `delayRender`
+
+Remotion uses `delayRender()` to defer the first frame until fonts
+load. HF's compiler inlines Google Fonts at compile time and waits
+on `@font-face` readiness via the Frame Adapter pattern — the
+`delayRender` call drops in translation. See [media.md](media.md).
+
+## Multi-weight loading
+
+When Remotion loads multiple weights:
+
+```tsx
+loadFont("normal", { weights: ["400", "500", "700", "800"] });
+```
+
+Inline all weights in the Google Fonts URL:
+
+```
+?family=Inter:wght@400;500;700;800&display=swap
+```
+
+Translation rule: enumerate every distinct `font-weight` value
+that appears in the composition's CSS (`font-weight: 800` →
+weight 800 must be loaded). If the Remotion source loads weights
+that aren't actually used, drop them.
+
+## Font subsetting
+
+Remotion's `loadFont` doesn't subset; HF's compiler doesn't either
+(yet). Don't try to optimize this in translation — it's lossless to
+keep the same weight set as the Remotion source.