HyperFrames Core
HyperFrames は HTML から動画をレンダリングします。コンポジションとは、data-* 属性でタイミングを宣言し、アニメーションランタイムがシーク可能で、メディア再生がフレームワークによって管理される HTML ファイルです。
このスキルは技術的な契約です — 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/review-loop.md | ライブボード上で計画→スケッチ→ビルドのレビューパスを実行する。すべてのストーリーボード計画ワークフローで共有される |
references/production-loop.md | 承認された計画を納品動画に変換する。段階の依存関係(オーディオ、フレーム、アセンブリ、トランジション、キャプション、検証、納品)により、自由形式のビルドが直接続く |
references/brief-contract.md | ブリーフの基本ルール — モードの導出(協調的/自律的)、共有フィールドレジストリ、質問の不変条件(質問自体は /hyperframes → 意図レイヤーにあります) |
references/brief-format.md | BRIEF.md を作成する — ワークフローのセットアップが作成し、その後のすべてのステップが読み取る確認済みの意図文書 |
references/script-format.md | オプションの SCRIPT.md ロック済みナレーションを作成する |
references/subagent-dispatch.md | サブエージェントディスパッチ動詞(並列ファンアウト/バックグラウンド/待機)を自分のハーネスにマッピングする |
references/frame-worker-core.md | 共有フレームワーカーの役割契約 — 各ナラティブワークフローのパケットビルダーは、そのワークフローの sub-agents/frame-worker.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 に縮小し、コンテンツが左上隅に積み重なります。これを自動化されたゲートだけでキャッチしようとしないでください。スナップショットを検査してください。スケルトン → 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 の注意点(最初のビルドで確実に失敗します)
lint がキャッチする 2 つのルールですが、事後的にしかキャッチしません。初回から正しく記述してください:
- ルートコンポジション要素は
data-start="0"を保持する必要があります(data-composition-id/data-width/data-heightと一緒に)。省略すると、lintはroot_composition_missing_data_startで失敗します。 - CSS の初期
transformと 同じプロパティに対する GSAP トゥイーンを決して組み合わせないでください。CSS の値とトゥイーンの開始が競合し、lintはgsap_css_transform_conflictで拒否します。代わりに、CSS のtransform: translateX(-40px)ではなく、トゥイーン内でgsap.fromTo(el, { x: -40 }, { x: 0 })を使用して初期状態を設定してください。
譲れないルール(自動化ゲートが見逃す可能性のある静的なバグ)
ここに記載。完全な根拠はリンクされたリファレンスにあります。以下に違反しないでください:
- レンダリング時のクロック / 未シードの
Math.random/ ネットワーク / 入力状態は禁止。repeat: -1は使用不可(有限のカウントを使用)。→determinism-rules.md - ビジュアルプロパティの許可リストのみをアニメーション化する。
displayや生のvisibilityをトゥイーンしない。GSAPautoAlphaとゼロ期間タイムライン境界セットは、可視性例外の唯一のものであり、それらは非クリップ要素またはクリップ内のラッパーにのみ適用。フレームワークだけが.clipの可視性を制御します。ページ読み込み時に後方シーンのクリップに対して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を実行