rhwp

---

HWP/HWPX 파일과 지원되는 HML 문서를 어디서든 열어보세요. 무료, 설치 없이.

rhwp는 Rust + WebAssembly 기반의 오픈소스 HWP/HWPX 뷰어/에디터입니다. 닫힌 포맷의 벽을 깨고, 모든 사람, 모든 AI, 모든 플랫폼에서 한글 문서를 자유롭게 읽고 쓸 수 있게 합니다.

온라인 데모 | VS Code 확장 | Open VSX

0.9.0과 PDF 개발자 안내

PDF를 편집 가능한 HWP/HWPX로 가져오는 기능을 CLI·Rust·WASM·Studio에서 제공합니다. JBIG2·JPEG 2000·ICC, 암호 인증, 자원 프로필과 취소 가능한 쪽별 진행률이 포함됩니다. PDF 시작 안내에서 빌드부터 첫 변환·Worker 통합까지 따라 할 수 있습니다. 0.9.0 릴리즈 노트에 변경과 기여자를 정리했습니다. 0.9.0부터 crates.io 배포를 시작합니다. Rust 라이브러리와 Cargo 설치 CLI가 주 대상이며, 게시 후에는 rhwp = "0.9.0" 또는 cargo install rhwp --version 0.9.0 --locked --bin rhwp로 사용할 수 있습니다. Rust API·feature·CLI 설치 안내를 참고하세요. PNG·PDF 출력·Sixel·Kitty에는 --features native-skia를 추가합니다.

로드맵

혼자 뼈대를 세우고, 함께 살을 붙이고, 모두의 것으로 완성한다.

현재는 v0.9.0 — v1.0 조판 엔진 체계화를 중심으로 작업하면서, 40명이 넘는 외부 기여자와 두 명의 공동 유지보수자(콜레보레이터)가 참여하는 v2.0 협업 기반도 함께 발전시키고 있습니다. 버전별 목표와 완료 기준, 함께 진행되는 작업, AI 활용 세부 로드맵의 위치는 프로젝트 로드맵에서 설명합니다. rhwp 업스트림에 기여할 기능과 별도 다운스트림 프로젝트에서 구현할 제품의 경계도 같은 문서에서 확인할 수 있습니다.

현재 이정표

v0.5.0 ~ v0.8.x — 뼈대 (현재)

역공학 완성, 읽기/쓰기 기반 구축

• HWP 5.0 / HWPX 파서, 문단·표·수식·이미지·차트 렌더링
• HML(HWPML 2.9/2.91) 가져오기: 본문·서식·표·사각형 글상자·지원 수식, loss-safe HML/HWP/HWPX 저장
• 페이지네이션 (다단 분할, 표 행 분할), 머리말/꼬리말/바탕쪽/각주
• SVG/PNG/PDF 내보내기 (CLI) + Canvas/CanvasKit 렌더링 (WASM/Web)
• 웹 에디터 + hwpctl 호환 API (30 Actions, Field API)
• 3,400+ Rust 테스트 + studio 단위/e2e/시각 회귀 CI

HML은 실제 corpus로 확인된 HWPML 2.9/2.91 구조만 제한 지원합니다. 지원 범위의 수식은 가져와 편집할 수 있고, 보존 불가 요소가 없는 HML 원본은 preflight 검사 후 HML로 다시 저장할 수 있습니다. 그림·내장/외부 리소스 등 미지원 요소는 경고하고 손실 저장을 차단합니다.

릴리즈 이력

사이클별 상세 변경 사항(기여자 목록 포함)은 CHANGELOG.md에 기록합니다.

Features

Parsing (파싱)

• HWP 5.0 binary format (OLE2 Compound File)
• HWPX (Open XML-based format)
• HML (HWPML 2.9/2.91) — 검증된 구조 제한 지원
• Sections, paragraphs, tables, textboxes, images, equations, charts
• Header/footer, master pages, footnotes/endnotes

Rendering (렌더링)

• 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

Equation (수식)

• 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

Pagination (페이지 분할)

• Multi-column document column/page splitting
• Table row-level page splitting (PartialTable)
• shape_reserved handling for TopAndBottom objects
• vpos-based paragraph position correction

Output (출력)

• SVG export (CLI, legacy + layer replay)
• PNG export (native Skia, --features native-skia)
• PDF export: SVG compatibility 기본(--text-as-paths 지원, 바이트 재현성), native Skia direct opt-in(--features native-skia, --backend direct)
• Canvas rendering (WASM/Web) + 명시 opt-in 문서 단위 Canvas2D/CanvasKit 자동 선택
• 저장: HWP 편집 저장, HWPX/HML 의미 보존 저장, HWPX → HWP 변환 경로
• Debug overlay (paragraph/table boundaries + indices + y-coordinates)

Multi-Renderer Backends (멀티 렌더러 백엔드)

• 공통 paint IR: PageRenderTree → PageLayerTree (Rust DocumentCore::build_page_layer_tree, WASM getPageLayerTree) — schemaVersion: 1, 호환 변경은 additive 원칙
• 백엔드: legacy/layered SVG, Canvas2D, CanvasKit 직접 replay, native Skia PNG/direct PDF(--features native-skia)
• Studio, 브라우저 확장/embed, VS Code 뷰어의 기본 요청은 호환 경로인 Canvas2D입니다. Studio 계열에서 ?renderer=auto를 명시하면 bounded document preflight가 완전하고 적격이며 필요한 문서 폰트를 준비할 수 있는 경우만 CanvasKit으로 고정합니다. 표준 선·도형 점선과 수평 글자 겹침, 탭 리더, 밑줄·취소선·강조점, 위치가 확정된 공백·탭·문단 끝·줄바꿈 부호, nominal glyph replay가 안전한 일반 TextRun의 세로쓰기·장평·음영·그림자·외곽선·양각·음각은 CanvasKit이 직접 재생합니다. 방향과 cluster advance 권한이 아직 없는 복합 shaping 문자, 옛한글·boxed-PUA와 장평 또는 paint effect의 조합, 세로·회전된 특수 시각 op, [표], [그림] 같은 구조 조판 부호를 포함하는 showControlCodes, 판정·초기화·리소스 준비·런타임 실패는 해당 문서 revision 전체를 Canvas2D로 고정합니다. ?renderer=canvas2d와 ?renderer=canvaskit은 명시적 강제 선택입니다.
• Text IR v2: 폰트 blob 증명 기반 GlyphRun/GlyphOutline 사이드카 — 검증된 수평 nominal GlyphRun은 CanvasKit direct replay, 나머지는 TextRun 폴백 (호환 계약)
• direct PDF는 print profile과 CSS px→PDF point 72/96 변환을 사용합니다. 손실되는 gradient/pattern/shadow/connector/image adjustment는 SVG backend 사용을 안내하며 실패하고, Raw SVG만 --raster-dpi 기반 bounded raster fallback을 사용합니다.
• 시각 회귀 CI: render-diff(Canvas 계열 + browser/compatibility PDF report), selected direct/compatibility PDF 2% hard gate, 4-backend 공통 replay-plane(배경→글뒤→본문→글앞) 계약

Web Editor (웹 에디터)

• Text editing (insert, delete, undo/redo)
• Character/paragraph formatting dialogs
• Table creation, row/column insert/delete, cell formula
• hwpctl-compatible API layer (한컴 웹기안기 호환)

hwpctl Compatibility (한컴 호환 레이어)

• 30 Actions: TableCreate, InsertText, CharShape, ParagraphShape, etc.
• ParameterSet/ParameterArray API
• Field API: GetFieldList, PutFieldText, GetFieldText
• Template data binding support

npm 패키지 — 웹에서 바로 사용하기

에디터 임베드 (3줄)

웹 페이지에 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>

HWP 뷰어/파서 (직접 API 호출)

WASM 기반 파서/렌더러를 직접 사용하여 HWP 파일을 SVG로 렌더링합니다.

npm install @rhwp/core

This is the beginning of the README. Read the rest at the original. Read the full README ↗