python-hwpx 3.4.1__tar.gz → 3.6.0__tar.gz

{python_hwpx-3.4.1/src/python_hwpx.egg-info → python_hwpx-3.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 3.4.1
+Version: 3.6.0
 Summary: 한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리
 Author: python-hwpx Maintainers
 License-Expression: Apache-2.0
@@ -70,7 +70,7 @@ Dynamic: license-file
 `hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동 구성요소입니다.
 “first-party”는 프로젝트 유지보수 관계를 뜻하며, 한컴 또는 제3자의 공식 인증을 뜻하지 않습니다.
 
-현재 PyPI 공개 릴리스는 `python-hwpx 3.4.1`입니다. 일반
+현재 PyPI 공개 릴리스는 `python-hwpx 3.6.0`입니다. 일반
 `pip install python-hwpx`로 이 릴리스를 설치할 수 있습니다.
 현재 패키지 분류는 `Development Status :: 3 - Alpha`입니다. 이 분류는 API와 제품의
 성숙도를 나타내며, 공개 버전이나 플러그인의 최소 호환 버전을 대신하지 않습니다.

{python_hwpx-3.4.1 → python_hwpx-3.6.0}/README.md

@@ -25,7 +25,7 @@
 `hwpx-mcp-server`와 `hwpx-plugin`은 같은 프로젝트가 직접 유지보수하는 first-party 연동 구성요소입니다.
 “first-party”는 프로젝트 유지보수 관계를 뜻하며, 한컴 또는 제3자의 공식 인증을 뜻하지 않습니다.
 
-현재 PyPI 공개 릴리스는 `python-hwpx 3.4.1`입니다. 일반
+현재 PyPI 공개 릴리스는 `python-hwpx 3.6.0`입니다. 일반
 `pip install python-hwpx`로 이 릴리스를 설치할 수 있습니다.
 현재 패키지 분류는 `Development Status :: 3 - Alpha`입니다. 이 분류는 API와 제품의
 성숙도를 나타내며, 공개 버전이나 플러그인의 최소 호환 버전을 대신하지 않습니다.

{python_hwpx-3.4.1 → python_hwpx-3.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "python-hwpx"
-version = "3.4.1"
+version = "3.6.0"
 description = "한글 없이 HWPX 문서를 열고, 편집하고, 생성하고, 검증하는 Python 자동화 라이브러리"
 readme = { file = "README.md", content-type = "text/markdown" }
 license = "Apache-2.0"

{python_hwpx-3.4.1 → python_hwpx-3.6.0}/src/hwpx/form_fit/engine.py

@@ -17,13 +17,32 @@ from __future__ import annotations
 
 from dataclasses import dataclass, replace
 
-from .measure import SlotMetrics, estimate_text_width, measure
+from .measure import (
+    GROSS_ROW_GROWTH_FACTOR,
+    MIN_ROW_GROWTH_LINES,
+    SlotMetrics,
+    estimate_text_width,
+    measure,
+)
 from .policy import FitPolicy
 from .report import FitResult
 
 # Font ladder step (points) used when shrinking.
 _SHRINK_STEP_PT = 0.5
 
+# The vertical room could not be measured (merged cell, no height, or an auto-grow
+# floor); the fit is width-only and the oracle must confirm the vertical fit.
+_HEIGHT_UNAVAILABLE_NOTE = (
+    "cell height is not a usable budget (merged/auto-grow); fit is width-only — "
+    "render oracle should confirm the vertical fit"
+)
+# The content needs more vertical room than the authored cell height, but not
+# grossly — the row will grow modestly. Reported (never silent), deferred to oracle.
+_ROW_GROWTH_NOTE = (
+    "value needs more lines than the cell height budgets; the row will grow — "
+    "render oracle should confirm no page shift"
+)
+
 
 @dataclass(slots=True)
 class FitEngine:
@@ -36,6 +55,26 @@ class FitEngine:
         policy: FitPolicy | None = None,
         *,
         field_id: str | None = None,
+    ) -> FitResult:
+        result = self._fit_decide(value, slot, policy, field_id=field_id)
+        inline_count = int(getattr(slot, "inline_object_count", 0) or 0)
+        if inline_count and (value or "") != "":
+            inline_width = float(getattr(slot, "inline_object_width", 0.0) or 0.0)
+            result.warnings.append(
+                f"cell line shared with {inline_count} inline control(s) "
+                f"({inline_width:.0f} HWPUNIT deducted from the width budget); "
+                "control-sharing cells are unusual fill targets — verify with a "
+                "render gate or pick the intended value cell"
+            )
+        return result
+
+    def _fit_decide(
+        self,
+        value: str,
+        slot: SlotMetrics,
+        policy: FitPolicy | None = None,
+        *,
+        field_id: str | None = None,
     ) -> FitResult:
         policy = policy or FitPolicy()
         value = "" if value is None else str(value)
@@ -58,12 +97,35 @@ class FitEngine:
         if policy.mode == "expand_row":
             return self._expand_row(value, slot, policy, field_id)
 
+        # Inline objects can consume the whole line; with less than a glyph of
+        # width left there is nothing to reshape into — refuse with a message
+        # that names the cause instead of an absurd wrapped-line estimate.
+        if (
+            int(getattr(slot, "inline_object_count", 0) or 0)
+            and slot.available_width < slot.font_pt * 100.0 * 0.6
+        ):
+            return FitResult(
+                ok=False,
+                value=value,
+                applied_value=value,
+                lines=0,
+                font_pt=slot.font_pt,
+                overflow_detected=True,
+                confidence="high",
+                errors=[
+                    "FIELD_OVERFLOW: inline control(s) leave no usable width in "
+                    "this cell; choose the intended value cell or allow row "
+                    "expansion"
+                ],
+                field_id=field_id,
+            )
+
         # Reshaping ladder: wrap, shrink, or wrap_then_shrink, then fail_on_overflow.
         wrap_lines = policy.effective_max_lines if policy.may_wrap else 1
         wrap_slot = replace(slot, max_lines=wrap_lines)
         measurement = measure(value, wrap_slot)
         if measurement.fits:
-            return FitResult(
+            result = FitResult(
                 ok=True,
                 value=value,
                 applied_value=value,
@@ -78,11 +140,15 @@ class FitEngine:
                 warnings=list(measurement.notes),
                 field_id=field_id,
             )
+            return self._apply_height_budget(result, value, slot, policy, wrap_lines, field_id)
 
         if policy.may_shrink:
             shrunk = self._try_shrink(value, slot, policy, wrap_lines)
             if shrunk is not None:
-                return replace(shrunk, field_id=field_id)
+                shrunk = replace(shrunk, field_id=field_id)
+                return self._apply_height_budget(
+                    shrunk, value, slot, policy, wrap_lines, field_id
+                )
 
         # Still overflowing → terminal overflow action (confidence-gated).
         return self._overflow(value, wrap_slot, policy, field_id, measurement)
@@ -212,6 +278,205 @@ class FitEngine:
             candidate = round(candidate - _SHRINK_STEP_PT, 4)
         return best
 
+    # -- vertical (row-height) budget ------------------------------------- #
+    def _apply_height_budget(
+        self,
+        result: FitResult,
+        value: str,
+        slot: SlotMetrics,
+        policy: FitPolicy,
+        wrap_lines: int,
+        field_id: str | None,
+    ) -> FitResult:
+        """Overlay the authored row-height budget on a width-fitting *result*.
+
+        The width ladder decides horizontal fit; this decides whether the value
+        also sits inside the cell's *vertical* room, so a filled row does not
+        silently grow and shift the page (the dominant M9 form-fill defect).
+
+        Honesty contract (mirrors the width path, grounded in the S-085 P0/P1
+        measurement): the authored ``cellSz.height`` is an unreliable proxy in wild
+        forms (auto-grow, tiny floors, merges), so a *modest* vertical overflow is
+        reported and deferred to the render oracle; only a *gross* balloon shrinks
+        or fails closed. ``allow_row_expand`` / ``expand_row`` opt out entirely.
+        """
+
+        if slot.available_height is None:
+            if slot.height_unavailable and result.ok:
+                result.warnings.append(_HEIGHT_UNAVAILABLE_NOTE)
+            return result
+        if policy.allow_row_expand or policy.mode == "expand_row":
+            return result
+
+        font = result.font_pt if result.font_pt is not None else slot.font_pt
+        wrapped = result.lines if result.lines is not None else 1
+        verdict = self._height_verdict(slot, wrapped, font)
+        if verdict == "fits":
+            return result
+        if verdict == "modest":
+            # S-085 P1 calibration round 2 (differential-measured): the modest
+            # band is where pages actually shift, so try to shrink INTO the
+            # budget first; only defer to the oracle when no font >= min can
+            # land the value fully inside the authored height.
+            if policy.may_shrink:
+                shrunk = self._try_shrink_for_height(
+                    value, slot, policy, wrap_lines, field_id, accept_modest=False
+                )
+                if shrunk is not None:
+                    return shrunk
+            result.overflow_detected = True
+            result.warnings.append(_ROW_GROWTH_NOTE)
+            return result
+
+        # Gross vertical balloon: shrink (prefer a full fit, else the least
+        # growth), else fail-closed.
+        if policy.may_shrink:
+            shrunk = self._try_shrink_for_height(
+                value, slot, policy, wrap_lines, field_id, accept_modest=True
+            )
+            if shrunk is not None:
+                return shrunk
+        return self._overflow_height(value, slot, policy, field_id, wrapped, font)
+
+    def _height_verdict(self, slot: SlotMetrics, wrapped_lines: int, font_pt: float) -> str:
+        """Classify vertical fit as ``fits`` / ``modest`` / ``gross``."""
+
+        budget = slot.height_lines(font_pt)
+        if budget is None or wrapped_lines <= budget:
+            return "fits"
+        optimistic = slot.height_lines_optimistic(font_pt) or budget
+        if (
+            wrapped_lines > optimistic * GROSS_ROW_GROWTH_FACTOR
+            and (wrapped_lines - optimistic) >= MIN_ROW_GROWTH_LINES
+        ):
+            return "gross"
+        return "modest"
+
+    def _try_shrink_for_height(
+        self,
+        value: str,
+        slot: SlotMetrics,
+        policy: FitPolicy,
+        wrap_lines: int,
+        field_id: str | None,
+        *,
+        accept_modest: bool,
+    ) -> FitResult | None:
+        """Largest font (>= min) that lands the value INSIDE the height budget.
+
+        Walks the shrink ladder preferring a full vertical fit ("fits"). When
+        ``accept_modest`` is true and no font achieves a full fit, the largest
+        candidate whose growth is merely *modest* (never gross) is returned as
+        the least-damage fallback, reported and deferred to the oracle.
+        """
+
+        ceiling = policy.max_font_pt or slot.font_pt
+        candidate = min(slot.font_pt, ceiling)
+        modest_candidate: tuple[float, int] | None = None
+        while candidate >= policy.min_font_pt - 1e-9:
+            trial = replace(slot, font_pt=candidate, max_lines=wrap_lines)
+            m = measure(value, trial)
+            if m.fits and m.confidence == "high":
+                verdict = self._height_verdict(slot, m.lines, candidate)
+                if verdict == "fits":
+                    return self._shrunk_result(
+                        value, slot, candidate, m.lines, wrap_lines, field_id,
+                        modest=False,
+                    )
+                if verdict == "modest" and modest_candidate is None:
+                    modest_candidate = (candidate, m.lines)
+            candidate = round(candidate - _SHRINK_STEP_PT, 4)
+        if accept_modest and modest_candidate is not None:
+            font_pt, lines = modest_candidate
+            return self._shrunk_result(
+                value, slot, font_pt, lines, wrap_lines, field_id, modest=True
+            )
+        return None
+
+    def _shrunk_result(
+        self,
+        value: str,
+        slot: SlotMetrics,
+        candidate: float,
+        lines: int,
+        wrap_lines: int,
+        field_id: str | None,
+        *,
+        modest: bool,
+    ) -> FitResult:
+        changes: dict[str, object] = {}
+        warnings: list[str] = []
+        if candidate != slot.font_pt:
+            changes = {
+                "font_pt": round(candidate, 2),
+                "from_font_pt": round(slot.font_pt, 2),
+            }
+            warnings.append(
+                f"font shrunk {slot.font_pt:g}pt → {candidate:g}pt to fit the row height"
+            )
+        if wrap_lines > 1 and lines > 1:
+            changes["wrapped_lines"] = lines
+        if modest:
+            warnings.append(_ROW_GROWTH_NOTE)
+        return FitResult(
+            ok=True,
+            value=value,
+            applied_value=value,
+            applied_style_changes=changes,
+            lines=lines,
+            font_pt=round(candidate, 2),
+            confidence="high",
+            overflow_detected=modest,
+            warnings=warnings,
+            field_id=field_id,
+        )
+
+    def _overflow_height(
+        self,
+        value: str,
+        slot: SlotMetrics,
+        policy: FitPolicy,
+        field_id: str | None,
+        wrapped_lines: int,
+        font_pt: float,
+    ) -> FitResult:
+        """Terminal action for a gross vertical balloon that shrink cannot resolve."""
+
+        budget = slot.height_lines(font_pt)
+        action = policy.overflow
+        # Line-level truncation is not modelled; keep the value and warn (honest).
+        if action == "truncate":
+            action = "warn"
+        if action == "warn":
+            return FitResult(
+                ok=True,
+                value=value,
+                applied_value=value,
+                lines=wrapped_lines,
+                font_pt=font_pt,
+                overflow_detected=True,
+                confidence="high",
+                warnings=[
+                    f"value needs ~{wrapped_lines} lines but the row height holds "
+                    f"~{budget}; the row will balloon (overflow=warn)"
+                ],
+                field_id=field_id,
+            )
+        return FitResult(
+            ok=False,
+            value=value,
+            applied_value=value,
+            lines=wrapped_lines,
+            font_pt=font_pt,
+            overflow_detected=True,
+            confidence="high",
+            errors=[
+                f"FIELD_OVERFLOW: value needs ~{wrapped_lines} lines but the row height "
+                f"holds ~{budget}; shrink/shorten the value or allow row expansion"
+            ],
+            field_id=field_id,
+        )
+
     # -- terminal overflow action ----------------------------------------- #
     def _overflow(
         self,

{python_hwpx-3.4.1 → python_hwpx-3.6.0}/src/hwpx/form_fit/measure.py

@@ -53,6 +53,31 @@ _CLASS_UNCERTAINTY: dict[str, float] = {
 # multiplicative factor so it scales and also buys headroom on the advance error.
 DEFAULT_SAFETY = 0.93
 
+# --- Vertical (line-height) model ------------------------------------------- #
+# Per-line vertical advance as a multiple of the em (font height in HWPUNIT).
+# HWP's application default is 160% line spacing, so a line occupies ~1.6 em; this
+# is the advance used when a paragraph declares no explicit lineSpacing, and it
+# matches ``layout.lint._LINE_SPACING``. Used as the *expected* pitch for the
+# authored vertical budget (the point at which the row is warned it will grow).
+DEFAULT_LINE_SPACING_RATIO = 1.6
+
+# Tightest per-line advance Hancom is observed to use (a glyph box with no leading).
+# Measured on the M9 wild-form corpus: two soft-wrapped lines render inside cells
+# only ~2.0 em tall, so the real pitch bottoms out near 1.0 em. Used to compute the
+# *optimistic* (most generous) height budget, so a vertical overflow is only treated
+# as high confidence when content overflows even at this tightest pitch.
+MIN_LINE_SPACING_RATIO = 1.0
+
+# A vertical overflow is a *hard* balloon (shrink-or-refuse) only when content needs
+# at least this multiple of the optimistic authored line budget AND this many extra
+# lines in absolute terms. Below the gross threshold the row may grow only modestly
+# and the render oracle arbitrates. Measure-first calibration on the M9 corpus: a
+# hard cap at the optimistic budget mis-refuses 47% of known-good multi-line cells,
+# whereas this gross gate mis-refuses 2% — it fires on page-shifting balloons only.
+# (Same balloon philosophy as ``layout.lint._BALLOON_FACTOR``.)
+GROSS_ROW_GROWTH_FACTOR = 2.0
+MIN_ROW_GROWTH_LINES = 2
+
 Confidence = Literal["high", "low"]
 
 
@@ -189,11 +214,69 @@ class SlotMetrics:
     max_lines: int = 1
     raw_width: float | None = None  # cellSz.width before margins (diagnostics)
     source: str = "cell"
+    # Vertical budget. ``available_height`` is the usable inner height (HWPUNIT)
+    # after top/bottom cell margins + the safety inset. ``None`` means the vertical
+    # room was not (or could not be) measured, and the fit stays width-only.
+    available_height: float | None = None
+    # Per-line advance as a multiple of the em, from the cell's declared paragraph
+    # line spacing (PERCENT). ``None`` falls back to ``DEFAULT_LINE_SPACING_RATIO``.
+    line_spacing_ratio: float | None = None
+    # Width already consumed on the line by inline treat-as-char objects
+    # (checkboxes, form controls, pictures) that share the target paragraph.
+    # Their declared ``hp:sz/@width`` is subtracted from the usable width —
+    # ignoring them made the engine call "fits" on a fill that real Hancom
+    # wrapped, growing the row and repaginating a 10-page form (S-087 P0).
+    inline_object_width: float = 0.0
+    inline_object_count: int = 0
+    # A cell height existed but was unusable (merged row-span fragment, or an
+    # auto-grow floor shorter than one line). Records "height budget unavailable"
+    # so the fit reports width-only honestly rather than guessing a vertical fit.
+    height_unavailable: bool = False
 
     @property
     def capacity(self) -> float:
         return self.available_width * self.max_lines
 
+    def _line_ratio(self) -> float:
+        ratio = self.line_spacing_ratio
+        return ratio if ratio and ratio > 0 else DEFAULT_LINE_SPACING_RATIO
+
+    def line_height(self, font_pt: float | None = None) -> float:
+        """Expected per-line vertical advance in HWPUNIT at *font_pt*."""
+
+        pt = self.font_pt if font_pt is None else font_pt
+        return pt * 100.0 * self._line_ratio()
+
+    def height_lines(self, font_pt: float | None = None) -> int | None:
+        """Expected vertical line budget at *font_pt* (declared/default pitch).
+
+        ``None`` when the vertical room is unmeasured. Never less than 1 — a cell
+        always accommodates its first line; the risk we guard is *growth* past it.
+        """
+
+        if self.available_height is None:
+            return None
+        line_h = self.line_height(font_pt)
+        if line_h <= 0:
+            return None
+        return max(int(self.available_height // line_h), 1)
+
+    def height_lines_optimistic(self, font_pt: float | None = None) -> int | None:
+        """Most-generous vertical budget (tightest plausible pitch).
+
+        This is the basis for the *confidence* of a vertical overflow: content that
+        overflows even this budget is grossly too tall regardless of pitch error.
+        """
+
+        if self.available_height is None:
+            return None
+        pt = self.font_pt if font_pt is None else font_pt
+        ratio = min(self._line_ratio(), MIN_LINE_SPACING_RATIO)
+        line_h = pt * 100.0 * ratio
+        if line_h <= 0:
+            return None
+        return max(int(self.available_height // line_h), 1)
+
 
 @dataclass(slots=True)
 class Measurement:
@@ -291,6 +374,50 @@ def _cell_margin(cell_element: object) -> tuple[int, int]:
     return (0, 0)
 
 
+def _cell_margin_vertical(cell_element: object) -> tuple[int, int]:
+    """Return (top, bottom) cellMargin in HWPUNIT, defaulting to 0."""
+
+    for child in cell_element:  # type: ignore[attr-defined]
+        if _local_name(child.tag) == "cellMargin":
+            return (
+                int(child.get("top", "0") or 0),
+                int(child.get("bottom", "0") or 0),
+            )
+    return (0, 0)
+
+
+def _first_para_line_spacing_ratio(cell: object, document: object) -> float | None:
+    """Per-line em multiple from the cell's first paragraph line spacing (PERCENT).
+
+    Only PERCENT spacing maps cleanly onto the em-relative line-height model; FIXED
+    / ATLEAST / BETWEENLINES are left to the conservative default so we never invent
+    a font-independent pitch (the shrink ladder varies the font).
+    """
+
+    try:
+        paragraphs = cell.paragraphs  # type: ignore[attr-defined]
+    except Exception:  # pragma: no cover - defensive
+        return None
+    for paragraph in paragraphs:
+        ref = getattr(paragraph, "para_pr_id_ref", None)
+        if ref is None or document is None:
+            continue
+        try:
+            prop = document.paragraph_property(ref)  # type: ignore[attr-defined]
+        except Exception:  # pragma: no cover - defensive
+            prop = None
+        spacing = getattr(prop, "line_spacing", None) if prop is not None else None
+        if spacing is None or not getattr(spacing, "value", None):
+            continue
+        if (getattr(spacing, "spacing_type", None) or "PERCENT").upper() != "PERCENT":
+            return None
+        try:
+            return int(spacing.value) / 100.0
+        except (TypeError, ValueError):  # pragma: no cover - defensive
+            return None
+    return None
+
+
 def _first_run_font_pt(cell: object, document: object) -> float:
     """Resolve the cell's first run font size in points (default 10pt)."""
 
@@ -339,27 +466,107 @@ def resolve_slot_metrics(
     verified against Hancom's own ``lineSeg/@horzsize`` (±10 HWPUNIT on 82% of
     cells; the safety factor covers the rest plus paragraph indent, which is left
     to the HarfBuzz pass).
+
+    ``available_height`` follows the same philosophy — ``(cellSz.height - top -
+    bottom margin) * safety`` — but is recorded as *unavailable* (``None`` +
+    ``height_unavailable``) whenever the authored height is not a real ceiling:
+    a merged cell (its ``cellSz.height`` is a single-row fragment, not the spanned
+    height), a cell with no height, or an auto-grow floor shorter than one line
+    (Hancom simply grows the row past it). The fit then stays width-only rather
+    than guess a vertical fit.
     """
 
     raw_width = float(getattr(cell, "width", 0) or 0)
     element = getattr(cell, "element", None)
     left, right = _cell_margin(element) if element is not None else (0, 0)
     inner = max(raw_width - left - right, 0.0) * safety
+    inline_width, inline_count = (
+        _inline_object_width(element) if element is not None else (0.0, 0)
+    )
+    if inline_width:
+        inner = max(inner - inline_width, 0.0)
     resolved_pt = font_pt if font_pt is not None else _first_run_font_pt(cell, document)
+    line_ratio = _first_para_line_spacing_ratio(cell, document)
+
+    available_height: float | None = None
+    height_unavailable = False
+    raw_height = float(getattr(cell, "height", 0) or 0)
+    try:
+        row_span = int(getattr(cell, "span", (1, 1))[0])
+    except Exception:  # pragma: no cover - defensive
+        row_span = 1
+    top, bottom = _cell_margin_vertical(element) if element is not None else (0, 0)
+    inner_h = max(raw_height - top - bottom, 0.0) * safety if raw_height > 0 else 0.0
+    # A cell authored shorter than one line at the tightest pitch is an auto-grow
+    # floor, not a ceiling (Hancom grows the row past it); a merged row-span's
+    # cellSz.height is only one of the spanned rows. Neither is a usable budget.
+    one_line = resolved_pt * 100.0 * MIN_LINE_SPACING_RATIO
+    if row_span <= 1 and inner_h >= one_line:
+        available_height = inner_h
+    else:
+        height_unavailable = True
+
     return SlotMetrics(
         available_width=inner,
         font_pt=resolved_pt,
         max_lines=max(max_lines, 1),
         raw_width=raw_width,
         source="cell",
+        available_height=available_height,
+        line_spacing_ratio=line_ratio,
+        height_unavailable=height_unavailable,
+        inline_object_width=inline_width,
+        inline_object_count=inline_count,
     )
 
 
+def _inline_object_width(cell_element: object) -> tuple[float, int]:
+    """Total declared width of inline treat-as-char objects in the cell.
+
+    Checkboxes and similar form controls flow on the text line
+    (``hp:pos/@treatAsChar='1'``) and consume their ``hp:sz/@width``; a fill
+    value shares whatever width remains. Objects without a declared size are
+    counted but contribute 0 width (the count still signals reduced trust).
+    """
+
+    total = 0.0
+    count = 0
+    iter_fn = getattr(cell_element, "iter", None)
+    if iter_fn is None:
+        return 0.0, 0
+    for node in iter_fn():
+        tag = getattr(node, "tag", "")
+        if not isinstance(tag, str):
+            continue
+        local = tag.rsplit("}", 1)[-1].lower()
+        if local != "pos":
+            continue
+        if (node.get("treatAsChar") or "").strip() not in {"1", "true", "TRUE"}:
+            continue
+        holder = node.getparent() if hasattr(node, "getparent") else None
+        if holder is None:
+            continue
+        count += 1
+        for sibling in holder:
+            sib_local = str(getattr(sibling, "tag", "")).rsplit("}", 1)[-1].lower()
+            if sib_local == "sz":
+                try:
+                    total += float(sibling.get("width") or 0)
+                except (TypeError, ValueError):
+                    pass
+                break
+    return total, count
+
+
 __all__ = [
     "SlotMetrics",
     "Measurement",
     "Confidence",
     "DEFAULT_SAFETY",
+    "DEFAULT_LINE_SPACING_RATIO",
+    "MIN_LINE_SPACING_RATIO",
+    "GROSS_ROW_GROWTH_FACTOR",
+    "MIN_ROW_GROWTH_LINES",
     "classify_char",
     "char_advance",
     "estimate_text_width",

{python_hwpx-3.4.1 → python_hwpx-3.6.0}/src/hwpx/opc/package.py

@@ -159,10 +159,69 @@ def _local_name(element: etree._Element) -> str:
         return tag
 
 
+def _paragraph_plain_text_length(paragraph: etree._Element) -> int | None:
+    """Plain text length of a simple paragraph, or ``None`` when unjudgeable.
+
+    Mirrors the oxml-side stale detector: only paragraphs made purely of runs
+    with text/tab-like children can be judged at the byte boundary; anything
+    else (controls, tables, fields) returns ``None`` so its cache is kept.
+    """
+    total = 0
+    for child in paragraph:
+        child_name = _local_name(child).lower()
+        if child_name in _LAYOUT_CACHE_ELEMENT_NAMES:
+            continue
+        if child_name != "run":
+            return None
+        for run_child in child:
+            run_child_name = _local_name(run_child).lower()
+            if run_child_name == "t":
+                total += len("".join(run_child.itertext()))
+            elif run_child_name in {"tab", "linebreak", "hyphen", "nbspace"}:
+                total += 1
+            else:
+                return None
+    return total
+
+
+def _paragraph_layout_cache_is_stale(paragraph: etree._Element) -> bool:
+    text_length = _paragraph_plain_text_length(paragraph)
+    if text_length is None:
+        return False
+    for child in paragraph:
+        if _local_name(child).lower() not in _LAYOUT_CACHE_ELEMENT_NAMES:
+            continue
+        for line_seg in child:
+            if _local_name(line_seg).lower() != "lineseg":
+                continue
+            textpos = line_seg.get("textpos")
+            if textpos is None:
+                continue
+            try:
+                if int(textpos) > text_length:
+                    return True
+            except ValueError:
+                return True
+    return False
+
+
 def _strip_section_layout_caches(payload: bytes) -> bytes:
+    """Drop only *stale* paragraph layout caches from a section payload.
+
+    Valid caches are the authored layout of untouched paragraphs; removing
+    them forces the editor to re-lay-out entire multi-page documents, which
+    shifted page counts and stacked glyphs in the wild form-fill differential
+    (specs/031 P0 receipt). The mutating APIs upstream clear the caches of
+    exactly the paragraphs they touch, so this byte-boundary sweep only
+    guards against writers that left a provably stale cache behind.
+    """
     root = parse_xml(payload)
     removed = False
     for parent in root.iter():
+        if _local_name(parent).lower() != "p":
+            continue
+        if not _paragraph_layout_cache_is_stale(parent):
+            continue
         for child in list(parent):
             if _local_name(child).lower() in _LAYOUT_CACHE_ELEMENT_NAMES:
                 parent.remove(child)