[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-77819":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":8,"language":10,"languages":8,"totalLinesOfCode":8,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":16,"stars7d":17,"stars30d":18,"stars90d":15,"forks30d":15,"starsTrendScore":19,"compositeScore":20,"rankGlobal":8,"rankLanguage":8,"license":21,"archived":22,"fork":22,"defaultBranch":23,"hasWiki":24,"hasPages":24,"topics":25,"createdAt":8,"pushedAt":8,"updatedAt":26,"readmeContent":27,"aiSummary":28,"trendingCount":15,"starSnapshotCount":15,"syncStatus":13,"lastSyncTime":29,"discoverSource":30},77819,"alhangeul-macos","postmelee\u002Falhangeul-macos","postmelee",null,"https:\u002F\u002Fpostmelee.github.io\u002Falhangeul-macos\u002F","Swift",179,14,2,10,0,5,26,67,15,70.23,"MIT License",false,"main",true,[],"2026-06-12 04:01:22","\u003Cp align=\"center\">\n  \u003Cimg src=\"assets\u002Flogo-256@2x.png\" alt=\"Alhangeul logo\" width=\"128\" \u002F>\n\u003C\u002Fp>\n\n# \u003Cdiv align=\"center\">Alhangeul\u003C\u002Fdiv>\n\n\u003Cp align=\"center\">\n  \u003Cstrong>알한글 for macOS\u003C\u002Fstrong>\u003Cbr\u002F>\n  \u003Cem>오픈소스 HWP\u002FHWPX 유틸리티 앱 \u003C\u002Fem>\n\u003C\u002Fp>\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fpostmelee\u002Falhangeul-macos\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fplatform-macOS%2012%2B-blue\" alt=\"macOS 12+\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fwww.swift.org\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FSwift-5.9-orange\" alt=\"Swift 5.9\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fwww.rust-lang.org\u002F\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FRust-native%20bridge-orange\" alt=\"Rust native bridge\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fopensource.org\u002Flicenses\u002FMIT\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg\" alt=\"License: MIT\" \u002F>\u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fgithub.com\u002Fpostmelee\u002Falhangeul-macos\u002Freleases\">\u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fdownloads\u002Fpostmelee\u002Falhangeul-macos\u002Ftotal?label=downloads\" alt=\"GitHub all releases downloads\" \u002F>\u003C\u002Fa>\n\u003C\u002Fp>\n\n\u003Ch3 align=\"center\">Mac에서 한글 파일은 더 이상 이방인이 아닙니다.\u003C\u002Fh3>\n\n![banner](assets\u002Fbanner_home.png)\n\n\u003Cp align=\"center\">스페이스바로 미리보고, Finder에서 썸네일로 찾고, 앱에서 열어 저장·공유·PDF 내보내기까지 처리하세요.\u003C\u002Fp>\n\n---\n\n## 알한글 for macOS\n\n\u003Cstrong>알한글(alhangeul-macos)\u003C\u002Fstrong>은 HWP\u002FHWPX 파일을 macOS에서 미리보고, 앱에서 열고, 저장하고, 공유하고, PDF로 내보낼 수 있게 하는 오픈소스 데스크톱 앱입니다. 파일을 업로드하지 않고 로컬에서 문서를 다루는 것을 기본값으로 둡니다.\n> Rust 기반 [`rhwp`](https:\u002F\u002Fgithub.com\u002Fedwardkim\u002Frhwp) 코어를 macOS 앱, Quick Look preview, Finder thumbnail, Swift bridge로 연결합니다. 첫 viewer는 `rhwp-studio`를 WKWebView로 품고, Finder\u002FQuick Look과 PDF 내보내기에는 이 저장소의 Swift\u002FRust bridge 렌더링 경로를 함께 사용합니다.\n> \"닫힌 HWP\u002FHWPX 문서를 더 많은 환경에서 다룰 수 있게 한다\"는 [`rhwp`](https:\u002F\u002Fgithub.com\u002Fedwardkim\u002Frhwp)의 방향을 **Mac 네이티브** 경험으로 확장합니다.\n\n\n## 현재 작업 축\n\n`v0.1.x`는 WebView-backed public release 라인입니다. Finder Quick Look과 썸네일, WKWebView 기반 앱 뷰어, 저장\u002F공유\u002FPDF 내보내기, signed\u002Fnotarized DMG 배포, Sparkle 업데이트 확인을 안정화하는 데 집중합니다.\n\n장기 방향은 WebView fallback을 유지하면서 native macOS viewer\u002Feditor shell로 점진적으로 옮겨가는 것입니다. 이 경로는 Swift가 HWP renderer 전체를 재구현하는 것이 아니라, Rust\u002Frhwp Skia renderer와 Swift 편집 UI\u002F오버레이를 결합하는 방향으로 둡니다. 세부 구현 제약과 날짜가 필요한 판단은 [제품 로드맵 메모](mydocs\u002Ftech\u002Fproduct_roadmap_notes.md)에 분리해 둡니다.\n\n### 기여자 브랜치 전환 안내\n\n> [!IMPORTANT]\n> 2026-05-14에 제품 개발 기본 브랜치가 `devel-webview`에서 `devel`로 전환되었고, 2026-05-16에 `devel-webview`에 남아 있던 #243 변경까지 `devel`에 병합되었습니다. 전환 전 fork나 오래된 clone을 기준으로 새 기여를 시작하려는 경우, 브랜치 이력이 크게 바뀌었으므로 저장소를 새로 fork\u002Fclone한 뒤 최신 `devel`에서 작업 브랜치를 다시 만들어 주세요.\n\n> 기존 `devel`에 있던 native viewer\u002Feditor 장기 작업은 `native-viewer-editor` 브랜치로 보존했습니다. 이 브랜치는 이제 Swift native macOS shell, Rust\u002Frhwp Skia renderer 연동, Swift 편집 UI\u002F오버레이 실험 라인으로 취급합니다. `devel-webview`는 퇴역한 legacy alias이며 신규 PR 대상이나 자동화 기준으로 사용하지 않습니다.\n\n## 최신 공개 릴리즈\n\n### v0.1.3\n\n`v0.1.3`은 upstream `rhwp v0.7.12` core\u002Fstudio를 반영해 HWP\u002FHWPX parser, viewer, WMF\u002FHWP3 처리 개선을 포함하는 patch release입니다. 앱 소유 UTI `com.postmelee.alhangeul.*`, Hancom 계열 UTI 지원, About 창의 bundled `rhwp` provenance 표시, Sparkle 업데이트 확인, signed\u002Fnotarized universal DMG 배포 기준은 유지합니다.\n\n- GitHub Release: [Alhangeul v0.1.3](https:\u002F\u002Fgithub.com\u002Fpostmelee\u002Falhangeul-macos\u002Freleases\u002Ftag\u002Fv0.1.3)\n- 업데이트 페이지: [알한글 v0.1.3](https:\u002F\u002Fpostmelee.github.io\u002Falhangeul-macos\u002Fupdates\u002Fv0.1.3.html)\n- Homebrew Cask: `brew install --cask postmelee\u002Ftap\u002Falhangeul`\n- 포함된 `rhwp`: [`v0.7.12`](https:\u002F\u002Fgithub.com\u002Fedwardkim\u002Frhwp\u002Freleases\u002Ftag\u002Fv0.7.12) (`rhwp-core.lock`, bundled `rhwp-studio` manifest 기준)\n- Sparkle update 기준: short version은 `0.1.3`, build는 `9`입니다.\n\n과거 릴리즈 상세와 검증 기록은 `mydocs\u002Frelease\u002F`의 릴리즈별 문서와 [GitHub Releases](https:\u002F\u002Fgithub.com\u002Fpostmelee\u002Falhangeul-macos\u002Freleases)에 누적합니다. 사용자용 릴리즈 노트 목록은 [업데이트 페이지](https:\u002F\u002Fpostmelee.github.io\u002Falhangeul-macos\u002Fupdates\u002F)에서 확인할 수 있습니다. README에는 최신 공개 릴리즈 1개만 요약하고, bundled `rhwp` provenance는 한 줄 요약만 표시합니다.\n\n## 이정표\n\n```text\nv0.1.x(WebView 첫 배포) -> v0.2(Mac 통합 확장) -> v0.3(변환과 자동화) -> v0.5+(native macOS viewer\u002Feditor shell) -> v2.0(Agent-ready 문서 환경)\n```\n\n| 버전 | 단계 | 사용자에게 보이는 변화 | 주요 범위 |\n|------|------|------------------------|-----------|\n| `v0.1.x` | WebView-backed public release | Finder와 Quick Look에서 HWP\u002FHWPX가 보이고, 앱에서는 `rhwp-studio` 기반 viewer\u002Feditor로 문서를 열고 내보냅니다. | Quick Look, thumbnail, WKWebView HostApp, 저장\u002F공유\u002FPDF, signed\u002Fnotarized DMG, Sparkle |\n| `v0.2` | Mac 통합 확장 | 앱 화면 밖에서도 문서 정보와 내용을 더 잘 다룹니다. | 문서 정보\u002F본문 추출, Spotlight\u002Fmdimporter 검토, Mac 서비스 연동 기반 |\n| `v0.3` | 변환과 자동화 | 여러 HWP\u002FHWPX 문서를 Finder, CLI, Shortcuts 흐름에서 변환합니다. | Text\u002FMarkdown\u002Fblocks JSON\u002FHWPX 변환, batch 변환, Quick Action, CLI |\n| `v0.5+` | Native macOS viewer\u002Feditor shell | WebView 의존도를 낮추고 Mac-native 문서 보기와 편집 상호작용 기반을 키웁니다. | Rust\u002Frhwp Skia renderer 연동, native search\u002Fcopy, Swift overlay, editor safety gates |\n| `v2.0` | Agent-ready Docs | 에이전트가 문서를 열고 수정하고 렌더링 결과로 검증하는 루프를 제공합니다. | structured patch API, page anchor, document diff, render verification |\n\n미래 기능 후보와 장기 제품 방향은 [제품 로드맵 메모](mydocs\u002Ftech\u002Fproduct_roadmap_notes.md)에서 관리합니다. README에는 아직 확정되지 않은 버전별 지원 기능 체크리스트를 나열하지 않습니다.\n\n## v0.1.x 구현 범위\n\n현재 공개 릴리즈 라인에서 제공하는 기능과 알려진 제약입니다.\n\n### 제공 기능\n\n- [x] `.hwp`, `.hwpx` Quick Look preview\n- [x] 첫 페이지 기반 Finder thumbnail\n- [x] WKWebView 기반 HWP\u002FHWPX viewer\u002Feditor\n- [x] WebView 내부 찾기, 선택, 복사, 기본 편집 UI\n- [x] Finder 또는 다른 앱에서 HWP\u002FHWPX 파일 열기\n- [x] Finder에서 viewer 영역으로 끌어와서 열기\n- [x] 최근 문서 목록과 security-scoped bookmark 기반 재열기\n- [x] HWP 저장과 다른 이름으로 저장\n- [x] PDF 내보내기\n- [x] native 인쇄 flow 연결\n- [x] macOS 공유 sheet\n- [x] 원본 URL이 있는 문서를 Finder에서 보기\n- [x] Quick Look\u002FThumbnail extension 상태 진단\n- [x] signed\u002Fnotarized DMG 배포 기준\n- [x] `v0.1.1`부터 Intel Mac과 Apple Silicon Mac을 위한 단일 universal DMG 배포 기준\n- [x] Sparkle 업데이트 확인 경로\n\n### 현재 제한 사항\n\n- 앱 화면의 viewer\u002Feditor와 Finder Quick Look\u002Fthumbnail, PDF 내보내기, 인쇄는 서로 다른 렌더링 경로를 사용할 수 있습니다.\n- Quick Look\u002FThumbnail smoke 통과는 extension 등록과 기본 렌더 성공을 뜻하며, 모든 문서가 앱 화면과 같은 시각 결과로 보인다는 보장은 아닙니다.\n- HWPX 문서는 현재 직접 저장이 제한되어 HWP export 경로를 사용합니다.\n- 손상, 대용량, 미지원 문서 fallback은 앱과 extension이 멈추지 않도록 하는 안전장치이며, 파일 복구나 부분 렌더링을 보장하지 않습니다.\n- CoreGraphics\u002FCoreText 기반 native renderer의 style, image effect\u002Ffill, text layout, RawSvg\u002FOLE 등 parity gap은 현재 Quick Look\u002FThumbnail\u002FPDF와 fallback\u002Fdiagnostic 경로에서 계속 다룹니다. HostApp 장기 native 경로는 Rust\u002Frhwp Skia renderer와 Swift overlay를 결합하는 방향으로 분리합니다.\n\n## Features\n\n### Finder Integration (Finder 통합)\n\n- `.hwp`, `.hwpx` Quick Look preview\n- 단일 페이지는 PNG, 다중 페이지는 Quick Look 표시용 PDF preview로 표시\n- 첫 페이지 기반 Finder thumbnail과 thumbnail render cache\n- `.hwp`, `.hwpx` 및 Hancom 계열 UTI 등록\n- 50 MB 초과 파일 preview fallback\n- 앱 정보 창에서 Quick Look\u002FThumbnail extension 번들 포함과 시스템 등록 상태 확인\n\n### WKWebView Viewer (MVP 뷰어)\n\n- macOS SwiftUI 기반 HostApp shell과 WKWebView\n- `edwardkim\u002Frhwp` `v0.7.12` snapshot의 `rhwp-studio` viewer 통합\n- HWP\u002FHWPX 파일 열기\n- WebView 내부 찾기, 복사, 기본 편집 UI\n- Finder 또는 다른 앱에서 파일 열기 요청 수신\n- Finder에서 viewer 영역으로 끌어와서 열기\n- 최근 문서 목록에서 다시 열기\n- 로컬 파일을 앱 sandbox 안에서 WebView viewer로 전달\n- WebView 기반 스크롤, 확대\u002F축소, 페이지 이동, 오류 상태 표시\n\n### Document Actions (문서 작업)\n\n- 파일 메뉴와 `Command+O\u002FS\u002FShift+S\u002FP` 단축키를 native 열기, 저장, 다른 이름으로 저장, 인쇄 flow에 연결\n- HWP 문서 저장과 다른 이름으로 저장\n- PDF로 내보내기 후 저장된 PDF를 Finder에서 표시\n- macOS 공유 sheet로 현재 문서 공유\n- 원본 URL이 있는 문서를 Finder에서 보기\n- HWPX 문서는 현재 bundled `rhwp-studio`의 정책에 따라 직접 저장이 비활성화되어 있으며, 저장 flow는 HWP export 경로를 사용\n\n### Rendering Paths (렌더링 경로)\n\n| 표면 | v0.1 렌더링 경로 | 기준 |\n|------|------------------|------|\n| HostApp viewer\u002Feditor 화면 | `rhwp-studio` Web\u002FWASM rendering in WKWebView | 첫 공개 배포의 기본 viewer\u002Feditor 경로 |\n| PDF 내보내기 | Rust bridge + Swift CoreGraphics\u002FCoreText render tree PDF 경로 | 앱 화면과 같은 renderer를 쓰지는 않음 |\n| 인쇄 | `rhwp-studio` page payload + 별도 WKWebView\u002FPDFKit\u002FAppKit print operation | PDF 내보내기와 다른 출력 경로 |\n| Quick Look preview | Rust bridge + Swift CoreGraphics\u002FCoreText render tree bitmap\u002FPDF | Finder preview용 경로 |\n| Finder thumbnail | Rust bridge + Swift CoreGraphics\u002FCoreText first-page bitmap\u002Fcache | Finder icon\u002Fthumbnail용 경로 |\n\nWKWebView 경로는 native macOS shell이 충분히 안정화될 때까지 fallback과 비교 기준선으로 유지합니다. 현재 Quick Look\u002FThumbnail\u002FPDF export의 native bitmap 경로는 Rust core render tree JSON, CoreGraphics, CoreText, 이미지 bin data를 사용합니다. HostApp 장기 native 경로는 Swift macOS shell, Rust\u002Frhwp Skia renderer, Swift 편집 UI\u002F오버레이를 결합하는 방향으로 둡니다.\n\n### Core Bridge (코어 브리지)\n\n- `edwardkim\u002Frhwp`를 git dependency로 사용하는 `RustBridge` crate\n- C ABI 기반 `rhwp_*` FFI entrypoint\n- `cbindgen` header\u002Fmodulemap 생성\n- universal static library 생성\n- `Rhwp.xcframework`를 HostApp, Quick Look, Thumbnail target에서 공유\n- FFI symbol set을 `rhwp-ffi-symbols.txt`로 고정\n- `rhwp-core.lock`으로 core source provenance와 Rust bridge reference artifact metadata 기록\n\n### Development Workflow (개발 워크플로우)\n\n- XcodeGen 기반 project 생성\n- Rust bridge, Swift renderer, Swift app shell 소유 경계 분리\n- `check-no-appkit.sh`로 shared Swift bridge의 AppKit\u002FUIKit 의존성 검사\n- native renderer 변경은 `validate-stage3-render.sh`로 렌더링 smoke test\n- 제품 기능과 배포 후보 작업은 `devel`, HostApp native macOS shell과 Swift overlay 실험 작업은 `native-viewer-editor` 기준으로 분리\n- GitHub Issue 기반 task branch와 한국어 작업 문서\n\n자세한 구조와 bridge 정책은 [아키텍처 문서](mydocs\u002Ftech\u002Fproject_architecture.md)를 참조하세요.\n\n## Release \u002F Install\n\n공개 배포 기준은 Developer ID로 서명하고 Apple notarization을 통과한 DMG입니다. GitHub Release에는 `alhangeul-macos-\u003Cversion>.dmg`와 checksum을 함께 공개합니다. `v0.1.1`부터 공식 DMG는 앱 본체와 Quick Look\u002FThumbnail extension 실행 파일이 `arm64 + x86_64` slice를 포함하는 단일 universal DMG 기준으로 검증합니다. Intel Mac과 Apple Silicon Mac 모두 같은 파일을 받으며, 아키텍처별 DMG는 따로 제공하지 않습니다.\n\nHomebrew Cask로 설치할 수도 있습니다.\n\n```bash\nbrew install --cask postmelee\u002Ftap\u002Falhangeul\n```\n\n설치 후에는 `Alhangeul.app`을 한 번 실행하세요. macOS가 Quick Look 및 Thumbnail extension을 발견하고 등록한 뒤 Finder에서 `.hwp`, `.hwpx` preview와 thumbnail을 사용할 수 있습니다.\n\n최신 공개 릴리즈는 [GitHub Releases](https:\u002F\u002Fgithub.com\u002Fpostmelee\u002Falhangeul-macos\u002Freleases\u002Flatest)와 [업데이트 페이지](https:\u002F\u002Fpostmelee.github.io\u002Falhangeul-macos\u002Fupdates\u002F)에서 확인합니다. 릴리스가 게시되기 전에는 아래 소스 빌드 절차를 사용하세요. unsigned, ad-hoc signed, rehearsal DMG는 일반 사용자 배포 산출물이 아닙니다.\n\n## Quick Start (소스 빌드)\n처음 프로젝트에 참여하는 개발자는 [Project Structure](#project-structure)를 먼저 보고, 세부 경계는 [아키텍처 문서](mydocs\u002Ftech\u002Fproject_architecture.md), 상세한 빌드 및 검증 절차는 [빌드 및 실행 가이드](mydocs\u002Fmanual\u002Fbuild_run_guide.md)를 확인하세요. 실제 빌드는 Rust bridge 산출물을 만든 뒤 Xcode project를 생성하고 HostApp을 빌드하는 순서입니다.\n\n### Requirements\n\n- macOS 12 Monterey 이상\n- Xcode 15 이상\n- Swift 5.9\n- Rust toolchain\n- `cbindgen`\n- XcodeGen\n\n### Initial Setup\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fpostmelee\u002Falhangeul-macos.git\ncd alhangeul-macos\n\nrustup target add aarch64-apple-darwin x86_64-apple-darwin\ncargo install cbindgen\nbrew install xcodegen\n```\n\n### Build\n\n```bash\n.\u002Fscripts\u002Fbuild-rust-macos.sh\nxcodegen generate\nxcodebuild -project Alhangeul.xcodeproj \\\n  -scheme HostApp \\\n  -configuration Debug \\\n  -derivedDataPath build.noindex\u002FDerivedData \\\n  CODE_SIGNING_ALLOWED=NO \\\n  build\n```\n\n### Run\n\n```bash\nopen build.noindex\u002FDerivedData\u002FBuild\u002FProducts\u002FDebug\u002FAlhangeul.app\n```\n\n### Checks\n\n```bash\n.\u002Fscripts\u002Fcheck-no-appkit.sh\nscripts\u002Fverify-rhwp-studio-assets.sh\n```\n\n- WKWebView viewer 경로를 바꾼 경우: [빌드 및 실행 가이드](mydocs\u002Fmanual\u002Fbuild_run_guide.md)의 HostApp WKWebView viewer smoke test\n- native renderer 경로를 바꾼 경우: `.\u002Fscripts\u002Fvalidate-stage3-render.sh`\n- Core dependency - [core dependency 운영 가이드](mydocs\u002Fmanual\u002Fcore_dependency_operation_guide.md)\n- CI workflow 역할과 로컬 재현 - [CI workflow 가이드](mydocs\u002Fmanual\u002Fci_workflow_guide.md)\n- release packaging, signing, notarization - [릴리스\u002F배포 가이드](mydocs\u002Fmanual\u002Frelease_distribution_guide.md)\n- Finder extension 등록 검증 - [빌드 및 실행 가이드](mydocs\u002Fmanual\u002Fbuild_run_guide.md)\n- renderer 비교 디버깅 - [core\u002Fnative 렌더 비교 가이드](mydocs\u002Fmanual\u002Frender_core_native_compare_guide.md)\n\n## Project Structure\n\n이 저장소는 먼저 macOS 제품 타깃을 나누고, 그 아래에 공통 Swift 계층과 Rust bridge를 둡니다.\n\n```text\nSources\u002F\n├── HostApp\u002F                  # macOS WKWebView viewer app\n│   ├── Resources\u002F            # bundled rhwp-studio static asset\n│   ├── Services\u002F             # 열기\u002F저장\u002FPDF\u002F공유\u002FFinder reveal, WebView resource\u002Fdocument bridge\n│   ├── Stores\u002F               # WKWebView viewer 문서 payload와 loading\u002Ferror 상태\n│   ├── Support\u002F              # 빌드 정보\n│   └── Views\u002F                # SwiftUI\u002FWebKit viewer UI\n├── QLExtension\u002F              # Quick Look preview extension\n├── ThumbnailExtension\u002F       # Finder thumbnail extension\n├── Shared\u002F                   # HostApp\u002Fextension 공통 macOS helper\n└── RhwpCoreBridge\u002F           # AppKit\u002FUIKit 없는 Swift FFI wrapper + render tree renderer\n\nRustBridge\u002F                   # edwardkim\u002Frhwp를 C ABI로 노출하는 Rust staticlib crate\n├── Cargo.toml                # rhwp git dependency 선언\n├── Cargo.lock                # Cargo가 해석한 resolved commit 고정\n├── cbindgen.toml             # C header 생성 설정\n└── src\u002Flib.rs                # rhwp_* FFI entrypoints\n\nFrameworks\u002F                   # generated Rhwp.xcframework\u002Fheader\u002Fmodulemap, git ignore 대상\nproject.yml                   # Xcode project 원본\nrhwp-core.lock                # core provenance + Rust bridge reference artifact metadata\nsamples\u002F                      # render smoke와 Finder smoke용 HWP\u002FHWPX fixture\nscripts\u002F                      # build, lock verify, render smoke, package helper\nmydocs\u002F                       # hyper-waterfall 작업 문서와 운영 매뉴얼\n```\n\n`project.yml`은 `Alhangeul.xcodeproj`의 원본입니다. target, source 포함 범위, bundle identifier, extension embedding을 바꿀 때는 `project.yml`을 수정한 뒤 `xcodegen generate`를 실행합니다.\n\n타깃 간 소유 경계, 공통 Swift 계층, Rust bridge, 런타임 데이터 흐름은 [아키텍처 문서](mydocs\u002Ftech\u002Fproject_architecture.md)를 참조하세요.\n\n## AI 페어 프로그래밍으로 개발합니다\n\n> 이 섹션의 문제의식과 개발 방법론 설명은 `edwardkim\u002Frhwp` README.md의 [\"AI 페어 프로그래밍으로 개발합니다\"](https:\u002F\u002Fgithub.com\u002Fedwardkim\u002Frhwp#ai-%ED%8E%98%EC%96%B4-%ED%94%84%EB%A1%9C%EA%B7%B8%EB%9E%98%EB%B0%8D%EC%9C%BC%EB%A1%9C-%EA%B0%9C%EB%B0%9C%ED%95%A9%EB%8B%88%EB%8B%A4) 섹션을 바탕으로 합니다. alhangeul-macos에서는 같은 절차를 Claude Code와 OpenAI Codex에 함께 적용합니다.\n\n**이것은 바이브 코딩이 아닙니다.** AI가 주는 코드를 읽지도 않고 수락하는 것이 아닙니다. 모든 계획은 검토되고, 모든 결과물은 검증되며, 모든 결정의 뒤에는 사람이 있습니다.\n\n바이브 코딩 — AI 출력을 읽지 않고 수락하고, AI에게 아키텍처 결정을 맡기고, 이해하지 못하는 코드를 배포하는 것 — 은 함정입니다. 겉보기에는 동작하지만, 이해하지 못했기 때문에 문제가 생겨도 진단할 수 없는 코드가 만들어집니다.\n\n이 프로젝트는 정반대의 접근을 취합니다. 사람 **작업지시자**가 방향, 품질, 아키텍처 결정의 완전한 소유권을 유지하고, AI는 혼자서는 불가능한 속도와 규모로 구현을 수행합니다. 핵심 차이: **사람은 절대 생각을 멈추지 않습니다.**\n\n### 바이브 코딩 vs. AI 주도 개발\n\n| | 바이브 코딩 | 이 프로젝트 |\n|--|-----------|-----------|\n| **사람의 역할** | AI 출력 수락 | 지시, 검토, 결정 |\n| **계획** | 없음 — \"그냥 만들어\" | 계획서 작성 → 승인 → 실행 |\n| **품질 관문** | 동작하길 바람 | 빌드 + 렌더링 smoke test + 코드 리뷰 |\n| **디버깅** | AI에게 AI 버그 수정 요청 | 사람이 진단, AI가 구현 |\n| **아키텍처** | 우연히 형성 | 의도적 설계 (core, bridge, app 경계) |\n| **문서** | 없음 | `mydocs\u002F` 프로세스 기록 |\n| **결과물** | 취약, 유지보수 어려움 | 검증 가능한 변경 단위 |\n\nAI는 배율기입니다. 하지만 배율기는 기존 프로세스를 증폭시킵니다. 프로세스 없음 × AI = 빠른 혼돈. 좋은 프로세스 × AI = 비범한 결과물.\n\n### 개발 프로세스\n\n이 프로젝트는 [**Claude Code**](https:\u002F\u002Fclaude.ai\u002Fcode) 와 [**OpenAI Codex**](https:\u002F\u002Fopenai.com\u002Fko-KR\u002Fcodex\u002F)를 페어 프로그래밍 파트너로 사용하여 개발합니다. 전체 개발 과정은 Issue, branch, 작업 문서, PR에 투명하게 남깁니다.\n\n```text\n작업지시자 (사람)                    AI 페어 프로그래머 (Claude Code \u002F Codex)\n────────────────                    ─────────────────────────────────────\n방향 설정, 우선순위 결정        →    분석, 계획, 구현\n계획 검토, 승인                ←    구현 계획서 작성\n도메인 피드백 제공              →    디버깅, 테스트, 반복\n아키텍처 결정                  →    정밀하게 실행\n품질 및 정확성 판단            ←    코드, 문서, 테스트 생성\n```\n\n`mydocs\u002F` 디렉토리에 개발 기록이 있습니다: 일일 작업 기록, 구현 계획서, 단계별 완료 보고서, 최종 보고서, 기술 연구 문서, 트러블슈팅 기록.\n\n> `mydocs\u002F`는 코드에 대한 문서만이 아닙니다 — **AI로 소프트웨어를 만드는 방법**에 대한 문서입니다.\n\n**Hyper-Waterfall 방법론** — 거시적 워터폴 + 미시적 애자일, AI가 이 둘을 동시에 가능하게 한다.\n\n### Git 워크플로우\n\n```text\nlocal\u002Ftask{N}  ──커밋──커밋──┐\n                              ├─→ publish\u002Ftask{N} push\n                              ├─→ 통합 브랜치 Open PR + merge\n                              ├─→ main merge + 태그 (릴리즈 시점)\n```\n\n| 브랜치 | 용도 |\n|--------|------|\n| `main` | 릴리즈 |\n| `devel` | v0.1.x 첫 공개 배포, WKWebView-backed viewer\u002Feditor, Finder\u002FQuick Look, PDF\u002F공유\u002F저장, Mac 통합\u002F변환, 배포\u002F문서 작업의 기본 통합 |\n| `native-viewer-editor` | native macOS viewer\u002Feditor shell, Rust\u002Frhwp Skia renderer 연동, Swift 편집 UI\u002F오버레이 장기 작업 통합 |\n| `devel-webview` | 퇴역한 legacy alias. 신규 작업과 자동화 기준으로 사용하지 않음 |\n| `local\u002Ftask{N}` | GitHub Issue 번호 기반 타스크 브랜치 |\n| `publish\u002Ftask{N}` | `devel` 또는 `native-viewer-editor` 대상 PR 생성을 위한 원격 게시 브랜치 |\n\n제품 브랜치와 native 전환 브랜치 역할은 [WKWebView\u002Fnative 브랜치 전략](mydocs\u002Ftech\u002Fbranch_strategy_webview_native.md)을 기준으로 유지합니다.\n\n### 타스크 관리\n\n- **GitHub Issues**로 타스크 번호 자동 채번 — 중복 방지\n- 브랜치명: `local\u002Ftask{issue번호}`\n- PR 생성용 원격 브랜치명: `publish\u002Ftask{issue번호}`\n- 오늘할일: `mydocs\u002Forders\u002Fyyyymmdd.md`\n- 커밋 메시지:\n  - 기본형: `Task #{번호}: 내용`\n  - 단계 커밋: `Task #{번호} Stage {N}: 내용`\n- PR 대상: 작업 범위에 따라 `devel` 또는 `native-viewer-editor`\n\n### 타스크 진행 절차\n\n이슈 → 브랜치 → 오늘할일 → 수행계획서 → 구현계획서 → 구현 → 검증 → 단계 보고 → 최종 보고 → PR 게시 → merge 후 정리.\n\n15단계 상세, 승인 게이트, 커밋 메시지 규칙은 [`task_workflow_guide.md`](mydocs\u002Fmanual\u002Ftask_workflow_guide.md)를 참고하세요.\n\n### 디버깅 프로토콜\n\n렌더링 문제:\n\n1. `validate-stage3-render.sh` → 기본 샘플의 native render pipeline smoke 확인\n2. `render-debug-compare.sh` → 특정 파일의 render tree JSON, core SVG, native PNG, pixel diff 산출\n3. core SVG와 native PNG가 다르면 [core\u002Fnative 렌더 비교 가이드](mydocs\u002Fmanual\u002Frender_core_native_compare_guide.md)에 따라 Swift renderer 문제와 core 문제를 분리\n4. 필요 시 별도 `edwardkim\u002Frhwp` clone 또는 Cargo checkout에서 core rendering data 확인\n\nFinder\u002FQuick Look 통합 문제:\n\n1. `pluginkit -mAvvv | grep com.postmelee.alhangeul` → extension 등록 후보 확인\n2. `qlmanage -p` → Finder preview 경로 확인\n3. `qlmanage -t -x` → thumbnail 생성 경로 확인\n4. 반복 시행착오는 [Finder 통합 검증 시행착오 방지 가이드](mydocs\u002Ftroubleshootings\u002Ffinder_integration_validation_pitfalls.md)를 확인\n\n### 문서 생성 규칙\n\n모든 문서는 **한국어**로 작성합니다.\n\n```text\nmydocs\u002F\n├── orders\u002F           # 오늘 할일 (yyyymmdd.md)\n├── plans\u002F            # 수행 계획서, 구현 계획서\n│   └── archives\u002F     # 완료된 계획서 보관\n├── working\u002F          # 단계별 완료 보고서\n├── report\u002F           # 최종 보고서\n├── feedback\u002F         # 코드 리뷰 피드백\n├── tech\u002F             # 기술 사항 정리 문서\n├── manual\u002F           # 매뉴얼, 가이드 문서\n├── troubleshootings\u002F # 트러블슈팅 관련 문서\n└── pr\u002F               # 외부 기여자 PR 검토 기록\n```\n\n폴더별 역할, 파일명 규칙(`task_{milestone}_{issue}.md` 등), 외부 PR 정책은 [`document_structure_guide.md`](mydocs\u002Fmanual\u002Fdocument_structure_guide.md)를 참고하세요.\n\n## Architecture\n\n```mermaid\ngraph TB\n    HWP[HWP\u002FHWPX File] --> Open[Open panel \u002F Finder open \u002F Drag and drop]\n    Open --> Store[DocumentViewerStore]\n    Store --> WebView[WKWebView]\n    WebView --> Studio[bundled rhwp-studio]\n    Studio --> WebCore[edwardkim\u002Frhwp Web\u002FWASM]\n    Store -. native target .-> NativeViewer[Native macOS shell \u002F Swift overlay]\n    WebView --> HostBridge[WKUserScript + message handler]\n    HostBridge --> Save[HWP save \u002F Save As]\n    HostBridge --> Share[macOS share sheet]\n    HostBridge --> Print[AppKit print]\n    HostBridge --> PDF[PDF export]\n    Store --> Reveal[Finder reveal \u002F Recent documents]\n    HWP --> Preview[Quick Look Preview]\n    HWP --> Thumbnail[Finder Thumbnail]\n    PDF --> Shared[Shared preview\u002FPDF renderer]\n    Preview --> Shared\n    Thumbnail --> Shared\n    NativeViewer --> Shared\n    Shared --> Doc[RhwpDocument]\n    Doc --> Bridge[RhwpCoreBridge]\n    Bridge --> XC[Rhwp.xcframework \u002F Rhwp C ABI]\n    XC --> RustBridge[RustBridge]\n    RustBridge --> Core[edwardkim\u002Frhwp git dependency]\n    Core --> Data[Render Tree JSON \u002F Image Data]\n    Data --> Bridge\n    Bridge --> CG[CoreGraphics \u002F CoreText Renderer]\n    Core --> Skia[Rust\u002Frhwp Skia Renderer]\n    Skia -. long-term HostApp path .-> NativeViewer\n```\n\n## Contributing\n\n기여 환영합니다. 다음 핵심 사항을 먼저 확인해 주세요:\n- PR base는 작업 범위에 따라 다릅니다. 첫 공개 배포, WKWebView-backed viewer\u002Feditor, Finder\u002FQuick Look, PDF\u002F공유\u002F저장, Mac 통합\u002F변환, 배포, 문서, Skia 공통 기반 작업은 `devel`로 보내고, HostApp native macOS shell과 Swift overlay 관련 기여는 `native-viewer-editor`로 보냅니다. `main`은 릴리즈 브랜치입니다.\n- 이슈 먼저 확인: 동일 영역에 진행 중인 작업이 있는지 [열린 이슈](https:\u002F\u002Fgithub.com\u002Fpostmelee\u002Falhangeul-macos\u002Fissues) 와 [열린 PR](https:\u002F\u002Fgithub.com\u002Fpostmelee\u002Falhangeul-macos\u002Fpulls) 을 먼저 확인해 주세요. 중복 작업을 방지합니다.\n- 이슈 close 는 메인테이너: 작업 완료 후 PR 만 제출해 주세요. 이슈는 PR 머지 시 메인테이너가 close 합니다.\n\n상세한 기여 절차 (Fork → 브랜치 → 커밋 → PR) 는 [CONTRIBUTING.md](CONTRIBUTING.md) 를, 브랜치 전략의 판단 근거는 [WKWebView\u002Fnative 브랜치 전략](mydocs\u002Ftech\u002Fbranch_strategy_webview_native.md)을 참고하세요.\n\n## Notice\n\n본 제품은 한글과컴퓨터의 한글 문서 파일(`.hwp`, `.hwpx`) 공개 문서를 참고하여 개발하였습니다.\n\n## Trademark\n\n\"한글\", \"한컴\", \"HWP\", \"HWPX\"는 주식회사 한글과컴퓨터의 등록 상표입니다. 본 프로젝트는 한글과컴퓨터와 제휴, 후원, 승인 관계가 없는 독립적인 오픈소스 프로젝트입니다.\n\n\"Hangul\", \"Hancom\", \"HWP\", and \"HWPX\" are registered trademarks of Hancom Inc. This project is an independent open-source project with no affiliation, sponsorship, or endorsement by Hancom Inc.\n\n## License\n\nAlhangeul macOS 저장소 자체 코드는 [MIT License](LICENSE)로 배포되며, 주 저작권자는 Taegyu Lee입니다.\n\nBundled `rhwp`, `rhwp-studio`, Sparkle, WOFF2 fonts, 앱 아이콘\u002F로고 원본 provenance는 [THIRD_PARTY_LICENSES.md](THIRD_PARTY_LICENSES.md)를 확인하세요. Core\u002Fversion provenance와 Rust bridge reference artifact metadata는 [rhwp-core.lock](rhwp-core.lock)에, bundled `rhwp-studio` provenance는 [rhwp-studio manifest](Sources\u002FHostApp\u002FResources\u002Frhwp-studio\u002Fmanifest.json)에, font 목록과 license는 [FONTS.md](Sources\u002FHostApp\u002FResources\u002Frhwp-studio\u002Ffonts\u002FFONTS.md)에 기록합니다.\n","Alhangeul是一款为macOS设计的开源HWP\u002FHWPX文件处理工具，支持预览、打开、保存、分享及导出PDF等功能。它通过将基于Rust的`rhwp`核心与macOS应用、Quick Look预览、Finder缩略图以及Swift桥接相结合，提供了一种无需上传文件即可在本地操作文档的方式。此项目特别适合需要在Mac上处理韩文文档（.hwp\u002F.hwpx）的用户，无论是简单的查看还是复杂的编辑需求都能得到满足。此外，Alhangeul致力于为用户提供原生体验的同时保持跨平台兼容性，使得封闭格式的HWP\u002FHWPX文件能够在更广泛的环境中被访问和使用。","2026-06-11 03:56:07","CREATED_QUERY"]