docs/specs/html-preview/iframe-section-alignment.md

# HTML プレビュー・セクション管理システム設計書

## 1. 概要

改善案生成結果の HTML プレビュー機能において、セクションの可視性制御、順序管理、iframe 内表示、位置同期を統合的に管理するシステムの設計仕様。

## 2. システムアーキテクチャ

### 2.1 4層アーキテクチャ構成

```mermaid
graph TB
    A[セクション管理レイヤー<br/>useSectionManager] --> B[HTML生成・表示レイヤー<br/>TabContentRenderer]
    B --> C[位置同期レイヤー<br/>usePreciseSectionAlignment]
    B --> D[スクロール制御レイヤー<br/>handleSectionClick]

    E[Zustand Store] --> A
    F[ContentSection[]] --> A
    G[FV/CN HTML Generation] --> B
    H[iframe Display] --> B
    I[Environment Variables] --> C
```

### 2.2 レイヤー間の責任分離

| レイヤー | 責任 | 主要機能 |
|---------|------|---------|
| **セクション管理** | セクション状態の管理 | 可視性制御、順序管理、永続化 |
| **HTML生成・表示** | UI統合とHTML生成 | FV/CN HTML生成、iframe表示、ダウンロード |
| **位置同期** | iframe内位置同期 | セクション位置測定、カード位置計算 |
| **スクロール制御** | ユーザー操作対応 | セクションクリック、スムーズスクロール |

## 3. セクション管理レイヤー仕様

### 3.1 useSectionManager の機能

#### 3.1.1 型定義
```typescript
interface SectionVisibility {
  [key: string]: {
    visible: boolean;   // セクションの表示/非表示
    order: number;      // セクションの表示順序
  };
}

interface UseSectionManagerReturn {
  sectionVisibility: SectionVisibility;
  handleSectionVisibility: (key: string) => void;
  handleSectionOrder: (key: string, direction: 'asc' | 'desc') => void;
  filterAndSortSections: (sections: ContentSection[]) => ContentSection[];
  getSectionInfoForDropdown: (sections: ContentSection[]) => SectionInfo[];
  resetSectionVisibility: () => void;
  hasChanges: boolean;
}
```

#### 3.1.2 状態管理の仕組み
- **キー形式**: `${section.大区分}-${section.中区分}`
- **初期状態**: 全セクション visible: true, order: インデックス順
- **永続化**: Zustand store でタブ間状態保持
- **変更検知**: 初期状態と現在状態の diff による hasChanges 判定

#### 3.1.3 主要機能
```typescript
// セクション可視性の切り替え
handleSectionVisibility('ヘッダー-メインビジュアル');

// セクション順序の変更
handleSectionOrder('コンテンツ-商品紹介', 'asc');

// 可視セクションのフィルタリング・ソート
const visibleSections = filterAndSortSections(allSections);

// 初期状態にリセット
resetSectionVisibility();
```

## 4. HTML生成・表示レイヤー仕様

### 4.1 TabContentRenderer の責任

#### 4.1.1 統合制御機能
- **セクション管理統合**: useSectionManager の呼び出しと状態管理
- **HTML生成制御**: FV/CN HTML生成の条件判定と実行
- **iframe表示制御**: 生成されたHTMLのiframe表示
- **ダウンロード機能**: 画像・コードダウンロードの実装

#### 4.1.2 生成条件の制御
```typescript
// HTML生成の有効化条件
const htmlGenerationEnabled = React.useMemo(() => {
  const hasMinimalData = hasFvData && hasCnData;

  if (dummyMode) {
    return hasScreenshot && hasMinimalData;
  } else if (generateAllTabs) {
    return hasScreenshot && hasMinimalData;
  } else {
    return hasScreenshot && hasMinimalData;
  }
}, [dummyMode, generateAllTabs, hasScreenshot, hasFvData, hasCnData]);
```

#### 4.1.3 モード別動作
- **ダミーモード**: 事前生成されたダミーHTML/画像を使用
- **全タブ生成モード**: 全タブで一括HTML生成
- **通常モード**: アクティブタブのみHTML生成

## 5. 位置同期レイヤー仕様

### 5.1 usePreciseSectionAlignment の機能

#### 5.1.1 環境制御
```typescript
// 環境変数による機能制御
const isAlignmentFeatureEnabled = process.env.NEXT_PUBLIC_ENABLE_SECTION_ALIGNMENT === 'true';
const alignmentEnabled = isAlignmentFeatureEnabled && isActive && !!tabCnData && tabCnData.length > 0;
```

#### 5.1.2 位置同期アルゴリズム
- **測定**: iframe内セクション要素の位置・サイズ測定
- **計算**: セクションとカードの位置対応計算
- **同期**: transform: translateY による位置調整

#### 5.1.3 観測機能
- **MutationObserver**: iframe内DOM構造変更の監視
- **ResizeObserver**: セクションサイズ変更の監視
- **デバウンス処理**: 150ms のデバウンスで性能最適化

## 6. スクロール制御レイヤー仕様

### 6.1 handleSectionClick の動作

#### 6.1.1 セクション検索アルゴリズム
```typescript
const searchMethods = [
  () => iframeDoc.querySelector(`[data-section-key="${sectionKey}"]`),
  () => iframeDoc.querySelector(`[aria-label="${sectionKey}"]`),
  () => iframeDoc.querySelector(`[aria-label*="${sectionKey}"]`),
  // 複数のフォールバック手法...
];
```

#### 6.1.2 スクロール位置計算
```typescript
// 最終スクロール位置の計算
const iframeRect = iframe.getBoundingClientRect();
const finalScrollTop = window.scrollY + iframeRect.top + sectionOffsetTop - 36; // sticky tab height

window.scrollTo({
  top: Math.max(0, finalScrollTop),
  behavior: 'smooth',
});
```

## 7. データフローと状態管理

### 7.1 データフロー
```
ContentSection[]
  ↓
useSectionManager (状態管理)
  ↓
TabContentRenderer (UI統合)
  ↓
[並行処理]
  ├─ HTML生成 → iframe表示
  ├─ 位置同期 (usePreciseSectionAlignment)
  └─ スクロール制御 (handleSectionClick)
```

### 7.2 状態永続化
- **保存場所**: Zustand store
- **保存単位**: タブ名単位での状態管理
- **保存内容**: sectionVisibility オブジェクト
- **復元タイミング**: タブ切り替え時の自動復元

### 7.3 変更検知システム
```typescript
const checkHasChanges = (current: SectionVisibility, initial: SectionVisibility) => {
  // 可視性変更の検知
  if (current[key].visible !== initial[key].visible) return true;

  // 順序変更の検知
  if (current[key].order !== initial[key].order) return true;

  return false;
};
```

## 8. 環境設定と制御

### 8.1 環境変数による機能制御
- `NEXT_PUBLIC_ENABLE_SECTION_ALIGNMENT`: 位置同期機能の有効/無効
- 各生成モードの制御: dummyMode, generateAllTabs

### 8.2 条件分岐による最適化
- **ローカル環境**: 画像生成をスキップ（RateLimit回避）
- **ダミーモード**: 事前生成データの使用
- **デプロイ環境**: 全機能の有効化

## 9. パフォーマンス仕様

### 9.1 応答性能
- **状態更新**: デバウンス 150ms
- **HTML生成**: 非同期処理による UI ブロック回避
- **位置同期**: リアルタイム更新（有効時のみ）
- **スクロール**: smooth behavior による自然な動作

### 9.2 メモリ効率
- **Observer**: 必要時のみアクティブ化
- **状態管理**: 必要最小限のデータ保持
- **HTML**: ミニファイ化された軽量コンテンツ

## 10. エラーハンドリング

### 10.1 段階的フォールバック
```typescript
// セクション検索の段階的フォールバック
for (let i = 0; i < searchMethods.length; i++) {
  try {
    targetElement = searchMethods[i]();
    if (targetElement) break;
  } catch (error) {
    console.log(`Search method ${i + 1} failed:`, error);
  }
}
```

### 10.2 エラー時の安全な動作
- **セクション未発見**: iframe先頭への安全なスクロール
- **HTML生成失敗**: エラー表示とリトライ機能
- **位置同期失敗**: デフォルト表示への自動フォールバック

## 11. 実装のポイント

### 11.1 責任分離の徹底
- **セクション管理**: 完全に独立したレイヤー
- **HTML生成**: 非同期処理による分離
- **位置同期**: 環境変数による任意機能
- **スクロール制御**: ユーザー操作への専念

### 11.2 拡張性の確保
- **モジュラー設計**: 各レイヤーの独立性
- **設定可能**: 環境変数による柔軟な制御
- **フォールバック**: 段階的な機能劣化

### 11.3 デバッグ支援
- **詳細ログ**: 各段階での状態出力
- **段階的検索**: 複数手法による要素発見
- **状態可視化**: hasChanges による変更状態の明示

## 12. 今後の発展可能性

### 12.1 機能拡張
- **セクション編集**: インライン編集機能
- **プレビュー強化**: リアルタイムプレビュー
- **エクスポート拡張**: 多形式対応

### 12.2 性能改善
- **仮想化**: 大量セクションの効率的表示
- **キャッシュ**: 生成結果のインテリジェントキャッシュ
- **並列化**: 生成処理の更なる並列化