hyperframes-core

プラグインのインストール： このスキルが HyperFrames プラグイン内にある場合、セットアップまたは鮮度確認コマンドを実行する前に、プラグインの実行ルールに従ってください。スタンドアロンでインストールした場合は、以下の更新手順を使用してください。

HyperFrames Core

エージェントが陥りやすい問題（最初にお読みください）：

• flex／inset で中央に配置してください。GSAP の x／y を適用するノードに CSS の transform: translate(-50%,-50%) を使用しないでください。Lint：gsap_css_transform_conflict。fromTo または xPercent／yPercent を使用してください。
• シーン終了時に tl.set(..., {visibility:"hidden"}) を追加しないでください。ランタイムが時間指定クリップをすでに非表示にします。内側のノードに不透明度のフェードを適用する（または .clip に opacity を適用する）だけで十分です。キャプションの強制終了には別のルールがあります。
• window.__timelines["id"] は、ルートの data-composition-id と一致している必要があります。
• render の実行後、サマリーの2行目を確認してください。beginframe と screenshot の違い、GPU モード、ステージの所要時間が表示されます。Linux で screenshot と software gpu の組み合わせは、時間のかかる経路です。

HyperFrames は HTML から動画をレンダリングします。コンポジションは、DOM で data-* 属性を使ってタイミングを宣言し、アニメーションランタイムがシーク可能で、メディア再生をフレームワークが管理する HTML ファイルです。

このスキルは、1つの HyperFrames プロジェクトを構築するための技術的な契約です。以下はビルドガイドです。トピックごとの詳細は references/ にあります（次のインデックスを参照）。必要に応じてお読みください。プロセス文書（brief、storyboard、review、production、dispatch、frame-worker）は /hyperframes → references/ にあります。その他の内容は、関連するドメインスキル（hyperframes-animation、hyperframes-creative、media-use、hyperframes-cli、hyperframes-registry）に記載されています。各スキルの対象範囲は /hyperframes の機能マップで確認できます。

参考資料

ファイル	内容
references/minimal-composition.md	描画可能な最小のコンポジションの骨格から始める
references/composition-patterns.md	モノリシック形式とモジュラー形式を選ぶ。モジュラー形式の index.html を構成する。サブコンポジションの型を選ぶ
references/data-attributes.md	data-*（ルート／クリップ／サブコンポジションのホスト／旧形式のエイリアス）を調べる。class="clip" を使用する
references/tracks-and-clips.md	data-track-index が制御する内容（および制御しない内容）、z-index、別のクリップを基準にしたクリップのタイミングを理解する。npx hyperframes timeline ですべてのトラックとクリップを一覧表示する
references/creator-editing-recipes.md	カット／トリム／並べ替え／タイミング変更／フリーズ／カメラ／マスク／クロスフェード／オーディオ編集の、正確なレシピと制限を確認する
references/sub-compositions.md	サブコンポジション（ホスト属性、<template>、インスタンスごとの変数）を接続し、その内部でアニメーションを設定する
references/variables-and-media.md	変数を宣言する。<video>／<audio> を配置し、音量とトリムを設定する
references/determinism-rules.md	シーク可能なタイムラインを作成する。決定性に関する禁止事項、レイアウト／テキストの収まりを確認する
references/full-screen-motion.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> で囲みません。スタンドアロンのルートを囲むと、すべてのコンテンツが非表示になり、lint により拒否されます（standalone_composition_wrapped_in_template、エラー）。
• サブコンポジション（data-composition-src 経由で読み込み）：ルートを <template> で囲みます。これが記述すべき形式です。ローダーは通常の完全なドキュメントも受け付け、その場合は <body> にフォールバックしますが、サンプルとツールが想定しているのはテンプレート形式です。

⚠ 転送ルール：テンプレート形式のサブコンポジションでは、アセンブラーはファイル自体の <head> にある <style>／<script> を削除します（packages/core/src/compiler/compositionAssembly.ts の hasTemplate ゲート）。そのため、<style>／<script> はテンプレートの内側に記述してください。<link> はどちらの場合も引き上げられます。 ⚠ ホスト ID の規約：ホストスロット、内部テンプレート、window.__timelines["<id>"] キーには、同じ ID を指定してください。異なるローカル ID もサポートされています（アセンブラーはファイル内の最初のルートにフォールバックします）が、不一致は警告なしで処理されるため、理由がない限り ID を一致させてください。

ファイル形式、ホストの接続方法、事前レンダリングのチェックリスト → references/sub-compositions.md。

ルート要素にはサイズ指定が必要です（レイアウトが正常に動作しない場合があります）

スタンドアロンのルート要素には width／height: 100% を指定します。キャンバスサイズは data-width／data-height で指定します。ランタイムはそのピクセル値をコンポジションのルート要素に設定します。#root に 1920px／1080px をハードコードしないでください。ひな形 → references/minimal-composition.md。

一時停止したタイムラインを1つだけ登録します

各コンポジションは、window.__timelines["<id>"] に gsap.timeline({ paused: true }) をちょうど1つ登録します（キーはルート要素の data-composition-id）。非同期コールバック（document.fonts.ready）内で構築してもかまいません。重要なのは、構築が完了した後にのみ登録することです。レンダリングの長さはルート要素の data-duration で決まり、タイムラインの長さではありません。タイムラインがその長さを超えて再生される場合は途中で切られ、早く終了する場合は最後のフレームで止まります。ルート要素の data-duration を省略すると、長さはタイムライン、メディアの再生区間、またはアダプターから推定されます。window.__timelines = window.__timelines || {} は不要です。ランタイムはインラインスクリプトの実行前にレジストリを作成するため、lint もこれを要求しなくなりました。サブタイムラインを手動でホストにネストしないでください。ランタイムが、登録済みの子タイムラインを自動的にネストします。詳細な仕様（GSAP 以外のランタイムを含む）→ references/determinism-rules.md ＋ hyperframes-animation/adapters/。

初回の lint でつまずきやすい点（最初のビルドで必ず失敗する原因）

lint で検出されますが、問題が起きてからしかわからないルールです。最初から正しく記述してください。

• 同じプロパティに対して、CSS の初期 transform と GSAP のトゥイーンを併用しないでください。CSS の値とトゥイーンの開始値が競合し、lint は gsap_css_transform_conflict を出して拒否します。CSS の transform: translateX(-40px) ではなく、gsap.fromTo(el, { x: -40 }, { x: 0 }) のようにトゥイーン内で初期状態を設定してください。
• <video>／<audio> に crossorigin を指定しないでください。キャンバス／WebGL／WebAudio からの読み取りの場合も含め、lint は必ず media_crossorigin_breaks_preview（エラー）を出して拒否します。抑制する方法はありません。
• <video data-start> の祖先に data-start を指定しないでください。lint は video_nested_in_timed_element（エラー）を出して拒否します。タイミングを設定するのはラッパーか動画のどちらか一方だけにしてください。
• すべての <audio> に id が必要です。lint は media_missing_id を出して拒否します。また、id のない <audio> はミキサーに検出されないため、レンダリングは無音になります。
• .clip に autoAlpha または visibility を指定してトゥイーンしないでください。lint は gsap_animates_clip_element を出して拒否します。代わりに子要素をアニメーションさせてください。
• 名前付き CSS font-family には、同梱されたローカルファイルを参照する、同じファイル内の @font-face が必要です。指定しないと lint は font_family_without_font_face を出します。
• サブコンポジションの #root には、1920px／1080px をハードコードするのではなく、width／height: 100%（または inset: 0）を指定します。キャンバスサイズは data-width／data-height で指定します。

lint エラーが1つでもあると、レイアウトとコントラストの監査も無効になります。その場合、check は 0 sample(s) と 0/0 text checks を報告します。問題がないファイルのように見えますが、実際には何も検査されていません。数値を信頼する前に、lint エラーを解消してください。

譲れないルール（自動チェックで見逃される可能性がある、潜在的なバグ）

ここに記載しています。詳しい理由はリンク先のリファレンスを参照してください。違反しないでください。

• レンダリング時の時計、シードなしのMath.random、ネットワーク、入力状態は使用しないでください。repeat: -1は、有限のルートdata-durationがある場合に限り使用できます（書き出し時にはその長さでクリップされます。それ以外の場合は有限回数を指定してください）。→ determinism-rules.md
• .clip要素のdisplay、visibility、autoAlphaをトゥイーンしないでください。クリップの表示状態はフレームワークが管理しており、lintはこれを拒否します（gsap_animates_clip_element）。代わりに子要素をアニメーションさせてください。→ determinism-rules.md
• 本文に<br>を使わないでください。変換する要素はブロックレベルにしてサイズを指定し、パルスする絶対配置の装飾要素にはピーク時の余白を確保してください。→ determinism-rules.md
• <video>／<audio>はドキュメント全体をフラットに検索して検出されるため、フレームワークはあらゆるネストの深さ（サブコンポジションの<template>内やラッパー内を含む）にあるこれらの要素をシークしてデコードします。厳守すべき制限が1つあります。<video data-start>が、同じくdata-startを持つ別の通常の要素内にある場合、lintはエラーを報告します。これは実際に問題を引き起こし（ソースフレームが誤り、続いてクリップがスロットの途中で消える）、ラッパーか動画のどちらか一方にタイミングを設定し、両方には設定しないでください。サブコンポジションのホストは例外です。サブコンポジション内のメディアは正しくレンダリングされます。もう1つの注意点は配置ではなくタイムラインです。サブコンポジションのタイムラインからホストのルート要素をアニメーションさせることはできません。→ variables-and-media.md
• 組み立て後のページ全体で、すべてのidを一意にしてください（サブコンポジションのIDにはコンポジションIDを接頭辞として付け、#<id>-heroのようにします）。こうすることで、独自の#id CSSやgetElementByIdの呼び出しが正しく解決されます。フレームの挿入はIDに依存しなくなりました。コンパイラは、すべてのvideo[src]／audio[src]／img[src]にドキュメント内で一意なdata-hf-render-idを付与します。src属性の代わりに<source>子要素を使うメディアにはこの属性が付与されないため、その場合も一意なIDが重要です。→ composition-patterns.md
• 通常のレンダリングでは、コンポジションのルートに画面全体を覆う塗りつぶしを設定しても問題ありません。レイヤー合成の経路（HDRコンテンツ、またはシェーダートランジションを使用するコンポジション）の場合に限り、その塗りつぶしは破棄されます。この経路では、下のレイヤーが透けて見えるよう、エンジンがすべてのコンポジションルートを透明にするためです。コンポジションでシェーダートランジションまたはHDRメディアを使う場合は、画面全体を覆う子要素（position:absolute; inset:0）に塗りつぶしを設定してください。→ composition-patterns.md

既存のコンポジションを編集する

• まずファイルを読んでください。無関係なタイミング、トラック、ID、変数、メディアパスは維持してください。
• プロジェクトのタイムライン上にある要素（トラック、クリップ、開始位置、終了位置、再生内容）を確認するには、index.htmlや各サブコンポジションのファイルをすべて読むのではなく、npx hyperframes timeline [--json]を実行してください。
• 既存のコンポジションIDとタイムラインキーに合わせてください。
• クリップを追加する場合は、周囲のクリップを考慮してdata-start／data-durationを意図的に設定してください。data-track-indexはStudio上の表示レーンであり、タイミングを制約するものではないため、空いている必要はありません。
• クリップの終了位置がルートのdata-durationを超える場合、そのクリップは途中で切られます。同じ編集で、ルートのdata-durationをクリップの終了位置まで延長してください（lintはclip_ends_past_root_durationを警告します）。
• 別のタイミング指定要素の内側にネストされたクリップのdata-startは、その要素からではなくコンポジションを基準にします。また、その要素が表示されている間だけ表示されます。timelineはそのクリップを親の下に一覧表示し、表示時間帯が重ならない場合はnever visibleと警告します（lintはnested_clip_never_visibleを報告します）。
• 任意のコンポジション要素に設定されたdata-hiddenは、その時間帯にかかわらず、プレビューとレンダリングの両方で要素を非表示にします。これは非破壊的で元に戻せる設定で、Studioのタイムラインにある目のアイコンで切り替えられます。
• サブコンポジションを追加する場合は、ホストに接続する前に、内部のdata-composition-idを確認してください。

検証

コマンドの詳細は hyperframes-cli を使用してください。

• npx hyperframes check が成功すること（lint、runtime、layout、motion、contrast 全体で検出結果が 0 件）
• サブコンポジションがあるプロジェクト：npx hyperframes snapshot --at <midpoints> を実行し、各フレームを目視確認します
• レビューには npx hyperframes preview --background を使用します（ユーザーは Studio のタイムラインで何でも編集でき、起動コマンドの実行後もサーバーは動作し続けます）
• ユーザーの承認後にのみ npx hyperframes render を実行します