HyperFrames Core
HyperFramesはHTMLからビデオをレンダリングします。コンポジションは、DOMが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。
ルートはサイズ指定が必要(サイレントレイアウトバグ)
スタンドアロンルートには、明示的な サイズ指定されたボックス(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 <中間点>を実行し、各フレームを目視確認する - レビュー用に
npx hyperframes previewを使用する(ユーザーはStudioのタイムラインで任意のものを編集できる) -
npx hyperframes renderはユーザーが承認した後にのみ実行する