hyperframes

HyperFrames

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

Open Design 統合 (このサーフェスにとって中核)

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

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

ほとんどの OD リクエスト (「テスト動画」、「5 秒の製品リビール」、「デモクリップ」) では、 コンポジション HTML をゼロから書かないでください。HyperFrames の 組み込みスキャフォールドを使い、プロンプトが実際に変更する部分だけを編集します。 「ゼロから作成する」パスは数分のモデル出力とサイレントな チャットツール時間を消費しますが、スキャフォールドパスは数秒で済みます。

# 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). This runs in your shell — pure file copy,
#    no Chrome, no network beyond the npx cache.
npx hyperframes init "$COMP" --example blank --skip-skills --non-interactive

# 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 `npx 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 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=$(node "$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=$(node "$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 をスキップしてください。 以下の HARD-GATE セクション (「Approach」の下) では、コンポジションを書く前に DESIGN.md / visual-style.md を読むか、 停止して 3 つのムードに関する質問をするよう指示しています。このゲートは スタンドアロンの HF プロジェクト向けです。OD プロジェクトにはすでに独自の デザインシステムレイヤーがあります — ユーザーはプロジェクト作成時に ビジュアルの方向性を選んでいます。OD のテストレンダリングでは、デフォルトを次にしてください: ダークキャンバス (#0b0b0f)、ウォームアクセント 1 つ (#ffb76b)、クールアクセント 1 つ (#7da4ff)、 抑制されたモーション。ユーザーのプロンプトが被写体すら選べないほど曖昧な場合 (ごくまれ) にのみ、スタイルに関する入力を求めてください。

スキャフォールドをスキップしてゼロから書くべき場合: ユーザーが、空白のテンプレートでは明らかに 対応できないもの (例: 複数コンポジションのタイムライン、音声リアクティブなオーバーレイ、すでに生成済みの TTS トラックに同期したキャプション) を明示的に求めた場合のみです。それ以外のすべてでは、 init + edit がデフォルトのパスです。

自分のシェルから今でも実行できる、より軽量な HF サブコマンド (Chrome を起動する必要がないもの):

• npx hyperframes lint "$COMP" — ディスパッチ前にコンポジションを検証
• npx hyperframes transcribe <audio> — キャプションを生成
• npx hyperframes tts <text> — ナレーションを生成

デーモンディスパッチは render/inspect/preview (Chrome に依存するものすべて) のために 取っておいてください。

してはいけないこと: od media generate --model hyperframes-html を呼び出す — このディスパッチャパスは意図的に 400 (AGENT_RENDERED) を返します。HyperFrames は npx 経由でユーザー自身が直接レンダリングします。

してはいけないこと: hyperframes.json / meta.json / index.html を プロジェクトルートに置く — OD のファイル一覧は再帰的にスキャンするため、ユーザーは チャットに無関係な 3 つのファイルが現れるのを見ることになります。

render 以外の CLI オプション (lint、preview、transcribe、tts、inspect、 benchmark) については、タスクがそれを必要とする場合 (例: コンポジションから参照する前に TTS 音声をキャッシュに生成する場合)、シェルツールから直接呼び出してください。

Approach

HTML を書く前に、高いレベルで考えてください:

1. What — 視聴者に何を体験させるべきか? 物語の弧、重要な瞬間、感情のビートを特定します。
2. Structure — コンポジションはいくつか、どれがサブコンポジションでどれがインラインか、どのトラックが何を担うか (動画、音声、オーバーレイ、キャプション)。
3. Timing — どのクリップが尺を決めるか、トランジションはどこに配置されるか、ペースはどうか。
4. Layout — まず最終状態を構築します。以下の「Layout Before Animation」を参照してください。
5. Animate — 次に以下のルールを使ってモーションを加えます。

小さな編集 (色を直す、タイミングを調整する、要素を 1 つ追加する) の場合は、直接ルールに進んでください。

ビジュアルアイデンティティゲート

コンポジションの HTML を書く前に、必ずビジュアルアイデンティティを定義しておく必要があります。デフォルトまたは汎用的な色でコンポジションを書いてはいけません。

この順序で確認してください:

1. プロジェクトに DESIGN.md が存在するか? → それを読んでください。その正確な色、フォント、モーションルール、および「やってはいけないこと」の制約を使用してください。
2. visual-style.md が存在するか? → それを読んでください。その style_prompt_full と構造化フィールドを適用してください。(注: visual-style.md はプロジェクト固有のファイルです。visual-styles.md は 8 つの名前付きプリセットを含むスタイルライブラリであり、別のファイルです。)
3. ユーザーがスタイルを指定したか (例: 「Swiss Pulse」、「dark and techy」、「luxury brand」)? → 8 つの名前付きプリセットについては visual-styles.md を読んでください。最小限の DESIGN.md を次の内容で生成してください: ## Style Prompt (1 段落)、## Colors (役割付きの 3〜5 個の hex 値)、## 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 にスケール、opacity 0) に配置し、着地すると思う位置へトゥイーンすると、最終レイアウトを推測していることになります。重なりは、動画がレンダリングされるまで見えません。先に終了状態を構築することで、モーションを追加する前にレイアウトの問題を確認して修正できます。

プロセス

1. 各シーンのヒーローフレームを特定する — 最も多くの要素が同時に見える瞬間です。これがあなたが構築するレイアウトです。
2. そのフレームの静的 CSS を書く。 .scene-content コンテナは width: 100%; height: 100%; padding: Npx; と display: flex; flex-direction: column; gap: Npx; box-sizing: border-box を使ってシーン全体を埋めなければなりません (MUST)。コンテンツを内側に押し込むには padding を使ってください — コンテンツコンテナに 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 スタックのデザイン (カードスタック、奥行きレイヤー) は意図的なものです。レイアウトのステップは 意図しない 重なりを捕まえることに関するものです — 2 つの見出しが互いの上に着地する、統計がラベルを覆う、コンテンツがフレームからはみ出すなど。

データ属性

すべてのクリップ

属性	必須	値
id	はい	一意の識別子
data-start	はい	秒数またはクリップ ID 参照（"el-1"、"intro + 2"）
data-duration	img/div/コンポジションでは必須	秒数。video/audio はデフォルトでメディアの長さになります。
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> を使用しません — data-composition-id の div を <body> に直接配置します。スタンドアロンファイルで <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に従ってください。

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

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

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

• まずコンポジション全体を読んでください。既存のフォント、色、アニメーションパターンに合わせます
• 要求された箇所だけを変更してください
• 無関係なクリップのタイミングは維持してください

出力チェックリスト

• npx hyperframes lint と npx hyperframes validate の両方がパスする
• npx hyperframes inspect がパスする、または報告されたすべてのオーバーフローが意図的にマークされている
• コントラストの警告に対処している(以下の品質チェックを参照)
• レイアウトの問題に対処している(以下の品質チェックを参照)
• アニメーションの振り付けを検証している(以下の品質チェックを参照)

品質チェック

ビジュアルインスペクト

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

npx hyperframes inspect
npx hyperframes 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 skills/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.2 秒未満)、paced-slow(2 秒超)

JSON を読んでください。サマリーをスキャンして予期しないものを探します。すべてのフラグを確認し、修正するか正当化します。タイムラインが意図した振り付けのリズムを示していることを検証します。修正後に再実行します。

小さな編集(色の修正、1 つの再生時間の調整)ではスキップしてください。新しいコンポジションや重要なアニメーションの変更では実行してください。

---

リファレンス（必要に応じて読み込み）

• 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/）にあります — スキルファイルではなく、パッケージのソースを読み込んでください。

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