HyperFrames コア
HyperFrames は HTML からビデオをレンダリングします。コンポジションは、data-* 属性でタイミングを宣言する DOM を持ち、アニメーションランタイムがシーク可能で、メディア再生がフレームワークによって所有される 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 に collapse し、コンテンツが左上隅に寄ってしまいます。lint/validate/inspect はこれを 検出しません。スケルトン → references/minimal-composition.md。
1つの一時停止タイムライン
各コンポジションは、ページロード時に 同期的に 構築された、window.__timelines["<id>"](キー = ルート data-composition-id)に 正確に1つ の gsap.timeline({ paused: true }) を登録します。レンダリング期間 = ルート 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はユーザーが承認した後にのみ実行する