fullscreen-chat-contracts

name	fullscreen-chat-contracts
description	フルスクリーンチャットの実行時契約とデバッグ手法。Content/YTDLiveChat/ソース解決/スイッチ挙動/iframe 隠蔽方式/blur・background スタイルを変更するとき、またはフルスクリーン/ネイティブチャットの表示崩れ・スロットリング問題を調査するときに使う。live/archive/no-chat の境界、iframe の DOM 移動、CSS の隠蔽方式、スタイル適用先に関わるコードを触るときは必ず参照すること。

Fullscreen Chat 契約

live / archive / no-chat 境界の破壊を防ぎ、過去の回帰バグを再発させないためのガイド。実ブラウザでの確認は ylc-agent-browser を前提にする。

コア契約

1. live: current video の native live_chat iframe が存在する場合はその iframe を borrow する。native iframe が取れない場合のみ managed iframe live_chat?v=<videoId> に fallback する
2. archive: native live_chat_replay iframe のみ borrow する。動画遷移後に stale iframe を再利用しない
3. no-chat / replay-unavailable: switch を表示しない。overlay / extension iframe を出さない
4. 判定責務: canToggle（スイッチ有効化）と sourceReady（attach 可否）は分離する。archive で sourceReady だけを switch 有効条件にしない（deadlock 回避）

YouTube フルスクリーン時の DOM 移動

YouTube はフルスクリーン進入時に #chat-container を #secondary-inner から #panels-full-bleed-container に移動する。この挙動はコードからは読み取れず、ylc-agent-browser / agent-browser で実際に確認する必要がある。

落とし穴: #secondary にだけ CSS を適用しても、フルスクリーン中の #chat-container には効かない。#panels-full-bleed-container にも同等の処理が必要。

iframe 隠蔽方式

Chrome は表示面積ゼロまたは display: none 配下の iframe のタイマーを強くスロットルする。チャット iframe がスロットルされるとメッセージ更新が止まるため、隠蔽方式の選択が重要。

方式	使える場面	理由
display: none	iframe を含まない要素のみ	スロットルされるが影響なし
visibility: hidden + position: fixed + width: 400px	iframe を含む要素	描画面積を維持しスロットルを回避
width: 0 + overflow: hidden	使わない	過去の回帰原因。スロットルされる

iframe を含む祖先要素を隠すときは visibility: hidden + position: fixed + top: -200vh で画面外に配置し、pointer-events: none + z-index: -9999 で干渉を防ぐ。

スタイル契約（blur / background）

1. blur: iframe host ではなく iframe document の body に適用する。host 側に filter をかけると iframe 全体がぼけて文字が読めなくなる
2. background: --yt-live-chat-background-color は transparent を維持する。暗色化は内部変数のみで行う
3. iframe サーフェス透過: entrypoints/content/features/YTDLiveChatIframe/styles/iframe.css で html/body と主要 chat コンテナ背景を透過させる

デバッグ: 状態採取チェックリスト

不具合を再現したら、以下の状態を採取して壊れている境界を特定する:

項目	確認方法	壊れている境界
fullscreen 状態	document.fullscreenElement	DOM 移動（上記セクション参照）
switch ボタン	存在有無・aria-pressed 値	toggle/overlay gating
native iframe	#chatframe の href・playable 状態	source resolver
extension iframe	data-ylc-chat・data-ylc-owned・src	mode 判定・borrow/新規作成

スロットリング問題の詳細な診断手順は references/throttling-diagnostics.md を参照。

ガードレール

• デバッグ中に大規模リファクタを混ぜない。
• permissions 変更は明示依頼がある場合のみ。