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.

skills/remotion-to-hyperframes/references/escape-hatch.md

@@ -0,0 +1,115 @@
+# When to bow out: the runtime interop pattern
+
+Some Remotion compositions can't be translated cleanly. The skill should
+recognize them upfront and recommend the **runtime interop pattern** from
+[PR #214](https://github.com/heygen-com/hyperframes/pull/214) instead of
+producing broken HTML.
+
+## When to recommend interop
+
+Run `scripts/lint_source.py` first. If it returns any blocker, recommend
+interop. The blockers are:
+
+| Rule                        | What it catches                                                |
+| --------------------------- | -------------------------------------------------------------- |
+| `r2hf/use-state`            | useState driving animation                                     |
+| `r2hf/use-reducer`          | useReducer driving animation                                   |
+| `r2hf/use-effect-deps`      | useEffect/useLayoutEffect with non-empty deps (side effects)   |
+| `r2hf/async-metadata`       | calculateMetadata returns a Promise                            |
+| `r2hf/third-party-react-ui` | Imports from MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI |
+
+Each of these breaks the seek-driven, deterministic-frame model that HF
+relies on. Translating them produces silently-wrong output.
+
+## What the interop pattern actually does
+
+Per [PR #214](https://github.com/heygen-com/hyperframes/pull/214), the
+runtime adapter:
+
+1. Bundles the user's Remotion code with React + `@remotion/player` via esbuild.
+2. Mounts a Remotion `<Player>` inside an HF composition's HTML.
+3. Pauses the player on mount.
+4. Registers the player on `window.__hfRemotion` with `seekTo(frame)`,
+   `pause()`, `durationInFrames`, `fps`.
+5. HF's render loop seeks the player frame-by-frame via `seekTo(frame)`.
+
+Result: Remotion's React tree renders at HF's deterministic frame ticks.
+Custom hooks, useState, useEffect, MUI components — all work because
+Remotion's React reconciler is doing the rendering.
+
+## The recommendation message
+
+When the skill detects a blocker, output something like:
+
+> The Remotion source uses `useState` (and others), which can't be
+> translated to HF's seek-driven HTML model. The recommended path is the
+> **runtime interop pattern**: bundle your Remotion code with `@remotion/player`
+> and let HF drive it frame-by-frame.
+>
+> See https://github.com/heygen-com/hyperframes/pull/214 for the full
+> implementation. Quick summary:
+>
+> 1. Bundle `entry.tsx` with esbuild: `npx esbuild entry.tsx --bundle --outfile=dist/bundle.js --format=iife --jsx=automatic`
+> 2. Mount the Player and register on `window.__hfRemotion`:
+>
+>    ```tsx
+>    const playerRef = useRef<PlayerRef>(null);
+>    useEffect(() => {
+>      playerRef.current?.pause();
+>      window.__hfRemotion = window.__hfRemotion || [];
+>      window.__hfRemotion.push({
+>        seekTo: (f) => playerRef.current?.seekTo(f),
+>        pause: () => playerRef.current?.pause(),
+>        durationInFrames,
+>        fps,
+>      });
+>    }, []);
+>    ```
+>
+> 3. Reference the bundle from your HF `index.html` and render normally:
+>    `<script src="dist/bundle.js"></script>`
+
+## The lint output already includes recommendations
+
+`lint_source.py` emits a `recommendation` field per finding. Surface those
+verbatim — they're tuned per blocker rule:
+
+```json
+{
+  "rule": "r2hf/use-state",
+  "message": "useState detected — Remotion compositions that drive animation via React state are not deterministic frame-capture targets in HyperFrames",
+  "recommendation": "Use the runtime interop pattern from PR #214 instead of attempting a translation"
+}
+```
+
+## When NOT to bow out: warnings only
+
+Some patterns produce warnings, not blockers — translate after dropping
+the wrappers:
+
+| Rule                      | Action                                                              |
+| ------------------------- | ------------------------------------------------------------------- |
+| `r2hf/lambda-import`      | drop the `@remotion/lambda` config; HF runs single-machine, log gap |
+| `r2hf/delay-render`       | drop the call; HF handles asset readiness                           |
+| `r2hf/use-callback`       | drop the wrapper, inline the function                               |
+| `r2hf/use-memo`           | drop the wrapper, compute inline                                    |
+| `r2hf/custom-hook` (pure) | inline the hook body if it's a derivation of `useCurrentFrame`      |
+| `r2hf/static-file`        | replace `staticFile("x")` with `"assets/x"`                         |
+| `r2hf/interpolate-colors` | translate to GSAP color tween (see [timing.md](timing.md))          |
+
+These are documented in T4 cases 05–07.
+
+`r2hf/lambda-import` is a warning — not a blocker — because Lambda
+configuration is orthogonal to the rendered composition. Translating an
+otherwise-clean Remotion comp shouldn't fail just because the author also
+configured AWS Lambda for distributed rendering. The skill drops the
+`@remotion/lambda` imports and `renderMediaOnLambda(...)` calls in step 3
+(Generate) and writes a `TRANSLATION_NOTES.md` entry so the user knows to
+set up HF rendering separately.
+
+## When the source has BOTH blockers AND warnings
+
+Bow out. The presence of a single blocker means the skill shouldn't
+attempt translation — even if the rest of the composition is clean.
+The user should use interop for the whole thing OR refactor the
+blocker patterns out of their Remotion source first.