python-hwpx 3.7.0__tar.gz → 4.0.0__tar.gz

{python_hwpx-3.7.0 → python_hwpx-4.0.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-4.0.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: python-hwpx
+Version: 4.0.0
+Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리
+Author: python-hwpx Maintainers
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/airmang/python-hwpx
+Project-URL: Documentation, https://airmang.github.io/python-hwpx/
+Project-URL: Issues, https://github.com/airmang/python-hwpx/issues
+Keywords: hwp,hwpx,hancom,opc,xml,document-automation,validation,template
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Text Processing :: Markup :: XML
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Requires-Dist: lxml<7,>=4.9
+Provides-Extra: visual
+Requires-Dist: pymupdf>=1.24; extra == "visual"
+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"
+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"
+Dynamic: license-file
+
+<p align="center">
+  <h1 align="center">python-hwpx</h1>
+  <p align="center">
+    <strong>한컴 없이 HWPX를 읽고, 고치고, 만드는 순수 파이썬 라이브러리</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/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>
+    <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>
+  </p>
+</p>
+
+<p align="center">한국어 | <a href="README_EN.md">English</a></p>
+
+기존 문서는 손댄 곳만 고치고(미수정 영역은 바이트 그대로), 새 문서는 실제
+한컴오피스가 받아들이는 형태로 만듭니다. HWPX는 ZIP+XML(OWPML/OPC) 구조라
+Windows·macOS·Linux·CI 어디서든 순수 파이썬으로 동작합니다.
+
+| | 레포 | 역할 |
+|---|---|---|
+| 📦 | **`python-hwpx`** | 순수 파이썬 HWPX 코어 (이 레포) |
+| 🔌 | [`hwpx-mcp-server`](https://github.com/airmang/hwpx-mcp-server) | MCP 클라이언트(Claude Desktop 등)에서 HWPX 조작 |
+| 🎯 | [`hwpx-plugin`](https://github.com/airmang/hwpx-plugins) | 에이전트용 플러그인·스킬 번들 |
+
+## 시작하기
+
+```bash
+pip install python-hwpx      # Python 3.10+
+```
+
+```python
+from hwpx import HwpxDocument
+
+doc = HwpxDocument.open("보고서.hwpx")
+doc.add_paragraph("자동화로 추가한 문단입니다.")
+doc.save_to_path("보고서-수정.hwpx")
+```
+
+## 무엇을 하나
+
+- **읽기·추출** — 텍스트/HTML/rich Markdown 내보내기(서식·중첩 표·각주 보존), XPath 객체 탐색
+- **편집** — 문단·표·이미지·머리글/바닥글·메모·각주, 줄간격·여백·쪽번호 등 서식
+- **양식 채우기** — 라벨·경로 기반 셀 채움, 바이트 보존 구조 편집(행·열·오토핏·shrink-to-fit)
+- **생성** — 조립형 builder, 공문 lint·결재란, 사진대지·명패·조직도, mail merge, 신구대조표
+- **변경추적·목차** — redline 저작, 네이티브 목차·상호참조
+- **검증·안전** — XSD·패키지 검증 CLI, 열림 안전 게이트, 모든 쓰기에 영수증(`MutationReport`)
+
+자세한 내용: [사용 가이드](docs/usage.md) · [API 레퍼런스](https://airmang.github.io/python-hwpx/) · [안정 API 표면](docs/stable-api.md) · [예제](docs/examples.md)
+
+### 양식 채우기 — 서식은 그대로, 값만
+
+```python
+doc = HwpxDocument.open("신청서.hwpx")
+result = doc.fill_by_path({
+    "성명 > right": "홍길동",
+    "소속 > right": "플랫폼팀",
+})
+doc.save_to_path("신청서-작성완료.hwpx")
+```
+
+라벨 기준으로 셀을 찾아 채우고, 손대지 않은 영역은 원본 바이트가 그대로 유지됩니다.
+
+### 저장에는 영수증이 따라옵니다
+
+```python
+report = doc.save_to_path("결과.hwpx", return_report=True)
+print(report.actual_mode)        # "patch" — 문서 재조립 없이 저장됨
+print(report.preservation.untouched_part_payloads.to_dict())
+                                 # {"verified": 17, "changed": 0}
+```
+
+요청한 보존 등급을 지킬 수 없으면 아무것도 쓰지 않고 실패합니다(fail-closed).
+전체 규칙은 [안전한 쓰기 계약](docs/safe-write-contract.md)에 있습니다.
+
+## 실측으로 말합니다
+
+산출물 전수를 실제 한컴오피스로 측정해 그대로 공개합니다(동결 코퍼스 N=497):
+
+- **한컴 오픈 476/476 all-pass** — 우리가 만든 파일을 실한컴이 전부 엽니다
+- **미수정 영역 바이트 보존 497/497** · 개인정보 0-leak
+- **렌더 검증 416/476** + 정직 버킷 43 — 한컴 자체가 PDF export를 거부한 케이스도 숨기지 않고 집계
+- 낮은 숫자도 그대로 발행합니다 — 전체 수치·주의사항: [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html)
+
+기능별로 되는 것과 안 되는 것은 [지원 매트릭스](docs/support-matrix.md)에 등급으로
+명시되어 있습니다. 현재 개발 상태는 Alpha입니다 — API는 바뀔 수 있습니다.
+
+> 위 수치는 *생성물 수용률* 축입니다(만든 파일을 실한컴이 받는가). 문서 *파싱 recall*과는
+> 다른 축이므로 파서 프로젝트 수치와 병치 비교하지 마세요.
+
+## 비교
+
+| | python-hwpx | pyhwpx | pyhwp |
+|---|---|---|---|
+| **대상 포맷** | `.hwpx` (OWPML/OPC) | `.hwpx` | `.hwp` (v5 바이너리) |
+| **한/글 설치** | 불필요 | 필요 (Windows COM) | 불필요 |
+| **크로스 플랫폼** | ✅ Linux / macOS / Windows / CI | ❌ Windows 전용 | ✅ |
+| **편집/생성 API** | ✅ | ✅ (COM) | ❌ 대부분 읽기 |
+| **AI 에이전트 연동 (MCP)** | ✅ | ❌ | ❌ |
+
+> HWP(v5 바이너리)는 지원하지 않습니다. 한컴오피스에서 HWPX로 변환 후 사용하세요.
+
+## 알려진 제약
+
+- `add_shape()` / `add_control()`은 한/글이 요구하는 모든 하위 요소를 생성하지 않습니다.
+- `<hp:pic>` 그림 개체의 완전 자동 생성은 제공하지 않습니다.
+- 암호화된 HWPX는 지원하지 않습니다.
+
+## 기여하기
+
+[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/) ·
+[CONTRIBUTING](CONTRIBUTING.md)
+
+HWPX 내부 구조가 처음이라면 [내부 실전 가이드](docs/internals/)부터 — 실제 한/글
+동작에서 확인된 조판 캐시·목차 필드·OPC 재패킹 같은 실전 지식을 정리해 두었습니다.
+
+## 감사의 말
+
+아래 공개 표준·프로젝트에 빚지고 있습니다.
+
+- **[OWPML — 개방형 워드프로세서 마크업 언어 (KS X 6101)](https://www.kssn.net/search/stddetail.do?itemNo=K001010119985)** — HWPX가 기반하는 한국 산업 표준
+- **[hancom-io/hwpx-owpml-model](https://github.com/hancom-io/hwpx-owpml-model)** — OWPML 요소 구조 참조 모델 · **[neolord0/hwpxlib](https://github.com/neolord0/hwpxlib)** — 오라클 샘플 코퍼스
+- **[edwardkim/rhwp](https://github.com/edwardkim/rhwp)** — 멱등성·검증 게이트 설계 영감
+- **범정부오피스** — 공무 문서 편집 워크플로 아이디어
+
+## License · Maintainer
+
+Apache-2.0 ([LICENSE](LICENSE) · [NOTICE](NOTICE)) — **Kohkyuhyun** [@airmang](https://github.com/airmang) · [kokyuhyun@hotmail.com](mailto:kokyuhyun@hotmail.com)

python_hwpx-4.0.0/README.md

@@ -0,0 +1,132 @@
+<p align="center">
+  <h1 align="center">python-hwpx</h1>
+  <p align="center">
+    <strong>한컴 없이 HWPX를 읽고, 고치고, 만드는 순수 파이썬 라이브러리</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/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>
+    <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>
+  </p>
+</p>
+
+<p align="center">한국어 | <a href="README_EN.md">English</a></p>
+
+기존 문서는 손댄 곳만 고치고(미수정 영역은 바이트 그대로), 새 문서는 실제
+한컴오피스가 받아들이는 형태로 만듭니다. HWPX는 ZIP+XML(OWPML/OPC) 구조라
+Windows·macOS·Linux·CI 어디서든 순수 파이썬으로 동작합니다.
+
+| | 레포 | 역할 |
+|---|---|---|
+| 📦 | **`python-hwpx`** | 순수 파이썬 HWPX 코어 (이 레포) |
+| 🔌 | [`hwpx-mcp-server`](https://github.com/airmang/hwpx-mcp-server) | MCP 클라이언트(Claude Desktop 등)에서 HWPX 조작 |
+| 🎯 | [`hwpx-plugin`](https://github.com/airmang/hwpx-plugins) | 에이전트용 플러그인·스킬 번들 |
+
+## 시작하기
+
+```bash
+pip install python-hwpx      # Python 3.10+
+```
+
+```python
+from hwpx import HwpxDocument
+
+doc = HwpxDocument.open("보고서.hwpx")
+doc.add_paragraph("자동화로 추가한 문단입니다.")
+doc.save_to_path("보고서-수정.hwpx")
+```
+
+## 무엇을 하나
+
+- **읽기·추출** — 텍스트/HTML/rich Markdown 내보내기(서식·중첩 표·각주 보존), XPath 객체 탐색
+- **편집** — 문단·표·이미지·머리글/바닥글·메모·각주, 줄간격·여백·쪽번호 등 서식
+- **양식 채우기** — 라벨·경로 기반 셀 채움, 바이트 보존 구조 편집(행·열·오토핏·shrink-to-fit)
+- **생성** — 조립형 builder, 공문 lint·결재란, 사진대지·명패·조직도, mail merge, 신구대조표
+- **변경추적·목차** — redline 저작, 네이티브 목차·상호참조
+- **검증·안전** — XSD·패키지 검증 CLI, 열림 안전 게이트, 모든 쓰기에 영수증(`MutationReport`)
+
+자세한 내용: [사용 가이드](docs/usage.md) · [API 레퍼런스](https://airmang.github.io/python-hwpx/) · [안정 API 표면](docs/stable-api.md) · [예제](docs/examples.md)
+
+### 양식 채우기 — 서식은 그대로, 값만
+
+```python
+doc = HwpxDocument.open("신청서.hwpx")
+result = doc.fill_by_path({
+    "성명 > right": "홍길동",
+    "소속 > right": "플랫폼팀",
+})
+doc.save_to_path("신청서-작성완료.hwpx")
+```
+
+라벨 기준으로 셀을 찾아 채우고, 손대지 않은 영역은 원본 바이트가 그대로 유지됩니다.
+
+### 저장에는 영수증이 따라옵니다
+
+```python
+report = doc.save_to_path("결과.hwpx", return_report=True)
+print(report.actual_mode)        # "patch" — 문서 재조립 없이 저장됨
+print(report.preservation.untouched_part_payloads.to_dict())
+                                 # {"verified": 17, "changed": 0}
+```
+
+요청한 보존 등급을 지킬 수 없으면 아무것도 쓰지 않고 실패합니다(fail-closed).
+전체 규칙은 [안전한 쓰기 계약](docs/safe-write-contract.md)에 있습니다.
+
+## 실측으로 말합니다
+
+산출물 전수를 실제 한컴오피스로 측정해 그대로 공개합니다(동결 코퍼스 N=497):
+
+- **한컴 오픈 476/476 all-pass** — 우리가 만든 파일을 실한컴이 전부 엽니다
+- **미수정 영역 바이트 보존 497/497** · 개인정보 0-leak
+- **렌더 검증 416/476** + 정직 버킷 43 — 한컴 자체가 PDF export를 거부한 케이스도 숨기지 않고 집계
+- 낮은 숫자도 그대로 발행합니다 — 전체 수치·주의사항: [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html)
+
+기능별로 되는 것과 안 되는 것은 [지원 매트릭스](docs/support-matrix.md)에 등급으로
+명시되어 있습니다. 현재 개발 상태는 Alpha입니다 — API는 바뀔 수 있습니다.
+
+> 위 수치는 *생성물 수용률* 축입니다(만든 파일을 실한컴이 받는가). 문서 *파싱 recall*과는
+> 다른 축이므로 파서 프로젝트 수치와 병치 비교하지 마세요.
+
+## 비교
+
+| | python-hwpx | pyhwpx | pyhwp |
+|---|---|---|---|
+| **대상 포맷** | `.hwpx` (OWPML/OPC) | `.hwpx` | `.hwp` (v5 바이너리) |
+| **한/글 설치** | 불필요 | 필요 (Windows COM) | 불필요 |
+| **크로스 플랫폼** | ✅ Linux / macOS / Windows / CI | ❌ Windows 전용 | ✅ |
+| **편집/생성 API** | ✅ | ✅ (COM) | ❌ 대부분 읽기 |
+| **AI 에이전트 연동 (MCP)** | ✅ | ❌ | ❌ |
+
+> HWP(v5 바이너리)는 지원하지 않습니다. 한컴오피스에서 HWPX로 변환 후 사용하세요.
+
+## 알려진 제약
+
+- `add_shape()` / `add_control()`은 한/글이 요구하는 모든 하위 요소를 생성하지 않습니다.
+- `<hp:pic>` 그림 개체의 완전 자동 생성은 제공하지 않습니다.
+- 암호화된 HWPX는 지원하지 않습니다.
+
+## 기여하기
+
+[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/) ·
+[CONTRIBUTING](CONTRIBUTING.md)
+
+HWPX 내부 구조가 처음이라면 [내부 실전 가이드](docs/internals/)부터 — 실제 한/글
+동작에서 확인된 조판 캐시·목차 필드·OPC 재패킹 같은 실전 지식을 정리해 두었습니다.
+
+## 감사의 말
+
+아래 공개 표준·프로젝트에 빚지고 있습니다.
+
+- **[OWPML — 개방형 워드프로세서 마크업 언어 (KS X 6101)](https://www.kssn.net/search/stddetail.do?itemNo=K001010119985)** — HWPX가 기반하는 한국 산업 표준
+- **[hancom-io/hwpx-owpml-model](https://github.com/hancom-io/hwpx-owpml-model)** — OWPML 요소 구조 참조 모델 · **[neolord0/hwpxlib](https://github.com/neolord0/hwpxlib)** — 오라클 샘플 코퍼스
+- **[edwardkim/rhwp](https://github.com/edwardkim/rhwp)** — 멱등성·검증 게이트 설계 영감
+- **범정부오피스** — 공무 문서 편집 워크플로 아이디어
+
+## License · Maintainer
+
+Apache-2.0 ([LICENSE](LICENSE) · [NOTICE](NOTICE)) — **Kohkyuhyun** [@airmang](https://github.com/airmang) · [kokyuhyun@hotmail.com](mailto:kokyuhyun@hotmail.com)

{python_hwpx-3.7.0 → python_hwpx-4.0.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "3.7.0"
+version = "4.0.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,7 +116,14 @@ python_version = "3.10"
 follow_imports = "skip"
 files = [
     "src/hwpx/document.py",
+    "src/hwpx/errors.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",
@@ -157,7 +171,14 @@ ignore_missing_imports = true
 # both central facades and every extracted/touched runtime owner to the gate.
 include = [
     "src/hwpx/document.py",
+    "src/hwpx/errors.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.7.0 → python_hwpx-4.0.0}/src/hwpx/__init__.py

@@ -1,6 +1,18 @@
 # SPDX-License-Identifier: Apache-2.0
-"""High-level utilities for working with HWPX documents."""
+"""High-level utilities for working with HWPX documents.
 
+최상위 ``from hwpx import ...`` 표면은 세 계층으로 나뉩니다(정책·전수 목록:
+``docs/stable-api.md``):
+
+- **stable** — ``__all__``에 있는 이름. 계약이 굳었고 major 경계에서만 깨질 수 있음.
+- **experimental** — 계약이 유동적. ``from hwpx.experimental import ...``로 쓰세요.
+  최상위 재내보내기는 하위 호환을 위해 유지하되 접근 시 ``DeprecationWarning``이 나며
+  다음 major에서 제거될 예정입니다.
+- **deprecated** — 대체 경로로 이전하세요. 접근 시 ``DeprecationWarning``이 납니다.
+"""
+
+import importlib
+import warnings
 from importlib.metadata import PackageNotFoundError, version as _metadata_version
 
 
@@ -11,13 +23,94 @@ def _resolve_version() -> str:
     except PackageNotFoundError:
         return "0+unknown"
 
+
+# --- experimental / deprecated 최상위 표면 (지연 접근, 접근 시 경고) ---------------
+#
+# stable 이름은 아래에서 eager import 되어 모듈 전역에 존재하므로 ``__getattr__``이
+# 호출되지 않습니다(=경고 없음). 여기 등록된 이름만 지연 해석되어 경고를 냅니다.
+# 4.0.0에서 제거되는 이름은 0개 — 모두 계속 import 가능합니다.
+
+_EXPERIMENTAL_EXPORTS = {
+    # 문서 ingestion 프레임워크(임의 포맷 -> HWPX). 계약 유동.
+    "ConversionAttempt": "hwpx.ingest",
+    "DocumentConverter": "hwpx.ingest",
+    "DocumentIngestError": "hwpx.ingest",
+    "DocumentIngestResult": "hwpx.ingest",
+    "DocumentIngestor": "hwpx.ingest",
+    "DocumentSourceInfo": "hwpx.ingest",
+    "UnsupportedDocumentFormat": "hwpx.ingest",
+    # 레이아웃 프리뷰(한컴 없는 정직 근사). 계약 유동.
+    "LayoutPreview": "hwpx.tools.layout_preview",
+    "PreviewPage": "hwpx.tools.layout_preview",
+    "render_layout_preview": "hwpx.tools.layout_preview",
+    # 문서 프리뷰 뷰어(3.8.0 신규). 계약 유동.
+    "DocumentViewer": "hwpx.tools.document_viewer",
+    "render_document_viewer": "hwpx.tools.document_viewer",
+}
+
+_DEPRECATED_EXPORTS = {
+    "analyze_template_formfit": "hwpx.template_formfit",
+    "apply_template_formfit": "hwpx.template_formfit",
+    "TEMPLATE_FORMFIT_BASELINE_SCHEMA_VERSION": "hwpx.template_formfit",
+    "TEMPLATE_FORMFIT_PLAN_SCHEMA_VERSION": "hwpx.template_formfit",
+}
+
+# deprecated formfit 표면의 공통 대체 경로 안내.
+_FORMFIT_REPLACEMENT = (
+    "구조적 form-fill 경로를 사용하세요: 라이브러리는 "
+    "hwpx.table_patch.fill_cells 계열, MCP는 analyze_form_fill/apply_form_fill/"
+    "verify_form_fill."
+)
+
+
+def _experimental_message(name: str) -> str:
+    return (
+        f"'hwpx.{name}'는 실험적(experimental) 표면입니다. 계약이 유동적이므로 "
+        f"'from hwpx.experimental import {name}'로 import하세요. 최상위 재내보내기는 "
+        f"다음 major에서 제거될 예정입니다."
+    )
+
+
+def _deprecated_message(name: str) -> str:
+    return (
+        f"'hwpx.{name}'는 deprecated입니다. {_FORMFIT_REPLACEMENT} 이 이름은 "
+        f"다음 major에서 제거될 예정입니다."
+    )
+
+
 def __getattr__(name: str) -> object:
-    """Resolve dynamic module attributes."""
+    """Resolve dynamic module attributes.
+
+    ``__version__``은 경고 없이 지연 해석하고, experimental/deprecated 이름은
+    해석 시 ``DeprecationWarning``을 냅니다.
+    """
 
     if name == "__version__":
         return _resolve_version()
+
+    module_name = _EXPERIMENTAL_EXPORTS.get(name)
+    if module_name is not None:
+        warnings.warn(_experimental_message(name), DeprecationWarning, stacklevel=2)
+        return getattr(importlib.import_module(module_name), name)
+
+    module_name = _DEPRECATED_EXPORTS.get(name)
+    if module_name is not None:
+        warnings.warn(_deprecated_message(name), DeprecationWarning, stacklevel=2)
+        return getattr(importlib.import_module(module_name), name)
+
     raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
 
+
+def __dir__() -> list[str]:
+    return sorted(
+        set(globals())
+        | set(__all__)
+        | set(_EXPERIMENTAL_EXPORTS)
+        | set(_DEPRECATED_EXPORTS)
+    )
+
+
+# --- stable 최상위 표면 (eager import) ------------------------------------------
 from .tools.text_extractor import (
     DEFAULT_NAMESPACES,
     ParagraphInfo,
@@ -70,21 +163,8 @@ from .tools.style_profile import (
     placeholder_fill_report,
     register_template,
 )
-from .tools.layout_preview import (
-    LayoutPreview,
-    PreviewPage,
-    render_layout_preview,
-)
-from .ingest import (
-    ConversionAttempt,
-    DocumentConverter,
-    DocumentIngestError,
-    DocumentIngestResult,
-    DocumentIngestor,
-    DocumentSourceInfo,
-    HwpxMarkdownConverter,
-    UnsupportedDocumentFormat,
-)
+from .ingest import HwpxMarkdownConverter
+from .errors import HwpxError
 from .mutation_report import (
     MutationReport,
     PreservationDowngradeError,
@@ -120,12 +200,6 @@ from .quality import (
     SavePipeline,
     VisualCompleteReport,
 )
-from .template_formfit import (
-    TEMPLATE_FORMFIT_BASELINE_SCHEMA_VERSION,
-    TEMPLATE_FORMFIT_PLAN_SCHEMA_VERSION,
-    analyze_template_formfit,
-    apply_template_formfit,
-)
 
 __all__ = [
     "QualityPolicy",
@@ -137,30 +211,21 @@ __all__ = [
     "DEFAULT_STYLE_PRESET",
     "DOCUMENT_PLAN_SCHEMA_VERSION",
     "get_document_plan_schema",
-    "ConversionAttempt",
     "DocumentBlock",
-    "DocumentConverter",
-    "DocumentIngestError",
-    "DocumentIngestResult",
-    "DocumentIngestor",
     "DocumentPlan",
-    "DocumentSourceInfo",
     "DocumentStylePreset",
     "EditorOpenSafetyReport",
     "ParagraphInfo",
     "PackageValidationReport",
     "BytePreservingPatchResult",
+    "HwpxError",
     "MutationReport",
     "PreservationDowngradeError",
     "PlanValidationReport",
     "ParagraphTextPatch",
     "PatchApplied",
     "PatchSkipped",
-    "LayoutPreview",
-    "PreviewPage",
     "SectionInfo",
-    "TEMPLATE_FORMFIT_BASELINE_SCHEMA_VERSION",
-    "TEMPLATE_FORMFIT_PLAN_SCHEMA_VERSION",
     "TextExtractor",
     "FoundElement",
     "HwpxMarkdownConverter",
@@ -173,7 +238,6 @@ __all__ = [
     "STYLE_PROFILE_SCHEMA_VERSION",
     "TEMPLATE_REGISTRY_SCHEMA_VERSION",
     "TABLE_COMPUTE_REPORT_VERSION",
-    "UnsupportedDocumentFormat",
     "apply_style_profile_to_plan",
     "build_comparison_table_plan",
     "build_image_grid",
@@ -186,8 +250,6 @@ __all__ = [
     "HwpxDocument",
     "HwpxPackage",
     "create_document_from_plan",
-    "analyze_template_formfit",
-    "apply_template_formfit",
     "approval_box",
     "describe_template",
     "extract_style_profile",
@@ -205,7 +267,6 @@ __all__ = [
     "validate_editor_open_safety",
     "validate_package",
     "paragraph_patch",
-    "render_layout_preview",
     "register_template",
     "table_compute",
 ]