python-hwpx 6.1.0__tar.gz → 6.3.0__tar.gz

{python_hwpx-6.1.0/src/python_hwpx.egg-info → python_hwpx-6.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 6.1.0
+Version: 6.3.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0

{python_hwpx-6.1.0 → python_hwpx-6.3.0}/pyproject.toml

@@ -1,10 +1,10 @@
 [build-system]
-requires = ["setuptools==83.0.0", "wheel==0.47.0"]
+requires = ["setuptools==84.0.0", "wheel==0.48.0"]
 build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "6.1.0"
+version = "6.3.0"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"

{python_hwpx-6.1.0 → python_hwpx-6.3.0}/src/hwpx/_document/ns/parts.py

@@ -25,9 +25,11 @@ from ...errors import HwpxValueError
 from ...oxml._document_primitives import _HH
 from ...oxml.header_compat import (
     apply_paragraph_auto_spacing as _apply_paragraph_auto_spacing,
+    remove_license_mark as _remove_license_mark,
     set_compatible_document_target_program as _set_compatible_document_target_program,
     set_doc_option_link_info as _set_doc_option_link_info,
     set_layout_compatibility_flags as _set_layout_compatibility_flags,
+    set_license_mark as _set_license_mark,
 )
 from ._base import _Namespace
 
@@ -215,6 +217,29 @@ class PartsNamespace(_Namespace):
             footnote_inherit=footnote_inherit,
         )
 
+    def set_license_mark(
+        self,
+        *,
+        mark_type: str,
+        flag: int,
+        lang: int | None = None,
+    ) -> None:
+        """`hh:docOption/hh:licensemark` 설정("입력 > CCL 넣기…"가 남기는
+        문서 수준 라이선스 레코드). 실측 gold는
+        `type="CCL" flag="0" lang="6"` — 스키마가 `type`을 `xs:unsignedInt`
+        로 선언하는데도 실물은 문자열이라 `mark_type`이 `str`이다.
+
+        눈에 보이는 CC 배지는 별개다 — 라이선스 증서 URL을 `href`로 단
+        평범한 그림(`add_picture`)이고, 이 setter는 문서 수준 레코드만
+        건드린다."""
+
+        _set_license_mark(self._primary_header(), mark_type=mark_type, flag=flag, lang=lang)
+
+    def remove_license_mark(self) -> bool:
+        """`hh:docOption/hh:licensemark`를 지운다. 실제로 지웠으면 True."""
+
+        return _remove_license_mark(self._primary_header())
+
     def set_paragraph_auto_spacing(
         self,
         para_pr_id: str | int,

{python_hwpx-6.1.0 → python_hwpx-6.3.0}/src/hwpx/capabilities.py

@@ -432,6 +432,55 @@ _CAPABILITY_AREAS: tuple[dict[str, Any], ...] = (
         "entry_points": ("hwpx.document:HwpxDocument",),
         "authoring_methods": (),
     },
+    {
+        "area": "index-mark",
+        "namespace": "doc.refs",
+        "matrix_row": "색인 표시",
+        # P4 — 팀장 실한컴 GUI 프로브 gold 2건(1키/2키) 역설계.
+        # HwpxOxmlParagraph.add_index_mark만 있다(HwpxDocument 루트에는
+        # 없음) — title-mark와 같은 이유로 authoring_methods=(). title-mark
+        # 와 같은 doc.refs 네임스페이스(둘 다 "본문 문단에 다는 색인/차례
+        # 계열 마크")지만 별도 영역이다: 겨냥하는 요소도(hp:indexmark vs
+        # hp:titleMark) 편집기 메뉴도 다르고, 한 영역에 묶으면 매트릭스
+        # 등급 하나로 두 기능의 검증 상태를 뭉개게 된다(toc-crossref의
+        # "혼합 지원 영역 오염" 방지 원칙).
+        "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": (),
+    },
+    {
+        "area": "mail-merge-field",
+        "namespace": "doc.fields",
+        "matrix_row": "메일머지 표시 필드",
+        # P4 — 팀장 실한컴 GUI 프로브 gold 역설계. 기존 "mail-merge"
+        # 영역에 합치지 않고 새로 만든 이유: 그 영역은 namespace=None ·
+        # 진입점이 순수 모듈 함수(hwpx.tools.mail_merge:merge_template_rows) ·
+        # 등급이 Edit(기존 hp:t 텍스트 치환, 새 요소를 안 만든다)인 반면
+        # 이쪽은 doc.fields 문단 메서드 · Create(hp:fieldBegin
+        # type="MAILMERGE"를 새로 만든다)다 — 합치면 한 영역이 두 진입
+        # 경로·두 등급을 갖는 "혼합 지원 영역 오염"이 된다(toc-crossref에서
+        # 하이퍼링크·책갈피를 떼어낸 것과 같은 판단). 행 제목도 기존 행이
+        # "placeholder 템플릿 배치 생성"으로 스코프를 명시하고 있어 이
+        # 기능을 담을 수 없다. date-time-proofreading-mark-fields와 같은
+        # field_marks.py·같은 hp:fieldBegin 계열이지만 그쪽에 합류시키지
+        # 않은 것도 같은 이유다 — 그 행은 "입력 > 필드" 계열 3종이고
+        # 메일머지 표시는 "도구 > 메일 머지" 메뉴다.
+        "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": (),
+    },
+    {
+        "area": "license-mark",
+        "namespace": "doc.parts",
+        "matrix_row": "라이선스 표시(CCL)",
+        # P4 — 팀장 실한컴 GUI 프로브 gold 역설계. doc.parts.set_license_
+        # mark/remove_license_mark는 set_* 이름이라 document-options-
+        # compatibility·document-metadata와 같은 이유로
+        # authoring_methods=(). 트레인㊺가 "CCL 전용 요소는 없다, 그림+
+        # 하이퍼링크 조합일 뿐"이라고 판정했던 자리를 실측이 뒤집었다 —
+        # hh:licensemark는 실제로 이 메뉴가 쓰는 전용 문서 수준 레코드다
+        # (배지 그림은 그 판정대로 별개의 hp:pic+href).
+        "entry_points": ("hwpx.document:HwpxDocument",),
+        "authoring_methods": (),
+    },
 )
 
 #: 패키지에 동봉되는 계약 문서 이름 → 파일. MCP resources 표면의 원천.

{python_hwpx-6.1.0 → python_hwpx-6.3.0}/src/hwpx/data/contract_docs/support-matrix.md

@@ -39,6 +39,7 @@
 | 각주/미주 | Edit·Create·Render-verified | `add_footnote`·`add_endnote`; M6 읽기 경로에서 note 노출. 5.5.0에서 실한컴 gold 계약으로 방출 수리(본문 run 내 `hp:ctrl` 래핑·`number`/`suffixChar`·각주 본문 `autoNum`+스타일 15/16) — 옛 방출이 각주를 그리지 않던 실결함 종결, 리더는 실한컴산·구식 양형상 모두 수용(CHANGELOG [5.5.0]) |
 | 네이티브 목차(TOC)/상호참조 | Create·Render-verified | `hwpx.tools.toc_author.add_native_toc`·`mark_toc_dirty`·`toc_verify`; corpus-metrics「네이티브 목차」구조 15/15, 실한컴 재계산 후 페이지 정합 5/5 |
 | 차례 숨기기·제목 차례 표시 | Create(experimental)·Render-verified | `HwpxOxmlParagraph.add_title_mark(in_toc=)`(6.15 트레인, DEV-044). 스키마는 `hp:titleMark`를 `hp:t`의 선택군 자식으로 실제 선언하되(`ignore: xs:boolean, default="false"`) `xs:documentation`이 전혀 없어 의미는 미문서화 — 실코퍼스 14건(전부 `ignore="1"`, 차례 페이지 항목 문단의 헤딩 텍스트 미러 run 바로 앞)으로 구조는 6.13에 이미 확정됐으나, 캐럿이 있는 문단에 정확히 들어간다는 타겟팅 계약은 이 환경의 자동화 한계(캔버스 클릭·키 입력 모두 문서에 미도달)로 실측이 안 돼 저작을 보류하고 있었다. **6.15**: 팀장의 Windows 박스 COM `SetPos`+`MarkTitle`/`HideTitle` 3변형(`SetPos(0,2,0)`+`MarkTitle`→p2에만 `ignore="1"`, `SetPos(0,2,0)`+`HideTitle`→p2에만 `ignore="0"`, `SetPos(0,1,0)`+`MarkTitle`→p1에만 `ignore="1"`)이 타겟팅을 확정 — 마크는 항상 캐럿이 있는 문단의 첫 run 첫 `hp:t` 맨 앞, 그 문단 자신의 텍스트 바로 앞에 들어간다(이전 Mac 프로브의 절 정의 문단 착지는 캐럿 이동 불가에 따른 퇴화 현상이었음이 확인됨). 폴라리티는 이름의 직관과 반대(`in_toc=True`="제목 차례 표시"→`ignore="1"`, `in_toc=False`="차례 숨기기"→`ignore="0"`) — Mac GUI A/B와 Windows COM 양쪽에서 독립 재확인. 호출자가 대상 문단을 직접 지정하는 API 형태가 실 편집기의 "캐럿 문단" 타겟팅과 정확히 대응한다. 실한컴 렌더 검증: `docs/openrate/report-v21.json` authored-title-mark 스트라텀(극성 로테이션·단일/두-표제 문서·양쪽 표제 반대 극성 동시 표시·기존 charPr 합성 각 1건, 5건), macOS Hancom GUI 오라클 5/5 render_checked·0 render_failed(2026-08-15 측정) |
+| 색인 표시 | Create(experimental) | `HwpxOxmlParagraph.add_index_mark(first, second=)`(P4). 팀장 실한컴(HWP 13.0.0.3901) GUI 프로브 gold 2건(`tests/fixtures/gui_probes/index_mark_first_only.hwpx`=1단계 키만, `index_mark_two_keys.hwpx`=2단계 키까지) 역설계. 배치는 `add_title_mark`와 **다르다** — titleMark는 `hp:t` 안에 들어가지만 indexmark는 같은 run 안의 `hp:ctrl` 형제로 텍스트 **앞**에 선다(`<hp:run><hp:ctrl><hp:indexmark><hp:firstKey>apple</hp:firstKey></hp:indexmark></hp:ctrl><hp:t>apple item paragraph.</hp:t></hp:run>`). 타겟팅 계약은 같다 — 호출자가 대상 문단을 직접 지정하는 형태가 실 편집기의 "캐럿이 있는 문단"과 대응한다. **스키마 편차**: `ParaList XML schema.xml:209-216`은 `firstKey`/`secondKey`를 둘 다 필수 시퀀스로 선언하는데(속성 0개, 두 키 모두 무타입) 실물은 1단계 색인에서 `secondKey`를 아예 생략한다 — `add_new_num`의 `autoNumFormat` 생략과 같은 부류로 실측을 따랐다(빈 문자열 키는 생략과 방출 XML이 달라져 typed 거부). 코퍼스 실사용 0건 — 계약 근거는 GUI 프로브 gold 전부. 실한컴 렌더 검증: `docs/openrate/report-v22.json` authored-index-mark 스트라텀(1키/2키/두 문단 독립 마크/**한 문단 2마크(관측 밖 경계)**/커스텀 charPr 표제 합성, 5건), macOS Hancom GUI 오라클 5/5 render_checked·0 render_failed(2026-08-18 측정) — 관측 밖 조합 포함 전량 수용 |
 | 암호화 HWPX | Unsupported-and-rejected | 복호화 API 없음. 암호화된 content part는 파싱 단계에서 예외(`XMLSyntaxError`)로 거부 — 무음으로 잘못된 문서를 만들지 않음(fail-closed) |
 | HWP 5.x 바이너리 | Unsupported-and-rejected | HWP v5는 ZIP이 아니므로 열기 시 `BadZipFile` 예외. OLE2/CFBF 시그니처를 확인하면 예외 메시지가 HWPX 변환을 안내한다(예외 타입은 그대로) |
 | 누름틀(form field) 생성 | Parse·Edit·Create(experimental)·Render-verified | `list_form_fields`·`fill_form_field`로 조회·서식 보존 채움에 더해, `doc.fields.add`(구 `add_form_field`, 5.1.0+)가 실한컴 CLICKHERE 계약 그대로 신규 누름틀을 생성한다(표 셀 배치 포함). 만든 필드는 기존 list/fill과 실제 한컴이 특수분기 없이 소비. 실한컴 렌더 검증: `docs/openrate/report-v15.json` authored-formfield 스트라텀(prompt/memo/editable 로테이션 + 표 셀 배치 1건, 5건), macOS Hancom GUI 오라클 5/5 render_checked·0 render_failed(2026-08-08 측정) — 이 영역의 첫 독립 실한컴 판정. **원장 라우팅은 없음** — `hp:fieldBegin`은 CLICKHERE/TOC/CROSSREF/하이퍼링크/메모가 공유하는 저수준 요소라 여전히 미등록(무근거 승격 회피 원칙) — 등급 갱신은 이 산문과 report-v15.json 직접 인용으로만 |
@@ -49,6 +50,7 @@
 | 바탕쪽 | Parse·Create(experimental)·Render-verified | `doc.parts.master_pages`(읽기, 6.4 트레인⑮)·`.add_master_page`(쓰기, 6.13 트레인㊻) + `doc.page.set_master_page`/`.master_page_refs`(절 참조 배선, `section_format.py`). 편집기 메뉴 표면 역매핑(트레인㊷)이 [부분 대응](읽기만, 쓰기 없음)으로 지목한 갭 — `HwpxOxmlMasterPage` 자신의 독스트링이 "읽기 전용... 쓰기 경로는 열지 않는다"고 명시했던 6.4 트레인⑮의 의도적 스코프 축소를 이번에 닫는다. 유일한 실 예시(`error__20250808__2015년_12월_재난안전종합상황_분석_및_전망.hwpx`)로 역설계: 파트 파일명·매니페스트 `opf:item id`·`masterPage` 루트 자신의 `id`·절의 `hp:masterPage/@idRef` 넷 다 **같은 문자열**("masterpage0")을 쓴다. 매니페스트에 이 파트는 있으나 spine `opf:itemref`는 없다(바탕쪽은 읽기 순서 파트가 아니다). `hp:secPr`의 자식 시퀀스에서 `hp:masterPage`는 맨 끝(pageBorderFill들 뒤)에 오고 `masterPageCnt`가 그 개수와 일치 — `SectionProperties.add_master_page_reference`가 그대로 append(멱등, 중복 idRef 무시)·카운트 동기화. `masterPage`의 `hp:subList`는 `textWidth`/`textHeight`를 실 예시가 페이지 여백에서 계산한 값으로 쓰지만 그 공식을 역산할 근거가 1건으로는 없어 다른 subList 빌더의 정직한 기본값("0")을 그대로 둔다(curve와 같은 원칙). 신규 바탕쪽이 여러 절 사이에서 공유/독립되는 관행 자체는 실증 근거가 없어 "파트 하나 생성 + 호출자가 지정한 절마다 명시적 배선"이라는 최소 계약만 제공한다. 실한컴 렌더 검증: `docs/openrate/report-v17.json` authored-master-page 스트라텀(page_type/page_number/page_duplicate/page_front 로테이션 + 두 번째 바탕쪽 생성으로 파트 인덱스 자동증가 확인, 5건), macOS Hancom GUI 오라클 5/5 render_checked·0 render_failed(2026-08-11 측정) — **패키지에 새 파트를 싣는 쓰기 경로가 실한컴을 통과한 첫 확인**(이전에 자체 발견·수리한 매니페스트 dirty 결함의 반증이기도 하다) |
 | 날짜/시간·교정 부호·파일 이름 필드 | Create(experimental)·Render-verified | `HwpxOxmlParagraph.add_date_field`/`.add_proofreading_mark`/`.add_path_field`(`oxml/field_marks.py`, 6.13 트레인㊻+6.14 트레인㊽b). 팀장 실한컴 macOS GUI 프로브①③(2026-08-11) gold(`tests/fixtures/gui_probes/date_and_proofreading_mark.hwpx`) 역설계 — `add_hyperlink`의 3-run 격리와 달리 세 필드 다 단일 `hp:run` 안에 `ctrl(begin)`/`t`/`ctrl(end)`을 나란히 담는다(선택군 반복 허용은 DEV-017이 이미 확인). **날짜/시간**(`type="DATE"`): `id`/`fieldid` 독립 난수·`dirty="0"`(TOC와 달리 재계산 트리거 아님)·`hp:parameters`(`Prop=8`·`Command`=포맷 미리보기 문자열·`DateNation`="KOR"·`DateFormat`="YYYY년 M월 D일") — 관측 포맷 1건뿐이라 이 값만 지원(typed 거부, curve·connectLine과 같은 원칙), 캐시 텍스트는 호출자가 계산해 넘긴다. **교정 부호**(`type="PROOFREADING_MARKS_SIGN"`): 스키마 선언값(`PROOFREADING_MARKS`)과 실측이 달라 **DEV-043**으로 등재 — `hp:parameters`(`Prop=0`·`Command="$RevisionSign;N;"`, 캐시 텍스트 없음), 인덱스가 확인된 건 "띄움표"(N=1) 하나뿐이라 그것만 지원(대화상자 21종 중 나머지 20종은 인덱스-기호 대응표 근거 없음). **파일 이름**(`type="PATH"`, 6.14 트레인㊽b): GUI 프로브 불필요 — 트레인㊺가 이미 확보한 실 코퍼스 계약(`tests/fixtures/markdown_export/99_all_in_one_stress.hwpx`, 페이지 머리말 안) 그대로. `hp:parameters`(`Prop=8`=DATE와 공유값·`Command`=`Format`=`"$F"` 리터럴 고정), 캐시 텍스트는 관측 예시에서 파일명 그대로(호출자가 계산해 넘김, 전체 경로인지 파일명뿐인지조차 표본 1건으로는 확정 못 함). 이 세 필드를 정밀 대조하다 `hp:fieldEnd`가 `beginIDRef` 말고도 `fieldid`(fieldBegin 자신의 `fieldid`와 같은 값)를 반복해서 갖는다는 사실도 새로 확인 — 날짜/교정 부호의 기존 구현엔 이게 빠져 있었다(이미 v18 실한컴이 수용은 했으나 gold와 완전히 일치시키려 세 필드 전부 소급 수정). 실한컴 렌더 검증: `docs/openrate/report-v18.json` authored-date-field·authored-proofreading-marks 두 스트라텀(cached_text/배치/반복/char_pr_id_ref/표제 합성 로테이션 각 5건, 표 합성 포함, 10건), macOS Hancom GUI 오라클 10/10 render_checked·0 render_failed(2026-08-11 측정) — **팀장 자신의 GUI 리버스로 확보한 계약이 같은 편집기로 되돌려 검증된** 첫 사례(계약 출처와 검증 오라클이 동일 애플리케이션). 파일 이름 필드는 `docs/openrate/report-v19.json` authored-path-field 스트라텀(cached_text/배치/반복/char_pr_id_ref/표제 합성 로테이션, 5건 — fieldEnd/@fieldid 소급 수정을 실제로 담은 첫 배치), macOS Hancom GUI 오라클 5/5 render_checked·0 render_failed(2026-08-11 측정)로 마찬가지로 검증 완료 |
 | 문서 옵션·호환성 | Parse·Preserve·Edit·Render-verified | `doc.parts.set_compatible_document_target_program`·`set_layout_compatibility_flags`·`set_doc_option_link_info`·`set_paragraph_auto_spacing`(6.6+). 읽기는 5.x부터(`hh:compatibleDocument`/`docOption`, cycle 6.1 `settings.py`/`header.py`) — 6.6이 쓰기 쪽. 실코퍼스 47/47 리버스로 계약 확정: `compatibleDocument@targetProgram`은 `"HWP201X"`만 관측·`layoutCompatibility`는 플래그 0개(스키마 48종 선언 대비)·`docOption/linkinfo`는 `path` 항상 빈 문자열·`footnoteInherit` 항상 `"0"`·`pageInherit`만 실제로 갈림(8/47 `"1"`). `hh:paraPr/hh:autoSpacing`은 `_apply_paragraph_margins`/`_apply_paragraph_line_spacing`이 이미 쓰는 자손-순회 관용구를 재사용하지만, 그 둘과 달리 실 autoSpacing은 `hp:switch`로 안 감싸인다(1832/1832 직속 자식, DEV-018과 대조 확인). 불리언은 전부 `"0"`/`"1"`(DEV-006과 같은 관례, `"true"`/`"false"` 0건). `HwpxOxmlHeader`의 owner 파일(`header_part.py`)이 1600줄 캡에 헤드룸이 없어(1599/1600) 새 모듈(`oxml/header_compat.py`)의 자유함수로 산다. 실한컴 렌더 검증: `docs/openrate/report-v10.json` authored-compat 스트라텀, macOS Hancom GUI 오라클 15/15 render_checked·0 render_failed(2026-08-07 측정) — **관측 밖 조합(targetProgram=HWP2018·실제 layoutCompatibility 플래그·footnoteInherit=1·비어있지 않은 linkinfo path) 전부 포함해서도 15/15 수용**, 즉 실한컴의 실제 수용 경계가 실코퍼스 관측 분포보다 넓다는 게 확인됐다(모든 프로브 축에서 거부 0건) |
+| 라이선스 표시(CCL) | Parse·Create | `doc.parts.set_license_mark(mark_type=, flag=, lang=)`/`.remove_license_mark()`(`oxml/header_compat.py`, P4). 팀장 실한컴 GUI 프로브 gold(`tests/fixtures/gui_probes/license_mark_ccl.hwpx`, "입력 > CCL 넣기…") 역설계 — `hh:docOption` 안 `hh:linkinfo` 바로 뒤 형제로 `<hh:licensemark type="CCL" flag="0" lang="6"/>`. **트레인㊺의 판정("CCL 전용 요소는 없다, 그림+하이퍼링크 조합일 뿐")을 실측이 뒤집었다** — 코퍼스 67파일 0건이라 실사용 근거가 없었을 뿐, 이 메뉴는 실제로 전용 문서 수준 레코드를 쓴다(배지 그림이 별개라는 그 판정의 나머지 절반은 맞다 — 배지는 라이선스 증서 URL을 `href`로 단 평범한 `hp:pic`이고, 이 setter는 문서 수준 레코드만 건드린다). **스키마 편차**: `Header XML schema.xml`의 `DocOptionType`은 `type`을 `xs:unsignedInt use="required"`로 선언하는데 실물은 문자열 `"CCL"`이다 — 스키마만 보고 `int`로 선언돼 있던 읽기 모델(`LicenseMark.type`)은 실한컴 CCL 문서를 `to_model()`로 읽는 순간 `ValueError: Invalid integer value: 'CCL'`로 터졌고, 이 트레인이 실측을 따라 `str`로 고쳤다(DEV-043과 같은 실측 우선 부류). `flag`/`lang`은 관측 `0`/`6`이라 정수 유지 — 관측이 1건뿐이라 값 범위는 강제하지 않는다(`set_compatible_document_target_program`과 같은 원칙, `mark_type` 빈 문자열만 typed 거부). 실한컴 렌더 검증: `docs/openrate/report-v22.json` authored-license-mark 스트라텀(관측값 CCL/0/6·flag/lang 변주·**미관측 type 문자열 "KOGL"(경계)**·재설정 멱등, 5건), macOS Hancom GUI 오라클 5/5 render_checked·0 render_failed(2026-08-18 측정) — 미관측 type 문자열도 수용(수용 경계가 관측 분포보다 넓다) |
 | 페이지 레이아웃(용지·여백·머리말/꼬리말·쪽번호·단·줄번호·격자·요소 숨김) | Edit·Create·Render-verified | `doc.page`(6.8 트레인㉚ 등재, 코드 자체는 이전 사이클부터 존재). 최초 5개(`set_visibility`/`set_line_numbers`/`set_grid`/`restart_page_number`/`hide_page_elements` → `hp:visibility`/`hp:lineNumberShape`/`hp:grid`/`hp:newNum`/`hp:pageHiding`, `docs/openrate/report-v4.json` authored-page-structure·`report-v6.json` authored-pagecontrol, 각 15/15 render_checked)에 이어 **6.9 트레인㉜**이 나머지 실질 표면을 마저 검증: `set_size`/`set_margins`/`set_header`/`set_footer`/`set_page_number`/`set_columns` → `hp:pagePr`/`hp:margin`/`hp:header`/`hp:footer`/`hp:colPr`/`hp:pageNum`, `docs/openrate/report-v12.json` authored-pagelayout 15/15 render_checked·0 render_failed(2026-08-07 측정, header 제거 경로도 이 배치에서 함께 확인). 11개 요소 전부 `by-capability-area+openrate-corpus`. **남은 정직한 여백**: `hp:autoNum`은 각주/목록류 자동번호와 공유하는 요소라 의도적으로 미등록(실제 표시 요소인 `hp:pageNum`은 검증됨, DEV류 무근거 승격 회피 원칙과 동일), `setup()`은 위 이미 검증된 setter들을 그대로 호출하는 합성 편의 메서드라 별도 프로브가 없다, `remove_footer`는 `remove_header`와 대칭이나 v12가 이름으로 지목한 건 후자뿐이다. **6.12 트레인㊸ 갭③**이 `text_direction`/`set_text_direction`(`hp:secPr` 자신의 `textDirection`/`textVerticalWidthHead` 속성, 편집기 메뉴 표면 역매핑이 찾은 신규 갭)을 추가했다 — 실코퍼스 67파일 전수(모든 fixture 하위 디렉터리) 측정: `hp:secPr` 74건 전부 `textDirection="HORIZONTAL"`·`textVerticalWidthHead="0"`, `VERTICAL`/`VERTICALALL` 실사용 0건. 그래도 이 값은 새 구조를 추측하는 게 아니라 스키마가 명확히 선언한 열거값(`HORIZONTAL`/`VERTICAL`/`VERTICALALL`)을 이미 정상 파싱·직렬화되는 기존 요소(`hp:secPr`)에 그대로 쓰는 것뿐이라 구조적 추측 위험이 없다. 실한컴 렌더 검증: `docs/openrate/report-v16.json` authored-text-direction 스트라텀(`VERTICAL`×2·`VERTICALALL`×2·명시적 `HORIZONTAL`×1, `vertical_header_footer` True/False 조합), macOS Hancom GUI 오라클 5/5 render_checked·0 render_failed(2026-08-10 측정) — **이 실코퍼스(67파일 전수)에 실사용 0건이던 `VERTICAL`/`VERTICALALL`이 이 프로젝트에서 실한컴을 통과한 첫 문서**다. **원장 라우팅은 없음**: `textDirection`은 요소가 아니라 속성이고, 그 부모 `hp:secPr` 자체는 모든 문서에 항상 존재하는 컨테이너(위 5+6개 자식 요소를 이미 개별 등록)라 `hp:secPr`를 통째로 등록하면 이 값을 한 번도 안 건드린 문서까지 전부 위양성 처리된다 |
 | 문자 서식(굵게·기울임·밑줄·글꼴·크기·색 등) | Edit·Create·Render-verified | `doc.styles.ensure_run`(6.8 트레인㉚ 등재, 코드는 이전 사이클부터 존재 — `hh:charPr`는 이미 "문단·표 저작/편집" 영역이 요소째 소유하고 있어 이 영역은 캐파빌리티 키워드 배선 없이 매트릭스 산문으로만 근거를 남긴다). **17/17 키워드 인자 전부 실한컴 증거 확보 완결(6.12 트레인㊶)**: `bold`/`color`/`size`(`docs/openrate/report-v4.json` authored-named-style, 10/10 render_checked), `outline`/`emboss`/`engrave`/`script`(sup/sub, `docs/openrate/report-v7.json` authored-charformat, 15/15 render_checked), `underline`/`underline_shape`/`underline_color`/`strike`/`strike_shape`/`ratio`/`letter_spacing`/`shadow`(`docs/openrate/report-v14.json` authored-charformat2, 5/5 render_checked, 2026-08-08), 그리고 마지막 잔존이던 `italic`(v14의 authored-charformat2 뱅크가 빠뜨렸던 항목 — `docs/openrate/report-v15.json` authored-charformat-italic 스트라텀, italic 단독+bold/underline/color 조합, macOS Hancom GUI 오라클 5/5 render_checked·0 render_failed, 2026-08-08 측정)까지 전부 확보됐다. `base_char_pr_id`는 XML 요소가 아니라 파이썬 레벨 조합 방식(기존 charPr 복제 후 오버라이드)이라 이 17개 카운트에서 애초에 제외(등록 대상 없음), `highlight`는 별도 매트릭스 행("형광펜(하이라이트)")이 이미 독립적으로 Render-verified라 이 행의 카운트에 안 넣는다 — 두 제외 사유 모두 이 행 초판부터 일관됨 |
 | 목록 서식(글머리표·번호매기기) | Create·Edit·Render-verified | `doc.styles.apply_list_format`/`.ensure_numbering`(6.8 트레인㉚ 등재, 코드는 이전 사이클부터 존재). 실한컴 렌더 검증: `docs/openrate/report-v14.json` authored-listformat 스트라텀(bullet/number kind × level 1·2 로테이션, bullet_char/number_format/start 오버라이드), macOS Hancom GUI 오라클 5/5 render_checked·0 render_failed(2026-08-08 측정) — 이 영역의 첫 독립 실한컴 판정. `hh:bullet`/`bullets`/`numbering`/`numberings`/`paraHead`가 원장에 새로 등록됐다(6.11 트레인㊳, 이전엔 대응 capabilityArea 자체가 없었다) — `hh:heading`(paraPr 안에서 numbering/bullet을 가리키는 polymorphic idRef)은 document_merge 등 다른 경로도 공유하는 저수준 요소라 의도적으로 미등록. **6.13 트레인㊻**: `ensure_numbering`/`apply_list_format`이 세 번째 `kind="outline"`을 받는다 — `hh:heading type="OUTLINE"`이 이 목록 서식과 **같은** `hh:numbering`/`hh:paraHead` id-space를 쓴다는 사실(`bind_outline_level`, `_document/headings.py`)을 그대로 재사용해, `add_heading`/`apply_paragraph_format(outline_level=)`이 항상 고정 `idRef="0"`(스켈레톤 개요 스타일)만 참조하던 것과 달리 **커스텀 개요 번호 모양**(numFormat/start)을 만들 길을 연다. 실코퍼스 67파일 전수: `hh:heading type="OUTLINE"` 451건 전부 `idRef="0"`뿐이라 커스텀 idRef 조합은 실코퍼스 밖이지만 — 재사용하는 `hh:numbering`/`hh:paraHead` 구조 자체는 v14에서 이미 render-verified라 구조적 추측 위험은 없었고, 이번에 실측으로도 확인됐다: `docs/openrate/report-v17.json` authored-outline-numbering 스트라텀(level/numFormat/start 로테이션 + 기존 `apply_paragraph_format(outline_level=)` 수준 증가와 합성한 1건, 5건), macOS Hancom GUI 오라클 5/5 render_checked·0 render_failed(2026-08-11 측정) — 합성 레코드가 "`apply_paragraph_format(outline_level=)`이 paraPr을 새로 만들 때마다 `idRef="0"`을 하드코딩해 커스텀 번호 모양을 무음으로 덮어쓴다"는 기존 동작(버그 아님, 충실 재현)도 같이 실증했다. `apply_paragraph_format(outline_level=)`을 통한 개요 적용/해제·수준 증감은 코드가 이미 완비돼 있었다(신규 코드 없음, 이번 트레인이 확인만 함) |
@@ -57,6 +59,7 @@
 | 찾아바꾸기 | Edit·Render-verified | `doc.text.replace`/`.find_runs`(6.8 트레인㉚ 등재, 코드는 이전 사이클부터 존재). 실한컴 렌더 검증: `docs/openrate/report-v14.json` authored-findreplace 스트라텀(무제한 치환 + `char_pr_id_ref`로 좁힌 스타일 한정 치환 교대), macOS Hancom GUI 오라클 5/5 render_checked·0 render_failed(2026-08-08 측정). **원장 라우팅은 없음** — 기존 `hp:t` 텍스트만 치환할 뿐 새 요소를 안 만든다(document-merge·mail-merge·table-navigation-fill과 같은 이유) — 등급 갱신은 이 산문과 report-v14.json 직접 인용으로만 |
 | 하이퍼링크·책갈피 | Create·Render-verified | `doc.refs.add_hyperlink`/`.add_bookmark`(6.8 트레인㉚에서 "네이티브 목차(TOC)/상호참조" 영역에서 분리 — 그 영역의 Render-verified 근거는 TOC 구조·페이지 정합뿐이라 하이퍼링크·책갈피를 한 번도 독립적으로 커버한 적이 없었다, 편집기 표면 인벤토리 트레인㉙ 발견). **6.9 트레인㉜**: `docs/openrate/report-v12.json` authored-hyperlink-bookmark 스트라텀(북마크 생성 후 외부 URL/문서 내 `#앵커` 하이퍼링크 교대), macOS Hancom GUI 오라클 15/15 render_checked·0 render_failed(2026-08-07 측정) — 이 영역의 첫 독립 실한컴 판정. `hp:bookmark`는 요소 직접 등록(`by-openrate-corpus`), `hp:fieldBegin`(하이퍼링크 자신의 컨트롤)은 CLICKHERE/TOC/CROSSREF와 공유하는 저수준 요소라 여전히 요소 등록 없음 — 영역 등급만 실측으로 갱신, 원장 오염 경로는 그대로 차단 |
 | 메일머지(placeholder 템플릿 배치 생성) | Edit·Render-verified | `hwpx.tools.mail_merge.merge_template_rows`(6.8 트레인㉛ 등재, 코드는 이전 사이클부터 존재 — 편집기 표면 인벤토리 트레인㉙·계층 판정 트레인㉚이 찾을 때까지 캐파빌리티·매트릭스 어디에도 등재가 없었다). `{{field}}`/`${field}`/`<<field>>` 세 플레이스홀더 문법을 지원하는 템플릿 1개 + 행 데이터(csv/json/시퀀스)로 문서 N개를 배치 생성 — 기존 `hp:t` 텍스트를 치환하는 것이라 새 요소를 만들지 않는다(Create가 아니라 Edit). `strict`/`fit_policy`/`value_sanitizer` 등 운영 옵션 다수. 실한컴 렌더 검증: `docs/openrate/report-v13.json` authored-mailmerge 스트라텀(세 플레이스홀더 문법 각각 겨냥하는 전용 템플릿으로 회전), macOS Hancom GUI 오라클 10/10 render_checked·0 render_failed(2026-08-08 측정) — 이 영역의 첫 독립 실한컴 판정 |
+| 메일머지 표시 필드 | Create(experimental) | `HwpxOxmlParagraph.add_mail_merge_field(name, cached_text=)`(`oxml/field_marks.py`, P4). 팀장 실한컴 GUI 프로브 gold(`tests/fixtures/gui_probes/mailmerge_display_fields.hwpx`, "도구 > 메일 머지 > 메일 머지 표시 달기"로 필드 2개 삽입) 역설계 — 위 「메일머지(placeholder 템플릿 배치 생성)」가 **기존 `hp:t` 텍스트를 치환**하는 Edit인 것과 달리 이쪽은 `hp:fieldBegin type="MAILMERGE"` 자체를 새로 만드는 Create다(그래서 별도 영역). DATE/PATH와 같은 단일 run 안 `ctrl(begin)`/`t`/`ctrl(end)` 배치에 더해 **끝에 빈 `hp:t`가 하나 더** 붙고(gold 2/2), `hp:fieldBegin`에 `metaTag` 속성이 **없다**(DATE/교정 부호/PATH gold는 셋 다 `metaTag=""`) — 필드 종류마다 실측이 갈리는 유일한 속성. `hp:parameters`(`cnt="5"`): `Fiexde=1`(**오타 철자가 실물·한컴 공식 문서 공통의 정본이라 정정 금지** — `trackchageConfig`·memo의 `NOMAL`과 같은 부류) · `Prop=8`(DATE/PATH와 같은 캐시 필드류 공유값) · `Command`/`FieldValue`가 둘 다 필드 이름 그대로 · `FieldType="USER_DEFINE"`. 캐시 텍스트 기본값 `{{이름}}`은 `hwpx.tools.mail_merge`가 인식하는 플레이스홀더 문법이라 이 필드로 저작한 템플릿이 그 배치 생성기에 그대로 물린다. gold의 두 필드는 `id`가 다른데 `fieldid`는 같은 값을 공유하나, 표본이 문서 하나뿐이라 채번 규칙을 역산할 근거가 없어 DATE/PATH와 같은 독립 난수를 쓴다. 실한컴 렌더 검증: `docs/openrate/report-v22.json` authored-mailmerge-field 스트라텀(단일/2필드/커스텀 캐시/**한글 필드명(경계)**/표 셀 안 필드, 5건), macOS Hancom GUI 오라클 5/5 render_checked·0 render_failed(2026-08-18 측정) |
 | 문서 끼워 넣기(문서 병합) | Create·Render-verified | `hwpx.tools.document_merge.append_document`/`.insert_document`(6.9 트레인㉝ v1, 6.10 트레인㊱ v2 — 편집기 표면 인벤토리 트레인㉙의 macOS 메뉴 전수 스캔이 찾은 신규 갭, "입력→문서 끼워 넣기…"). 다른 HWPX 문서의 본문을 연 문서에 끼워 넣는다 — 핵심은 헤더가 소유한 8개 공유 자원(charPr/paraPr/style/borderFill/tabPr/numbering·bullet/memoPr/fontfaces)을 원본에서 새 id로 복제해 재매핑하는 것이지 단순 복사가 아니다(그대로 복사하면 대상 문서의 기존 id를 조용히 가로챈다). 한컴 편집기 실측(팀장, 2026-08-07): "입력→문서 끼워 넣기…" 패널의 4개 고유 옵션(글자 모양 유지·스타일 유지·쪽 모양 유지·문단 모양 유지, 기본값 전부 해제=흡수)이 정책 축의 실측 근거. v2는 이 4축을 한컴과 같은 이름의 매개변수(`keep_character_shape`/`keep_style`/`keep_paragraph_shape`/`keep_page_shape`)로 노출한다 — 기본값은 v1의 기출하·실검증 동작과 동일(글자·스타일·문단 모양=유지, 쪽 모양=흡수), 반대 방향은 매핑 실측이 없어 typed 오류로 정직 거부(과설계 안 함). v2는 MEMO 병합도 지원한다(DEV-042): `hp:memogroup`은 절 레벨 형제라 원본의 모든 절에서 참조된 `hp:memo`를 찾아 복제, 새 메모 id 채번 후 body 문단 복제본과 같은 리스트로 묶어 기존 축1 재매핑(charPr/paraPr/style/memoShapeIDRef)에 그대로 태운다. 실측으로 찾은 결함 8건을 수정(v1 6건 + v2 2건): 스타일 자신의 기본 charPr/paraPr 누락, `HwpxOxmlDocument.char_properties` 캐시 미무효화, `linkListIDRef`/`linkListNextIDRef` 과잉거부(팀장 독립 검증 — 벤더드 코퍼스 5,891/5,891건이 전부 "0" 관용값인데 존재만으로 거부해 표가 든 모든 문서, 우리 자신의 `add_table` 산출물 포함, 병합이 불가능했다), 저장 경로 dirty-tracking 미설정(가장 심각 — `target_header.mark_dirty()`를 호출하지 않아 헤더에 새로 추가한 요소가 저장 시 조용히 누락되는데, 그림이 있는 병합만 우연히 `add_image`의 부수효과로 가려져 있었다), `hp:secPr` 제거가 통째 run을 지워 표·텍스트까지 함께 삭제(실코퍼스 표 문서에서 secPr·표·텍스트가 한 run에 공존, 수정 후 secPr만 개별 제거), 새 id 채번 순서가 프로세스마다 비결정적(`set` 순회를 `sorted()`로 교체), `check_id_integrity` 자신의 `memoShapeIDRef="0"` 오탐(fresh 문서의 secPr 스켈레톤 기본값을 memo_shapes 테이블이 채워지는 순간부터 댕글링으로 오판 — 병합과 무관한 사전 존재 결함, `id_integrity.py`의 `_ALLOWED_SENTINELS`로 수정), `hp:fieldEnd`의 `fieldid` 미재생성(원본 문서의 raw uuid4().hex 값이 복사된 내용에 그대로 남음 — v14 생성기 자체 결정성 검사로 발견, `begin_fieldid_map`으로 수정). `hp:connectLine`(스마트 연결선)·`chartIDRef`·실체인 `linkListIDRef`가 있으면 fail-closed 거부. 참조 무결성은 재발명하지 않고 기존 `hwpx.tools.id_integrity.check_id_integrity`로 검증(설계 문서: `docs/2026-08-08-document-merge-contract.md`). 실한컴 렌더 검증: `docs/openrate/report-v13.json` authored-docmerge 스트라텀(v1, 10건 중 4건이 표 포함 — 위 결함 셋이 전부 표 병합에서 터졌던 형태를 정면으로 겨냥), macOS Hancom GUI 오라클 10/10 render_checked·0 render_failed(2026-08-08 측정). v2(4축 매개변수+MEMO 병합)는 `docs/openrate/report-v14.json` authored-docmerge2 스트라텀(단일 메모/센티널 기본값/대상 기존 memogroup 합류/표 동반 4갈래, 4축 기본값 명시통과 호출), macOS Hancom GUI 오라클 5/5 render_checked·0 render_failed(2026-08-08 측정)로 검증 완료. 6.15: 클론 경로 감사(속성-클론 중첩 참조 앨리어싱 수리, `b81713e`)의 후속으로 v20(`cross-real-merge`, 우리 자신이 생성한 문서가 아니라 실한컴이 저장한 문서끼리 병합 — v13의 성긴 헤더로는 이 앨리어싱 결함이 애초에 안 보였을 것이라는 지적)을 실행: 실 문서 3종 쌍방향 병합·중간 삽입 3건·필드 보유 소스 2종·3단 연쇄 병합 12건, macOS Hancom GUI 오라클 12/12 render_checked·0 render_failed(2026-08-12 측정) — 앨리어싱 수리 후 재현이 사라졌음을 실 소스로 재확인. 세 버전 모두 같은 스트라텀 그룹(document_merge)이라 원장 라우팅은 여전히 없음(위 산문 근거만) |
 | 덧말·글자 겹치기 | Parse·Create·Render-verified | `doc.shapes.add_dutmal`/`.add_composed_character`(6.9 트레인㉞). `hp:compose`(글자 겹치기/원문자·합자)는 읽기 모델이 이전 사이클(commit `6f88e2e`)부터 있었으나 저작 API·캐파빌리티 등재가 없었다 — 이번에 `add_composed_character`로 채우고 같은 `body.ComposedCharacter`/`_composed_character_to_xml` 경로를 저작에도 재사용(파싱·저작 한 코드 경로). `hp:dutmal`(덧말)은 이번에 처음 리버스엔지니어링 — 실코퍼스 표본 정확히 1건(`reader_writer__SimpleDutmal.hwpx`, hwpxlib 왕복 픽스처), macOS 편집기 메뉴 전수 스캔(트레인㉙)이 1급 메뉴 항목임은 확인했으나 그 이상의 빈도 근거는 없다 — 정직 고지. 그 1건이 스키마의 두 주장을 직접 반증한다(`option`은 스키마상 `fixed="4"`인데 실측 `"0"`, `szRatio`는 `xs:positiveInteger`인데 실측 `"0"` — DEV-041). 저작 API는 이 실측값을 기본값으로 채택하고 스키마 주장을 검증 규칙으로 강제하지 않는다. 둘 다 `hp:t`의 자식이 아니라 `hp:run` 직속(스키마 문서 순서와 실제 위치가 다름, 실코퍼스로 확인). 실한컴 렌더 검증: `docs/openrate/report-v13.json` authored-dutmal-compose 스트라텀(dutmal 기본값을 실측값 그대로 두고 검증 — 스키마 주장이 아니라 우리 채택을 오라클이 판정), macOS Hancom GUI 오라클 10/10 render_checked·0 render_failed(2026-08-08 측정) — `hp:compose`/`hp:dutmal`/`hp:mainText`/`hp:subText` 4개 요소 전부 원장에 `by-openrate-corpus` 반영(코드-쓰기 분류기가 `_qualified_tag(tag, "literal")`류 관용구를 못 잡던 갭도 이번에 수동 override로 같이 메움) |
 
@@ -86,6 +89,7 @@
 | 각주/미주 | `doc.notes` |
 | 네이티브 목차(TOC)/상호참조 | `doc.refs` |
 | 차례 숨기기·제목 차례 표시 | `doc.refs` |
+| 색인 표시 | `doc.refs` |
 | 암호화 HWPX | 미지원 |
 | HWP 5.x 바이너리 | 미지원 |
 | 누름틀(form field) 생성 | `doc.fields` |
@@ -96,6 +100,7 @@
 | 바탕쪽 | `doc.parts`/`doc.page` |
 | 날짜/시간·교정 부호·파일 이름 필드 | `doc.fields` |
 | 문서 옵션·호환성 | `doc.parts` |
+| 라이선스 표시(CCL) | `doc.parts` |
 | 페이지 레이아웃(용지·여백·머리말/꼬리말·쪽번호·단·줄번호·격자·요소 숨김) | `doc.page` |
 | 문자 서식(굵게·기울임·밑줄·글꼴·크기·색 등) | `doc.styles` |
 | 목록 서식(글머리표·번호매기기) | `doc.styles` |
@@ -104,6 +109,7 @@
 | 찾아바꾸기 | `doc.text` |
 | 하이퍼링크·책갈피 | `doc.refs` |
 | 메일머지(placeholder 템플릿 배치 생성) | 모듈 — `hwpx.tools.mail_merge` |
+| 메일머지 표시 필드 | `doc.fields` |
 | 문서 끼워 넣기(문서 병합) | 모듈 — `hwpx.tools.document_merge` |
 | 덧말·글자 겹치기 | `doc.shapes` |
 

{python_hwpx-6.1.0 → python_hwpx-6.3.0}/src/hwpx/oxml/_document_primitives.py

@@ -200,8 +200,12 @@ def _refresh_copied_paragraph_subtree_ids(paragraph: ET.Element) -> None:
         }:
             node.set("id", _object_id())
 
-        if "instId" in node.attrib:
-            node.set("instId", _object_id())
+        # 스키마·실한컴 산출물의 속성명은 소문자 "instid"다. 과거 이 코드가
+        # 방출한 "instId"(카멜케이스)를 실은 파일도 재발급 대상에 남긴다 —
+        # 속성명 자체는 보존(바이트 보수), 값만 재발급.
+        for inst_attr in ("instid", "instId"):
+            if inst_attr in node.attrib:
+                node.set(inst_attr, _object_id())
 
 
 def _clone_paragraph_element(paragraph: ET.Element) -> ET.Element:

{python_hwpx-6.1.0 → python_hwpx-6.3.0}/src/hwpx/oxml/body.py

@@ -32,7 +32,10 @@ INLINE_OBJECT_NAMES = {
     "ole",
     "chart",
     "video",
-    "audio",
+    # "audio"는 제외 — 실한컴(Windows 한글 2024 실측)은 소리 삽입을
+    # hp:ole(EMBEDDED/ICON)로 방출하고 hp:audio를 생성하지 않으며, 보유
+    # 실코퍼스 표본도 0건이다. 실물 미검증 요소를 인라인 읽기 지원으로
+    # 분류하지 않는다(빈도 0 = 읽기측 불투명 보존만). python-hwpx#89.
     "textart",
 }
 

{python_hwpx-6.1.0 → python_hwpx-6.3.0}/src/hwpx/oxml/field_marks.py

@@ -60,6 +60,35 @@ GUI 프로브 불필요했다. 구조는 DATE와 동형(단일 run, 캐시 텍
 **v1 스코프**: ``Command``/``Format`` 둘 다 이 관측값("$F") 하나만
 지원(typed 거부) -- 포맷 코드 문법을 역산할 근거가 없는 건 DATE의
 ``Command`` 미리보기 문자열과 같은 사정이다.
+
+## 메일머지 표시 필드(``type="MAILMERGE"``)
+
+실측 gold(``tests/fixtures/gui_probes/mailmerge_display_fields.hwpx``,
+"도구 > 메일 머지 > 메일 머지 표시 달기"로 필드 2개를 삽입)가 위 세
+필드와 다른 점 셋:
+
+* ``hp:fieldBegin``에 ``metaTag`` 속성이 **없다**(DATE/교정 부호/PATH
+  gold는 셋 다 ``metaTag=""``를 달고 있다) -- ``_field_begin``의
+  *meta_tag* 인자가 그 차이만 담당한다.
+* ``hp:parameters``(``cnt="5"``)의 첫 파라미터가 ``hp:booleanParam``이고
+  이름이 ``"Fiexde"``다 -- **오타 철자가 실물·한컴 공식 문서 공통의
+  정본**이라 고쳐 쓰면 안 된다(``trackchageConfig``·memo의 ``NOMAL``과
+  같은 부류). 나머지는 ``Prop=8``(DATE/PATH와 같은 "캐시 필드"류 공유
+  값) · ``Command``/``FieldValue``가 둘 다 필드 이름 그대로 ·
+  ``FieldType="USER_DEFINE"``.
+* ``ctrl(end)`` 뒤에 **빈 ``hp:t``가 하나 더** 붙는다(gold 2/2 필드 모두).
+  용도를 역산할 근거는 없으나 실측이 일관되므로 그대로 재현한다 --
+  캐시 텍스트를 넣는 ``hp:t``와 달리 내용이 없다.
+
+캐시 텍스트 기본값은 ``"{{이름}}"``(gold 실측 관행, ``hwpx.tools.
+mail_merge``가 치환 대상으로 인식하는 세 문법 중 하나) -- DATE/PATH와
+달리 여기선 우리가 계산할 수 있는 값이라(필드 이름만으로 결정된다)
+호출자에게 떠넘기지 않는다.
+
+``fieldid``: gold의 두 필드는 ``id``가 서로 다른데 ``fieldid``는 같은
+값을 공유한다(``627928423``). 표본이 문서 하나뿐이라 이게 "필드 종류당
+1개"인지 "문서당 1개"인지 역산할 근거가 없어, DATE/PATH와 같은
+독립 난수 채번을 그대로 쓴다(실한컴도 ``id``≠``fieldid``인 건 같다).
 """
 
 from __future__ import annotations
@@ -80,6 +109,7 @@ __all__ = [
     "PROOFREADING_MARKS",
     "PATH_FORMATS",
     "create_date_field",
+    "create_mail_merge_field",
     "create_proofreading_mark_field",
     "create_path_field",
 ]
@@ -104,7 +134,9 @@ PATH_FORMATS: dict[str, str] = {
 }
 
 
-def _field_begin(field_type: str) -> tuple[ET.Element, ET.Element, str, str]:
+def _field_begin(
+    field_type: str, *, meta_tag: bool = True
+) -> tuple[ET.Element, ET.Element, str, str]:
     """``hp:ctrl > hp:fieldBegin`` -- 관측된 고정 속성 그대로.
 
     Returns ``(ctrl, fieldBegin, field_id, field_ref_id)`` -- *field_id*는
@@ -112,11 +144,15 @@ def _field_begin(field_type: str) -> tuple[ET.Element, ET.Element, str, str]:
     ``fieldid``, ``id``와는 독립 난수)는 ``fieldEnd``의 ``fieldid``에
     그대로 쓴다(둘 다 실측 gold에 있는 속성 -- 값이 다른데도 fieldEnd가
     양쪽을 다 반복해서 갖는다).
+
+    *meta_tag*: ``metaTag=""``를 다는지. DATE/교정 부호/PATH gold는 셋 다
+    달고 있고 MAILMERGE gold는 없다 -- 필드 종류마다 실측이 갈리는
+    유일한 속성이라 여기서만 분기한다(모듈 독스트링 참조).
     """
     field_id = _object_id()
     field_ref_id = _object_id()
     ctrl = ET.Element(f"{_HP}ctrl")
-    begin = _append_child(ctrl, f"{_HP}fieldBegin", {
+    attributes = {
         "id": field_id,
         "type": field_type,
         "name": "",
@@ -124,8 +160,10 @@ def _field_begin(field_type: str) -> tuple[ET.Element, ET.Element, str, str]:
         "dirty": "0",
         "zorder": "-1",
         "fieldid": field_ref_id,
-        "metaTag": "",
-    })
+    }
+    if meta_tag:
+        attributes["metaTag"] = ""
+    begin = _append_child(ctrl, f"{_HP}fieldBegin", attributes)
     return ctrl, begin, field_id, field_ref_id
 
 
@@ -242,6 +280,55 @@ def create_path_field(
     return [ctrl_begin, text_el, ctrl_end]
 
 
+def create_mail_merge_field(
+    name: str,
+    *,
+    cached_text: str | None = None,
+) -> list[ET.Element]:
+    """메일머지 표시 필드(``type="MAILMERGE"``) 요소열을 만든다.
+
+    *name*은 데이터 열 이름("도구 > 메일 머지 > 메일 머지 표시 달기"
+    대화상자의 필드 이름)이고, ``Command``/``FieldValue`` 두 파라미터에
+    그대로 실린다. *cached_text*를 생략하면 ``"{{name}}"`` --
+    ``hwpx.tools.mail_merge.merge_template_rows``가 치환 대상으로 인식하는
+    플레이스홀더 문법이라, 이 필드로 저작한 템플릿이 그 배치 생성기에
+    그대로 물린다.
+
+    반환값은 한 run에 순서대로 append할 요소 리스트
+    (``[ctrl(begin), t, ctrl(end), t(빈 것)]``) -- 마지막 빈 ``hp:t``까지
+    실측 gold 그대로다(모듈 독스트링 참조).
+    """
+    if not name:
+        from ..errors import HwpxValueError
+
+        raise HwpxValueError(
+            "mail merge field name must be a non-empty string",
+            code="field-mail-merge-empty-name",
+            context={"name": name},
+            suggestion='데이터 열 이름을 주세요 -- 예: add_mail_merge_field("name").',
+        )
+
+    ctrl_begin, begin, field_id, field_ref_id = _field_begin("MAILMERGE", meta_tag=False)
+    params = _append_child(begin, f"{_HP}parameters", {"cnt": "5", "name": ""})
+    # "Fiexde"는 실물·한컴 공식 문서 공통의 오타 철자다 -- 고치지 않는다.
+    fixed = _append_child(params, f"{_HP}booleanParam", {"name": "Fiexde"})
+    fixed.text = "1"
+    prop = _append_child(params, f"{_HP}integerParam", {"name": "Prop"})
+    prop.text = "8"
+    command = _append_child(params, f"{_HP}stringParam", {"name": "Command"})
+    command.text = _sanitize_text(name)
+    field_type = _append_child(params, f"{_HP}stringParam", {"name": "FieldType"})
+    field_type.text = "USER_DEFINE"
+    field_value = _append_child(params, f"{_HP}stringParam", {"name": "FieldValue"})
+    field_value.text = _sanitize_text(name)
+
+    text_el = ET.Element(f"{_HP}t")
+    text_el.text = _sanitize_text(cached_text if cached_text is not None else f"{{{{{name}}}}}")
+
+    ctrl_end = _field_end(field_id, field_ref_id)
+    return [ctrl_begin, text_el, ctrl_end, ET.Element(f"{_HP}t")]
+
+
 def _append_field_elements(
     paragraph: "HwpxOxmlParagraph",
     elements: list[ET.Element],
@@ -308,3 +395,15 @@ def _paragraph_add_path_field(
     """파일 이름 필드를 이 문단에 삽입한다."""
     elements = create_path_field(cached_text, path_format=path_format)
     return _append_field_elements(self, elements, char_pr_id_ref=char_pr_id_ref)
+
+
+def _paragraph_add_mail_merge_field(
+    self: "HwpxOxmlParagraph",
+    name: str,
+    *,
+    cached_text: str | None = None,
+    char_pr_id_ref: str | int | None = None,
+) -> "HwpxOxmlInlineObject":
+    """메일머지 표시 필드를 이 문단에 삽입한다."""
+    elements = create_mail_merge_field(name, cached_text=cached_text)
+    return _append_field_elements(self, elements, char_pr_id_ref=char_pr_id_ref)

{python_hwpx-6.1.0 → python_hwpx-6.3.0}/src/hwpx/oxml/header.py

@@ -34,7 +34,20 @@ class LinkInfo:
 
 @dataclass(slots=True)
 class LicenseMark:
-    type: int
+    """``hh:docOption/hh:licensemark`` — 문서 수준 라이선스 레코드.
+
+    ``type``이 ``str``인 건 실측이다: 스키마(``Header XML schema.xml``의
+    ``DocOptionType``)는 ``xs:unsignedInt use="required"``라고 선언하지만
+    실한컴(HWP 13.0.0.3901)이 실제로 쓰는 값은 ``"CCL"``이라는 문자열이다
+    (gold ``tests/fixtures/gui_probes/license_mark_ccl.hwpx``). 이전
+    ``int`` 선언은 스키마만 보고 정한 것이라, 실한컴이 만든 CCL 문서를
+    ``to_model()``로 읽으면 ``ValueError: Invalid integer value: 'CCL'``로
+    터졌다 — 저작 쪽(``header_compat.set_license_mark``)을 열면서 실측으로
+    드러났다. 실측 우선 원칙(DEV-043과 같은 부류)에 따라 값은 그대로
+    보존한다. ``flag``/``lang``은 관측값이 ``"0"``/``"6"``이라 정수 그대로.
+    """
+
+    type: str
     flag: int
     lang: Optional[int]
 
@@ -989,8 +1002,12 @@ def parse_link_info(node: etree._Element) -> LinkInfo:
 
 
 def parse_license_mark(node: etree._Element) -> LicenseMark:
+    # 빠진 ``type``은 같은 ``DocOptionType`` 안에서 ``parse_link_info``가
+    # 스키마-required인 ``path``를 다루는 방식 그대로 빈 문자열로 둔다
+    # (문자열 속성은 이 모듈에서 raise 대상이 아니다 -- 정수 변환이
+    # 필요한 ``flag``/``lang``만 ``parse_int``가 검사한다).
     return LicenseMark(
-        type=parse_int(node.get("type"), allow_none=False),
+        type=node.get("type", ""),
         flag=parse_int(node.get("flag"), allow_none=False),
         lang=parse_int(node.get("lang")),
     )

{python_hwpx-6.1.0 → python_hwpx-6.3.0}/src/hwpx/oxml/header_compat.py

@@ -66,9 +66,11 @@ if TYPE_CHECKING:
 
 __all__ = [
     "apply_paragraph_auto_spacing",
+    "remove_license_mark",
     "set_compatible_document_target_program",
     "set_doc_option_link_info",
     "set_layout_compatibility_flags",
+    "set_license_mark",
 ]
 
 
@@ -146,6 +148,32 @@ def set_layout_compatibility_flags(header: HwpxOxmlHeader, flags: Iterable[str])
     header.mark_dirty()
 
 
+def _doc_option_element(header: HwpxOxmlHeader) -> ET.Element:
+    """``hh:docOption``(+스키마 필수인 ``hh:linkinfo`` 첫 자식)을 보장하고
+    돌려준다. ``linkinfo``는 ``minOccurs`` 기본값이라 필수인데, 코퍼스
+    47/47이 ``path=""``/``pageInherit="0"``/``footnoteInherit="0"``이므로
+    새로 만들 때 그 값으로 채운다."""
+
+    root = header.element
+    doc_option = HwpxOxmlHeader._direct_child_by_local(root, "docOption")
+    if doc_option is None:
+        doc_option = root.makeelement(f"{_HH}docOption", {})
+        HwpxOxmlHeader._insert_child_after(
+            root,
+            doc_option,
+            {"beginNum", "refList", "forbiddenWordList", "compatibleDocument"},
+        )
+    if HwpxOxmlHeader._direct_child_by_local(doc_option, "linkinfo") is None:
+        doc_option.insert(
+            0,
+            doc_option.makeelement(
+                f"{_HH}linkinfo",
+                {"path": "", "pageInherit": "0", "footnoteInherit": "0"},
+            ),
+        )
+    return doc_option
+
+
 def set_doc_option_link_info(
     header: HwpxOxmlHeader,
     *,
@@ -157,22 +185,9 @@ def set_doc_option_link_info(
     ``footnoteInherit`` attributes. ``None`` leaves an attribute unchanged
     (or defaults it to the corpus-majority value on first creation)."""
 
-    root = header.element
-    doc_option = HwpxOxmlHeader._direct_child_by_local(root, "docOption")
-    if doc_option is None:
-        doc_option = root.makeelement(f"{_HH}docOption", {})
-        HwpxOxmlHeader._insert_child_after(
-            root,
-            doc_option,
-            {"beginNum", "refList", "forbiddenWordList", "compatibleDocument"},
-        )
+    doc_option = _doc_option_element(header)
     link_info = HwpxOxmlHeader._direct_child_by_local(doc_option, "linkinfo")
-    if link_info is None:
-        link_info = doc_option.makeelement(
-            f"{_HH}linkinfo",
-            {"path": "", "pageInherit": "0", "footnoteInherit": "0"},
-        )
-        doc_option.append(link_info)
+    assert link_info is not None  # _doc_option_element guarantees it
     if path is not None:
         link_info.set("path", path)
     if page_inherit is not None:
@@ -182,6 +197,80 @@ def set_doc_option_link_info(
     header.mark_dirty()
 
 
+def set_license_mark(
+    header: HwpxOxmlHeader,
+    *,
+    mark_type: str,
+    flag: int,
+    lang: int | None = None,
+) -> None:
+    """Set ``hh:docOption/hh:licensemark`` -- the document-level licence
+    record "입력 > CCL 넣기…" writes.
+
+    Real-Hancom contract (gold ``tests/fixtures/gui_probes/
+    license_mark_ccl.hwpx``, HWP 13.0.0.3901): the element is a
+    ``hh:linkinfo`` sibling, second child of ``hh:docOption``, and reads
+    ``<hh:licensemark type="CCL" flag="0" lang="6"/>``.
+
+    **``type`` is a string, not a number.** The schema (``Header XML
+    schema.xml``'s ``DocOptionType``) declares ``type`` as
+    ``xs:unsignedInt use="required"`` -- real Hancom emits ``"CCL"``. Same
+    measurement-over-schema precedent as ``field_marks``'s
+    ``PROOFREADING_MARKS_SIGN`` (DEV-043), so *mark_type* is typed ``str``
+    and passed through verbatim.
+
+    *flag*/*lang* are ints (``xs:byte`` in the schema, observed ``0``/``6``
+    -- 6 is the language code for this document's UI locale). No value
+    range is enforced beyond that: one observation is not an enumeration,
+    and ``set_compatible_document_target_program`` already established that
+    this module does not invent restrictions it has no evidence for.
+    Omitting *lang* omits the attribute (the schema marks it optional; the
+    other two are required and always written).
+
+    This setter writes the **document-level record only**. The visible CC
+    badge in the gold is an ordinary picture with a licence-deed URL
+    (``hp:pic`` + ``href``) -- author it with ``add_picture`` plus that
+    ``href``, exactly as for any other linked image.
+    """
+
+    if not mark_type:
+        raise HwpxValueError(
+            "mark_type must be a non-empty string",
+            code="header-compat-empty-license-mark-type",
+            context={"mark_type": mark_type},
+            suggestion='Pass the observed real-Hancom value, e.g. "CCL".',
+        )
+
+    doc_option = _doc_option_element(header)
+    license_mark = HwpxOxmlHeader._direct_child_by_local(doc_option, "licensemark")
+    if license_mark is None:
+        license_mark = doc_option.makeelement(f"{_HH}licensemark", {})
+        doc_option.append(license_mark)
+    license_mark.set("type", mark_type)
+    license_mark.set("flag", str(int(flag)))
+    if lang is None:
+        license_mark.attrib.pop("lang", None)
+    else:
+        license_mark.set("lang", str(int(lang)))
+    header.mark_dirty()
+
+
+def remove_license_mark(header: HwpxOxmlHeader) -> bool:
+    """Drop ``hh:docOption/hh:licensemark`` if present; returns whether one
+    was removed. ``hh:docOption`` itself stays (its ``hh:linkinfo`` child is
+    schema-required and unrelated to the licence record)."""
+
+    doc_option = HwpxOxmlHeader._direct_child_by_local(header.element, "docOption")
+    if doc_option is None:
+        return False
+    license_mark = HwpxOxmlHeader._direct_child_by_local(doc_option, "licensemark")
+    if license_mark is None:
+        return False
+    doc_option.remove(license_mark)
+    header.mark_dirty()
+    return True
+
+
 def apply_paragraph_auto_spacing(
     header: HwpxOxmlHeader,
     para_pr: ET.Element,

{python_hwpx-6.1.0 → python_hwpx-6.3.0}/src/hwpx/oxml/memo.py

@@ -277,7 +277,9 @@ class HwpxOxmlNote:
 
     @property
     def inst_id(self) -> str | None:
-        return self.element.get("instId")
+        # 정본 속성명은 "instid"(스키마·실한컴). "instId"는 과거 우리 저작이
+        # 방출한 카멜케이스 산출물 호환용 폴백.
+        return self.element.get("instid") or self.element.get("instId")
 
     @property
     def text(self) -> str:

{python_hwpx-6.1.0 → python_hwpx-6.3.0}/src/hwpx/oxml/note_authoring.py

@@ -128,7 +128,7 @@ def _paragraph_add_note(
         {
             "number": str(number),
             "suffixChar": str(ord(suffix[0])) if suffix else "41",
-            "instId": _object_id(),
+            "instid": _object_id(),
         },
     )
     sublist_attrs = _default_sublist_attributes()