プラグインのインストール: セットアップやfreshnessコマンドの前に、このスキルが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行目を確認してください:beginframevsscreenshot、GPUモード、ステージタイミング。Linuxでscreenshot+software gpuは低速パスです。
HyperFrames は HTML から動画をレンダリングします。コンポジションは、DOM が 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つの一時停止タイムライン
各コンポジションは、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は、ハードコードされた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は有限のルートdata-durationの下でのみ許可(クリップをそれにエクスポート — そうでなければ有限回数を使用)。→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)。これにより、自身の#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-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を実行