HyperFrames コア
HyperFrames は HTML からビデオをレンダリングします。コンポジションは HTML ファイルであり、その DOM が data-* 属性でタイミングを宣言し、アニメーションランタイムがシーク可能で、メディア再生がフレームワークによって管理されるものです。
このスキルは 技術契約 です — 1つの 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 を処理し、クリップを別のクリップに対して相対的にタイミング設定する |
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/brief-contract.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つの一時停止タイムライン
各コンポジションは ちょうど1つ の gsap.timeline({ paused: true }) を window.__timelines["<id>"] (キー = ルート data-composition-id)に登録する。これはページロード時に 同期的に 構築される。レンダリング期間 = ルート 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-hiddenは、プレビュー と レンダリングの両方でその要素を非表示にし、その時間ウィンドウを上書きします。これは非破壊的/元に戻すことができ、Studioのタイムラインの目のアイコンで切り替えられます。 - サブコンポジションを追加する場合:ホストを配線する前に、内部の
data-composition-idを確認してください。
バリデーション
コマンドの詳細については hyperframes-cli を使用してください
-
npx hyperframes checkが成功する(lint、ランタイム、レイアウト、モーション、コントラストにわたって0件の結果) - サブコンポジションがあるプロジェクト:
npx hyperframes snapshot --at <midpoints>を実行し、各フレームを目視確認する -
npx hyperframes previewでレビューする(ユーザーはStudioのタイムラインで任意のものを編集できる) - ユーザーの承認後、
npx hyperframes renderを実行する