개요

macOS Finder에서 HWP/HWPX 파일에 대한 Quick Look 미리보기 및 썸네일을 제공하는 확장(HWP Quick Look.app)을 구현한다.

포크(postmelee/rhwp) 내부 rhwp-macos/ 디렉토리 + macos/* 브랜치 기반으로 개발하며, 업스트림 ios/devel Swift 공유 레이어(CGTreeRenderer.swift 등)의 UIKit 의존을 CoreGraphics/CoreText로 치환하여 iOS·macOS 양쪽에서 동일 코드가 동작하도록 만든다.

목표

• Finder 스페이스바 → 첫 페이지 Quick Look 미리보기
• Finder 아이콘 뷰 썸네일
• Homebrew cask 초안 (.app 배포)
• 최소 macOS 12.0 (Monterey)
• Universal binary (aarch64 + x86_64)

비목표

• 공증/배포 자동화 (후속 트랙)
• 편집 기능 (뷰어/썸네일 only)
• 다중 페이지 스크롤 (v0.1.0 범위 외)

아키텍처

.hwp/.hwpx → QLPreviewProvider → Data → RhwpDocument(FFI)
 → rhwp_render_page_tree(JSON) → RenderNode
 → CGTreeRenderer (CoreGraphics/CoreText) → QLPreviewReply

• FFI 신규 추가 없음 (ios/devel의 8종 표면 재사용)
• 공유 4종 (RhwpDocument, RenderTree, FontFallback, CGTreeRenderer)에서 UIKit 제거
• Rust → Rhwp.xcframework (XCFramework) 로 Swift에서 링크

단계

• Stage 0: 업스트림 재검증 (완료)
• Stage 1: worktree + 스캐폴드 (완료)
• Stage 2: Rust macOS 빌드 파이프라인 (XCFramework)
• Stage 3: Swift 공유 레이어 UIKit → CG/CT 치환 + iOS 빌드 검증
• Stage 4: QL Preview Extension 최소 동작 + UTI
• Stage 5: Thumbnail Extension + HostApp UX
• Stage 6: 릴리스 패키징 + Homebrew cask 초안

검증 기준

• Finder 스페이스바 → 첫 페이지 렌더 (< 3초)
• Finder 썸네일 (< 2초)
• peak RSS < 200MB (100페이지 문서)
• 공유 코드 AppKit/UIKit 의존 없음
• iOS Xcode 빌드 회귀 없음
• brew install --cask rhwp-macos (본인 tap)

참고

• 구현 계획서: mydocs/plans/rhwp_quicklook_macos_impl.md
• 업스트림 고정 SHA: 34b6e20 (edwardkim/rhwp@ios/devel, 2026年04月20日)