HyperFrames コアコンポジションコントラクト

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

HyperFrames コア

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

• flex/inset で中央揃えにし、GSAP で x/y を適用するノードに CSS の transform: translate(-50%,-50%) を使わないでください。Lint: 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モード、ステージタイミング）を読んでください。screenshot + Linux 上の 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	モノリシック vs モジュラーを選択する。モジュラー 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（エラー）で無条件に拒否します。canvas/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 は、ハードコードされた 1920px/1080px ではなく、width/height: 100%（または inset: 0）を使用します。キャンバスサイズは 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 を実行する