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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 3.4.1
+Version: 3.5.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.5.0`입니다. 일반
 `pip install python-hwpx`로 이 릴리스를 설치할 수 있습니다.
 현재 패키지 분류는 `Development Status :: 3 - Alpha`입니다. 이 분류는 API와 제품의
 성숙도를 나타내며, 공개 버전이나 플러그인의 최소 호환 버전을 대신하지 않습니다.

{python_hwpx-3.4.1 → python_hwpx-3.5.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.5.0`입니다. 일반
 `pip install python-hwpx`로 이 릴리스를 설치할 수 있습니다.
 현재 패키지 분류는 `Development Status :: 3 - Alpha`입니다. 이 분류는 API와 제품의
 성숙도를 나타내며, 공개 버전이나 플러그인의 최소 호환 버전을 대신하지 않습니다.

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

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

{python_hwpx-3.4.1 → python_hwpx-3.5.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:
@@ -63,7 +82,7 @@ class FitEngine:
         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 +97,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 +235,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.5.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,62 @@ 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
+    # 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 +367,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,6 +459,14 @@ 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)
@@ -346,12 +474,35 @@ def resolve_slot_metrics(
     left, right = _cell_margin(element) if element is not None else (0, 0)
     inner = max(raw_width - left - right, 0.0) * safety
     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,
     )
 
 
@@ -360,6 +511,10 @@ __all__ = [
     "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.5.0/src/python_hwpx.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-hwpx
-Version: 3.4.1
+Version: 3.5.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.5.0`입니다. 일반
 `pip install python-hwpx`로 이 릴리스를 설치할 수 있습니다.
 현재 패키지 분류는 `Development Status :: 3 - Alpha`입니다. 이 분류는 API와 제품의
 성숙도를 나타내며, 공개 버전이나 플러그인의 최소 호환 버전을 대신하지 않습니다.

{python_hwpx-3.4.1 → python_hwpx-3.5.0}/tests/test_form_fit.py

@@ -200,6 +200,99 @@ def test_warn_policy_never_fails():
     assert result.ok is True and result.overflow_detected is True
 
 
+# --------------------------------------------------------------------------- #
+# Vertical (row-height) budget — S-085 P1.
+# --------------------------------------------------------------------------- #
+def _vslot(width=6000, font_pt=10.0, height=None, ratio=None, unavailable=False):
+    return SlotMetrics(
+        available_width=width,
+        font_pt=font_pt,
+        available_height=height,
+        line_spacing_ratio=ratio,
+        height_unavailable=unavailable,
+    )
+
+
+def test_line_height_and_budget_math():
+    slot = _vslot(height=3300)  # default 160% pitch → 1600/line; tight 1.0 → 1000/line
+    assert slot.line_height(10.0) == pytest.approx(1600.0)
+    assert slot.height_lines(10.0) == 2          # floor(3300 / 1600)
+    assert slot.height_lines_optimistic(10.0) == 3  # floor(3300 / 1000)
+
+
+def test_budget_uses_declared_percent_line_spacing():
+    slot = _vslot(height=3300, ratio=2.0)  # declared 200% → 2000/line
+    assert slot.line_height(10.0) == pytest.approx(2000.0)
+    assert slot.height_lines(10.0) == 1          # floor(3300 / 2000)
+    # Optimistic budget never uses a looser pitch than the tight floor.
+    assert slot.height_lines_optimistic(10.0) == 3  # floor(3300 / 1000)
+
+
+def test_budget_is_none_without_height_and_never_below_one():
+    assert _vslot(height=None).height_lines(10.0) is None
+    assert _vslot(height=None).height_lines_optimistic(10.0) is None
+    # A cell shorter than one line still reports a 1-line budget (guaranteed floor).
+    assert _vslot(height=500).height_lines(10.0) == 1
+
+
+def test_no_height_budget_is_width_only_with_warning_when_unavailable():
+    engine = FitEngine()
+    warned = engine.fit("홍길동", _vslot(height=None, unavailable=True), FitPolicy())
+    assert warned.ok and any("width-only" in w for w in warned.warnings)
+    # A caller that never had a height (native field) must NOT get the warning.
+    silent = engine.fit("홍길동", _vslot(height=None, unavailable=False), FitPolicy())
+    assert silent.ok and not any("width-only" in w for w in silent.warnings)
+
+
+def test_value_fits_within_ample_height_is_unchanged():
+    engine = FitEngine()
+    # 11 Hangul wrap to 2 lines in a 6000-wide slot; a 6000-tall cell budgets 3.
+    result = engine.fit("가" * 11, _vslot(height=6000), FitPolicy(mode="wrap"))
+    assert result.ok and not result.overflow_detected
+    assert not any("row will grow" in w for w in result.warnings)
+
+
+def test_modest_vertical_overflow_warns_and_defers_to_oracle():
+    engine = FitEngine()
+    # 2 lines needed, 1-line height budget → modest growth: reported, never a fail.
+    result = engine.fit("가" * 11, _vslot(height=1600), FitPolicy(mode="wrap"))
+    assert result.ok is True
+    assert result.overflow_detected is True
+    assert result.errors == []
+    assert any("row will grow" in w for w in result.warnings)
+
+
+def test_gross_vertical_balloon_fails_closed_when_cannot_shrink():
+    engine = FitEngine()
+    # 4 lines in a 1-line budget = a gross balloon; wrap mode cannot shrink → fail.
+    result = engine.fit(
+        "가" * 20, _vslot(height=1600), FitPolicy(mode="wrap", overflow="fail")
+    )
+    assert result.ok is False and result.overflow_detected
+    assert any("FIELD_OVERFLOW" in e for e in result.errors)
+
+
+def test_gross_vertical_balloon_shrinks_when_allowed():
+    engine = FitEngine()
+    before = _vslot(height=1600)
+    result = engine.fit("가" * 20, before, FitPolicy(mode="wrap_then_shrink", min_font_pt=8.0))
+    assert result.ok is True
+    assert result.font_pt is not None and result.font_pt < before.font_pt
+    assert result.applied_style_changes.get("from_font_pt") == 10.0
+
+
+def test_expand_row_bypasses_the_height_budget():
+    engine = FitEngine()
+    # A gross balloon is accepted (no fail) when row growth is opted into explicitly.
+    result = engine.fit(
+        "가" * 20,
+        _vslot(height=1600),
+        FitPolicy(mode="wrap_then_shrink", allow_row_expand=True),
+    )
+    assert result.ok is True
+    assert not any("FIELD_OVERFLOW" in e for e in result.errors)
+
+
 # --------------------------------------------------------------------------- #
 # Report adapter → the one VisualCompleteReport.
 # --------------------------------------------------------------------------- #
@@ -215,3 +308,32 @@ def test_to_form_report_folds_results():
     assert len(report.fields) == 2
     assert report.fields[0]["fieldId"] == "name"
     assert any("FIELD_OVERFLOW" in e for e in report.errors)
+
+
+def test_modest_vertical_overflow_shrinks_into_budget_when_possible():
+    # S-085 P1 round 2 (differential-measured): the modest band is where pages
+    # actually shift, so wrap_then_shrink must land INSIDE the height budget
+    # instead of warning and letting the row grow.
+    engine = FitEngine()
+    # height=2400: 2 lines exceed the 1-line budget at 10pt (modest), but a
+    # shrink to 7.5pt lands both lines fully inside the budget.
+    before = _vslot(height=2400)
+    result = engine.fit(
+        "가" * 11, before, FitPolicy(mode="wrap_then_shrink", min_font_pt=6.0)
+    )
+    assert result.ok is True
+    assert result.overflow_detected is False
+    assert not any("row will grow" in w for w in result.warnings)
+    assert result.font_pt is not None and result.font_pt < before.font_pt
+
+
+def test_modest_vertical_overflow_defers_when_shrink_cannot_reach_budget():
+    # height=1600 cannot hold two lines even at min font — the honest outcome
+    # stays the reported modest deferral, never a false shrink claim.
+    engine = FitEngine()
+    result = engine.fit(
+        "가" * 11, _vslot(height=1600), FitPolicy(mode="wrap_then_shrink", min_font_pt=6.0)
+    )
+    assert result.ok is True
+    assert result.overflow_detected is True
+    assert any("row will grow" in w for w in result.warnings)

{python_hwpx-3.4.1 → python_hwpx-3.5.0}/tests/test_form_fit_integration.py

@@ -84,6 +84,21 @@ def test_fit_records_ledger_entry_on_style_change():
     assert entry.reason in ("style_changed", "form_filled")
 
 
+def test_fit_row_height_balloon_refuses_through_real_cell():
+    # A real cell with a short authored height: a grossly too-tall value must not be
+    # accepted as a silent 100-line row growth — it fails closed (S-085 P1).
+    doc = HwpxDocument.new()
+    table = doc.add_table(1, 1)
+    cell = table.cell(0, 0)
+    cell.set_size(width=6000, height=1800)  # ~1-line-tall cell
+    result = table.set_cell_text(
+        0, 0, "서울특별시 강남구 테헤란로 " * 8,
+        fit=FitPolicy(mode="wrap_then_shrink", overflow="fail", min_font_pt=8.0),
+    )
+    assert result is not None and result.ok is False
+    assert result.overflow_detected and any("FIELD_OVERFLOW" in e for e in result.errors)
+
+
 def test_fit_borderline_overflow_downgrades_to_warn():
     # ~5 Hangul (5000) into a slot whose inner width lands just under that after
     # the 0.93 safety factor → borderline, must NOT hard-fail.