document-adapter 0.3.0__tar.gz → 0.4.0__tar.gz

document_adapter-0.4.0/NOTICE

@@ -0,0 +1,29 @@
+document-adapter
+Copyright 2026 Son Seongjun / PlateerLab
+
+This product includes software developed at PlateerLab
+(https://github.com/PlateerLab).
+
+===============================================================================
+Third-party code attributions
+===============================================================================
+
+HWPX table grid parsing logic
+-----------------------------
+
+Portions of the HWPX table grid construction in
+`document_adapter/hwpx_core/grid.py` (cell position / cell span parsing, and
+the skip-map approach for merged non-anchor cells) are adapted from:
+
+  PlateerLab/xgen-doc2chunk
+  https://github.com/PlateerLab/xgen-doc2chunk
+  Licensed under the Apache License, Version 2.0
+
+The adapted logic is limited to read-side grid construction. All edit-side
+functionality (cell writing, row insertion, ZIP round-trip preservation) is
+original to this project.
+
+You may obtain a copy of the Apache License 2.0 at:
+  http://www.apache.org/licenses/LICENSE-2.0
+
+===============================================================================

{document_adapter-0.3.0 → document_adapter-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: document-adapter
-Version: 0.3.0
+Version: 0.4.0
 Summary: LLM-friendly document template editing (DOCX/PPTX/HWPX) with MCP server and Claude API tool-use support
 Author-email: Son Seongjun <sonsj97@plateer.com>
 License: MIT
@@ -9,7 +9,7 @@ Project-URL: Repository, https://github.com/PlateerLab/document-adapter
 Project-URL: Issues, https://github.com/PlateerLab/document-adapter/issues
 Project-URL: PyPI, https://pypi.org/project/document-adapter/
 Project-URL: Changelog, https://github.com/PlateerLab/document-adapter/releases
-Keywords: mcp,model-context-protocol,llm,claude,anthropic,tool-use,agent,document,docx,pptx,hwpx,hwp,template,template-engine,office,office-automation,word,powerpoint,hancom,korean,docxtpl,python-docx,python-pptx,python-hwpx
+Keywords: mcp,model-context-protocol,llm,claude,anthropic,tool-use,agent,document,docx,pptx,hwpx,hwp,template,template-engine,office,office-automation,word,powerpoint,hancom,korean,docxtpl,python-docx,python-pptx,lxml
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -26,15 +26,17 @@ Classifier: Environment :: Console
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: python-docx>=1.1
+License-File: NOTICE
+Requires-Dist: python-docx>=1.2
 Requires-Dist: docxtpl>=0.20
 Requires-Dist: python-pptx>=1.0
-Requires-Dist: python-hwpx>=2.9
+Requires-Dist: lxml>=5.0
 Requires-Dist: mcp>=1.0
 Provides-Extra: claude
 Requires-Dist: anthropic>=0.40; extra == "claude"
 Provides-Extra: dev
 Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: python-hwpx>=2.9; extra == "dev"
 Dynamic: license-file
 
 # document-adapter
@@ -57,12 +59,18 @@ Dynamic: license-file
 |---|---|---|---|---|---|---|---|
 | `.docx` | `docxtpl` + `python-docx` | Jinja2 (`{%tr%}` loop 포함) | ✅ | ✅ | ✅ | ✅ | ✅ |
 | `.pptx` | `python-pptx` | `{{key}}` 치환 | ✅ (슬라이드 위치 포함) | ✅ | — (포맷 미지원) | ✅ | ❌ (미지원) |
-| `.hwpx` | `python-hwpx` (Pure Python) | `{{key}}` 치환 | ✅ | ✅ | ✅ | ✅ | ✅ (v0.3+) |
+| `.hwpx` | 자체 `hwpx_core` (lxml + zipfile) | `{{key}}` 치환 | ✅ | ✅ | ✅ | ✅ | ✅ |
 
 - HWPX는 한컴오피스 설치가 **불필요**합니다 (macOS/Linux 서버에서 그대로 동작).
 - 구버전 `.hwp`(바이너리 포맷)는 지원하지 않습니다 — `.hwpx`로 변환 후 사용하세요.
 - 병합 셀: 3개 포맷 모두 preview에 `null` 슬롯 + `merges` 메타로 구조 노출. non-anchor 좌표에 쓰기는 `MergedCellWriteError`로 거부.
 
+## 라이선스 (상용 사용 가능)
+
+- 본 프로젝트: **MIT License**
+- 런타임 의존성(`python-docx`, `docxtpl`, `python-pptx`, `lxml`, `mcp`): 전부 **허용형 OSS** (MIT/BSD/Apache-2.0/LGPL-2.1). 상용·내부 서비스에 그대로 포함 가능.
+- v0.3 이하에서 사용했던 `python-hwpx` (Non-Commercial License) 는 v0.4.0부터 **dev 환경(테스트 fixture 생성) 전용**으로 이동. HWPX 편집은 자체 `hwpx_core` 모듈이 수행합니다.
+
 ## 설치
 
 ```bash

{document_adapter-0.3.0 → document_adapter-0.4.0}/README.md

@@ -18,12 +18,18 @@
 |---|---|---|---|---|---|---|---|
 | `.docx` | `docxtpl` + `python-docx` | Jinja2 (`{%tr%}` loop 포함) | ✅ | ✅ | ✅ | ✅ | ✅ |
 | `.pptx` | `python-pptx` | `{{key}}` 치환 | ✅ (슬라이드 위치 포함) | ✅ | — (포맷 미지원) | ✅ | ❌ (미지원) |
-| `.hwpx` | `python-hwpx` (Pure Python) | `{{key}}` 치환 | ✅ | ✅ | ✅ | ✅ | ✅ (v0.3+) |
+| `.hwpx` | 자체 `hwpx_core` (lxml + zipfile) | `{{key}}` 치환 | ✅ | ✅ | ✅ | ✅ | ✅ |
 
 - HWPX는 한컴오피스 설치가 **불필요**합니다 (macOS/Linux 서버에서 그대로 동작).
 - 구버전 `.hwp`(바이너리 포맷)는 지원하지 않습니다 — `.hwpx`로 변환 후 사용하세요.
 - 병합 셀: 3개 포맷 모두 preview에 `null` 슬롯 + `merges` 메타로 구조 노출. non-anchor 좌표에 쓰기는 `MergedCellWriteError`로 거부.
 
+## 라이선스 (상용 사용 가능)
+
+- 본 프로젝트: **MIT License**
+- 런타임 의존성(`python-docx`, `docxtpl`, `python-pptx`, `lxml`, `mcp`): 전부 **허용형 OSS** (MIT/BSD/Apache-2.0/LGPL-2.1). 상용·내부 서비스에 그대로 포함 가능.
+- v0.3 이하에서 사용했던 `python-hwpx` (Non-Commercial License) 는 v0.4.0부터 **dev 환경(테스트 fixture 생성) 전용**으로 이동. HWPX 편집은 자체 `hwpx_core` 모듈이 수행합니다.
+
 ## 설치
 
 ```bash

document_adapter-0.4.0/document_adapter/hwpx_adapter.py

@@ -0,0 +1,348 @@
+"""HWPX 어댑터: document_adapter.hwpx_core 기반 (python-hwpx 의존 없음).
+
+- 패키지 로드/저장은 HwpxPackage가 처리 (bytes-copy 보존, 수정 XML만 재직렬화)
+- 표 순회는 iter_grid 직접 사용 (cellAddr + cellSpan → logical grid)
+- run-level 포맷은 paragraph 헬퍼가 첫 <hp:t>만 갈아끼워 유지
+"""
+from __future__ import annotations
+
+import re
+import warnings
+from copy import deepcopy
+from pathlib import Path
+from typing import Any, Iterator
+
+from lxml import etree
+
+from document_adapter.hwpx_core import (
+    HP_CELL_ADDR,
+    HP_P,
+    HP_RUN,
+    HP_SUBLIST,
+    HP_T,
+    HP_TBL,
+    HP_TC,
+    HP_TR,
+    HwpxPackage,
+    cell_paragraph_texts,
+    cell_paragraphs,
+    cell_text,
+    iter_grid,
+    nested_tables,
+    paragraph_text,
+    set_paragraph_text,
+    table_shape,
+    write_cell,
+)
+
+from .base import (
+    CellContent,
+    CellOutOfBoundsError,
+    DocumentAdapter,
+    MergeInfo,
+    MergedCellWriteError,
+    NotImplementedForFormat,
+    TableIndexError,
+    TableSchema,
+)
+
+TAG_PATTERN = re.compile(r"\{\{\s*(\w+)\s*\}\}")
+
+
+class HwpxAdapter(DocumentAdapter):
+    format = "hwpx"
+
+    def _open(self) -> None:
+        self._pkg = HwpxPackage.open(self.path)
+
+    def save(self, path: Path | str | None = None) -> Path:
+        target = Path(path) if path else self.path
+        self._pkg.save(target)
+        self.path = target
+        return target
+
+    def close(self) -> None:
+        self._pkg.close()
+
+    # ---- 테이블 순회 ----
+
+    def _iter_tables(
+        self,
+    ) -> Iterator[tuple[int, etree._Element, str, str]]:
+        """(flat_index, tbl_element, parent_path, section_part_name) 순회.
+
+        최상위 테이블과 그 안의 중첩 테이블을 DFS 순서로 부여.
+        """
+        idx_counter = [0]
+
+        def walk(tbl: etree._Element, parent_path: str, section_name: str):
+            current_idx = idx_counter[0]
+            idx_counter[0] += 1
+            yield current_idx, tbl, parent_path, section_name
+            seen_anchors: set[tuple[int, int]] = set()
+            for entry in iter_grid(tbl):
+                if not entry.is_anchor or entry.anchor in seen_anchors:
+                    continue
+                seen_anchors.add(entry.anchor)
+                for child_tbl in nested_tables(entry.cell_element):
+                    child_parent = (
+                        f"{parent_path}.tables[{current_idx}].cell"
+                        f"({entry.anchor[0]},{entry.anchor[1]})"
+                    )
+                    yield from walk(child_tbl, child_parent, section_name)
+
+        for section_name, root in self._pkg.iter_section_roots():
+            # 최상위 <hp:tbl> 찾기: root > hp:p > hp:run > hp:tbl
+            for p in root.findall(HP_P):
+                for run in p.findall(HP_RUN):
+                    for tbl in run.findall(HP_TBL):
+                        yield from walk(tbl, "", section_name)
+
+    def _get_table(self, table_index: int) -> tuple[etree._Element, str]:
+        """flat_index로 (tbl_element, section_part_name) 반환."""
+        for idx, tbl, _, section_name in self._iter_tables():
+            if idx == table_index:
+                return tbl, section_name
+        raise TableIndexError(f"HWPX table index {table_index} not found")
+
+    def _find_grid_entry(self, tbl: etree._Element, row: int, col: int):
+        rows, cols = table_shape(tbl)
+        if row < 0 or col < 0 or row >= rows or col >= cols:
+            raise CellOutOfBoundsError(
+                f"cell ({row},{col}) out of bounds ({rows}x{cols})"
+            )
+        for entry in iter_grid(tbl):
+            if (entry.row, entry.column) == (row, col):
+                return entry
+        raise CellOutOfBoundsError(
+            f"cell ({row},{col}) does not resolve to any physical cell"
+        )
+
+    def _resolve_anchor_cell(
+        self,
+        tbl: etree._Element,
+        row: int,
+        col: int,
+        *,
+        allow_merge_redirect: bool,
+    ):
+        entry = self._find_grid_entry(tbl, row, col)
+        if not entry.is_anchor:
+            anchor_r, anchor_c = entry.anchor
+            if not allow_merge_redirect:
+                raise MergedCellWriteError(
+                    f"cell ({row},{col}) is part of a merged region anchored at "
+                    f"({anchor_r},{anchor_c}) span={entry.span}. "
+                    f"Write to the anchor coordinate, or pass "
+                    f"allow_merge_redirect=True."
+                )
+            warnings.warn(
+                f"write to ({row},{col}) redirected to merge anchor "
+                f"({anchor_r},{anchor_c})",
+                stacklevel=3,
+            )
+        return entry
+
+    # ---- 검사 ----
+
+    def get_placeholders(self) -> list[str]:
+        text = self._pkg.export_text()
+        return sorted(set(TAG_PATTERN.findall(text)))
+
+    def get_tables(
+        self,
+        min_rows: int = 1,
+        min_cols: int = 1,
+        preview_rows: int = 4,
+        max_cell_len: int = 40,
+    ) -> list[TableSchema]:
+        schemas: list[TableSchema] = []
+        for idx, tbl, parent_path, _ in self._iter_tables():
+            rows, cols = table_shape(tbl)
+            if rows < min_rows or cols < min_cols:
+                continue
+
+            visible_rows = min(rows, preview_rows)
+            preview: list[list[str | None]] = [
+                [None for _ in range(cols)] for _ in range(visible_rows)
+            ]
+            merges: list[MergeInfo] = []
+            seen_anchors: set[tuple[int, int]] = set()
+
+            for entry in iter_grid(tbl):
+                if entry.anchor in seen_anchors:
+                    continue
+                if entry.is_anchor:
+                    seen_anchors.add(entry.anchor)
+                    if entry.row < visible_rows:
+                        text = cell_text(entry.cell_element).strip()
+                        preview[entry.row][entry.column] = text[:max_cell_len]
+                    if entry.span != (1, 1):
+                        merges.append(MergeInfo(anchor=entry.anchor, span=entry.span))
+
+            schemas.append(
+                TableSchema(
+                    index=idx,
+                    rows=rows,
+                    cols=cols,
+                    preview=preview,
+                    merges=merges,
+                    parent_path=parent_path or None,
+                )
+            )
+        return schemas
+
+    def get_cell(self, table_index: int, row: int, col: int) -> CellContent:
+        tbl, _ = self._get_table(table_index)
+        entry = self._find_grid_entry(tbl, row, col)
+
+        tc = entry.cell_element
+        text = cell_text(tc)
+        paragraphs = cell_paragraph_texts(tc)
+
+        nested_indices: list[int] = []
+        if entry.is_anchor:
+            child_tbls = nested_tables(tc)
+            if child_tbls:
+                nested_ids = {id(t) for t in child_tbls}
+                for child_idx, child_tbl, _, _ in self._iter_tables():
+                    if id(child_tbl) in nested_ids:
+                        nested_indices.append(child_idx)
+
+        return CellContent(
+            row=row,
+            col=col,
+            text=text,
+            paragraphs=paragraphs,
+            is_anchor=entry.is_anchor,
+            anchor=entry.anchor,
+            span=entry.span,
+            nested_table_indices=nested_indices,
+        )
+
+    # ---- 편집 ----
+
+    def render_template(self, context: dict[str, Any]) -> None:
+        """섹션의 모든 <hp:p> 에서 {{key}} 치환. paragraph 단위로 처리해
+        run 포맷은 보존한다 (첫 <hp:t>에 치환 결과를 쓰고 나머지는 비움).
+        """
+        def substitute(p: etree._Element) -> bool:
+            text = paragraph_text(p)
+            if not TAG_PATTERN.search(text):
+                return False
+            new_text = TAG_PATTERN.sub(
+                lambda m: str(context.get(m.group(1), m.group(0))), text
+            )
+            set_paragraph_text(p, new_text)
+            return True
+
+        for section_name, root in self._pkg.iter_section_roots():
+            changed = False
+            for p in root.iter(HP_P):
+                if substitute(p):
+                    changed = True
+            if changed:
+                self._pkg.mark_dirty(section_name)
+
+    def set_cell(
+        self,
+        table_index: int,
+        row: int,
+        col: int,
+        value: str,
+        *,
+        allow_merge_redirect: bool = False,
+    ) -> str:
+        tbl, section_name = self._get_table(table_index)
+        entry = self._resolve_anchor_cell(
+            tbl, row, col, allow_merge_redirect=allow_merge_redirect
+        )
+        tc = entry.cell_element
+        old = cell_text(tc).strip()
+        write_cell(tc, value)
+        self._pkg.mark_dirty(section_name)
+        return old
+
+    def append_to_cell(
+        self,
+        table_index: int,
+        row: int,
+        col: int,
+        value: str,
+        separator: str = "  ",
+        *,
+        allow_merge_redirect: bool = False,
+    ) -> str:
+        tbl, section_name = self._get_table(table_index)
+        entry = self._resolve_anchor_cell(
+            tbl, row, col, allow_merge_redirect=allow_merge_redirect
+        )
+        tc = entry.cell_element
+        old = cell_text(tc).strip()
+        new_value = f"{old}{separator}{value}" if old else value
+        write_cell(tc, new_value)
+        self._pkg.mark_dirty(section_name)
+        return old
+
+    def append_row(self, table_index: int, values: list[str]) -> None:
+        """표 끝에 새 행 추가: 마지막 <hp:tr> deepcopy → 각 셀 비우고
+        cellAddr.rowAddr를 새 인덱스로 갱신. 제약은 기존과 동일:
+          - 마지막 행이 rowSpan에 걸리면 NotImplementedForFormat
+        """
+        tbl, section_name = self._get_table(table_index)
+        rows_before, _ = table_shape(tbl)
+
+        trs = tbl.findall(HP_TR)
+        if not trs:
+            raise NotImplementedForFormat("cannot append row to empty HWPX table")
+
+        last_row = trs[-1]
+        for tc in last_row.findall(HP_TC):
+            from document_adapter.hwpx_core.constants import HP_CELL_SPAN
+
+            span = tc.find(HP_CELL_SPAN)
+            addr = tc.find(HP_CELL_ADDR)
+            if span is not None and addr is not None:
+                try:
+                    row_span = int(span.get("rowSpan", "1"))
+                    row_addr = int(addr.get("rowAddr", "0"))
+                except (TypeError, ValueError):
+                    continue
+                if row_addr + row_span - 1 != rows_before - 1:
+                    raise NotImplementedForFormat(
+                        "last row participates in a cross-row merge; "
+                        "append_row is not safe for this table."
+                    )
+
+        new_row_idx = rows_before
+        new_row = deepcopy(last_row)
+        for tc in new_row.findall(HP_TC):
+            addr = tc.find(HP_CELL_ADDR)
+            if addr is not None:
+                addr.set("rowAddr", str(new_row_idx))
+            # 기존 텍스트만 비우고 run/paragraph 구조는 유지
+            sublist = tc.find(HP_SUBLIST)
+            if sublist is not None:
+                for p in sublist.findall(HP_P):
+                    for run in p.findall(HP_RUN):
+                        for t in run.findall(HP_T):
+                            t.text = ""
+
+        tbl.append(new_row)
+
+        # rowCnt 속성 갱신 (있을 때만)
+        row_cnt_attr = tbl.get("rowCnt")
+        if row_cnt_attr and row_cnt_attr.isdigit():
+            tbl.set("rowCnt", str(int(row_cnt_attr) + 1))
+
+        self._pkg.mark_dirty(section_name)
+
+        # 값 채우기 (병합된 non-anchor 위치는 스킵)
+        for i, value in enumerate(values):
+            _, cols = table_shape(tbl)
+            if i >= cols:
+                break
+            try:
+                self.set_cell(table_index, new_row_idx, i, value)
+            except MergedCellWriteError:
+                continue

document_adapter-0.4.0/document_adapter/hwpx_core/__init__.py

@@ -0,0 +1,67 @@
+"""HWPX 저수준 패키지 — python-hwpx 의존 없이 zipfile+lxml로 HWPX 문서 편집.
+
+이 패키지는 표 편집에 필요한 최소 기능만 제공한다:
+- ZIP 컨테이너 입출력 (수정 안 한 파일은 bytes 그대로 보존)
+- XML 트리의 lazy 파싱과 dirty 추적
+- 병합 셀 인식된 logical grid 순회
+
+구조:
+- constants: HWPX XML 네임스페이스
+- package.HwpxPackage: python-hwpx의 HwpxDocument 대체
+- grid.iter_grid: python-hwpx의 Table.iter_grid() 대체
+"""
+from document_adapter.hwpx_core.constants import (
+    HC_NS,
+    HH_NS,
+    HP_NS,
+    HS_NS,
+    OPF_NS,
+    HP_CELL_ADDR,
+    HP_CELL_SPAN,
+    HP_P,
+    HP_RUN,
+    HP_SUBLIST,
+    HP_T,
+    HP_TBL,
+    HP_TC,
+    HP_TR,
+)
+from document_adapter.hwpx_core.grid import GridEntry, iter_grid, table_shape
+from document_adapter.hwpx_core.package import HwpxPackage
+from document_adapter.hwpx_core.paragraph import (
+    cell_paragraph_texts,
+    cell_paragraphs,
+    cell_text,
+    nested_tables,
+    paragraph_text,
+    set_paragraph_text,
+    write_cell,
+)
+
+__all__ = [
+    "HC_NS",
+    "HH_NS",
+    "HP_NS",
+    "HS_NS",
+    "OPF_NS",
+    "HP_CELL_ADDR",
+    "HP_CELL_SPAN",
+    "HP_P",
+    "HP_RUN",
+    "HP_SUBLIST",
+    "HP_T",
+    "HP_TBL",
+    "HP_TC",
+    "HP_TR",
+    "GridEntry",
+    "HwpxPackage",
+    "iter_grid",
+    "table_shape",
+    "cell_paragraph_texts",
+    "cell_paragraphs",
+    "cell_text",
+    "nested_tables",
+    "paragraph_text",
+    "set_paragraph_text",
+    "write_cell",
+]

document_adapter-0.4.0/document_adapter/hwpx_core/constants.py

@@ -0,0 +1,27 @@
+"""HWPX XML 네임스페이스 상수."""
+from __future__ import annotations
+
+HP_NS = "http://www.hancom.co.kr/hwpml/2011/paragraph"
+HC_NS = "http://www.hancom.co.kr/hwpml/2011/core"
+HH_NS = "http://www.hancom.co.kr/hwpml/2011/head"
+HS_NS = "http://www.hancom.co.kr/hwpml/2011/section"
+OPF_NS = "http://www.idpf.org/2007/opf/"
+
+HP_P = f"{{{HP_NS}}}p"
+HP_RUN = f"{{{HP_NS}}}run"
+HP_T = f"{{{HP_NS}}}t"
+HP_TBL = f"{{{HP_NS}}}tbl"
+HP_TR = f"{{{HP_NS}}}tr"
+HP_TC = f"{{{HP_NS}}}tc"
+HP_CELL_ADDR = f"{{{HP_NS}}}cellAddr"
+HP_CELL_SPAN = f"{{{HP_NS}}}cellSpan"
+HP_SUBLIST = f"{{{HP_NS}}}subList"
+HS_SEC = f"{{{HS_NS}}}sec"
+
+NAMESPACES = {
+    "hp": HP_NS,
+    "hc": HC_NS,
+    "hh": HH_NS,
+    "hs": HS_NS,
+    "opf": OPF_NS,
+}

document_adapter-0.4.0/document_adapter/hwpx_core/grid.py

@@ -0,0 +1,145 @@
+"""<hp:tbl> 에서 병합 셀 인식된 logical grid를 생성.
+
+python-hwpx의 ``Table.iter_grid()``를 대체. xgen-doc2chunk의 ``_build_cell_grid``
+패턴을 차용하되, **읽기만이 아니라 쓰기도 지원**하기 위해 각 ``GridEntry``가
+anchor cell의 lxml ``<hp:tc>`` Element 자체를 노출한다.
+
+HWPX 표 구조:
+  <hp:tbl rowCnt colCnt>
+    <hp:tr>+
+      <hp:tc>+
+        <hp:cellAddr rowAddr colAddr>
+        <hp:cellSpan rowSpan colSpan>  (병합 시만 존재 또는 >1)
+        <hp:subList> → <hp:p> → <hp:run> → <hp:t>
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Iterator
+
+from lxml import etree
+
+from document_adapter.hwpx_core.constants import HP_CELL_ADDR, HP_CELL_SPAN, HP_TC, HP_TR
+
+
+@dataclass(frozen=True)
+class GridEntry:
+    """Logical grid의 한 슬롯.
+
+    - ``is_anchor=True``: 이 (row, col)이 셀의 anchor 좌표
+    - ``is_anchor=False``: 병합된 셀에 덮여 있는 non-anchor 슬롯. ``anchor``가 앵커 좌표.
+    ``cell_element``는 항상 anchor 셀의 ``<hp:tc>``.
+    """
+    row: int
+    column: int
+    is_anchor: bool
+    anchor: tuple[int, int]
+    span: tuple[int, int]  # (rowspan, colspan)
+    cell_element: etree._Element
+
+
+def _parse_cell_position(tc: etree._Element) -> tuple[int, int]:
+    addr = tc.find(HP_CELL_ADDR)
+    if addr is None:
+        return 0, 0
+    try:
+        row = int(addr.get("rowAddr", "0"))
+    except (TypeError, ValueError):
+        row = 0
+    try:
+        col = int(addr.get("colAddr", "0"))
+    except (TypeError, ValueError):
+        col = 0
+    return row, col
+
+
+def _parse_cell_span(tc: etree._Element) -> tuple[int, int]:
+    span = tc.find(HP_CELL_SPAN)
+    if span is None:
+        return 1, 1
+    try:
+        rs = int(span.get("rowSpan", "1"))
+    except (TypeError, ValueError):
+        rs = 1
+    try:
+        cs = int(span.get("colSpan", "1"))
+    except (TypeError, ValueError):
+        cs = 1
+    return max(1, rs), max(1, cs)
+
+
+def table_shape(tbl: etree._Element) -> tuple[int, int]:
+    """표의 (rows, cols). rowCnt/colCnt 속성이 없으면 앵커 좌표로 추정."""
+    rows = _safe_int(tbl.get("rowCnt"))
+    cols = _safe_int(tbl.get("colCnt"))
+    if rows > 0 and cols > 0:
+        return rows, cols
+
+    max_row = -1
+    max_col = -1
+    for tr in tbl.findall(HP_TR):
+        for tc in tr.findall(HP_TC):
+            r, c = _parse_cell_position(tc)
+            rs, cs = _parse_cell_span(tc)
+            max_row = max(max_row, r + rs - 1)
+            max_col = max(max_col, c + cs - 1)
+    return max(rows, max_row + 1), max(cols, max_col + 1)
+
+
+def _safe_int(v: str | None) -> int:
+    if v is None:
+        return 0
+    try:
+        return int(v)
+    except ValueError:
+        return 0
+
+
+def iter_grid(tbl: etree._Element) -> Iterator[GridEntry]:
+    """<hp:tbl> 요소를 병합 셀 인식해 logical grid 순서로 순회.
+
+    row-major: (0,0), (0,1), ..., (0,C-1), (1,0), ...
+    """
+    rows, cols = table_shape(tbl)
+    if rows <= 0 or cols <= 0:
+        return
+
+    # 1) anchor 좌표 → {span, cell_element}
+    anchors: dict[tuple[int, int], tuple[tuple[int, int], etree._Element]] = {}
+    for tr in tbl.findall(HP_TR):
+        for tc in tr.findall(HP_TC):
+            r, c = _parse_cell_position(tc)
+            span = _parse_cell_span(tc)
+            anchors[(r, c)] = (span, tc)
+
+    # 2) 각 (row, col)이 어느 anchor에 속하는지 역산 매핑
+    owner: dict[tuple[int, int], tuple[int, int]] = {}
+    for (ar, ac), (span, _tc) in anchors.items():
+        rs, cs = span
+        for dr in range(rs):
+            for dc in range(cs):
+                slot = (ar + dr, ac + dc)
+                # 여러 anchor가 같은 slot을 주장하면 가장 가까운(= 자기 자신) 우선
+                if slot in owner:
+                    # 이미 자기 자신으로 설정됐다면 유지
+                    continue
+                owner[slot] = (ar, ac)
+
+    # 3) row-major 순회
+    for r in range(rows):
+        for c in range(cols):
+            slot = (r, c)
+            anchor_coord = owner.get(slot)
+            if anchor_coord is None:
+                # grid에 선언되지 않은 슬롯 (손상 문서). 빈 앵커 취급.
+                continue
+            span, cell_el = anchors[anchor_coord]
+            is_anchor = (anchor_coord == slot)
+            yield GridEntry(
+                row=r,
+                column=c,
+                is_anchor=is_anchor,
+                anchor=anchor_coord,
+                span=span,
+                cell_element=cell_el,
+            )