🔒 spec(svg-composition-animation): close SPEC — all phases complete

SPEC: 20260413-0806_svg-composition-animation
All tasks checked off. Moved to closed.

Author: ShotaroKataoka

.kiro/specs/closed/20260413_sktok/20260413-0806_svg-composition-animation/design.md

@@ -0,0 +1,333 @@
+# Design: SVG Composition Animation
+
+## Architecture
+
+```
+run_python(measure_slides=[N])
+  ↓
+PPTX build → LibreOffice SVG export (existing _run_measure)
+  ↓
+split_slide_components() ← NEW
+  ├─ <font>/<glyph> 除去
+  ├─ base64 PNG → base64 WebP 変換
+  ├─ コンポーネント分割 + メタデータ抽出
+  └─ 背景抽出
+  ↓
+構造化JSON → S3保存 → presigned URL
+  ↓
+WebUI polling → JSON fetch → SVG組み立て → アニメーション
+```
+
+## Engine: `sdpm.preview.compose`
+
+~~New module: `skill/sdpm/preview/compose.py`~~
+
+**修正**: composeはMCP Remote専用ロジック（消費者はWebUIのみ、CLI/MCP Localでは不使用）。
+principlesの判断フロー「Infrastructure-dependent → MCP Remote独自実装」に該当。
+Engineに置くとCLI/MCP Localに不要な依存（Pillow for WebP変換）が入る。
+
+→ `mcp-server/tools/compose.py` に配置。
+
+```python
+def extract_optimized_defs(svg_path: Path) -> dict:
+    """Extract and optimize shared defs from LibreOffice SVG.
+
+    Processing:
+      1. Strip <font>/<glyph> tags (keep font-family on text elements)
+      2. Convert inline base64 PNG → base64 WebP
+
+    Returns:
+        {
+            "version": 1,        # Schema version for forward compatibility
+            "defs": str,          # Optimized: fonts stripped, images as WebP base64
+        }
+    """
+
+def split_slide_components(svg_path: Path, slide_num: int) -> dict:
+    """Split LibreOffice SVG into per-component data (defs excluded).
+
+    Processing:
+      1. Extract background from master page
+      2. Split Page group into component fragments with metadata
+      3. Convert inline base64 PNG → base64 WebP in component SVG fragments
+
+    Returns:
+        {
+            "version": 1,        # Schema version for forward compatibility
+            "viewBox": str,
+            "bgFill": str,        # Background fill color
+            "bgSvg": str | None,  # Background + BackgroundObjects SVG fragment
+            "components": [
+                {
+                    "class": str,
+                    "bbox": {"x": float, "y": float, "w": float, "h": float} | None,
+                    "text": str,  # Preview text (first 80 chars)
+                    "svg": str,   # SVG fragment (images converted to WebP base64)
+                }
+            ]
+        }
+    """
+```
+
+### SVG最適化パイプライン
+
+```
+Original defs (~1MB):
+  <font>/<glyph>: 515KB (49%) → 除去
+  base64 PNG:     508KB (49%) → WebP base64 36KB
+  clipPath等:      24KB  (2%) → そのまま
+                              ─────────
+Optimized defs:                ~60KB
+
+フォント戦略:
+  - <font>/<glyph> タグ除去（SVGフォント埋め込み）
+  - テキスト要素の font-family="Amazon Ember Display" は維持
+  - ブラウザにフォントがあれば正しく描画、なければフォールバック
+  - 将来: @font-face + woff2 配信で拡張可能（font-family残存が基盤）
+
+画像戦略:
+  - data:image/png;base64,... → decode → WebP変換 → data:image/webp;base64,...
+  - インライン維持（外部リクエスト不要、CORS不要）
+  - 実測: PNG 351KB → WebP 12KB (3%)
+```
+
+### 既存コードとの共有
+
+- `sdpm.preview.measure`: SVG_NS, スライドグループ構造, BoundingBox取得 → 共通定数・ユーティリティ化
+- `split_svg_per_slide()` (measure.py内): スライド単位分割ロジック → compose でも同じ構造を走査
+- Phase 1実装時に共通化の範囲を判断する（過剰な事前リファクタリングは避ける）
+
+## MCP Server: compose処理 + S3保存
+
+`server.py` の `_run_measure()` 後に compose を同期実行。SVGは `_run_measure` で既に生成済み（`tmpdir/measure.svg`）なので追加のLibreOffice呼び出し不要。
+
+MCPレスポンスにはcomposeデータを含めない（エージェントが使う情報ではない）。
+S3に保存し、WebUIがポーリングで取得する。既存のWebPプレビューと同じパターン。
+
+```python
+# In run_python post-processing, after _run_measure
+# Note: save=False (dry-run for agent layout check) skips compose entirely.
+# tmpdir safety: compose runs within the same `with tempfile.TemporaryDirectory()` block
+# as _run_measure, so tmpdir/measure.svg is guaranteed to exist at this point.
+if measure_slides and save:
+    from sdpm.preview.compose import extract_optimized_defs, split_slide_components
+    try:
+        defs_data = extract_optimized_defs(svg_path)
+        _storage.put_json(f"decks/{deck_id}/compose/defs.json", defs_data)
+    except Exception:
+        logger.error("compose defs failed", exc_info=True)
+    for slide_num in measure_slides:
+        try:
+            data = split_slide_components(svg_path, slide_num)
+            key = f"decks/{deck_id}/compose/slide_{slide_num}.json"
+            _storage.put_json(key, data)
+        except Exception:
+            logger.error("compose failed for slide %d", slide_num, exc_info=True)
+```
+
+### データ伝搬経路
+
+```
+Engine compose → S3保存
+  ├─ decks/{deck_id}/compose/defs.json          ← デッキレベル共通defs (1回)
+  └─ decks/{deck_id}/compose/slide_{N}.json     ← スライド個別 (defs除外)
+  ↓
+deck API (GET /decks/{id})
+  ├─ DeckDetail.defsUrl → defs.json presigned URL
+  └─ SlidePreview.composeUrl → slide_{N}.json presigned URL
+  ↓
+WebUI ポーリング (useWorkspace)
+  ├─ defsUrl変更検知 → defs再fetch
+  └─ composeUrl変更検知 → AnimatedSlidePreview
+```
+
+### deck API レスポンス拡張
+
+`DeckDetail` に `defsUrl` フィールドを追加:
+```typescript
+export interface DeckDetail {
+  // ... existing fields ...
+  defsUrl: string | null      // 共通defs presigned URL (新規)
+}
+```
+
+`SlidePreview` に `composeUrl` フィールドを追加:
+```typescript
+export interface SlidePreview {
+  slideId: string
+  previewUrl: string | null   // WebP (既存)
+  composeUrl: string | null   // 構造化JSON presigned URL (新規、defs除外)
+  updatedAt: string
+  slideJson?: string
+}
+```
+
+presigned URLはポーリング時に毎回生成されるため、有効期限切れの問題は発生しない。
+`useWorkspace` の presigned URL安定化ロジックを composeUrl および defsUrl にも適用する。
+
+## WebUI: AnimatedSlidePreview
+
+New component: `web-ui/src/components/deck/AnimatedSlidePreview.tsx`
+
+### 責務
+1. 構造化JSONからSVG DOMを組み立て（defs + bgSvg + components[].svg）
+2. メタデータ（bbox, class）でアニメーション制御
+3. エージェント種別の自動割当（フロント側責務）
+
+### Props
+```typescript
+interface AnimatedSlidePreviewProps {
+  defsUrl: string;             // S3 presigned URL to shared defs JSON
+  composeUrl: string;          // S3 presigned URL to slide component JSON (defs excluded)
+  slideId?: string;            // For scroll targeting
+  onComplete?: () => void;     // Called when animation finishes
+  fallback?: React.ReactNode;  // Fallback when compose version mismatches or fetch fails
+}
+```
+
+### SVG組み立て
+```
+fetch(defsUrl) → defs JSON (cached per polling cycle)
+fetch(composeUrl) → slide JSON
+  ↓
+if (data.version !== COMPOSE_VERSION) → fallback to WebP thumbnail
+  ↓
+<svg viewBox={data.viewBox}>
+  {data.bgSvg ? <g innerHTML={sanitize(bgSvg)}/> : <rect fill={bgFill}/>}
+  <g innerHTML={sanitize(defsData.defs)}/>
+  {data.components.map(comp =>
+    <g innerHTML={sanitize(comp.svg)} class="component" opacity={0}/>
+  )}
+</svg>
+```
+
+### 差分アニメーション（バックエンド diff）
+
+変更があったコンポーネントのみアニメーションする。diff計算はバックエンド（server.py）で行い、
+各コンポーネントに `changed: boolean` フラグを付与する。フロントはフラグを参照するだけ。
+
+**UX根拠**:
+- Motion Design Restraint: "One primary animation per interaction" — 変更していない箇所のアニメーションはノイズ
+- Purposeful Animation: アニメーションの目的は「AIが今ここを変更した」というフィードバック
+- Cognitive Load: ユーザーは「何が変わったのか」を即座に把握したい
+
+**なぜバックエンドdiffか**:
+- compose JSONは毎回新しいepochでS3に保存される → フロントはURL変更だけでは内容変更を判別できない
+- フロントでのdiffは initialLoad判定・URL安定化・defsUrl変更時の再描画制御が複雑化した
+- バックエンドはS3に前回データがあり、PPTXソース（slides_json）も保持している → 正確なdiffが可能
+
+**2段階diff**:
+
+1. **スライドレベル突合（sourceHash）**: スライドJSONのmd5ハッシュでスライドの同一性を判定。
+   番号ではなく内容ベースなので、挿入・削除・並べ替えに対応。
+   ```python
+   sourceHash = md5(json.dumps(slide_json, sort_keys=True))
+   ```
+   - 前回の全スライドを `{sourceHash: components_map}` のdictに格納
+   - 新スライドのsourceHashで前回データをO(1)で引く
+   - sourceHash不一致 or 前回なし → 全コンポーネント `changed: true`
+
+2. **コンポーネントレベルdiff（class+bbox キー + text+class fingerprint）**:
+   sourceHashが一致したスライド同士で、コンポーネント単位の変更を検出。
+   - キー: `class+bbox` （Phase 0検証済み、false_neg=0）
+   - fingerprint: `class|text` で内容変更を検出
+   - キー不一致 or fingerprint不一致 → `changed: true`
+
+**compose JSONスキーマ拡張**:
+```json
+{
+  "version": 1,
+  "sourceHash": "abc123...",
+  "viewBox": "...",
+  "components": [
+    {
+      "class": "TitleText",
+      "bbox": {...},
+      "text": "...",
+      "svg": "...",
+      "changed": true
+    }
+  ]
+}
+```
+
+**フロント側**: `comp.changed` を参照するだけ。diff検出・initialLoad判定・前回データ保持が不要。
+```typescript
+const animTargets = new Set<number>()
+data.components.forEach((comp, i) => {
+  if (comp.changed) animTargets.add(i)
+})
+```
+
+**composeクリーンナップ**: 新しいcompose JSONアップロード後、古いepochファイルを削除（WebPと同じパターン）。
+
+### アニメーションフェーズ（PoCから移植）
+
+アニメーション対象コンポーネントのみ実行。不変コンポーネントは即座にopacity=1で表示。
+
+```
+Per changed/new component (stagger 420ms):
+  Phase 1 (+0ms):    カーソル飛来 → bbox左上に着地
+  Phase 2 (+250ms):  ワイヤーフレーム展開（左上→右下ドラッグ）+ カーソル右下移動
+  Phase 3 (+450ms):  マテリアライズ + タイプライター + カーソルフェードアウト
+
+Unchanged components:
+  即座に opacity=1 で表示（アニメーションなし）
+
+Deleted components:
+  フェードアウト (200ms, ease-out)
+```
+
+### タイプライター実装
+- `textLength`/`lengthAdjust` を一時除去（文字引き伸ばし防止）
+- 文字数適応速度: 800ms/コンポーネント目標、15-50ms/文字でクランプ
+- 全文字完了後に `textLength`/`lengthAdjust` 復元
+- `useRef` でSVG DOM直接操作（React re-render回避）
+
+### エージェント割当（フロント側）
+
+割当は決定的でなければならない（ランダム禁止）。リプレイ・差分更新で色が変わると不自然。
+
+```typescript
+const AGENTS = [
+  { name: 'Layout',    color: '#3b6cf0' },  // TitleText, SubtitleText
+  { name: 'Content',   color: '#2ba882' },  // text.length > 20
+  { name: 'Visual',    color: '#8b5cf6' },  // Graphic, image
+  { name: 'Data',      color: '#d97706' },  // ConnectorShape, line
+  { name: 'Decorator', color: '#e04070' },  // その他（フォールバック、ランダムにしない）
+];
+```
+
+### SlideCarousel 統合
+```
+SlideCarousel (slidesタブ)
+  ├─ composeUrl あり → AnimatedSlidePreview 表示 (defsUrl + composeUrl)
+  │   └─ onComplete → アニメーション完了（SVGのまま表示継続）
+  └─ composeUrl なし → 従来のWebPサムネイル表示（SlideThumbnail）
+```
+
+**自動スクロール**: composeUrl変更検知時、`changed: true` コンポーネントを持つ最初のスライドにスクロール。
+AnimatedSlidePreviewが `onAnimate` コールバックで通知 → SlideCarouselが最初の通知元にスクロール。
+
+他コンポーネント（DeckCard, SearchResultsGrid, MentionPopup等）は変更なし。
+従来の `previewUrl`（WebP presigned URL）をそのまま使用。
+
+### アクセシビリティ
+- `prefers-reduced-motion`: アニメーション無効時は即座に全表示
+
+### タイプライターcleanup
+- スライド切替・アンマウント時に `useEffect` cleanup で `textLength`/`lengthAdjust` を復元
+- 復元漏れ防止のため、除去した属性値を `useRef` で保持
+
+### セキュリティ
+- composeデータ（構造化JSON）は自前Engine生成のみ。外部ユーザー入力がSVGフラグメントに混入する経路は現時点でない
+- S3 presigned URL経由で取得するため、認証済みユーザーのみアクセス可能
+- `dangerouslySetInnerHTML` 使用箇所はcomposeデータに限定
+- 防御的措置: `innerHTML` 代入前に DOMPurify でサニタイズ（将来の入力経路追加に備えた多層防御）
+
+## 削除対象
+
+なし（WebPパイプラインは維持）
+
+---
+**Created**: 2026-04-13