zilmate 1.9.3 → 1.10.1

package/.agents/skills/prompt-engineering-patterns/scripts/optimize-prompt.py

@@ -0,0 +1,279 @@
+#!/usr/bin/env python3
+"""
+Prompt Optimization Script
+
+Automatically test and optimize prompts using A/B testing and metrics tracking.
+"""
+
+import json
+import time
+from typing import List, Dict, Any
+from dataclasses import dataclass
+from concurrent.futures import ThreadPoolExecutor
+import numpy as np
+
+
+@dataclass
+class TestCase:
+    input: Dict[str, Any]
+    expected_output: str
+    metadata: Dict[str, Any] = None
+
+
+class PromptOptimizer:
+    def __init__(self, llm_client, test_suite: List[TestCase]):
+        self.client = llm_client
+        self.test_suite = test_suite
+        self.results_history = []
+        self.executor = ThreadPoolExecutor()
+
+    def shutdown(self):
+        """Shutdown the thread pool executor."""
+        self.executor.shutdown(wait=True)
+
+    def evaluate_prompt(self, prompt_template: str, test_cases: List[TestCase] = None) -> Dict[str, float]:
+        """Evaluate a prompt template against test cases in parallel."""
+        if test_cases is None:
+            test_cases = self.test_suite
+
+        metrics = {
+            'accuracy': [],
+            'latency': [],
+            'token_count': [],
+            'success_rate': []
+        }
+
+        def process_test_case(test_case):
+            start_time = time.time()
+
+            # Render prompt with test case inputs
+            prompt = prompt_template.format(**test_case.input)
+
+            # Get LLM response
+            response = self.client.complete(prompt)
+
+            # Measure latency
+            latency = time.time() - start_time
+
+            # Calculate individual metrics
+            token_count = len(prompt.split()) + len(response.split())
+            success = 1 if response else 0
+            accuracy = self.calculate_accuracy(response, test_case.expected_output)
+
+            return {
+                'latency': latency,
+                'token_count': token_count,
+                'success_rate': success,
+                'accuracy': accuracy
+            }
+
+        # Run test cases in parallel
+        results = list(self.executor.map(process_test_case, test_cases))
+
+        # Aggregate metrics
+        for result in results:
+            metrics['latency'].append(result['latency'])
+            metrics['token_count'].append(result['token_count'])
+            metrics['success_rate'].append(result['success_rate'])
+            metrics['accuracy'].append(result['accuracy'])
+
+        return {
+            'avg_accuracy': np.mean(metrics['accuracy']),
+            'avg_latency': np.mean(metrics['latency']),
+            'p95_latency': np.percentile(metrics['latency'], 95),
+            'avg_tokens': np.mean(metrics['token_count']),
+            'success_rate': np.mean(metrics['success_rate'])
+        }
+
+    def calculate_accuracy(self, response: str, expected: str) -> float:
+        """Calculate accuracy score between response and expected output."""
+        # Simple exact match
+        if response.strip().lower() == expected.strip().lower():
+            return 1.0
+
+        # Partial match using word overlap
+        response_words = set(response.lower().split())
+        expected_words = set(expected.lower().split())
+
+        if not expected_words:
+            return 0.0
+
+        overlap = len(response_words & expected_words)
+        return overlap / len(expected_words)
+
+    def optimize(self, base_prompt: str, max_iterations: int = 5) -> Dict[str, Any]:
+        """Iteratively optimize a prompt."""
+        current_prompt = base_prompt
+        best_prompt = base_prompt
+        best_score = 0
+        current_metrics = None
+
+        for iteration in range(max_iterations):
+            print(f"\nIteration {iteration + 1}/{max_iterations}")
+
+            # Evaluate current prompt
+            # Bolt Optimization: Avoid re-evaluating if we already have metrics from previous iteration
+            if current_metrics:
+                metrics = current_metrics
+            else:
+                metrics = self.evaluate_prompt(current_prompt)
+
+            print(f"Accuracy: {metrics['avg_accuracy']:.2f}, Latency: {metrics['avg_latency']:.2f}s")
+
+            # Track results
+            self.results_history.append({
+                'iteration': iteration,
+                'prompt': current_prompt,
+                'metrics': metrics
+            })
+
+            # Update best if improved
+            if metrics['avg_accuracy'] > best_score:
+                best_score = metrics['avg_accuracy']
+                best_prompt = current_prompt
+
+            # Stop if good enough
+            if metrics['avg_accuracy'] > 0.95:
+                print("Achieved target accuracy!")
+                break
+
+            # Generate variations for next iteration
+            variations = self.generate_variations(current_prompt, metrics)
+
+            # Test variations and pick best
+            best_variation = current_prompt
+            best_variation_score = metrics['avg_accuracy']
+            best_variation_metrics = metrics
+
+            for variation in variations:
+                var_metrics = self.evaluate_prompt(variation)
+                if var_metrics['avg_accuracy'] > best_variation_score:
+                    best_variation_score = var_metrics['avg_accuracy']
+                    best_variation = variation
+                    best_variation_metrics = var_metrics
+
+            current_prompt = best_variation
+            current_metrics = best_variation_metrics
+
+        return {
+            'best_prompt': best_prompt,
+            'best_score': best_score,
+            'history': self.results_history
+        }
+
+    def generate_variations(self, prompt: str, current_metrics: Dict) -> List[str]:
+        """Generate prompt variations to test."""
+        variations = []
+
+        # Variation 1: Add explicit format instruction
+        variations.append(prompt + "\n\nProvide your answer in a clear, concise format.")
+
+        # Variation 2: Add step-by-step instruction
+        variations.append("Let's solve this step by step.\n\n" + prompt)
+
+        # Variation 3: Add verification step
+        variations.append(prompt + "\n\nVerify your answer before responding.")
+
+        # Variation 4: Make more concise
+        concise = self.make_concise(prompt)
+        if concise != prompt:
+            variations.append(concise)
+
+        # Variation 5: Add examples (if none present)
+        if "example" not in prompt.lower():
+            variations.append(self.add_examples(prompt))
+
+        return variations[:3]  # Return top 3 variations
+
+    def make_concise(self, prompt: str) -> str:
+        """Remove redundant words to make prompt more concise."""
+        replacements = [
+            ("in order to", "to"),
+            ("due to the fact that", "because"),
+            ("at this point in time", "now"),
+            ("in the event that", "if"),
+        ]
+
+        result = prompt
+        for old, new in replacements:
+            result = result.replace(old, new)
+
+        return result
+
+    def add_examples(self, prompt: str) -> str:
+        """Add example section to prompt."""
+        return f"""{prompt}
+
+Example:
+Input: Sample input
+Output: Sample output
+"""
+
+    def compare_prompts(self, prompt_a: str, prompt_b: str) -> Dict[str, Any]:
+        """A/B test two prompts."""
+        print("Testing Prompt A...")
+        metrics_a = self.evaluate_prompt(prompt_a)
+
+        print("Testing Prompt B...")
+        metrics_b = self.evaluate_prompt(prompt_b)
+
+        return {
+            'prompt_a_metrics': metrics_a,
+            'prompt_b_metrics': metrics_b,
+            'winner': 'A' if metrics_a['avg_accuracy'] > metrics_b['avg_accuracy'] else 'B',
+            'improvement': abs(metrics_a['avg_accuracy'] - metrics_b['avg_accuracy'])
+        }
+
+    def export_results(self, filename: str):
+        """Export optimization results to JSON."""
+        with open(filename, 'w') as f:
+            json.dump(self.results_history, f, indent=2)
+
+
+def main():
+    # Example usage
+    test_suite = [
+        TestCase(
+            input={'text': 'This movie was amazing!'},
+            expected_output='Positive'
+        ),
+        TestCase(
+            input={'text': 'Worst purchase ever.'},
+            expected_output='Negative'
+        ),
+        TestCase(
+            input={'text': 'It was okay, nothing special.'},
+            expected_output='Neutral'
+        )
+    ]
+
+    # Mock LLM client for demonstration
+    class MockLLMClient:
+        def complete(self, prompt):
+            # Simulate LLM response
+            if 'amazing' in prompt:
+                return 'Positive'
+            elif 'worst' in prompt.lower():
+                return 'Negative'
+            else:
+                return 'Neutral'
+
+    optimizer = PromptOptimizer(MockLLMClient(), test_suite)
+
+    try:
+        base_prompt = "Classify the sentiment of: {text}\nSentiment:"
+
+        results = optimizer.optimize(base_prompt)
+
+        print("\n" + "="*50)
+        print("Optimization Complete!")
+        print(f"Best Accuracy: {results['best_score']:.2f}")
+        print(f"Best Prompt:\n{results['best_prompt']}")
+
+        optimizer.export_results('optimization_results.json')
+    finally:
+        optimizer.shutdown()
+
+
+if __name__ == '__main__':
+    main()

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

@@ -0,0 +1,127 @@
+---
+name: remotion-to-hyperframes
+description: 'Port an existing Remotion (React) composition to HyperFrames HTML. Use ONLY when the user explicitly asks to port/convert/migrate/translate a Remotion source. Do NOT use: (a) authoring a new HyperFrames composition; (b) Remotion mentioned in passing; (c) Remotion code shared as reference only; (d) "same video as my Remotion one" without explicit migrate request — treat as fresh build. Doubt → `/general-video`. One-way, Remotion-only: no reverse export (HyperFrames→Remotion or any framework), no non-Remotion source (After Effects, Framer Motion, plain React/CSS) → out of scope, re-create via `/general-video`. Flags unsupported patterns (useState, useEffect, async calculateMetadata, third-party React libs, `@remotion/lambda`) and recommends runtime interop over lossy translation. Unsure whether to port vs. build fresh, or only a passing Remotion mention? → /hyperframes.'
+---
+
+# Remotion to HyperFrames
+
+> **Confirm the route before you build.** Use this **only** to port an existing **Remotion** (React) composition's source into HyperFrames. Authoring a **new** composition (even one inspired by a Remotion video) → the creation workflows / `/general-video`. **Out of scope** (one-way, Remotion-only): no reverse export (HyperFrames → Remotion or any framework), and a **non-Remotion** source (After Effects, Framer Motion, plain React / CSS) has no Remotion source to translate → re-create via `/general-video`. Unsure, or only a passing Remotion mention? **Read `/hyperframes` first.**
+
+## 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/.agents/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