HyperFrames Core
HyperFrames は HTML から動画をレンダリングします。コンポジションは、data-* 属性でタイミングを宣言する DOM を持ち、アニメーションランタイムはシーク可能で、メディア再生はフレームワークが所有する HTML ファイルです。
このスキルは技術契約です。その他の関心事は、以下の兄弟スキルにあります。
hyperframes-animation— アトミックなモーションルール + シーンブループリント + ランタイムごとのアダプター (GSAP, Lottie, Three, Anime.js, CSS, WAAPI, TypeGPU)hyperframes-creative— パレット、タイポグラフィ、ナレーション、ビート計画、オーディオリアクティブhyperframes-media— TTS、Whisper 文字起こし、背景除去、キャプションhyperframes-registry— ブロックとコンポーネントのインストール (hyperframes add)hyperframes-cli— 開発ループコマンド (lint / validate / preview / render)
Tailwind v4 プロジェクト (hyperframes init --tailwind) については、references/tailwind.md を参照してください。ブラウザランタイム契約は Studio の Tailwind v3 セットアップとは異なります。
ルーティング
| 目的 | 参照先 |
|---|---|
| 最小限のレンダリング可能なコンポジションを見る | references/minimal-composition.md |
| モノリシック単一ファイルとモジュラーサブコンポジションアーキテクチャの選択 | references/composition-patterns.md |
モジュラーな index.html の構造化(オーケストレーター + スロット + ルートオーディオ) | references/composition-patterns.md |
| サブコンポジションアーキタイプの選択(コンテンツ / ドライバーのみ / マルチシーンマージ / オーディオリアクティブ) | references/composition-patterns.md |
data-* 属性の確認(ルート、クリップ、サブコンポジションホスト、レガシーエイリアス) | references/data-attributes.md |
class="clip" の正しい使い方 | references/data-attributes.md |
data-track-index の選択; 同一トラックの重なり; track-index と CSS z-index の比較 | references/tracks-and-clips.md |
クリップを別のクリップに対して相対的にタイミング設定 (data-start="intro + 2"、クロスフェード重なり、チェーン) | references/tracks-and-clips.md |
サブコンポジションの配線(ホスト属性、<template> ラッパー、インスタンスごとの変数) | references/sub-compositions.md |
サブコンポジション内でのアニメーション (gsap.fromTo と gsap.from の違い、シークバック動作) | references/sub-compositions.md |
変数の宣言(型、追加オプション、デフォルト、CI での --strict-variables) | references/variables-and-media.md |
<video> / <audio> の配置、音量設定、data-media-start によるトリミング | references/variables-and-media.md |
シーク可能なタイムラインの構築(一時停止、同期構築、gsap.set の後続シーントラップ) | references/determinism-rules.md |
非決定論的状態の回避(クロック、Math.random、repeat: -1、有限リピート式) | references/determinism-rules.md |
アニメーション可能 / 不可能なもの(視覚プロパティ許可リスト; display / visibility は不可) | references/determinism-rules.md |
テキストのフィッティングとオーバーフローの防止 (fitTextFontSize シグネチャ、<br> ルール、レイアウト契約) | references/determinism-rules.md |
| 共有背景を用いたフルフレームモーションの作成 | references/full-screen-motion.md |
Tailwind v4 プロジェクトでの作業 (init --tailwind) | references/tailwind.md |
アニメーションランタイムの詳細 (GSAP API、Lottie、Three.js など) については、hyperframes-animation → adapters/<runtime>.md を参照してください。
コンポジション構造
2 つのルート形式があります。これらは互換性がありません。
- スタンドアロン (最上位の
index.html) — ルート<div data-composition-id="…">は直接<body>内に置かれます。<template>ラッパーは不要です。 スタンドアロンルートを<template>でラップすると、すべてのコンテンツがブラウザから隠蔽され、レンダリングが壊れます。 - サブコンポジション (
data-composition-srcで読み込まれるファイル) — ルート<div data-composition-id="…">は<template>でラップする必要があります。ラッパーがないと、ランタイムはそれを展開してマウントできません。
⚠ サブコンポジション転送ルール:ランタイムは
<template>の内容のみをライブ DOM に複製します。テンプレート外のすべて —<head>や<head>内の<style>/<script>/<link>を含む — は破棄されます。<style>および<script>ブロックは<head>ではなく、<template>内に配置してください。⚠ ホスト ID ルール:ホストファイル内で、スロットの
data-composition-idは、内部テンプレートのdata-composition-idおよびwindow.__timelines["<id>"]キーと完全に一致する必要があります。-mount/-slot/-hostのようなサフィックスを追加しないでください。
ファイル構造、ホスト配線、落とし穴の例、およびプリレンダリング検証チェックリストについては、references/sub-compositions.md を参照してください。
ルートはサイズ指定が必要(静的なレイアウトバグ)
スタンドアロンルートは明示的にサイズ指定されたボックスを確立する必要があり、ルートと height: 100% 要素の間のすべての祖先は解決された高さを持っている必要があります。ルートまたは中間ラッパーに高さがない場合、flex / height:100% のコンテンツコンテナは約 0 に縮小し、コンテンツは左上隅に積み重なります(多くの場合、最初のグリフが x=0 でクリップされます)。lint、validate、inspect はこれを検出しません — inspect は収縮したルートに対して作成者の data-width / data-height を代用し、「0 個のレイアウト問題」と報告します。
<body style="margin: 0">
<div
id="root"
data-composition-id="main"
data-width="1920"
data-height="1080"
data-duration="5"
style="position: relative; width: 1920px; height: 1080px; overflow: hidden"
>
<!-- 堅牢に中央揃え:position:absolute + inset:0 でサイズ指定ルートを埋めます。中間ラッパーがあっても機能します。あるいは flex コンテナを使用する場合は、その親チェーンがサイズ指定されている場合のみ。 -->
<section
class="clip"
data-start="0"
data-duration="5"
data-track-index="1"
style="position: absolute; inset: 0; display: grid; place-items: center; padding: 120px 160px; box-sizing: border-box"
>
<h1>タイトル</h1>
</section>
</div>
</body>
センタリングコンテナに padding(80px 以上)を保持してください。これは、大きなテキストがフレーム端に触れるのを防ぐタイトルセーフマージンです。references/minimal-composition.md を参照してください。
タイムライン契約(GSAP デフォルト)
すべてのコンポジションは、正確に 1 つの GSAP タイムラインを登録します。
gsap.timeline({ paused: true })で作成 — プレーヤーが再生を所有します。window.__timelines["<composition-id>"]に登録。キーはルートのdata-composition-idと完全に一致する必要があります。ドット構文 (window.__timelines.<id> = tl) は、ID が有効な識別子である場合に同等です。ID に-が含まれる場合はブラケットを使用してください。- タイムラインをページロード中に同期的に構築 —
async、setTimeout、Promise、またはイベントハンドラ内では構築しないでください。レンダラーはページロード完了後にサンプリングします。遅延されたタイムライン構築はサンプルを逃します。 - レンダリング期間はルートの
data-durationから取得され、GSAP タイムライン長からは取得されません。期間を設定するために空のトゥイーンでタイムラインを埋めないでください。 - サブコンポジションの場合、サブタイムラインをホストに手動でネスト (
master.add(sub)) しないでください。フレームワークがそれらを独立して駆動します。
非 GSAP ランタイム(Lottie / Three / WAAPI / CSS / Anime.js / TypeGPU)の場合、同等の契約は hyperframes-animation/adapters/<runtime>.md にあります。ランタイム横断的なアニメーションランタイム契約については、references/determinism-rules.md を参照してください。
不可避のルール
これらはレンダラーを壊すか — または lint / validate / inspect で検出されない静かな視覚的バグを引き起こします (ルール 3, 7-8)。(同期タイムライン構築については、上記のタイムライン契約でカバーされています。)
- 視覚を駆動する
Math.random()/Date.now()/performance.now()は禁止 — シード付き PRNG を使用してください。 repeat: -1は禁止。repeat: Math.max(0, Math.floor(duration / cycleDuration) - 1)を使用 —floor、ceilは不可 (ceilはdata-durationを超え、gsap_repeat_ceil_overshootlint に引っかかります。max(0, …)は負の repeat (= 無限) を避けます)。<video>/<audio>はホストルート (index.html) の直接の子でなければなりません — サブコンポジションの<template>内やラッパー<div>内には絶対に配置しないでください。そうしないとデコードされず、空白/黒でレンダリングされます(静かなバグ)。フレームワークが再生を所有します:video.play()/audio.play()/currentTime = …は禁止。サブコンポジションはホスト要素を駆動できないため(セレクターまたはquerySelector)、ホストメディアはメインタイムラインからグローバル時間でアニメーションしてください。references/variables-and-media.mdを参照。- 後続シーンのクリップ要素に対する
gsap.set()は禁止(それらはまだ DOM にありません)。クリップのdata-start以降でtl.set(selector, vars, time)を使用してください。 display/visibilityのアニメーションは禁止。opacity/ 変形をアニメーションしてください。クリップのライフサイクルが表示/非表示を処理します。- 本文テキストに
<br>は禁止。テキストはmax-widthで折り返してください。 - 変形される要素はブロックレベルかつサイズ指定されている必要があります。
transform/scaleX/scaleYはインライン<span>では何も行わず、自動幅 (0px) の要素を拡大縮小しても何も表示されません → 見えないバー/塗りつぶし。display: block/inline-block/ flex-item を指定し、かつ実際のwidth/height(例:サイズ指定された親内でwidth: 100%) を与えてください。 - 絶対配置された装飾要素(バッジ、ピル、タグ)で、パルスまたはオーバーシュートするもの(
yoyoスケール、back.out)は、そのピークサイズでクリアランスが必要で、overflow: hiddenの端をまたいではいけません — そうしないと隣接要素と重なるかクリップされます。静止時ではなく、最大フレーム用に配置してください。
既存のコンポジションの編集
- 編集前に実際のファイルを読んでください。
- 無関係なタイミング、トラック、ID、変数、メディアパスは保持してください。
- 既存のコンポジション ID とタイムラインレジストリキーに一致させてください。
- クリップを追加するときは、重複しない
data-track-indexを選択するか、周囲のタイミングを意図的に調整してください。 - サブコンポジションを追加するときは、ホストを配線する前に内部の
data-composition-idを確認してください。
検証
コマンドの詳細については hyperframes-cli を使用してください。
-
npx hyperframes lintがパスする(0 エラー) -
npx hyperframes validateがパスする(0 コンソールエラー) -
npx hyperframes inspectがパスする、またはオーバーフローが意図的にマークされている - サブコンポジションを含むプロジェクト:
npx hyperframes snapshot --at <midpoints>で各フレームを目視確認