HyperFrames Core

HyperFrames Core は何をしますか？

HyperFrames は HTML からビデオをレンダリングします。コンポジションは、DOM が data-* 属性でタイミングを宣言し、アニメーションランタイムがシーク可能であり、メディア再生がフレームワークによって管理される HTML ファイルです。

このスキルは 技術契約 です — 1 つの 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/creator-editing-recipes.md	正しいカット/トリム/並べ替え/再タイミング/フリーズ/カメラ/マスク/クロスフェード/オーディオ編集のレシピとその制限をコピーする。
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	ライブボード上で plan → sketch → build のレビューパスを実行する。すべてのストーリーボード計画ワークフローで共有されます。
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 in 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 で拒否します。CSS の transform: translateX(-40px) の代わりに、gsap.fromTo(el, { x: -40 }, { x: 0 }) を使用してトゥイーン内で初期状態を設定してください。

交渉不可のルール（自動化ゲートが見逃す可能性のあるサイレントバグ）

ここに表示されています。完全な根拠はリンク先のリファレンスにあります。違反しないでください:

• レンダリング時間クロック / 未シードの Math.random / ネットワーク / 入力状態は不可。repeat: -1 は不可（有限カウントを使用）。 → determinism-rules.md
• ビジュアルプロパティの許可リストのみアニメーションさせる。display や生の visibility をトゥイーンしないでください。GSAP autoAlpha とゼロ期間のタイムラインバウンダリセットのみが可視性の例外であり、クリップ要素ではない要素またはクリップ内のラッパーでのみ使用できます。フレームワークのみが .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 --background を実行する（ユーザーは Studio のタイムラインで何でも編集でき、サーバーは呼び出しコマンドの後も存続します）
• ユーザーが承認した後にのみ npx hyperframes render を実行する