takomi 2.5.1 → 2.5.4

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

@@ -1,142 +1,142 @@
-# Remotion → HyperFrames API Map
-
-Authoritative translation table. Load this reference when starting a translation
-to know the high-level mapping; load the per-topic references for fragile
-details (timing, transitions, etc.).
-
-## Reading this table
-
-- **`drop`** = remove from output entirely. The HF runtime handles it.
-- **`see references/X.md`** = the mapping is non-trivial; read the linked file.
-- **`refuse + interop`** = the skill bows out and recommends the runtime adapter
-  pattern from [PR #214](https://github.com/heygen-com/hyperframes/pull/214).
-
-## 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}">`                                                                    |
-
-## Sequencing
-
-See [sequencing.md](sequencing.md) for nesting and stagger details.
-
-| Remotion                                   | HyperFrames                                                                                               |
-| ------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
-| `<Sequence from={F} durationInFrames={D}>` | `<div data-start="<F/fps>" data-duration="<D/fps>" data-track-index="N">`                                 |
-| `<Series>` + `<Series.Sequence>`           | siblings with sequential `data-start` values                                                              |
-| `<Loop durationInFrames={D}>`              | not a primitive — emit a custom GSAP `repeat: -1` loop with manual offset math                            |
-| `<Freeze frame={F}>`                       | drop the wrapper; HF doesn't have running animation outside the seek-driven timeline so freeze is a no-op |
-
-## Timing
-
-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`                                                             |
-
-## 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"` — 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
-
-See [transitions.md](transitions.md).
-
-| Remotion                                                                       | HyperFrames                                                                                               |
-| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
-| `<TransitionSeries>` + `<TransitionSeries.Transition presentation={fade()} />` | manual `gsap.to(scene, {opacity: 0/1, duration})` crossfade at the boundary                               |
-| `slide()`, `wipe()`, `clockWipe()`, `fade()`                                   | HF [shader-transitions](https://hyperframes.heygen.com/catalog/blocks) package presets — pick the closest |
-| `linearTiming({durationInFrames})`                                             | duration in seconds (`/fps`)                                                                              |
-| `springTiming({config})`                                                       | duration in seconds, ease `back.out` — see [timing.md](timing.md)                                         |
-
-## Lottie
-
-See [lottie.md](lottie.md).
-
-| Remotion                        | HyperFrames                                                                                                       |
-| ------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `<Lottie animationData={data}>` | `<div id="lottie-N">` + `<script>const anim = lottie.loadAnimation({...}); window.__hfLottie.push(anim)</script>` |
-| `loop` / `playbackRate` props   | translate only after checking player seek behavior; HF adapter seeks absolute time via `goToAndStop`              |
-| `@remotion/lottie` runtime      | `lottie-web` from CDN — drop the React wrapper                                                                    |
-
-## Fonts
-
-See [fonts.md](fonts.md).
-
-| Remotion                                            | HyperFrames                                                                                 |
-| --------------------------------------------------- | ------------------------------------------------------------------------------------------- |
-| `loadFont()` from `@remotion/google-fonts/<Family>` | `@font-face` rule referencing the Google Fonts CSS, OR `<link>` to Google Fonts in `<head>` |
-| Local font via `@font-face`                         | same — paste the rule into `<style>`                                                        |
-| System font fallback                                | document the font-fallback divergence cost (see [eval.md](eval.md))                         |
-
-## Parameters
-
-See [parameters.md](parameters.md).
-
-| Remotion                      | HyperFrames                                                                                   |
-| ----------------------------- | --------------------------------------------------------------------------------------------- |
-| `z.object({foo: z.string()})` | `data-foo` on `#stage` (the schema is implicit in HTML structure)                             |
-| nested array prop (`stats[]`) | repeated HTML markup with per-instance `data-*` attrs                                         |
-| Zod default values            | bake defaults into the HTML directly                                                          |
-| Zod runtime validation        | not represented; if validation matters, validate in the translation step before emitting HTML |
-
-## React patterns
-
-| Remotion                                           | HyperFrames                                                      |
-| -------------------------------------------------- | ---------------------------------------------------------------- |
-| Custom React subcomponent (pure, prop-driven)      | inline as repeated HTML using the prop interface as the template |
-| `useState` driving animation                       | **refuse + interop**                                             |
-| `useReducer` driving animation                     | **refuse + interop**                                             |
-| `useEffect(fn, [deps])` (non-empty deps)           | **refuse + interop**                                             |
-| `useEffect(fn, [])` (mount-once side effect)       | drop the effect; use `queueMicrotask` if startup work is needed  |
-| `useCallback`, `useMemo`                           | drop the wrappers — decorative                                   |
-| Custom hook (pure derivation of `useCurrentFrame`) | inline the body                                                  |
-| Custom hook with state/effects                     | refuse + interop                                                 |
-
-## Distributed rendering
-
-`@remotion/lambda` and `@remotion/cloudrun` are deployment configuration —
-orthogonal to the rendered composition itself. The skill emits these as
-**warnings** (not blockers) and drops them in step 3 (Generate) with a note
-in `TRANSLATION_NOTES.md`. HF is single-machine today; document the gap.
-
-| Remotion                   | HyperFrames                                            |
-| -------------------------- | ------------------------------------------------------ |
-| `@remotion/lambda` import  | drop the import (warning `r2hf/lambda-import`)         |
-| `renderMediaOnLambda(...)` | drop the call; note in `TRANSLATION_NOTES.md`          |
-| `@remotion/cloudrun`       | drop the import + call; note in `TRANSLATION_NOTES.md` |
-
-## When to bow out entirely
-
-If any blocker pattern is present, recommend the runtime interop pattern from
-[PR #214](https://github.com/heygen-com/hyperframes/pull/214) instead of
-attempting translation. See [escape-hatch.md](escape-hatch.md).
-
-The blockers are documented in [`scripts/lint_source.py`](../scripts/lint_source.py)
-and tested by [tier-4-escape-hatch](../assets/test-corpus/tier-4-escape-hatch/).
+# Remotion → HyperFrames API Map
+
+Authoritative translation table. Load this reference when starting a translation
+to know the high-level mapping; load the per-topic references for fragile
+details (timing, transitions, etc.).
+
+## Reading this table
+
+- **`drop`** = remove from output entirely. The HF runtime handles it.
+- **`see references/X.md`** = the mapping is non-trivial; read the linked file.
+- **`refuse + interop`** = the skill bows out and recommends the runtime adapter
+  pattern from [PR #214](https://github.com/heygen-com/hyperframes/pull/214).
+
+## 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}">`                                                                    |
+
+## Sequencing
+
+See [sequencing.md](sequencing.md) for nesting and stagger details.
+
+| Remotion                                   | HyperFrames                                                                                               |
+| ------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `<Sequence from={F} durationInFrames={D}>` | `<div data-start="<F/fps>" data-duration="<D/fps>" data-track-index="N">`                                 |
+| `<Series>` + `<Series.Sequence>`           | siblings with sequential `data-start` values                                                              |
+| `<Loop durationInFrames={D}>`              | not a primitive — emit a custom GSAP `repeat: -1` loop with manual offset math                            |
+| `<Freeze frame={F}>`                       | drop the wrapper; HF doesn't have running animation outside the seek-driven timeline so freeze is a no-op |
+
+## Timing
+
+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`                                                             |
+
+## 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"` — 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
+
+See [transitions.md](transitions.md).
+
+| Remotion                                                                       | HyperFrames                                                                                               |
+| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
+| `<TransitionSeries>` + `<TransitionSeries.Transition presentation={fade()} />` | manual `gsap.to(scene, {opacity: 0/1, duration})` crossfade at the boundary                               |
+| `slide()`, `wipe()`, `clockWipe()`, `fade()`                                   | HF [shader-transitions](https://hyperframes.heygen.com/catalog/blocks) package presets — pick the closest |
+| `linearTiming({durationInFrames})`                                             | duration in seconds (`/fps`)                                                                              |
+| `springTiming({config})`                                                       | duration in seconds, ease `back.out` — see [timing.md](timing.md)                                         |
+
+## Lottie
+
+See [lottie.md](lottie.md).
+
+| Remotion                        | HyperFrames                                                                                                       |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `<Lottie animationData={data}>` | `<div id="lottie-N">` + `<script>const anim = lottie.loadAnimation({...}); window.__hfLottie.push(anim)</script>` |
+| `loop` / `playbackRate` props   | translate only after checking player seek behavior; HF adapter seeks absolute time via `goToAndStop`              |
+| `@remotion/lottie` runtime      | `lottie-web` from CDN — drop the React wrapper                                                                    |
+
+## Fonts
+
+See [fonts.md](fonts.md).
+
+| Remotion                                            | HyperFrames                                                                                 |
+| --------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `loadFont()` from `@remotion/google-fonts/<Family>` | `@font-face` rule referencing the Google Fonts CSS, OR `<link>` to Google Fonts in `<head>` |
+| Local font via `@font-face`                         | same — paste the rule into `<style>`                                                        |
+| System font fallback                                | document the font-fallback divergence cost (see [eval.md](eval.md))                         |
+
+## Parameters
+
+See [parameters.md](parameters.md).
+
+| Remotion                      | HyperFrames                                                                                   |
+| ----------------------------- | --------------------------------------------------------------------------------------------- |
+| `z.object({foo: z.string()})` | `data-foo` on `#stage` (the schema is implicit in HTML structure)                             |
+| nested array prop (`stats[]`) | repeated HTML markup with per-instance `data-*` attrs                                         |
+| Zod default values            | bake defaults into the HTML directly                                                          |
+| Zod runtime validation        | not represented; if validation matters, validate in the translation step before emitting HTML |
+
+## React patterns
+
+| Remotion                                           | HyperFrames                                                      |
+| -------------------------------------------------- | ---------------------------------------------------------------- |
+| Custom React subcomponent (pure, prop-driven)      | inline as repeated HTML using the prop interface as the template |
+| `useState` driving animation                       | **refuse + interop**                                             |
+| `useReducer` driving animation                     | **refuse + interop**                                             |
+| `useEffect(fn, [deps])` (non-empty deps)           | **refuse + interop**                                             |
+| `useEffect(fn, [])` (mount-once side effect)       | drop the effect; use `queueMicrotask` if startup work is needed  |
+| `useCallback`, `useMemo`                           | drop the wrappers — decorative                                   |
+| Custom hook (pure derivation of `useCurrentFrame`) | inline the body                                                  |
+| Custom hook with state/effects                     | refuse + interop                                                 |
+
+## Distributed rendering
+
+`@remotion/lambda` and `@remotion/cloudrun` are deployment configuration —
+orthogonal to the rendered composition itself. The skill emits these as
+**warnings** (not blockers) and drops them in step 3 (Generate) with a note
+in `TRANSLATION_NOTES.md`. HF is single-machine today; document the gap.
+
+| Remotion                   | HyperFrames                                            |
+| -------------------------- | ------------------------------------------------------ |
+| `@remotion/lambda` import  | drop the import (warning `r2hf/lambda-import`)         |
+| `renderMediaOnLambda(...)` | drop the call; note in `TRANSLATION_NOTES.md`          |
+| `@remotion/cloudrun`       | drop the import + call; note in `TRANSLATION_NOTES.md` |
+
+## When to bow out entirely
+
+If any blocker pattern is present, recommend the runtime interop pattern from
+[PR #214](https://github.com/heygen-com/hyperframes/pull/214) instead of
+attempting translation. See [escape-hatch.md](escape-hatch.md).
+
+The blockers are documented in [`scripts/lint_source.py`](../scripts/lint_source.py)
+and tested by [tier-4-escape-hatch](../assets/test-corpus/tier-4-escape-hatch/).

package/assets/.agent/skills/remotion-to-hyperframes/references/escape-hatch.md

@@ -1,115 +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.
+# 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.