hyperframes-core

HyperFrames Core

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

このスキルは、hyperframes プロジェクトを構築するための技術的な契約です。以下はビルドガイドで、トピックごとの詳細は references/ にあります（次の一覧を参照）。必要に応じて読み進めてください。その他の内容は、関連するドメインスキルで扱います。具体的には、hyperframes-animation、hyperframes-creative、hyperframes-media、hyperframes-cli、hyperframes-registry です。各スキルの対象範囲は /hyperframes の機能マップに記載されています。

References

ファイル	次の目的で読みます…
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。

ルートにはサイズ指定が必要です（見つけにくいレイアウトバグ）

スタンドアロンのルートには、明示的にサイズ指定されたボックス（px 単位の width／height）が必要です。また、height:100% の要素に至るまでの各祖先要素で、高さが確定している必要があります。そうでない場合、flex／100% の子要素が約 0 に縮み、コンテンツが左上に積み重なります。lint／validate／inspect では検出できません。ひな形 → references/minimal-composition.md。

一時停止されたタイムライン

各コンポジションは、window.__timelines["<id>"]（キーはルートの data-composition-id）に、gsap.timeline({ paused: true })を正確に1つ登録します。ページ読み込み時に同期的に構築してください。レンダリング時間はルートの 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>-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 を実行する