알(R), 모두의 한글 — 알에서 시작하다
All HWP, Open for Everyone
한국어 | English
HWP 파일을 어디서든 열어보세요. 무료, 설치 없이.
rhwp는 Rust + WebAssembly 기반의 오픈소스 HWP/HWPX 뷰어/에디터입니다. 닫힌 포맷의 벽을 깨고, 모든 사람, 모든 AI, 모든 플랫폼에서 한글 문서를 자유롭게 읽고 쓸 수 있게 합니다.
온라인 데모 | VS Code 확장 | Open VSX
혼자 뼈대를 세우고, 함께 살을 붙이고, 모두의 것으로 완성한다.
0.5 ──── 1.0 ──── 2.0 ──── 3.0
뼈대 조판 협업 완성
| 단계 | 방향 | 전략 |
|---|---|---|
| 0.5 → 1.0 | 읽기/쓰기 기반 위에 조판 엔진 체계화 | 핵심 아키텍처를 혼자 견고하게 |
| 1.0 → 2.0 | AI 조판 파이프라인 위에 커뮤니티 참여 개방 | 기여 진입 장벽을 낮추는 구조 |
| 2.0 → 3.0 | 커뮤니티가 채운 기능 위에 공공 자산화 | 한컴 대등 수준 달성 |
0.5.0까지 혼자 뼈대를 완성하고 공개하는 이유 — 커뮤니티가 붙었을 때 방향이 흔들리지 않으려면 핵심 아키텍처가 먼저 견고해야 합니다.
역공학 완성, 읽기/쓰기 기반 구축
- HWP 5.0 / HWPX 파서, 문단·표·수식·이미지·차트 렌더링
- 페이지네이션 (다단 분할, 표 행 분할), 머리말/꼬리말/바탕쪽/각주
- SVG 내보내기 (CLI) + Canvas 렌더링 (WASM/Web)
- 웹 에디터 + hwpctl 호환 API (30 Actions, Field API)
- 783+ 테스트
AI 조판 파이프라인, 뼈대 완성
- 편집 시 동적 재조판 체계화 (LINE_SEG 재계산 + 페이지네이션 연동)
- AI 기반 문서 생성/편집 파이프라인
- 문서 조판 품질 한컴 뷰어 수준 도달
커뮤니티가 기능을 채워가는 단계, 살 붙이기
- 플러그인/확장 아키텍처, 실시간 협업 편집
- 다양한 출력 포맷 (PDF, DOCX 등)
한컴과 대등한 수준, 완전한 공공 자산
- 전체 HWP 기능 커버리지, 접근성(a11y), 모바일 대응
- 공공기관 실무 투입 가능 수준
자세한 내용은 로드맵 문서를 참조하세요.
- HWP 5.0 binary format (OLE2 Compound File)
- HWPX (Open XML-based format)
- Sections, paragraphs, tables, textboxes, images, equations, charts
- Header/footer, master pages, footnotes/endnotes
- Paragraph layout: line spacing, indentation, alignment, tab stops
- Tables: cell merging, border styles (solid/double/triple/dotted), cell formula calculation
- Multi-column layout (2-column, 3-column, etc.)
- Paragraph numbering/bullets
- Vertical text (영문 눕힘/세움)
- Header/footer (odd/even page separation)
- Master pages (Both/Odd/Even, is_extension/overlap)
- Object placement: TopAndBottom, treat-as-char (TAC), in-front-of/behind text
- Fractions (OVER), square roots (SQRT/ROOT), subscript/superscript
- Matrices: MATRIX, PMATRIX, BMATRIX, DMATRIX
- Cases, alignment (EQALIGN), stacking (PILE/LPILE/RPILE)
- Large operators: INT, DINT, TINT, OINT, SUM, PROD
- Relations (REL/BUILDREL), limits (lim), long division (LONGDIV)
- 15 text decorations, full Greek alphabet, 100+ math symbols
- Multi-column document column/page splitting
- Table row-level page splitting (PartialTable)
- shape_reserved handling for TopAndBottom objects
- vpos-based paragraph position correction
- SVG export (CLI)
- Canvas rendering (WASM/Web)
- Debug overlay (paragraph/table boundaries + indices + y-coordinates)
- Text editing (insert, delete, undo/redo)
- Character/paragraph formatting dialogs
- Table creation, row/column insert/delete, cell formula
- hwpctl-compatible API layer (한컴 웹기안기 호환)
- 30 Actions: TableCreate, InsertText, CharShape, ParagraphShape, etc.
- ParameterSet/ParameterArray API
- Field API: GetFieldList, PutFieldText, GetFieldText
- Template data binding support
웹 페이지에 HWP 에디터를 통째로 임베드합니다. 메뉴, 툴바, 서식, 표 편집 — 모든 기능을 그대로 사용할 수 있습니다.
npm install @rhwp/editor<div id="editor" style="width:100%; height:100vh;"></div>
<script type="module">
import { createEditor } from '@rhwp/editor';
const editor = await createEditor('#editor');
</script>WASM 기반 파서/렌더러를 직접 사용하여 HWP 파일을 SVG로 렌더링합니다.
npm install @rhwp/coreimport init, { HwpDocument } from '@rhwp/core';
globalThis.measureTextWidth = (font, text) => {
const ctx = document.createElement('canvas').getContext('2d');
ctx.font = font;
return ctx.measureText(text).width;
};
await init({ module_or_path: '/rhwp_bg.wasm' });
const resp = await fetch('document.hwp');
const doc = new HwpDocument(new Uint8Array(await resp.arrayBuffer()));
document.getElementById('viewer').innerHTML = doc.renderPageSvg(0);| 패키지 | 용도 | 설치 |
|---|---|---|
| @rhwp/editor | 완전한 에디터 UI (iframe) | npm i @rhwp/editor |
| @rhwp/core | WASM 파서/렌더러 (API) | npm i @rhwp/core |
처음 프로젝트에 참여하는 개발자는 온보딩 가이드를 먼저 읽어보세요. 프로젝트 아키텍처, 디버깅 도구, 개발 워크플로우를 한눈에 파악할 수 있습니다.
- Rust 1.75+
- Docker (for WASM build)
- Node.js 18+ (for web editor)
cargo build # Development build
cargo build --release # Release build
cargo test # Run tests (755+ tests)WASM 빌드는 Docker를 사용합니다. 플랫폼에 관계없이 동일한 wasm-pack + Rust 툴체인 환경을 보장하기 위함입니다.
cp .env.docker.example .env.docker # 최초 1회: 환경변수 템플릿 복사
docker compose --env-file .env.docker run --rm wasm빌드 결과물은 pkg/ 디렉토리에 생성됩니다.
cd rhwp-studio
npm install
npx vite --host 0.0.0.0 --port 7700Open http://localhost:7700 in your browser.
rhwp export-svg sample.hwp # Export to output/
rhwp export-svg sample.hwp -o my_dir/ # Export to custom directory
rhwp export-svg sample.hwp -p 0 # Export specific page (0-indexed)
rhwp export-svg sample.hwp --debug-overlay # Debug overlay (paragraph/table boundaries)rhwp dump sample.hwp # Full IR dump
rhwp dump sample.hwp -s 2 -p 45 # Section 2, paragraph 45 only
rhwp dump-pages sample.hwp -p 15 # Page 16 layout items
rhwp info sample.hwp # File info (size, version, sections, fonts)export-svg --debug-overlay→ Identify paragraphs/tables bys{section}:pi={index} y={coord}dump-pages -p N→ Check paragraph layout list and heightsdump -s N -p M→ Inspect ParaShape, LINE_SEG, table properties
No code modification needed for the entire debugging process.
src/
├── main.rs # CLI entry point
├── parser/ # HWP/HWPX file parser
├── model/ # HWP document model
├── document_core/ # Document core (CQRS: commands + queries)
│ ├── commands/ # Edit commands (text, formatting, tables)
│ ├── queries/ # Queries (rendering data, pagination)
│ └── table_calc/ # Table formula engine (SUM, AVG, PRODUCT, etc.)
├── renderer/ # Rendering engine
│ ├── layout/ # Layout (paragraph, table, shapes, cells)
│ ├── pagination/ # Pagination engine
│ ├── equation/ # Equation parser/layout/renderer
│ ├── svg.rs # SVG output
│ └── web_canvas.rs # Canvas output
├── serializer/ # HWP file serializer (save)
└── wasm_api.rs # WASM bindings
rhwp-studio/ # Web editor (TypeScript + Vite)
├── src/
│ ├── core/ # Core (WASM bridge, types)
│ ├── engine/ # Input handlers
│ ├── hwpctl/ # hwpctl compatibility layer
│ ├── ui/ # UI (menus, toolbars, dialogs)
│ └── view/ # Views (ruler, status bar, canvas)
├── e2e/ # E2E tests (Puppeteer + Chrome CDP)
│ └── helpers.mjs # Test helpers (headless/host modes)
mydocs/ # Project documentation (Korean)
├── orders/ # Daily task tracking
├── plans/ # Task plans and implementation specs
├── feedback/ # Code review feedback
├── tech/ # Technical documents
└── manual/ # Manuals and guides
scripts/ # Build & quality tools
├── metrics.sh # Code quality metrics collection
└── dashboard.html # Quality dashboard with trend tracking
이것은 바이브 코딩이 아닙니다. AI가 주는 코드를 읽지도 않고 수락하는 것이 아닙니다. 모든 계획은 검토되고, 모든 결과물은 검증되며, 모든 결정의 뒤에는 사람이 있습니다.
바이브 코딩 — AI 출력을 읽지 않고 수락하고, AI에게 아키텍처 결정을 맡기고, 이해하지 못하는 코드를 배포하는 것 — 은 함정입니다. 겉보기에는 동작하지만, 이해하지 못했기 때문에 문제가 생겨도 진단할 수 없는 코드가 만들어집니다.
이 프로젝트는 정반대의 접근을 취합니다. 사람 작업지시자가 방향, 품질, 아키텍처 결정의 완전한 소유권을 유지하고, AI는 혼자서는 불가능한 속도와 규모로 구현을 수행합니다. 핵심 차이: 사람은 절대 생각을 멈추지 않습니다.
| 바이브 코딩 | 이 프로젝트 | |
|---|---|---|
| 사람의 역할 | AI 출력 수락 | 지시, 검토, 결정 |
| 계획 | 없음 — "그냥 만들어" | 계획서 작성 → 승인 → 실행 |
| 품질 관문 | 동작하길 바람 | 783 테스트 + Clippy + CI + 코드 리뷰 |
| 디버깅 | AI에게 AI 버그 수정 요청 | 사람이 진단, AI가 구현 |
| 아키텍처 | 우연히 형성 | 의도적 설계 (CQRS, 의존성 방향) |
| 문서 | 없음 | 724개 파일의 프로세스 기록 |
| 결과물 | 취약, 유지보수 어려움 | 프로덕션 수준, 100K+ 라인 |
AI는 배율기입니다. 하지만 배율기는 기존 프로세스를 증폭시킵니다. 프로세스 없음 × AI = 빠른 혼돈. 좋은 프로세스 × AI = 비범한 결과물.
이 프로젝트는 Claude Code (Anthropic AI 코딩 에이전트)를 페어 프로그래밍 파트너로 사용하여 개발합니다. 전체 개발 과정이 투명하게 문서화되어 있습니다.
작업지시자 (사람) AI 페어 프로그래머 (Claude Code)
──────────────── ─────────────────────────────
방향 설정, 우선순위 결정 → 분석, 계획, 구현
계획 검토, 승인 ← 구현 계획서 작성
도메인 피드백 제공 → 디버깅, 테스트, 반복
아키텍처 결정 → 정밀하게 실행
품질 및 정확성 판단 ← 코드, 문서, 테스트 생성
mydocs/ 디렉토리(724개 파일, 영문 번역: mydocs/eng/)에 전체 개발 기록이 있습니다: 일일 작업 기록, 구현 계획서, 코드 리뷰 피드백, 기술 연구 문서, 트러블슈팅 기록.
mydocs/는 코드에 대한 문서가 아닙니다 — AI로 소프트웨어를 만드는 방법에 대한 문서입니다. 오픈소스 방법론입니다.
Hyper-Waterfall 방법론 — 거시적 워터폴 + 미시적 애자일, AI가 이 둘을 동시에 가능하게 한다.
local/task{N} ──커밋──커밋──┐
├─→ devel merge (관련 타스크 묶어서)
├─→ main merge + 태그 (릴리즈 시점)
| 브랜치 | 용도 |
|---|---|
main |
릴리즈 (태그: v0.5.0 등) |
devel |
개발 통합 |
local/task{N} |
GitHub Issue 번호 기반 타스크 브랜치 |
- GitHub Issues로 타스크 번호 자동 채번 — 중복 방지
- GitHub Milestones로 타스크 그룹화
- 마일스톤 표기:
M{버전}(예: M100=v1.0.0, M05x=v0.5.x) - 오늘할일:
mydocs/orders/yyyymmdd.md—M100 #1형식으로 참조 - 커밋 메시지:
Task #1: 내용—closes #1로 Issue 자동 종료
gh issue create→ GitHub Issue 등록 (마일스톤 지정)local/task{issue번호}브랜치 생성- 수행계획서 작성 → 승인 → 구현 → 테스트
- devel merge →
closes #{번호}
export-svg --debug-overlay→ 문단/표 식별dump-pages -p N→ 배치 목록과 높이dump -s N -p M→ ParaShape, LINE_SEG 상세
mydocs/의 문서는 AI 기반 소프트웨어 개발의 교육 자료로 활용됩니다.
모든 문서는 한국어로 작성합니다.
mydocs/
├── orders/ # 오늘 할일 (yyyymmdd.md)
├── plans/ # 수행 계획서, 구현 계획서
│ └── archives/ # 완료된 계획서 보관
├── working/ # 단계별 완료 보고서
├── report/ # 기본 보고서
├── feedback/ # 코드 리뷰 피드백
├── tech/ # 기술 사항 정리 문서
├── manual/ # 매뉴얼, 가이드 문서
└── troubleshootings/ # 트러블슈팅 관련 문서
| 문서 유형 | 위치 | 파일명 규칙 |
|---|---|---|
| 오늘 할일 | orders/ |
yyyymmdd.md — 마일스톤(M100)+Issue(#1) 형식 |
| 수행 계획서 | plans/ |
Issue 번호 참조 |
| 완료 보고서 | working/ |
Issue 번호 참조 |
| 기술 문서 | tech/ |
주제별 자유 명명 |
graph TB
HWP[HWP/HWPX File] --> Parser
Parser --> Model[Document Model]
Model --> DocumentCore
DocumentCore --> |Commands| Edit[Edit Operations]
DocumentCore --> |Queries| Render[Rendering Pipeline]
Render --> Pagination
Pagination --> Layout
Layout --> SVG[SVG Output]
Layout --> Canvas[Canvas Output]
DocumentCore --> WASM[WASM API]
WASM --> Studio[rhwp-studio Web Editor]
Studio --> hwpctl[hwpctl Compatibility Layer]
- 1 inch = 7,200 HWPUNIT
- 1 inch = 25.4 mm
- 1 HWPUNIT ≈ 0.00353 mm
See CONTRIBUTING.md for guidelines.
본 제품은 한글과컴퓨터의 한글 문서 파일(.hwp) 공개 문서를 참고하여 개발하였습니다.
"한글", "한컴", "HWP", "HWPX"는 주식회사 한글과컴퓨터의 등록 상표입니다. 본 프로젝트는 한글과컴퓨터와 제휴, 후원, 승인 관계가 없는 독립적인 오픈소스 프로젝트입니다.
"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.
MIT License — Copyright (c) 2025-2026 Edward Kim