dsh-hyperframes 0.1.1 → 0.3.0

package/skills/product-launch-video/sub-agents/frame-worker.md

@@ -0,0 +1,21 @@
+# Frame worker — product-launch delta
+
+> The shared law is the core contract above (the packet builder prepends `../hyperframes-core/references/frame-worker-core.md` to this file as `_role.md`) — read the two as one role. This file carries only what's specific to a product-launch frame; you run N-up, **one frame each** — your dispatch carries exactly one packet. Tempted to add a generic GSAP / timeline rule here? Wrong home — it belongs in the core contract or `hyperframes-core`.
+
+## Your `focal:` / `roles:` — real captured media
+
+- `focal:` — which candidate is the hero.
+- `roles:` — each candidate's role: `cutout` foreground / `background` full-bleed / supporting — plus the real media available (each `public/<basename> — description`; a **`[video]`** tag marks a `.mp4` motion source that cannot be mounted by this sub-composition worker).
+- **Asset paths are project-root relative everywhere.** This includes HTML attributes and CSS `url(...)` values such as `@font-face src`: use `assets/...` (or the supplied `capture/assets/...` path), never `../` or `../../`. Shared fonts are staged before dispatch so every parallel frame resolves the same local files; never fall back to a network `@import`.
+
+## Placing candidates (product-launch constraint)
+
+**Place each candidate by its `roles`** (the `focal` is the hero): a `cutout` is a foreground subject — respect the 83% keep-out, lay text around it, not over its face; a `background` is full-bleed and dimmed ~30–50% so foreground content stays legible. Frame files are sub-compositions. Audio remains orchestrator-owned: never author `<audio>` in a frame. An approved `[video]` candidate may be declared as a frame-local `<video data-frame-video="approved" data-start="..." data-duration="..." data-track-index="...">`; `assemble-index.mjs` hoists it to the host root and translates its timing. Give every approved video explicit host geometry with numeric `data-frame-video-x`, `data-frame-video-y`, `data-frame-video-width`, and `data-frame-video-height`; optionally set `data-frame-video-fit="cover|contain|fill|none|scale-down"` (default `cover`). The assembler converts only those values to host CSS: frame-local classes and inline styles do not cross the hoist boundary. Do not use this declaration for audio, unapproved URLs, or videos without explicit timing and geometry. If no approved video is supplied, use an explicitly supplied static still/key art (`[video-still]` or another image candidate) as `<img>`; do not extract a frame, fabricate a URL, or silently embed an unapproved clip.
+
+When a frame showcases a captured website, use the supplied screenshot as the page. Do not rebuild the full site in HTML: even a close recreation can change the real layout, spacing, or branding. If the shot needs motion inside the page, overlay the supplied real assets at measured positions or rebuild only the moving component.
+
+Brand text comes from your frame's `scene` / narrative — never from `frame.md` (a style spec, not the product's content). Place the named assets, and never invent new ones.
+
+## Cross-frame handoffs
+
+If the packet includes `handoff_in:` or `handoff_out:`, treat those values as a hard boundary contract. Start or end the named element at the exact x/y position, scale, opacity, and motion direction/speed provided; a field the packet states as unchanged is still binding, not optional. Do not restyle or reinterpret that boundary state. The neighboring frame is being built by another worker and will use the matching values.

package/skills/remotion-to-hyperframes/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: remotion-to-hyperframes
+description: 'Port an existing Remotion (React) composition''s source to HyperFrames HTML. Use ONLY on an explicit ask to port/convert/migrate/translate a Remotion source — one-way, Remotion-only. A passing Remotion mention, reference-only code, or "make something like my Remotion video" is a fresh build (/general-video). Unclear → /hyperframes.'
+---
+
+> **First, keep this skill fresh — confirm with the user before running:** `npx hyperframes skills update remotion-to-hyperframes`. A fast no-op when everything is current; otherwise it refreshes this skill plus the core domain skills it depends on before you rely on them.
+
+# Remotion to HyperFrames
+
+> **The front door is `/hyperframes`.** Use this **only** to port an existing **Remotion** (React) composition's source into HyperFrames, one way. Authoring a **new** composition, re-creating from a non-Remotion source (After Effects, Framer Motion, plain React / CSS — there is no Remotion source to translate), a passing Remotion mention, or any uncertainty → read `/hyperframes` first: the intent layer owns every route decision.
+
+## Overview
+
+Translate Remotion (React-based) video compositions into HyperFrames (HTML + GSAP) compositions. Most Remotion idioms have direct HyperFrames equivalents — the translation is mechanical for ~80% of typical compositions. This skill encodes the mapping and guards against the lossy 20% by refusing to translate patterns that don't fit HF's seek-driven model and recommending the runtime interop pattern from [PR #214](https://github.com/heygen-com/hyperframes/pull/214) instead.
+
+The skill ships with a **tiered test corpus** (T1–T4, 4 fixtures total) that grades translations against measured SSIM thresholds. Don't translate without running the eval — a translation that "looks right" but renders 0.05 SSIM lower than the validated baseline is silently wrong.
+
+## When to use
+
+**Use this skill ONLY when the user explicitly asks to migrate from Remotion.** Example trigger phrases:
+
+- "port my Remotion project to HyperFrames"
+- "convert this Remotion code to HyperFrames"
+- "migrate from Remotion"
+- "translate this Remotion comp"
+- "rewrite this as HyperFrames HTML"
+
+**Do NOT use this skill when:**
+
+- (a) The user is authoring a **new** HyperFrames composition, even if they have or are A/B-testing a similar Remotion video.
+- (b) The user mentions Remotion in passing without asking for migration.
+- (c) The user shares Remotion code as reference material rather than asking for a translation.
+- (d) The user asks for "the same video as my Remotion one" without explicitly asking to migrate the source — treat that as a fresh HyperFrames build.
+
+**NOT SUPPORTED (decline — this is not what this skill does):**
+
+- **The reverse direction.** Exporting a HyperFrames composition back out _to_ Remotion (or to any other framework) is not a workflow — the translation is Remotion → HyperFrames only. Say so plainly.
+- **Non-Remotion sources.** An After Effects project (`.aep`), a Framer Motion / plain-React / CSS animation, or any other tool's source is not a Remotion composition — there is no Remotion source to translate. Re-create it natively via `/general-video`, or decline if HyperFrames can't represent it.
+
+When in doubt, default to authoring a native HyperFrames composition with `/general-video` (the general HyperFrames authoring flow) instead.
+
+## Workflow
+
+### Step 1: Lint the source
+
+Run [`scripts/lint_source.py`](scripts/lint_source.py) over the Remotion source directory. The lint detects patterns that can't translate cleanly:
+
+- **Blockers** (refuse + recommend interop): `useState`, `useReducer`, `useEffect`/`useLayoutEffect` with non-empty deps, async `calculateMetadata`, third-party React UI libraries (MUI, Chakra, Mantine, antd, shadcn, Radix, NextUI).
+- **Warnings** (translate after dropping the construct): `@remotion/lambda` config, `delayRender`, `useCallback`, `useMemo`, custom hooks.
+- **Info** (translate with note): `staticFile`, `interpolateColors`.
+
+If any blocker fires, **stop**. Read [`references/escape-hatch.md`](references/escape-hatch.md) and surface the recommendation message. Warnings don't stop translation — drop the offending construct in step 3 and note the gap in `TRANSLATION_NOTES.md`. `@remotion/lambda` config is the canonical warning case: the skill drops the import + `renderMediaOnLambda(...)` calls but translates the rest of the composition.
+
+### Step 2: Plan the translation
+
+Read [`references/api-map.md`](references/api-map.md) — the index of every Remotion API and its HF equivalent or per-topic reference. Identify which topic references you'll need based on what the source uses:
+
+| Source contains                                                           | Load reference                                |
+| ------------------------------------------------------------------------- | --------------------------------------------- |
+| `Composition`, `defaultProps`, `schema`, `calculateMetadata`              | [`parameters.md`](references/parameters.md)   |
+| `Sequence`, `Series`, `Loop`, `AbsoluteFill`, `Freeze`                    | [`sequencing.md`](references/sequencing.md)   |
+| `useCurrentFrame`, `interpolate`, `spring`, `Easing`, `interpolateColors` | [`timing.md`](references/timing.md)           |
+| `Audio`, `Video`, `Img`, `IFrame`, `staticFile`, `delayRender`            | [`media.md`](references/media.md)             |
+| `TransitionSeries`, `@remotion/transitions`                               | [`transitions.md`](references/transitions.md) |
+| `@remotion/lottie`                                                        | [`lottie.md`](references/lottie.md)           |
+| `@remotion/google-fonts/<Family>`, `Font.loadFont`, `@font-face`          | [`fonts.md`](references/fonts.md)             |
+
+Don't load all of them — load only what the specific source needs.
+
+### Step 3: Generate the HF composition
+
+Emit `index.html` with:
+
+- Root `<div id="stage">` carrying the composition's `data-composition-id`, `data-start="0"`, `data-duration` (in seconds), `data-fps`, `data-width`, `data-height`, plus one `data-*` per scalar prop.
+- A flat list of scene divs with `data-start` / `data-duration` / `data-track-index`.
+- Inline `<style>` for layout; CSS sets the `from` state of every animated property.
+- A single `<script>` tag at the bottom containing one paused `gsap.timeline({paused: true})`. Every Remotion `useCurrentFrame()` derivation becomes a tween on this timeline at the right offset.
+- `window.__timelines["<composition-id>"] = tl;` registers the timeline with HF's runtime.
+
+Custom React subcomponents inline as repeated HTML using the prop interface as the template (see [`parameters.md`](references/parameters.md) for the per-instance `data-*` pattern).
+
+### Step 4: Validate
+
+Run the eval harness — [`references/eval.md`](references/eval.md) for the full guide. Quick path:
+
+```bash
+# Render Remotion baseline (after npm install in the fixture)
+cd remotion-src && npx remotion render <CompositionId> out/baseline.mp4
+
+# Render HF translation
+cd ../hf-src && npx hyperframes render --skill=remotion-to-hyperframes --output ../hf.mp4
+
+# SSIM diff
+../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff
+```
+
+Threshold: ~0.02 below `p05` of the source's complexity tier (see `eval.md`'s validated thresholds table). If the diff fails, run [`scripts/frame_strip.sh`](scripts/frame_strip.sh) to see _which_ frames diverged, then re-read the relevant timing/sequencing/media reference.
+
+**Critical**: both renders must use matching pixel format. Set `Config.setVideoImageFormat("png")` + `Config.setColorSpace("bt709")` in the Remotion source's `remotion.config.ts` — otherwise the diff measures encoder differences (~0.05 SSIM hit), not translation fidelity.
+
+### Step 5: Document gaps
+
+Anything that didn't translate cleanly (volume ramps dropped, custom presentations approximated, fonts substituted) gets a `TRANSLATION_NOTES.md` written next to the HF output. See [`references/limitations.md`](references/limitations.md) for the format.
+
+## What this skill explicitly does NOT do
+
+- **Translate React state machines.** Compositions that drive animation via `useState` + `useEffect` are not deterministic frame-capture targets in HyperFrames' seek-driven model. Recommend the runtime interop pattern.
+- **Run Remotion's render pipeline alongside HyperFrames.** That's the runtime interop pattern from [PR #214](https://github.com/heygen-com/hyperframes/pull/214) — a separate solution for compositions that fail this skill's lint.
+
+(`@remotion/lambda` is _not_ a blocker — Lambda config is deployment, not animation. The skill drops it as a warning and translates the rest. See [`references/escape-hatch.md`](references/escape-hatch.md).)
+
+## How to grade your own translation
+
+Run the test corpus orchestrator:
+
+```bash
+./assets/test-corpus/run.sh
+```
+
+It runs T1, T2, T3 (render + diff) and T4 (lint validation), prints a per-tier pass/fail table, and emits an aggregate JSON report. Use this to verify the skill is working end-to-end on a clean checkout — and as a regression check after editing any reference.
+
+Validated baseline (as of 2026-04-27):
+
+| Tier | Composition shape                           | Mean SSIM | Threshold |
+| ---- | ------------------------------------------- | --------- | --------- |
+| T1   | single-element fade-in                      | 0.974     | 0.95      |
+| T2   | multi-scene + spring + audio + image        | 0.985     | 0.95      |
+| T3   | data-driven, custom subcomponents, count-up | 0.953     | 0.90      |
+| T4   | escape-hatch (8 lint cases)                 | 8/8 pass  | n/a       |

package/skills/remotion-to-hyperframes/assets/test-corpus/run.sh

@@ -0,0 +1,249 @@
+#!/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

package/skills/remotion-to-hyperframes/assets/test-corpus/tier-1-title-card/README.md

@@ -0,0 +1,41 @@
+# Tier 1 — title-card-fade
+
+## What it tests
+
+The simplest non-trivial Remotion → HyperFrames translation. A single text
+element fades in over the first 0.5 s, holds for 2.0 s, and fades out over
+the last 0.5 s. No audio, no media, no custom components.
+
+If a translation can't pass T1, it's broken on table-stakes basics:
+`AbsoluteFill`, `useCurrentFrame`, `interpolate` with multi-segment input,
+and the timing offset between Remotion's frame-based driver and HF's
+paused-GSAP driver.
+
+## Translation walk-through
+
+| Remotion                                                      | HyperFrames                                                                                             |
+| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `<AbsoluteFill style={{ backgroundColor: "#0a0a0a" }}>`       | `<body style="background: #0a0a0a">` + a positioned root div                                            |
+| `useCurrentFrame()`                                           | dropped — HF seeks the timeline                                                                         |
+| `interpolate(frame, [0, 15, 75, 90], [0, 1, 1, 0])` at fps=30 | `gsap.timeline({ paused: true })` with three `.to()` calls at offsets 0s/0.5s/2.5s, each `ease: "none"` |
+| `<div style={{ opacity }}>HELLO</div>`                        | static markup; opacity is animated by the timeline                                                      |
+
+The Remotion→HF time conversion is `time = frame / fps`. So
+`[0, 15, 75, 90]` at 30 fps becomes `[0, 0.5, 2.5, 3.0]` seconds.
+
+## How to render and evaluate
+
+```bash
+# Render Remotion baseline
+cd remotion-src && npm install && npm run render
+# Renders to remotion-src/out/baseline.mp4
+
+# Render HyperFrames translation
+cd ../hf-src && npx hyperframes render --output ../hf.mp4
+
+# Compare with the eval harness (from skill scripts/)
+../../../scripts/render_diff.sh ./remotion-src/out/baseline.mp4 ./hf.mp4 ./diff
+```
+
+`expected.json` documents the SSIM threshold (0.95) for this fixture; the
+calibrated mean against Remotion @ 4.0 with PNG/BT.709 output is 0.974.

package/skills/remotion-to-hyperframes/assets/test-corpus/tier-1-title-card/expected.json

@@ -0,0 +1,26 @@
+{
+  "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."
+}

package/skills/remotion-to-hyperframes/assets/test-corpus/tier-1-title-card/hf-src/index.html

@@ -0,0 +1,61 @@
+<!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>

package/skills/remotion-to-hyperframes/assets/test-corpus/tier-1-title-card/remotion-src/package.json

@@ -0,0 +1,14 @@
+{
+  "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"
+  }
+}

package/skills/remotion-to-hyperframes/assets/test-corpus/tier-1-title-card/remotion-src/remotion.config.ts

@@ -0,0 +1,13 @@
+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);

package/skills/remotion-to-hyperframes/assets/test-corpus/tier-1-title-card/remotion-src/src/Root.tsx

@@ -0,0 +1,13 @@
+import { Composition } from "remotion";
+import { TitleCard } from "./TitleCard";
+
+export const RemotionRoot = () => (
+  <Composition
+    id="TitleCard"
+    component={TitleCard}
+    durationInFrames={90}
+    fps={30}
+    width={1280}
+    height={720}
+  />
+);

package/skills/remotion-to-hyperframes/assets/test-corpus/tier-1-title-card/remotion-src/src/TitleCard.tsx

@@ -0,0 +1,34 @@
+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>
+  );
+};

package/skills/remotion-to-hyperframes/assets/test-corpus/tier-1-title-card/remotion-src/src/index.ts

@@ -0,0 +1,4 @@
+import { registerRoot } from "remotion";
+import { RemotionRoot } from "./Root";
+
+registerRoot(RemotionRoot);

package/skills/remotion-to-hyperframes/assets/test-corpus/tier-1-title-card/remotion-src/tsconfig.json

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