HyperFrames コア
HyperFrames は HTML からビデオをレンダリングします。合成(composition)は、DOM が data-* 属性でタイミングを宣言し、アニメーションランタイムがシーク可能で、メディア再生がフレームワークによって管理される HTML ファイルです。
このスキルは 技術契約 — HyperFrames プロジェクトを1つ構築する方法を定義します。以下の本文はビルドガイドです。トピックごとの詳細は 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 <midpoints>で各フレームを目視確認 -
npx hyperframes previewでレビュー(ユーザーは Studio のタイムラインで任意に編集可能) -
npx hyperframes renderはユーザーの承認後にのみ実行