python-hwpx-automation 7.2.0__tar.gz → 7.3.1__tar.gz

{python_hwpx_automation-7.2.0/src/python_hwpx_automation.egg-info → python_hwpx_automation-7.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx-automation
-Version: 7.2.0
+Version: 7.3.1
 Summary: Task-oriented HWPX document automation for Python, with an optional MCP adapter.
 Author: Kohkyuhyun
 License-Expression: Apache-2.0
@@ -74,8 +74,9 @@ Dynamic: license-file
 
 <!-- release-state: release-approved -->
 > [!NOTE]
-> 발행이 승인된 7.2.0 후보 (release-approved; 원격 발행 대기): `python-hwpx 6.5.0 → python-hwpx-automation 7.2.0 → hwpx-plugin 2.3.0` (`5e5c23651f92785a`).
-> 공개 트레인: `python-hwpx 6.4.0 → python-hwpx-automation 7.1.0 → hwpx-plugin 2.2.0` (`ba0211fc854a0a97`).
+> 발행이 승인된 7.3.1 후보 (release-approved; 원격 발행 대기): `python-hwpx 6.5.0 → python-hwpx-automation 7.3.1 → hwpx-plugin 2.3.0` (`5e5c23651f92785a`).
+> 공개 트레인: `python-hwpx 6.5.0 → python-hwpx-automation 7.2.0 → hwpx-plugin 2.3.0` (`5e5c23651f92785a`).
+> [발행·설치 영수증](docs/releases/2026-09-22-trustworthy-edit-engine.md)
 > 공개 좌표는 core·automation PyPI와 plugin GitHub
 > Release·marketplace·실제 marketplace 설치 관찰 후에만 승격합니다.
 > [릴리스 runbook](docs/release-runbook.md)
@@ -132,7 +133,7 @@ Gemini CLI는 `~/.gemini/settings.json`, Cursor·Windsurf는 각 에디터의 MC
       "command": "uvx",
       "args": [
         "--from",
-        "python-hwpx-automation[mcp]==7.1.0",
+        "python-hwpx-automation[mcp]==7.2.0",
         "hwpx-automation-mcp"
       ],
       "env": {
@@ -156,6 +157,19 @@ Gemini CLI는 `~/.gemini/settings.json`, Cursor·Windsurf는 각 에디터의 MC
 기존 `hwpx-mcp-server` 배포·import·콘솔·설정 키도 6.x 동안 그대로 동작합니다 —
 전체 목록과 유지 규칙: [6.x 호환 표면](docs/compatibility-6x.md)
 
+## 한컴으로 PDF 렌더하기
+
+한컴(macOS 한컴오피스 한글 또는 Windows 한글 COM)이 있는 컴퓨터에서 문서 하나를
+PDF와 쪽 PNG로 렌더합니다. 별도 환경에서 실행하므로 호출하는 쪽의 python-hwpx
+고정 버전을 건드리지 않습니다.
+
+```bash
+uvx --from "python-hwpx-automation[oracle]==7.3.1" \
+  hwpx render-pdf in.hwpx out.pdf --png out/page --json
+```
+
+JSON 결과·종료 코드·플랫폼 요구 사항: [render-pdf](docs/render-pdf.md)
+
 ## 무엇을 하나
 
 기본 모드에서 다수의 HWPX 도구를 제공하며, 고급 모드(`HWPX_AUTOMATION_ADVANCED=1`)에서 점검·검증용 도구가 추가됩니다.

{python_hwpx_automation-7.2.0 → python_hwpx_automation-7.3.1}/README.md

@@ -14,8 +14,9 @@
 
 <!-- release-state: release-approved -->
 > [!NOTE]
-> 발행이 승인된 7.2.0 후보 (release-approved; 원격 발행 대기): `python-hwpx 6.5.0 → python-hwpx-automation 7.2.0 → hwpx-plugin 2.3.0` (`5e5c23651f92785a`).
-> 공개 트레인: `python-hwpx 6.4.0 → python-hwpx-automation 7.1.0 → hwpx-plugin 2.2.0` (`ba0211fc854a0a97`).
+> 발행이 승인된 7.3.1 후보 (release-approved; 원격 발행 대기): `python-hwpx 6.5.0 → python-hwpx-automation 7.3.1 → hwpx-plugin 2.3.0` (`5e5c23651f92785a`).
+> 공개 트레인: `python-hwpx 6.5.0 → python-hwpx-automation 7.2.0 → hwpx-plugin 2.3.0` (`5e5c23651f92785a`).
+> [발행·설치 영수증](docs/releases/2026-09-22-trustworthy-edit-engine.md)
 > 공개 좌표는 core·automation PyPI와 plugin GitHub
 > Release·marketplace·실제 marketplace 설치 관찰 후에만 승격합니다.
 > [릴리스 runbook](docs/release-runbook.md)
@@ -72,7 +73,7 @@ Gemini CLI는 `~/.gemini/settings.json`, Cursor·Windsurf는 각 에디터의 MC
       "command": "uvx",
       "args": [
         "--from",
-        "python-hwpx-automation[mcp]==7.1.0",
+        "python-hwpx-automation[mcp]==7.2.0",
         "hwpx-automation-mcp"
       ],
       "env": {
@@ -96,6 +97,19 @@ Gemini CLI는 `~/.gemini/settings.json`, Cursor·Windsurf는 각 에디터의 MC
 기존 `hwpx-mcp-server` 배포·import·콘솔·설정 키도 6.x 동안 그대로 동작합니다 —
 전체 목록과 유지 규칙: [6.x 호환 표면](docs/compatibility-6x.md)
 
+## 한컴으로 PDF 렌더하기
+
+한컴(macOS 한컴오피스 한글 또는 Windows 한글 COM)이 있는 컴퓨터에서 문서 하나를
+PDF와 쪽 PNG로 렌더합니다. 별도 환경에서 실행하므로 호출하는 쪽의 python-hwpx
+고정 버전을 건드리지 않습니다.
+
+```bash
+uvx --from "python-hwpx-automation[oracle]==7.3.1" \
+  hwpx render-pdf in.hwpx out.pdf --png out/page --json
+```
+
+JSON 결과·종료 코드·플랫폼 요구 사항: [render-pdf](docs/render-pdf.md)
+
 ## 무엇을 하나
 
 기본 모드에서 다수의 HWPX 도구를 제공하며, 고급 모드(`HWPX_AUTOMATION_ADVANCED=1`)에서 점검·검증용 도구가 추가됩니다.

{python_hwpx_automation-7.2.0 → python_hwpx_automation-7.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx-automation"
-version = "7.2.0"
+version = "7.3.1"
 description = "Task-oriented HWPX document automation for Python, with an optional MCP adapter."
 readme = "README.md"
 authors = [{ name = "Kohkyuhyun" }]

{python_hwpx_automation-7.2.0 → python_hwpx_automation-7.3.1}/src/hwpx_automation/form_fill.py

@@ -1122,10 +1122,15 @@ def _runtime_validation(path: str) -> dict[str, Any]:
         {
             "part": getattr(issue, "part_name", None),
             "message": getattr(issue, "message", str(issue)),
+            "severity": getattr(issue, "severity", "error"),
         }
         for issue in getattr(document_report, "issues", ())
     ]
-    structure = {"ok": not structure_issues, "issues": structure_issues}
+    # a schema warning from python-hwpx does not block the hand-off; only its errors do
+    structure = {
+        "ok": not any(issue["severity"] == "error" for issue in structure_issues),
+        "issues": structure_issues,
+    }
     if validate_package is None:
         package = _dependency_unavailable_report(
             "python-hwpx>=2.10.3 is required for HWPX package validation",
@@ -1208,7 +1213,7 @@ def _issue_payload(issue: Any) -> dict[str, Any]:
     return {
         "part": getattr(issue, "part_name", None),
         "message": getattr(issue, "message", str(issue)),
-        "level": getattr(issue, "level", "error"),
+        "level": getattr(issue, "severity", "error"),
     }
 
 

{python_hwpx_automation-7.2.0 → python_hwpx_automation-7.3.1}/src/hwpx_automation/identity.json

@@ -7,26 +7,26 @@
     "candidate": {
       "pythonHwpx": "6.5.0",
       "canonicalDistribution": "python-hwpx-automation",
-      "canonicalAutomation": "7.2.0",
+      "canonicalAutomation": "7.3.1",
       "compatibilityDistribution": "hwpx-mcp-server",
-      "compatibility": "7.2.0",
+      "compatibility": "7.3.1",
       "plugin": "2.3.0",
       "contractHash": "5e5c23651f92785a"
     },
     "currentPublic": {
-      "pythonHwpx": "6.4.0",
+      "pythonHwpx": "6.5.0",
       "primaryDistribution": "python-hwpx-automation",
-      "primaryApplication": "7.1.0",
-      "plugin": "2.2.0",
-      "contractHash": "ba0211fc854a0a97"
+      "primaryApplication": "7.2.0",
+      "plugin": "2.3.0",
+      "contractHash": "5e5c23651f92785a"
     },
     "promotionGate": "Three states are mandatory: unreleased-candidate while auditing; release-approved only after separate owner approval and while currentPublic still names the previously observed coherent stack; released only in a follow-up commit after remote truth is observed for core, canonical automation, the compatibility distribution, the plugin GitHub release, the marketplace entry, and a real marketplace install. The automation tag workflow publishes only release-approved, leaves currentPublic unchanged, and hands an attached receipt to plugin publication.",
     "previousPublic": {
-      "pythonHwpx": "6.4.0",
+      "pythonHwpx": "6.5.0",
       "primaryDistribution": "python-hwpx-automation",
-      "primaryApplication": "7.1.0",
-      "plugin": "2.2.0",
-      "contractHash": "ba0211fc854a0a97"
+      "primaryApplication": "7.2.0",
+      "plugin": "2.3.0",
+      "contractHash": "5e5c23651f92785a"
     },
     "publicationEvidence": null
   },

{python_hwpx_automation-7.2.0 → python_hwpx_automation-7.3.1}/src/hwpx_automation/office/agent/blueprint/native.py

@@ -19,6 +19,15 @@ from ..model import AgentContractError
 
 _HWP_UNITS_PER_MM = 7200 / 25.4
 _INLINE_KINDS = frozenset({"table", "picture", "shape", "footnote", "endnote"})
+#: Names a blueprint may give a click-here field. Hancom opens the field only
+#: under its own type name, CLICK_HERE.
+_CLICK_HERE_NAMES = frozenset({"FORM", "CLICKHERE", "NURUMTUL", "누름틀"})
+
+
+def hancom_field_type(field_type: object) -> str | None:
+    """CLICK_HERE for any name of a click-here field, None for another field type."""
+    normalized = str(field_type or "ClickHere").replace("_", "").replace("-", "").upper()
+    return "CLICK_HERE" if normalized in _CLICK_HERE_NAMES else None
 
 
 @dataclass(frozen=True, slots=True)
@@ -463,9 +472,8 @@ class TypedNativeBridge:
     def _create_form_field(self, node_id: str, paragraph: Any) -> None:
         node = self.nodes[node_id]
         properties = node["properties"]
-        field_type = str(properties.get("fieldType") or "ClickHere")
-        normalized_type = field_type.replace("_", "").replace("-", "").upper()
-        if normalized_type not in {"FORM", "CLICKHERE", "NURUMTUL", "누름틀"}:
+        field_type = hancom_field_type(properties.get("fieldType"))
+        if field_type is None:
             raise AgentContractError("unsupported_content", "only FORM fields are replayable", target=node_id)
         host_id = self.references.get((node_id, "hostRun"))
         end_id = self.references.get((node_id, "endRun"))
@@ -486,7 +494,7 @@ class TypedNativeBridge:
                 "id": begin_id,
                 "fieldid": field_id,
                 "name": str(properties.get("name") or "")[:512],
-                "type": "CLICK_HERE" if normalized_type in {"FORM", "CLICKHERE"} else field_type,
+                "type": field_type,
                 "editable": "0" if properties.get("readOnly") else "1",
                 "dirty": "0",
                 "zorder": "-1",

{python_hwpx_automation-7.2.0 → python_hwpx_automation-7.3.1}/src/hwpx_automation/office/agent/blueprint/replay.py

@@ -23,7 +23,7 @@ from .bundle import BlueprintBundle, read_blueprint_bundle
 from .dump import dump_document_blueprint
 from .mapping import ReplayPlan, materialize_dependencies, plan_replay
 from .model import BlueprintReplayResult, validate_replay_request
-from .native import CreatedBinding, TypedNativeBridge
+from .native import CreatedBinding, TypedNativeBridge, hancom_field_type
 
 IdempotencyStore = MutableMapping[str, Any]
 FaultInjector = Callable[[str, int | None], None]
@@ -80,6 +80,9 @@ def _semantic_nodes(
             identity = mapped.get("identity") if mapped else None
             if isinstance(identity, Mapping) and identity.get("name"):
                 properties["style"] = identity["name"]
+        if node["kind"] == "form-field" and "fieldType" in properties:
+            # A click-here field is written, and so read back, as CLICK_HERE whatever the blueprint called it.
+            properties["fieldType"] = hancom_field_type(properties["fieldType"]) or properties["fieldType"]
         normalized.append(
             {
                 "blueprintId": str(node["blueprintId"]),

{python_hwpx_automation-7.2.0 → python_hwpx_automation-7.3.1}/src/hwpx_automation/office/agent/cli.py

@@ -591,10 +591,18 @@ def main(
     stdin = cast(TextIO, stdin or sys.stdin)
     stdout = cast(TextIO, stdout or sys.stdout)
     stderr = cast(TextIO, stderr or sys.stderr)
+    arguments = list(argv) if argv is not None else sys.argv[1:]
+    # Dispatched ahead of the parser, whose help and choice errors stay
+    # byte-identical to the frozen core CLI. The rendering owner is imported
+    # only here, so every other command stays free of the Hancom side.
+    if arguments[:1] == ["render-pdf"]:
+        from ..rendering.cli import main as render_main
+
+        return render_main(arguments, prog="hwpx", stdout=stdout, stderr=stderr)
     parser = build_parser()
     try:
         with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
-            args = parser.parse_args(list(argv) if argv is not None else None)
+            args = parser.parse_args(arguments)
         if args.command == "help":
             if args.kind == "blueprint":
                 if args.json_help:

{python_hwpx_automation-7.2.0 → python_hwpx_automation-7.3.1}/src/hwpx_automation/office/agent/commands.py

@@ -73,6 +73,8 @@ _PARAGRAPH_ALIGNMENTS = frozenset(
 _TABLE_ALIGNMENTS = frozenset({"LEFT", "CENTER", "RIGHT", "INSIDE", "OUTSIDE"})
 _VERTICAL_ALIGNMENTS = frozenset({"TOP", "CENTER", "BOTTOM"})
 _INLINE_KINDS = frozenset({"table", "picture", "shape", "footnote", "endnote"})
+#: Notes sit in an hp:ctrl: Hancom drops a note outside one and crashes on an empty one.
+_NOTE_TAGS = frozenset({"footNote", "endNote"})
 _SHAPE_KINDS = frozenset({"line", "rect", "ellipse", "arc", "polygon", "curve", "connectLine"})
 
 # Creation needs a few geometry fields that are readable, rather than editable,
@@ -450,7 +452,12 @@ def _insert_inline(
         _tag_like(paragraph.element, "run"),
         {"charPrIDRef": paragraph.char_pr_id_ref or "0"},
     )
-    run.append(element)
+    if _local_name(element) in _NOTE_TAGS:
+        control = run.makeelement(_tag_like(paragraph.element, "ctrl"), {})
+        control.append(element)
+        run.append(control)
+    else:
+        run.append(element)
     if index >= len(siblings):
         paragraph.element.append(run)
     else:
@@ -458,6 +465,8 @@ def _insert_inline(
         anchor_run = anchor.getparent() if hasattr(anchor, "getparent") else next(
             child for child in paragraph.element if anchor in list(child)
         )
+        if _local_name(anchor_run) == "ctrl":
+            anchor_run = anchor_run.getparent()
         paragraph.element.insert(list(paragraph.element).index(anchor_run), run)
     paragraph.section.mark_dirty()
     return run
@@ -468,6 +477,9 @@ def _remove_inline_element(element: Any, paragraph: Any) -> None:
         child for child in paragraph.element if element in list(child)
     )
     run.remove(element)
+    if _local_name(run) == "ctrl" and not list(run):
+        control, run = run, run.getparent()
+        run.remove(control)
     if not list(run) and run in list(paragraph.element):
         paragraph.element.remove(run)
     paragraph.section.mark_dirty()

{python_hwpx_automation-7.2.0 → python_hwpx_automation-7.3.1}/src/hwpx_automation/office/agent/document.py

@@ -55,6 +55,15 @@ def _mm(value: object) -> float | None:
     return round(units / _HWP_UNITS_PER_MM, 3)
 
 
+def _drawn_page_size(page_size: Any) -> tuple[int, int]:
+    """Width and height as Hancom draws the page: as stored for
+    ``landscape="WIDELY"`` (portrait), turned otherwise (``NARROWLY``)."""
+
+    if page_size.orientation == "WIDELY":
+        return page_size.width, page_size.height
+    return page_size.height, page_size.width
+
+
 def _first_child(element: Any, local_name: str) -> Any | None:
     for child in element:
         if _local_name(child) == local_name:
@@ -249,7 +258,7 @@ class HwpxAgentDocument:
         self._add_record(root)
         for section_index, section in enumerate(self.document.sections, start=1):
             section_path = SemanticPath().child(indexed_segment("section", section_index))
-            page_size = section.properties.page_size
+            page_width, page_height = _drawn_page_size(section.properties.page_size)
             section_record = NodeRecord(
                 kind="section",
                 path=section_path.canonical,
@@ -259,8 +268,8 @@ class HwpxAgentDocument:
                     "index": section_index,
                     "partId": Path(section.part_name).name,
                     "paragraphCount": len(section.paragraphs),
-                    "pageWidthMm": _mm(page_size.width),
-                    "pageHeightMm": _mm(page_size.height),
+                    "pageWidthMm": _mm(page_width),
+                    "pageHeightMm": _mm(page_height),
                 },
                 native=section,
                 parent_path="/",

{python_hwpx_automation-7.2.0 → python_hwpx_automation-7.3.1}/src/hwpx_automation/office/authoring/__init__.py

@@ -2030,6 +2030,10 @@ def _normalize_v2_page(value: Any) -> BuilderPageSize | None:
     width = _float_value(value.get("widthMm", value.get("width_mm")), default=210)
     height = _float_value(value.get("heightMm", value.get("height_mm")), default=297)
     orientation = str(value.get("orientation") or "PORTRAIT").strip() or "PORTRAIT"
+    # Hancom's own landscape values, as read from a document: WIDELY is
+    # portrait, NARROWLY landscape. Hand the builder the plain names so every
+    # python-hwpx version draws the same page.
+    orientation = {"WIDELY": "PORTRAIT", "NARROWLY": "LANDSCAPE"}.get(orientation.upper(), orientation)
     return BuilderPageSize(width_mm=width, height_mm=height, orientation=orientation)
 
 
@@ -2681,7 +2685,10 @@ def _flow_oversized_authored_table(table: Any) -> None:
     section = table.paragraph.section
     page = section.properties.page_size
     margins = section.properties.page_margins
-    body_height = page.height - margins.top - margins.bottom
+    # Hancom turns every page but landscape="WIDELY", so a landscape page's
+    # drawn height is its stored width.
+    drawn_height = page.height if page.orientation == "WIDELY" else page.width
+    body_height = drawn_height - margins.top - margins.bottom
     if body_height > 0 and table.height > body_height:
         table.set_treat_as_char(False)
 

{python_hwpx_automation-7.2.0 → python_hwpx_automation-7.3.1}/src/hwpx_automation/office/authoring/builder/core.py

@@ -1,8 +1,11 @@
 # SPDX-License-Identifier: Apache-2.0
 from __future__ import annotations
 
+from contextvars import ContextVar
 from dataclasses import dataclass, field
+from datetime import datetime, timezone
 from importlib import import_module
+from inspect import signature
 from os import PathLike
 from pathlib import Path
 from typing import Any, ClassVar, Mapping, Sequence, cast
@@ -23,6 +26,29 @@ BuilderChild = (
 )
 _HWP_UNITS_PER_MM = 7200 / 25.4
 _A4_HWP_SIZE = (59528, 84188)
+#: ``hp:pagePr@landscape`` as Hancom writes it: WIDELY draws the page as stored
+#: (portrait), NARROWLY turns it (landscape).
+_HANCOM_PAGE_ORIENTATION = {
+    "PORTRAIT": "WIDELY",
+    "WIDELY": "WIDELY",
+    "LANDSCAPE": "NARROWLY",
+    "NARROWLY": "NARROWLY",
+}
+
+
+def _hancom_page_form(orientation: str, width: int, height: int) -> tuple[str, int, int]:
+    """Return *orientation* and the page size in Hancom's own form.
+
+    Hancom stores both orientations with the paper's portrait size and turns
+    the page for NARROWLY. python-hwpx 6.5 writes the value as given and later
+    versions write the same form, so every core draws the same page. Unknown
+    values pass through unchanged.
+    """
+
+    value = _HANCOM_PAGE_ORIENTATION.get(orientation.strip().upper())
+    if value is None:
+        return orientation, width, height
+    return value, min(width, height), max(width, height)
 
 # Builder presets hook at Document.lower(), where a single
 # preset context can be passed into Heading/Run/Bullet lowering without
@@ -257,6 +283,8 @@ class Paragraph:
     children: Sequence[Run | PageNumber] = field(default_factory=tuple)
     align: str | None = None
     style: str | None = None
+    #: Optional caller name; ``save_to_path`` reports where it was written.
+    key: str | None = None
 
     def _alignment_para_pr(self, document: HwpxDocument) -> str | None:
         """Resolve ``align`` into the paragraph-property reference that emits it.
@@ -503,6 +531,8 @@ class Table:
     merges: Sequence[str] = field(default_factory=tuple)
     header_shading: str | None = None
     column_widths: Sequence[int | float] = field(default_factory=tuple)
+    #: Optional caller name; ``save_to_path`` reports the paragraph holding it.
+    key: str | None = None
 
     def lower(
         self,
@@ -794,13 +824,117 @@ def _merge_flags(*flag_sets: dict[str, bool]) -> dict[str, bool]:
     return merged
 
 
+# Keyed Paragraph/Table nodes -> the paragraph they were written to. While a
+# Document collects anchors, each keyed child records the paragraph counts
+# before it is lowered; after its section is lowered, the first paragraph added
+# since then is its element. Positions are read at the very end, by identity,
+# so a native TOC inserted afterwards cannot shift them.
+_AnchorEntry = tuple[str, tuple[int, ...], Any]
+_ANCHOR_SINK: ContextVar[list[_AnchorEntry] | None] = ContextVar(
+    "hwpx_builder_anchor_sink", default=None
+)
+
+
+def _paragraph_counts(document: HwpxDocument) -> tuple[int, ...]:
+    return tuple(len(section.paragraphs) for section in document.oxml.sections)
+
+
+def _anchor_mark(document: HwpxDocument, child: object) -> None:
+    sink = _ANCHOR_SINK.get()
+    key = getattr(child, "key", None)
+    if sink is not None and key is not None:
+        sink.append((key, _paragraph_counts(document), None))
+
+
+def _anchor_resolve(document: HwpxDocument) -> None:
+    sink = _ANCHOR_SINK.get()
+    if not sink:
+        return
+    sections = document.oxml.sections
+    for position, (key, before, element) in enumerate(sink):
+        if element is not None:
+            continue
+        for index, section in enumerate(sections):
+            start = before[index] if index < len(before) else 0
+            paragraphs = section.paragraphs
+            if len(paragraphs) > start:
+                sink[position] = (key, before, paragraphs[start].element)
+                break
+
+
+def _anchor_positions(
+    document: HwpxDocument, sink: Sequence[_AnchorEntry]
+) -> dict[str, dict[str, int]]:
+    positions: dict[int, dict[str, int]] = {}
+    for section_index, section in enumerate(document.oxml.sections):
+        for paragraph_index, paragraph in enumerate(section.paragraphs):
+            positions[id(paragraph.element)] = {
+                "section": section_index,
+                "paragraph": paragraph_index,
+            }
+    return {
+        key: dict(positions[id(element)])
+        for key, _before, element in sink
+        if element is not None and id(element) in positions
+    }
+
+
+def _check_unique_keys(sections: Sequence["Section"]) -> None:
+    seen: set[str] = set()
+    for section in sections:
+        for child in section.children:
+            key = getattr(child, "key", None)
+            if key is None:
+                continue
+            if key in seen:
+                raise ValueError(f"duplicate builder node key: {key!r}")
+            seen.add(key)
+
+
+def _write_package_metadata(document: HwpxDocument, metadata: Metadata) -> None:
+    """Write *metadata* to ``content.hpf`` (Hancom: File > Document Info).
+
+    OPF has no organization field, so ``organization`` stays in the save
+    report's ``metadata`` only. Created/modified are stamped at build time
+    instead of keeping the blank template's dates.
+    """
+
+    stamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+    document.parts.set_document_metadata(
+        title=metadata.title or None,
+        creator=metadata.author or None,
+        created_date=stamp,
+        modified_date=stamp,
+    )
+
+
+_SCHEMA_CHECK_NOT_RUN = "OWPML schema check could not run"
+
+
+def _schema_lint(document_report: object) -> str:
+    """``schema_lint`` from python-hwpx's own validation, never assumed.
+
+    python-hwpx 6.6+ checks headers and sections against the full OWPML schema
+    and reports violations as warnings. Older cores only check a lax section
+    stub, so nothing was schema-checked: report ``not_checked``, not ``pass``.
+    """
+
+    if "full_schema" not in signature(validate_document).parameters:
+        return "not_checked"
+    issues = getattr(document_report, "issues", ())
+    if any(_SCHEMA_CHECK_NOT_RUN in str(getattr(issue, "message", "")) for issue in issues):
+        return "not_checked"
+    if getattr(document_report, "errors", ()):
+        return "fail"
+    return "warning" if getattr(document_report, "warnings", ()) else "pass"
+
+
 def _hard_gates(
     package_report: object,
     document_report: object,
     reopen_report: ReopenReport,
     editor_open_safety_report: object | None = None,
 ) -> dict[str, str]:
-    document_warnings = getattr(document_report, "warnings", ())
     editor_open_safety_ok = (
         True
         if editor_open_safety_report is None
@@ -809,7 +943,7 @@ def _hard_gates(
     return {
         "package_validation": "pass" if getattr(package_report, "ok", False) else "fail",
         "document_errors": "pass" if getattr(document_report, "ok", False) else "fail",
-        "schema_lint": "warning" if document_warnings else "pass",
+        "schema_lint": _schema_lint(document_report),
         "reopen": "pass" if reopen_report.ok else "fail",
         "editor_open_safety": "pass" if editor_open_safety_ok else "fail",
         "id_integrity": "unavailable",
@@ -840,10 +974,11 @@ class Section:
             else:
                 width = _mm_to_hwp_units(self.page.width_mm)
                 height = _mm_to_hwp_units(self.page.height_mm)
+            orientation, width, height = _hancom_page_form(self.page.orientation, width, height)
             document.page.set_size(
                 width=width,
                 height=height,
-                orientation=self.page.orientation,
+                orientation=orientation,
                 section_index=section_index,
             )
         if self.margins is not None:
@@ -863,6 +998,7 @@ class Section:
             self.footer.lower(document, section_index=section_index, preset=preset)
         pending_native_tocs = native_toc_sink if native_toc_sink is not None else []
         for child in self.children:
+            _anchor_mark(document, child)
             if isinstance(child, (Paragraph, PageBreak)):
                 if isinstance(child, Paragraph):
                     child.lower(document, preset=preset)
@@ -901,6 +1037,7 @@ class Section:
                 )
                 continue
             raise NotImplementedError(f"{type(child).__name__} lowering is not implemented yet")
+        _anchor_resolve(document)
         if native_toc_sink is None:
             # standalone Section.lower call: resolve deferred TOCs now
             _apply_native_tocs(document, pending_native_tocs)
@@ -924,16 +1061,11 @@ class Document:
         return flags
 
     def lower(self) -> HwpxDocument:
+        _check_unique_keys(self.sections)
         document = HwpxDocument.new()
         preset = _builder_preset(self.preset)
         if self.metadata is not None:
-            for label, value in (
-                ("제목", self.metadata.title),
-                ("작성자", self.metadata.author),
-                ("기관", self.metadata.organization),
-            ):
-                if value:
-                    document.add_paragraph(f"{label}: {value}", inherit_style=False)
+            _write_package_metadata(document, self.metadata)
         pending_native_tocs: list[tuple[int, NativeToc]] = []
         for index, section in enumerate(self.sections):
             section.lower(
@@ -945,8 +1077,17 @@ class Document:
         _apply_native_tocs(document, pending_native_tocs)
         return document
 
+    def _lower_with_anchors(self) -> tuple[HwpxDocument, dict[str, dict[str, int]]]:
+        sink: list[_AnchorEntry] = []
+        token = _ANCHOR_SINK.set(sink)
+        try:
+            document = self.lower()
+        finally:
+            _ANCHOR_SINK.reset(token)
+        return document, _anchor_positions(document, sink)
+
     def save_to_path(self, path: str | PathLike[str]) -> BuilderSaveReport:
-        document = self.lower()
+        document, anchors = self._lower_with_anchors()
         # Funnel the write through the single SavePipeline and keep its uniform
         # report (plan §2 Phase B). Transparent policy -> behaviour-identical to
         # the prior ``document.save_to_path`` for a from-scratch (new) document.
@@ -982,6 +1123,7 @@ class Document:
             feature_flags=feature_flags,
             editor_open_safety=editor_open_safety_report,
             visual_complete=visual_complete,
+            anchors=anchors,
         )
         return report
 

{python_hwpx_automation-7.2.0 → python_hwpx_automation-7.3.1}/src/hwpx_automation/office/authoring/builder/report.py

@@ -62,6 +62,10 @@ class BuilderSaveReport:
     # through (plan §2 Phase B). Additive: ``None`` only if a caller builds a
     # report by hand without going through ``Document.save_to_path``.
     visual_complete: VisualCompleteReport | None = None
+    # ``key`` of each keyed Paragraph/Table -> ``{"section": i, "paragraph": j}``
+    # in the saved file (for a Table, the paragraph that holds it), so later
+    # edits need not find the node again by its text.
+    anchors: dict[str, dict[str, int]] = field(default_factory=dict)
 
     def __post_init__(self) -> None:
         hard_gates = dict(self.hard_gates)
@@ -80,6 +84,7 @@ class BuilderSaveReport:
             "path": str(self.path),
             "metadata": dict(self.metadata or {}),
             "hard_gates": dict(self.hard_gates),
+            "anchors": {key: dict(value) for key, value in self.anchors.items()},
             "fidelity_contract": {
                 "proves": list(FIDELITY_CONTRACT["proves"]),
                 "does_not_prove": list(FIDELITY_CONTRACT["does_not_prove"]),

{python_hwpx_automation-7.2.0 → python_hwpx_automation-7.3.1}/src/hwpx_automation/office/authoring/template_analyzer.py

@@ -333,6 +333,11 @@ def _extract_section_layout(section_path: str, section_xml: ET.Element) -> Secti
     margin = page_pr.find(f"{_HP_TAG}margin") if page_pr is not None else None
     margins = _margin_summary(margin)
     page_width = _int_attr(page_pr, "width")
+    page_height = _int_attr(page_pr, "height")
+    # Hancom draws a page as stored only for landscape="WIDELY" (portrait);
+    # NARROWLY, the schema default, turns it. Report the page as drawn.
+    if page_pr is not None and page_pr.get("landscape") != "WIDELY":
+        page_width, page_height = page_height, page_width
     body_width = None
     if page_width is not None:
         body_width = max(
@@ -345,7 +350,7 @@ def _extract_section_layout(section_path: str, section_xml: ET.Element) -> Secti
     return SectionLayoutSummary(
         section_path=section_path,
         page_width=page_width,
-        page_height=_int_attr(page_pr, "height"),
+        page_height=page_height,
         margins=margins,
         computed_body_width=body_width,
     )

python_hwpx_automation-7.3.1/src/hwpx_automation/office/rendering/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Run ``python -m hwpx_automation.office.rendering render-pdf IN OUT``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())