python-hwpx 3.6.0__tar.gz → 3.8.0__tar.gz

{python_hwpx-3.6.0 → python_hwpx-3.8.0}/NOTICE

@@ -29,10 +29,22 @@ reimplemented from public references, without copying source code:
   from public model headers only. hwpxlib sample packages were used only as
   structure and roundtrip fixtures.
 
-These form-fill references were used as behavior evidence only. The
+- OpenBapul/hml-equation-parser (Apache-2.0): HULK-style EqEdit <-> LaTeX token
+  mapping, referenced for reader-direction <hp:equation> script rendering. The
+  token maps are a clean-room re-derivation from the public EqEdit grammar; no
+  source code was copied, translated, or vendored.
+
+These form-fill and equation references were used as behavior evidence only. The
 implementation is a clean-room Python implementation; no source code was
 copied, translated, vendored, or linked.
 
+## Optional dependency: latex2mathml
+
+The optional ``preview`` extra depends on roniemartinez/latex2mathml (MIT), used
+to convert LaTeX to MathML for the document preview viewer. It is an unmodified
+third-party dependency installed via pip; its MIT license travels with the
+package.
+
 ## Test fixtures: hwpxlib sample corpus
 
 tests/fixtures/hwpxlib_corpus/ contains .hwpx sample files vendored from

{python_hwpx-3.6.0/src/python_hwpx.egg-info → python_hwpx-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 3.6.0
+Version: 3.8.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0
@@ -27,10 +27,13 @@ Requires-Dist: pillow>=10.0; extra == "visual"
 Requires-Dist: numpy>=1.26; extra == "visual"
 Provides-Extra: xlsx
 Requires-Dist: openpyxl>=3.1; extra == "xlsx"
+Provides-Extra: preview
+Requires-Dist: latex2mathml>=3.77; extra == "preview"
 Provides-Extra: dev
 Requires-Dist: build>=1.0; extra == "dev"
 Requires-Dist: twine>=4.0; extra == "dev"
 Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: latex2mathml>=3.77; extra == "dev"
 Provides-Extra: test
 Requires-Dist: build>=1.0; extra == "test"
 Requires-Dist: numpy>=1.26; extra == "test"
@@ -38,6 +41,7 @@ Requires-Dist: pillow>=10.0; extra == "test"
 Requires-Dist: pytest>=7.4; extra == "test"
 Requires-Dist: pytest-cov>=5.0; extra == "test"
 Requires-Dist: ruff>=0.12; extra == "test"
+Requires-Dist: latex2mathml>=3.77; extra == "test"
 Provides-Extra: typecheck
 Requires-Dist: mypy>=1.10; extra == "typecheck"
 Requires-Dist: pyright>=1.1.390; extra == "typecheck"
@@ -46,16 +50,35 @@ Dynamic: license-file
 <p align="center">
   <h1 align="center">python-hwpx</h1>
   <p align="center">
-    <strong>한글 없이 HWPX 문서를 Python으로 읽고, 편집하고, 생성하고, 구조를 검증합니다.</strong>
+    <strong>한컴 없이 HWPX를 안전하게 자동화하는 Python 계층 — 최소 범위 편집, 검증된 저작, 모든 쓰기에 영수증.</strong>
   </p>
   <p align="center">
     <a href="https://pypi.org/project/python-hwpx/"><img src="https://img.shields.io/pypi/v/python-hwpx?color=blue&label=PyPI" alt="PyPI"></a>
     <a href="https://pypi.org/project/python-hwpx/"><img src="https://img.shields.io/pypi/pyversions/python-hwpx" alt="Python"></a>
     <a href="https://github.com/airmang/python-hwpx/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"></a>
     <a href="https://airmang.github.io/python-hwpx/"><img src="https://img.shields.io/badge/docs-Sphinx-8CA1AF" alt="Docs"></a>
+    <a href="https://github.com/airmang/python-hwpx/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/airmang/python-hwpx/tests.yml?branch=main&label=tests" alt="Tests"></a>
+    <a href="https://airmang.github.io/python-hwpx/corpus-metrics.html"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fairmang.github.io%2Fpython-hwpx%2F_static%2Fbadge-hancom-open.json" alt="Hancom open"></a>
   </p>
 </p>
 
+<p align="center">한국어 | <a href="README_EN.md">English</a></p>
+
+---
+
+> **python-hwpx는 한컴 없이 HWPX를 안전하게 자동화하는 Python 계층입니다.** 기존
+> 문서는 최소 범위만 수정하고, 새 문서는 실제 한컴 수용이 검증된 형태로 생성하며,
+> 모든 쓰기에 변경·보존·검증 영수증을 남기고, 완전한 해석과 렌더링은 전문 백엔드에
+> 위임할 수 있습니다.
+
+- **최소 범위 편집** — 미수정 part는 저장 시 바이트 그대로 유지됩니다(patch 경로
+  바이트 보존 497/497, 동결 코퍼스 v2 · 2026-07-19).
+- **검증된 저작** — 밑바닥 생성도 실제 한컴이 받아들이는 형태로 냅니다(산출물 한컴
+  오픈 476/476 all-pass, 실저작 품질 게이트 58/58).
+- **모든 쓰기에 영수증** — 대표 저장 경로는 [Safe Write Contract](docs/safe-write-contract.md)의
+  `MutationReport`(`hwpx.mutation-report/v1`)로 실제 쓰기 모드·보존 등급·검증 결과를
+  **측정해** 반환합니다.
+
 ---
 
 ## 🧩 HWPX Stack (3종)
@@ -66,11 +89,10 @@ Dynamic: license-file
 | 🔌 MCP 서버 | [`hwpx-mcp-server`](https://github.com/airmang/hwpx-mcp-server) | MCP 클라이언트(Claude Desktop, VS Code 등)에서 HWPX 조작 |
 | 🎯 에이전트 스킬 | [`hwpx-plugin`](https://github.com/airmang/hwpx-plugins) | 에이전트가 HWPX를 바로 쓰게 해주는 first-party 플러그인·스킬 번들 |
 
-`python-hwpx`는 HWPX 파싱·편집·생성을 제공하는 코어 라이브러리이며,
-`hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동 구성요소입니다.
-“first-party”는 프로젝트 유지보수 관계를 뜻하며, 한컴 또는 제3자의 공식 인증을 뜻하지 않습니다.
+`hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동
+구성요소입니다(유지보수 관계를 뜻하며, 한컴 등 외부 기관의 인증을 뜻하지 않습니다).
 
-현재 PyPI 공개 릴리스는 `python-hwpx 3.6.0`입니다. 일반
+현재 PyPI 공개 릴리스는 `python-hwpx 3.8.0`입니다. 일반
 `pip install python-hwpx`로 이 릴리스를 설치할 수 있습니다.
 현재 패키지 분류는 `Development Status :: 3 - Alpha`입니다. 이 분류는 API와 제품의
 성숙도를 나타내며, 공개 버전이나 플러그인의 최소 호환 버전을 대신하지 않습니다.
@@ -80,13 +102,22 @@ Dynamic: license-file
 ## 실측으로 말합니다 — Published Corpus
 
 이 스택의 산출물은 주장 대신 **실제 한컴오피스 전수 측정**으로 검증됩니다
-(동결 코퍼스 N=497, 2026-07-19, 상세·주의사항은
+(동결 코퍼스 v2, N=497 산출물, 2026-07-19, 실한컴 12.0.0.3288 COM/GUI 오라클;
+상세·주의사항은
 [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html)):
 
-- **한컴 오픈 수용률 100%** (476/476 all-pass, 하한 ≥99.4%) · 파싱 96.2%
-- **미수정 영역 바이트 보존 100%** (497/497, patch 경로) · **개인정보 0-leak**
-- 렌더 검증 416건 + 정직 버킷(변경추적 문서의 PDF export는 한컴 자체가 거부 — 실측 한계로 발행)
-- 양식 채움 차등은 wild 공개 양식에서 49.2% — **낮은 숫자도 그대로 발행**하고 잔여 과제로 명기합니다
+- **한컴 오픈 수용률 476/476 all-pass** (동결 코퍼스 v2 · 2026-07-19 · 실한컴 COM
+  `Open()` 판정 · rule-of-three 하한 99.37%) · 파싱 96.2%(458/476)
+- **미수정 영역 바이트 보존 497/497** (patch 경로 한정, zip-part diff · 오라클 불요)
+  · **개인정보 0-leak** (35문서/합성 140값)
+- 렌더 검증 416/476 (실한컴 `SaveAs("PDF")`) + 정직 버킷 43건(변경추적 문서의 PDF
+  export는 한컴 자체가 거부 — 실측 한계로 발행) + 미검증 17건
+- wild 공개 양식 채움은 구조결함 픽스 후 **무음 서식파괴 16.7%**(판정 66조합, 못 담는 타깃은 typed 거부 35건·산출분 pass 17/28) — **낮은 숫자도 그대로 발행**하고 잔여(페이지 리플·표 shape)를 명명합니다
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/airmang/python-hwpx/main/docs/images/redline-hancom.png" alt="python-hwpx가 남긴 변경추적과 AI 에이전트 메모가 실제 한/글에서 열린 화면" width="720">
+</p>
+<p align="center"><sub>python-hwpx로 작성한 변경추적(취소선·삽입)과 AI 에이전트 메모 — 실제 한/글에서 연 화면입니다.</sub></p>
 
 > 이 숫자들은 *생성물 수용률* 축입니다(우리가 만든 파일을 실제 한컴이 받아들이는가).
 > 문서 *파싱 recall*과는 다른 축이므로 파서 프로젝트 수치와 병치 비교하지 마세요.
@@ -195,6 +226,59 @@ hwpx-analyze-template 보고서.hwpx
 
 > 전체 기능·클래스·메서드 목록은 [사용 가이드](docs/usage.md)와 [API 레퍼런스](https://airmang.github.io/python-hwpx/api_reference.html)를 참고하세요.
 
+## 안전한 쓰기 계약 (Safe Write Contract)
+
+대표 저장 경로(`save_to_path` · `save_to_stream` · `to_bytes`)는 **요청한 보존 등급을
+쓰기 전에 판정하고, 실제로 무엇을 바꿨는지 측정한 영수증**을 돌려줍니다.
+
+```python
+from hwpx.mutation_report import PreservationDowngradeError
+
+# 영수증과 함께 저장 — 달성 가능한 가장 강한 보존 등급 자동 선택(mode="auto" 기본)
+report = doc.save_to_path("결과.hwpx", return_report=True)
+print(report.actual_mode)                                   # "patch" | "rebuild"
+print(report.preservation.untouched_part_payloads.to_dict())  # {"verified": 17, "changed": 0}
+
+# patch 등급 강제 — 미달이면 아무것도 쓰지 않고 예외(fail-closed)
+try:
+    doc.save_to_path("결과.hwpx", mode="patch", fallback="error")
+except PreservationDowngradeError as exc:
+    print(exc.offending_parts, exc.suggestion)
+```
+
+- `mode="patch" | "rebuild" | "auto"`(기본 `auto`) · `fallback="error" | "rebuild"`(기본 `error`)
+- `mode="patch"` + `fallback="error"`에서 미수정 part의 바이트 동일성을 지킬 수 없으면
+  **아무것도 쓰지 않고** `PreservationDowngradeError`를 던집니다(무음 rebuild 없음).
+- `MutationReport`는 `requestedMode`/`actualMode`/`fallbackUsed`, 변경 part와 좌표 명시
+  범위, 보존 3층(part 페이로드·ZIP 레코드·전체 패키지), 검증 3항목(`passed`/`failed`/`not_performed`)을
+  **측정해** 반환합니다.
+
+> 파라미터 전체와 `MutationReport` 스키마는 [안전한 쓰기 계약 문서](docs/safe-write-contract.md)를 참고하세요.
+
+## 지원 매트릭스
+
+능력 영역별 실제 등급입니다(동결 코퍼스 v2 · 2026-07-19 · 실한컴 12.0.0.3288 오라클).
+등급 어휘: **Parse / Preserve / Edit / Create / Render-verified /
+Unsupported-but-preserved / Unsupported-and-rejected**.
+
+| 능력 영역 | 상태 | 증거 |
+|---|---|---|
+| 문단·표 저작/편집 | Parse·Preserve·Edit·Create·Render-verified | 오픈 476/476 · 실저작 게이트 58/58 · 렌더 416 |
+| 표 구조 변경(행·열·표, 오토핏) | Preserve·Edit | `hwpx.table_patch` · 바이트 보존 497/497 |
+| 양식 채움(byte-splice) | Preserve·Edit | `hwpx.patch`·`table_patch`·`body_patch` · 보존 497/497 (wild 무음 서식파괴 16.7%·typed 거부 35/66, 잔여 명명) |
+| 그림 삽입/치환 | Edit·Create | `add_picture`·`replace_picture` (복잡 개체는 한컴 확인 권장) |
+| 차트 | Unsupported-but-preserved | 생성 API 없음 · 기존 차트 part는 patch 보존 |
+| 수식 | Parse·Unsupported-but-preserved | 저작 API 없음 · 기존 수식 파싱·patch 보존 |
+| 변경추적(redline) | Edit·Create | `add_tracked_*` · 실한컴 `IsTrackChange=1` (한컴이 PDF export 거부 → `render_unavailable` 정직 집계) |
+| 메모(코멘트) | Edit·Create·Render-verified | `add_memo*` · 실 Windows 한컴 검증 |
+| 각주/미주 | Edit·Create | `add_footnote`·`add_endnote` (렌더 독립 게이트 미측정) |
+| 네이티브 목차/상호참조 | Create·Render-verified | `add_native_toc`·`toc_verify` · 구조 15/15 · 페이지 정합 5/5 |
+| 암호화 HWPX | Unsupported-and-rejected | 복호화 없음 · 암호화 part는 파싱 단계 예외로 거부 |
+| HWP 5.x 바이너리 | Unsupported-and-rejected | ZIP 아님 → 열기 시 `BadZipFile` (HWPX로 변환 후 사용) |
+| 누름틀(form field) 생성 | Parse·Edit | 기존 필드 조회·서식보존 채움 · **신규 누름틀 생성 도구는 미제공** |
+
+> 각 등급의 판정 근거와 상세 증거 포인터는 [지원 매트릭스 문서](docs/support-matrix.md)를 참고하세요.
+
 ## 대항 라이브러리 비교
 
 | | python-hwpx | pyhwpx | pyhwp |
@@ -219,6 +303,7 @@ hwpx-analyze-template 보고서.hwpx
 - **[🚀 빠른 시작](docs/quickstart.md)** · **[📚 사용 가이드](docs/usage.md)** — 첫 파일 열기부터 문단·표·메모·섹션 편집, 텍스트 추출·검증까지
 - **[💡 예제 모음](docs/examples.md)** · [`examples/`](examples/) — `build_release_checklist.py`(메모·스타일 편집 HWPX 생성), `extract_text.py`(CLI 텍스트 추출), `find_objects.py`(OWPML 노드 추적) 등
 - **[📐 스키마 개요](docs/schema-overview.md)** · **[🔧 설치 검증](docs/installation.md)**
+- **[🔬 HWPX 내부 실전 가이드](docs/internals/)** — 실제 한/글 동작에서 확인된 HWPUNIT·조판 캐시·목차 필드·OPC 재패킹·메모·오라클 한계
 - **[📖 전체 문서 (Sphinx)](https://airmang.github.io/python-hwpx/)** — API 레퍼런스·50+ 실전 패턴·FAQ
 - **[📝 CHANGELOG](CHANGELOG.md)** · **[🤝 CONTRIBUTING](CONTRIBUTING.md)** · **[👥 CONTRIBUTORS](CONTRIBUTORS.md)**
 
@@ -226,6 +311,11 @@ hwpx-analyze-template 보고서.hwpx
 
 버그 리포트, 기능 제안, PR 모두 환영합니다.
 
+- **[help wanted 이슈](https://github.com/airmang/python-hwpx/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)** — 지금 들어오기 좋은 입구입니다. 시작 전에 이슈에 코멘트로 방향을 남겨주세요.
+- **[마일스톤](https://github.com/airmang/python-hwpx/milestones)** — 공개 로드맵입니다. 프로젝트가 어디로 가는지 여기서 보입니다.
+- **[Discussions](https://github.com/airmang/python-hwpx/discussions)** — 질문·아이디어는 이슈 대신 여기로.
+- **[내부 실전 가이드](docs/internals/)** — HWPX 내부 구조가 처음이라면 여기부터. 개발 흐름은 [CONTRIBUTING.md](CONTRIBUTING.md)에 있습니다.
+
 ```bash
 git clone https://github.com/airmang/python-hwpx.git
 cd python-hwpx

{python_hwpx-3.6.0 → python_hwpx-3.8.0}/README.md

@@ -1,16 +1,35 @@
 <p align="center">
   <h1 align="center">python-hwpx</h1>
   <p align="center">
-    <strong>한글 없이 HWPX 문서를 Python으로 읽고, 편집하고, 생성하고, 구조를 검증합니다.</strong>
+    <strong>한컴 없이 HWPX를 안전하게 자동화하는 Python 계층 — 최소 범위 편집, 검증된 저작, 모든 쓰기에 영수증.</strong>
   </p>
   <p align="center">
     <a href="https://pypi.org/project/python-hwpx/"><img src="https://img.shields.io/pypi/v/python-hwpx?color=blue&label=PyPI" alt="PyPI"></a>
     <a href="https://pypi.org/project/python-hwpx/"><img src="https://img.shields.io/pypi/pyversions/python-hwpx" alt="Python"></a>
     <a href="https://github.com/airmang/python-hwpx/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License"></a>
     <a href="https://airmang.github.io/python-hwpx/"><img src="https://img.shields.io/badge/docs-Sphinx-8CA1AF" alt="Docs"></a>
+    <a href="https://github.com/airmang/python-hwpx/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/airmang/python-hwpx/tests.yml?branch=main&label=tests" alt="Tests"></a>
+    <a href="https://airmang.github.io/python-hwpx/corpus-metrics.html"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fairmang.github.io%2Fpython-hwpx%2F_static%2Fbadge-hancom-open.json" alt="Hancom open"></a>
   </p>
 </p>
 
+<p align="center">한국어 | <a href="README_EN.md">English</a></p>
+
+---
+
+> **python-hwpx는 한컴 없이 HWPX를 안전하게 자동화하는 Python 계층입니다.** 기존
+> 문서는 최소 범위만 수정하고, 새 문서는 실제 한컴 수용이 검증된 형태로 생성하며,
+> 모든 쓰기에 변경·보존·검증 영수증을 남기고, 완전한 해석과 렌더링은 전문 백엔드에
+> 위임할 수 있습니다.
+
+- **최소 범위 편집** — 미수정 part는 저장 시 바이트 그대로 유지됩니다(patch 경로
+  바이트 보존 497/497, 동결 코퍼스 v2 · 2026-07-19).
+- **검증된 저작** — 밑바닥 생성도 실제 한컴이 받아들이는 형태로 냅니다(산출물 한컴
+  오픈 476/476 all-pass, 실저작 품질 게이트 58/58).
+- **모든 쓰기에 영수증** — 대표 저장 경로는 [Safe Write Contract](docs/safe-write-contract.md)의
+  `MutationReport`(`hwpx.mutation-report/v1`)로 실제 쓰기 모드·보존 등급·검증 결과를
+  **측정해** 반환합니다.
+
 ---
 
 ## 🧩 HWPX Stack (3종)
@@ -21,11 +40,10 @@
 | 🔌 MCP 서버 | [`hwpx-mcp-server`](https://github.com/airmang/hwpx-mcp-server) | MCP 클라이언트(Claude Desktop, VS Code 등)에서 HWPX 조작 |
 | 🎯 에이전트 스킬 | [`hwpx-plugin`](https://github.com/airmang/hwpx-plugins) | 에이전트가 HWPX를 바로 쓰게 해주는 first-party 플러그인·스킬 번들 |
 
-`python-hwpx`는 HWPX 파싱·편집·생성을 제공하는 코어 라이브러리이며,
-`hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동 구성요소입니다.
-“first-party”는 프로젝트 유지보수 관계를 뜻하며, 한컴 또는 제3자의 공식 인증을 뜻하지 않습니다.
+`hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동
+구성요소입니다(유지보수 관계를 뜻하며, 한컴 등 외부 기관의 인증을 뜻하지 않습니다).
 
-현재 PyPI 공개 릴리스는 `python-hwpx 3.6.0`입니다. 일반
+현재 PyPI 공개 릴리스는 `python-hwpx 3.8.0`입니다. 일반
 `pip install python-hwpx`로 이 릴리스를 설치할 수 있습니다.
 현재 패키지 분류는 `Development Status :: 3 - Alpha`입니다. 이 분류는 API와 제품의
 성숙도를 나타내며, 공개 버전이나 플러그인의 최소 호환 버전을 대신하지 않습니다.
@@ -35,13 +53,22 @@
 ## 실측으로 말합니다 — Published Corpus
 
 이 스택의 산출물은 주장 대신 **실제 한컴오피스 전수 측정**으로 검증됩니다
-(동결 코퍼스 N=497, 2026-07-19, 상세·주의사항은
+(동결 코퍼스 v2, N=497 산출물, 2026-07-19, 실한컴 12.0.0.3288 COM/GUI 오라클;
+상세·주의사항은
 [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html)):
 
-- **한컴 오픈 수용률 100%** (476/476 all-pass, 하한 ≥99.4%) · 파싱 96.2%
-- **미수정 영역 바이트 보존 100%** (497/497, patch 경로) · **개인정보 0-leak**
-- 렌더 검증 416건 + 정직 버킷(변경추적 문서의 PDF export는 한컴 자체가 거부 — 실측 한계로 발행)
-- 양식 채움 차등은 wild 공개 양식에서 49.2% — **낮은 숫자도 그대로 발행**하고 잔여 과제로 명기합니다
+- **한컴 오픈 수용률 476/476 all-pass** (동결 코퍼스 v2 · 2026-07-19 · 실한컴 COM
+  `Open()` 판정 · rule-of-three 하한 99.37%) · 파싱 96.2%(458/476)
+- **미수정 영역 바이트 보존 497/497** (patch 경로 한정, zip-part diff · 오라클 불요)
+  · **개인정보 0-leak** (35문서/합성 140값)
+- 렌더 검증 416/476 (실한컴 `SaveAs("PDF")`) + 정직 버킷 43건(변경추적 문서의 PDF
+  export는 한컴 자체가 거부 — 실측 한계로 발행) + 미검증 17건
+- wild 공개 양식 채움은 구조결함 픽스 후 **무음 서식파괴 16.7%**(판정 66조합, 못 담는 타깃은 typed 거부 35건·산출분 pass 17/28) — **낮은 숫자도 그대로 발행**하고 잔여(페이지 리플·표 shape)를 명명합니다
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/airmang/python-hwpx/main/docs/images/redline-hancom.png" alt="python-hwpx가 남긴 변경추적과 AI 에이전트 메모가 실제 한/글에서 열린 화면" width="720">
+</p>
+<p align="center"><sub>python-hwpx로 작성한 변경추적(취소선·삽입)과 AI 에이전트 메모 — 실제 한/글에서 연 화면입니다.</sub></p>
 
 > 이 숫자들은 *생성물 수용률* 축입니다(우리가 만든 파일을 실제 한컴이 받아들이는가).
 > 문서 *파싱 recall*과는 다른 축이므로 파서 프로젝트 수치와 병치 비교하지 마세요.
@@ -150,6 +177,59 @@ hwpx-analyze-template 보고서.hwpx
 
 > 전체 기능·클래스·메서드 목록은 [사용 가이드](docs/usage.md)와 [API 레퍼런스](https://airmang.github.io/python-hwpx/api_reference.html)를 참고하세요.
 
+## 안전한 쓰기 계약 (Safe Write Contract)
+
+대표 저장 경로(`save_to_path` · `save_to_stream` · `to_bytes`)는 **요청한 보존 등급을
+쓰기 전에 판정하고, 실제로 무엇을 바꿨는지 측정한 영수증**을 돌려줍니다.
+
+```python
+from hwpx.mutation_report import PreservationDowngradeError
+
+# 영수증과 함께 저장 — 달성 가능한 가장 강한 보존 등급 자동 선택(mode="auto" 기본)
+report = doc.save_to_path("결과.hwpx", return_report=True)
+print(report.actual_mode)                                   # "patch" | "rebuild"
+print(report.preservation.untouched_part_payloads.to_dict())  # {"verified": 17, "changed": 0}
+
+# patch 등급 강제 — 미달이면 아무것도 쓰지 않고 예외(fail-closed)
+try:
+    doc.save_to_path("결과.hwpx", mode="patch", fallback="error")
+except PreservationDowngradeError as exc:
+    print(exc.offending_parts, exc.suggestion)
+```
+
+- `mode="patch" | "rebuild" | "auto"`(기본 `auto`) · `fallback="error" | "rebuild"`(기본 `error`)
+- `mode="patch"` + `fallback="error"`에서 미수정 part의 바이트 동일성을 지킬 수 없으면
+  **아무것도 쓰지 않고** `PreservationDowngradeError`를 던집니다(무음 rebuild 없음).
+- `MutationReport`는 `requestedMode`/`actualMode`/`fallbackUsed`, 변경 part와 좌표 명시
+  범위, 보존 3층(part 페이로드·ZIP 레코드·전체 패키지), 검증 3항목(`passed`/`failed`/`not_performed`)을
+  **측정해** 반환합니다.
+
+> 파라미터 전체와 `MutationReport` 스키마는 [안전한 쓰기 계약 문서](docs/safe-write-contract.md)를 참고하세요.
+
+## 지원 매트릭스
+
+능력 영역별 실제 등급입니다(동결 코퍼스 v2 · 2026-07-19 · 실한컴 12.0.0.3288 오라클).
+등급 어휘: **Parse / Preserve / Edit / Create / Render-verified /
+Unsupported-but-preserved / Unsupported-and-rejected**.
+
+| 능력 영역 | 상태 | 증거 |
+|---|---|---|
+| 문단·표 저작/편집 | Parse·Preserve·Edit·Create·Render-verified | 오픈 476/476 · 실저작 게이트 58/58 · 렌더 416 |
+| 표 구조 변경(행·열·표, 오토핏) | Preserve·Edit | `hwpx.table_patch` · 바이트 보존 497/497 |
+| 양식 채움(byte-splice) | Preserve·Edit | `hwpx.patch`·`table_patch`·`body_patch` · 보존 497/497 (wild 무음 서식파괴 16.7%·typed 거부 35/66, 잔여 명명) |
+| 그림 삽입/치환 | Edit·Create | `add_picture`·`replace_picture` (복잡 개체는 한컴 확인 권장) |
+| 차트 | Unsupported-but-preserved | 생성 API 없음 · 기존 차트 part는 patch 보존 |
+| 수식 | Parse·Unsupported-but-preserved | 저작 API 없음 · 기존 수식 파싱·patch 보존 |
+| 변경추적(redline) | Edit·Create | `add_tracked_*` · 실한컴 `IsTrackChange=1` (한컴이 PDF export 거부 → `render_unavailable` 정직 집계) |
+| 메모(코멘트) | Edit·Create·Render-verified | `add_memo*` · 실 Windows 한컴 검증 |
+| 각주/미주 | Edit·Create | `add_footnote`·`add_endnote` (렌더 독립 게이트 미측정) |
+| 네이티브 목차/상호참조 | Create·Render-verified | `add_native_toc`·`toc_verify` · 구조 15/15 · 페이지 정합 5/5 |
+| 암호화 HWPX | Unsupported-and-rejected | 복호화 없음 · 암호화 part는 파싱 단계 예외로 거부 |
+| HWP 5.x 바이너리 | Unsupported-and-rejected | ZIP 아님 → 열기 시 `BadZipFile` (HWPX로 변환 후 사용) |
+| 누름틀(form field) 생성 | Parse·Edit | 기존 필드 조회·서식보존 채움 · **신규 누름틀 생성 도구는 미제공** |
+
+> 각 등급의 판정 근거와 상세 증거 포인터는 [지원 매트릭스 문서](docs/support-matrix.md)를 참고하세요.
+
 ## 대항 라이브러리 비교
 
 | | python-hwpx | pyhwpx | pyhwp |
@@ -174,6 +254,7 @@ hwpx-analyze-template 보고서.hwpx
 - **[🚀 빠른 시작](docs/quickstart.md)** · **[📚 사용 가이드](docs/usage.md)** — 첫 파일 열기부터 문단·표·메모·섹션 편집, 텍스트 추출·검증까지
 - **[💡 예제 모음](docs/examples.md)** · [`examples/`](examples/) — `build_release_checklist.py`(메모·스타일 편집 HWPX 생성), `extract_text.py`(CLI 텍스트 추출), `find_objects.py`(OWPML 노드 추적) 등
 - **[📐 스키마 개요](docs/schema-overview.md)** · **[🔧 설치 검증](docs/installation.md)**
+- **[🔬 HWPX 내부 실전 가이드](docs/internals/)** — 실제 한/글 동작에서 확인된 HWPUNIT·조판 캐시·목차 필드·OPC 재패킹·메모·오라클 한계
 - **[📖 전체 문서 (Sphinx)](https://airmang.github.io/python-hwpx/)** — API 레퍼런스·50+ 실전 패턴·FAQ
 - **[📝 CHANGELOG](CHANGELOG.md)** · **[🤝 CONTRIBUTING](CONTRIBUTING.md)** · **[👥 CONTRIBUTORS](CONTRIBUTORS.md)**
 
@@ -181,6 +262,11 @@ hwpx-analyze-template 보고서.hwpx
 
 버그 리포트, 기능 제안, PR 모두 환영합니다.
 
+- **[help wanted 이슈](https://github.com/airmang/python-hwpx/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)** — 지금 들어오기 좋은 입구입니다. 시작 전에 이슈에 코멘트로 방향을 남겨주세요.
+- **[마일스톤](https://github.com/airmang/python-hwpx/milestones)** — 공개 로드맵입니다. 프로젝트가 어디로 가는지 여기서 보입니다.
+- **[Discussions](https://github.com/airmang/python-hwpx/discussions)** — 질문·아이디어는 이슈 대신 여기로.
+- **[내부 실전 가이드](docs/internals/)** — HWPX 내부 구조가 처음이라면 여기부터. 개발 흐름은 [CONTRIBUTING.md](CONTRIBUTING.md)에 있습니다.
+
 ```bash
 git clone https://github.com/airmang/python-hwpx.git
 cd python-hwpx

{python_hwpx-3.6.0 → python_hwpx-3.8.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "3.6.0"
+version = "3.8.0"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"
@@ -38,10 +38,16 @@ visual = [
 xlsx = [
     "openpyxl>=3.1",
 ]
+# Document preview viewer equation rendering: LaTeX -> MathML. Optional; without
+# it the preview fails closed to a LaTeX code block instead of dropping equations.
+preview = [
+    "latex2mathml>=3.77",
+]
 dev = [
     "build>=1.0",
     "twine>=4.0",
     "pytest>=7.4",
+    "latex2mathml>=3.77",
 ]
 test = [
     "build>=1.0",
@@ -50,6 +56,7 @@ test = [
     "pytest>=7.4",
     "pytest-cov>=5.0",
     "ruff>=0.12",
+    "latex2mathml>=3.77",
 ]
 typecheck = [
     "mypy>=1.10",
@@ -109,6 +116,13 @@ python_version = "3.10"
 follow_imports = "skip"
 files = [
     "src/hwpx/document.py",
+    "src/hwpx/mutation_report.py",
+    "src/hwpx/equation/__init__.py",
+    "src/hwpx/equation/tokens.py",
+    "src/hwpx/equation/eqedit.py",
+    "src/hwpx/equation/mathml.py",
+    "src/hwpx/equation/render.py",
+    "src/hwpx/tools/document_viewer.py",
     "src/hwpx/_document/_units.py",
     "src/hwpx/_document/fields.py",
     "src/hwpx/_document/layout.py",
@@ -156,6 +170,13 @@ ignore_missing_imports = true
 # both central facades and every extracted/touched runtime owner to the gate.
 include = [
     "src/hwpx/document.py",
+    "src/hwpx/mutation_report.py",
+    "src/hwpx/equation/__init__.py",
+    "src/hwpx/equation/tokens.py",
+    "src/hwpx/equation/eqedit.py",
+    "src/hwpx/equation/mathml.py",
+    "src/hwpx/equation/render.py",
+    "src/hwpx/tools/document_viewer.py",
     "src/hwpx/_document/_units.py",
     "src/hwpx/_document/fields.py",
     "src/hwpx/_document/layout.py",

{python_hwpx-3.6.0 → python_hwpx-3.8.0}/src/hwpx/__init__.py

@@ -75,6 +75,10 @@ from .tools.layout_preview import (
     PreviewPage,
     render_layout_preview,
 )
+from .tools.document_viewer import (
+    DocumentViewer,
+    render_document_viewer,
+)
 from .ingest import (
     ConversionAttempt,
     DocumentConverter,
@@ -85,6 +89,10 @@ from .ingest import (
     HwpxMarkdownConverter,
     UnsupportedDocumentFormat,
 )
+from .mutation_report import (
+    MutationReport,
+    PreservationDowngradeError,
+)
 from .patch import (
     BytePreservingPatchResult,
     ParagraphTextPatch,
@@ -146,6 +154,8 @@ __all__ = [
     "ParagraphInfo",
     "PackageValidationReport",
     "BytePreservingPatchResult",
+    "MutationReport",
+    "PreservationDowngradeError",
     "PlanValidationReport",
     "ParagraphTextPatch",
     "PatchApplied",
@@ -200,6 +210,8 @@ __all__ = [
     "validate_package",
     "paragraph_patch",
     "render_layout_preview",
+    "render_document_viewer",
+    "DocumentViewer",
     "register_template",
     "table_compute",
 ]