HyperFrames Core は何をしますか?
エージェント向け注意点(最初にお読みください):
- flex/
insetで中央揃えにし、CSStransform: translate(-50%,-50%)を使用しないでください。GSAP でx/yをアニメーションするノードに対して使用すると競合します。Lint メッセージ:gsap_css_transform_conflict。代わりにfromToまたはxPercent/yPercentを使用してください。 - シーン終了時に
tl.set(..., {visibility:"hidden"})を追加しないでください。ランタイムはすでにタイミング設定されたクリップを非表示にします。内部ノード(または.clipのopacity)での透明度フェードで十分です。キャプションの強制終了は別ルールです。 window.__timelines["id"]はルートのdata-composition-idと一致する必要があります。render後、サマリーの 2 行目を読んでください:beginframevsscreenshot、GPU モード、ステージタイミング。screenshot+ Linux のsoftware gpuは低速パスです。
HyperFrames は HTML からビデオをレンダリングします。コンポジションとは、data-* 属性でタイミングを宣言し、アニメーションランタイムがシーク可能で、メディア再生がフレームワークに所有される 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(エラー)で無条件に拒否します。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 つのハード制限:lintは、data-startを持つ<video>が同じくdata-startを持つ別の プレーン 要素内にある場合にエラーとし、その失敗は現実のものになります(間違ったソースフレームが取得され、クリップがスロット途中で消えます)。そのため、タイミングはラッパーかビデオのどちらか一方に設定し、両方には決して設定しないでください。サブコンポジションホストは対象外です:サブコンポジション内のメディアは正しくレンダリングされます。もう 1 つの注意点は配置ではなくタイムラインです:サブコンポジションのタイムラインはホストルート要素をアニメーションできません。→variables-and-media.md- すべての
idを アセンブルされた ページ全体で一意に保ってください(サブコンポジションの 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を実行する