seam-craft

Seam Craft — シーン間トランジションのレンダリング前提条件

これは、PLV のシーン間シームに関するレンダリングの正確性を保つための指針です。選択されるトランジションの種類にかかわらず、どのトランジションでも正しく合成されるための前提条件と、マスタータイムラインの仕組みを説明します。各トランジションのカタログ（クロスフェード、プッシュスライド、ズームスルー、カーブカットなど）はトランジションレジストリにあり、このページでは、それらすべての基盤となる指針を説明します。

この指針が対象とするトランジションはTier-B 対応です。つまり、2 つのシーンのクリップラッパー（#el-<sid>）に対する純粋な transform／opacity／filter であり、overlay DOM の注入やシーンごとの連携はありません。overlay ファミリー（staggered blocks、blinds、light leak、grid dissolve、page burn）とシェーダートランジションは、後続フェーズに延期されています。

ステージの背景に関する前提条件（白フラッシュ対策）

複数のテンプレートでは、2 つのラッパーの opacity の合計が 1 未満になる時間帯が発生します（cut-the-curve の中間時間帯のカット、zoom-through の 0.15 の下限、通常のクロスフェードにおける power-curve の落ち込み）。その時間帯には、ラッパーの背後にあるものが透けて見えます。組み立てられた index.html の #root に不透明な背景がない場合、レンダラーは落ち込み部分をデフォルトの白いページに合成するため、シームのたびに白フラッシュが発生し、暗い映像では特に目立ちます（修正前に Spotify の 2 回の実行で確認済み）。アセンブラーはステージに背景色を塗る必要があります。 #root { background: var(--canvas-deep, var(--canvas, #000)) } — 現在は assemble-index.mjs がこれを出力します。このテンプレートを使うほかのすべてのコンシューマーも、同じ保証を担います。

インジェクターによるトランジションの適用方法

シーン i（from）とシーン i+1（to）の間の break 境界で、インジェクターは次の処理を行います。

1. #el-<from> ラッパーの data-duration を duration_s だけ延長します（最終フレームを保持します — core/src/runtime/init.ts:1393-1410 の external-slot 分岐で確認済み）。
2. #el-<to> ラッパーの data-start を duration_s だけ前倒しします（オーバーラップ時間帯を作成します）。
3. すべてのクリップの data-track-index を 0/1 の ping-pong 方式で再割り当てし、オーバーラップする 2 つのラッパーが同じトラックを共有しないようにします（同一トラック上のオーバーラップは禁止されています — core/src/lint/rules/composition.ts）。上位トラックが前面に合成されます。
4. gsap_template を T = overlap-start の位置で window.__timelines["main"] にスタンプします。

プロトタイプのレンダーで確認済み（2026-05-31）：マスタータイムラインのラッパー tween がシークされ、レンダリングされます（サブコンプ独自の一時停止中のタイムラインとの二重シークはありません — ランタイムがそれぞれを独立して制御します）。延長されたラッパーはシーン i の最終フレームを保持し、トラック番号の高い incoming ラッパーが outgoing ラッパーの上に合成され、ブレンドされます。

テンプレートのプレースホルダー

インジェクターは各 gsap_template 行の次のトークンを置換します。

トークン	意味
__OLD__	"#el-<from>" — outgoing クリップラッパーのセレクター（引用符付き）
__NEW__	"#el-<to>" — incoming クリップラッパーのセレクター（引用符付き）
__T__	オーバーラップ開始時刻（秒、マスタークロック）
__DUR__	この境界の duration_s
__DX__	方向指定タイプの水平方向の移動量：-1920（LEFT）／1920（RIGHT）
__DY__	垂直方向の移動量：-1080（UP）／1080（DOWN）
__ORIGIN_OUT__ / __ORIGIN_IN__	squeeze 用の transformOrigin ペア

マスタータイムライン上の filter／scaleX／transformOrigin は lint に準拠しています（確認済み：core/src/lint/rules/gsap.ts にはプロパティごとの許可リストがなく、チェックの対象範囲は data-composition-id の範囲に限定されています。x/y/scale/rotation/opacity の許可リストは_シーンワーカー_のプロンプトルールにのみ適用され、index.html は対象ではありません）。