1仕組みと動作原理
最初に静的 lint を実行して「翻訳可能か」を判定：スクリプトがルールに基づいて Remotion ソースコードを走査し、検出結果を blocker（翻訳を拒絶しランタイム相互運用を代替提案）/ warning（該当構造を破棄して翻訳を続行するが TRANSLATION_NOTES.md に差分を記録）/ info（翻訳して注記）の3段階に分類。
skills/remotion-to-hyperframes/scripts/lint_source.py
Blockers (skill should refuse to translate): - r2hf/use-state React state machine drives animation - r2hf/use-effect-deps useEffect/useLayoutEffect with non-empty deps (side effects) - r2hf/use-reducer useReducer drives animation - r2hf/async-metadata calculateMetadata returns a Promise - r2hf/third-party-react-ui Imports a React UI library (shadcn, mui, antd, mantine, chakra)
ここで行われていること：HF の seek 駆動モデルでは決定論的に表現できない Remotion の記法を、事前に実行可能な静的チェックとして検出。blocker に該当した場合は直ちに停止し、references/escape-hatch.md を参照して PR #214 のランタイム相互運用を提案。warning は翻訳を中断しない。スクリプト自体はテキスト/正規表現解析のみを行い（import は argparse/json/re/sys/dataclasses/pathlib のみ）、走査対象のコードは実行しない。
翻訳は機械的マッピング＋必要に応じたトピック別リファレンスの読み込み：api-map.md をインデックスとし、ソースに出現する API に応じて該当トピック（parameters/sequencing/timing/media/transitions/lottie/fonts）のみを読み込み、一度に全件を読み出さない。
skills/remotion-to-hyperframes/SKILL.md
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
ここで行われていること：作成者は約80%が機械的翻訳可能で、20%は不可逆的（ロスあり）と明示。不確実性を明記し、破損した HTML を無理に出力するのではなく、その20%を「拒絶＋代替提案」で処理する。
出力形式は固定：composition-id/start/duration/fps/寸法および各スカラープロパティの data-* を保持する1つの <div id="stage">、data-start/data-duration/data-track-index を持つフラットなシーン div、底部で一時停止され window.__timelines に登録された GSAP タイムライン。
skills/remotion-to-hyperframes/SKILL.md
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.
ここで行われていること：React の「フレームごとの再評価」パラダイムを「一時停止されたタイムライン上のトゥイーン」パラダイムに変換。これが useState/useEffect 駆動のアニメーションを翻訳できない根本原因（フレーム決定論的ではないため）。
検収は「見た目の印象」ではなく定量化可能な SSIM：同梱の4段階テストコーパス T1〜T4 で各平均 SSIM と閾値ベースラインを提示。エンコーダ差異の混入を防ぐため、両側のレンダリングで同一のピクセルフォーマット使用を義務付け。
skills/remotion-to-hyperframes/SKILL.md
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.
ここで行われていること：「翻訳の再現性」を回帰テスト可能な指標化。ベースライン表（2026-04-27）：T1 単一要素フェードイン 0.974/閾値 0.95、T2 複数シーン+spring+音声+画像 0.985/0.95、T3 データ駆動+カスタム子コンポーネント+カウント 0.953/0.90、T4 8つの lint エスケープケース 8/8 パス。また同セクションでは「both renders must use matching pixel format」（png + bt709 を設定しないと約 0.05 SSIM のエンコーダ差異を検出してしまう）という重要な注意点も明記。
差異デバッグ用の専用ツール：frame_strip.sh で「基準フレーム | 翻訳フレーム」を並べたストリップ画像を生成しズレているフレームを特定。render_diff.sh でフレームごとの SSIM を出力し summary.json（mean/min/p05/p95/frame_count/pass）を生成。
skills/remotion-to-hyperframes/scripts/render_diff.sh
# render_diff.sh — compute per-frame SSIM between two video files. # # The eval primitive for the remotion-to-hyperframes skill: given a Remotion # render and a HyperFrames render of the same composition, report whether the # translation is visually equivalent.
ここで行われていること：「だいたい合っている」を特定可能な診断チェーンに分解。まず p05/mean で失敗を判定し、ストリップ画像で該当フレームを確認した上で、該当するトピック別リファレンス（timing/sequencing/media）を参照して修正する。
差分の記録を義務化：クリーンに翻訳できなかった要素（音量ランプ、カスタムプレゼンテーション、フォント置換など）は、HF 出力の横にある TRANSLATION_NOTES.md にすべて記録。さらに本スキルが対応しない事項（逆方向のエクスポート、Remotion 以外のソース、React ステートマシン、Remotion とのレンダリングパイプライン並行実行）を明示。
skills/remotion-to-hyperframes/SKILL.md
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.
ここで行われていること：「サイレントな品質低下」の防止。損失が発生した場合は必ず明示的に記録する。また、「@remotion/lambda は（アニメーションではなくデプロイに関するものなので）blocker ではない」といった判定境界も明記し、誤検知による拒否を防ぐ。
2コア機能
01Remotion → HyperFrames への単方向ソース移植（この単一方向のみに対応することを明示）
02実行可能な翻訳適合性 lint（3段階の検出 + 行/列 + rule id + 推奨事項；--json をサポート）
03API トピック別のマッピングインデックス（Composition/Sequence/Series/Loop/Freeze/useCurrentFrame/interpolate/spring/Audio/Video/Img/IFrame/staticFile/TransitionSeries/lottie/google-fonts…）
04段階的テストコーパス + SSIM 回帰ベースライン（T1 単一要素フェードイン / T2 複数シーン+spring+音声+画像 / T3 データ駆動+子コンポーネント / T4 8つの lint エスケープケース）
05差異特定ツール：並列フレームストリップ（frame_strip.sh）およびフレーム単位の SSIM レポート（render_diff.sh、p05 および pass 判定を含む）
06自己テスト/スモークテスト：スクリプト層は実際の Remotion や HF パイプラインに依存せず、ハーネス出力の妥当性を検証可能（ffmpeg testsrc で合成入力を生成）
07拒絶と代替提案パス：blocker 検出時には壊れた HTML を出力せず、PR #214 のランタイム相互運用を代替提案
3外部依存関係
| Kind | Dependency / Endpoint |
|---|---|
| cli | hyperframes CLI（渲染翻译产物：npx hyperframes render --skill=remotion-to-hyperframes） |
| cli | Remotion CLI（生成基准渲染：npx remotion render <CompositionId> out/baseline.mp4） |
| cli | ffmpeg / ffprobe（SSIM 比较、帧抽取、条带拼图；脚本缺它即 exit 2） |
| cli | python3（lint_source.py 与 frame_strip.sh 内嵌的 python 片段） |
| package | HF 侧可选包（shader-transitions / lottie 适配器等，由 api-map 引用；HF 侧的 blocks 目录） |
| network | 文档外链（仅参考；fonts.md 里的 Google Fonts 预连接示例属于产出 HTML 的写法，非本 skill 调用） |
| cli | hyperframes skills update（自刷新，需网络） |
4推奨統制措置と判定根拠
安全運用のための推奨統制措置
Agent 向け
段階的・都度認可、サンドボックス推奨
管理者向け
承認フロー、ロールバック可能、全履歴監査
判定根拠（ファイルパスと抜粋）
- scripts/: ローカルスクリプトまたはコマンドの実行: python3 scripts/lint_source.py <remotion-src> [--json]（走査対象ディレクトリの静的テキスト解析。走査対象コードは実行しない）
- 本地工作目录: ファイルの読み書きと成果物の出力: 翻訳生成物：hf-src/index.html（HF コンポジション）および TRANSLATION_NOTES.md
監査ノート： 動作面はクリーンかつ検証可能です。すべてのスクリプトはローカルツール（python3 による静的 lint + ffmpeg/ffprobe による SSIM 計算および画像結合）であり、ローカルファイルの読み書きのみを行います。ディレクトリ全体でネットワーク通信ゼロ、認証情報読み取りゼロ、外部パッケージダウンロードゼロ（pip/npm によるインストールなし）です。環境として必要な動作は、ffmpeg/ffprobe の呼び出しと、（ユーザーが実行する）npx レンダリングコマンドのみです。外部送信が一切ないため「イエロー」には該当せず、ローカルスクリプトの実行およびユーザーソースディレクトリの読み取りと生成物の書き込みを行うため「グリーン」には該当しません。留意点：ユーザーの Remotion ソースディレクトリが読み取られ（モデルが翻訳生成のために参照）、テストコーパス内に fetch の例が存在します（lint のテスト入力としてのみ使用され、実行はされません）。
5二重目の独立検証
- [ok] 是否真的零网络 / 零凭证（蓝档判定的关键） — 脚本层 fetch/curl/wget/http.request 0 命中；process.env 命中仅 3 处且在 tier-4 的 validate.sh 里读路径变量；无 API_KEY/TOKEN/SECRET/.env/Bearer 命中。27 处 URL 全部可解释为文档链接、示例 HTML 资源或测试夹具端点。
- [ok] 测试夹具里的 fetch / example.com 是否会被执行（是否构成隐藏外发） — 逐文件确认：tier-4 的 8 个 .tsx 与 scripts/tests/fixtures/*.tsx 只被 lint_source.py 以文本方式扫描（脚本无 subprocess/无 import 被扫描模块），run.sh 的 T4 分支只跑 lint 校验（'It runs T1, T2, T3 (render + diff) and T4 (lint validation)'）。不会被渲染或执行，因此不构成外发。
- [ok] 『外部资源』逐条回查调用点 — npx remotion render 与 npx hyperframes render 在 SKILL.md Step 4 原文；ffmpeg/ffprobe 的存在性检查与调用在 render_diff.sh/frame_strip.sh 原文；python3 调用在 frame_strip.sh 原文；shader-transitions 与 lottie 适配器链接在 api-map.md/lottie.md 原文。无推测项。
- [ok] lint 规则是否真能拦住它宣称拦的东西（blocker 是否只是文档口号） — lint_source.py 的 docstring 与 THIRD_PARTY_UI_PACKAGES 集合、rule id（r2hf/use-state、r2hf/use-effect-deps、r2hf/use-reducer、r2hf/async-metadata、r2hf/third-party-react-ui 等）在源码中真实存在，并配有 8 个 tier-4 用例与 validate.sh 断言（'8/8 pass' 基线）。规则实现与文档口径一致。
- [unlocatable] 验证：SSIM 阈值基线表是否可在源码内复算 — SKILL.md 的基线表（T1 0.974、T2 0.985、T3 0.953、T4 8/8，日期 2026-04-27）是历史测量值；复算需要执行 Remotion 与 HF 两条渲染管线（本任务禁止构建/渲染，且环境未验证具备 Remotion）。故该表按『文档声明』记录，不在结论中当作已验证事实。
- [ok] meta.official_desc 与 SKILL.md 原文的逐字比对（体检工具的 ⚠ 项） — 本 skill 的 frontmatter 用 YAML 单引号风格书写：`description: 'Port an existing Remotion (React) composition''s source to …'`——文件里的两个连续单引号是 YAML 的转义语法，解析后的字符串值是带**一个**撇号的 `composition's`。本 JSON 的 meta.official_desc 记录的是解析后的真实描述文本（与 YAML 解析结果一致），因此对**原始文件字节**做朴素逐字比对时会出现一处不可避免的差异（源码里的 `composition''s` vs 记录值的 `composition's`）。这不是改写，也不影响展示层：如实记录为报告口径差异，而非内容出入。
6結論
最適な用途： 手元に既存の Remotion（React）コンポジションソースがあり、それを HyperFrames HTML に移植することを明確に要求しているプロジェクトに最適。特に回帰テスト可能な検証を求めるチームに適しており、本スキルが提供する4段階テストコーパスと SSIM 閾値を用いることで、「翻訳再現性」を CI や手動回帰テストに組み込める。また、「手元の Remotion ソースが翻訳可能かどうか」を判定したいケースにも適している（lint_source.py を1回実行するだけで blocker/warning のリストを取得可能）。
不向きな用途： 非推奨：① HyperFrames 作品の新規作成（手元に類似の Remotion 動画がある場合も含む）— /general-video を使用すべき；② 単に「私の Remotion 動画のようなものを作りたい」という要望（description にて新規作成として扱うよう明示）；③ 逆方向エクスポート（HF → Remotion や他フレームワーク）；④ Remotion 以外のソース（After Effects .aep、Framer Motion、純粋な React/CSS）；⑤ ステートマシン駆動の Remotion コンポジション（blocker に該当するため、ランタイム相互運用を使用すべき）；⑥ レンダリングレベルの評価を実行したくないケース（実行しないと検証できず、正確性を担保できないため）。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload remotion-to-hyperframes.tar.gz
sha256:
Option B · Copy Guide for Agent7dc73746cff19b96…Agent はこの JSON ガイドから自動的にダウンロードして検証します。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit b8328f9573.