HyperFrames コア
HyperFrames は HTML からビデオをレンダリングします。コンポジションとは、DOM が data-* 属性でタイミングを宣言し、アニメーションランタイムがシーク可能で、メディア再生がフレームワークによって所有される HTML ファイルです。
このスキルは技術的な契約書 — 1 つの hyperframes プロジェクトを構築する方法です。以下の本文はビルドガイドです。トピックごとの詳細は 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 を参照してください。
ルートにはサイズ指定が必要 (静かなレイアウトバグ)
スタンドアロンルートには明示的なサイズ指定されたボックス (ピクセル単位の 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を実行する