HyperFrames コア
エージェントの落とし穴(最初に読むこと):
- 中央揃えには flex/
insetを使用し、後で GSAP でx/yをアニメーションするノードに CSStransform: 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行目を読んでください:beginframevsscreenshot、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 | モノリシック 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つの一時停止タイムライン
各コンポジションは、正確に1つ の gsap.timeline({ paused: true }) を window.__timelines["<id>"](キー = ルート data-composition-id)に登録します。非同期コールバック(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で拒否します。CSStransform: 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>-hero)。これにより、独自の#idCSS と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-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