Task #860: HWP3/HWP5/HWPX 의 EMF/WMF image 콘텐츠 렌더 정정

mydocs/plans/task_m100_860.md

@@ -0,0 +1,94 @@
+# Task #860 수행계획서
+
+**이슈**: https://github.com/edwardkim/rhwp/issues/860
+**브랜치**: `local/task860`
+**작성일**: 2026-05-13
+**제목**: HWP3 sample14 의 그림(bin_id=2) 내부 콘텐츠 누락 — 박스 외곽만 렌더, 내부 텍스트 안 보임
+
+## 1. 본 단계 목적
+
+`samples/hwp3-sample14.hwp` (및 HWP5/HWPX 변환본) 의 그림 (bin_id=2, 149.9×41.9mm, tac=true) 의 **내부 콘텐츠 렌더링 결함 정정**.
+
+- 한컴 PDF (권위 자료): 박스 외곽 + 내부 텍스트 (terminal-style "If you leave me now / You'll take away..." 등) 표시
+- rhwp: 박스 외곽만, **내부 콘텐츠 누락**
+
+목표: rhwp 가 한컴 PDF 와 동일하게 그림 내부 콘텐츠 표시.
+
+## 2. 본질 진단 가설
+
+### 가설 H1 — BinData 추출 실패
+
+HWP3 파서 (`src/parser/hwp3/`) 가 BinData 의 image binary 를 추출 못 함. SVG 의 `<image>` 에 빈 또는 잘못된 data URI.
+
+### 가설 H2 — Vector primitives 미지원
+
+이 그림이 raster (PNG/JPEG) 가 아닌 vector primitives (HWP3 의 drawing object group) 일 가능성. rhwp 의 image renderer 가 vector 처리 미지원.
+
+### 가설 H3 — Image format 미지원
+
+HWP3 특수 image format (예: WMF/EMF embedded in HWP3) — rhwp 의 image decoder 가 unhandled.
+
+### 가설 H4 — SVG embedding 실패
+
+image data 추출 OK 지만 SVG `<image>` data URI 생성/embedding 단계 실패.
+
+### 가설 H5 — Image format 정합하지만 PNG/SVG rendering 시 색상 처리 불일치
+
+image 자체는 ok 지만 SVG/PNG 변환 시 검은 배경 + 녹색 텍스트 조합이 누락 (e.g., transparency 처리).
+
+## 3. 단계 분해 (구현 계획서 초안)
+
+### 3-A. 본질 정밀 진단
+
+- A1. 한컴 PDF page 2 의 image 와 rhwp 의 SVG 생성된 image element 비교
+- A2. HWP3 파일의 BinData 의 bin_id=2 raw byte 추출 + format header 식별 (magic bytes 로 PNG/JPEG/EMF/WMF 식별)
+- A3. rhwp SVG 의 image element 검사 (data URI, href, 빈 placeholder 여부)
+- A4. 가설 H1~H5 결판 → 본질 위치 (코드 line) 식별
+
+**산출**: `mydocs/working/task_m100_860_stage_a.md`
+
+### 3-B. 정정 후보 평가
+
+- B1. 정정 후보 ≥ 1 개 식별 + 회귀 위험 평가
+- B2. 다른 sample (image 보유) 회귀 위험
+
+**산출**: `mydocs/working/task_m100_860_stage_b.md`
+
+### 3-C. 정정 구현 + 검증
+
+- C1. 정정 구현 (HWP3 파서 또는 image rendering)
+- C2. 검증:
+  1. cargo build --release
+  2. cargo test --release --lib (1246 passed 기대)
+  3. page 2 PNG 시각 비교 한컴 PDF 정합
+  4. HWP3 sample13 등 다른 HWP3 sample 회귀 검사
+  5. HWPX 변환본 검증
+
+**산출**: `mydocs/working/task_m100_860.md` (종합)
+**커밋**: `Task #860: HWP3 sample14 그림 내부 콘텐츠 렌더 정정`
+
+## 4. 검증 기준
+
+- page 2 의 그림 내부 텍스트 ("If you leave me now / You'll take away..." 등) 표시 — 한컴 PDF 정합
+- cargo test --release --lib: 1246 passed (회귀 0)
+- 다른 sample (image 보유) 회귀 0
+
+## 5. 위험 + 회피
+
+| 위험 | 회피 |
+|---|---|
+| HWP3 image format 의 복잡성 | format 별 단계적 fix (한 format 씩) |
+| 다른 sample 회귀 | 회귀 검증 필수 (hwp3-sample13 등) |
+| CLAUDE.md 규칙: HWP3 전용 로직은 `src/parser/hwp3/` 내부만 | renderer 의 공통 모듈에 HWP3 분기 추가 금지. format 추상화 통해 처리 |
+
+## 6. 본 단계 범위 외
+
+- HWP3 의 다른 결함 (별도 issue)
+- HWPX 파서 결함
+- WASM browser 검증 (선택)
+
+## 7. 승인 요청
+
+본 수행계획서 승인 후 → 구현 계획서 → 3-A 부터 진행.
+
+📋 **Task #860 수행계획서 승인 요청드립니다.**

mydocs/plans/task_m100_860_impl.md

@@ -0,0 +1,128 @@
+# Task #860 구현 계획서
+
+**선행**: `mydocs/plans/task_m100_860.md` (수행계획서, 승인 완료)
+**브랜치**: `local/task860`
+**작성일**: 2026-05-13
+
+## 단계 분해 (3 단계 + 승인 게이트)
+
+### Stage A: 본질 정밀 진단
+
+**A.1 한컴 PDF vs rhwp page 2 이미지 비교**:
+
+```bash
+mkdir -p output/860
+# 한컴 PDF page 2 의 image stream 추출
+pdfimages -all "pdf/hwp3-sample14-hwp5-2022.pdf" output/860/pdf_img 2>&1 | tail -3
+ls -la output/860/pdf_img*
+
+# rhwp SVG 의 image element 추출
+./target/release/rhwp export-svg "samples/hwp3-sample14.hwp" -p 1 -o /tmp/860/
+grep -o "<image[^>]*" /tmp/860/hwp3-sample14_002.svg | head -3
+```
+
+**A.2 HWP3 의 BinData bin_id=2 raw byte 추출**:
+
+```bash
+# HWP3 파서가 BinData 어떻게 처리하는지 확인
+grep -rn "BinData\|bin_data\|fn parse_bin_data" src/parser/hwp3/ | head -10
+
+# HWP3 binary 의 bin_id=2 byte 추출 (debug print 추가 또는 cargo example)
+```
+
+format 식별:
+- PNG magic: `89 50 4E 47` (b"\x89PNG")
+- JPEG magic: `FF D8 FF`
+- EMF magic: `01 00 00 00` (header)
+- WMF magic: `D7 CD C6 9A`
+- Custom HWP format ?
+
+**A.3 rhwp SVG 의 image element 검사**:
+
+- `<image href="data:image/png;base64,..."/>` 형식?
+- 빈 placeholder 또는 src 없음?
+- crop coords 정상?
+
+**A.4 가설 H1~H5 결판**:
+
+각 가설 ✓/✗ → 본질 위치:
+- 본질 코드 line (HWP3 parser 또는 image rendering)
+- 정정 방향 명확화
+
+**산출**: `mydocs/working/task_m100_860_stage_a.md`
+- BinData 추출 결과 (format / size / first bytes)
+- SVG image element 분석
+- 가설 결판
+- 정정 후보 ≥ 1 개
+
+### Stage B: 정정 후보 평가
+
+**B.1 정정 후보 회귀 위험 평가**:
+
+다른 sample 검사:
+- `samples/hwp3-sample13.hwp` (다른 HWP3 sample)
+- 기존 HWP3 image 보유 sample 들
+
+**B.2 정정 후보 우선순위**:
+
+CLAUDE.md 규칙 (HWP3 전용 로직 → `src/parser/hwp3/` 내부) 정합 확인.
+
+**산출**: `mydocs/working/task_m100_860_stage_b.md`
+- 정정 후보 + 회귀 위험
+- 정정 순서
+
+### Stage C: 정정 구현 + 검증
+
+**C.1 정정 구현**:
+
+진단 결과에 따라 1~3 위치 소스 수정. 작은 변경 우선.
+
+수정 위치 후보 (A 진단 후 확정):
+- `src/parser/hwp3/` (image binary 추출 / format 변환)
+- 또는 image format conversion (예: EMF → PNG via emf crate)
+
+**C.2 검증**:
+1. `cargo build --release`
+2. `cargo test --release --lib --bins` (1246 passed 기대)
+3. page 2 PNG 시각 비교 한컴 PDF 정합 — 박스 내부 텍스트 표시
+4. 다른 HWP3 sample 회귀:
+   - `samples/hwp3-sample13.hwp`
+   - HWP3 image 보유 다른 sample
+5. HWP5 변환본 (hwp3-sample14-hwp5.hwp) 도 동일 결과 확인 — 같은 image bin_id 사용 시 같은 결함이므로 fix 후 동일 정합
+
+**C.3 종합 보고서**:
+
+**산출**: `mydocs/working/task_m100_860.md` (종합)
+**커밋**: `Task #860: HWP3 sample14 그림 내부 콘텐츠 렌더 정정 — {본질 위치}`
+
+## 작업 순서 + 승인 게이트
+
+```
+A 본질 정밀 진단 → 산출 → 단계 완료 → 승인
+                                        ↓
+B 정정 후보 평가 → 산출 → 단계 완료 → 승인
+                                        ↓
+C 정정 구현 + 검증 + 종합 → 커밋 → 단계 완료 → 승인
+```
+
+각 단계 후 승인 게이트.
+
+## 위험 + 회피
+
+| 위험 | 회피 |
+|---|---|
+| HWP3 image format 의 복잡성 | format 별 단계적 fix |
+| EMF/WMF decoder 의존성 추가 필요 | crate (emf, wmf 등) 사용 또는 fallback PNG 변환 |
+| 다른 sample 회귀 | hwp3-sample13 + 기존 sample 회귀 검증 |
+| CLAUDE.md HWP3 전용 로직 제약 | 공통 모듈에 HWP3 분기 추가 금지, parser 내부만 |
+
+## 본 단계 범위 외
+
+- HWP3 의 다른 결함 (별도 issue)
+- WASM browser 검증 (선택)
+
+## 승인 요청
+
+본 구현 계획서 승인 후 → Stage A 부터 시작.
+
+📋 **Task #860 구현 계획서 승인 요청드립니다.**

mydocs/plans/task_m100_860_v2.md

@@ -0,0 +1,94 @@
+# Task #860 Stage D 수행계획서 (v2)
+
+**선행**: Task #860 Stage A-C (commit `4908ab0`, BMP image 콘텐츠 fix 완료)
+**브랜치**: `local/task860`
+**작성일**: 2026-05-13
+**범위**: Stage A-C 의 잔여 결함 — 그림 paragraph 와 캡션 paragraph 의 순서 (page boundary) 결함
+
+## 1. 본 단계 목적
+
+Stage A-C 의 fix 후 BMP image 콘텐츠 정상 표시 (한컴 PDF 정합). 그러나 page 2/11 시각 비교 시 추가 결함 발견:
+
+| 시각 요소 순서 | rhwp page 2 | 한컴 page 2 |
+|---|---|---|
+| 페이지 상단 | 라벨 ("'P' 명령 이후...") | **박스 2개** (Vim 화면) |
+| 박스 아래 | 박스 2개 | 라벨 |
+
+→ rhwp 가 그림 (image control 보유 paragraph) 과 캡션 paragraph 의 page boundary 처리 차이.
+
+**목표**: 한컴 PDF 와 페이지 별 paragraph 순서 정합.
+
+## 2. 본질 진단 가설
+
+### 가설 H1 — Page boundary 가 그림과 캡션 사이에 발생
+
+rhwp 가 그림 paragraph 를 페이지 1 끝에 packing, 캡션 paragraph 를 페이지 2 시작에 packing. 한컴은 그림 + 캡션 같은 페이지에 통합.
+
+### 가설 H2 — Paragraph 순서 자체 차이
+
+rhwp 와 한컴이 IR 의 paragraph 순서 해석 다름. HWP3 의 그림 + 캡션 paragraph 가 한컴은 "박스 → 캡션" 으로, rhwp 는 "캡션 → 박스" 로 해석.
+
+### 가설 H3 — 그림 paragraph 의 page_break_before/after 처리
+
+그림 paragraph 가 page_break_before 또는 다른 break flag 보유. rhwp 가 잘못 처리.
+
+### 가설 H4 — TAC 그림 paragraph 의 캡션 결합 (HWP3 의 caption mechanism)
+
+HWP3 의 그림 control 가 캡션 정보를 별도 control 또는 attribute 로 가짐. rhwp 가 캡션을 별도 paragraph 로 처리하여 순서/위치 어긋남.
+
+## 3. 단계 분해 (구현 계획서 초안)
+
+### Stage D-A: 본질 정밀 진단
+
+- A1. rhwp 의 page 1 vs page 2 boundary 의 paragraph 식별 (dump-pages)
+- A2. 한컴 PDF page 1 vs page 2 의 paragraph 분포 (pdftotext)
+- A3. 그림 paragraph (pi=N) 의 controls + page_break / column_type flag 확인
+- A4. 캡션 paragraph 식별 + 그 위치 결정 로직 추적
+- A5. 가설 H1~H4 결판
+
+**산출**: `mydocs/working/task_m100_860_stage_d_a.md`
+
+### Stage D-B: 정정 후보 평가
+
+- B1. 정정 후보 ≥ 1 개 식별
+- B2. 회귀 위험 평가 (다른 HWP3 sample 의 그림 + 캡션)
+
+**산출**: `mydocs/working/task_m100_860_stage_d_b.md`
+
+### Stage D-C: 정정 구현 + 검증
+
+- C1. 정정 구현 (HWP3 파서 또는 typeset 또는 layout)
+- C2. 검증:
+  1. cargo build --release
+  2. cargo test --release --lib (1230 passed 기대)
+  3. sample14 page 2 PNG 한컴 PDF 정합
+  4. sample13, exam_eng 회귀 검사
+- C3. 종합 보고서 + 커밋
+
+**산출**: `mydocs/working/task_m100_860_v2.md` (종합)
+**커밋**: `Task #860 Stage D: HWP3 그림+캡션 paragraph 순서 정합`
+
+## 4. 검증 기준
+
+- page 2 의 paragraph 순서 한컴 PDF 정합 (박스 → 캡션 → 본문)
+- cargo test --release --lib: 1230 passed (회귀 0)
+- 다른 HWP3 sample 회귀 0
+
+## 5. 위험 + 회피
+
+| 위험 | 회피 |
+|---|---|
+| HWP3 의 캡션 처리 본질 변경의 광범위 회귀 | D-A 진단 후 보수적 정정 + 회귀 검증 |
+| Stage C 의 fix 와 충돌 | 통합 검증 (BMP 콘텐츠 + paragraph 순서) |
+| CLAUDE.md HWP3 전용 로직 제약 | `src/parser/hwp3/` 내부 처리 우선, 공통 모듈 변경 시 careful |
+
+## 6. 본 단계 범위 외
+
+- 다른 HWP3 결함 (별도 issue 또는 task)
+- WASM browser 검증 (선택)
+
+## 7. 승인 요청
+
+본 수행계획서 승인 후 → 구현 계획서 → Stage D-A 부터 진행.
+
+📋 **Task #860 Stage D 수행계획서 승인 요청드립니다.**