python-hwpx 2.19.0__py3-none-any.whl → 2.20.0__py3-none-any.whl

hwpx/tools/toc_author.py

@@ -0,0 +1,291 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Author Hancom-native TOC and page cross-reference fields (M7 / S-062 P2).
+
+Emits the exact field contract reverse-engineered from an owner-authored
+Hancom document (``specs/009-native-toc-xrefs/evidence/
+p0-native-toc-xml-contract.md``; gold pair vendored in
+``tests/fixtures/m7_toc_gold/``):
+
+* ``<hp:fieldBegin type="TABLEOFCONTENTS">`` + ``TableOfContents:set`` Command
+  DSL wrapping generated entry paragraphs (HYPERLINK fields whose single
+  ``<hp:t>`` nests the dot-leader ``hp:tab``; page number in the tab's tail),
+* ``<hp:fieldBegin type="CROSSREF">`` page references whose cached result is
+  the plain ``hp:t`` run between fieldBegin and fieldEnd (Hancom recomputes
+  these automatically on edit/save — P0 measured),
+* anchors that are plain paragraph ``id`` attributes; TOC-targeted headings
+  therefore need document-unique ids (:func:`ensure_paragraph_anchor_id`).
+
+Honest semantics (measured): entry page numbers emitted here are ESTIMATES —
+Hancom only recomputes the TOC block on an explicit 차례 새로 고침, which the
+P3 oracle triggers and verifies. CROSSREF caches self-heal on edit/save.
+The parameter spelling ``Fiexde`` replicates Hancom's own output verbatim.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Sequence
+from uuid import uuid4
+
+# live section paragraphs are lxml elements — new nodes must match
+from lxml import etree as ET
+
+from hwpx.document import HwpxDocument
+
+_HP = "{http://www.hancom.co.kr/hwpml/2011/paragraph}"
+_NON_UNIQUE_PARA_ID = "2147483648"
+_OUTLINE_NAME_RE = re.compile(r"^(?:개요|Outline)\s*(\d+)$")
+#: Measured TOC Command (gold contract). ContentsMake:uint:31 = the bitmask the
+#: Hancom dialog emitted (title+table+figure+equation blocks); other values are
+#: unmeasured, so v1 replicates the captured value verbatim.
+_TOC_COMMAND = (
+    "TableOfContents:set:140:ContentsMake:uint:31 ContentsStyles:wstring:0: "
+    "ContentsLevel:int:{level} ContentsAutoTabRight:int:0 "
+    "ContentsLeader:int:{leader} ContentsHyperlink:bool:{hyperlink}  "
+)
+
+
+def _rand_id() -> str:
+    return str(uuid4().int & 0x7FFFFFFF)
+
+
+def _existing_paragraph_ids(doc: HwpxDocument) -> set[str]:
+    ids: set[str] = set()
+    for section in doc.oxml.sections:
+        for p_el in section.element.iter(f"{_HP}p"):
+            pid = p_el.get("id")
+            if pid:
+                ids.add(pid)
+    return ids
+
+
+def ensure_paragraph_anchor_id(doc: HwpxDocument, paragraph: Any) -> str:
+    """Make ``paragraph`` addressable as a field anchor (``?#<id>``).
+
+    Hancom resolves TOC/CROSSREF targets by the paragraph ``id`` attribute, so
+    an anchor id must be unique in the document (generated paragraphs may all
+    carry the shared ``2147483648`` constant)."""
+    element = paragraph.element
+    pid = element.get("id")
+    ids = _existing_paragraph_ids(doc)
+    duplicated = pid and sum(1 for section in doc.oxml.sections
+                             for p in section.element.iter(f"{_HP}p")
+                             if p.get("id") == pid) > 1
+    if not pid or pid == _NON_UNIQUE_PARA_ID or duplicated:
+        new_id = _rand_id()
+        while new_id in ids:
+            new_id = _rand_id()
+        element.set("id", new_id)
+        pid = new_id
+    return pid
+
+
+def outline_heading_paragraphs(doc: HwpxDocument) -> list[tuple[Any, int, str]]:
+    """Return ``(paragraph, level, text)`` for 개요/Outline-styled paragraphs."""
+    levels: dict[str, int] = {}
+    for style_id, style in (doc.styles or {}).items():
+        name = getattr(style, "name", "") or ""
+        match = _OUTLINE_NAME_RE.match(name.strip())
+        if match:
+            levels[str(style_id)] = int(match.group(1))
+    result: list[tuple[Any, int, str]] = []
+    for section in doc.sections:
+        for paragraph in section.paragraphs:
+            style_ref = paragraph.element.get("styleIDRef")
+            if style_ref in levels and (paragraph.text or "").strip():
+                result.append((paragraph, levels[style_ref], paragraph.text.strip()))
+    return result
+
+
+# ── low-level field emission ─────────────────────────────────────────
+def _param(parent: ET.Element, kind: str, name: str, value: str, *, preserve: bool = False) -> None:
+    el = ET.SubElement(parent, f"{_HP}{kind}", {"name": name})
+    if preserve:
+        el.set("{http://www.w3.org/XML/1998/namespace}space", "preserve")
+    el.text = value
+
+
+def _field_begin(run: ET.Element, *, ftype: str, field_id: str, editable: str, dirty: str) -> ET.Element:
+    ctrl = ET.SubElement(run, f"{_HP}ctrl")
+    begin = ET.SubElement(
+        ctrl,
+        f"{_HP}fieldBegin",
+        {
+            "id": field_id,
+            "type": ftype,
+            "name": "",
+            "editable": editable,
+            "dirty": dirty,
+            "zorder": "-1",
+            "fieldid": _rand_id(),
+            "metaTag": "",
+        },
+    )
+    return begin
+
+
+def _field_end(run: ET.Element, field_id: str) -> None:
+    ctrl = ET.SubElement(run, f"{_HP}ctrl")
+    ET.SubElement(ctrl, f"{_HP}fieldEnd", {"beginIDRef": field_id})
+
+
+def _entry_paragraph(numbered_title: str, page: int, target_id: str, char_pr: str = "0") -> ET.Element:
+    """One generated TOC entry: HYPERLINK field wrapping ``title<tab/>page``."""
+    p = ET.Element(f"{_HP}p", {
+        "id": _rand_id(), "paraPrIDRef": "0", "styleIDRef": "0",
+        "pageBreak": "0", "columnBreak": "0", "merged": "0",
+    })
+    field_id = _rand_id()
+    run1 = ET.SubElement(p, f"{_HP}run", {"charPrIDRef": char_pr})
+    begin = _field_begin(run1, ftype="HYPERLINK", field_id=field_id, editable="0", dirty="1")
+    params = ET.SubElement(begin, f"{_HP}parameters", {"cnt": "5", "name": ""})
+    _param(params, "integerParam", "Prop", "0")
+    _param(params, "stringParam", "Command", f"?#{target_id};0;1;0;")
+    _param(params, "stringParam", "Category", "HWPHYPERLINK_TYPE_HWP")
+    _param(params, "stringParam", "TargetType", "HWPHYPERLINK_TARGET_OUTLINE")
+    _param(params, "stringParam", "DocOpenType", "HWPHYPERLINK_JUMP_CURRENTTAB")
+
+    run2 = ET.SubElement(p, f"{_HP}run", {"charPrIDRef": char_pr})
+    t = ET.SubElement(run2, f"{_HP}t")
+    t.text = numbered_title
+    tab = ET.SubElement(t, f"{_HP}tab", {"width": "34032", "leader": "3", "type": "2"})
+    tab.tail = str(page)
+
+    run3 = ET.SubElement(p, f"{_HP}run", {"charPrIDRef": char_pr})
+    _field_end(run3, field_id)
+    return p
+
+
+def mark_toc_dirty(doc: HwpxDocument) -> int:
+    """Set ``dirty="1"`` on every TABLEOFCONTENTS field — the measured
+    re-number trigger: Hancom regenerates a dirty TOC (entries, styles, page
+    numbers) when it next opens the document. Call after edits that shift
+    pagination. Returns the number of fields marked."""
+    count = 0
+    for section in doc.oxml.sections:
+        for begin in section.element.iter(f"{_HP}fieldBegin"):
+            if begin.get("type") == "TABLEOFCONTENTS":
+                begin.set("dirty", "1")
+                count += 1
+        if count:
+            section.mark_dirty()
+    return count
+
+
+def add_native_toc(
+    doc: HwpxDocument,
+    *,
+    at_index: int = 0,
+    title: str = "<제목 차례>",
+    level: int = 2,
+    leader: int = 3,
+    hyperlink: bool = True,
+    dirty: bool = True,
+    headings: Sequence[Any] | None = None,
+) -> dict[str, Any]:
+    """Insert a Hancom-native TABLEOFCONTENTS field region at ``at_index``.
+
+    Entries are generated from ``headings`` (paragraph wrappers) or, when
+    omitted, auto-detected 개요/Outline-styled paragraphs. Emitted entry page
+    numbers are naive estimates; with ``dirty=True`` (default, measured
+    semantics) Hancom regenerates the whole region — correct entries, styles,
+    and page numbers — on its next open, so the first thing a user sees is a
+    TOC Hancom itself computed. Returns a summary dict.
+
+    Collection note (measured): Hancom collects outline-styled paragraphs and
+    — via the ``ContentsStyles:wstring:0:`` command — style-0 (바탕글)
+    paragraphs too; give body text a non-collected style (e.g. 본문, style 1)
+    or it will appear as TOC entries after regeneration.
+    """
+    if headings is None:
+        detected = outline_heading_paragraphs(doc)
+    else:
+        detected = [(p, 1, (p.text or "").strip()) for p in headings]
+    if not detected:
+        raise ValueError("no outline headings found to build a TOC from")
+
+    anchors: list[tuple[str, int, str]] = []
+    for paragraph, lvl, text in detected:
+        anchor = ensure_paragraph_anchor_id(doc, paragraph)
+        anchors.append((anchor, lvl, text))
+
+    section = doc.oxml.sections[0]
+    toc_field_id = _rand_id()
+
+    # opening paragraph: [ctrl fieldBegin TABLEOFCONTENTS][t title]
+    open_p = ET.Element(f"{_HP}p", {
+        "id": _rand_id(), "paraPrIDRef": "0", "styleIDRef": "0",
+        "pageBreak": "0", "columnBreak": "0", "merged": "0",
+    })
+    run = ET.SubElement(open_p, f"{_HP}run", {"charPrIDRef": "0"})
+    begin = _field_begin(
+        run, ftype="TABLEOFCONTENTS", field_id=toc_field_id,
+        editable="1", dirty="1" if dirty else "0",
+    )
+    params = ET.SubElement(begin, f"{_HP}parameters", {"cnt": "2", "name": ""})
+    _param(params, "integerParam", "Prop", "8")
+    _param(
+        params, "stringParam", "Command",
+        _TOC_COMMAND.format(level=level, leader=leader, hyperlink=1 if hyperlink else 0),
+        preserve=True,
+    )
+    t = ET.SubElement(run, f"{_HP}t")
+    t.text = title
+
+    entry_elements = [
+        _entry_paragraph(f"{i}. {text}", 1, anchor)
+        for i, (anchor, _lvl, text) in enumerate(anchors, start=1)
+    ]
+
+    # closing paragraph: [ctrl fieldEnd]
+    close_p = ET.Element(f"{_HP}p", {
+        "id": _rand_id(), "paraPrIDRef": "0", "styleIDRef": "0",
+        "pageBreak": "0", "columnBreak": "0", "merged": "0",
+    })
+    close_run = ET.SubElement(close_p, f"{_HP}run", {"charPrIDRef": "0"})
+    _field_end(close_run, toc_field_id)
+
+    section.insert_paragraphs(at_index, [open_p, *entry_elements, close_p])
+    return {
+        "tocFieldId": toc_field_id,
+        "entryCount": len(anchors),
+        "anchors": [a for a, _l, _t in anchors],
+        "cachedPagesAreEstimates": True,
+    }
+
+
+def add_page_crossref(
+    doc: HwpxDocument,
+    paragraph: Any,
+    target_paragraph: Any,
+    *,
+    cached_page: int = 1,
+) -> dict[str, Any]:
+    """Append a Hancom-native page CROSSREF (상호참조 → 쪽 번호) to ``paragraph``.
+
+    The cached result run is a best-effort estimate; Hancom recomputes CROSSREF
+    caches automatically on edit/save (P0 measured on the gold pair: 2→3)."""
+    target_id = ensure_paragraph_anchor_id(doc, target_paragraph)
+    field_id = _rand_id()
+    p_el = paragraph.element
+
+    run1 = ET.SubElement(p_el, f"{_HP}run", {"charPrIDRef": "0"})
+    begin = _field_begin(run1, ftype="CROSSREF", field_id=field_id, editable="0", dirty="0")
+    params = ET.SubElement(begin, f"{_HP}parameters", {"cnt": "8", "name": ""})
+    _param(params, "booleanParam", "Fiexde", "1")  # sic — Hancom's own spelling
+    _param(params, "integerParam", "Prop", "0")
+    _param(params, "stringParam", "Command", f"?#{target_id};5;0;0;0;")
+    _param(params, "stringParam", "RefPath", f"?#{target_id};")
+    _param(params, "stringParam", "RefType", "TARGET_OUTLINE")
+    _param(params, "stringParam", "RefContentType", "OBJECT_TYPE_PAGE")
+    _param(params, "booleanParam", "RefHyperLink", "false")
+    _param(params, "stringParam", "RefOpenType", "HWPHYPERLINK_JUMP_CURRENTTAB")
+
+    run2 = ET.SubElement(p_el, f"{_HP}run", {"charPrIDRef": "0"})
+    t = ET.SubElement(run2, f"{_HP}t")
+    t.text = str(cached_page)
+
+    run3 = ET.SubElement(p_el, f"{_HP}run", {"charPrIDRef": "0"})
+    _field_end(run3, field_id)
+
+    paragraph.section.mark_dirty()
+    return {"fieldId": field_id, "targetId": target_id, "cachedPage": cached_page}

hwpx/tools/toc_fidelity.py

@@ -0,0 +1,410 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Native TOC / cross-reference fidelity harness (M7 / S-062).
+
+Parses the Hancom-native field contract captured in
+``specs/009-native-toc-xrefs/evidence/p0-native-toc-xml-contract.md``:
+
+* ``<hp:fieldBegin type="TABLEOFCONTENTS">`` region whose generated entries are
+  HYPERLINK fields wrapping a single ``<hp:t>`` of the form
+  ``제목텍스트<hp:tab leader=".."/>쪽번호`` (page number lives in the *tail* of
+  the nested ``hp:tab``),
+* ``<hp:fieldBegin type="CROSSREF">`` whose cached result is the plain ``hp:t``
+  run between its fieldBegin and fieldEnd,
+* anchors that are plain paragraph ``id`` attributes (``?#<para-id>``).
+
+Measured semantics (P0, owner-confirmed): CROSSREF caches recompute
+automatically on edit/save; the TOC block only recomputes after an explicit
+차례 새로 고침 — so ``dirty`` is NOT a reliable staleness marker and the only
+honest verdict comes from comparing cached page numbers against rendered ones
+(Hancom render -> fitz words). Without an oracle the report degrades to a
+structural verdict with ``render_checked=False`` (Constitution V/IX).
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Sequence
+
+from hwpx.document import HwpxDocument
+
+_HP = "{http://www.hancom.co.kr/hwpml/2011/paragraph}"
+_TARGET_RE = re.compile(r"\?#(\d+)")
+#: Generated paragraphs share this constant id — useless as an anchor.
+NON_UNIQUE_PARA_ID = "2147483648"
+
+
+@dataclass(frozen=True)
+class TocEntry:
+    target_id: str | None
+    title: str
+    cached_page: int | None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"targetId": self.target_id, "title": self.title, "cachedPage": self.cached_page}
+
+
+@dataclass(frozen=True)
+class CrossRef:
+    target_id: str | None
+    cached_page: int | None
+    ref_content_type: str | None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "targetId": self.target_id,
+            "cachedPage": self.cached_page,
+            "refContentType": self.ref_content_type,
+        }
+
+
+@dataclass
+class TocModel:
+    """Everything the harness reads out of one document's XML."""
+
+    toc_field_id: str | None = None
+    toc_command: str | None = None
+    entries: list[TocEntry] = field(default_factory=list)
+    crossrefs: list[CrossRef] = field(default_factory=list)
+    paragraph_texts: dict[str, str] = field(default_factory=dict)  # para id -> text
+
+
+# ── XML parsing ──────────────────────────────────────────────────────
+def _open(source: str | Path | bytes | HwpxDocument) -> HwpxDocument:
+    if isinstance(source, HwpxDocument):
+        return source
+    return HwpxDocument.open(source)
+
+
+def _para_text(p_el: Any) -> str:
+    parts: list[str] = []
+    for t in p_el.iter(f"{_HP}t"):
+        if t.text:
+            parts.append(t.text)
+        for child in t:
+            if child.tail:
+                parts.append(child.tail)
+    return "".join(parts)
+
+
+def _field_type(ctrl_el: Any) -> tuple[Any, str] | None:
+    begin = ctrl_el.find(f"{_HP}fieldBegin")
+    if begin is None:
+        return None
+    return begin, begin.get("type", "")
+
+
+def _string_params(begin_el: Any) -> dict[str, str]:
+    params: dict[str, str] = {}
+    parameters = begin_el.find(f"{_HP}parameters")
+    if parameters is None:
+        return params
+    for child in parameters:
+        name = child.get("name")
+        if name:
+            params[name] = child.text or ""
+    return params
+
+
+def _target_of(params: dict[str, str]) -> str | None:
+    for key in ("RefPath", "Command"):
+        value = params.get(key) or ""
+        match = _TARGET_RE.search(value)
+        if match:
+            return match.group(1)
+    return None
+
+
+def parse_toc_model(source: str | Path | bytes | HwpxDocument) -> TocModel:
+    """Parse the native TOC field region, CROSSREF fields, and paragraph ids."""
+    doc = _open(source)
+    model = TocModel()
+
+    for section in doc.oxml.sections:
+        root = section.element
+        inside_toc = False  # region state spans paragraphs (fieldBegin..fieldEnd)
+        for p_el in root.iter(f"{_HP}p"):
+            pid = p_el.get("id")
+            if pid and pid not in model.paragraph_texts:
+                model.paragraph_texts[pid] = _para_text(p_el)
+
+            # walk runs/ctrls in document order with a tiny state machine
+            hyperlink_target: str | None = None
+            crossref: dict[str, Any] | None = None
+            for run in p_el.findall(f"{_HP}run"):
+                for child in run:
+                    tag = child.tag
+                    if tag == f"{_HP}ctrl":
+                        info = _field_type(child)
+                        if info is None:
+                            end = child.find(f"{_HP}fieldEnd")
+                            if end is not None:
+                                # closes an open crossref…
+                                if crossref is not None:
+                                    model.crossrefs.append(
+                                        CrossRef(
+                                            target_id=crossref["target"],
+                                            cached_page=crossref["page"],
+                                            ref_content_type=crossref["content_type"],
+                                        )
+                                    )
+                                    crossref = None
+                                # …or the TOC region itself
+                                if inside_toc and end.get("beginIDRef") == model.toc_field_id:
+                                    inside_toc = False
+                            continue
+                        begin, ftype = info
+                        params = _string_params(begin)
+                        if ftype == "TABLEOFCONTENTS":
+                            model.toc_field_id = begin.get("id")
+                            model.toc_command = params.get("Command")
+                            inside_toc = True
+                        elif ftype == "CROSSREF":
+                            crossref = {
+                                "target": _target_of(params),
+                                "page": None,
+                                "content_type": params.get("RefContentType"),
+                            }
+                        elif ftype == "HYPERLINK":
+                            hyperlink_target = _target_of(params)
+                    elif tag == f"{_HP}t":
+                        if crossref is not None:
+                            digits = (child.text or "").strip()
+                            if digits.isdigit():
+                                crossref["page"] = int(digits)
+                            continue
+                        tab = child.find(f"{_HP}tab")
+                        if tab is not None and (hyperlink_target is not None or inside_toc):
+                            # Hyperlinked entry (ContentsHyperlink:1, gold) or the
+                            # PLAIN entry Hancom regenerates with ContentsHyperlink:0
+                            # (measured on a refreshed save): same t+tab+page shape,
+                            # no target reference — identity resolves by title.
+                            title = (child.text or "").strip()
+                            page_text = (tab.tail or "").strip()
+                            model.entries.append(
+                                TocEntry(
+                                    target_id=hyperlink_target,
+                                    title=title,
+                                    cached_page=int(page_text) if page_text.isdigit() else None,
+                                )
+                            )
+                            hyperlink_target = None
+    return model
+
+
+# ── structural verdict (oracle-free) ─────────────────────────────────
+def structural_report(source: str | Path | bytes | HwpxDocument) -> dict[str, Any]:
+    """Oracle-free checks: fields present, anchors resolve, internal consistency.
+
+    ``internal_conflicts`` cross-checks CROSSREF caches (auto-recomputed by
+    Hancom) against TOC entry caches (explicit-refresh only) for shared
+    targets — a disagreement proves the TOC block is stale without any render.
+    """
+    model = parse_toc_model(source)
+    targets = [e.target_id for e in model.entries] + [c.target_id for c in model.crossrefs]
+    unresolved = [t for t in targets if t and t not in model.paragraph_texts]
+
+    conflicts: list[dict[str, Any]] = []
+    entry_pages = {e.target_id: e.cached_page for e in model.entries if e.target_id}
+    for ref in model.crossrefs:
+        if ref.target_id in entry_pages and ref.cached_page is not None:
+            toc_page = entry_pages[ref.target_id]
+            if toc_page is not None and toc_page != ref.cached_page:
+                conflicts.append(
+                    {
+                        "targetId": ref.target_id,
+                        "tocCachedPage": toc_page,
+                        "crossrefCachedPage": ref.cached_page,
+                    }
+                )
+
+    return {
+        "hasNativeToc": model.toc_field_id is not None,
+        "tocCommand": model.toc_command,
+        "entryCount": len(model.entries),
+        "crossrefCount": len(model.crossrefs),
+        "entries": [e.to_dict() for e in model.entries],
+        "crossrefs": [c.to_dict() for c in model.crossrefs],
+        "unresolvedTargets": unresolved,
+        "targetsResolve": not unresolved,
+        "internal_conflicts": conflicts,
+        "internally_consistent": not conflicts,
+    }
+
+
+# ── repagination trigger ─────────────────────────────────────────────
+def grow_paragraph(doc: HwpxDocument, *, contains: str, added_chars: int = 2000) -> bool:
+    """Lengthen the first body paragraph containing ``contains`` to force a
+    page shift on the next Hancom re-layout. Returns True when applied."""
+    filler = " 재배열을 유발하기 위한 채움 문장입니다." * (added_chars // 24 + 1)
+    for section in doc.sections:
+        for paragraph in section.paragraphs:
+            text = paragraph.text or ""
+            if contains in text:
+                paragraph.text = text + filler[:added_chars]
+                return True
+    return False
+
+
+# ── oracle leg ───────────────────────────────────────────────────────
+def _normalize(text: str) -> str:
+    return re.sub(r"\s+", "", text)
+
+
+_OUTLINE_PREFIX_RE = re.compile(r"^\d+(?:\.\d+)*\.?")
+
+
+def heading_rendered_pages(pdf_path: str, headings: dict[str, str]) -> dict[str, int | None]:
+    """Locate each heading's rendered page (1-based) via the PDF text layer.
+
+    Line-exact matching (measured discipline — a page-substring heuristic
+    misfires two ways against a real Hancom render: body echoes of the title
+    match later pages, and excluding the TOC's page hides a heading that
+    shares it). A rendered heading is a *whole line* equal to the title,
+    optionally prefixed by its outline number ("1." / "2.1"). TOC entry lines
+    never match (they carry a trailing leader + page digits) and body echoes
+    never match (the line continues past the title). Wrapped multi-line
+    headings are a known limitation — keep demo headings single-line.
+    """
+    from hwpx.form_fit.wordbox import extract_word_boxes
+
+    boxes = extract_word_boxes(pdf_path)
+    grouped: dict[tuple[int, int, int], list[Any]] = {}
+    for box in boxes:
+        grouped.setdefault((box.page, box.block, box.line), []).append(box)
+    lines: list[tuple[int, str]] = []
+    for (page, _block, _line), words in sorted(grouped.items()):
+        text = _normalize("".join(w.text for w in sorted(words, key=lambda w: w.word_no)))
+        if text:
+            lines.append((page, text))
+
+    result: dict[str, int | None] = {}
+    for para_id, title in headings.items():
+        needle = _normalize(title)
+        found: int | None = None
+        if needle:
+            for page, line_text in lines:
+                if line_text == needle or _OUTLINE_PREFIX_RE.sub("", line_text) == needle:
+                    # LAST match wins: the TOC region precedes the body, and a
+                    # TOC entry whose page digit wraps to its own line (no
+                    # right tab stop) is indistinguishable from a numbered
+                    # heading line — measured against a real render of our own
+                    # emission. The real heading always follows the TOC.
+                    found = page + 1  # fitz 0-based -> Hancom 1-based
+        result[para_id] = found
+    return result
+
+
+def toc_verify(
+    source: str | Path | bytes,
+    *,
+    oracle: Any | None = None,
+    pdf_path: str | None = None,
+) -> dict[str, Any]:
+    """Full verdict: structural report + (when a render is available) cached
+    page numbers checked against rendered heading pages.
+
+    Pass ``pdf_path`` to reuse an existing render; else ``oracle.render_pdf``
+    is used when the oracle reports available. Otherwise degrades honestly.
+    """
+    structural = structural_report(source)
+    report: dict[str, Any] = {
+        "structural": structural,
+        "render_checked": False,
+        "toc_correctness_ratio": None,
+        "stale_entries": [],
+        "crossref_correctness_ratio": None,
+        "verdict": "unverified",
+    }
+
+    model = parse_toc_model(source)
+
+    def _entry_key(entry: TocEntry) -> str | None:
+        """Lookup key for an entry: its anchor id, or (plain regenerated
+        entries carry no target reference) a title-derived key."""
+        if entry.target_id:
+            return entry.target_id
+        stripped = _OUTLINE_PREFIX_RE.sub("", _normalize(entry.title))
+        return f"title::{stripped}" if stripped else None
+
+    headings: dict[str, str] = {}
+    for t in {e.target_id for e in model.entries} | {c.target_id for c in model.crossrefs}:
+        if t and t in model.paragraph_texts and model.paragraph_texts[t].strip():
+            headings[t] = model.paragraph_texts[t]
+    for entry in model.entries:
+        key = _entry_key(entry)
+        if key and key.startswith("title::"):
+            # identity by title: the rendered heading line equals the entry
+            # title minus its numbering prefix
+            title = _OUTLINE_PREFIX_RE.sub("", entry.title.strip()).strip()
+            if title:
+                headings[key] = title
+
+    rendered_pdf = pdf_path
+    if rendered_pdf is None and oracle is not None:
+        try:
+            if getattr(oracle, "available", lambda: False)():
+                src = source if isinstance(source, (str, Path)) else None
+                if src is None:
+                    import tempfile
+
+                    handle, tmp = tempfile.mkstemp(suffix=".hwpx")
+                    Path(tmp).write_bytes(source)  # type: ignore[arg-type]
+                    src = tmp
+                rendered_pdf = oracle.render_pdf(str(src))
+        except Exception:  # pragma: no cover - defensive: degrade, never crash
+            rendered_pdf = None
+
+    if not rendered_pdf:
+        if not structural["internally_consistent"]:
+            report["verdict"] = "stale_detected_structurally"
+        return report
+
+    try:
+        actual = heading_rendered_pages(rendered_pdf, headings)
+    except Exception:  # pragma: no cover - fitz/pdf failure -> honest degrade
+        return report
+
+    report["render_checked"] = True
+    report["rendered_pdf"] = rendered_pdf
+    report["heading_pages"] = actual
+
+    stale: list[dict[str, Any]] = []
+    scored = 0
+    correct = 0
+    entry_rows: list[dict[str, Any]] = []
+    for entry in model.entries:
+        actual_page = actual.get(_entry_key(entry) or "")
+        row = entry.to_dict() | {"actualPage": actual_page}
+        if entry.cached_page is not None and actual_page is not None:
+            scored += 1
+            if entry.cached_page == actual_page:
+                correct += 1
+            else:
+                stale.append(row)
+        entry_rows.append(row)
+    report["toc_entries"] = entry_rows
+    report["toc_correctness_ratio"] = (correct / scored) if scored else None
+    report["stale_entries"] = stale
+
+    xr_scored = xr_correct = 0
+    xr_rows: list[dict[str, Any]] = []
+    for ref in model.crossrefs:
+        actual_page = actual.get(ref.target_id or "")
+        row = ref.to_dict() | {"actualPage": actual_page}
+        if ref.cached_page is not None and actual_page is not None:
+            xr_scored += 1
+            if ref.cached_page == actual_page:
+                xr_correct += 1
+        xr_rows.append(row)
+    report["crossrefs"] = xr_rows
+    report["crossref_correctness_ratio"] = (xr_correct / xr_scored) if xr_scored else None
+
+    ratios = [r for r in (report["toc_correctness_ratio"], report["crossref_correctness_ratio"]) if r is not None]
+    if not ratios:
+        report["verdict"] = "unverified"
+    elif all(r == 1.0 for r in ratios):
+        report["verdict"] = "verified"
+    else:
+        report["verdict"] = "stale"
+    return report

hwpx/visual/_refresh_hwpx_mac.applescript

@@ -0,0 +1,162 @@
+-- SPDX-License-Identifier: Apache-2.0
+-- Mac Hancom field-refresh backend (M7 native TOC / cross-references).
+--
+-- Opens an .hwpx IN PLACE, lets Hancom regenerate any dirty="1" fields
+-- (measured semantics: a dirty TABLEOFCONTENTS is rebuilt on open — entries,
+-- styles, and page numbers recomputed by Hancom itself; CROSSREF caches
+-- recompute automatically), saves the document back over the same path
+-- (파일 > 저장하기), and closes it.
+--
+-- Why save-then-close instead of exporting a PDF from the regenerating
+-- session: this Hancom build crashes when PDF export runs right after an
+-- open-time TOC regeneration (measured: deterministic %%EOF-less torsos, then
+-- the process dies). The refreshed FILE is stable; render it in a fresh
+-- session afterwards.
+--
+-- Usage:  osascript _refresh_hwpx_mac.applescript <doc.hwpx> [timeoutSecs]
+-- Output: "OK" on success; "ERR: <reason>" otherwise.
+
+property procName : "Hancom Office HWP"
+property appName : "Hancom Office HWP"
+property fileMenuName : "파일"
+property saveItemName : "저장하기"
+property closeDocPrefix : "문서 닫기"
+
+on run argv
+	if (count of argv) < 1 then return "ERR: usage: <doc.hwpx> [timeoutSecs]"
+	set inputPath to item 1 of argv
+	set timeoutSecs to 90
+	if (count of argv) ≥ 2 then
+		try
+			set timeoutSecs to (item 2 of argv) as integer
+		end try
+	end if
+	set inputBase to do shell script "basename " & quoted form of inputPath
+
+	try
+		do shell script "open -a " & quoted form of appName & " " & quoted form of inputPath
+		if not (waitForWindowNamed(inputBase, timeoutSecs)) then
+			return "ERR: document window did not open: " & inputBase
+		end if
+		-- Let the dirty-field regeneration settle before saving.
+		delay 3
+
+		clickFileMenuItem(saveItemName, false)
+		delay 2
+		-- A compat/format sheet may appear on save: accept the default.
+		pressReturnOnAnySheet()
+		delay 1
+
+		clickFileMenuItem(closeDocPrefix, true)
+		delay 1
+		-- If a save-changes sheet still appears, discard (we already saved).
+		dismissDontSaveSheetIfPresent()
+		return "OK"
+	on error errMsg number errNum
+		try
+			clickFileMenuItem(closeDocPrefix, true)
+			dismissDontSaveSheetIfPresent()
+		end try
+		return "ERR: " & errMsg & " (" & errNum & ")"
+	end try
+end run
+
+on clickFileMenuItem(itemName, prefixMatch)
+	tell application "System Events" to tell process procName
+		set frontmost to true
+		delay 0.2
+		set fileMenu to missing value
+		repeat with mbi in menu bar items of menu bar 1
+			if (name of mbi as string) is fileMenuName then
+				set fileMenu to menu 1 of mbi
+				exit repeat
+			end if
+		end repeat
+		if fileMenu is missing value then error "menu '" & fileMenuName & "' not found"
+		repeat with mi in menu items of fileMenu
+			try
+				set miName to (name of mi as string)
+				if (prefixMatch and miName starts with itemName) or (not prefixMatch and miName is itemName) then
+					click mi
+					return
+				end if
+			end try
+		end repeat
+		error "menu item not found: " & itemName
+	end tell
+end clickFileMenuItem
+
+on windowNames()
+	try
+		tell application "System Events" to tell process procName
+			return (name of windows) as list
+		end tell
+	on error
+		return {}
+	end try
+end windowNames
+
+on listContains(theList, theValue)
+	repeat with x in theList
+		if (x as string) is theValue then return true
+	end repeat
+	return false
+end listContains
+
+on waitForWindowNamed(winName, secs)
+	repeat (secs * 2) times
+		if listContains(windowNames(), winName) then return true
+		delay 0.5
+	end repeat
+	return false
+end waitForWindowNamed
+
+on pressReturnOnAnySheet()
+	repeat 4 times
+		set found to false
+		try
+			tell application "System Events" to tell process procName
+				repeat with i from 1 to (count of windows)
+					try
+						if (count of sheets of window i) > 0 then
+							set frontmost to true
+							key code 36 -- Return = default button
+							set found to true
+						end if
+					end try
+				end repeat
+			end tell
+		end try
+		if not found then return false
+		delay 0.8
+	end repeat
+	return true
+end pressReturnOnAnySheet
+
+on dismissDontSaveSheetIfPresent()
+	repeat 6 times
+		set handled to false
+		try
+			tell application "System Events" to tell process procName
+				repeat with i from 1 to (count of windows)
+					try
+						if (count of sheets of window i) > 0 then
+							repeat with b in buttons of (sheet 1 of window i)
+								try
+									set bn to (name of b as string)
+									if bn contains "안 함" or bn contains "안함" then
+										click b
+										set handled to true
+									end if
+								end try
+							end repeat
+						end if
+					end try
+				end repeat
+			end tell
+		end try
+		if handled then return true
+		delay 0.3
+	end repeat
+	return false
+end dismissDontSaveSheetIfPresent

hwpx/visual/_render_hwpx_mac.applescript

@@ -162,8 +162,12 @@ on waitForWindowGone(winName, secs)
 end waitForWindowGone
 
 on waitForFile(p, secs)
+	-- size>0 alone is NOT completion: Hancom streams the PDF asynchronously and
+	-- closing the document mid-write truncates it (measured: a TOC-regenerating
+	-- document produced a deterministic %%EOF-less torso). Require the PDF
+	-- trailer marker so the export has actually finished before we move on.
 	repeat (secs * 2) times
-		if (do shell script "test -s " & quoted form of p & " && echo 1 || echo 0") is "1" then
+		if (do shell script "test -s " & quoted form of p & " && tail -c 64 " & quoted form of p & " | grep -q '%%EOF' && echo 1 || echo 0") is "1" then
 			return true
 		end if
 		delay 0.5

hwpx/visual/oracle.py

@@ -52,6 +52,7 @@ from hwpx.form_fit.wordbox import WordBox
 _BACKEND_SCRIPT = "_render_hwpx.ps1"
 _OPEN_RATE_SCRIPT = "_hancom_open_rate.ps1"
 _MAC_BACKEND_SCRIPT = "_render_hwpx_mac.applescript"
+_MAC_REFRESH_SCRIPT = "_refresh_hwpx_mac.applescript"
 _COM_REGISTRY_KEYS = (
     r"HWPFrame.HwpObject\CLSID",
     r"SOFTWARE\Classes\HWPFrame.HwpObject\CLSID",
@@ -493,6 +494,42 @@ class MacHancomOracle(RenderBackend):
                 except OSError:
                     pass
 
+    def refresh_document(self, hwpx_path: str) -> bool:
+        """Open ``hwpx_path``, let dirty fields regenerate, save in place, close.
+
+        The measured native-TOC re-number trigger (M7): a ``dirty="1"``
+        TABLEOFCONTENTS is rebuilt on open — Hancom itself computes entries and
+        page numbers — and CROSSREF caches recompute automatically. Exporting a
+        PDF from the same regenerating session crashes this Hancom build
+        (deterministic truncated PDFs, then the process dies), so refresh and
+        render are intentionally two separate sessions. Returns True when the
+        file was re-saved.
+        """
+        if not self.available():
+            return False
+        src = os.path.abspath(hwpx_path)
+        try:
+            before = os.stat(src).st_mtime_ns
+        except OSError:
+            return False
+        with resources.as_file(
+            resources.files("hwpx.visual").joinpath(_MAC_REFRESH_SCRIPT)
+        ) as script:
+            cmd = [self._osascript, str(script), src, str(int(self.timeout))]
+            try:
+                proc = subprocess.run(
+                    cmd, capture_output=True, text=True,
+                    timeout=self.timeout + 60.0, check=False,
+                )
+            except (subprocess.TimeoutExpired, OSError):
+                return False
+        if "OK" not in (proc.stdout or ""):
+            return False
+        try:
+            return os.stat(src).st_mtime_ns != before
+        except OSError:
+            return False
+
 
 class NullOracle(RenderBackend):
     """Sentinel backend for environments with no reachable Hancom.

{python_hwpx-2.19.0.dist-info → python_hwpx-2.20.0.dist-info}/METADATA

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

{python_hwpx-2.19.0.dist-info → python_hwpx-2.20.0.dist-info}/RECORD

@@ -131,6 +131,8 @@ hwpx/tools/table_navigation.py,sha256=rtbrWFKpJhqC3LD0ZXImyHgjmDR2hjHCFy3_S-qNBw
 hwpx/tools/template_analyzer.py,sha256=LEc5xazy0YwPCY5sLycSvOk3U8NRMKWDYDu_rz1WZXM,23802
 hwpx/tools/text_extract_cli.py,sha256=BmsDAwNXpDPhEayb9ez2ORtGNzPd_Xxduy4_cLXhnUw,2188
 hwpx/tools/text_extractor.py,sha256=m9OSBd4FjZrzlMP8b4uS2Lnmjp-u-t7EBKFDF3P1bTM,25514
+hwpx/tools/toc_author.py,sha256=vkAwMO6uTR9Rk8Sy5h6Zvx8uYb_vbptr7bBi2EBLfNI,11932
+hwpx/tools/toc_fidelity.py,sha256=POljSwcjFFmLMtXH5WVmzGA03aBMLcN39hg52DpdRzM,17336
 hwpx/tools/validator.py,sha256=U856izL9NcJZOiKDYoCpwOSaFNQ2Un8Jn4pzL20A96Q,7100
 hwpx/tools/_schemas/header.xsd,sha256=mJXuFMuHGT1JnFFaluUpYUglwjMCNlfbFCRVM26eHXE,664
 hwpx/tools/_schemas/section.xsd,sha256=MgvavVHG05RDfUnVPxVU10H4FQOja5ON04_m9Uk_m7E,522
@@ -142,17 +144,18 @@ hwpx/tools/fuzz/minimize.py,sha256=gv9fEU1PsmpXR-Z6wiejMC0umHV90GYhtO2Ht8x2__Y,1
 hwpx/tools/fuzz/runner.py,sha256=NkSrlWUf813SqEwkhi05LmusMgM9r2j2JiPCqzzvPN8,17906
 hwpx/visual/__init__.py,sha256=KCmFghTLZjWA1reS-dHhdrn2i0FBUQMUv3qghZb7Fqo,2347
 hwpx/visual/_hancom_open_rate.ps1,sha256=stgE7ID2DuIpHWZHi414hmPuvPKnbecPO-oLrFWYBSg,16016
+hwpx/visual/_refresh_hwpx_mac.applescript,sha256=N26GN5hYjXUwhh_LYI-wt3DWTFwshUX4hBpCDrODEXc,4684
 hwpx/visual/_render_hwpx.ps1,sha256=r7bUPQvMMwVhz5YiUIEZPSAO18GbPPfnaK8iZb67d3w,2412
-hwpx/visual/_render_hwpx_mac.applescript,sha256=ghyvFNwtJ3-0cfy8jQ6HyuJVnFFfXt_Uy5tHjccd5os,7620
+hwpx/visual/_render_hwpx_mac.applescript,sha256=Zq-D0HOlz7xlIeN1su1nL4EzSU9rBmPlvtU4HBwdr08,7980
 hwpx/visual/detectors.py,sha256=WySbPnhyp4vTZWtkHoAiNY9G9AoZbVNgVgwaEZzt1R0,4853
 hwpx/visual/diff.py,sha256=0X5T9IgwRZU3td-7vnPrlowovtGud7P_ymq0KVehlKk,5677
 hwpx/visual/masks.py,sha256=oXhgynAb4uKjJtZ2BGHHdAjyvWGqSFlZFQ-iJxzHiuo,1832
-hwpx/visual/oracle.py,sha256=aON9dPbpbYnUoQ7b1aD5bez2d8BevYeZgWbxdIhP_sA,29746
+hwpx/visual/oracle.py,sha256=VNO-tAB-lzTdW5XtSELxg_Aau369qRFBsJvNryHF_D8,31319
 hwpx/visual/report.py,sha256=2RhXN1KBYOZTim9FNpeUhaaDHR7oFxI6Z2DLUkDIiwE,1717
-python_hwpx-2.19.0.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
-python_hwpx-2.19.0.dist-info/licenses/NOTICE,sha256=k48h6EaGQE8Y1c0dS9sIOOcz4YqkbcImWClF7pBOgsg,2473
-python_hwpx-2.19.0.dist-info/METADATA,sha256=R1wYmaa1RlVZuuDuGl4CyQsdl-56YSBbB1_IjZu1WGs,19982
-python_hwpx-2.19.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-python_hwpx-2.19.0.dist-info/entry_points.txt,sha256=4U6WXYWHxEiWp2VRHo97fvOYNh7ebu6roonk7chxKcY,453
-python_hwpx-2.19.0.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
-python_hwpx-2.19.0.dist-info/RECORD,,
+python_hwpx-2.20.0.dist-info/licenses/LICENSE,sha256=_ubz4wv-BkkT3l3gu-QuH7JGeVjuRYGZoZK95eNsCHU,9688
+python_hwpx-2.20.0.dist-info/licenses/NOTICE,sha256=k48h6EaGQE8Y1c0dS9sIOOcz4YqkbcImWClF7pBOgsg,2473
+python_hwpx-2.20.0.dist-info/METADATA,sha256=ocHd1cXv2SP9a-kS7cxsutbef5hTE-3Ox8IpK2ii8FA,19982
+python_hwpx-2.20.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+python_hwpx-2.20.0.dist-info/entry_points.txt,sha256=4U6WXYWHxEiWp2VRHo97fvOYNh7ebu6roonk7chxKcY,453
+python_hwpx-2.20.0.dist-info/top_level.txt,sha256=R1iToqDh80Nf2oQhRjTN0rbN2X6kyDUizIocZjkhuxc,5
+python_hwpx-2.20.0.dist-info/RECORD,,