Alhangeul
알한글 for macOS
알한글(alhangeul-macos)은 HWP/HWPX 파일을 macOS에서 미리보고, 앱에서 열고, 저장하고, 공유하고, PDF로 내보낼 수 있게 하는 오픈소스 데스크톱 앱입니다. 파일을 업로드하지 않고 로컬에서 문서를 다루는 것을 기본값으로 둡니다.
Rust 기반 rhwp 코어를 macOS 앱, Quick Look preview, Finder thumbnail, Swift bridge로 연결합니다. 첫 viewer는 rhwp-studio를 WKWebView로 품고, Finder/Quick Look은 Swift/Rust bridge native renderer를, PDF/인쇄는 현재 editor의 page SVG를 격리된 native 출력 경로에서 사용합니다.
"닫힌 HWP/HWPX 문서를 더 많은 환경에서 다룰 수 있게 한다"는 rhwp의 방향을 Mac 네이티브 경험으로 확장합니다.
Support
Maintained with support from OpenAI’s Codex for Open Source program.
Support is provided to the maintainer and does not imply endorsement.
현재 작업 축
v0.2.x는 Spotlight 통합을 추가한 WebView-backed public release 라인입니다. Finder Quick Look과 썸네일, WKWebView 기반 앱 뷰어, 저장/공유/PDF 내보내기, signed/notarized DMG 배포, Sparkle 업데이트 확인을 안정화하는 데 집중합니다.
장기 방향은 WebView fallback을 유지하면서 native macOS viewer/editor shell로 점진적으로 옮겨가는 것입니다. 이 경로는 Swift가 HWP renderer 전체를 재구현하는 것이 아니라, Rust/rhwp Skia renderer와 Swift 편집 UI/오버레이를 결합하는 방향으로 둡니다. 세부 구현 제약과 날짜가 필요한 판단은 제품 로드맵 메모에 분리해 둡니다.
v0.2.0부터 평문 HWP3/HWP5/HWPX의 본문을 Spotlight에서 검색할 수 있습니다. Applications에 설치하고 한 번 실행한 뒤 검색 준비와 문서 색인에 시간이 걸릴 수 있습니다. v0.2.2에서는 동일 버전을 제거·재설치해도 새 설치로 인식하여 기존 문서의 검색 준비를 다시 요청하도록 보완했습니다. 계속 검색되지 않으면 단순 지연으로 단정하지 말고 지원 범위·문제 구분 안내를 확인해 주세요. 검증 환경과 결과는 릴리스 기록에 구분해 두었습니다.
[!NOTE]
메인테이너 현재 결정(2026-06-01): 당분간 새 편집 기능을 빠르게 넓히기보다 upstream rhwp Skia renderer의 시각 정합성을 높이고, 그 결과를 Quick Look/Thumbnail/PDF/native viewer preview 정확도로 연결하는 것으로 결정했습니다. 앱의 기본 preview 경로는 안정성 gate가 통과될 때까지 현행 fallback을 유지하며, Skia 경로는 visual diff와 성능 검증을 거쳐 단계적으로 확대합니다. 다만 이는 앱 배포나 upstream rhwp release 반영을 멈춘다는 뜻이 아니며, 안정적인 rhwp release tag가 나오면 core, bundled rhwp-studio, provenance, smoke 검증을 맞춰 계속 반영하고 필요한 patch release도 이어갑니다. 자세한 배경과 기여 방향은 Discussion #325에 정리했습니다.
기여자 브랜치 전환 안내
[!IMPORTANT]
2026-05-14에 제품 개발 기본 브랜치가 devel-webview에서 devel로 전환되었고, 2026-05-16에 devel-webview에 남아 있던 #243 변경까지 devel에 병합되었습니다. 전환 전 fork나 오래된 clone을 기준으로 새 기여를 시작하려는 경우, 브랜치 이력이 크게 바뀌었으므로 저장소를 새로 fork/clone한 뒤 최신 devel에서 작업 브랜치를 다시 만들어 주세요.
기존 devel에 있던 native viewer/editor 장기 작업은 native-viewer-editor 브랜치로 보존했습니다. 이 브랜치는 이제 Swift native macOS shell, Rust/rhwp Skia renderer 연동, Swift 편집 UI/오버레이 실험 라인으로 취급합니다. devel-webview는 퇴역한 legacy alias이며 신규 PR 대상이나 자동화 기준으로 사용하지 않습니다.
릴리즈 안내
v0.2.4
v0.2.4 (22)는 편집 오류의 복구 결과를 안내하고, 복구된 문서에서 같은 창으로 편집·저장을 이어갑니다. 가져온 딸기 글꼴을 HWPX 첫 조판에 연결하고 문서에 지정된 굵기를 화면과 PDF에 반영합니다.
- 포함된
rhwp: v0.9.0, core·bundled Studio commit c9095c5f67632e6721e800ccc7fb43ea49d26682
- 글꼴을 추가하려면 Mac 글꼴 사용 안내를 참고하세요.
- 릴리즈 기록: v0.2.4 검증·제한 사항, 업데이트 문서
- 다운로드: GitHub Release v0.2.4. macOS 12 이상을 대상으로 하는 Intel·Apple Silicon 공용 서명·공증 DMG입니다. 최소 macOS 12와 Intel 실기기 GUI는 이번 릴리즈에서 직접 시험하지 못했습니다.
- 기존 앱:
알한글 → 업데이트 확인...에서 업데이트할 수 있습니다.
- 일부 HWPX의 가운데 정렬은 한컴 출력과 약 4pt 차이가 있습니다. 실제 Mac의 Spotlight 본문 검색은 후속 검증 중입니다.
GitHub Release, Sparkle, Homebrew Cask의 최신 공개 버전은 모두 v0.2.4 (22)이며 같은 signed/notarized universal DMG를 사용합니다.
이전 v0.1.10 저장 주의: HWP3 저장 시 원본이 HWP5 bytes로 바뀌거나, 보호 문서 저장 시 보호가 제거된 평문으로 원본을 덮어쓸 수 있습니다(#482, #480). v0.1.10을 계속 사용하는 경우 HWP3·암호 문서는 먼저 사본을 만들고 native 저장을 사용하지 마세요. 원본 보호가 적용된 최신 버전으로 업데이트하세요.
과거 릴리즈와 검증 기록은 릴리즈 인덱스, GitHub Releases와 업데이트 페이지에서 확인할 수 있습니다.
이정표
v0.1.x(WebView 첫 배포) -> v0.2(Mac 통합 확장) -> v0.3(변환과 자동화) -> v0.5+(native macOS viewer/editor shell) -> v2.0(Agent-ready 문서 환경)
| 버전 | 단계 | 사용자에게 보이는 변화 | 주요 범위 |
|---|
v0.1.x | WebView-backed public release | Finder와 Quick Look에서 HWP/HWPX가 보이고, 앱에서는 rhwp-studio 기반 viewer/editor로 문서를 열고 내보냅니다. | Quick Look, thumbnail, WKWebView HostApp, 저장/공유/PDF, signed/notarized DMG, Sparkle |
v0.2 | Mac 통합 확장 | 앱 화면 밖에서도 문서 정보와 내용을 더 잘 다룹니다. | 문서 정보/본문 추출, Spotlight/mdimporter 검토, Mac 서비스 연동 기반 |
v0.3 | 변환과 자동화 | 여러 HWP/HWPX 문서를 Finder, CLI, Shortcuts 흐름에서 변환합니다. | Text/Markdown/blocks JSON/HWPX 변환, batch 변환, Quick Action, CLI |
v0.5+ | Native macOS viewer/editor shell | WebView 의존도를 낮추고 Mac-native 문서 보기와 편집 상호작용 기반을 키웁니다. | Rust/rhwp Skia renderer 연동, native search/copy, Swift overlay, editor safety gates |
v2.0 | Agent-ready Docs | 에이전트가 문서를 열고 수정하고 렌더링 결과로 검증하는 루프를 제공합니다. | structured patch API, page anchor, document diff, render verification |
미래 기능 후보와 장기 제품 방향은 제품 로드맵 메모에서 관리합니다. README에는 아직 확정되지 않은 버전별 지원 기능 체크리스트를 나열하지 않습니다.
현재 구현 범위
현재 공개 릴리즈 v0.2.4의 제공 기능과 제한 사항입니다.
제공 기능
This is the beginning of the README. Read the rest at the original. Read the full README ↗
