python-hwpx 5.0.1__tar.gz → 5.1.1__tar.gz

{python_hwpx-5.0.1/src/python_hwpx.egg-info → python_hwpx-5.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 5.0.1
+Version: 5.1.1
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0
@@ -14,8 +14,11 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Text Processing :: Markup :: XML
+Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -63,26 +66,33 @@ Dynamic: license-file
 
 <p align="center">한국어 | <a href="README_EN.md">English</a></p>
 
-기존 문서는 손댄 곳만 고치고(미수정 영역은 바이트 그대로), 새 문서는 실제
-한컴오피스가 받아들이는 형태로 만듭니다. HWPX는 ZIP+XML(OWPML/OPC) 구조라
-Windows·macOS·Linux·CI 어디서든 순수 파이썬으로 동작합니다. 한컴오피스도
-Windows도 필요하지 않으므로 **ChatGPT 채팅 환경에서도 HWPX 문서를 만들고
-고칠 수 있습니다** — 파이썬이 도는 곳이면 됩니다.
+한컴오피스가 없어도 됩니다. HWPX는 ZIP+XML(OWPML) 포맷이라 순수 파이썬만으로
+읽고, 고치고, 새로 만들 수 있습니다 — Windows·macOS·Linux·CI, 그리고
+**파이썬이 도는 ChatGPT 채팅 안에서도** 그대로 동작합니다. 기존 문서는 손댄
+곳만 바뀌고 나머지는 바이트 그대로 유지되며, 새 문서는 실제 한컴오피스가 여는
+형태로 만들어집니다.
 
-| 계층 | 저장소 | 정본 책임 |
-|---|---|---|
-| Core | [`python-hwpx`](https://github.com/airmang/python-hwpx) | HWPX package/object model·OPC/OXML·직렬화·재사용 primitive |
-| Automation | [`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation) | Python 자동화·워크플로·profile/policy·렌더·선택형 MCP adapter |
-| Judgment | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) | 에이전트 intent/genre 판단·ambiguity 처리·plugin/skill 가이드 |
+<p align="center">
+  <img src="https://raw.githubusercontent.com/airmang/python-hwpx/main/docs/assets/chatgpt-formfill.png" width="760" alt="일반 ChatGPT 대화에 hwpx 양식을 올려 지도안 작성을 부탁하고, 양식이 유지된 채 채워진 문서를 돌려받는 화면">
+</p>
+<p align="center"><sub>일반 ChatGPT 대화 — 양식 <code>.hwpx</code>를 올리고 말로 부탁하면, 서식을 유지한 채 채워진 문서가 돌아옵니다.</sub></p>
 
-이 저장소는 위 표의 Core 정본입니다. 5.0의 모듈 소유권, 삭제 경로 재등장
-방지, 의존성 허용 범위는
-[제품 경계 문서](docs/architecture/product-boundary.md)에 고정돼 있습니다.
+**ChatGPT에서 그대로 따라 하기** — 문서를 올리면서 이렇게 부탁하면 됩니다:
 
-> **Python 블록 판정:** 이 current manual의 모든 Python 블록은
-> [실행 분류 ledger](docs/python-example-ledger.json)에 exact source digest와 함께
-> 동결돼 있습니다. **독립 실행 예제** 표시가 없는 블록은 기존 입력 파일이나 앞
-> 문맥을 요구하는 조각이며, 그대로 실행할 수 있는 예제로 간주하지 않습니다.
+```text
+이 .hwpx 파일을 python-hwpx 라이브러리로 열어서 작업해줘.
+(pip install python-hwpx 로 설치하면 돼)
+양식과 서식은 그대로 두고, ○○만 바꿔서 새 파일로 돌려줘.
+```
+
+설치부터 결과 파일까지 대화 안에서 끝납니다 — 내 컴퓨터에 파이썬이 없어도 됩니다.
+AI 도구가 정확한 API를 배우도록 [llms.txt](https://airmang.github.io/python-hwpx/llms.txt)도 제공합니다.
+
+| | 저장소 | 역할 |
+|---|---|---|
+| 📦 | [`python-hwpx`](https://github.com/airmang/python-hwpx) | HWPX 문서를 읽고·고치고·만드는 순수 파이썬 엔진 |
+| 🔌 | [`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation) | 저작·양식 채움 워크플로, `hwpx` CLI, 선택형 MCP 서버 |
+| 🎯 | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) | 에이전트가 알맞은 도구를 고르도록 돕는 플러그인/스킬 번들 |
 
 ## 시작하기
 
@@ -90,11 +100,6 @@ Windows도 필요하지 않으므로 **ChatGPT 채팅 환경에서도 HWPX 문
 pip install python-hwpx      # Python 3.10+
 ```
 
-> **5.x 호환 extra:** `pip install "python-hwpx[visual]"`은 기존 설치 명령을
-> 깨뜨리지 않기 위해 계속 허용되지만, `visual` extra는 비어 있어 PDF·이미지
-> 렌더링 의존성을 설치하지 않습니다. 렌더·PDF 이미징 실행은
-> `python-hwpx-automation[oracle]`이 소유합니다.
-
 ```python
 from hwpx import HwpxDocument
 
@@ -103,23 +108,24 @@ doc.add_paragraph("자동화로 추가한 문단입니다.")
 doc.save_to_path("보고서-수정.hwpx")
 ```
 
-백지에서 새 문서를 만들 때는 `HwpxDocument.new()`로 시작해 같은 API로
-문단·표·머리말을 채우고 `save_to_path()`로 저장합니다.
-
-문서 저작·양식 채움·시험지 조판 같은 상위 워크플로가 필요하면
+백지에서 시작할 때는 `HwpxDocument.new()`로 만들어 같은 API로 문단·표·머리말을
+채우면 됩니다. 문서 저작·양식 채움·시험지 조판 같은 상위 워크플로가 필요하면
 [`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation)을
-함께 설치하세요. MCP SDK 없이 같은 환경에서 그대로 동작합니다.
+함께 설치하세요.
+
+> 기존 설치 명령 호환을 위해 `pip install "python-hwpx[visual]"`도 계속
+> 동작합니다. 다만 이 extra는 비어 있어 렌더·PDF 의존성을 설치하지 않습니다 —
+> 그 역할은 `python-hwpx-automation[oracle]`이 맡습니다.
 
 ## 무엇을 하나
 
-- **읽기·추출** — 텍스트/HTML/rich Markdown 내보내기(서식·중첩 표·각주 보존), XPath 객체 탐색
-- **편집** — 문단·표·이미지·머리글/바닥글·메모·각주, 줄간격·여백·쪽번호 등 서식
-- **양식 채우기** — 라벨·경로 기반 셀 채움, 바이트 보존 구조 편집(행·열·오토핏·shrink-to-fit)
-- **생성·일괄 처리** — 문단·표·이미지·목차·상호참조 저작, 명시적 sanitizer 기반 mail merge, 텍스트 diff
-- **변경추적·목차** — redline 저작, 네이티브 목차·상호참조
-- **검증·안전** — 패키지 구조 검증 CLI, 열림 안전 게이트, 모든 쓰기에 영수증(`MutationReport`) — 번들 XSD는 느슨한 구조 스키마이며 OWPML 전체 검증은 아닙니다
+- **읽기·추출** — 텍스트/HTML/Markdown 내보내기 (서식·중첩 표·각주 보존)
+- **편집** — 문단·표·이미지·머리글/바닥글·메모·각주, 줄간격·여백·쪽번호 같은 서식
+- **양식 채우기** — 라벨로 셀을 찾아 값만 채우기, 행·열 조정 같은 구조 편집도 바이트 보존으로
+- **생성·일괄 처리** — 새 문서 저작, 목차·상호참조, mail merge, 텍스트 diff, 변경추적(redline)
+- **검증·안전** — 패키지 구조 검증 CLI, 열림 안전 게이트, 모든 저장에 영수증(`MutationReport`)
 
-자세한 내용: [사용 가이드](docs/usage.md) · [API 레퍼런스](https://airmang.github.io/python-hwpx/) · [안정 API 표면](docs/stable-api.md) · [예제](docs/examples.md)
+자세한 내용: [5분 퀵스타트](docs/quickstart.md) · [사용 가이드](docs/usage.md) · [API 레퍼런스](https://airmang.github.io/python-hwpx/) · [예제](docs/examples.md)
 
 ### 양식 채우기 — 서식은 그대로, 값만
 
@@ -144,22 +150,31 @@ print(report.preservation.untouched_part_payloads.to_dict())
 ```
 
 요청한 보존 등급을 지킬 수 없으면 아무것도 쓰지 않고 실패합니다(fail-closed).
-전체 규칙은 [안전한 쓰기 계약](docs/safe-write-contract.md)에 있습니다.
+전체 규칙: [안전한 쓰기 계약](docs/safe-write-contract.md).
+
+*예제 중 **독립 실행 예제** 표시가 없는 블록은 여러분의 기존 문서를 입력으로
+쓰는 조각입니다. 예제별 Python 블록 판정은
+[실행 ledger](docs/python-example-ledger.json)에 동결돼 있습니다.*
 
 ## 실측으로 말합니다
 
-산출물 전수를 실제 한컴오피스로 측정해 그대로 공개합니다(동결 코퍼스 N=497):
+만든 파일이 실제 한컴오피스에서 열리는지, 동결 코퍼스 전수(N=497)를 재서
+그대로 공개합니다:
 
-- **한컴 오픈 476/476 all-pass** — 우리가 만든 파일을 실한컴이 전부 엽니다
-- **미수정 영역 바이트 보존 497/497** · 개인정보 0-leak
-- **렌더 검증 416/476** + 정직 버킷 43 — 한컴 자체가 PDF export를 거부한 케이스도 숨기지 않고 집계
-- 낮은 숫자도 그대로 발행합니다 — 전체 수치·주의사항: [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html)
+- **한컴 열림 476/476** — 우리가 만든 파일을 실한컴이 전부 엽니다
+- **미수정 영역 바이트 보존 497/497** · 개인정보 유출 0
+- **렌더 검증 416/476** — 한컴 자체가 PDF 내보내기를 거부한 43건도 숨기지 않고 집계
+- 전체 수치와 주의사항: [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html) · 기능별 등급: [지원 매트릭스](docs/support-matrix.md)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/airmang/python-hwpx/main/docs/assets/hancom-open-generated.png" width="760" alt="ChatGPT 실행 환경에서 python-hwpx로 생성한 HWPX 문서를 실제 한컴오피스에서 연 모습">
+</p>
+<p align="center"><sub>ChatGPT 실행 환경에서 생성한 문서를 실제 한컴오피스로 연 모습.</sub></p>
 
-기능별로 되는 것과 안 되는 것은 [지원 매트릭스](docs/support-matrix.md)에 등급으로
-명시되어 있습니다. 현재 개발 상태는 Alpha입니다 — API는 바뀔 수 있습니다.
+현재 개발 상태는 Alpha입니다 — API는 바뀔 수 있습니다.
 
-> 위 수치는 *생성물 수용률* 축입니다(만든 파일을 실한컴이 받는가). 문서 *파싱 recall*과는
-> 다른 축이므로 파서 프로젝트 수치와 병치 비교하지 마세요.
+> 위 수치는 "만든 파일을 실한컴이 받아주는가"라는 축입니다. 문서 파싱 성능과는
+> 다른 축이므로 파서 프로젝트 수치와 직접 비교하지 마세요.
 
 ## 어디서 쓰나
 
@@ -172,11 +187,10 @@ print(report.preservation.untouched_part_payloads.to_dict())
 | Codex 마켓플레이스 플러그인 | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) 설치 |
 | Claude Code · Hermes · OpenClaw | 같은 MCP 서버를 각 클라이언트에 등록 ([`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation)) |
 
-실측: 일반 ChatGPT 대화에 `.hwpx`를 올리고 python-hwpx 설치를 요청했을 때 PyPI
-설치가 성공했고, 문서를 편집해 되받았습니다. 다만 파이썬 실행과 네트워크 허용
-범위는 플랜·설정에 따라 다르므로 모든 계정에서 보장되는 경로는 아닙니다.
-네트워크가 막힌 실행 환경에서는 wheel 파일을 함께 업로드하면 오프라인 설치로
-같은 여정이 됩니다.
+실제로 일반 ChatGPT 대화에 `.hwpx`를 올리고 설치를 부탁했을 때 PyPI 설치와
+편집·되받기까지 동작하는 것을 확인했습니다. 파이썬 실행과 네트워크 허용 범위는
+플랜·설정에 따라 다르며, 네트워크가 막힌 환경에서는 wheel 파일을 함께 올리면
+오프라인 설치로 같은 여정이 됩니다.
 
 ## 비교
 
@@ -192,11 +206,10 @@ print(report.preservation.untouched_part_payloads.to_dict())
 
 ## 알려진 제약
 
-- `add_shape()` / `add_control()`은 한/글이 요구하는 모든 하위 요소를 생성하지 않는
-  저수준 탈출구입니다. 그대로 저장한 문서는 한/글이 열지 못하며, 신호는 호출 시점의
-  경고 하나뿐입니다(저장도 패키지 검증도 막지 않습니다). 도형은 `add_line()` /
+- `add_shape()` / `add_control()`은 저수준 탈출구라, 그대로 저장하면 한/글이
+  열지 못하는 파일이 됩니다(호출 시 경고만 나옵니다). 도형은 `add_line()` /
   `add_rectangle()` / `add_ellipse()`를 쓰세요.
-- 그림은 단순 개체 생성까지 지원하며, 그룹·효과 같은 복잡 개체 생성은 미지원입니다.
+- 그림은 단순 개체 생성까지 지원합니다 (그룹·효과 미지원).
 - 암호화된 HWPX는 지원하지 않습니다.
 
 ## 기여하기
@@ -204,11 +217,12 @@ print(report.preservation.untouched_part_payloads.to_dict())
 [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 재패킹 같은 실전 지식을 정리해 두었습니다.
+공개 API의 안정 범위는 [안정 API 표면](docs/stable-api.md), 계층 간 소유권은
+[제품 경계 문서](docs/architecture/product-boundary.md)에 있습니다.
 
 ## 감사의 말
 

{python_hwpx-5.0.1 → python_hwpx-5.1.1}/README.md

@@ -15,26 +15,33 @@
 
 <p align="center">한국어 | <a href="README_EN.md">English</a></p>
 
-기존 문서는 손댄 곳만 고치고(미수정 영역은 바이트 그대로), 새 문서는 실제
-한컴오피스가 받아들이는 형태로 만듭니다. HWPX는 ZIP+XML(OWPML/OPC) 구조라
-Windows·macOS·Linux·CI 어디서든 순수 파이썬으로 동작합니다. 한컴오피스도
-Windows도 필요하지 않으므로 **ChatGPT 채팅 환경에서도 HWPX 문서를 만들고
-고칠 수 있습니다** — 파이썬이 도는 곳이면 됩니다.
+한컴오피스가 없어도 됩니다. HWPX는 ZIP+XML(OWPML) 포맷이라 순수 파이썬만으로
+읽고, 고치고, 새로 만들 수 있습니다 — Windows·macOS·Linux·CI, 그리고
+**파이썬이 도는 ChatGPT 채팅 안에서도** 그대로 동작합니다. 기존 문서는 손댄
+곳만 바뀌고 나머지는 바이트 그대로 유지되며, 새 문서는 실제 한컴오피스가 여는
+형태로 만들어집니다.
 
-| 계층 | 저장소 | 정본 책임 |
-|---|---|---|
-| Core | [`python-hwpx`](https://github.com/airmang/python-hwpx) | HWPX package/object model·OPC/OXML·직렬화·재사용 primitive |
-| Automation | [`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation) | Python 자동화·워크플로·profile/policy·렌더·선택형 MCP adapter |
-| Judgment | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) | 에이전트 intent/genre 판단·ambiguity 처리·plugin/skill 가이드 |
+<p align="center">
+  <img src="https://raw.githubusercontent.com/airmang/python-hwpx/main/docs/assets/chatgpt-formfill.png" width="760" alt="일반 ChatGPT 대화에 hwpx 양식을 올려 지도안 작성을 부탁하고, 양식이 유지된 채 채워진 문서를 돌려받는 화면">
+</p>
+<p align="center"><sub>일반 ChatGPT 대화 — 양식 <code>.hwpx</code>를 올리고 말로 부탁하면, 서식을 유지한 채 채워진 문서가 돌아옵니다.</sub></p>
 
-이 저장소는 위 표의 Core 정본입니다. 5.0의 모듈 소유권, 삭제 경로 재등장
-방지, 의존성 허용 범위는
-[제품 경계 문서](docs/architecture/product-boundary.md)에 고정돼 있습니다.
+**ChatGPT에서 그대로 따라 하기** — 문서를 올리면서 이렇게 부탁하면 됩니다:
 
-> **Python 블록 판정:** 이 current manual의 모든 Python 블록은
-> [실행 분류 ledger](docs/python-example-ledger.json)에 exact source digest와 함께
-> 동결돼 있습니다. **독립 실행 예제** 표시가 없는 블록은 기존 입력 파일이나 앞
-> 문맥을 요구하는 조각이며, 그대로 실행할 수 있는 예제로 간주하지 않습니다.
+```text
+이 .hwpx 파일을 python-hwpx 라이브러리로 열어서 작업해줘.
+(pip install python-hwpx 로 설치하면 돼)
+양식과 서식은 그대로 두고, ○○만 바꿔서 새 파일로 돌려줘.
+```
+
+설치부터 결과 파일까지 대화 안에서 끝납니다 — 내 컴퓨터에 파이썬이 없어도 됩니다.
+AI 도구가 정확한 API를 배우도록 [llms.txt](https://airmang.github.io/python-hwpx/llms.txt)도 제공합니다.
+
+| | 저장소 | 역할 |
+|---|---|---|
+| 📦 | [`python-hwpx`](https://github.com/airmang/python-hwpx) | HWPX 문서를 읽고·고치고·만드는 순수 파이썬 엔진 |
+| 🔌 | [`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation) | 저작·양식 채움 워크플로, `hwpx` CLI, 선택형 MCP 서버 |
+| 🎯 | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) | 에이전트가 알맞은 도구를 고르도록 돕는 플러그인/스킬 번들 |
 
 ## 시작하기
 
@@ -42,11 +49,6 @@ Windows도 필요하지 않으므로 **ChatGPT 채팅 환경에서도 HWPX 문
 pip install python-hwpx      # Python 3.10+
 ```
 
-> **5.x 호환 extra:** `pip install "python-hwpx[visual]"`은 기존 설치 명령을
-> 깨뜨리지 않기 위해 계속 허용되지만, `visual` extra는 비어 있어 PDF·이미지
-> 렌더링 의존성을 설치하지 않습니다. 렌더·PDF 이미징 실행은
-> `python-hwpx-automation[oracle]`이 소유합니다.
-
 ```python
 from hwpx import HwpxDocument
 
@@ -55,23 +57,24 @@ doc.add_paragraph("자동화로 추가한 문단입니다.")
 doc.save_to_path("보고서-수정.hwpx")
 ```
 
-백지에서 새 문서를 만들 때는 `HwpxDocument.new()`로 시작해 같은 API로
-문단·표·머리말을 채우고 `save_to_path()`로 저장합니다.
-
-문서 저작·양식 채움·시험지 조판 같은 상위 워크플로가 필요하면
+백지에서 시작할 때는 `HwpxDocument.new()`로 만들어 같은 API로 문단·표·머리말을
+채우면 됩니다. 문서 저작·양식 채움·시험지 조판 같은 상위 워크플로가 필요하면
 [`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation)을
-함께 설치하세요. MCP SDK 없이 같은 환경에서 그대로 동작합니다.
+함께 설치하세요.
+
+> 기존 설치 명령 호환을 위해 `pip install "python-hwpx[visual]"`도 계속
+> 동작합니다. 다만 이 extra는 비어 있어 렌더·PDF 의존성을 설치하지 않습니다 —
+> 그 역할은 `python-hwpx-automation[oracle]`이 맡습니다.
 
 ## 무엇을 하나
 
-- **읽기·추출** — 텍스트/HTML/rich Markdown 내보내기(서식·중첩 표·각주 보존), XPath 객체 탐색
-- **편집** — 문단·표·이미지·머리글/바닥글·메모·각주, 줄간격·여백·쪽번호 등 서식
-- **양식 채우기** — 라벨·경로 기반 셀 채움, 바이트 보존 구조 편집(행·열·오토핏·shrink-to-fit)
-- **생성·일괄 처리** — 문단·표·이미지·목차·상호참조 저작, 명시적 sanitizer 기반 mail merge, 텍스트 diff
-- **변경추적·목차** — redline 저작, 네이티브 목차·상호참조
-- **검증·안전** — 패키지 구조 검증 CLI, 열림 안전 게이트, 모든 쓰기에 영수증(`MutationReport`) — 번들 XSD는 느슨한 구조 스키마이며 OWPML 전체 검증은 아닙니다
+- **읽기·추출** — 텍스트/HTML/Markdown 내보내기 (서식·중첩 표·각주 보존)
+- **편집** — 문단·표·이미지·머리글/바닥글·메모·각주, 줄간격·여백·쪽번호 같은 서식
+- **양식 채우기** — 라벨로 셀을 찾아 값만 채우기, 행·열 조정 같은 구조 편집도 바이트 보존으로
+- **생성·일괄 처리** — 새 문서 저작, 목차·상호참조, mail merge, 텍스트 diff, 변경추적(redline)
+- **검증·안전** — 패키지 구조 검증 CLI, 열림 안전 게이트, 모든 저장에 영수증(`MutationReport`)
 
-자세한 내용: [사용 가이드](docs/usage.md) · [API 레퍼런스](https://airmang.github.io/python-hwpx/) · [안정 API 표면](docs/stable-api.md) · [예제](docs/examples.md)
+자세한 내용: [5분 퀵스타트](docs/quickstart.md) · [사용 가이드](docs/usage.md) · [API 레퍼런스](https://airmang.github.io/python-hwpx/) · [예제](docs/examples.md)
 
 ### 양식 채우기 — 서식은 그대로, 값만
 
@@ -96,22 +99,31 @@ print(report.preservation.untouched_part_payloads.to_dict())
 ```
 
 요청한 보존 등급을 지킬 수 없으면 아무것도 쓰지 않고 실패합니다(fail-closed).
-전체 규칙은 [안전한 쓰기 계약](docs/safe-write-contract.md)에 있습니다.
+전체 규칙: [안전한 쓰기 계약](docs/safe-write-contract.md).
+
+*예제 중 **독립 실행 예제** 표시가 없는 블록은 여러분의 기존 문서를 입력으로
+쓰는 조각입니다. 예제별 Python 블록 판정은
+[실행 ledger](docs/python-example-ledger.json)에 동결돼 있습니다.*
 
 ## 실측으로 말합니다
 
-산출물 전수를 실제 한컴오피스로 측정해 그대로 공개합니다(동결 코퍼스 N=497):
+만든 파일이 실제 한컴오피스에서 열리는지, 동결 코퍼스 전수(N=497)를 재서
+그대로 공개합니다:
 
-- **한컴 오픈 476/476 all-pass** — 우리가 만든 파일을 실한컴이 전부 엽니다
-- **미수정 영역 바이트 보존 497/497** · 개인정보 0-leak
-- **렌더 검증 416/476** + 정직 버킷 43 — 한컴 자체가 PDF export를 거부한 케이스도 숨기지 않고 집계
-- 낮은 숫자도 그대로 발행합니다 — 전체 수치·주의사항: [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html)
+- **한컴 열림 476/476** — 우리가 만든 파일을 실한컴이 전부 엽니다
+- **미수정 영역 바이트 보존 497/497** · 개인정보 유출 0
+- **렌더 검증 416/476** — 한컴 자체가 PDF 내보내기를 거부한 43건도 숨기지 않고 집계
+- 전체 수치와 주의사항: [실측 코퍼스 메트릭](https://airmang.github.io/python-hwpx/corpus-metrics.html) · 기능별 등급: [지원 매트릭스](docs/support-matrix.md)
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/airmang/python-hwpx/main/docs/assets/hancom-open-generated.png" width="760" alt="ChatGPT 실행 환경에서 python-hwpx로 생성한 HWPX 문서를 실제 한컴오피스에서 연 모습">
+</p>
+<p align="center"><sub>ChatGPT 실행 환경에서 생성한 문서를 실제 한컴오피스로 연 모습.</sub></p>
 
-기능별로 되는 것과 안 되는 것은 [지원 매트릭스](docs/support-matrix.md)에 등급으로
-명시되어 있습니다. 현재 개발 상태는 Alpha입니다 — API는 바뀔 수 있습니다.
+현재 개발 상태는 Alpha입니다 — API는 바뀔 수 있습니다.
 
-> 위 수치는 *생성물 수용률* 축입니다(만든 파일을 실한컴이 받는가). 문서 *파싱 recall*과는
-> 다른 축이므로 파서 프로젝트 수치와 병치 비교하지 마세요.
+> 위 수치는 "만든 파일을 실한컴이 받아주는가"라는 축입니다. 문서 파싱 성능과는
+> 다른 축이므로 파서 프로젝트 수치와 직접 비교하지 마세요.
 
 ## 어디서 쓰나
 
@@ -124,11 +136,10 @@ print(report.preservation.untouched_part_payloads.to_dict())
 | Codex 마켓플레이스 플러그인 | [`hwpx-plugins`](https://github.com/airmang/hwpx-plugins) 설치 |
 | Claude Code · Hermes · OpenClaw | 같은 MCP 서버를 각 클라이언트에 등록 ([`python-hwpx-automation`](https://github.com/airmang/python-hwpx-automation)) |
 
-실측: 일반 ChatGPT 대화에 `.hwpx`를 올리고 python-hwpx 설치를 요청했을 때 PyPI
-설치가 성공했고, 문서를 편집해 되받았습니다. 다만 파이썬 실행과 네트워크 허용
-범위는 플랜·설정에 따라 다르므로 모든 계정에서 보장되는 경로는 아닙니다.
-네트워크가 막힌 실행 환경에서는 wheel 파일을 함께 업로드하면 오프라인 설치로
-같은 여정이 됩니다.
+실제로 일반 ChatGPT 대화에 `.hwpx`를 올리고 설치를 부탁했을 때 PyPI 설치와
+편집·되받기까지 동작하는 것을 확인했습니다. 파이썬 실행과 네트워크 허용 범위는
+플랜·설정에 따라 다르며, 네트워크가 막힌 환경에서는 wheel 파일을 함께 올리면
+오프라인 설치로 같은 여정이 됩니다.
 
 ## 비교
 
@@ -144,11 +155,10 @@ print(report.preservation.untouched_part_payloads.to_dict())
 
 ## 알려진 제약
 
-- `add_shape()` / `add_control()`은 한/글이 요구하는 모든 하위 요소를 생성하지 않는
-  저수준 탈출구입니다. 그대로 저장한 문서는 한/글이 열지 못하며, 신호는 호출 시점의
-  경고 하나뿐입니다(저장도 패키지 검증도 막지 않습니다). 도형은 `add_line()` /
+- `add_shape()` / `add_control()`은 저수준 탈출구라, 그대로 저장하면 한/글이
+  열지 못하는 파일이 됩니다(호출 시 경고만 나옵니다). 도형은 `add_line()` /
   `add_rectangle()` / `add_ellipse()`를 쓰세요.
-- 그림은 단순 개체 생성까지 지원하며, 그룹·효과 같은 복잡 개체 생성은 미지원입니다.
+- 그림은 단순 개체 생성까지 지원합니다 (그룹·효과 미지원).
 - 암호화된 HWPX는 지원하지 않습니다.
 
 ## 기여하기
@@ -156,11 +166,12 @@ print(report.preservation.untouched_part_payloads.to_dict())
 [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 재패킹 같은 실전 지식을 정리해 두었습니다.
+공개 API의 안정 범위는 [안정 API 표면](docs/stable-api.md), 계층 간 소유권은
+[제품 경계 문서](docs/architecture/product-boundary.md)에 있습니다.
 
 ## 감사의 말
 

{python_hwpx-5.0.1 → python_hwpx-5.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "5.0.1"
+version = "5.1.1"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"
@@ -21,8 +21,11 @@ classifiers = [
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Software Development :: Libraries",
     "Topic :: Text Processing :: Markup :: XML",
+    "Typing :: Typed",
 ]
 dependencies = [
     "lxml>=4.9,<7",

{python_hwpx-5.0.1 → python_hwpx-5.1.1}/src/hwpx/_document/fields.py

@@ -211,10 +211,16 @@ def _form_field_payload(
         name = _field_parameter_value(parameters, "fieldName", "fieldname", "field_name", "name", "title")
     prompt = _first_attr(field_begin, _FORM_FIELD_PROMPT_ATTRS)
     if not prompt:
-        prompt = _field_parameter_value(parameters, *_FORM_FIELD_PARAM_NAMES)
+        # "Direction" is the real-Hancom 안내문 parameter (P0 gold contract).
+        prompt = _field_parameter_value(parameters, "Direction", *_FORM_FIELD_PARAM_NAMES)
     instruction = _field_parameter_value(parameters, "instruction", "guide", "help", "description", "desc")
     if not instruction:
         instruction = prompt
+    memo = _field_parameter_value(parameters, "HelpState", "memo")
+    dirty = (field_begin.get("dirty") or "").strip()
+    # Contract: while dirty != "1" the content between begin/end is the prompt
+    # placeholder (screen-only, not printed), not a user value.
+    is_placeholder = dirty != "1" and bool(prompt) and current_value == prompt
     return {
         "index": index,
         "field_id": _field_identifier(field_begin),
@@ -223,9 +229,13 @@ def _form_field_payload(
         "name": name,
         "prompt": prompt,
         "instruction": instruction,
+        "memo": memo,
+        "dirty": dirty,
+        "is_placeholder": is_placeholder,
         "current_value": current_value,
         "field_type": field_begin.get("type", ""),
         "control_type": ctrl.get("type", ""),
+        "_field_begin": field_begin,
         "section_index": section_index,
         "paragraph_index": paragraph_index,
         "paragraph_index_in_section": paragraph_index_in_section,
@@ -320,6 +330,62 @@ def list_form_fields(doc: "HwpxDocument") -> list[dict[str, Any]]:
     ]
 
 
+_PROMPT_TEXT_COLOR = "#FF0000"
+
+
+def add_form_field(
+    doc: "HwpxDocument",
+    name: str,
+    *,
+    prompt: str = "",
+    memo: str = "",
+    editable: bool = True,
+    paragraph: Any | None = None,
+    section: Any | None = None,
+    section_index: int | None = None,
+) -> dict[str, Any]:
+    """Create a click-here (누름틀) form field and return its field payload.
+
+    The emitted XML follows the real-Hancom CLICKHERE contract
+    (reverse-engineered from Hancom Office 12.0.0.3288 gold documents). The
+    prompt (안내문) is materialized as a screen-only red-italic run, exactly as
+    Hancom authors it. The created field is immediately re-read through the
+    standard ``list_form_fields`` matcher — creation fails loudly if the
+    standard consumer would not recognize it (no special-casing by design).
+    """
+
+    if not str(name).strip():
+        raise ValueError("form field name must be a non-empty string")
+    if paragraph is None:
+        paragraph = doc.add_paragraph(
+            "", section=section, section_index=section_index, include_run=False,
+        )
+
+    prompt_char_pr: str | None = None
+    if _sanitize_field_text(prompt):
+        prompt_char_pr = doc.ensure_run_style(italic=True, color=_PROMPT_TEXT_COLOR)
+
+    control = paragraph.add_form_field(
+        name,
+        prompt=prompt,
+        memo=memo,
+        editable=editable,
+        prompt_char_pr_id_ref=prompt_char_pr,
+    )
+    _clear_form_field_layout_cache(paragraph.element)
+
+    field_begin = control.element.find(f"{_HP}fieldBegin")
+    created_id = field_begin.get("id", "") if field_begin is not None else ""
+    for match in _iter_form_field_matches(doc):
+        if match.get("id") == created_id:
+            return {
+                key: value for key, value in match.items() if not key.startswith("_")
+            }
+    raise RuntimeError(
+        "created form field was not recognized by the standard form-field matcher"
+    )
+
+
 def _select_form_field(
     doc: "HwpxDocument",
     matches: Sequence[dict[str, Any]],
@@ -447,9 +513,23 @@ def fill_form_field(
             node.text = ""
             for child in list(node):
                 child.tail = ""
+        if match.get("is_placeholder"):
+            # Contract (P0 gold): Hancom swaps the screen-only prompt style for
+            # the surrounding style when a value replaces the placeholder.
+            begin_run = runs[int(match["_begin_run_index"])]
+            begin_ref = begin_run.get("charPrIDRef")
+            primary_run = primary.getparent()
+            if begin_ref is not None and primary_run is not None:
+                primary_run.set("charPrIDRef", begin_ref)
     else:
         _insert_form_field_text_run(doc, match, sanitized)
 
+    # Contract (P0 gold): a field that went through fill machinery carries
+    # dirty="1"; while dirty != "1" readers treat the content as the prompt.
+    field_begin = match.get("_field_begin")
+    if field_begin is not None:
+        field_begin.set("dirty", "1")
+
     if fit_result is not None:
         _apply_form_field_fit_style(doc, match, fit_result)
 

{python_hwpx-5.0.1 → python_hwpx-5.1.1}/src/hwpx/document.py

@@ -1388,6 +1388,48 @@ class HwpxDocument:
             section_index=section_index,
         )
 
+    def add_form_field(
+        self,
+        name: str,
+        *,
+        prompt: str = "",
+        memo: str = "",
+        editable: bool = True,
+        paragraph: HwpxOxmlParagraph | None = None,
+        section: HwpxOxmlSection | None = None,
+        section_index: int | None = None,
+    ) -> dict[str, Any]:
+        """Create a click-here (누름틀) form field. **Experimental contract.**
+
+        Emits the real-Hancom CLICKHERE shape (안내문 placeholder run included)
+        so the created field is indistinguishable from a Hancom-authored one:
+        ``list_form_fields``/``fill_form_field`` recognize it with no
+        special-casing, and real Hancom Office enumerates and fills it.
+
+        Args:
+            name: Field name (non-empty).
+            prompt: 안내문 shown while the field is empty. Screen-only —
+                Hancom does not print it.
+            memo: Help text (``HelpState``).
+            paragraph: Target paragraph (e.g. inside a table cell). When
+                omitted a new paragraph is appended to *section*.
+
+        Returns:
+            The created field's payload, same shape as a ``list_form_fields``
+            entry.
+        """
+
+        return _fields.add_form_field(
+            self,
+            name,
+            prompt=prompt,
+            memo=memo,
+            editable=editable,
+            paragraph=paragraph,
+            section=section,
+            section_index=section_index,
+        )
+
 
     def set_page_size(
         self,