HyperFrames Core は何をしますか?
HyperFrames は HTML からビデオをレンダリングします。コンポジションは、data-* 属性でタイミングを宣言し、アニメーションランタイムがシーク可能で、メディア再生がフレームワークに所有される HTML ファイルです。
このスキルは 技術契約 — 1つの hyperframes プロジェクトを構築する方法です。以下の本文はビルドガイドです。トピックごとの詳細は references/(次のインデックス)にあり、必要に応じて参照してください。その他の関心事は兄弟ドメインスキル — hyperframes-animation、hyperframes-creative、hyperframes-media、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 を処理; 別のクリップを基準にタイミングを設定 |
references/sub-compositions.md | サブコンポジションを接続(ホスト属性、<template>、インスタンスごとの変数)し、内部でアニメーション |
references/variables-and-media.md | 変数を宣言; <video>/<audio> を配置、音量設定、トリミング |
references/determinism-rules.md | シーク可能なタイムラインを構築; 決定論禁止事項; アニメート可能プロパティのホワイトリスト; レイアウト / テキストフィット |
references/full-screen-motion.md | 共有背景を使用してフルフレームモーションを作成 |
references/storyboard-format.md | STORYBOARD.md 計画(+ 解析されたマニフェスト)を作成 |
references/script-format.md | オプションの SCRIPT.md ロックされたナレーションを作成 |
references/subagent-dispatch.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>ラッパーはなし(ラップするとすべてのコンテンツが隠れてレンダリングが壊れます)。 - サブコンポジション(
data-composition-src経由でロード)— ルートは<template>でラップする必要があります。
⚠ トランスポートルール: ランタイムは
<template>の内容のみをクローンします; 外側(<head>スタイル/スクリプトを含む)はすべて破棄されるため、<style>/<script>はテンプレート 内側 に配置してください。 ⚠ ホストIDルール: ホストスロットのdata-composition-idは、内部テンプレートのdata-composition-idおよびwindow.__timelines["<id>"]キーと 完全に一致 する必要があります —-mount/-slot/-host接尾辞は付けないでください。
ファイル形状、ホスト配線、およびレンダリング前チェックリスト → references/sub-compositions.md。
ルートのサイズ指定が必要(静的なレイアウトバグ)
スタンドアロンルートは明示的な サイズ指定ボックス(width/height をpxで)が必要であり、height:100% 要素までのすべての祖先が解決された高さを持っている必要があります — そうしないと、flex/100% の子が約0に潰れてコンテンツが左上隅に詰まります。lint/validate/inspect はこれを キャッチしません。スケルトン → references/minimal-composition.md。
1つの一時停止タイムライン
各コンポジションは、ページロード時に 同期的に 構築された gsap.timeline({ paused: true }) を window.__timelines["<id>"](キー = ルート data-composition-id)に ちょうど1つ 登録します。レンダリング期間 = ルート data-duration、タイムラインの長さではありません。サブタイムラインを手動でホストにネストしないでください。完全な契約(非GSAPランタイムを含む)→ references/determinism-rules.md + hyperframes-animation/adapters/。
譲れないルール(lint/validate/inspect がキャッチしない静的なバグ)
ここに提示; 完全な根拠はリンクされたリファレンスにあります。違反しないでください:
- レンダリングタイムクロック / 未シードの
Math.random/ ネットワーク / 入力状態なし;repeat: -1なし(有限カウントを使用)。→determinism-rules.md - ビジュアルプロパティのホワイトリストのみアニメート;
display/visibilityは絶対に使用しない; 後続シーンのクリップにgsap.setを使用しない。→determinism-rules.md - 本文テキストに
<br>を使用しない; 変換された要素はブロックレベル + サイズ指定が必要; パルスする絶対配置装飾はピーククリアランスが必要。→determinism-rules.md <video>/<audio>はホストルートの 直接の子 である必要があります(サブコンポジション<template>/ラッパー内には絶対に配置しない); フレームワークが再生を所有します。→variables-and-media.md- すべての
idは 組み立てられた ページ全体で一意でなければなりません; サブコンポジション内では、id にコンポジションIDをプレフィックスとして付けます(#<id>-hero)。重複する<video>/<img>id は 空白 をレンダリングします — プロデューサーはgetElementByIdでフレームを注入するため、ファイルをまたがる重複はlintをすり抜けます。→composition-patterns.md - フルスクリーンシーンの塗りつぶしは、完全ににじみ出る 子(
position:absolute; inset:0)に配置し、コンポジションルート自体には決して配置しないでください — プロデューサーのフレーム合成は、ルート要素自身のbackgroundをドロップする可能性があります(フレームは 黒 でレンダリングされます)。プレビュー/snapshotでは正しく表示されていても。→composition-patterns.md
既存のコンポジションの編集
- 最初にファイルを読んでください。関係のないタイミング、トラック、ID、変数、メディアパスを保持してください。
- 既存のコンポジションIDとタイムラインキーに一致させてください。
- クリップを追加する場合: 重複しない
data-track-indexを選択するか、意図的に周囲のタイミングを調整してください。 - サブコンポジションを追加する場合: ホストを配線する前に、内部の
data-composition-idを確認してください。
検証
コマンドの詳細は hyperframes-cli を使用
-
npx hyperframes lintがパスする(エラー0) -
npx hyperframes validateがパスする(コンソールエラー0) -
npx hyperframes inspectがパスする(エラー0) - サブコンポジションを含むプロジェクト:
npx hyperframes snapshot --at <midpoints>で各フレームを目視確認 -
npx hyperframes previewでレビュー(ユーザーは Studio のタイムラインで何でも編集可能) -
npx hyperframes renderはユーザーの承認後にのみ実行