hyperframes

HyperFrames

動画の信頼できる情報源は HTML です。コンポジションは、タイミングを指定する data-* 属性、アニメーション用の GSAP タイムライン、外観を指定する CSS を含む HTML ファイルです。このフレームワークは、クリップの表示、メディア再生、タイムラインの同期を処理します。

OpenDesign との統合（この用途で重要）

このスキルが OpenDesign 内で実行される場合（つまり、$OD_PROJECT_DIR が設定されている場合）、出力フローは固定されています。プロジェクトルートに置くのは、レンダリング済みの .mp4 のみです。コンポジションのソースファイル（hyperframes.json、meta.json、index.html、アセット）は、ユーザーの FileViewer やチャットの「生成ファイル」チップを散らかさないよう、隠しキャッシュディレクトリ内に配置します。

OD 内でのレンダリングワークフロー — 高速パス：

ほとんどの OD リクエスト（「テスト動画」、「5s の商品紹介」、「デモクリップ」など）では、コンポジション HTML を一から作成しないでください。Open Design の決定論的なひな形を使い、プロンプトで変更が指定された部分だけを編集します。「一から作成する」方法ではモデルの出力に数分かかり、チャットツールの実行時間も予測できません。ひな形を使う方法なら数秒で済みます。

# 1. Pick a hidden cache slot. Dotfile prefix → OD's project file
#    listing skips it, so the source files never clutter the chat.
COMP_REL=".hyperframes-cache/$(date +%s)-$(openssl rand -hex 2)"
COMP="$OD_PROJECT_DIR/$COMP_REL"

# 2. Get an immediately-renderable scaffold (hyperframes.json,
#    meta.json, index.html with GSAP CDN + window.__timelines.main
#    already registered). Open Design writes these files itself; it does
#    not run `hyperframes init`, consult an npx cache, or install global skills.
"$OD_NODE_BIN" "$OD_BIN" media scaffold \
  --project "$OD_PROJECT_ID" \
  --composition-dir "$COMP_REL"

# 3. Edit ONLY $COMP/index.html — change `data-duration` on the root
#    if you need a non-default length, swap the placeholder palette
#    in <style>, add 1–3 clip <div>s for text/imagery, and append the
#    matching GSAP tweens inside the existing
#    `window.__timelines["main"] = gsap.timeline({paused:true})` block.
#    Keep edits minimal; the scaffold is already valid HF.

# 4. Dispatch render through the OD daemon. Do NOT run HyperFrames
#    `render` from this shell — the daemon runs it for you in an
#    unsandboxed process. (Many agent CLIs, Claude Code in particular,
#    wrap Bash in macOS sandbox-exec under which puppeteer's Chrome
#    subprocess hangs partway through frame capture. The daemon process
#    is unsandboxed, so renders complete reliably.)
#
#    The dispatcher returns within ~1s with a {taskId}; drive the
#    render to completion by looping `"$OD_NODE_BIN" "$OD_BIN" media wait <taskId>` calls.
#    Each call long-polls up to 25s (well under your shell tool's
#    default 30s cap) and exits 0/2/5 to signal done/running/failed.
out=$("$OD_NODE_BIN" "$OD_BIN" media generate \
  --project "$OD_PROJECT_ID" \
  --surface video \
  --model hyperframes-html \
  --output "<descriptive-name>.mp4" \
  --composition-dir "$COMP_REL")
ec=$?
task_id=$(printf '%s\n' "$out" | tail -1 | jq -r '.taskId // empty')
since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // 0')
while [ "$ec" -eq 2 ] && [ -n "$task_id" ]; do
  out=$("$OD_NODE_BIN" "$OD_BIN" media wait "$task_id" --since "$since")
  ec=$?
  since=$(printf '%s\n' "$out" | tail -1 | jq -r '.nextSince // '"$since")
done
[ "$ec" -ne 0 ] && { echo "$out" >&2; exit "$ec"; }

各 generate 呼び出しと各 wait 呼び出しの実行時間は最大約 25 秒なので、エージェントのシェルツールの既定の約 30 秒の上限に達することはありません。HF の進捗行（Capturing frame N/M）は、ループ中ずっと stderr にリアルタイムで出力されます。レンダリングが完了すると、最後の stdout 行は {"file": { "name": "<output>", "size": …, "kind": "video", … }} になります。生成されたファイルがユーザーにわかるよう、返信には file.name を記載してください。

OD 内では Visual Identity Gate をスキップしてください。 以下の「Approach」セクションにある HARD-GATE では、コンポジションを作成する前に DESIGN.md / visual-style.md を読むか、作業を中止して雰囲気に関する質問を 3 つするよう指示しています。このゲートは単独の HF プロジェクト向けです。OD プロジェクトには独自のデザインシステムレイヤーがすでにあります。ユーザーはプロジェクト作成時にビジュアルの方向性を選択しています。OD のテストレンダリングでは、既定で暗いキャンバス（#0b0b0f）、温色のアクセントカラー 1 色（#ffb76b）、寒色のアクセントカラー 1 色（#7da4ff）、控えめなモーションを使用します。スタイルに関する入力を求めるのは、ユーザーのプロンプトが題材を選ぶことさえ難しいほど曖昧な場合に限ります（非常にまれです）。

ひな形を使わず、一から作成するのは、空のテンプレートでは明らかに対応できない内容をユーザーが明示的に求めた場合のみです（例：複数のコンポジションを含むタイムライン、音声に反応するオーバーレイ、すでに生成済みの TTS トラックに同期した字幕）。それ以外はすべて、初期化して編集する方法を既定とします。

自分のシェルから引き続き実行できる、軽量な HF サブコマンドは次のとおりです（Chrome の起動は不要です）。

• "$OD_NODE_BIN" "$OD_HYPERFRAMES_BIN" lint "$COMP" — ディスパッチ前にコンポジションを検証します
• "$OD_NODE_BIN" "$OD_HYPERFRAMES_BIN" transcribe <audio> — 字幕を生成します
• "$OD_NODE_BIN" "$OD_HYPERFRAMES_BIN" tts <text> — ナレーションを生成します

デーモンへのディスパッチは render／inspect／preview（Chrome が必要なもの）に限定します。.hyperframes-cache/ 内にコンポジションを作成したら、"$OD_NODE_BIN" "$OD_BIN" media generate --surface video --model hyperframes-html --composition-dir <rel> を呼び出してレンダリングします。デーモンは、Chrome が必要な HyperFrames のレンダリングをシェルのサンドボックス外で実行し、進捗をストリーミングして返します。HyperFrames の render は自分で実行しないでください。

プロジェクトルートに hyperframes.json／meta.json／index.html を置かないでください。OD のファイル一覧は再帰的にスキャンするため、チャットに無関係なファイルが 3 つ表示されてしまいます。

render 以外の CLI オプション（lint、preview、transcribe、tts、inspect、benchmark）は、タスクに応じてシェルツールから直接呼び出してください（例：コンポジションから参照する TTS 音声をキャッシュ内に生成する場合）。

アプローチ

HTML を書き始める前に、全体像を考えます。

1. 内容 — 視聴者にどのような体験をしてもらうか。物語の流れ、重要な場面、感情の動きを見定めます。
2. 構成 — コンポジションはいくつにするか、どれをサブコンポジションにし、どれをインラインにするか。各トラックに何を配置するか（動画、音声、オーバーレイ、キャプション）を決めます。
3. タイミング — どのクリップが尺を決めるか、トランジションをどこに配置するか、テンポをどうするかを考えます。
4. レイアウト — まず完成状態を作ります。下記の「アニメーションの前にレイアウト」を参照してください。
5. アニメーション — その後、以下のルールに従って動きを加えます。

小さな編集（色の修正、タイミングの調整、要素の追加など）では、すぐにルールに進んでください。

ビジュアルアイデンティティの必須確認

コンポジションの HTML を書く前に、必ずビジュアルアイデンティティを定義してください。デフォルトや汎用的な色を使ってコンポジションを書いてはいけません。

次の順に確認します。

1. プロジェクトに DESIGN.md があるか？ → 読み込んでください。そこに記載されている正確な色、フォント、モーションのルール、「避けるべきこと」の制約を使用します。
2. visual-style.md があるか？ → 読み込んでください。style_prompt_full と構造化フィールドを適用します。（注：visual-style.md はプロジェクト固有のファイルです。visual-styles.md は 8 つの名前付きプリセットを含むスタイルライブラリで、別のファイルです。）
3. ユーザーがスタイルを指定しているか（例：「Swiss Pulse」、「ダークでテクニカル」、「高級ブランド」）？ → visual-styles.md を読み込み、8 つの名前付きプリセットを確認してください。次の内容を含む最小限の DESIGN.md を生成します：## Style Prompt（1 段落）、## Colors（役割を付けた 3～5 個の 16 進数値）、## Typography（1～2 個のフォントファミリー）、## What NOT to Do（3～5 個のアンチパターン）。
4. いずれにも該当しないか？ → HTML を書く前に、次の 3 つの質問をしてください。
   • どのような雰囲気にしますか？（爆発的／映画的／流動的／テクニカル／カオス／温かみのある）
   • 明るいキャンバスと暗いキャンバスのどちらにしますか？
   • ブランドカラー、フォント、ビジュアルの参考資料に指定はありますか？ その後、回答をもとに最小限の DESIGN.md を生成します。

すべてのコンポジションで、配色とタイポグラフィを DESIGN.md、visual-style.md、またはユーザーの明示的な指示にたどれるようにしてください。#333、#3b82f6、Roboto を使おうとしているなら、この手順を飛ばしています。

モーションのデフォルト、サイズ設定、登場パターン、イージングについては、house-style.md に従ってください。ハウススタイルでは、要素を「どのように」動かすかを定めます。DESIGN.md では、要素を「どのように見せるか」を定めます。

アニメーションの前にレイアウト

すべての要素を、最もよく見える瞬間、つまり完全に表示され、正しい位置にあり、まだ退出していないフレームに配置します。まず静的な HTML+CSS として記述してください。まだ GSAP は使いません。

これが重要な理由： アニメーションの開始状態（画面外、スケール 0、不透明度 0）に要素を配置し、着地させたい位置までトゥイーンさせると、最終的なレイアウトは推測に頼ることになります。動画がレンダリングされるまで、要素の重なりは見えません。先に完成状態を作れば、動きを加える前にレイアウトの問題を確認して修正できます。

手順

1. 各シーンのヒーローフレーム、つまり同時に最も多くの要素が表示される瞬間を特定します。ここで構築するレイアウトを決めます。
2. そのフレームの静的な CSS を記述します。.scene-content コンテナは、width: 100%; height: 100%; padding: Npx; を指定し、display: flex; flex-direction: column; gap: Npx; box-sizing: border-box を使って、シーン全体を必ず埋めるようにします。パディングを使ってコンテンツを内側に寄せます。コンテンツコンテナに position: absolute; top: Npx を使ってはいけません。絶対配置のコンテンツコンテナは、コンテンツが残りの領域より高い場合に、はみ出します。position: absolute は装飾要素にのみ使用します。
3. gsap.from() で登場させます — 画面外／不可視の状態から、CSS で指定した位置へアニメーションさせます。CSS の位置が基準となり、トゥイーンはそこへ至る動きを表します。
4. gsap.to() で退出させます — CSS で指定した位置から、画面外／不可視の状態へアニメーションさせます。

例

/* scene-content fills the scene, padding positions content */
.scene-content {
  display: flex;
  flex-direction: column;
  justify-content: center;
  width: 100%;
  height: 100%;
  padding: 120px 160px;
  gap: 24px;
  box-sizing: border-box;
}
.title {
  font-size: 120px;
}
.subtitle {
  font-size: 42px;
}
/* Container fills any scene size (1920x1080, 1080x1920, etc).
   Padding positions content. Flex + gap handles spacing. */

誤り — 寸法のハードコードと絶対配置：

.scene-content {
  position: absolute;
  top: 200px;
  left: 160px;
  width: 1920px;
  height: 1080px;
  display: flex; /* ... */
}

// Step 3: Animate INTO those positions
tl.from(".title", { y: 60, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
tl.from(".subtitle", { y: 40, opacity: 0, duration: 0.5, ease: "power3.out" }, 0.2);
tl.from(".logo", { scale: 0.8, opacity: 0, duration: 0.4, ease: "power2.out" }, 0.3);

// Step 4: Animate OUT from those positions
tl.to(".title", { y: -40, opacity: 0, duration: 0.4, ease: "power2.in" }, 3);
tl.to(".subtitle", { y: -30, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.1);
tl.to(".logo", { scale: 0.9, opacity: 0, duration: 0.3, ease: "power2.in" }, 3.2);

時間をまたいで要素が同じ空間を共有する場合

要素 A が退場してから要素 B が同じ領域に登場する場合、それぞれのヒーローフレームで正しい CSS の位置を指定する必要があります。タイムラインの順序によって視覚的に同時に表示されることはありませんが、レイアウトの手順を省くと、タイミングの誤りによって意図せず重なるケースを見逃してしまいます。

意図的な重なりとは

レイヤー効果（テキストの背後のグロー、影の要素、背景パターン）や、z 軸を重ねたデザイン（カードのスタック、奥行きのあるレイヤー）は意図的なものです。レイアウトの手順では、意図しない重なり、つまり見出しが重なったり、統計値がラベルを覆ったり、コンテンツがフレームからはみ出したりする状態を検出します。

データ属性

すべてのクリップ

属性	必須	値
id	はい	一意の識別子
data-start	はい	秒数またはクリップ ID の参照（"el-1"、"intro + 2"）
data-duration	img/div/コンポジションでは必須	秒数。動画／音声はメディアの長さがデフォルトです。
data-track-index	はい	整数。同じトラック上のクリップは重ねられません。
data-media-start	いいえ	ソース内のトリム位置（秒）
data-volume	いいえ	0-1（デフォルトは 1）

data-track-index は視覚的なレイヤー順序には影響しません。CSS の z-index を使用してください。

コンポジションクリップ

属性	必須	値
data-composition-id	はい	一意のコンポジション ID
data-start	はい	開始時間（ルートコンポジションでは "0" を指定）
data-duration	はい	GSAP タイムラインの長さより優先されます
data-width / data-height	はい	ピクセル寸法（1920x1080 または 1080x1920）
data-composition-src	いいえ	外部 HTML ファイルへのパス

コンポジションの構造

data-composition-src で読み込むサブコンポジションでは、<template> ラッパーを使用します。単独のコンポジション（メインの index.html）では <template> を使用しません。<body> 内に data-composition-id を持つ div を直接配置します。単独ファイルで <template> を使用すると、ブラウザーからすべてのコンテンツが隠され、レンダリングが壊れます。

サブコンポジションの構造：

<template id="my-comp-template">
  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
    
    <style>
      [data-composition-id="my-comp"] {
        /* scoped styles */
      }
    </style>
    <script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/gsap.min.js"></script>
    <script>
      window.__timelines = window.__timelines || {};
      const tl = gsap.timeline({ paused: true });
      // tweens...
      window.__timelines["my-comp"] = tl;
    </script>
  </div>
</template>

ルートでの読み込み：<div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>

動画と音声

動画には muted playsinline が必要です。音声は常に独立した <audio> 要素にします。

<video
  id="el-v"
  data-start="0"
  data-duration="30"
  data-track-index="0"
  src="video.mp4"
  muted
  playsinline
></video>
<audio
  id="el-a"
  data-start="0"
  data-duration="30"
  data-track-index="2"
  src="video.mp4"
  data-volume="1"
></audio>

タイムラインの規約

• すべてのタイムラインは { paused: true } で開始します。再生はプレーヤーが制御します
• すべてのタイムラインを登録します：window.__timelines["<composition-id>"] = tl
• フレームワークがサブタイムラインを自動的にネストします。手動で追加しないでください
• 長さは GSAP タイムラインの長さではなく、data-duration で決まります
• 長さを設定するために空のトゥイーンを作成しないでください

ルール（必須）

決定論的であること： Math.random()、Date.now()、時間ベースのロジックは使用しないでください。疑似乱数値が必要な場合は、シード付き PRNG（例：mulberry32）を使用してください。

GSAP： アニメーションの対象は視覚的なプロパティ（opacity、x、y、scale、rotation、color、backgroundColor、borderRadius、変換）のみにしてください。visibility、displayをアニメーションしたり、video.play()／audio.play()を呼び出したりしないでください。

アニメーションの競合： 同じ要素の同じプロパティを、複数のタイムラインから同時にアニメーションさせないでください。

repeat: -1は禁止： 無限リピートのタイムラインはキャプチャエンジンを破損させます。コンポジションの長さから正確なリピート回数を計算してください：repeat: Math.ceil(duration / cycleDuration) - 1。

同期的なタイムライン構築： async／await、setTimeout、Promise の内部でタイムラインを構築しないでください。キャプチャエンジンはページ読み込み後に window.__timelines を同期的に読み取ります。フォントはコンパイラーによって埋め込まれるため、すぐに利用できます。フォントの読み込みを待つ必要はありません。

以下の操作は禁止です：

1. window.__timelinesへの登録を忘れる
2. 音声に動画を使う — 動画は常にミュートし、別の<audio>を使用する
3. 時間指定のある div の中に動画を入れる — 時間指定のないラッパーを使用する
4. data-layerを使用する（data-track-indexを使用する）。またはdata-endを使用する（data-durationを使用する）
5. 動画要素の寸法をアニメーションする — ラッパー div をアニメーションする
6. メディアに対して play／pause／seek を呼び出す — 再生はフレームワークが管理します
7. data-composition-idのないトップレベルコンテナを作成する
8. いずれかのタイムラインまたはトゥイーンでrepeat: -1を使用する — 常に有限回のリピートにする
9. タイムラインを非同期に構築する（async、setTimeout、Promiseの内部）
10. 後のシーンのクリップ要素にgsap.set()を使用する — ページ読み込み時には DOM に存在しません。代わりに、クリップのdata-start時刻以降にtl.set(selector, vars, timePosition)をタイムライン内で使用してください。
11. コンテンツテキストに<br>を使用する — 強制改行では、実際に描画されたフォントの幅が考慮されません。自然に折り返すテキストに<br>を追加すると、不要な改行が生じて重なりの原因になります。代わりにmax-widthでテキストを折り返してください。例外：各単語を意図的に1行ずつ表示する短いディスプレイタイトル（例：130px の「THE\nIMMORTAL\nGAME」）。

シーン遷移（必須）

複数シーンから成るすべてのコンポジションは、以下のルールをすべて守る必要があります。1つでも違反すると、コンポジションは破損します。

1. シーン間では必ず遷移を使用してください。 ジャンプカットは禁止です。例外はありません。
2. すべてのシーンで必ずイントロアニメーションを使用してください。 すべての要素はgsap.from()でアニメーションして表示させます。完成状態の要素をそのまま表示してはいけません。シーンに5つの要素がある場合、5つのイントロトゥイーンが必要です。
3. 最後のシーンを除き、アウトロアニメーションは絶対に使用しないでください。 つまり、遷移が始まる前に、不透明度を0にする、画面外へ移動させる、スケールを0にするなど、要素を消すアニメーションを行うgsap.to()は使用禁止です。遷移そのものがアウトロです。遷移が始まる瞬間、退出するシーンのコンテンツは完全に表示された状態でなければなりません。
4. 最後のシーンのみ： 最後のシーンでは、要素をフェードアウトできます（例：黒へのフェード）。gsap.to(..., { opacity: 0 })が許可されるのはこのシーンだけです。

誤り — 遷移前にアウトロアニメーションを行う：

// BANNED — this empties the scene before the transition can use it
tl.to("#s1-title", { opacity: 0, y: -40, duration: 0.4 }, 6.5);
tl.to("#s1-subtitle", { opacity: 0, duration: 0.3 }, 6.7);
// transition fires on empty frame

正しい — イントロのみ。アウトロは遷移で処理する：

// Scene 1 entrance animations
tl.from("#s1-title", { y: 50, opacity: 0, duration: 0.7, ease: "power3.out" }, 0.3);
tl.from("#s1-subtitle", { y: 30, opacity: 0, duration: 0.5, ease: "power2.out" }, 0.6);
// NO exit tweens — transition at 7.2s handles the scene change
// Scene 2 entrance animations
tl.from("#s2-heading", { x: -40, opacity: 0, duration: 0.6, ease: "expo.out" }, 8.0);

アニメーションのガードレール

• 最初のアニメーションは0.1～0.3秒ずらす（t=0にはしない）
• イントロトゥイーンごとにイージングを変える — シーンごとに少なくとも3種類の異なるイージングを使用する
• 1つのシーン内でイントロのパターンを繰り返さない
• 暗い背景で全画面の線形グラデーションを避ける（H.264のバンディングが発生するため、放射状グラデーション、または単色と局所的なグローを使用する）
• レンダリングされる動画では、見出しは60px以上、本文は20px以上、データラベルは16px以上にする
• 数値列にはfont-variant-numeric: tabular-numsを使用する

visual-style.mdまたはアニメーションの指示がない場合は、美的スタイルのデフォルトとしてhouse-style.mdに従ってください。

タイポグラフィとアセット

• フォント： CSS に使用したい font-family を記述するだけで構いません。コンパイラーが対応フォントを自動的に埋め込みます。フォントが対応していない場合は、コンパイラーが警告します。
• 外部メディアには crossorigin="anonymous" を追加してください
• 動的なテキストのオーバーフローには、window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight }) を使用してください
• すべてのファイルは index.html と同じプロジェクトルートに配置します。サブコンポジションでは ../ を使用してください

既存のコンポジションの編集

• 最初にコンポジション全体を読み、既存のフォント、色、アニメーションのパターンに合わせてください
• 依頼された箇所だけを変更してください
• 関係のないクリップのタイミングは維持してください

出力チェックリスト

• "$OD_NODE_BIN" "$OD_HYPERFRAMES_BIN" lint と "$OD_NODE_BIN" "$OD_HYPERFRAMES_BIN" validate がどちらも成功する
• "$OD_NODE_BIN" "$OD_HYPERFRAMES_BIN" inspect が成功する、または報告されたオーバーフローすべてに意図的なものであることを示すマークが付いている
• コントラストに関する警告に対処する（下記の「品質チェック」を参照）
• レイアウトの問題に対処する（下記の「品質チェック」を参照）
• アニメーションの振り付けを確認する（下記の「品質チェック」を参照）

品質チェック

視覚的な検査

hyperframes inspect はヘッドレス Chrome でコンポジションを実行し、タイムライン上をシークして、タイムスタンプ、セレクター、バウンディングボックス、修正のヒントとともに視覚的なレイアウトの問題をマッピングします。lint と validate の後に実行してください。

"$OD_NODE_BIN" "$OD_HYPERFRAMES_BIN" inspect
"$OD_NODE_BIN" "$OD_HYPERFRAMES_BIN" inspect --json

失敗の多くは、吹き出しやカードからテキストがはみ出している、固定サイズのラベルが動的なテキストをクリップしている、またはテキストがキャンバスの外に移動していることを意味します。コンテナーのサイズやパディングを大きくする、フォントサイズや文字間隔を小さくする、テキストがコンテナー内で折り返すように適切な max-width を指定する、または動的なテキストに window.__hyperframes.fitTextFontSize(...) を使用して修正してください。

密度の高い動画では --samples 15 を、特定のヒーローフレームでは --at 1.5,4,7.25 を使用してください。繰り返し発生する静的な問題は、エージェントのコンテキストが埋め尽くされないよう、デフォルトでまとめられます。イントロやアウトロのアニメーションで意図的にオーバーフローさせる場合は、要素または祖先に data-layout-allow-overflow を設定してください。装飾要素を監査対象から除外する場合は、data-layout-ignore を設定してください。

hyperframes layout は、同じチェックを実行するための互換エイリアスです。

コントラスト

hyperframes validate はデフォルトで WCAG コントラスト監査を実行します。5 つのタイムスタンプにシークし、ページのスクリーンショットを撮影し、各テキスト要素の背後の背景ピクセルをサンプリングして、コントラスト比を算出します。失敗すると警告が表示されます。

⚠ WCAG AA contrast warnings (3):
  · .subtitle "secondary text" — 2.67:1 (need 4.5:1, t=5.3s)

警告が表示された場合：

• 暗い背景では、失敗した色を明るくして、コントラスト比を 4.5:1（通常のテキスト）または 3:1（大きなテキスト、24px 以上、または太字で 19px 以上）にしてください
• 明るい背景では、色を暗くしてください
• パレットの系統を維持し、新しい色を作らずに既存の色を調整してください
• 問題がなくなるまで hyperframes validate を再実行してください

素早く反復作業を行い、後で確認する場合は、--no-contrast を使ってスキップしてください。

アニメーションマップ

アニメーションを作成した後、アニメーションマップを実行して振り付けを確認してください。

node design-templates/hyperframes/scripts/animation-map.mjs <composition-dir> \
  --out <composition-dir>/.hyperframes/anim-map

次の内容を含む単一の animation-map.json を出力します。

• トゥイーンごとの概要： "#card1 animates opacity+y over 0.50s. moves 23px up. fades in. ends at (120, 200)"
• ASCII タイムライン： コンポジションの再生時間全体にわたるすべてのトゥイーンのガントチャート
• スタッガーの検出： 実際の間隔を報告します（"3 elements stagger at 120ms"）
• デッドゾーン： アニメーションのない 1 秒超の期間。意図的な停止ですか、それとも開始アニメーションの不足ですか？
• 要素のライフサイクル： 最初と最後のアニメーション時刻、最終的な表示状態
• シーンのスナップショット： 5 つの主要なタイムスタンプにおける要素の表示状態
• フラグ： offscreen、collision、invisible、paced-fast（0.2s 未満）、paced-slow（2s 超）

JSON を読み、概要に予期しない内容がないか確認してください。すべてのフラグを確認し、修正するか、理由を説明してください。タイムラインで意図した振り付けのリズムになっていることを確認してください。修正後は再実行してください。

軽微な編集（色の修正や 1 つの再生時間の調整）ではスキップしてください。新しいコンポジションや大幅なアニメーション変更では実行してください。

---

References（必要に応じて読み込みます）

• references/captions.md — キャプション、字幕、歌詞、音声に同期したカラオケ。トーンに応じたスタイル検出、単語ごとのスタイル設定、テキストのはみ出し防止、キャプションの確実な終了、単語のグループ化を扱います。音声のタイミングに同期するテキストを追加する際に読みます。

• references/tts.md — Kokoro-82M によるテキスト読み上げ。音声の選択、速度の調整、TTS とキャプションのワークフローを扱います。ナレーションやボイスオーバーを生成する際に読みます。

• references/audio-reactive.md — 音声に反応するアニメーション：周波数帯域と振幅を GSAP のプロパティにマッピングします。映像を音楽、音声、サウンドに反応させる際に読みます。

• references/css-patterns.md — CSS と GSAP によるマーカーハイライト：ハイライト、円、バースト、落書き、スケッチアウト。決定論的で、完全にシーク可能です。テキストに視覚的な強調を加える際に読みます。

• references/typography.md — タイポグラフィ：フォントの組み合わせ、OpenType 機能、暗い背景向けの調整、フォント検出スクリプト。必ず読みます — どのコンポジションにもテキストが含まれます。

• references/motion-principles.md — モーションデザインの原則：感情としてのイージング、重みとしてのタイミング、階層としての振り付け、シーンのペース配分、環境的な動き、アンチパターン。GSAP アニメーションを振り付ける際に読みます。

• visual-styles.md — 名前付きのビジュアルスタイル 8 種（Swiss Pulse、Velvet Standard、Deconstructed、Maximalist Type、Data Drift、Soft Signal、Folk Frequency、Shadow Cut）。16 進数のカラーパレット、GSAP のイージングシグネチャ、シェーダーの組み合わせを含みます。ユーザーがスタイルを指定した場合、または DESIGN.md を生成する際に読みます。

• house-style.md — スタイルが指定されていない場合の、デフォルトのモーション、サイズ、カラーパレット。

• patterns.md — PiP、タイトルカード、スライドショーのパターン。

• data-in-motion.md — データ、統計、インフォグラフィックのパターン。

• references/transcript-guide.md — 文字起こしのコマンド、whisper モデル、外部 API、トラブルシューティング。

• references/dynamic-techniques.md — 動的なキャプションアニメーションの手法（カラオケ、clip-path、スラム、散乱、弾性、3D）。

• references/transitions.md — シーンのトランジション：クロスフェード、ワイプ、リビール、シェーダートランジション。エネルギーやムードの選択、CSS と WebGL の使い分けを扱います。複数シーンのコンポジションでは必ず読みます — トランジションがないシーンは、ジャンプカットのように感じられます。

  • transitions/catalog.md — 厳守事項、シーンテンプレート、種類ごとの実装コードへの案内。
  • シェーダートランジションは @hyperframes/shader-transitions（packages/shader-transitions/）にあります — スキルファイルではなく、パッケージのソースを読んでください。

• references/html-in-canvas.md — HTML-in-Canvas（drawElementImage）によって、ライブ DOM を WebGL テクスチャとしてレンダリングします：3D デバイスのモックアップ、シェーダーで変形する UI、リキッドガラス、ポータル。ユーザーから vfx-iphone-device、vfx-liquid-glass、vfx-portal、または「3D／シェーダーにマッピングされた HTML」効果を求められた際に読みます。レンダリング経路で Chrome のフラグは自動的に有効になりますが、アニメーションコンテンツでは毎フレームテクスチャを再キャプチャする必要があります — これが「画面が動かない」出力の最も一般的な原因です。

GSAP のパターンとエフェクトは /gsap スキルにあります。