Remotion To Hyperframes

run-report.json

#!/usr/bin/env bash
# run.sh — corpus orchestrator. Runs every tier and prints a pass/fail summary.
#
# Tiers 1-3: render Remotion baseline + HF translation, run SSIM diff,
#            assert mean >= ssim_threshold from each fixture's expected.json.
# Tier 4:    runs cases/validate.sh which lints each case and asserts against
#            expected.json.
#
# Usage:
#   ./run.sh                    run all tiers
#   ./run.sh tier-1-title-card  run a single tier
#
# Requirements:
#   - ffmpeg, ffprobe, python3 on PATH
#   - node 22 (for the HF CLI)
#   - npm (for Remotion installs)
#   - HF CLI built at packages/cli/dist/cli.js (run `bun run --filter @hyperframes/cli build`
#     in the repo root if missing)
#
# Output:
#   <fixture>/diff/summary.json   per-fixture SSIM summary
#   <fixture>/strip/strip.png     per-fixture comparison strip (only on fail)
#   ./run-report.json             aggregate report

set -euo pipefail

THIS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
SKILL_DIR="$(cd "$THIS_DIR/../.." && pwd)"
REPO_ROOT="$(cd "$SKILL_DIR/../.." && pwd)"

LINT="$SKILL_DIR/scripts/lint_source.py"
DIFF="$SKILL_DIR/scripts/render_diff.sh"
STRIP="$SKILL_DIR/scripts/frame_strip.sh"
HF_CLI="$REPO_ROOT/packages/cli/dist/cli.js"
REPORT="$THIS_DIR/run-report.json"

# Per-fixture results land here as one JSON file each, then the aggregator
# globs them. This is safer than building JSON via bash string concatenation
# (a fixture name containing a quote would break the previous approach).
RESULTS_DIR="$(mktemp -d)"
trap 'rm -rf "$RESULTS_DIR"' EXIT

# T4 is lint-only — no ffmpeg or HF CLI needed. Defer the render-tier
# toolchain checks until run_render_tier() actually runs, so
# `./run.sh tier-4-escape-hatch` works on a clean checkout.
require_render_tier_tools() {
  if [[ ! -f "$HF_CLI" ]]; then
    echo "error: HF CLI not built at $HF_CLI" >&2
    echo "       Run 'bun run --filter @hyperframes/cli build' in $REPO_ROOT" >&2
    return 2
  fi
  if ! command -v ffmpeg >/dev/null 2>&1; then
    echo "error: ffmpeg not on PATH" >&2
    return 2
  fi
  return 0
}

# Write one fixture's result as a JSON file. Values are passed via argv so
# bash string interpolation can't corrupt the JSON or inject Python source.
write_result() {
  local fixture_name="$1"
  local status="$2"
  shift 2
  python3 - "$RESULTS_DIR/$fixture_name.json" "$fixture_name" "$status" "$@" <<'PY'
import json
import sys

out_path, fixture_name, status, *kvs = sys.argv[1:]
result = {"fixture": fixture_name, "status": status}
for i in range(0, len(kvs), 2):
    k, v = kvs[i], kvs[i + 1]
    try:
        result[k] = float(v) if "." in v or v.lstrip("-").isdigit() else v
    except ValueError:
        result[k] = v
with open(out_path, "w") as f:
    json.dump(result, f)
PY
}

# Read a top-level scalar value from a JSON file. Falls back to $3 if the
# key is missing (used to default composition_id for older fixtures).
read_json_value() {
  local file="$1"
  local key="$2"
  local default="${3:-}"
  python3 - "$file" "$key" "$default" <<'PY'
import json
import sys

path, key, default = sys.argv[1], sys.argv[2], sys.argv[3]
with open(path) as f:
    data = json.load(f)
val = data.get(key, default)
print(val if val is not None else "")
PY
}

run_render_tier() {
  local fixture_dir="$1"
  local fixture_name
  fixture_name=$(basename "$fixture_dir")
  local expected="$fixture_dir/expected.json"

  if ! require_render_tier_tools; then
    echo "  ⚠ $fixture_name: render toolchain unavailable, skipping"
    write_result "$fixture_name" "skipped" reason "render toolchain unavailable"
    return 0
  fi

  local threshold composition_id
  threshold=$(read_json_value "$expected" "ssim_threshold")
  composition_id=$(read_json_value "$expected" "composition_id" "Composition")

  echo "  ▶ $fixture_name (threshold $threshold, composition $composition_id)"

  if [[ -x "$fixture_dir/setup.sh" ]]; then
    "$fixture_dir/setup.sh" >/dev/null
  fi

  if ! python3 "$LINT" "$fixture_dir/remotion-src/src/" >/dev/null; then
    echo "    ✗ lint failed (blockers in Remotion source)"
    write_result "$fixture_name" "fail" stage "lint"
    return 0
  fi

  if [[ ! -d "$fixture_dir/remotion-src/node_modules" ]]; then
    echo "    ⏳ npm install (first run)"
    (cd "$fixture_dir/remotion-src" && npm install --silent --no-progress >/dev/null 2>&1)
  fi

  echo "    ⏳ render Remotion baseline"
  if ! (cd "$fixture_dir/remotion-src" && \
        npx --no-install remotion render "$composition_id" out/baseline.mp4 >/dev/null 2>&1); then
    echo "    ✗ Remotion render failed"
    write_result "$fixture_name" "fail" stage "remotion-render"
    return 0
  fi

  echo "    ⏳ render HF translation"
  if ! (cd "$fixture_dir" && \
        node "$HF_CLI" render hf-src/ --output hf.mp4 --quiet >/dev/null 2>&1); then
    echo "    ✗ HF render failed"
    write_result "$fixture_name" "fail" stage "hf-render"
    return 0
  fi

  if R2HF_SSIM_THRESHOLD="$threshold" "$DIFF" \
      "$fixture_dir/remotion-src/out/baseline.mp4" \
      "$fixture_dir/hf.mp4" \
      "$fixture_dir/diff" >/dev/null; then
    local mean
    mean=$(read_json_value "$fixture_dir/diff/summary.json" "mean")
    echo "    ✓ pass (mean SSIM $mean, threshold $threshold)"
    write_result "$fixture_name" "pass" mean_ssim "$mean" threshold "$threshold"
  else
    local mean
    mean=$(read_json_value "$fixture_dir/diff/summary.json" "mean")
    echo "    ✗ fail (mean SSIM $mean, threshold $threshold)"
    "$STRIP" \
      "$fixture_dir/remotion-src/out/baseline.mp4" \
      "$fixture_dir/hf.mp4" \
      "$fixture_dir/strip" 8 >/dev/null
    write_result "$fixture_name" "fail" stage "ssim" mean_ssim "$mean" threshold "$threshold"
  fi
}

run_lint_tier() {
  local fixture_dir="$1"
  local fixture_name
  fixture_name=$(basename "$fixture_dir")

  echo "  ▶ $fixture_name (lint-only)"
  if "$fixture_dir/validate.sh" >/dev/null 2>&1; then
    echo "    ✓ pass (8/8 cases)"
    write_result "$fixture_name" "pass" mode "lint"
  else
    echo "    ✗ fail (some cases mismatched expected.json)"
    write_result "$fixture_name" "fail" mode "lint"
  fi
}

echo "remotion-to-hyperframes corpus run"
echo "=================================="

for tier in tier-1-title-card tier-2-multi-scene tier-3-data-driven; do
  if [[ -n "${1:-}" && "$1" != "$tier" ]]; then
    continue
  fi
  if [[ -d "$THIS_DIR/$tier" ]]; then
    run_render_tier "$THIS_DIR/$tier"
  fi
done

if [[ -z "${1:-}" || "$1" == "tier-4-escape-hatch" ]]; then
  if [[ -d "$THIS_DIR/tier-4-escape-hatch" ]]; then
    run_lint_tier "$THIS_DIR/tier-4-escape-hatch"
  fi
fi

# Aggregate the per-fixture JSON files into one report.
#
# Skipped fixtures are *not* a pass — they mean a tier didn't run because
# tooling or fixtures were unavailable. The orchestrator exits non-zero on
# any skip so a clean checkout that lacks the HF CLI doesn't accidentally
# report "passed 1/4" (T4 alone) and look like the corpus is healthy.
#
# Single-tier mode (`./run.sh tier-N`) only writes a result file for the
# selected tier; tiers that weren't run aren't counted as skips.
python3 - "$RESULTS_DIR" "$REPORT" <<'PY'
import json
import sys
from pathlib import Path

results_dir, out_path = Path(sys.argv[1]), Path(sys.argv[2])
results = sorted(
    (json.loads(p.read_text()) for p in results_dir.glob("*.json")),
    key=lambda r: r["fixture"],
)

total = len(results)
passed = sum(1 for r in results if r["status"] == "pass")
failed = sum(1 for r in results if r["status"] == "fail")
skipped = sum(1 for r in results if r["status"] == "skipped")
report = {
    "total": total,
    "passed": passed,
    "failed": failed,
    "skipped": skipped,
    "results": results,
}
out_path.write_text(json.dumps(report, indent=2))

print()
print("=" * 50)
print(f"  passed {passed}/{total}, failed {failed}, skipped {skipped}")
print(f"  report → {out_path}")
if skipped > 0:
    skipped_fixtures = [r["fixture"] for r in results if r["status"] == "skipped"]
    skipped_reasons = sorted({r.get("reason", "unknown") for r in results if r["status"] == "skipped"})
    print()
    print(f"  ⚠ {skipped} skipped: {', '.join(skipped_fixtures)}")
    for reason in skipped_reasons:
        print(f"    reason: {reason}")
    print("  Skipped fixtures count as failures for the aggregate.")
print("=" * 50)
sys.exit(0 if failed == 0 and skipped == 0 else 1)
PY

# Render output
remotion-src/out/
hf-src/out/
hf.mp4
diff/
strip/

# Remotion / HF dependencies
node_modules/
package-lock.json

{
  "tier": 1,
  "name": "title-card-fade",
  "composition_id": "TitleCard",
  "description": "Solid black background, single 'HELLO' element fades in 0-0.5s, holds 0.5-2.5s, fades out 2.5-3.0s. Tests the most basic Remotion → HyperFrames translation: a single AbsoluteFill, a single useCurrentFrame-driven interpolate, no audio, no media, no custom React components.",
  "duration_seconds": 3,
  "fps": 30,
  "width": 1280,
  "height": 720,
  "ssim_threshold": 0.95,
  "validation": {
    "measured_mean_ssim": 0.974,
    "measured_min_ssim": 0.972,
    "measured_p05_ssim": 0.972,
    "measured_p95_ssim": 0.983,
    "measured_at": "2026-04-27",
    "measured_against": "remotion@4.0 (PNG output, BT.709) vs hyperframes@0.4.15-alpha.1"
  },
  "translation_notes": [
    "Remotion: AbsoluteFill → HF: position:absolute;inset:0 div",
    "Remotion: interpolate(frame, [0,15,75,90], [0,1,1,0]) at fps=30 → HF: paused GSAP timeline with three keyframed tweens at 0s, 0.5s, 2.5s with ease:'none' (linear matches Remotion's default linear interpolation)",
    "No fonts loaded; both renderers use system Helvetica/Arial fallback. The Linux fallback diverges between Remotion's bundled Chromium and HyperFrames' chrome-headless-shell — same fontWeight:800 renders perceptibly bolder in HF. This costs ~0.025 mean SSIM and is the dominant non-translation noise floor.",
    "Remotion config must use setVideoImageFormat('png') + setColorSpace('bt709'); the JPEG default writes yuvj420p (full-range) which costs ~0.05 SSIM vs HF's yuv420p (limited-range)."
  ],
  "rationale": "Threshold 0.95 sits ~0.02 below measured p05. A real translation regression (wrong easing, wrong durations) drops mean SSIM by 0.05+. Encoder/font drift between CI runs is bounded at ~0.01."
}

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>tier-1-title-card</title>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js"></script>
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
        width: 1280px;
        height: 720px;
        overflow: hidden;
        background: #0a0a0a;
        font-family: Helvetica, Arial, sans-serif;
      }
      .title {
        position: absolute;
        inset: 0;
        display: flex;
        align-items: center;
        justify-content: center;
        color: #ffffff;
        font-size: 160px;
        font-weight: 800;
        letter-spacing: 0.05em;
        opacity: 0;
      }
    </style>
  </head>
  <body>
    <div
      id="stage"
      data-composition-id="tier-1-title-card"
      data-start="0"
      data-width="1280"
      data-height="720"
      data-duration="3"
      data-fps="30"
    >
      <div id="title" class="clip" data-start="0" data-duration="3" data-track-index="0">
        <div class="title">HELLO</div>
      </div>

      <script>
        // Translation of Remotion's
        //   interpolate(frame, [0, 15, 75, 90], [0, 1, 1, 0]) at fps=30
        // into a paused GSAP timeline keyed in seconds.
        // Frame ranges → time ranges:  0/30=0,  15/30=0.5,  75/30=2.5,  90/30=3.0
        const tl = gsap.timeline({ paused: true });
        const target = document.querySelector("#title .title");
        tl.to(target, { opacity: 1, duration: 0.5, ease: "none" }, 0);
        tl.to(target, { opacity: 1, duration: 2.0, ease: "none" }, 0.5);
        tl.to(target, { opacity: 0, duration: 0.5, ease: "none" }, 2.5);
        window.__timelines = window.__timelines || {};
        window.__timelines["tier-1-title-card"] = tl;
      </script>
    </div>
  </body>
</html>

{
  "name": "tier-1-title-card-remotion",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "render": "remotion render TitleCard out/baseline.mp4"
  },
  "dependencies": {
    "@remotion/cli": "^4.0.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "remotion": "^4.0.0"
  }
}

import { Config } from "@remotion/cli/config";

// Match HyperFrames' default render so SSIM diffs measure translation
// fidelity, not encoder differences.
//
//   setVideoImageFormat("png") avoids the JPEG limited-range/full-range
//   colorspace flag (yuvj420p vs yuv420p) that otherwise costs ~0.05 SSIM.
//
//   setColorSpace("bt709") matches HF's BT.709 SDR output.
Config.setVideoImageFormat("png");
Config.setColorSpace("bt709");
Config.setOverwriteOutput(true);
Config.setConcurrency(1);

import { registerRoot } from "remotion";
import { RemotionRoot } from "./Root";

registerRoot(RemotionRoot);

import { Composition } from "remotion";
import { TitleCard } from "./TitleCard";

export const RemotionRoot = () => (
  <Composition
    id="TitleCard"
    component={TitleCard}
    durationInFrames={90}
    fps={30}
    width={1280}
    height={720}
  />
);

import { AbsoluteFill, interpolate, useCurrentFrame } from "remotion";

export const TitleCard = () => {
  const frame = useCurrentFrame();

  // Fade in 0-15, hold 15-75, fade out 75-90.
  const opacity = interpolate(frame, [0, 15, 75, 90], [0, 1, 1, 0], {
    extrapolateLeft: "clamp",
    extrapolateRight: "clamp",
  });

  return (
    <AbsoluteFill
      style={{
        backgroundColor: "#0a0a0a",
        justifyContent: "center",
        alignItems: "center",
        fontFamily: "Helvetica, Arial, sans-serif",
      }}
    >
      <div
        style={{
          fontSize: 160,
          fontWeight: 800,
          color: "#ffffff",
          opacity,
          letterSpacing: "0.05em",
        }}
      >
        HELLO
      </div>
    </AbsoluteFill>
  );
};

{
  "compilerOptions": {
    "target": "ES2018",
    "module": "ESNext",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "moduleResolution": "node",
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true
  },
  "include": ["src"]
}

# Generated by setup.sh
remotion-src/public/
hf-src/assets/

# Remotion / HF dependencies
remotion-src/node_modules/
remotion-src/package-lock.json

# Render output
remotion-src/out/
hf-src/out/
hf.mp4
diff/
strip/

{
  "tier": 2,
  "name": "title-image-outro",
  "composition_id": "MultiScene",
  "description": "Three-scene composition exercising Sequence, spring, interpolate, Audio, Img, and staticFile. Title scene uses Remotion's spring (translated to GSAP back.out as an approximation). Image scene scales an Img (from staticFile) with linear interpolate. Outro scene fades text in linearly. A silent WAV plays throughout at volume 0.5.",
  "duration_seconds": 6,
  "fps": 30,
  "width": 1280,
  "height": 720,
  "ssim_threshold": 0.95,
  "validation": {
    "measured_mean_ssim": 0.985,
    "measured_min_ssim": 0.963,
    "measured_p05_ssim": 0.966,
    "measured_p95_ssim": 0.999,
    "measured_at": "2026-04-27",
    "measured_against": "remotion@4.0 (PNG output, BT.709) vs hyperframes@0.4.15-alpha.1",
    "notes": "Spring → back.out(1.4) translation came out cleaner than expected; mean 0.985 leaves substantial headroom over 0.95."
  },
  "translation_notes": [
    "spring({damping:12, stiffness:100, mass:1}) → back.out(1.4) over 0.7s. Spring overshoot+settle and back.out's overshoot+settle have similar shape; budget ~0.02 SSIM for the late-tail curvature mismatch (validated lower than predicted in spec; original notes overestimated drift).",
    "<Sequence from durationInFrames> → wrapping div with data-start/data-duration in seconds and explicit gsap.set(opacity, 0/1) at scene boundaries to crossfade in/out cleanly",
    "<Audio src volume> → <audio data-start data-duration data-volume>",
    "<Img src={staticFile('x')}> → <img src='assets/x'>; setup.sh copies the asset into both fixture trees",
    "interpolate with default linear easing → ease:'none' in GSAP",
    "Fonts again rely on system Helvetica/Arial; ~0.015 SSIM cost from AA differences"
  ],
  "rationale": "Threshold 0.95 sits ~0.015 below measured p05 (0.966). T2 actually validated cleaner than T1 because the lower title fontWeight (140px vs T1's 160px) shows less of the system-font fallback divergence."
}

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>tier-2-multi-scene</title>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js"></script>
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
        width: 1280px;
        height: 720px;
        overflow: hidden;
        background: #0a0a0a;
        font-family: Helvetica, Arial, sans-serif;
      }
      .scene {
        position: absolute;
        inset: 0;
        display: flex;
        align-items: center;
        justify-content: center;
        opacity: 0;
      }
      .title {
        font-size: 140px;
        font-weight: 800;
        color: #ffffff;
        letter-spacing: 0.05em;
        transform: scale(0);
      }
      .square {
        width: 200px;
        height: 200px;
        opacity: 0;
        transform: scale(0.8);
      }
      .outro {
        font-size: 100px;
        font-weight: 600;
        color: #ffffff;
      }
    </style>
  </head>
  <body>
    <div
      id="stage"
      data-composition-id="tier-2-multi-scene"
      data-start="0"
      data-width="1280"
      data-height="720"
      data-duration="6"
      data-fps="30"
    >
      <div id="scene-1" class="scene clip" data-start="0" data-duration="2" data-track-index="0">
        <div class="title">Welcome</div>
      </div>

      <div id="scene-2" class="scene clip" data-start="2" data-duration="2" data-track-index="0">
        <img class="square" src="assets/square.png" alt="" />
      </div>

      <div id="scene-3" class="scene clip" data-start="4" data-duration="2" data-track-index="0">
        <div class="outro">Goodbye</div>
      </div>

      <audio
        id="bg-music"
        data-start="0"
        data-duration="6"
        data-track-index="1"
        data-volume="0.5"
        src="assets/music.wav"
      ></audio>

      <script>
        // Translation of Remotion's 3-Sequence MultiScene at fps=30, total 6s.
        //
        // Scene 1 (0-2s): TitleScene — spring scale on "Welcome".
        //   Remotion: spring({frame, fps, config: {damping:12, stiffness:100, mass:1}})
        //   GSAP equivalent: back.out(1.4) over ~0.7s. Spring → ease translation
        //   is approximate; expect minor differences in the tail of the curve.
        //
        // Scene 2 (2-4s): ImageScene — opacity 0→1 over 0-0.5s + scale 0.8→1.0 over 0-2.0s.
        //   Both Remotion interpolates use linear (default), match with ease:"none".
        //
        // Scene 3 (4-6s): OutroScene — opacity 0→1 over 4-5s, linear.

        const tl = gsap.timeline({ paused: true });

        // Scene 1 setup: opacity flick on so scene becomes visible at start
        const scene1 = document.querySelector("#scene-1");
        const title = scene1.querySelector(".title");
        tl.set(scene1, { opacity: 1 }, 0);
        tl.to(title, { scale: 1, duration: 0.7, ease: "back.out(1.4)" }, 0);
        tl.set(scene1, { opacity: 0 }, 2);

        // Scene 2
        const scene2 = document.querySelector("#scene-2");
        const square = scene2.querySelector(".square");
        tl.set(scene2, { opacity: 1 }, 2);
        tl.to(square, { opacity: 1, duration: 0.5, ease: "none" }, 2);
        tl.to(square, { scale: 1.0, duration: 2.0, ease: "none" }, 2);
        tl.set(scene2, { opacity: 0 }, 4);

        // Scene 3
        const scene3 = document.querySelector("#scene-3");
        const outro = scene3.querySelector(".outro");
        tl.set(scene3, { opacity: 1 }, 4);
        tl.fromTo(outro, { opacity: 0 }, { opacity: 1, duration: 1.0, ease: "none" }, 4);

        window.__timelines = window.__timelines || {};
        window.__timelines["tier-2-multi-scene"] = tl;
      </script>
    </div>
  </body>
</html>

{
  "name": "tier-2-multi-scene-remotion",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "render": "remotion render MultiScene out/baseline.mp4"
  },
  "dependencies": {
    "@remotion/cli": "^4.0.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "remotion": "^4.0.0"
  }
}

import { Config } from "@remotion/cli/config";

// Match HyperFrames' default render so SSIM diffs measure translation
// fidelity, not encoder differences.
//
//   setVideoImageFormat("png") avoids the JPEG limited-range/full-range
//   colorspace flag (yuvj420p vs yuv420p) that otherwise costs ~0.05 SSIM.
//
//   setColorSpace("bt709") matches HF's BT.709 SDR output.
Config.setVideoImageFormat("png");
Config.setColorSpace("bt709");
Config.setOverwriteOutput(true);
Config.setConcurrency(1);

import { registerRoot } from "remotion";
import { RemotionRoot } from "./Root";

registerRoot(RemotionRoot);

import {
  AbsoluteFill,
  Audio,
  Img,
  Sequence,
  interpolate,
  spring,
  staticFile,
  useCurrentFrame,
  useVideoConfig,
} from "remotion";

const TitleScene = () => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();
  const scale = spring({ frame, fps, config: { damping: 12, stiffness: 100, mass: 1 } });
  return (
    <AbsoluteFill
      style={{
        backgroundColor: "#0a0a0a",
        justifyContent: "center",
        alignItems: "center",
        fontFamily: "Helvetica, Arial, sans-serif",
      }}
    >
      <div
        style={{
          fontSize: 140,
          fontWeight: 800,
          color: "#ffffff",
          transform: `scale(${scale})`,
          letterSpacing: "0.05em",
        }}
      >
        Welcome
      </div>
    </AbsoluteFill>
  );
};

const ImageScene = () => {
  const frame = useCurrentFrame();
  const opacity = interpolate(frame, [0, 15], [0, 1], { extrapolateRight: "clamp" });
  const scale = interpolate(frame, [0, 60], [0.8, 1.0], { extrapolateRight: "clamp" });
  return (
    <AbsoluteFill
      style={{
        backgroundColor: "#0a0a0a",
        justifyContent: "center",
        alignItems: "center",
      }}
    >
      <Img
        src={staticFile("square.png")}
        style={{
          width: 200,
          height: 200,
          opacity,
          transform: `scale(${scale})`,
        }}
      />
    </AbsoluteFill>
  );
};

const OutroScene = () => {
  const frame = useCurrentFrame();
  const opacity = interpolate(frame, [0, 30], [0, 1], { extrapolateRight: "clamp" });
  return (
    <AbsoluteFill
      style={{
        backgroundColor: "#0a0a0a",
        justifyContent: "center",
        alignItems: "center",
        fontFamily: "Helvetica, Arial, sans-serif",
      }}
    >
      <div
        style={{
          fontSize: 100,
          fontWeight: 600,
          color: "#ffffff",
          opacity,
        }}
      >
        Goodbye
      </div>
    </AbsoluteFill>
  );
};

export const MultiScene = () => (
  <AbsoluteFill>
    <Sequence from={0} durationInFrames={60}>
      <TitleScene />
    </Sequence>
    <Sequence from={60} durationInFrames={60}>
      <ImageScene />
    </Sequence>
    <Sequence from={120} durationInFrames={60}>
      <OutroScene />
    </Sequence>
    <Audio src={staticFile("music.wav")} volume={0.5} />
  </AbsoluteFill>
);

import { Composition } from "remotion";
import { MultiScene } from "./MultiScene";

export const RemotionRoot = () => (
  <Composition
    id="MultiScene"
    component={MultiScene}
    durationInFrames={180}
    fps={30}
    width={1280}
    height={720}
  />
);

{
  "compilerOptions": {
    "target": "ES2018",
    "module": "ESNext",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "moduleResolution": "node",
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true
  },
  "include": ["src"]
}

#!/usr/bin/env bash
# setup.sh — generate the binary assets this fixture needs.
#
# Both Remotion and HyperFrames variants need a 200x200 blue PNG and a
# 6-second silent WAV. Generating them via ffmpeg keeps binaries out of
# the repo while still letting the fixture render reproducibly.
#
# Run from the fixture root: ./setup.sh

set -euo pipefail

THIS_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"

if ! command -v ffmpeg >/dev/null 2>&1; then
  echo "error: ffmpeg not on PATH" >&2
  exit 2
fi

mkdir -p "$THIS_DIR/remotion-src/public" "$THIS_DIR/hf-src/assets"

# 200x200 solid blue PNG, ~200 bytes.
ffmpeg -y -hide_banner -loglevel error \
  -f lavfi -i "color=color=#3066be:size=200x200" -frames:v 1 \
  "$THIS_DIR/remotion-src/public/square.png"
cp "$THIS_DIR/remotion-src/public/square.png" "$THIS_DIR/hf-src/assets/square.png"

# 6-second silent WAV at 8 kHz mono. ~96 KB if checked in, but it is generated.
ffmpeg -y -hide_banner -loglevel error \
  -f lavfi -i "anullsrc=cl=mono:r=8000" -t 6 -acodec pcm_s16le \
  "$THIS_DIR/remotion-src/public/music.wav"
cp "$THIS_DIR/remotion-src/public/music.wav" "$THIS_DIR/hf-src/assets/music.wav"

echo "generated:"
ls -la "$THIS_DIR/remotion-src/public/" "$THIS_DIR/hf-src/assets/"

# Render output
remotion-src/out/
hf-src/out/
hf.mp4
diff/
strip/

# Remotion / HF dependencies
node_modules/
package-lock.json

{
  "tier": 3,
  "name": "stargazed-data-driven",
  "composition_id": "Stargazed",
  "description": "Data-driven 10-second composition with three scenes, custom React subcomponents reused across scenes, a Zod schema with defaultProps, and a count-up number animation. Translates the realistic shape of a production Remotion composition into HF — without using the runtime adapter from PR #214.",
  "duration_seconds": 10,
  "fps": 30,
  "width": 1280,
  "height": 720,
  "ssim_threshold": 0.9,
  "validation": {
    "measured_mean_ssim": 0.953,
    "measured_min_ssim": 0.927,
    "measured_p05_ssim": 0.938,
    "measured_p95_ssim": 0.977,
    "measured_at": "2026-04-27",
    "measured_against": "remotion@4.0 (PNG output, BT.709) vs hyperframes@0.4.15-alpha.1",
    "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."
  },
  "remotion_apis_exercised": [
    "Composition with z.object schema and typed defaultProps",
    "Sequence (3 nested with computed offsets)",
    "AbsoluteFill",
    "useCurrentFrame, useVideoConfig",
    "interpolate (single-segment, multi-segment, with extrapolation)",
    "spring (two configs: damping:12 and damping:14)",
    "Custom React subcomponents reused with different props (StatCard ×3)",
    "Custom React utility component (AnimatedNumber for count-up)",
    "Custom React utility component (UnderlinedText)",
    "Per-instance delay via prop (delayInFrames)"
  ],
  "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.",
    "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."
  ],
  "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."
}

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>tier-3-data-driven</title>
    <script src="https://cdnjs.cloudflare.com/ajax/libs/gsap/3.12.5/gsap.min.js"></script>
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
        width: 1280px;
        height: 720px;
        overflow: hidden;
        background: #0a0a0a;
        font-family: Helvetica, Arial, sans-serif;
        color: #ffffff;
      }
      .scene {
        position: absolute;
        inset: 0;
        display: flex;
        align-items: center;
        justify-content: center;
        opacity: 0;
      }

      /* Scene 1 — Title */
      .scene-1 {
        flex-direction: column;
      }
      .scene-1 .title {
        font-size: 160px;
        font-weight: 900;
        letter-spacing: 0.05em;
        transform: scale(0);
      }
      .scene-1 .subtitle {
        font-size: 36px;
        font-weight: 400;
        color: #9ca3af;
        margin-top: 24px;
        opacity: 0;
      }

      /* Scene 2 — Stats */
      .scene-2 {
        gap: 48px;
      }
      .stat-card {
        width: 280px;
        height: 220px;
        background: #1a1a1a;
        border-radius: 16px;
        border: 2px solid var(--card-color);
        display: flex;
        flex-direction: column;
        justify-content: center;
        align-items: center;
        opacity: 0;
        transform: scale(0);
      }
      .stat-card .number {
        font-size: 72px;
        font-weight: 800;
        color: var(--card-color);
        line-height: 1;
      }
      .stat-card .label {
        font-size: 24px;
        font-weight: 500;
        color: #9ca3af;
        margin-top: 16px;
        text-transform: uppercase;
        letter-spacing: 0.1em;
      }

      /* Scene 3 — Outro */
      .scene-3 .outro-wrap {
        position: relative;
        display: inline-block;
        opacity: 0;
      }
      .scene-3 .outro-text {
        font-size: 80px;
        font-weight: 600;
      }
      .scene-3 .outro-underline {
        position: absolute;
        left: 0;
        bottom: -8px;
        width: 100%;
        height: 6px;
        background: #fbbf24;
        border-radius: 3px;
        transform: scaleX(0);
        transform-origin: left center;
      }
    </style>
  </head>
  <body>
    <div
      id="stage"
      data-composition-id="tier-3-data-driven"
      data-start="0"
      data-width="1280"
      data-height="720"
      data-duration="10"
      data-fps="30"
      data-title="STARGAZED"
      data-subtitle="by HeyGen"
      data-outro="thanks for watching"
    >
      <!-- Scene 1: Title -->
      <div
        id="scene-1"
        class="scene scene-1 clip"
        data-start="0"
        data-duration="3"
        data-track-index="0"
      >
        <div class="title">STARGAZED</div>
        <div class="subtitle">by HeyGen</div>
      </div>

      <!-- Scene 2: Stats — three StatCards as repeated markup with per-instance data attrs -->
      <div
        id="scene-2"
        class="scene scene-2 clip"
        data-start="3"
        data-duration="4"
        data-track-index="0"
      >
        <div
          class="stat-card"
          data-stat-index="0"
          data-stat-value="1247"
          style="--card-color: #fbbf24"
        >
          <div class="number">0</div>
          <div class="label">Stars</div>
        </div>
        <div
          class="stat-card"
          data-stat-index="1"
          data-stat-value="312"
          style="--card-color: #60a5fa"
        >
          <div class="number">0</div>
          <div class="label">Forks</div>
        </div>
        <div
          class="stat-card"
          data-stat-index="2"
          data-stat-value="48"
          style="--card-color: #f87171"
        >
          <div class="number">0</div>
          <div class="label">Issues</div>
        </div>
      </div>

      <!-- Scene 3: Outro -->
      <div
        id="scene-3"
        class="scene scene-3 clip"
        data-start="7"
        data-duration="3"
        data-track-index="0"
      >
        <div class="outro-wrap">
          <div class="outro-text">thanks for watching</div>
          <div class="outro-underline"></div>
        </div>
      </div>

      <script>
        // ────────────────────────────────────────────────────────────────────
        // Translation of Stargazed.tsx
        //
        // Remotion structure:
        //   <Composition schema={zod} defaultProps={...} fps=30 dur=300>
        //     <Sequence 0..90>   <TitleScene title subtitle />
        //     <Sequence 90..210> <StatsScene stats />
        //     <Sequence 210..300><OutroScene text />
        //
        // HF structure:
        //   - root #stage carries data-* with the same props (title, subtitle, outro)
        //   - 3 scene divs with data-start/data-duration in seconds (frames/fps)
        //   - Custom React subcomponents inline as repeated HTML; their per-instance
        //     props become data-* attributes on the markup
        //   - Animation lives in a single paused GSAP timeline keyed by composition seconds
        //
        // Frame → time:
        //   Sequence(0,90)    → 0s..3s        (title)
        //   Sequence(90,210)  → 3s..7s        (stats; 4s window)
        //   Sequence(210,300) → 7s..10s       (outro)
        //   Stagger(i*12)     → i*0.4s        (12 frames at 30fps)
        // ────────────────────────────────────────────────────────────────────

        const tl = gsap.timeline({ paused: true });

        // ─── Scene 1: Title ─────────────────────────────────────────────────
        const scene1 = document.querySelector("#scene-1");
        const title = scene1.querySelector(".title");
        const subtitle = scene1.querySelector(".subtitle");

        tl.set(scene1, { opacity: 1 }, 0);
        // spring({damping:12, stiffness:100, mass:1}) → back.out(1.4) ~0.7s
        tl.to(title, { scale: 1, duration: 0.7, ease: "back.out(1.4)" }, 0);
        // interpolate(frame, [20,40], [0,1]) at fps=30 → 0.667s..1.333s linear
        tl.fromTo(subtitle, { opacity: 0 }, { opacity: 1, duration: 0.667, ease: "none" }, 0.667);
        tl.set(scene1, { opacity: 0 }, 3);

        // ─── Scene 2: Stats ─────────────────────────────────────────────────
        const scene2 = document.querySelector("#scene-2");
        const cards = scene2.querySelectorAll(".stat-card");

        tl.set(scene2, { opacity: 1 }, 3);

        cards.forEach((card, i) => {
          const stagger = i * 0.4; // i * 12 frames at 30 fps
          const start = 3 + stagger;
          const value = Number(card.dataset.statValue);
          const numberEl = card.querySelector(".number");

          // StatCard entrance:
          //   spring({damping:14, stiffness:90, mass:1}) → back.out(1.2) ~0.7s
          //   interpolate(local, [0,12], [0,1]) → 0s..0.4s linear opacity
          tl.to(card, { scale: 1, duration: 0.7, ease: "back.out(1.2)" }, start);
          tl.to(card, { opacity: 1, duration: 0.4, ease: "none" }, start);

          // AnimatedNumber: count from 0 → value with easeOutCubic over 45 frames (1.5s).
          // GSAP equivalent: a tween on a counter object with onUpdate rewriting textContent.
          // power3.out is GSAP's name for cubic easeOut.
          const counter = { v: 0 };
          tl.to(
            counter,
            {
              v: value,
              duration: 1.5,
              ease: "power3.out",
              onUpdate: () => {
                numberEl.textContent = Math.round(counter.v).toLocaleString();
              },
            },
            start,
          );
        });

        tl.set(scene2, { opacity: 0 }, 7);

        // ─── Scene 3: Outro ─────────────────────────────────────────────────
        const scene3 = document.querySelector("#scene-3");
        const outroWrap = scene3.querySelector(".outro-wrap");
        const underline = scene3.querySelector(".outro-underline");

        tl.set(scene3, { opacity: 1 }, 7);
        // interpolate(frame, [0,12], [0,1]) → 0s..0.4s linear opacity
        tl.to(outroWrap, { opacity: 1, duration: 0.4, ease: "none" }, 7);
        // interpolate(frame, [10,40], [0,1]) for underline → starts at 7+0.333s, dur 1s
        tl.to(underline, { scaleX: 1, duration: 1.0, ease: "none" }, 7.333);

        window.__timelines = window.__timelines || {};
        window.__timelines["tier-3-data-driven"] = tl;
      </script>
    </div>
  </body>
</html>

{
  "name": "tier-3-data-driven-remotion",
  "version": "0.0.0",
  "private": true,
  "scripts": {
    "render": "remotion render Stargazed out/baseline.mp4"
  },
  "dependencies": {
    "@remotion/cli": "^4.0.0",
    "react": "^18.3.1",
    "react-dom": "^18.3.1",
    "remotion": "^4.0.0",
    "zod": "^3.22.0"
  }
}

import { Config } from "@remotion/cli/config";

// Match HyperFrames' default render so SSIM diffs measure translation
// fidelity, not encoder differences.
//
//   setVideoImageFormat("png") avoids the JPEG limited-range/full-range
//   colorspace flag (yuvj420p vs yuv420p) that otherwise costs ~0.05 SSIM.
//
//   setColorSpace("bt709") matches HF's BT.709 SDR output.
Config.setVideoImageFormat("png");
Config.setColorSpace("bt709");
Config.setOverwriteOutput(true);
Config.setConcurrency(1);

import { interpolate, useCurrentFrame } from "remotion";

interface Props {
  from: number;
  to: number;
  durationInFrames: number;
}

/**
 * Counts from `from` to `to` over `durationInFrames` with easeOut.
 * Driven entirely by useCurrentFrame — deterministic.
 */
export const AnimatedNumber: React.FC<Props> = ({ from, to, durationInFrames }) => {
  const frame = useCurrentFrame();
  const t = interpolate(frame, [0, durationInFrames], [0, 1], {
    extrapolateLeft: "clamp",
    extrapolateRight: "clamp",
  });
  // Ease-out cubic — fast start, slow finish, matches the ramp on data dashboards.
  const eased = 1 - (1 - t) ** 3;
  const value = Math.round(from + (to - from) * eased);
  return <>{value.toLocaleString()}</>;
};

import { interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";
import { AnimatedNumber } from "./AnimatedNumber";

interface Props {
  label: string;
  value: number;
  color: string;
  delayInFrames: number;
}

export const StatCard: React.FC<Props> = ({ label, value, color, delayInFrames }) => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();
  const local = frame - delayInFrames;

  const scale = spring({
    frame: local,
    fps,
    config: { damping: 14, stiffness: 90, mass: 1 },
  });
  const opacity = interpolate(local, [0, 12], [0, 1], {
    extrapolateLeft: "clamp",
    extrapolateRight: "clamp",
  });

  return (
    <div
      style={{
        width: 280,
        height: 220,
        background: "#1a1a1a",
        borderRadius: 16,
        border: `2px solid ${color}`,
        display: "flex",
        flexDirection: "column",
        justifyContent: "center",
        alignItems: "center",
        opacity,
        transform: `scale(${scale})`,
      }}
    >
      <div style={{ fontSize: 72, fontWeight: 800, color, lineHeight: 1 }}>
        {local >= 0 ? <AnimatedNumber from={0} to={value} durationInFrames={45} /> : 0}
      </div>
      <div
        style={{
          fontSize: 24,
          fontWeight: 500,
          color: "#9ca3af",
          marginTop: 16,
          textTransform: "uppercase",
          letterSpacing: "0.1em",
        }}
      >
        {label}
      </div>
    </div>
  );
};

import { interpolate, useCurrentFrame } from "remotion";

interface Props {
  text: string;
  color: string;
}

export const UnderlinedText: React.FC<Props> = ({ text, color }) => {
  const frame = useCurrentFrame();
  // Underline scales from left over 0-30 frames.
  const underlineScaleX = interpolate(frame, [10, 40], [0, 1], {
    extrapolateLeft: "clamp",
    extrapolateRight: "clamp",
  });
  const opacity = interpolate(frame, [0, 12], [0, 1], {
    extrapolateLeft: "clamp",
    extrapolateRight: "clamp",
  });

  return (
    <div style={{ position: "relative", display: "inline-block", opacity }}>
      <div
        style={{
          fontSize: 80,
          fontWeight: 600,
          color: "#ffffff",
          fontFamily: "Helvetica, Arial, sans-serif",
        }}
      >
        {text}
      </div>
      <div
        style={{
          position: "absolute",
          left: 0,
          bottom: -8,
          width: "100%",
          height: 6,
          background: color,
          transform: `scaleX(${underlineScaleX})`,
          transformOrigin: "left center",
          borderRadius: 3,
        }}
      />
    </div>
  );
};

import { registerRoot } from "remotion";
import { RemotionRoot } from "./Root";

registerRoot(RemotionRoot);

import { Composition } from "remotion";
import { z } from "zod";
import { Stargazed, stargazedSchema } from "./Stargazed";

const defaultProps: z.infer<typeof stargazedSchema> = {
  title: "STARGAZED",
  subtitle: "by HeyGen",
  stats: [
    { label: "Stars", value: 1247, color: "#fbbf24" },
    { label: "Forks", value: 312, color: "#60a5fa" },
    { label: "Issues", value: 48, color: "#f87171" },
  ],
  outro: "thanks for watching",
};

export const RemotionRoot = () => (
  <Composition
    id="Stargazed"
    component={Stargazed}
    schema={stargazedSchema}
    durationInFrames={300}
    fps={30}
    width={1280}
    height={720}
    defaultProps={defaultProps}
  />
);

import { AbsoluteFill } from "remotion";
import { UnderlinedText } from "../components/UnderlinedText";

interface Props {
  text: string;
}

export const OutroScene: React.FC<Props> = ({ text }) => (
  <AbsoluteFill
    style={{
      justifyContent: "center",
      alignItems: "center",
      fontFamily: "Helvetica, Arial, sans-serif",
    }}
  >
    <UnderlinedText text={text} color="#fbbf24" />
  </AbsoluteFill>
);

import { AbsoluteFill } from "remotion";
import { StatCard } from "../components/StatCard";

interface Stat {
  label: string;
  value: number;
  color: string;
}

interface Props {
  stats: Stat[];
}

export const StatsScene: React.FC<Props> = ({ stats }) => (
  <AbsoluteFill
    style={{
      justifyContent: "center",
      alignItems: "center",
      gap: 48,
      flexDirection: "row",
      fontFamily: "Helvetica, Arial, sans-serif",
    }}
  >
    {stats.map((stat, i) => (
      <StatCard
        key={stat.label}
        label={stat.label}
        value={stat.value}
        color={stat.color}
        delayInFrames={i * 12}
      />
    ))}
  </AbsoluteFill>
);

import { AbsoluteFill, interpolate, spring, useCurrentFrame, useVideoConfig } from "remotion";

interface Props {
  title: string;
  subtitle: string;
}

export const TitleScene: React.FC<Props> = ({ title, subtitle }) => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();

  const titleScale = spring({
    frame,
    fps,
    config: { damping: 12, stiffness: 100, mass: 1 },
  });
  const subtitleOpacity = interpolate(frame, [20, 40], [0, 1], {
    extrapolateLeft: "clamp",
    extrapolateRight: "clamp",
  });

  return (
    <AbsoluteFill
      style={{
        justifyContent: "center",
        alignItems: "center",
        flexDirection: "column",
        fontFamily: "Helvetica, Arial, sans-serif",
      }}
    >
      <div
        style={{
          fontSize: 160,
          fontWeight: 900,
          color: "#ffffff",
          letterSpacing: "0.05em",
          transform: `scale(${titleScale})`,
        }}
      >
        {title}
      </div>
      <div
        style={{
          fontSize: 36,
          fontWeight: 400,
          color: "#9ca3af",
          marginTop: 24,
          opacity: subtitleOpacity,
        }}
      >
        {subtitle}
      </div>
    </AbsoluteFill>
  );
};

import { AbsoluteFill, Sequence } from "remotion";
import { z } from "zod";
import { TitleScene } from "./scenes/TitleScene";
import { StatsScene } from "./scenes/StatsScene";
import { OutroScene } from "./scenes/OutroScene";

export const stargazedSchema = z.object({
  title: z.string(),
  subtitle: z.string(),
  stats: z.array(
    z.object({
      label: z.string(),
      value: z.number(),
      color: z.string(),
    }),
  ),
  outro: z.string(),
});

export const Stargazed: React.FC<z.infer<typeof stargazedSchema>> = ({
  title,
  subtitle,
  stats,
  outro,
}) => (
  <AbsoluteFill style={{ backgroundColor: "#0a0a0a" }}>
    <Sequence from={0} durationInFrames={90}>
      <TitleScene title={title} subtitle={subtitle} />
    </Sequence>
    <Sequence from={90} durationInFrames={120}>
      <StatsScene stats={stats} />
    </Sequence>
    <Sequence from={210} durationInFrames={90}>
      <OutroScene text={outro} />
    </Sequence>
  </AbsoluteFill>
);

{
  "compilerOptions": {
    "target": "ES2018",
    "module": "ESNext",
    "jsx": "react-jsx",
    "strict": true,
    "esModuleInterop": true,
    "moduleResolution": "node",
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "isolatedModules": true
  },
  "include": ["src"]
}

// T4 case 01 — useState drives animation.
//
// Should be detected by lint_source.py as blocker r2hf/use-state.
// The skill should refuse to translate and recommend the runtime interop
// pattern from PR #214.
//
// Why this is a blocker: useState is React's component-local mutable state.
// HF's seek-driven model produces deterministic frames from a single time
// value — there's no per-frame React render cycle to update state on.

import React, { useState } from "react";
import { AbsoluteFill, useCurrentFrame } from "remotion";

export const StateDriven: React.FC = () => {
  const frame = useCurrentFrame();
  const [hue, setHue] = useState(0);

  // Even if this looks innocuous, the setHue call breaks determinism: HF
  // can't reproduce React state mutations across seeks.
  if (frame % 30 === 0 && hue < 360) {
    setHue((h) => h + 30);
  }

  return (
    <AbsoluteFill style={{ background: `hsl(${hue}, 80%, 50%)` }}>
      <div>frame {frame}</div>
    </AbsoluteFill>
  );
};

// T4 case 02 — useEffect with non-empty deps performs side effects per render.
//
// Should be detected by lint_source.py as blocker r2hf/use-effect-deps.
// The skill should refuse to translate.
//
// Why this is a blocker: side effects (network, DOM mutation outside the
// rendered tree, timers) don't translate to a seek-driven model. HF assumes
// the page is fully rendered and pure between seeks.

import React, { useEffect, useRef } from "react";
import { AbsoluteFill, useCurrentFrame } from "remotion";

export const SideEffectDriven: React.FC = () => {
  const frame = useCurrentFrame();
  const canvasRef = useRef<HTMLCanvasElement>(null);

  useEffect(() => {
    const canvas = canvasRef.current;
    if (!canvas) return;
    const ctx = canvas.getContext("2d");
    ctx?.fillRect(frame, frame, 10, 10);
  }, [frame]);

  return (
    <AbsoluteFill>
      <canvas ref={canvasRef} width={1280} height={720} />
    </AbsoluteFill>
  );
};

// T4 case 03 — calculateMetadata returns a Promise.
//
// Should be detected by lint_source.py as blocker r2hf/async-metadata.
// The skill should refuse to translate.
//
// Why this is a blocker: HF needs the composition's duration, dimensions,
// and props known up-front to produce HTML and seed the timeline. Async
// metadata fetched from a server at render time has no equivalent in HF —
// the metadata would need to be resolved at build time before the HTML is
// authored.

import React from "react";
import { AbsoluteFill, useCurrentFrame } from "remotion";

interface Props {
  text: string;
}

export const AsyncMetadataDriven: React.FC<Props> = ({ text }) => {
  const frame = useCurrentFrame();
  return (
    <AbsoluteFill>
      <div>
        {text} · frame {frame}
      </div>
    </AbsoluteFill>
  );
};

export const calculateMetadata = async ({ props }: { props: Props }) => {
  const response = await fetch(
    `https://api.example.com/duration?text=${encodeURIComponent(props.text)}`,
  );
  const { durationInFrames } = await response.json();
  return {
    durationInFrames,
    fps: 30,
  };
};

// T4 case 04 — Imports from a third-party React UI library.
//
// Should be detected by lint_source.py as blocker r2hf/third-party-react-ui.
// The skill should refuse to translate.
//
// Why this is a blocker: a Material-UI Button (or any React UI library
// component) is a React-only abstraction with internal hooks, refs, and
// theme provider context. Translating it to HTML+CSS would require
// re-implementing the design system, which is out of scope for a video
// translation skill. Use the runtime interop pattern from PR #214 to keep
// these components rendering through Remotion's React tree.

import React from "react";
import { Button } from "@mui/material";
import { AbsoluteFill, useCurrentFrame, interpolate } from "remotion";

export const MuiDriven: React.FC = () => {
  const frame = useCurrentFrame();
  const opacity = interpolate(frame, [0, 30], [0, 1], { extrapolateRight: "clamp" });

  return (
    <AbsoluteFill style={{ alignItems: "center", justifyContent: "center" }}>
      <div style={{ opacity }}>
        <Button variant="contained" color="primary">
          Click me · frame {frame}
        </Button>
      </div>
    </AbsoluteFill>
  );
};

// T4 case 05 — Imports @remotion/lambda for distributed rendering config.
//
// Should be detected by lint_source.py as warning r2hf/lambda-import.
// The skill drops the Lambda code with a note (HF runs single-machine
// today) and translates the rest of the composition.
//
// Why this is a warning, not a blocker: @remotion/lambda config is
// orthogonal to the rendered composition — it's deployment configuration,
// not animation logic. Treating it as a hard blocker would refuse
// translation for compositions that are otherwise clean. The skill drops
// the Lambda calls in step 3 (Generate) and writes a TRANSLATION_NOTES.md
// entry so the user knows to set up HF rendering separately.

import React from "react";
import { renderMediaOnLambda } from "@remotion/lambda";
import { AbsoluteFill, useCurrentFrame, interpolate } from "remotion";

export const LambdaConfigured: React.FC = () => {
  const frame = useCurrentFrame();
  const opacity = interpolate(frame, [0, 30], [0, 1]);
  return (
    <AbsoluteFill style={{ opacity }}>
      <div>frame {frame}</div>
    </AbsoluteFill>
  );
};

// Rendered at scale via Lambda — no HF equivalent.
export async function renderViaLambda() {
  return renderMediaOnLambda({
    region: "us-east-1",
    functionName: "remotion-render",
    composition: "LambdaConfigured",
    serveUrl: "https://example.com/bundle",
    inputProps: {},
    codec: "h264",
  });
}

// T4 case 06 — Patterns that warn but don't block.
//
// Should be detected by lint_source.py with:
//   - r2hf/delay-render (warning) — drop the call; HF handles asset readiness
//   - r2hf/use-callback (warning) — decorative, drop the wrapper
//   - r2hf/use-memo    (warning) — decorative, drop the wrapper
//
// 0 blockers expected — the skill should still translate this composition
// after dropping the wrappers. delayRender is paired with continueRender via
// an empty-deps useEffect (mount-once side effect), which doesn't trip the
// use-effect-deps blocker.

import React, { useCallback, useMemo } from "react";
import { AbsoluteFill, delayRender, continueRender, useCurrentFrame, interpolate } from "remotion";

const handle = delayRender();
// Resolve the handle once at module load — no per-frame side effects.
queueMicrotask(() => continueRender(handle));

export const WarningsOnly: React.FC = () => {
  const frame = useCurrentFrame();

  // useCallback / useMemo — decorative for render-perf in React, no equivalent
  // needed in the seek-driven HF model.
  const opacity = useMemo(
    () => interpolate(frame, [0, 30], [0, 1], { extrapolateRight: "clamp" }),
    [frame],
  );
  const onMount = useCallback(() => {}, []);

  return (
    <AbsoluteFill style={{ opacity }} onClick={onMount}>
      <div>frame {frame}</div>
    </AbsoluteFill>
  );
};

// T4 case 07 — Locally-defined custom hook.
//
// Should be detected by lint_source.py as warning r2hf/custom-hook.
// 0 blockers expected — the skill can attempt translation if the hook body
// is pure (derives from props/frame alone).
//
// Why this is a warning: custom hooks vary widely in what they do. Some are
// pure derivations of useCurrentFrame (translatable — inline the body); some
// wrap useState/useEffect (blocker — but those will be caught by the other
// rules independently). The warning prompts the agent to inspect the body.

import React from "react";
import { AbsoluteFill, useCurrentFrame, interpolate } from "remotion";

// Custom hook — pure derivation from frame, no state. Translates fine.
function useFadeIn(durationInFrames: number) {
  const frame = useCurrentFrame();
  return interpolate(frame, [0, durationInFrames], [0, 1], { extrapolateRight: "clamp" });
}

export const CustomHookDriven: React.FC = () => {
  const opacity = useFadeIn(30);
  return (
    <AbsoluteFill style={{ opacity }}>
      <div>fading in</div>
    </AbsoluteFill>
  );
};

// T4 case 08 — Multiple blockers + multiple warnings in one file.
//
// Should report:
//   blockers: r2hf/use-state, r2hf/use-effect-deps, r2hf/third-party-react-ui
//   warnings: r2hf/use-callback (also r2hf/delay-render via the import chain
//             would only fire if delayRender is actually called)
//
// Tests that the linter aggregates findings correctly and does not stop at
// the first blocker.

import React, { useState, useEffect, useCallback } from "react";
import { AbsoluteFill, useCurrentFrame } from "remotion";
import { Card } from "@chakra-ui/react";

interface Item {
  id: string;
  label: string;
}

export const MixedBlockers: React.FC = () => {
  const frame = useCurrentFrame();
  const [items, setItems] = useState<Item[]>([]);

  useEffect(() => {
    fetch("/api/items")
      .then((r) => r.json())
      .then(setItems);
  }, [frame]);

  const onClick = useCallback(() => {
    setItems((prev) => [...prev, { id: String(prev.length), label: "new" }]);
  }, []);

  return (
    <AbsoluteFill onClick={onClick}>
      {items.map((item) => (
        <Card key={item.id}>{item.label}</Card>
      ))}
    </AbsoluteFill>
  );
};