python-hwpx 6.6.0__tar.gz → 6.7.0__tar.gz

{python_hwpx-6.6.0/src/python_hwpx.egg-info → python_hwpx-6.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 6.6.0
+Version: 6.7.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0
@@ -68,7 +68,7 @@ Dynamic: license-file
 
 한컴오피스가 없어도 됩니다. HWPX는 ZIP+XML(OWPML) 포맷이라 순수 파이썬만으로
 읽고, 고치고, 새로 만들 수 있습니다 — Windows·macOS·Linux·CI, 그리고
-**파이썬이 도는 ChatGPT 채팅 안에서도** 그대로 동작합니다. 기존 문서의 저장은 요청한 보존 등급과 실제 검증 결과를 영수증으로 남깁니다.
+**파이썬이 도는 ChatGPT 채팅 안에서도** 그대로 동작합니다.
 새 문서의 한컴 호환성은 아래에 날짜·버전을 명시한 코퍼스로 측정합니다.
 
 <p align="center">
@@ -109,7 +109,7 @@ from hwpx import HwpxDocument
 
 doc = HwpxDocument.new()
 doc.add_heading("2026 운영계획", level=1)
-doc.add_paragraph("가. 추진 배경", style="개요 2")
+doc.add_paragraph("추진 배경", style="개요 2")  # 한/글이 "가." 번호를 붙인다
 doc.save_to_path("계획.hwpx")
 ```
 
@@ -130,7 +130,7 @@ doc.save_to_path("계획.hwpx")
 - **편집** — 문단·표·이미지·머리글/바닥글·메모·각주, 줄간격·여백·쪽번호 같은 서식
 - **양식 채우기** — 라벨로 셀을 찾아 값만 채우기, 행·열 조정 같은 구조 편집도 바이트 보존으로
 - **생성·일괄 처리** — 새 문서 저작, 목차·상호참조, mail merge, 텍스트 diff, 변경추적(redline)
-- **검증·안전** — 패키지 구조 검증 CLI, 열림 안전 게이트, 모든 저장에 영수증(`MutationReport`)
+- **검증·안전** — 패키지 구조 검증 CLI, 열림 안전 게이트, 저장 결과 보고(`return_report=True`)
 
 자세한 내용: [5분 퀵스타트](docs/quickstart.md) · [사용 가이드](docs/usage.md) · [API 레퍼런스](https://airmang.github.io/python-hwpx/) · [예제](docs/examples.md)
 
@@ -152,20 +152,6 @@ report = doc.save_to_path("신청서-작성완료.hwpx", mode="patch", fallback=
 바이트 보존을 요구합니다. 수정 파트 내부의 보존과 시각적 배치는 별도 확인이
 필요합니다. 출력 재개봉과 내용 확인까지 포함한 경로는 [안전한 쓰기 계약](docs/safe-write-contract.md)을 따르세요.
 
-### 저장에는 영수증이 따라옵니다
-
-```python
-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}
-```
-
-`mode="patch", fallback="error"`는 보존 등급 미달 시 출력하지 않습니다.
-기본 `auto`는 달성 가능한 등급을 선택합니다. `report.ok`는 요청 반영이나 시각
-검증 완료를 뜻하지 않습니다.
-전체 규칙: [안전한 쓰기 계약](docs/safe-write-contract.md).
-
 *예제 중 **독립 실행 예제** 표시가 없는 블록은 여러분의 기존 문서를 입력으로
 쓰는 조각입니다. 예제별 Python 블록 판정은
 [실행 ledger](docs/python-example-ledger.json)에 동결돼 있습니다.*
@@ -175,10 +161,9 @@ print(report.preservation.untouched_part_payloads.to_dict())
 만든 파일이 실제 한컴오피스에서 열리는지 재서 그대로 공개합니다. 측정마다
 스택과 날짜를 병기합니다:
 
-- **한컴 열림 120/120 · 렌더 검증 120/120** — 현행 스택(5.7.0 · 실한컴
-  12.0.0.3288 · 2026-08-03)의 축소 측정: 기준 스트라텀 + 신규 저작 표면
-  6종(각주·누름틀·수식·차트·체크박스·편집 계획). 영수증은 행마다 bucket이
-  있어 `jq` 한 줄로 재현됩니다
+- **한컴 열림 120/120 · 렌더 검증 120/120** — 기준 문서군 + 저작 기능
+  6종(각주·누름틀·수식·차트·체크박스·편집 계획) 축소 측정
+  (5.7.0 · 실한컴 12.0.0.3288 · 2026-08-03)
 - **한컴 열림 476/476** — 전수 동결 코퍼스(N=497) 측정
   (3.4.1 · 실한컴 12.0.0.3288 · 2026-07-19)
 - **미수정 영역 바이트 보존 497/497** · 개인정보 유출 0

{python_hwpx-6.6.0 → python_hwpx-6.7.0}/README.md

@@ -17,7 +17,7 @@
 
 한컴오피스가 없어도 됩니다. HWPX는 ZIP+XML(OWPML) 포맷이라 순수 파이썬만으로
 읽고, 고치고, 새로 만들 수 있습니다 — Windows·macOS·Linux·CI, 그리고
-**파이썬이 도는 ChatGPT 채팅 안에서도** 그대로 동작합니다. 기존 문서의 저장은 요청한 보존 등급과 실제 검증 결과를 영수증으로 남깁니다.
+**파이썬이 도는 ChatGPT 채팅 안에서도** 그대로 동작합니다.
 새 문서의 한컴 호환성은 아래에 날짜·버전을 명시한 코퍼스로 측정합니다.
 
 <p align="center">
@@ -58,7 +58,7 @@ from hwpx import HwpxDocument
 
 doc = HwpxDocument.new()
 doc.add_heading("2026 운영계획", level=1)
-doc.add_paragraph("가. 추진 배경", style="개요 2")
+doc.add_paragraph("추진 배경", style="개요 2")  # 한/글이 "가." 번호를 붙인다
 doc.save_to_path("계획.hwpx")
 ```
 
@@ -79,7 +79,7 @@ doc.save_to_path("계획.hwpx")
 - **편집** — 문단·표·이미지·머리글/바닥글·메모·각주, 줄간격·여백·쪽번호 같은 서식
 - **양식 채우기** — 라벨로 셀을 찾아 값만 채우기, 행·열 조정 같은 구조 편집도 바이트 보존으로
 - **생성·일괄 처리** — 새 문서 저작, 목차·상호참조, mail merge, 텍스트 diff, 변경추적(redline)
-- **검증·안전** — 패키지 구조 검증 CLI, 열림 안전 게이트, 모든 저장에 영수증(`MutationReport`)
+- **검증·안전** — 패키지 구조 검증 CLI, 열림 안전 게이트, 저장 결과 보고(`return_report=True`)
 
 자세한 내용: [5분 퀵스타트](docs/quickstart.md) · [사용 가이드](docs/usage.md) · [API 레퍼런스](https://airmang.github.io/python-hwpx/) · [예제](docs/examples.md)
 
@@ -101,20 +101,6 @@ report = doc.save_to_path("신청서-작성완료.hwpx", mode="patch", fallback=
 바이트 보존을 요구합니다. 수정 파트 내부의 보존과 시각적 배치는 별도 확인이
 필요합니다. 출력 재개봉과 내용 확인까지 포함한 경로는 [안전한 쓰기 계약](docs/safe-write-contract.md)을 따르세요.
 
-### 저장에는 영수증이 따라옵니다
-
-```python
-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}
-```
-
-`mode="patch", fallback="error"`는 보존 등급 미달 시 출력하지 않습니다.
-기본 `auto`는 달성 가능한 등급을 선택합니다. `report.ok`는 요청 반영이나 시각
-검증 완료를 뜻하지 않습니다.
-전체 규칙: [안전한 쓰기 계약](docs/safe-write-contract.md).
-
 *예제 중 **독립 실행 예제** 표시가 없는 블록은 여러분의 기존 문서를 입력으로
 쓰는 조각입니다. 예제별 Python 블록 판정은
 [실행 ledger](docs/python-example-ledger.json)에 동결돼 있습니다.*
@@ -124,10 +110,9 @@ print(report.preservation.untouched_part_payloads.to_dict())
 만든 파일이 실제 한컴오피스에서 열리는지 재서 그대로 공개합니다. 측정마다
 스택과 날짜를 병기합니다:
 
-- **한컴 열림 120/120 · 렌더 검증 120/120** — 현행 스택(5.7.0 · 실한컴
-  12.0.0.3288 · 2026-08-03)의 축소 측정: 기준 스트라텀 + 신규 저작 표면
-  6종(각주·누름틀·수식·차트·체크박스·편집 계획). 영수증은 행마다 bucket이
-  있어 `jq` 한 줄로 재현됩니다
+- **한컴 열림 120/120 · 렌더 검증 120/120** — 기준 문서군 + 저작 기능
+  6종(각주·누름틀·수식·차트·체크박스·편집 계획) 축소 측정
+  (5.7.0 · 실한컴 12.0.0.3288 · 2026-08-03)
 - **한컴 열림 476/476** — 전수 동결 코퍼스(N=497) 측정
   (3.4.1 · 실한컴 12.0.0.3288 · 2026-07-19)
 - **미수정 영역 바이트 보존 497/497** · 개인정보 유출 0

{python_hwpx-6.6.0 → python_hwpx-6.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "6.6.0"
+version = "6.7.0"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 문서 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"
@@ -295,6 +295,9 @@ files = [
     # Table width/height distribution (distribute cell width row by row) moved out
     # of table.py -- born in the gate, per the WP-A rule.
     "src/hwpx/oxml/table_sizes.py",
+    # A paragraph shape's heading (outline levels 8 to 10 in Hancom's hp:switch form),
+    # written and read in one place -- born in the gate, per the WP-A rule.
+    "src/hwpx/oxml/paragraph_heading.py",
     # Floating-shape reference frames (set_position) and shape-text
     # vertical alignment -- objects.py's overflow module (1600-line cap),
     # born in the gate, per the WP-A rule.
@@ -501,6 +504,9 @@ include = [
     # Table width/height distribution (distribute cell width row by row) moved out
     # of table.py -- born in the gate, per the WP-A rule.
     "src/hwpx/oxml/table_sizes.py",
+    # A paragraph shape's heading (outline levels 8 to 10 in Hancom's hp:switch form),
+    # written and read in one place -- born in the gate, per the WP-A rule.
+    "src/hwpx/oxml/paragraph_heading.py",
     # Floating-shape reference frames (set_position) and shape-text
     # vertical alignment -- objects.py's overflow module (1600-line cap),
     # born in the gate, per the WP-A rule.

{python_hwpx-6.6.0 → python_hwpx-6.7.0}/src/hwpx/__init__.py

@@ -45,6 +45,10 @@ _EXPERIMENTAL_EXPORTS = {
     "LayoutPreview": "hwpx.tools.layout_preview",
     "PreviewPage": "hwpx.tools.layout_preview",
     "render_layout_preview": "hwpx.tools.layout_preview",
+    # 쪽 수 추정(한/글 없이, 줄마다 쪽·단·세로 위치). 계약 유동.
+    "EstimatedLine": "hwpx.layout.pages",
+    "PageEstimate": "hwpx.layout.pages",
+    "estimate_pages": "hwpx.layout.pages",
     # 문서 프리뷰 뷰어(3.8.0 신규). 계약 유동.
     "DocumentViewer": "hwpx.tools.document_viewer",
     "render_document_viewer": "hwpx.tools.document_viewer",
@@ -347,6 +351,13 @@ def __dir__() -> list[str]:
     )
 
 
+# ``import hwpx.builder`` goes through the import system, not ``__getattr__``,
+# so the moved module names get their destination from a finder instead.
+from . import _moved_modules
+
+_moved_modules.install(_MOVED_TO_COMPANION)
+
+
 # --- stable 최상위 표면 (eager import) ------------------------------------------
 from .tools.text_extractor import (
     DEFAULT_NAMESPACES,

{python_hwpx-6.6.0 → python_hwpx-6.7.0}/src/hwpx/_document/_legacy.py

@@ -615,7 +615,7 @@ class _LegacyFacade:
         field_id: str | None = None,
         author: str | None = None,
         created: datetime | str | None = None,
-        number: int = 1,
+        number: int | None = None,
         anchor_char_pr_id_ref: str | int | None = None,
     ) -> tuple[HwpxOxmlMemo, HwpxOxmlParagraph, str]:
         """Create a memo and ensure it is visible by anchoring a MEMO field."""
@@ -801,7 +801,7 @@ class _LegacyFacade:
         field_id: str | None = None,
         author: str | None = None,
         created: datetime | str | None = None,
-        number: int = 1,
+        number: int | None = None,
         char_pr_id_ref: str | int | None = None,
     ) -> str:
         """Attach a MEMO field control to *paragraph* so Hangul shows *memo*."""

{python_hwpx-6.6.0 → python_hwpx-6.7.0}/src/hwpx/_document/fields.py

@@ -8,7 +8,7 @@ from typing import TYPE_CHECKING, Any, Iterator, Mapping, Sequence, cast
 
 from ..errors import HwpxStateError, HwpxValueError
 from ..objects.checkbox import CheckBox
-from ..objects.form_field import CellField, FieldLocation, FieldParameter, FormField
+from ..objects.form_field import CellField, FieldLocation, FieldParameter, FormField, TextBoxField
 from ..objects.results import FieldFillResult
 from ..oxml import HwpxOxmlParagraph
 from ..oxml.namespaces import HP
@@ -88,6 +88,41 @@ def _sanitize_field_text(value: str) -> str:
     return _TEXT_ILLEGAL.sub("", value)
 
 
+# Characters an hp:t holds as child elements; they belong to the text they sit in.
+_TEXT_CHARACTER_NAMES = {"tab": "\t", "lineBreak": "\n", "hyphen": "", "nbSpace": "\u00a0", "fwSpace": "\u3000"}
+
+
+def _text_node_value(node: Any) -> str:
+    """The text of an ``hp:t``, with ``hp:lineBreak`` as a newline and ``hp:tab`` as a tab."""
+
+    parts = [node.text or ""]
+    for child in node:
+        parts.append(_TEXT_CHARACTER_NAMES.get(_local_name(child), ""))
+        parts.append(child.tail or "")
+    return "".join(parts)
+
+
+def _write_text_node(node: Any, value: str) -> None:
+    """Put *value* in the ``hp:t`` *node* in place of its text.
+
+    A line break (CRLF, LF or CR) becomes ``hp:lineBreak``, the element Hancom
+    turns such a character into when it opens the file. The characters of the
+    old text (tabs, line breaks) go; other marks stay, emptied.
+    """
+
+    for child in list(node):
+        if _local_name(child) in _TEXT_CHARACTER_NAMES:
+            node.remove(child)
+        else:
+            child.tail = ""
+    lines = value.replace("\r\n", "\n").replace("\r", "\n").split("\n")
+    node.text = lines[0]
+    for line in lines[1:]:
+        line_break = node.makeelement(f"{_HP}lineBreak", {})
+        node.append(line_break)
+        line_break.tail = line
+
+
 def _field_type_tokens(*values: str | None) -> set[str]:
     tokens: set[str] = set()
     for value in values:
@@ -125,6 +160,11 @@ def _field_identifier(field_begin: Any) -> str:
 
 
 def _field_end_matches(field_begin: Any, field_end: Any) -> bool:
+    # An end that names its begin (beginIDRef) is that begin's end only: a fieldid
+    # is shared by every field of a type (Hancom's control id), so it pairs only
+    # ends that name no begin.
+    if field_begin.get("id") and field_end.get("beginIDRef"):
+        return field_begin.get("id") == field_end.get("beginIDRef")
     begin_keys = {
         value
         for value in (
@@ -160,6 +200,18 @@ def _field_parameters(field_begin: Any) -> list[dict[str, str]]:
     return parameters
 
 
+def _field_name(field_begin: Any, parameters: Sequence[dict[str, str]]) -> str:
+    """The field's name. A ``name`` attribute is the name even when empty: Hancom
+    treats such a field as unnamed (it lists and fills fields by name only)."""
+
+    if field_begin.get("name") is not None:
+        return field_begin.get("name", "").strip()
+    name = _first_attr(field_begin, _FORM_FIELD_NAME_ATTRS)
+    if not name:
+        name = _field_parameter_value(parameters, "fieldName", "fieldname", "field_name", "name", "title")
+    return name
+
+
 def _first_attr(element: Any, names: Sequence[str]) -> str:
     for name in names:
         value = (element.get(name) or "").strip()
@@ -178,6 +230,21 @@ def _field_parameter_value(parameters: Sequence[dict[str, str]], *names: str) ->
     return ""
 
 
+_COMMAND_DIRECTION = re.compile(r"(?:^|[\s:])Direction:wstring:(\d+):")
+
+
+def _command_direction(parameters: Sequence[dict[str, str]]) -> str:
+    """The prompt a field keeps only in its ``Command`` string
+    (``Clickhere:set:N:Direction:wstring:<length>:<prompt> HelpState:...``)."""
+
+    command = _field_parameter_value(parameters, "Command")
+    found = _COMMAND_DIRECTION.search(command)
+    if found is None:
+        return ""
+    start = found.end()
+    return command[start : start + int(found.group(1))]
+
+
 def _clear_form_field_layout_cache(paragraph: Any) -> int:
     removed = 0
     for child in list(paragraph):
@@ -208,6 +275,40 @@ def _find_field_end_position(
     return None
 
 
+def _find_field_end_in_following_paragraphs(
+    paragraph_element: Any, field_begin: Any
+) -> tuple[Any, list[Any], int, int, list[Any]] | None:
+    """The end of a field whose content runs past its paragraph: the later
+    paragraph beside it that holds the fieldEnd naming this field's id, that
+    paragraph's runs, the end's run and child index, and the paragraphs in
+    between. Only an end that names the begin's id counts here."""
+
+    ids = {value for value in (field_begin.get("id"), field_begin.get("fieldid")) if value}
+    if not ids:
+        return None
+    middle: list[Any] = []
+    sibling = paragraph_element.getnext()
+    while sibling is not None:
+        if _local_name(sibling) == "p":
+            runs = [child for child in sibling if _local_name(child) == "run"]
+            for run_index, run in enumerate(runs):
+                for child_index, child in enumerate(run):
+                    if _local_name(child) != "ctrl":
+                        continue
+                    for field_end in child.findall(f"{_HP}fieldEnd"):
+                        if _field_end_matches(field_begin, field_end) and (
+                            ids & {field_end.get("beginIDRef"), field_end.get("fieldid")}
+                        ):
+                            return sibling, runs, run_index, child_index, middle
+            middle.append(sibling)
+        sibling = sibling.getnext()
+    return None
+
+
+def _run_texts(runs: Sequence[Any]) -> str:
+    return "".join(_text_node_value(node) for run in runs for node in run if _local_name(node) == "t")
+
+
 def _field_text_nodes(
     doc: "HwpxDocument",
     runs: Sequence[Any],
@@ -244,13 +345,14 @@ def _form_field_payload(
     has_end: bool,
 ) -> dict[str, Any]:
     parameters = _field_parameters(field_begin)
-    name = _first_attr(field_begin, _FORM_FIELD_NAME_ATTRS)
-    if not name:
-        name = _field_parameter_value(parameters, "fieldName", "fieldname", "field_name", "name", "title")
+    name = _field_name(field_begin, parameters)
     prompt = _first_attr(field_begin, _FORM_FIELD_PROMPT_ATTRS)
     if not prompt:
         # "Direction" is the real-Hancom 안내문 parameter (P0 gold contract).
         prompt = _field_parameter_value(parameters, "Direction", *_FORM_FIELD_PARAM_NAMES)
+    if not prompt:
+        # Some fields keep it only inside their Command string.
+        prompt = _command_direction(parameters)
     instruction = _field_parameter_value(parameters, "instruction", "guide", "help", "description", "desc")
     if not instruction:
         instruction = prompt
@@ -325,17 +427,38 @@ def _iter_form_field_matches(doc: "HwpxDocument") -> list[dict[str, Any]]:
                         )
                         end_run_index: int | None = None
                         end_child_index: int | None = None
+                        span = None
                         if end_position is not None:
                             end_run_index, end_child_index, _field_end = end_position
+                        else:
+                            span = _find_field_end_in_following_paragraphs(paragraph_element, field_begin)
                         text_nodes = _field_text_nodes(
                             doc,
                             runs,
                             begin_run_index=run_index,
                             begin_child_index=child_index,
-                            end_run_index=end_run_index,
+                            end_run_index=end_run_index if span is None else len(runs) - 1,
                             end_child_index=end_child_index,
                         )
-                        current_value = "".join("".join(node.itertext()) for node in text_nodes)
+                        current_value = "".join(_text_node_value(node) for node in text_nodes)
+                        if span is not None:
+                            # the content goes on over paragraphs: their texts, one per line
+                            end_paragraph, end_runs, span_run, span_child, middle = span
+                            tail = _field_text_nodes(
+                                doc,
+                                end_runs,
+                                begin_run_index=0,
+                                begin_child_index=-1,
+                                end_run_index=span_run,
+                                end_child_index=span_child,
+                            )
+                            current_value = "\n".join(
+                                [
+                                    current_value,
+                                    *(_run_texts([c for c in p if _local_name(c) == "run"]) for p in middle),
+                                    "".join(_text_node_value(node) for node in tail),
+                                ]
+                            )
                         payload = _form_field_payload(
                             doc,
                             index=len(matches),
@@ -347,7 +470,7 @@ def _iter_form_field_matches(doc: "HwpxDocument") -> list[dict[str, Any]]:
                             ctrl=child,
                             field_begin=field_begin,
                             current_value=current_value,
-                            has_end=end_position is not None,
+                            has_end=end_position is not None or span is not None,
                         )
                         payload["_paragraph"] = paragraph
                         payload["_runs"] = runs
@@ -356,6 +479,7 @@ def _iter_form_field_matches(doc: "HwpxDocument") -> list[dict[str, Any]]:
                         payload["_end_run_index"] = end_run_index
                         payload["_end_child_index"] = end_child_index
                         payload["_text_nodes"] = text_nodes
+                        payload["_span"] = span
                         matches.append(payload)
             paragraph_index += 1
     return matches
@@ -401,7 +525,13 @@ def _form_field_from_match(doc: "HwpxDocument", match: Mapping[str, Any]) -> For
 
 
 def list_form_fields(doc: "HwpxDocument") -> tuple[FormField, ...]:
-    """Return native form/click-here fields in document order."""
+    """Return native form/click-here fields in document order.
+
+    Every field in the document is listed. An unnamed field (an empty ``name``) is
+    listed with an empty name and told apart by its id: :func:`fill_form_field`
+    does not find it by name, as Hancom does not, but ``field_index`` and
+    ``field_id`` reach it.
+    """
 
     return tuple(_form_field_from_match(doc, match) for match in _iter_form_field_matches(doc))
 
@@ -442,6 +572,80 @@ def fill_cell_fields(doc: "HwpxDocument", value: str, *, name: str, index: int |
     return tuple(fields)
 
 
+def list_text_box_fields(doc: "HwpxDocument") -> tuple[TextBoxField, ...]:
+    """Named text boxes in document order: Hancom lists a text box whose ``hp:drawText``
+    has a name among its fields (and leaves an unnamed one out)."""
+
+    return tuple(
+        TextBoxField(draw_text, section)
+        for section in doc.sections
+        for draw_text in section.element.iter(f"{_HP}drawText")
+        if (draw_text.get("name") or "").strip()
+    )
+
+
+def fill_text_box_fields(
+    doc: "HwpxDocument", value: str, *, name: str, index: int | None = None
+) -> tuple[TextBoxField, ...]:
+    """Set the text of every text box called *name*, or of the *index*-th of them only."""
+
+    wanted = (name or "").strip()
+    fields = [field for field in list_text_box_fields(doc) if wanted and field.name == wanted]
+    if index is not None:
+        fields = fields[index : index + 1] if index >= 0 else []
+    if not fields:
+        where = f"{wanted!r}" if index is None else f"{wanted!r} at index {index}"
+        raise HwpxValueError(
+            f"no text box named {where}",
+            code="field-text-box-not-found",
+            context={"name": wanted, "index": index},
+            suggestion="List doc.fields.text_boxes to see the text box names.",
+        )
+    for field in fields:
+        field.text = value
+    return tuple(fields)
+
+
+def text_box_text(draw_text: Any) -> str:
+    """The text of a text box, a line per paragraph."""
+
+    return "\n".join(
+        "".join(_text_node_value(node) for node in paragraph.iter(f"{_HP}t"))
+        for paragraph in draw_text.findall(f"{_HP}subList/{_HP}p")
+    )
+
+
+def set_text_box_text(draw_text: Any, section: Any, value: str) -> None:
+    """Put *value* in a text box as Hancom fills a text box field: the box keeps its
+    first paragraph and that paragraph's first run, which hold the value alone."""
+
+    sub_list = draw_text.find(f"{_HP}subList")
+    if sub_list is None:
+        sub_list = draw_text.makeelement(f"{_HP}subList", {})
+        draw_text.insert(0, sub_list)
+    paragraphs = sub_list.findall(f"{_HP}p")
+    first = paragraphs[0] if paragraphs else sub_list.makeelement(
+        f"{_HP}p", {"id": "0", "paraPrIDRef": "0", "styleIDRef": "0", "pageBreak": "0", "columnBreak": "0", "merged": "0"}
+    )
+    if not paragraphs:
+        sub_list.append(first)
+    for extra in paragraphs[1:]:
+        sub_list.remove(extra)
+    runs = first.findall(f"{_HP}run")
+    run = runs[0] if runs else first.makeelement(f"{_HP}run", {"charPrIDRef": "0"})
+    if not runs:
+        first.insert(0, run)
+    for extra in runs[1:]:
+        first.remove(extra)
+    for child in list(run):
+        run.remove(child)
+    text = run.makeelement(f"{_HP}t", {})
+    run.append(text)
+    _write_text_node(text, value)
+    _clear_form_field_layout_cache(first)
+    section.mark_dirty()
+
+
 _PROMPT_TEXT_COLOR = "#FF0000"
 
 
@@ -686,6 +890,7 @@ def _select_form_field(
             match
             for match in matches
             if wanted_name
+            and match.get("name")
             and wanted_name
             in {
                 str(match.get("name", "")).strip().casefold(),
@@ -735,10 +940,62 @@ def _insert_form_field_text_run(
     runs: list[Any] = match["_runs"]
     begin_run = runs[int(match["_begin_run_index"])]
     text_node = begin_run.makeelement(f"{_HP}t", {})
-    text_node.text = _sanitize_field_text(value)
+    _write_text_node(text_node, _sanitize_field_text(value))
     begin_run.insert(int(match["_begin_child_index"]) + 1, text_node)
 
 
+def _drop_nested_fields(match: Mapping[str, Any]) -> None:
+    """Hancom's way with a field that holds other fields: the value replaces
+    them with the rest of the content, so the begin and end of every field
+    lying wholly between this field's begin and end go."""
+
+    runs: list[Any] = match["_runs"]
+    end_run_index = match.get("_end_run_index")
+    if end_run_index is None:
+        return
+    begin_run_index = int(match["_begin_run_index"])
+    inside: list[tuple[Any, Any]] = []
+    for run_index in range(begin_run_index, int(end_run_index) + 1):
+        children = list(runs[run_index])
+        start = int(match["_begin_child_index"]) + 1 if run_index == begin_run_index else 0
+        stop = int(match["_end_child_index"]) if run_index == end_run_index else len(children)
+        inside.extend((runs[run_index], child) for child in children[start:stop] if _local_name(child) == "ctrl")
+    begun = {mark.get("id") for _, ctrl in inside for mark in ctrl.findall(f"{_HP}fieldBegin")}
+    ended = {mark.get("beginIDRef") for _, ctrl in inside for mark in ctrl.findall(f"{_HP}fieldEnd")}
+    nested = (begun & ended) - {None, ""}
+    for run, ctrl in inside:
+        marks = [(mark.get("id") if _local_name(mark) == "fieldBegin" else mark.get("beginIDRef"))
+                 for mark in ctrl if _local_name(mark) in ("fieldBegin", "fieldEnd")]
+        if marks and all(mark in nested for mark in marks):
+            run.remove(ctrl)
+
+
+def _collapse_field_span(match: Mapping[str, Any]) -> None:
+    """Hancom's way with a field whose content runs over paragraphs: the
+    content between the begin and the end goes, paragraphs and all, and the
+    end with the rest of its paragraph joins the begin's paragraph."""
+
+    end_paragraph, end_runs, end_run_index, end_child_index, middle = match["_span"]
+    paragraph_element = match["_paragraph"].element
+    runs: list[Any] = match["_runs"]
+    begin_run_index = int(match["_begin_run_index"])
+    begin_run = runs[begin_run_index]
+    for child in list(begin_run)[int(match["_begin_child_index"]) + 1 :]:
+        begin_run.remove(child)
+    for run in runs[begin_run_index + 1 :]:
+        paragraph_element.remove(run)
+    for element in middle:
+        element.getparent().remove(element)
+    end_run = end_runs[end_run_index]
+    moved = end_run.makeelement(end_run.tag, dict(end_run.attrib))
+    for child in list(end_run)[end_child_index:]:
+        moved.append(child)
+    position = paragraph_element.index(begin_run) + 1
+    for offset, run in enumerate([moved, *end_runs[end_run_index + 1 :]]):
+        paragraph_element.insert(position + offset, run)
+    end_paragraph.getparent().remove(end_paragraph)
+
+
 def fill_form_field(
     doc: "HwpxDocument",
     value: str,
@@ -766,6 +1023,13 @@ def fill_form_field(
         field_id=field_id,
         name=name,
     )
+    if not match.get("has_end"):
+        raise HwpxValueError(
+            f"the field {match.get('name') or match.get('index')!r} has no end, so it has no content to replace",
+            code="field-end-missing",
+            context={"name": match.get("name"), "index": match.get("index")},
+            suggestion="Hancom leaves such a field unchanged too; give it an end or remove it.",
+        )
     paragraph = match["_paragraph"]
     runs = match["_runs"]
     before_value = str(match.get("current_value", ""))
@@ -802,23 +1066,23 @@ def fill_form_field(
 
     text_nodes: list[Any] = match.get("_text_nodes", [])
     sanitized = _sanitize_field_text(write_value)
-    if text_nodes:
+    if match.get("_span") is None:
+        _drop_nested_fields(match)
+    if match.get("_span") is not None:
+        _collapse_field_span(match)
+        _insert_form_field_text_run(doc, match, sanitized)
+    elif text_nodes:
         primary = text_nodes[0]
-        primary.text = sanitized
-        for child in list(primary):
-            child.tail = ""
+        _write_text_node(primary, sanitized)
         for node in text_nodes[1:]:
-            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)
+            _write_text_node(node, "")
+        # Hancom writes the value in the shape of the run holding the field's
+        # begin, whatever shape the old value or the screen-only prompt had.
+        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)