HyperFrames Core
HyperFrames は HTML からビデオをレンダリングします。合成（composition）とは、data-* 属性でタイミングを宣言する DOM を持ち、アニメーションランタイムがシーク可能で、メディア再生をフレームワークが所有する HTML ファイルです。
このスキルは技術契約です — HyperFrames プロジェクトを 1 つ構築する方法を示します。以下の本文は構築ガイドです。トピックごとの詳細は references/（次にインデックスを参照）にあり、オンデマンドでお読みください。その他の関心事は、兄弟ドメインスキル（hyperframes-animation、hyperframes-creative、media-use、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/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 つの一時停止タイムライン
各合成は、ページ読み込み時に同期的に構築された、window.__timelines["<id>"]（キー = ルート data-composition-id）にちょうど 1 つの gsap.timeline({ paused: true }) を登録します。レンダリング期間 = ルート 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でそれを拒否します。CSStransform: 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を実行する