HyperFrames Core
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。
ルートはサイズを指定する必要があります(サイレントレイアウトバグ)
スタンドアロンルートには明示的なサイズ指定のボックス(px 単位の width/height)が必要であり、height:100% の要素までのすべての祖先が解決された高さを持つ必要があります — そうしないと、flex/100% の子要素は約 0 に縮小し、コンテンツが左上隅に詰め込まれます。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はユーザーが承認した後にのみ実行