topcheer/ggcode

HyperFrames コア

HyperFrames は HTML からビデオをレンダリングします。合成とは、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/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	計画 → スケッチ → 構築のレビューパスをライブボード上で実行する — すべてのストーリーボード計画ワークフローで共有される
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 を 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/。

譲れないルール (自動化ゲートが見逃す可能性のあるサイレントバグ)

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

• レンダリング時間のクロック / シードなしの 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 (ユーザーは Studio のタイムラインで何でも編集できます)
• ユーザーが承認した後にのみ npx hyperframes render を実行