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 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:

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, 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:

{
  "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:

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.