HyperFrames コア
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 | モノリシックとモジュール式の選択、モジュール式 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 つの一時停止タイムライン
各コンポジションは、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を実行する