heygen-com/hyperframes

プラグインのインストール: セットアップまたはフレッシュネスコマンドの前に、このスキルがHyperFramesプラグイン内にある場合は、プラグイン実行ルールに従ってください。スタンドアロンインストールの場合は、以下の更新手順をそのまま使用します。

HyperFrames Core

エージェントの落とし穴（最初にお読みください）：

• センタリングはflex/insetを使用し、後でGSAPのx/yでアニメーションさせるノードにCSS transform: translate(-50%,-50%)を使用しないでください。リンター: gsap_css_transform_conflict。代わりにfromToまたはxPercent/yPercentを使用してください。
• シーン終了時にtl.set(..., {visibility:"hidden"})を追加しないでください。ランタイムは既にタイミング指定されたクリップを非表示にします。内部ノード（または.clipのopacity）での不透明度フェードで十分です。キャプションのハードキルは別のルールです。
• window.__timelines["id"]はルートのdata-composition-idと一致している必要があります。
• render後、サマリーの2行目を確認してください：beginframe vs screenshot、GPUモード、ステージタイミング。Linuxでのscreenshot + software gpuは低速パスです。

HyperFramesはHTMLからビデオをレンダリングします。コンポジションとは、data-*属性でDOMがタイミングを宣言し、アニメーションランタイムがシーク可能で、メディア再生がフレームワークによって管理されるHTMLファイルです。

このスキルは技術的な契約です — 1つのhyperframesプロジェクトを構築する方法について説明します。以下の本文は構築ガイドです。トピックごとの詳細はreferences/（次はインデックス）にあり、必要に応じて参照してください。プロセスドキュメント（ブリーフ、ストーリーボード、レビュー、プロダクション、ディスパッチ、フレームワーカー）は/hyperframes → references/にあります。その他の関心事は、関連するドメインスキル（hyperframes-animation、hyperframes-creative、media-use、hyperframes-cli、hyperframes-registry）にあります。各スキルがカバーする内容については、/hyperframesの機能マップを参照してください。

リファレンス

ファイル	これを読む目的…
references/minimal-composition.md	最小のレンダリング可能なコンポジションスケルトンから始める
references/composition-patterns.md	モノリシックとモジュラーのどちらかを選択する。モジュラーなindex.htmlを構造化する。サブコンポのアーキタイプを選択する。
references/data-attributes.md	任意のdata-*（ルート / クリップ / サブコンポホスト / レガシーエイリアス）を検索する。class="clip"を使用する。
references/tracks-and-clips.md	data-track-indexが制御するもの（そして制御しないもの）を理解する、z-index、別のクリップに対する相対時間。npx hyperframes timelineですべてのトラックとクリップを一覧表示する。
references/creator-editing-recipes.md	信頼できるカット/トリム/並べ替え/再タイミング/フリーズ/カメラ/マスク/クロスフェード/オーディオ編集レシピとその制限をコピーする。
references/sub-compositions.md	サブコンポジション（ホスト属性、<template>、インスタンス変数）を配線し、その内部でアニメーションさせる。
references/variables-and-media.md	変数を宣言する。<video>/<audio>を配置し、音量を設定し、トリミングする。
references/determinism-rules.md	シーク可能なタイムラインを構築する。決定論の禁止事項。レイアウト / テキストフィット。
references/full-screen-motion.md	共有背景を使用したフルフレームモーションを作成する。
references/tailwind.md	Tailwind v4プロジェクトで作業する（init --tailwind。ランタイム契約はStudioのv3とは異なります）。

アニメーションランタイムの詳細（GSAP API、Lottie、Three.jsなど）については、hyperframes-animation → adapters/<runtime>.mdを参照してください。

コンポジションの構築

2つのルート形式（互換性なし）

• スタンドアロン（トップレベルのindex.html）：ルート<div data-composition-id="…">が<body>内に直接配置されます。<template>ラッパーはありません。スタンドアロンルートをラッピングするとすべてのコンテンツが非表示になり、lintでエラーとして拒否されます（standalone_composition_wrapped_in_template）。
• サブコンポジション（data-composition-src経由で読み込み）：ルートを<template>でラップします。これが記述すべき形式です。ローダーはプレーンな完全なドキュメントも受け入れ、その<body>にフォールバックしますが、テンプレート形式が例とツールで想定されているものです。

⚠ 転送ルール：テンプレート化されたサブコンポジションの場合、アセンブラはファイル自身の<head>の<style>/<script>を削除します（packages/core/src/compiler/compositionAssembly.ts、hasTemplateゲート）。そのため、<style>/<script>はテンプレート内部に配置してください。<link>はどちらの場合もホイストされます。 ⚠ ホストIDの慣例：ホストスロット、内部テンプレート、およびwindow.__timelines["<id>"]キーに同じIDを指定してください。異なるローカルIDもサポートされています（アセンブラはファイル内の最初のルートにフォールバックします）が、不一致はサイレントであるため、特別な理由がない限り一致させてください。

ファイル形状、ホスト配線、およびレンダリング前チェックリスト → references/sub-compositions.md。

ルートはサイズ指定が必要（サイレントレイアウトバグ）

スタンドアロンルートはwidth/height: 100%を作成します。キャンバスサイズはdata-width/data-heightです。ランタイムはこれらのピクセルをコンポジションルートにスタンプします。#rootに1920px/1080pxをハードコードしないでください。スケルトン → references/minimal-composition.md。

1つの一時停止タイムライン

各コンポジションは、window.__timelines["<id>"]（キー = ルートdata-composition-id）に正確に1つのgsap.timeline({ paused: true })を登録します。非同期コールバック（document.fonts.ready）内での構築もサポートされています。重要なのは、構築が完了した後にのみ登録することです。レンダリング長はルートのdata-durationであり、タイムラインの長さではありません：タイムラインがそれを超えるとカットされ、早期に終了すると最後のフレームを保持します。ルートのdata-durationを省略すると、長さは代わりに推測されます（タイムライン、メディアウィンドウ、またはアダプター）。window.__timelines = window.__timelines || {}は必要ありません：ランタイムはインラインスクリプトが実行される前にレジストリを作成し、lintはもはやそれを要求しません。サブタイムラインを手動でホストにネストしないでください。ランタイムは登録された子タイムラインを自動的にネストします。完全な契約（非GSAPランタイムを含む） → references/determinism-rules.md + hyperframes-animation/adapters/。

最初のパスでのlintの落とし穴（最初のビルドが確実に失敗する）

lintが実際にキャッチするルールですが、事後的にのみです。最初から正しく記述してください：

• CSSの初期transformと、同じプロパティに対するGSAPトゥイーンを決して組み合わせないでください — CSS値とトゥイーンの開始が競合し、lintはgsap_css_transform_conflictで拒否します。CSSのtransform: translateX(-40px)の代わりに、gsap.fromTo(el, { x: -40 }, { x: 0 })を使用してトゥイーン内で初期状態を設定してください。
• <video>/<audio>にcrossoriginを決して付けないでください。lintはそれをmedia_crossorigin_breaks_preview（エラー）で無条件に拒否します。キャンバス/WebGL/WebAudioの読み戻しも含みます。抑制はありません。
• data-startを持つ<video>に、同じくdata-startを持つ祖先を与えないでください。lintはvideo_nested_in_timed_element（エラー）で拒否します。ラッパーまたはビデオのどちらか一方にタイミングを設定し、両方には設定しないでください。
• すべての<audio>にはidが必要です。lintはmedia_missing_idで拒否し、idのない<audio>はミキサーによって決してピックアップされないため、レンダリングは無音になります。
• .clipをautoAlphaまたはvisibilityでトゥイーンしないでください — lintはgsap_animates_clip_elementで拒否します。代わりに子要素をアニメーションさせてください。
• 名前付きCSS font-familyには、出荷されたローカルファイルへのファイル内@font-faceが必要です。そうしないと、lintがfont_family_without_font_faceを発動します。
• サブコンポジション#rootはwidth/height: 100%（またはinset: 0）を使用し、1920px/1080pxをハードコードしないでください。キャンバスサイズはdata-width/data-heightです。

lint エラーはレイアウトとコントラストの監査もオフにします：checkはその後0 sample(s)と0/0 text checksを報告します。これはクリーンファイルのように見えますが、何も実行されなかったことを意味します。これらの数値を信頼する前に、lintエラーをクリアしてください。

交渉の余地のないルール（自動ゲートが見逃す可能性のあるサイレントバグ）

ここに示します。完全な根拠はリンクされたリファレンスにあります。違反しないでください：

• レンダリング時間のクロック / シードされていないMath.random / ネットワーク / 入力状態は使用しないでください。repeat: -1は使用しないでください（有限カウントを使用）。 → determinism-rules.md
• .clip要素でdisplay、visibility、またはautoAlphaを決してトゥイーンしないでください。フレームワークがクリップの可視性を所有し、lintはそれを拒否します（gsap_animates_clip_element）。代わりに子要素をアニメーションさせてください。 → determinism-rules.md
• 本文テキストに<br>は使用しないでください。変換された要素はブロックレベルでサイズ指定されている必要があります。パルスする絶対配置の装飾要素にはピーククリアランスが必要です。 → determinism-rules.md
• <video>/<audio>はフラットなドキュメントクエリによって検出されるため、フレームワークはそれらを任意のネスト深度でシークおよびデコードします（サブコンポ<template>またはラッパー内も含む）。1つのハードリミット：data-startを持つ<video>が、同じくdata-startを持つ別のプレーンな要素（サブコンポジションホストは例外）の内側にある場合、lintはエラーになります。また、実際の失敗（間違ったソースフレーム、その後ミッドスロットでクリップが消える）が発生するため、タイミングはラッパーまたはビデオのどちらか一方に設定し、両方には設定しないでください。サブコンポジションホストは例外です：サブコンポジション内のメディアは正しくレンダリングされます。もう1つの注意点はタイムラインであり、配置ではありません：サブコンポのタイムラインはホストルート要素をアニメーションできません。 → variables-and-media.md
• アセンブルされたページ全体で各idを一意に保ってください（サブコンポのidにはコンポジションidを接頭辞として付けます、#<id>-hero）。これにより、独自の#id CSSとgetElementById呼び出しが解決されます。フレームインジェクションはもはやそれに依存しません：コンパイラはすべてのvideo[src]/audio[src]/img[src]にドキュメント一意のdata-hf-render-idをスタンプします。src属性の代わりに<source>子要素を使用するメディアはスタンプされないため、そこで一意のidが依然として重要です。 → composition-patterns.md
• コンポジションルートへの全画面フィルは、通常のレンダリングでは問題ありません。レイヤードコンポジットパス（HDRコンテンツ、またはシェーダートランジションを使用するコンポジション）でのみドロップされます。このパスでは、エンジンがすべてのコンポジションルートを透明に強制し、下のレイヤーが透けて見えるようにします。コンポジションがシェーダートランジションまたはHDRメディアを使用する場合は、フィルを全面子要素（position:absolute; inset:0）に配置してください。 → composition-patterns.md

既存のコンポジションの編集

• 最初にファイルを読んでください。無関係なタイミング、トラック、ID、変数、メディアパスは保持してください。
• プロジェクトのタイムライン上にあるもの（トラック、クリップ、開始、終了、再生内容）を確認するには、index.htmlとすべてのサブコンポジションファイルを読む代わりに、npx hyperframes timeline [--json]を実行してください。
• 既存のコンポジションIDとタイムラインキーに一致させてください。
• クリップを追加する：周囲のクリップに対して意図的にdata-start/data-durationを設定してください。data-track-indexはStudioの表示レーンであり、タイミングの制約ではないため、空いている必要はありません。
• ルートのdata-durationを超えて終了するクリップはカットされます：同じ編集でルートのdata-durationをクリップの終了まで拡張してください（lintはclip_ends_past_root_durationを警告します）。
• 任意のコンポジション要素のdata-hiddenは、プレビューとレンダリングの両方でその要素を非表示にし、その時間枠をオーバーライドします。これは非破壊的/可逆的であり、Studioのタイムライン目のアイコンで切り替えられます。
• サブコンポジションを追加する：ホストを配線する前に、内部のdata-composition-idを確認してください。

検証

コマンドの詳細についてはhyperframes-cliを使用してください。

• npx hyperframes checkが成功する（lint、ランタイム、レイアウト、モーション、コントラスト全体で0件の検出）
• サブコンポジションがあるプロジェクト：npx hyperframes snapshot --at <midpoints>を実行し、各フレームを目視確認する
• レビュー用にnpx hyperframes preview --backgroundを実行する（ユーザーはStudioのタイムラインで何でも編集でき、サーバーは呼び出しコマンド後も存続します）
• ユーザーが承認した後にのみnpx hyperframes renderを実行する