sigdetect 0.5.1__py3-none-any.whl → 0.5.3__py3-none-any.whl

sigdetect/cropping.py

@@ -7,7 +7,9 @@ import logging
 import re
 from dataclasses import dataclass
 from pathlib import Path
-from typing import Literal, overload
+from typing import Callable, Literal, overload
+
+from PIL import Image, ImageDraw
 
 from .detector.file_result_model import FileResult
 from .detector.signature_model import Signature
@@ -22,6 +24,13 @@ try:  # pragma: no cover - optional dependency
 except Exception:  # pragma: no cover - optional dependency
     Document = None  # type: ignore[assignment]
 
+try:  # pragma: no cover - optional dependency
+    import pytesseract  # type: ignore
+    from pytesseract import Output as TesseractOutput
+except Exception:  # pragma: no cover - optional dependency
+    pytesseract = None  # type: ignore[assignment]
+    TesseractOutput = None  # type: ignore[assignment]
+
 
 class SignatureCroppingUnavailable(RuntimeError):
     """Raised when PNG cropping cannot be performed (e.g., PyMuPDF missing)."""
@@ -53,6 +62,7 @@ def crop_signatures(
     return_bytes: Literal[False] = False,
     save_files: bool = True,
     docx: bool = False,
+    trim: bool = True,
 ) -> list[Path]: ...
 
 
@@ -67,6 +77,7 @@ def crop_signatures(
     return_bytes: Literal[True],
     save_files: bool = True,
     docx: bool = False,
+    trim: bool = True,
 ) -> list[SignatureCrop]: ...
 
 
@@ -80,6 +91,7 @@ def crop_signatures(
     return_bytes: bool = False,
     save_files: bool = True,
     docx: bool = False,
+    trim: bool = True,
 ) -> list[Path] | list[SignatureCrop]:
     """Render each signature bounding box to a PNG image and optionally wrap it in DOCX.
 
@@ -87,6 +99,7 @@ def crop_signatures(
     the files to ``output_dir``. Set ``save_files=False`` to skip writing PNGs to disk.
     When ``docx=True``, DOCX files are written instead of PNGs. When ``return_bytes`` is True
     and ``docx=True``, ``SignatureCrop.docx_bytes`` will contain the DOCX payload.
+    When ``trim`` is enabled, the crop is tightened around the detected ink where possible.
     """
 
     if fitz is None:  # pragma: no cover - exercised when dependency absent
@@ -110,6 +123,15 @@ def crop_signatures(
             "python-docx is required to generate DOCX outputs for signature crops."
         )
 
+    page_signature_counts: dict[int, int] = {}
+    for signature in file_result.Signatures:
+        if signature.Page:
+            page_signature_counts[signature.Page] = page_signature_counts.get(signature.Page, 0) + 1
+
+    page_signature_index: dict[int, int] = {}
+    page_cache: dict[int, dict[str, object]] = {}
+    document_cache: dict[str, object] = {}
+
     with fitz.open(pdf_path) as document:  # type: ignore[attr-defined]
         per_document_dir = output_dir / pdf_path.stem
         if save_files:
@@ -117,38 +139,201 @@ def crop_signatures(
         scale = dpi / 72.0
         matrix = fitz.Matrix(scale, scale)
 
+        page_changed = False
         for index, signature in enumerate(file_result.Signatures, start=1):
-            if not signature.BoundingBox or not signature.Page:
-                continue
-            try:
-                page = document.load_page(signature.Page - 1)
-            except Exception as exc:  # pragma: no cover - defensive
-                if logger:
-                    logger.warning(
-                        "Failed to load page for signature crop",
-                        extra={
-                            "file": pdf_path.name,
-                            "page": signature.Page,
-                            "error": str(exc),
-                        },
+            page_number = signature.Page
+            if page_number:
+                page_signature_index[page_number] = page_signature_index.get(page_number, 0) + 1
+                signature_index = page_signature_index.get(page_number, 1)
+            else:
+                signature_index = 1
+            force_fallback = _is_pseudo_signature(signature)
+            force_existing = _has_image_evidence(signature)
+            candidates: list[tuple[str, int, tuple[float, float, float, float]]] = []
+            seen: set[tuple[int, float, float, float, float]] = set()
+
+            def add_candidate(
+                source: str,
+                candidate_page: int | None,
+                candidate_bbox: tuple[float, float, float, float] | None,
+            ) -> None:
+                if candidate_page is None or not _bbox_has_area(candidate_bbox):
+                    return
+                key = (
+                    candidate_page,
+                    round(candidate_bbox[0], 2),
+                    round(candidate_bbox[1], 2),
+                    round(candidate_bbox[2], 2),
+                    round(candidate_bbox[3], 2),
+                )
+                if key in seen:
+                    return
+                seen.add(key)
+                candidates.append((source, candidate_page, candidate_bbox))
+
+            delayed_existing: tuple[int, tuple[float, float, float, float]] | None = None
+            if page_number and _bbox_has_area(signature.BoundingBox):
+                if force_fallback:
+                    delayed_existing = (page_number, signature.BoundingBox)
+                else:
+                    add_candidate("existing", page_number, signature.BoundingBox)
+
+            page = None
+            if page_number:
+                try:
+                    page = document.load_page(page_number - 1)
+                except Exception as exc:  # pragma: no cover - defensive
+                    if logger:
+                        logger.warning(
+                            "Failed to load page for signature crop",
+                            extra={
+                                "file": pdf_path.name,
+                                "page": page_number,
+                                "error": str(exc),
+                            },
+                        )
+                    page = None
+
+            if not force_existing:
+                if page is not None and page_number is not None:
+                    resolved = _resolve_signature_bbox(
+                        page,
+                        signature,
+                        page_cache=page_cache,
+                        signature_count=page_signature_counts.get(page_number, 1),
+                        signature_index=signature_index,
+                        page_number=page_number,
                     )
+                    add_candidate("resolved", page_number, resolved)
+
+                fallback_page, resolved = _resolve_bbox_across_document(
+                    document,
+                    signature,
+                    page_cache=page_cache,
+                    document_cache=document_cache,
+                    signature_index=signature_index,
+                    signature_count=page_signature_counts.get(page_number or 1, 1),
+                    skip_page=page_number,
+                )
+                add_candidate("fallback", fallback_page, resolved)
+
+                if delayed_existing is not None:
+                    add_candidate("existing", delayed_existing[0], delayed_existing[1])
+
+            if not candidates:
                 continue
 
-            clip = _to_clip_rect(page, signature.BoundingBox)
-            if clip is None:
+            best_bytes: bytes | None = None
+            best_bbox: tuple[float, float, float, float] | None = None
+            best_page: int | None = None
+            best_score: int | None = None
+
+            for source, candidate_page, candidate_bbox in candidates:
+                try:
+                    page = document.load_page(candidate_page - 1)
+                except Exception as exc:  # pragma: no cover - defensive
+                    if logger:
+                        logger.warning(
+                            "Failed to load page for signature crop",
+                            extra={
+                                "file": pdf_path.name,
+                                "page": candidate_page,
+                                "error": str(exc),
+                            },
+                        )
+                    continue
+
+                image_rects = page_cache.get(candidate_page, {}).get("image_rects")
+                if image_rects is None:
+                    image_rects = _collect_image_rects(page)
+                    page_cache.setdefault(candidate_page, {})["image_rects"] = image_rects
+
+                min_overlap = 0.6
+                min_center_overlap = 0.2
+                if signature.RenderType in {"drawn", "typed"} or _is_pseudo_signature(signature):
+                    min_overlap = 0.3
+                    min_center_overlap = 0.1
+                refined_bbox = _refine_bbox_with_image_rects(
+                    page,
+                    candidate_bbox,
+                    image_rects=image_rects,
+                    min_overlap=min_overlap,
+                    min_center_overlap=min_center_overlap,
+                )
+                skip_trim = signature.RenderType in {"drawn", "typed"} or _is_pseudo_signature(signature)
+                candidate_allow_trim = True
+                if skip_trim and refined_bbox is not None:
+                    candidate_allow_trim = False
+
+                render_bboxes: list[tuple[tuple[float, float, float, float], bool]] = [
+                    (candidate_bbox, candidate_allow_trim)
+                ]
+                if refined_bbox and refined_bbox != candidate_bbox:
+                    skip_trim = signature.RenderType in {"drawn", "typed"} or _is_pseudo_signature(signature)
+                    render_bboxes.append((refined_bbox, not skip_trim))
+                if (signature.RenderType or "").lower() == "wet":
+                    expanded_bbox = _expand_wet_bbox(page, candidate_bbox)
+                    if expanded_bbox and expanded_bbox not in {candidate_bbox, refined_bbox}:
+                        render_bboxes.append((expanded_bbox, True))
+
+                for render_bbox, allow_trim in render_bboxes:
+                    clip = _to_clip_rect(page, render_bbox)
+                    if clip is None:
+                        continue
+                    try:
+                        pixmap = page.get_pixmap(matrix=matrix, clip=clip, alpha=False)
+                        raw_bytes = pixmap.tobytes("png")
+                        final_bytes = (
+                            _trim_signature_image_bytes(
+                                raw_bytes,
+                                render_type=signature.RenderType,
+                            )
+                            if trim and allow_trim
+                            else raw_bytes
+                        )
+                    except Exception as exc:  # pragma: no cover - defensive
+                        if logger:
+                            logger.warning(
+                                "Failed to render signature crop",
+                                extra={
+                                    "file": pdf_path.name,
+                                    "page": candidate_page,
+                                    "field": signature.FieldName,
+                                    "error": str(exc),
+                                },
+                            )
+                        continue
+
+                    if _is_blank_crop(final_bytes):
+                        continue
+
+                    dark, _ = _ink_metrics(final_bytes)
+                    if best_score is None or dark > best_score:
+                        best_score = dark
+                        best_bytes = final_bytes
+                        best_bbox = render_bbox
+                        best_page = candidate_page
+
+            if best_bytes is None or best_bbox is None or best_page is None:
                 continue
 
+            if signature.Page != best_page:
+                signature.Page = best_page
+                page_changed = True
+            signature.BoundingBox = best_bbox
+
+            final_bytes = best_bytes
+
             filename = _build_filename(index, signature)
             png_destination = per_document_dir / filename
             docx_destination = png_destination.with_suffix(".docx")
 
             try:
                 image_bytes: bytes | None = None
-                pixmap = page.get_pixmap(matrix=matrix, clip=clip, alpha=False)
                 if save_files and not docx_enabled:
-                    pixmap.save(png_destination)
+                    png_destination.write_bytes(final_bytes)
                 if return_bytes or docx_enabled:
-                    image_bytes = pixmap.tobytes("png")
+                    image_bytes = final_bytes
             except Exception as exc:  # pragma: no cover - defensive
                 if logger:
                     logger.warning(
@@ -206,6 +391,9 @@ def crop_signatures(
                     )
                 )
 
+        if page_changed:
+            _update_signature_pages(file_result)
+
     return generated_crops if return_bytes else generated_paths
 
 
@@ -221,6 +409,1370 @@ def _build_docx_bytes(image_bytes: bytes) -> bytes:
     return buffer.getvalue()
 
 
+@dataclass(frozen=True)
+class _OcrBox:
+    text: str
+    confidence: float
+    left: int
+    top: int
+    right: int
+    bottom: int
+
+
+_OCR_LABEL_PATTERNS: tuple[re.Pattern[str], ...] = (
+    re.compile(r"\b(signature|signed|sign)\b", re.IGNORECASE),
+    re.compile(r"\b(date\s+signed|date)\b", re.IGNORECASE),
+    re.compile(r"\b(print(?:ed)?\s+name)\b", re.IGNORECASE),
+    re.compile(
+        r"\b(client|patient|attorney|firm|law|counsel|representative|guardian|witness)\b",
+        re.IGNORECASE,
+    ),
+    re.compile(r"\b(docusign|docu\s*sign|envelope|adobe)\b", re.IGNORECASE),
+)
+
+
+def _is_label_text(text: str) -> bool:
+    cleaned = text.strip().lower()
+    if not cleaned:
+        return False
+    return any(pattern.search(cleaned) for pattern in _OCR_LABEL_PATTERNS)
+
+
+def _extract_ocr_boxes(
+    image: Image.Image,
+    *,
+    languages: str = "eng",
+    min_confidence: float = 50.0,
+) -> list[_OcrBox]:
+    if pytesseract is None or TesseractOutput is None:
+        return []
+    try:
+        data = pytesseract.image_to_data(
+            image,
+            lang=languages,
+            config="--psm 11",
+            output_type=TesseractOutput.DICT,
+        )
+    except Exception:
+        return []
+
+    texts = data.get("text", [])
+    boxes: list[_OcrBox] = []
+    for idx, raw in enumerate(texts):
+        text = str(raw).strip()
+        if not text:
+            continue
+        try:
+            confidence = float(data["conf"][idx])
+        except (ValueError, KeyError, TypeError):
+            continue
+        if confidence < min_confidence:
+            continue
+        try:
+            left = int(data["left"][idx])
+            top = int(data["top"][idx])
+            width = int(data["width"][idx])
+            height = int(data["height"][idx])
+        except (ValueError, KeyError, TypeError):
+            continue
+        if width <= 0 or height <= 0:
+            continue
+        boxes.append(
+            _OcrBox(
+                text=text,
+                confidence=confidence,
+                left=left,
+                top=top,
+                right=left + width,
+                bottom=top + height,
+            )
+        )
+    return boxes
+
+
+def _estimate_white_level(gray: Image.Image) -> int:
+    histogram = gray.histogram()
+    total_pixels = gray.width * gray.height
+    cutoff = int(total_pixels * 0.995)
+    cumulative = 0
+    white_level = 255
+    for idx, count in enumerate(histogram):
+        cumulative += count
+        if cumulative >= cutoff:
+            white_level = idx
+            break
+    return white_level
+
+
+def _find_horizontal_rule_rows(
+    gray: Image.Image,
+    *,
+    threshold: int = 240,
+    density_ratio: float = 0.25,
+    max_thickness: int = 8,
+) -> tuple[list[tuple[int, int]], list[int]]:
+    width, height = gray.size
+    if width == 0 or height == 0:
+        return [], []
+    pixels = gray.load()
+    row_density = []
+    for y in range(height):
+        dark = sum(1 for x in range(width) if pixels[x, y] < threshold)
+        row_density.append(dark)
+    line_threshold = int(width * density_ratio)
+    segments: list[tuple[int, int]] = []
+    start: int | None = None
+    for y, dark in enumerate(row_density):
+        if dark >= line_threshold:
+            if start is None:
+                start = y
+        else:
+            if start is not None:
+                if (y - 1) - start + 1 <= max_thickness:
+                    segments.append((start, y - 1))
+                start = None
+    if start is not None and (height - 1) - start + 1 <= max_thickness:
+        segments.append((start, height - 1))
+    return segments, row_density
+
+
+def _find_vertical_rule_cols(
+    gray: Image.Image,
+    *,
+    threshold: int = 240,
+    density_ratio: float = 0.6,
+    max_thickness: int = 6,
+) -> tuple[list[tuple[int, int]], list[int]]:
+    width, height = gray.size
+    if width == 0 or height == 0:
+        return [], []
+    pixels = gray.load()
+    col_density = []
+    for x in range(width):
+        dark = sum(1 for y in range(height) if pixels[x, y] < threshold)
+        col_density.append(dark)
+    line_threshold = int(height * density_ratio)
+    segments: list[tuple[int, int]] = []
+    start: int | None = None
+    for x, dark in enumerate(col_density):
+        if dark >= line_threshold:
+            if start is None:
+                start = x
+        else:
+            if start is not None:
+                if (x - 1) - start + 1 <= max_thickness:
+                    segments.append((start, x - 1))
+                start = None
+    if start is not None and (width - 1) - start + 1 <= max_thickness:
+        segments.append((start, width - 1))
+    return segments, col_density
+
+
+def _find_ink_band(
+    gray: Image.Image,
+    *,
+    threshold: int = 240,
+    min_density_ratio: float = 0.004,
+    gap_px: int = 3,
+) -> tuple[int, int] | None:
+    width, height = gray.size
+    if width == 0 or height == 0:
+        return None
+    pixels = gray.load()
+    min_density = max(2, int(width * min_density_ratio))
+    row_density = []
+    for y in range(height):
+        dark = sum(1 for x in range(width) if pixels[x, y] < threshold)
+        row_density.append(dark)
+
+    segments: list[tuple[int, int]] = []
+    start: int | None = None
+    for y, dark in enumerate(row_density):
+        if dark >= min_density:
+            if start is None:
+                start = y
+        else:
+            if start is not None:
+                segments.append((start, y - 1))
+                start = None
+    if start is not None:
+        segments.append((start, height - 1))
+
+    if not segments:
+        return None
+
+    merged: list[list[int]] = []
+    for seg in segments:
+        if not merged:
+            merged.append([seg[0], seg[1]])
+            continue
+        if seg[0] - merged[-1][1] <= gap_px:
+            merged[-1][1] = seg[1]
+        else:
+            merged.append([seg[0], seg[1]])
+
+    best = None
+    best_score = None
+    for y0, y1 in merged:
+        score = sum(row_density[y0 : y1 + 1])
+        if best_score is None or score > best_score:
+            best_score = score
+            best = (y0, y1)
+    return best
+
+
+def _pick_line_below_band(
+    segments: list[tuple[int, int]],
+    *,
+    band_end: int,
+) -> tuple[int, int] | None:
+    if not segments:
+        return None
+    below = [seg for seg in segments if seg[0] >= band_end]
+    if below:
+        return min(below, key=lambda seg: seg[0] - band_end)
+    return None
+
+
+def _bbox_from_boxes(boxes: list[_OcrBox]) -> tuple[int, int, int, int] | None:
+    if not boxes:
+        return None
+    left = min(box.left for box in boxes)
+    top = min(box.top for box in boxes)
+    right = max(box.right for box in boxes)
+    bottom = max(box.bottom for box in boxes)
+    if right <= left or bottom <= top:
+        return None
+    return left, top, right, bottom
+
+
+def _trim_bbox_by_ocr_boxes(
+    bbox: tuple[int, int, int, int],
+    boxes: list[_OcrBox],
+    *,
+    min_gap: int = 6,
+) -> tuple[int, int, int, int]:
+    x0, y0, x1, y1 = bbox
+    if not boxes:
+        return bbox
+    candidate = None
+    for box in boxes:
+        if box.top < y0 + min_gap:
+            continue
+        if box.left > x1 or box.right < x0:
+            continue
+        if candidate is None or box.top < candidate:
+            candidate = box.top
+    if candidate is not None and candidate - 1 > y0:
+        y1 = min(y1, candidate - 1)
+    return x0, y0, x1, y1
+
+
+def _trim_border_lines(
+    image: Image.Image,
+    *,
+    threshold: int = 240,
+    density_ratio: float = 0.85,
+    edge_ratio: float = 0.2,
+) -> Image.Image:
+    gray = image.convert("L")
+    width, height = gray.size
+    if width == 0 or height == 0:
+        return image
+    pixels = gray.load()
+    row_density = [sum(1 for x in range(width) if pixels[x, y] < threshold) for y in range(height)]
+    col_density = [sum(1 for y in range(height) if pixels[x, y] < threshold) for x in range(width)]
+
+    band_x = max(1, int(width * edge_ratio))
+    band_y = max(1, int(height * edge_ratio))
+    row_threshold = int(width * density_ratio)
+    col_threshold = int(height * density_ratio)
+
+    left_cut = -1
+    for x in range(band_x):
+        if col_density[x] >= col_threshold:
+            left_cut = x
+    right_cut = width
+    for x in range(width - band_x, width):
+        if col_density[x] >= col_threshold:
+            right_cut = x
+            break
+
+    top_cut = -1
+    for y in range(band_y):
+        if row_density[y] >= row_threshold:
+            top_cut = y
+    bottom_cut = height
+    for y in range(height - band_y, height):
+        if row_density[y] >= row_threshold:
+            bottom_cut = y
+            break
+
+    x0 = max(0, left_cut + 1)
+    x1 = min(width, right_cut)
+    y0 = max(0, top_cut + 1)
+    y1 = min(height, bottom_cut)
+    if x1 - x0 <= 2 or y1 - y0 <= 2:
+        return image
+    return image.crop((x0, y0, x1, y1))
+
+
+def _select_signature_line(
+    line_segments: list[tuple[int, int]],
+    row_density: list[int],
+) -> tuple[int, int] | None:
+    if not line_segments:
+        return None
+    best = None
+    best_score = None
+    for y0, y1 in line_segments:
+        score = sum(row_density[y0 : y1 + 1])
+        if best_score is None or score > best_score:
+            best_score = score
+            best = (y0, y1)
+    return best
+
+
+def _component_bboxes(
+    gray: Image.Image,
+    *,
+    threshold: int,
+    min_pixels: int = 40,
+    line_ratio: float = 12.0,
+    edge_margin: int = 1,
+) -> list[dict[str, int]]:
+    width, height = gray.size
+    if width == 0 or height == 0:
+        return []
+    pixels = gray.load()
+    visited = [False] * (width * height)
+    bboxes: list[dict[str, int]] = []
+
+    def index(x: int, y: int) -> int:
+        return y * width + x
+
+    for y in range(height):
+        for x in range(width):
+            idx = index(x, y)
+            if visited[idx]:
+                continue
+            if pixels[x, y] >= threshold:
+                visited[idx] = True
+                continue
+
+            stack = [(x, y)]
+            visited[idx] = True
+            min_x = max_x = x
+            min_y = max_y = y
+            count = 0
+            pixels_list: list[tuple[int, int]] = []
+
+            while stack:
+                cx, cy = stack.pop()
+                count += 1
+                pixels_list.append((cx, cy))
+                if cx < min_x:
+                    min_x = cx
+                if cx > max_x:
+                    max_x = cx
+                if cy < min_y:
+                    min_y = cy
+                if cy > max_y:
+                    max_y = cy
+
+                for nx in (cx - 1, cx, cx + 1):
+                    if nx < 0 or nx >= width:
+                        continue
+                    for ny in (cy - 1, cy, cy + 1):
+                        if ny < 0 or ny >= height:
+                            continue
+                        nidx = index(nx, ny)
+                        if visited[nidx]:
+                            continue
+                        visited[nidx] = True
+                        if pixels[nx, ny] < threshold:
+                            stack.append((nx, ny))
+
+            if count < min_pixels:
+                continue
+            w = max_x - min_x + 1
+            h = max_y - min_y + 1
+            if h <= 0 or w <= 0:
+                continue
+            if w > h * line_ratio or h > w * line_ratio:
+                continue
+            edge_count = 0
+            for px, py in pixels_list:
+                if (
+                    px <= min_x + edge_margin
+                    or px >= max_x - edge_margin
+                    or py <= min_y + edge_margin
+                    or py >= max_y - edge_margin
+                ):
+                    edge_count += 1
+            edge_ratio = edge_count / max(1, count)
+            bboxes.append(
+                {
+                    "min_x": min_x,
+                    "min_y": min_y,
+                    "max_x": max_x,
+                    "max_y": max_y,
+                    "count": count,
+                    "edge_ratio": edge_ratio,
+                    "edge_sum": edge_ratio * count,
+                }
+            )
+    return bboxes
+
+
+def _merge_component_bboxes(
+    components: list[dict[str, int]],
+    *,
+    gap: int = 6,
+) -> list[dict[str, int]]:
+    merged: list[dict[str, int]] = []
+    for comp in sorted(components, key=lambda item: item["count"], reverse=True):
+        placed = False
+        for target in merged:
+            dx = max(0, max(target["min_x"] - comp["max_x"], comp["min_x"] - target["max_x"]))
+            dy = max(0, max(target["min_y"] - comp["max_y"], comp["min_y"] - target["max_y"]))
+            if dx <= gap and dy <= gap:
+                target["min_x"] = min(target["min_x"], comp["min_x"])
+                target["min_y"] = min(target["min_y"], comp["min_y"])
+                target["max_x"] = max(target["max_x"], comp["max_x"])
+                target["max_y"] = max(target["max_y"], comp["max_y"])
+                target["count"] += comp["count"]
+                target["edge_sum"] = target.get("edge_sum", 0.0) + comp.get("edge_sum", 0.0)
+                target["edge_ratio"] = target["edge_sum"] / max(1, target["count"])
+                placed = True
+                break
+        if not placed:
+            entry = comp.copy()
+            if "edge_sum" not in entry:
+                entry["edge_sum"] = entry.get("edge_ratio", 0.0) * entry["count"]
+            merged.append(entry)
+    return merged
+
+
+def _components_bbox(
+    gray: Image.Image,
+    *,
+    threshold: int,
+    min_pixels: int = 40,
+    gap: int = 6,
+    max_edge_ratio: float = 0.7,
+) -> tuple[int, int, int, int] | None:
+    components = _component_bboxes(gray, threshold=threshold, min_pixels=min_pixels)
+    if not components:
+        return None
+    clusters = _merge_component_bboxes(components, gap=gap)
+    if not clusters:
+        return None
+    filtered = [item for item in clusters if item.get("edge_ratio", 0.0) < max_edge_ratio]
+    if filtered:
+        best = max(filtered, key=lambda item: item["count"])
+    else:
+        best = max(clusters, key=lambda item: item["count"])
+    return best["min_x"], best["min_y"], best["max_x"], best["max_y"]
+
+
+def _select_line_cutoff(
+    segments: list[tuple[int, int]],
+    row_density: list[int],
+    *,
+    min_above_dark: int = 40,
+    ratio_threshold: float = 0.5,
+) -> int | None:
+    if not segments:
+        return None
+    height = len(row_density)
+    candidates: list[tuple[int, int]] = []
+    for y0, y1 in segments:
+        above_dark = sum(row_density[:y0])
+        below_dark = sum(row_density[y1 + 1 :])
+        if above_dark < min_above_dark:
+            continue
+        if below_dark > 0 and above_dark < below_dark * ratio_threshold:
+            continue
+        candidates.append((y0, y1))
+    if not candidates:
+        return None
+    y0, y1 = max(candidates, key=lambda seg: seg[1])
+    pad = max(2, int(height * 0.01))
+    return min(height - 1, y1 + pad)
+
+
+def _mask_regions(
+    gray: Image.Image,
+    *,
+    boxes: list[_OcrBox],
+    line_segments: list[tuple[int, int]],
+    vertical_segments: list[tuple[int, int]] | None = None,
+    box_filter: Callable[[_OcrBox], bool] | None = None,
+) -> Image.Image:
+    masked = gray.copy()
+    draw = ImageDraw.Draw(masked)
+    width, height = gray.size
+    for y0, y1 in line_segments:
+        draw.rectangle((0, y0, width - 1, y1), fill=255)
+    if vertical_segments:
+        for x0, x1 in vertical_segments:
+            draw.rectangle((x0, 0, x1, height - 1), fill=255)
+    for box in boxes:
+        if box_filter is not None and not box_filter(box):
+            continue
+        draw.rectangle((box.left, box.top, box.right, box.bottom), fill=255)
+    return masked
+
+
+def _whiteout_regions_rgb(
+    image: Image.Image,
+    *,
+    boxes: list[_OcrBox],
+    line_segments: list[tuple[int, int]],
+    vertical_segments: list[tuple[int, int]] | None = None,
+) -> Image.Image:
+    width, height = image.size
+    if width == 0 or height == 0:
+        return image
+    rgb = image.convert("RGB")
+    draw = ImageDraw.Draw(rgb)
+    for y0, y1 in line_segments:
+        draw.rectangle((0, y0, width - 1, y1), fill=(255, 255, 255))
+    if vertical_segments:
+        for x0, x1 in vertical_segments:
+            draw.rectangle((x0, 0, x1, height - 1), fill=(255, 255, 255))
+    for box in boxes:
+        draw.rectangle((box.left, box.top, box.right, box.bottom), fill=(255, 255, 255))
+    return rgb
+
+
+def _is_blue_pixel(r: int, g: int, b: int) -> bool:
+    return b > 100 and b > r + 25 and b > g + 25
+
+
+def _build_ink_mask(
+    image: Image.Image,
+    *,
+    threshold: int,
+    remove_blue: bool = True,
+) -> Image.Image:
+    rgb = image.convert("RGB")
+    width, height = rgb.size
+    mask = Image.new("L", (width, height), 255)
+    pix = rgb.load()
+    mpix = mask.load()
+    for y in range(height):
+        for x in range(width):
+            r, g, b = pix[x, y]
+            gray = int(0.299 * r + 0.587 * g + 0.114 * b)
+            if gray < threshold and not (remove_blue and _is_blue_pixel(r, g, b)):
+                mpix[x, y] = 0
+    return mask
+
+
+def _tighten_to_ink_components(
+    image: Image.Image,
+    *,
+    remove_blue: bool,
+    pad_px: int = 2,
+) -> Image.Image:
+    gray = image.convert("L")
+    white_level = _estimate_white_level(gray)
+    threshold = min(245, max(200, white_level - 10))
+    if remove_blue:
+        mask = _build_ink_mask(image, threshold=threshold, remove_blue=True)
+        bbox = _components_bbox(mask, threshold=200, gap=10, max_edge_ratio=0.98)
+    else:
+        bbox = _components_bbox(gray, threshold=threshold, gap=10, max_edge_ratio=0.98)
+    if bbox is None:
+        return image
+    x0, y0, x1, y1 = bbox
+    width, height = image.size
+    x0 = max(0, x0 - pad_px)
+    y0 = max(0, y0 - pad_px)
+    x1 = min(width - 1, x1 + pad_px)
+    y1 = min(height - 1, y1 + pad_px)
+    if x1 <= x0 or y1 <= y0:
+        return image
+    return image.crop((x0, y0, x1 + 1, y1 + 1))
+
+
+def _components_bbox_on_line(
+    gray: Image.Image,
+    *,
+    threshold: int,
+    min_pixels: int = 40,
+    max_edge_ratio: float = 0.98,
+) -> tuple[int, int, int, int] | None:
+    components = _component_bboxes(gray, threshold=threshold, min_pixels=min_pixels)
+    if not components:
+        return None
+    filtered = [item for item in components if item.get("edge_ratio", 0.0) < max_edge_ratio]
+    if filtered:
+        components = filtered
+
+    clusters: list[dict[str, int]] = []
+    for comp in components:
+        comp_height = comp["max_y"] - comp["min_y"] + 1
+        placed = False
+        for cluster in clusters:
+            cluster_height = cluster["max_y"] - cluster["min_y"] + 1
+            overlap = min(cluster["max_y"], comp["max_y"]) - max(cluster["min_y"], comp["min_y"]) + 1
+            if overlap >= 0:
+                min_height = max(1, min(cluster_height, comp_height))
+                if (overlap / min_height) >= 0.3:
+                    placed = True
+            else:
+                gap = max(cluster["min_y"] - comp["max_y"], comp["min_y"] - cluster["max_y"])
+                y_gap = max(4, int(min(cluster_height, comp_height) * 0.6))
+                if gap <= y_gap:
+                    placed = True
+            if placed:
+                cluster["min_x"] = min(cluster["min_x"], comp["min_x"])
+                cluster["min_y"] = min(cluster["min_y"], comp["min_y"])
+                cluster["max_x"] = max(cluster["max_x"], comp["max_x"])
+                cluster["max_y"] = max(cluster["max_y"], comp["max_y"])
+                cluster["count"] += comp["count"]
+                break
+        if not placed:
+            clusters.append(comp.copy())
+
+    if not clusters:
+        return None
+    best = max(clusters, key=lambda item: item["count"])
+    return best["min_x"], best["min_y"], best["max_x"], best["max_y"]
+
+
+def _tighten_to_ink_components_on_line(
+    image: Image.Image,
+    *,
+    remove_blue: bool,
+    pad_px: int = 2,
+) -> Image.Image:
+    gray = image.convert("L")
+    white_level = _estimate_white_level(gray)
+    threshold = min(245, max(200, white_level - 10))
+    if remove_blue:
+        mask = _build_ink_mask(image, threshold=threshold, remove_blue=True)
+        bbox = _components_bbox_on_line(mask, threshold=200, max_edge_ratio=0.98)
+    else:
+        bbox = _components_bbox_on_line(gray, threshold=threshold, max_edge_ratio=0.98)
+    if bbox is None:
+        return image
+    x0, y0, x1, y1 = bbox
+    width, height = image.size
+    x0 = max(0, x0 - pad_px)
+    y0 = max(0, y0 - pad_px)
+    x1 = min(width - 1, x1 + pad_px)
+    y1 = min(height - 1, y1 + pad_px)
+    if x1 <= x0 or y1 <= y0:
+        return image
+    return image.crop((x0, y0, x1 + 1, y1 + 1))
+
+
+def _ink_bbox(
+    gray: Image.Image,
+    *,
+    threshold: int,
+) -> tuple[int, int, int, int] | None:
+    width, height = gray.size
+    pixels = gray.load()
+    min_x, min_y = width, height
+    max_x, max_y = -1, -1
+    for y in range(height):
+        for x in range(width):
+            if pixels[x, y] < threshold:
+                if x < min_x:
+                    min_x = x
+                if x > max_x:
+                    max_x = x
+                if y < min_y:
+                    min_y = y
+                if y > max_y:
+                    max_y = y
+    if max_x < 0:
+        return None
+    return min_x, min_y, max_x, max_y
+
+
+def _ocr_trim_signature_image_bytes(
+    image_bytes: bytes,
+    *,
+    render_type: str | None,
+    pad_px: int = 3,
+) -> bytes | None:
+    if pytesseract is None or TesseractOutput is None:
+        return None
+
+    image = Image.open(io.BytesIO(image_bytes))
+    gray = image.convert("L")
+    boxes = _extract_ocr_boxes(gray)
+    if not boxes:
+        return None
+
+    line_segments, row_density = _find_horizontal_rule_rows(gray)
+    vertical_segments, _ = _find_vertical_rule_cols(gray)
+
+    def mask_all(_: _OcrBox) -> bool:
+        return True
+
+    render = (render_type or "").lower()
+    if render in {"drawn", "wet"}:
+        cleaned = _whiteout_regions_rgb(
+            image,
+            boxes=boxes,
+            line_segments=line_segments,
+            vertical_segments=vertical_segments,
+        )
+        white_level = _estimate_white_level(cleaned.convert("L"))
+        threshold = min(245, max(200, white_level - 10))
+        mask = _build_ink_mask(cleaned, threshold=threshold, remove_blue=True)
+        bbox = _components_bbox(mask, threshold=200, gap=12, max_edge_ratio=0.95)
+    else:
+        masked_strict = _mask_regions(
+            gray,
+            boxes=boxes,
+            line_segments=line_segments,
+            vertical_segments=vertical_segments,
+            box_filter=mask_all,
+        )
+
+        white_level = _estimate_white_level(masked_strict)
+        threshold = min(245, max(200, white_level - 10))
+        bbox = _components_bbox(masked_strict, threshold=threshold)
+
+    if bbox is None:
+        line_segment = _select_signature_line(line_segments, row_density)
+        max_above = max(40, int(gray.height * 0.25))
+
+        def typed_filter(box: _OcrBox) -> bool:
+            if _is_label_text(box.text):
+                return True
+            if line_segment is not None:
+                line_start = line_segment[0]
+                keep = (line_start - max_above) <= box.bottom <= (line_start + 2)
+                return not keep
+            return False
+
+        masked_typed = _mask_regions(
+            gray,
+            boxes=boxes,
+            line_segments=line_segments,
+            vertical_segments=vertical_segments,
+            box_filter=typed_filter,
+        )
+        white_level = _estimate_white_level(masked_typed)
+        threshold = min(245, max(200, white_level - 10))
+        bbox = _components_bbox(masked_typed, threshold=threshold)
+        if bbox is None:
+            filtered = [box for box in boxes if not _is_label_text(box.text)]
+            if line_segment is not None:
+                line_start = line_segment[0]
+                filtered = [
+                    box
+                    for box in filtered
+                    if (line_start - max_above) <= box.bottom <= (line_start + 2)
+                ]
+            fallback_bbox = _bbox_from_boxes(filtered)
+            if fallback_bbox is None:
+                return None
+            x0, y0, x1, y1 = fallback_bbox
+        else:
+            x0, y0, x1, y1 = bbox
+    else:
+        x0, y0, x1, y1 = bbox
+
+    if render in {"drawn", "wet"}:
+        x0, y0, x1, y1 = _trim_bbox_by_ocr_boxes((x0, y0, x1, y1), boxes)
+    width, height = gray.size
+    x0 = max(0, x0 - pad_px)
+    y0 = max(0, y0 - pad_px)
+    x1 = min(width - 1, x1 + pad_px)
+    y1 = min(height - 1, y1 + pad_px)
+
+    if render in {"drawn", "wet"}:
+        x0, y0, x1, y1 = _trim_bbox_by_ocr_boxes((x0, y0, x1, y1), boxes, min_gap=2)
+
+    if x1 <= x0 or y1 <= y0:
+        return None
+    if (x1 - x0) < max(8, int(width * 0.08)) or (y1 - y0) < max(6, int(height * 0.08)):
+        return None
+
+    cropped = image.crop((x0, y0, x1 + 1, y1 + 1))
+    if render in {"drawn", "wet"}:
+        cropped = _trim_border_lines(cropped, density_ratio=0.55, edge_ratio=0.25)
+        cropped = _tighten_to_ink_components_on_line(cropped, remove_blue=True, pad_px=1)
+    else:
+        cropped = _trim_border_lines(cropped, density_ratio=0.65, edge_ratio=0.2)
+        cropped = _tighten_to_ink_components(cropped, remove_blue=False, pad_px=1)
+    buffer = io.BytesIO()
+    cropped.save(buffer, format="PNG")
+    return buffer.getvalue()
+
+
+def _wet_ink_trim_signature_image_bytes(
+    image_bytes: bytes,
+    *,
+    pad_px: int = 4,
+) -> bytes | None:
+    if pytesseract is None or TesseractOutput is None:
+        return None
+
+    image = Image.open(io.BytesIO(image_bytes))
+    gray = image.convert("L")
+
+    boxes = _extract_ocr_boxes(gray)
+    line_segments, _ = _find_horizontal_rule_rows(gray, density_ratio=0.18, max_thickness=6)
+    vertical_segments, _ = _find_vertical_rule_cols(gray)
+    cleaned = _whiteout_regions_rgb(
+        image,
+        boxes=boxes,
+        line_segments=line_segments,
+        vertical_segments=vertical_segments,
+    )
+    white_level = _estimate_white_level(cleaned.convert("L"))
+    threshold = min(245, max(200, white_level - 10))
+    mask = _build_ink_mask(cleaned, threshold=threshold, remove_blue=True)
+    bbox = _components_bbox_on_line(mask, threshold=200, max_edge_ratio=0.98)
+    if bbox is None:
+        return None
+    x0, y0, x1, y1 = bbox
+    width, height = gray.size
+    x0 = max(0, x0 - pad_px)
+    y0 = max(0, y0 - pad_px)
+    x1 = min(width - 1, x1 + pad_px)
+    y1 = min(height - 1, y1 + pad_px)
+    if x1 <= x0 or y1 <= y0:
+        return None
+    if (x1 - x0) < max(10, int(width * 0.08)) or (y1 - y0) < max(6, int(height * 0.08)):
+        return None
+
+    cropped = image.crop((x0, y0, x1 + 1, y1 + 1))
+    cropped = _trim_border_lines(cropped, density_ratio=0.55, edge_ratio=0.25)
+    cropped = _tighten_to_ink_components_on_line(cropped, remove_blue=True, pad_px=1)
+    buffer = io.BytesIO()
+    cropped.save(buffer, format="PNG")
+    return buffer.getvalue()
+
+
+def _select_best_trim(
+    original_bytes: bytes,
+    candidates: list[bytes],
+) -> bytes:
+    original_image = Image.open(io.BytesIO(original_bytes))
+    original_area = original_image.width * original_image.height
+    min_area = max(200, int(original_area * 0.01))
+
+    best_bytes: bytes | None = None
+    best_ratio = -1.0
+    best_area = None
+    best_dark = -1
+    for candidate in candidates:
+        if _is_blank_crop(candidate):
+            continue
+        image = Image.open(io.BytesIO(candidate))
+        area = image.width * image.height
+        if area < min_area:
+            continue
+        dark, ratio = _ink_metrics(candidate)
+        if ratio > best_ratio:
+            best_ratio = ratio
+            best_area = area
+            best_dark = dark
+            best_bytes = candidate
+            continue
+        if best_area is None:
+            continue
+        if abs(ratio - best_ratio) <= 0.01:
+            if area < best_area or (area == best_area and dark > best_dark):
+                best_ratio = ratio
+                best_area = area
+                best_dark = dark
+                best_bytes = candidate
+    return best_bytes or candidates[0]
+
+
+def _select_best_trim_wet(
+    original_bytes: bytes,
+    candidates: list[bytes],
+) -> bytes:
+    original_image = Image.open(io.BytesIO(original_bytes))
+    original_area = original_image.width * original_image.height
+    min_area = max(200, int(original_area * 0.01))
+    min_ratio = 0.0006
+
+    best_bytes: bytes | None = None
+    best_area = None
+    best_ratio = None
+    for candidate in candidates:
+        if _is_blank_crop(candidate):
+            continue
+        image = Image.open(io.BytesIO(candidate))
+        area = image.width * image.height
+        if area < min_area:
+            continue
+        dark, ratio = _ink_metrics(candidate)
+        if ratio < min_ratio:
+            continue
+        if best_ratio is None or ratio > best_ratio:
+            best_ratio = ratio
+            best_area = area
+            best_bytes = candidate
+            continue
+        if best_area is None or best_ratio is None:
+            continue
+        if abs(ratio - best_ratio) <= 0.02 and area > best_area:
+            best_area = area
+            best_bytes = candidate
+    if best_bytes is not None:
+        return _pad_signature_image_bytes(best_bytes, pad_px=3)
+    return _select_best_trim(original_bytes, candidates)
+
+
+def _pad_signature_image_bytes(image_bytes: bytes, *, pad_px: int) -> bytes:
+    if pad_px <= 0:
+        return image_bytes
+    image = Image.open(io.BytesIO(image_bytes)).convert("RGB")
+    width, height = image.size
+    padded = Image.new("RGB", (width + pad_px * 2, height + pad_px * 2), (255, 255, 255))
+    padded.paste(image, (pad_px, pad_px))
+    buffer = io.BytesIO()
+    padded.save(buffer, format="PNG")
+    return buffer.getvalue()
+
+
+def _trim_signature_image_bytes(
+    image_bytes: bytes,
+    *,
+    render_type: str | None = None,
+    pad_px: int = 4,
+    gap_px: int = 4,
+    min_density_ratio: float = 0.004,
+) -> bytes:
+    candidates: list[bytes] = [image_bytes]
+    render = (render_type or "").lower()
+    if render == "wet":
+        wet_trimmed = _wet_ink_trim_signature_image_bytes(image_bytes)
+        if wet_trimmed is not None:
+            candidates.append(wet_trimmed)
+    ocr_trimmed = _ocr_trim_signature_image_bytes(image_bytes, render_type=render_type)
+    if ocr_trimmed is not None:
+        candidates.append(ocr_trimmed)
+
+    heuristic = _heuristic_trim_signature_image_bytes(
+        image_bytes,
+        pad_px=pad_px,
+        gap_px=gap_px,
+        min_density_ratio=min_density_ratio,
+    )
+    candidates.append(heuristic)
+    if render == "wet":
+        return _select_best_trim_wet(image_bytes, candidates)
+    return _select_best_trim(image_bytes, candidates)
+
+
+def _heuristic_trim_signature_image_bytes(
+    image_bytes: bytes,
+    *,
+    pad_px: int = 4,
+    gap_px: int = 4,
+    min_density_ratio: float = 0.004,
+) -> bytes:
+    image = Image.open(io.BytesIO(image_bytes))
+    gray = image.convert("L")
+    width, height = gray.size
+
+    histogram = gray.histogram()
+    total_pixels = width * height
+    cutoff = int(total_pixels * 0.995)
+    cumulative = 0
+    white_level = 255
+    for idx, count in enumerate(histogram):
+        cumulative += count
+        if cumulative >= cutoff:
+            white_level = idx
+            break
+
+    if white_level < 200:
+        return image_bytes
+
+    thresholds = [min(254, max(200, white_level - delta)) for delta in (6, 4, 2, 1, 0)]
+    min_density = max(2, int(width * min_density_ratio))
+    pixels = gray.load()
+
+    row_densities: dict[int, list[int]] = {}
+    for threshold in thresholds:
+        row_density = []
+        for y in range(height):
+            dark = sum(1 for x in range(width) if pixels[x, y] < threshold)
+            row_density.append(dark)
+        row_densities[threshold] = row_density
+
+    line_bounds = _detect_horizontal_rule_cutoff(row_densities[thresholds[-1]], width)
+    scan_limit = None
+    descender_limit = height - 1
+    if line_bounds is not None:
+        line_start, line_end = line_bounds
+        scan_limit = max(0, line_start - 1)
+        descender_limit = min(height - 1, line_end + max(2, int(height * 0.02)))
+
+    min_band_height = max(4, int(height * 0.02))
+    best = None
+    best_small = None
+    best_small_threshold = None
+    best_threshold = None
+    line_threshold = int(width * 0.6)
+    for threshold in thresholds:
+        row_density = row_densities[threshold]
+        segments: list[tuple[int, int]] = []
+        start: int | None = None
+        for y, dark in enumerate(row_density):
+            if scan_limit is not None and y > scan_limit:
+                if start is not None:
+                    segments.append((start, y - 1))
+                    start = None
+                break
+            if dark >= min_density:
+                if start is None:
+                    start = y
+            else:
+                if start is not None:
+                    segments.append((start, y - 1))
+                    start = None
+        if start is not None:
+            segments.append((start, height - 1))
+
+        if not segments:
+            continue
+
+        merged: list[list[int]] = []
+        for seg in segments:
+            if not merged:
+                merged.append([seg[0], seg[1]])
+                continue
+            if seg[0] - merged[-1][1] <= gap_px:
+                merged[-1][1] = seg[1]
+            else:
+                merged.append([seg[0], seg[1]])
+
+        candidates = []
+        for y0, y1 in merged:
+            min_x, max_x = width, -1
+            total_dark = 0
+            for y in range(y0, y1 + 1):
+                for x in range(width):
+                    if pixels[x, y] < threshold:
+                        total_dark += 1
+                        if x < min_x:
+                            min_x = x
+                        if x > max_x:
+                            max_x = x
+            if max_x < 0:
+                continue
+            band_height = y1 - y0 + 1
+            band_width = max_x - min_x + 1
+            score = total_dark * (band_height**1.3)
+            if line_bounds is not None:
+                distance = max(0, line_bounds[0] - y1)
+                proximity = 1.0 / (1.0 + (distance / 20.0))
+                score *= 1.0 + 0.5 * proximity
+            candidates.append(
+                {
+                    "y0": y0,
+                    "y1": y1,
+                    "min_x": min_x,
+                    "max_x": max_x,
+                    "total": total_dark,
+                    "height": band_height,
+                    "width": band_width,
+                    "score": score,
+                }
+            )
+
+        if not candidates:
+            continue
+
+        candidates.sort(key=lambda item: item["score"], reverse=True)
+        top_candidate = candidates[0]
+        if top_candidate["height"] >= min_band_height:
+            if best is None or top_candidate["score"] > best["score"]:
+                best = top_candidate
+                best_threshold = threshold
+        else:
+            if best_small is None or top_candidate["score"] > best_small["score"]:
+                best_small = top_candidate
+                best_small_threshold = threshold
+
+    if best is None:
+        best = best_small
+        best_threshold = best_small_threshold
+
+    if best is None:
+        return image_bytes
+
+    expansion_density = row_densities.get(best_threshold, row_densities[thresholds[-1]])
+    expand_threshold = max(1, int(min_density * 0.4))
+    y0 = best["y0"]
+    y1 = best["y1"]
+
+    while y0 > 0 and expansion_density[y0 - 1] >= expand_threshold:
+        y0 -= 1
+    while y1 < descender_limit and expansion_density[y1 + 1] >= expand_threshold:
+        y1 += 1
+
+    max_white_pad = max(8, int(height * 0.04))
+    while y0 > 0 and (best["y0"] - y0) < max_white_pad:
+        if expansion_density[y0 - 1] >= expand_threshold:
+            break
+        y0 -= 1
+
+    min_x, max_x = width, -1
+    skip_line_rows = line_bounds is not None
+    for y in range(y0, y1 + 1):
+        if skip_line_rows and expansion_density[y] >= line_threshold:
+            continue
+        for x in range(width):
+            if pixels[x, y] < thresholds[-1]:
+                if x < min_x:
+                    min_x = x
+                if x > max_x:
+                    max_x = x
+    if max_x >= 0:
+        best = {
+            "y0": y0,
+            "y1": y1,
+            "min_x": min_x,
+            "max_x": max_x,
+        }
+
+    x0 = max(0, best["min_x"] - pad_px)
+    x1 = min(width - 1, best["max_x"] + pad_px)
+    y0 = max(0, best["y0"] - pad_px)
+    y1 = min(height - 1, best["y1"] + pad_px)
+
+    if x1 <= x0 or y1 <= y0:
+        return image_bytes
+    if (x1 - x0) < max(10, int(width * 0.2)) or (y1 - y0) < max(6, int(height * 0.08)):
+        return image_bytes
+
+    cropped = image.crop((x0, y0, x1 + 1, y1 + 1))
+    cropped = _trim_below_horizontal_rule(cropped)
+    cropped = _tighten_to_ink_band(cropped)
+    buffer = io.BytesIO()
+    cropped.save(buffer, format="PNG")
+    return buffer.getvalue()
+
+
+def _trim_below_horizontal_rule(
+    image: Image.Image,
+    *,
+    threshold: int = 240,
+) -> Image.Image:
+    gray = image.convert("L")
+    width, height = gray.size
+    if width == 0 or height == 0:
+        return image
+    pixels = gray.load()
+    row_density = []
+    for y in range(height):
+        dark = sum(1 for x in range(width) if pixels[x, y] < threshold)
+        row_density.append(dark)
+
+    line_bounds = _detect_horizontal_rule_cutoff(row_density, width)
+    if line_bounds is None:
+        return image
+
+    line_start, line_end = line_bounds
+    above_dark = sum(row_density[:line_start])
+    below_dark = sum(row_density[line_end + 1 :])
+    if above_dark < 40:
+        return image
+    if below_dark <= max(40, int(above_dark * 0.2)):
+        return image
+
+    keep_below = max(2, int(height * 0.01))
+    new_bottom = min(height - 1, line_end + keep_below)
+    if new_bottom <= 0 or new_bottom >= height - 1:
+        return image
+    return image.crop((0, 0, width, new_bottom + 1))
+
+
+def _tighten_to_ink_band(
+    image: Image.Image,
+    *,
+    threshold: int = 240,
+    pad_px: int = 2,
+    min_density_ratio: float = 0.004,
+) -> Image.Image:
+    gray = image.convert("L")
+    width, height = gray.size
+    if width == 0 or height == 0:
+        return image
+
+    pixels = gray.load()
+    row_density = []
+    for y in range(height):
+        dark = sum(1 for x in range(width) if pixels[x, y] < threshold)
+        row_density.append(dark)
+
+    line_threshold = int(width * 0.6)
+    line_rows = {i for i, d in enumerate(row_density) if d >= line_threshold}
+    if not line_rows and max(row_density, default=0) == 0:
+        return image
+
+    min_density = max(2, int(width * min_density_ratio))
+    segments: list[tuple[int, int]] = []
+    start: int | None = None
+    for y, dark in enumerate(row_density):
+        if y in line_rows:
+            if start is not None:
+                segments.append((start, y - 1))
+                start = None
+            continue
+        if dark >= min_density:
+            if start is None:
+                start = y
+        else:
+            if start is not None:
+                segments.append((start, y - 1))
+                start = None
+    if start is not None:
+        segments.append((start, height - 1))
+
+    if not segments:
+        return image
+
+    def segment_score(y0: int, y1: int) -> int:
+        return sum(row_density[y0 : y1 + 1])
+
+    line_groups: list[tuple[int, int]] = []
+    if line_rows:
+        sorted_rows = sorted(line_rows)
+        group_start = sorted_rows[0]
+        prev = sorted_rows[0]
+        for row in sorted_rows[1:]:
+            if row - prev > 1:
+                line_groups.append((group_start, prev))
+                group_start = row
+            prev = row
+        line_groups.append((group_start, prev))
+
+    max_gap = min(int(height * 0.35), 140)
+    best_segment: tuple[int, int] | None = None
+    best_score = None
+
+    def consider_segments(above: bool) -> bool:
+        nonlocal best_segment, best_score
+        found = False
+        for line_start, line_end in line_groups:
+            for y0, y1 in segments:
+                if above:
+                    gap = line_start - y1
+                    if y1 >= line_start or gap > max_gap:
+                        continue
+                else:
+                    gap = y0 - line_end
+                    if y0 <= line_end or gap > max_gap:
+                        continue
+
+                height_span = y1 - y0 + 1
+                if height_span < 2:
+                    continue
+                score = segment_score(y0, y1)
+                proximity = 1.0 / (1.0 + (gap / 25.0))
+                weighted = score * (1.0 + 0.5 * proximity)
+                if best_score is None or weighted > best_score:
+                    best_score = weighted
+                    best_segment = (y0, y1)
+                found = True
+        return found
+
+    if line_groups:
+        if not consider_segments(True):
+            consider_segments(False)
+
+    if best_segment is None:
+        for y0, y1 in segments:
+            score = segment_score(y0, y1)
+            if best_score is None or score > best_score:
+                best_score = score
+                best_segment = (y0, y1)
+
+    if best_segment is None:
+        return image
+
+    y0, y1 = best_segment
+    min_x, max_x = width, -1
+    for y in range(y0, y1 + 1):
+        if y in line_rows:
+            continue
+        for x in range(width):
+            if pixels[x, y] < threshold:
+                if x < min_x:
+                    min_x = x
+                if x > max_x:
+                    max_x = x
+
+    if max_x < 0:
+        return image
+
+    x0 = max(0, min_x - pad_px)
+    x1 = min(width - 1, max_x + pad_px)
+    y0 = max(0, y0 - pad_px)
+    y1 = min(height - 1, y1 + pad_px)
+    if x1 <= x0 or y1 <= y0:
+        return image
+    return image.crop((x0, y0, x1 + 1, y1 + 1))
+
+
+def _detect_horizontal_rule_cutoff(
+    row_density: list[int],
+    width: int,
+) -> tuple[int, int] | None:
+    if not row_density:
+        return None
+    line_threshold = int(width * 0.6)
+    max_thickness = 4
+    segments: list[tuple[int, int]] = []
+    start = None
+    for y, density in enumerate(row_density):
+        if density >= line_threshold:
+            if start is None:
+                start = y
+        else:
+            if start is not None:
+                segments.append((start, y - 1))
+                start = None
+    if start is not None:
+        segments.append((start, len(row_density) - 1))
+
+    if not segments:
+        return None
+
+    total_dark = sum(row_density)
+    if total_dark <= 0:
+        return None
+
+    min_above_dark = max(40, int(total_dark * 0.02))
+    for y0, y1 in segments:
+        thickness = y1 - y0 + 1
+        if thickness > max_thickness:
+            continue
+        above_dark = sum(row_density[:y0])
+        below_dark = sum(row_density[y1 + 1 :])
+        if above_dark < 40:
+            continue
+        midpoint_ratio = ((y0 + y1) / 2.0) / max(1, len(row_density))
+        if above_dark >= min_above_dark and midpoint_ratio >= 0.2:
+            return (y0, y1)
+        if midpoint_ratio >= 0.35:
+            return (y0, y1)
+        if above_dark >= max(40, int(below_dark * 0.3)):
+            return (y0, y1)
+    return None
+
+
 def _to_clip_rect(page, bbox: tuple[float, float, float, float]):
     width = float(page.rect.width)
     height = float(page.rect.height)
@@ -237,6 +1789,31 @@ def _to_clip_rect(page, bbox: tuple[float, float, float, float]):
     return fitz.Rect(left, top, right, bottom)
 
 
+def _expand_wet_bbox(page, bbox: tuple[float, float, float, float]) -> tuple[float, float, float, float] | None:
+    clip = _to_clip_rect(page, bbox)
+    if clip is None:
+        return None
+    rect = fitz.Rect(clip)
+    width = rect.width
+    height = rect.height
+    if width <= 0 or height <= 0:
+        return None
+    page_rect = page.rect
+    if width >= page_rect.width * 0.45:
+        return None
+
+    left_pad = max(6.0, width * 0.15)
+    left = max(page_rect.x0, rect.x0 - left_pad)
+    right = page_rect.x1 if width < page_rect.width * 0.7 else rect.x1
+
+    pad_y = max(12.0, height * 0.8)
+    top = max(page_rect.y0, rect.y0 - pad_y)
+    bottom = min(page_rect.y1, rect.y1 + pad_y)
+    if right <= left or bottom <= top:
+        return None
+    return _rect_to_pdf_tuple(fitz.Rect(left, top, right, bottom), page_rect.height)
+
+
 def _clamp(value: float, lower: float, upper: float) -> float:
     return max(lower, min(value, upper))
 
@@ -251,3 +1828,787 @@ def _slugify(value: str) -> str:
     cleaned = re.sub(r"[^A-Za-z0-9_-]+", "_", value.strip().lower())
     cleaned = cleaned.strip("_")
     return cleaned or "signature"
+
+
+def _update_signature_pages(file_result: FileResult) -> None:
+    pages = sorted({sig.Page for sig in file_result.Signatures if sig.Page})
+    file_result.SignaturePages = ",".join(str(page) for page in pages)
+
+
+def _bbox_has_area(bbox: tuple[float, float, float, float] | None) -> bool:
+    if not bbox or len(bbox) != 4:
+        return False
+    x0, y0, x1, y1 = bbox
+    return not (x0 == 0 and y0 == 0 and x1 == 0 and y1 == 0) and (x1 - x0) > 0 and (y1 - y0) > 0
+
+
+def _is_pseudo_signature(signature: Signature) -> bool:
+    if _has_image_evidence(signature):
+        return False
+    if signature.FieldName == "vendor_or_acro_detected":
+        return True
+    hint = (signature.Hint or "").lower()
+    if "vendororacronly" in hint:
+        return True
+    return any("pseudo:true" == token for token in signature.Evidence)
+
+
+def _has_image_evidence(signature: Signature) -> bool:
+    return bool(signature.Evidence and any("image:retainer" == token for token in signature.Evidence))
+
+
+def _collect_image_rects(page) -> list[object]:
+    rects: list[object] = []
+    try:
+        images = page.get_images(full=True)
+    except Exception:
+        return rects
+    for img in images:
+        xref = img[0]
+        try:
+            rects.extend(page.get_image_rects(xref))
+        except Exception:
+            continue
+    return rects
+
+
+def _filter_image_rects(rects: list[object], page_rect) -> list[object]:
+    if not rects:
+        return []
+    max_area = page_rect.width * page_rect.height * 0.35
+    filtered: list[object] = []
+    for rect in rects:
+        r = fitz.Rect(rect)
+        area = r.get_area()
+        if area <= 0:
+            continue
+        if area > max_area:
+            continue
+        filtered.append(r)
+    return filtered
+
+
+def _select_image_bbox(
+    image_rects: list[object],
+    signature: Signature,
+    role_rects: dict[str, list[object]],
+    label_rects: list[object],
+    page_rect,
+    *,
+    signature_index: int,
+    signature_count: int,
+) -> tuple[float, float, float, float] | None:
+    if not image_rects:
+        return None
+    filtered = _filter_image_rects(image_rects, page_rect)
+    if not filtered:
+        return None
+
+    role_hint = (signature.Role or "").lower()
+    anchors: list[object] = []
+    if role_hint in {"firm", "attorney"}:
+        anchors = role_rects.get("firm", [])
+    elif role_hint in {"client", "patient", "representative"}:
+        anchors = role_rects.get("client", []) + label_rects
+    else:
+        anchors = label_rects
+
+    if anchors:
+        candidate, score = _select_rect_near_labels_with_score(filtered, anchors)
+        max_distance = min(page_rect.height * 0.5, 260.0)
+        if candidate is None or score is None or score > max_distance:
+            candidate = None
+    else:
+        candidate = _select_rect_by_order(filtered, signature, signature_index, signature_count)
+
+    if candidate is None:
+        return None
+    bbox = _rect_to_pdf_tuple(candidate, page_rect.height)
+    if _bbox_has_area(bbox):
+        return bbox
+    return None
+
+
+def _refine_bbox_with_image_rects(
+    page,
+    bbox: tuple[float, float, float, float],
+    *,
+    image_rects: list[object],
+    min_overlap: float = 0.6,
+    min_center_overlap: float = 0.2,
+    min_area: float = 20.0,
+) -> tuple[float, float, float, float] | None:
+    clip = _to_clip_rect(page, bbox)
+    if clip is None:
+        return None
+    best_rect = None
+    best_overlap = None
+    best_distance = None
+    clip_center_x = (clip.x0 + clip.x1) / 2.0
+    clip_center_y = (clip.y0 + clip.y1) / 2.0
+    for rect in image_rects:
+        try:
+            inter = rect & clip
+        except Exception:
+            continue
+        if inter is None or inter.get_area() <= 0:
+            continue
+        rect_area = rect.get_area()
+        if rect_area <= min_area:
+            continue
+        overlap = inter.get_area() / max(1.0, rect_area)
+        center_x = (rect.x0 + rect.x1) / 2.0
+        center_y = (rect.y0 + rect.y1) / 2.0
+        center_inside = (clip.x0 <= center_x <= clip.x1) and (clip.y0 <= center_y <= clip.y1)
+        if overlap < min_overlap and not (center_inside and overlap >= min_center_overlap):
+            continue
+        distance = (center_x - clip_center_x) ** 2 + (center_y - clip_center_y) ** 2
+        if best_overlap is None:
+            best_overlap = overlap
+            best_distance = distance
+            best_rect = rect
+            continue
+        if overlap > best_overlap:
+            best_overlap = overlap
+            best_distance = distance
+            best_rect = rect
+            continue
+        if abs(overlap - best_overlap) <= 0.05 and best_distance is not None and distance < best_distance:
+            best_distance = distance
+            best_rect = rect
+    if best_rect is None:
+        return None
+    return _rect_to_pdf_tuple(best_rect, page.rect.height)
+
+
+def _ink_metrics(image_bytes: bytes, *, threshold: int = 240) -> tuple[int, float]:
+    image = Image.open(io.BytesIO(image_bytes))
+    gray = image.convert("L")
+    histogram = gray.histogram()
+    total = sum(histogram)
+    dark = sum(histogram[:threshold])
+    ratio = (dark / total) if total else 0.0
+    return dark, ratio
+
+
+def _is_blank_crop(
+    image_bytes: bytes,
+    *,
+    min_pixels: int = 40,
+    min_ratio: float = 0.0005,
+) -> bool:
+    dark, ratio = _ink_metrics(image_bytes)
+    return dark < min_pixels and ratio < min_ratio
+
+
+def _resolve_signature_bbox(
+    page,
+    signature: Signature,
+    *,
+    page_cache: dict[int, dict[str, object]],
+    signature_count: int,
+    signature_index: int,
+    page_number: int,
+) -> tuple[float, float, float, float] | None:
+    cache = page_cache.setdefault(page_number, {})
+    name = (signature.FieldName or "").strip()
+
+    label_rects = _get_label_rects(page_cache, page_number, page)
+    role_rects = _get_role_label_rects(page_cache, page_number, page)
+    line_rects = _get_line_rects(page_cache, page_number, page)
+
+    if signature.RenderType in {"typed", "drawn"}:
+        image_rects = _get_image_rects(page_cache, page_number, page)
+        image_bbox = _select_image_bbox(
+            image_rects,
+            signature,
+            role_rects,
+            label_rects,
+            page.rect,
+            signature_index=signature_index,
+            signature_count=signature_count,
+        )
+        if image_bbox is not None:
+            return image_bbox
+
+    line_bbox = _select_line_bbox(
+        line_rects,
+        signature,
+        role_rects,
+        label_rects,
+        page.rect,
+    )
+    if line_bbox is not None:
+        return line_bbox
+
+    widget_cache = cache.get("widget_cache")
+    if widget_cache is None:
+        widget_map, widget_sig_rects, widget_rects = _collect_widget_rects(page)
+        widget_cache = {
+            "map": widget_map,
+            "sig_rects": widget_sig_rects,
+            "all_rects": widget_rects,
+        }
+        cache["widget_cache"] = widget_cache
+    widget_map = widget_cache["map"]
+    widget_sig_rects = widget_cache["sig_rects"]
+    widget_rects = widget_cache["all_rects"]
+
+    if name:
+        rect = widget_map.get(name)
+        if rect is not None:
+            bbox = _rect_to_pdf_tuple(rect, page.rect.height)
+            if _bbox_has_area(bbox):
+                return bbox
+
+    rect = _select_rect_candidate(
+        widget_sig_rects,
+        signature,
+        signature_index,
+        signature_count,
+        label_rects,
+    )
+    if rect is not None:
+        bbox = _rect_to_pdf_tuple(rect, page.rect.height)
+        if _bbox_has_area(bbox):
+            return bbox
+
+    widget_candidates = _filter_signature_like_rects(widget_rects, page.rect)
+    rect = _select_rect_candidate(
+        widget_candidates,
+        signature,
+        signature_index,
+        signature_count,
+        label_rects,
+    )
+    if rect is not None:
+        bbox = _rect_to_pdf_tuple(rect, page.rect.height)
+        if _bbox_has_area(bbox):
+            return bbox
+    if not widget_candidates and len(widget_rects) == 1:
+        bbox = _rect_to_pdf_tuple(widget_rects[0], page.rect.height)
+        if _bbox_has_area(bbox):
+            return bbox
+
+    annot_cache = cache.get("annot_cache")
+    if annot_cache is None:
+        annot_map, annot_rects = _collect_annot_rects(page)
+        annot_cache = {"map": annot_map, "rects": annot_rects}
+        cache["annot_cache"] = annot_cache
+    annot_map = annot_cache["map"]
+    annot_rects = annot_cache["rects"]
+
+    if name:
+        rect = annot_map.get(name)
+        if rect is not None:
+            bbox = _rect_to_pdf_tuple(rect, page.rect.height)
+            if _bbox_has_area(bbox):
+                return bbox
+
+    annot_candidates = _filter_signature_like_rects(annot_rects, page.rect)
+    if not annot_candidates and len(annot_rects) == 1:
+        annot_candidates = [fitz.Rect(annot_rects[0])]
+    rect = _select_rect_candidate(
+        annot_candidates,
+        signature,
+        signature_index,
+        signature_count,
+        label_rects,
+    )
+    if rect is not None:
+        bbox = _rect_to_pdf_tuple(rect, page.rect.height)
+        if _bbox_has_area(bbox):
+            return bbox
+    if label_rects:
+        target = _select_rect_by_order(label_rects, signature, signature_index, signature_count)
+        if target is not None:
+            expanded = _expand_rect_from_label(target, page.rect)
+            if expanded is not None:
+                bbox = _rect_to_pdf_tuple(expanded, page.rect.height)
+                if _bbox_has_area(bbox):
+                    return bbox
+
+    if name:
+        fieldname_cache = cache.get("fieldname_cache")
+        if fieldname_cache is None:
+            fieldname_cache = {}
+            cache["fieldname_cache"] = fieldname_cache
+        rects = fieldname_cache.get(name)
+        if rects is None:
+            rects = _find_fieldname_text_rects(page, name)
+            fieldname_cache[name] = rects
+        if rects:
+            target = _select_rect_by_order(rects, signature, signature_index, signature_count)
+            if target is not None:
+                expanded = _expand_rect_around_text(target, page.rect)
+                if expanded is not None:
+                    bbox = _rect_to_pdf_tuple(expanded, page.rect.height)
+                    if _bbox_has_area(bbox):
+                        return bbox
+
+    return None
+
+
+def _resolve_bbox_across_document(
+    document,
+    signature: Signature,
+    *,
+    page_cache: dict[int, dict[str, object]],
+    document_cache: dict[str, object],
+    signature_index: int,
+    signature_count: int,
+    skip_page: int | None,
+) -> tuple[int | None, tuple[float, float, float, float] | None]:
+    label_pages = document_cache.get("label_pages")
+    if label_pages is None:
+        label_pages = []
+        for page_index in range(document.page_count):
+            page_number = page_index + 1
+            page = document.load_page(page_index)
+            labels = _get_label_rects(page_cache, page_number, page)
+            if labels:
+                label_pages.append(page_number)
+        document_cache["label_pages"] = label_pages
+
+    page_order = list(label_pages)
+    for page_number in range(1, document.page_count + 1):
+        if page_number not in page_order:
+            page_order.append(page_number)
+
+    for page_number in page_order:
+        if skip_page is not None and page_number == skip_page:
+            continue
+        page = document.load_page(page_number - 1)
+        resolved = _resolve_signature_bbox(
+            page,
+            signature,
+            page_cache=page_cache,
+            signature_count=signature_count,
+            signature_index=signature_index,
+            page_number=page_number,
+        )
+        if resolved is not None:
+            return page_number, resolved
+    return None, None
+
+
+_SIGNATURE_NAME_PATTERN = re.compile(r"\bsign", re.IGNORECASE)
+_SIGNATURE_LABEL_PATTERNS = (
+    re.compile(r"\bsignature\b", re.IGNORECASE),
+    re.compile(r"\bsign here\b", re.IGNORECASE),
+    re.compile(r"\bsigned by\b", re.IGNORECASE),
+    re.compile(r"/s/", re.IGNORECASE),
+)
+
+_ROLE_LABEL_PATTERNS = {
+    "client": (
+        re.compile(r"\bclient\b", re.IGNORECASE),
+        re.compile(r"\bpatient\b", re.IGNORECASE),
+        re.compile(r"\bplaintiff\b", re.IGNORECASE),
+    ),
+    "firm": (
+        re.compile(r"\bfirm\b", re.IGNORECASE),
+        re.compile(r"\battorney\b", re.IGNORECASE),
+        re.compile(r"\bcounsel\b", re.IGNORECASE),
+        re.compile(r"\blaw\b", re.IGNORECASE),
+        re.compile(r"\blegal\b", re.IGNORECASE),
+        re.compile(r"\bllc\b", re.IGNORECASE),
+        re.compile(r"\bllp\b", re.IGNORECASE),
+        re.compile(r"\bgroup\b", re.IGNORECASE),
+    ),
+}
+
+
+def _get_label_rects(
+    page_cache: dict[int, dict[str, object]],
+    page_number: int,
+    page,
+) -> list[object]:
+    cache = page_cache.setdefault(page_number, {})
+    label_rects = cache.get("label_rects")
+    if label_rects is None:
+        label_rects = _collect_signature_labels(page)
+        cache["label_rects"] = label_rects
+    return label_rects
+
+
+def _get_role_label_rects(
+    page_cache: dict[int, dict[str, object]],
+    page_number: int,
+    page,
+) -> dict[str, list[object]]:
+    cache = page_cache.setdefault(page_number, {})
+    role_rects = cache.get("role_rects")
+    if role_rects is None:
+        role_rects = _collect_role_text_rects(page)
+        cache["role_rects"] = role_rects
+    return role_rects
+
+
+def _get_line_rects(
+    page_cache: dict[int, dict[str, object]],
+    page_number: int,
+    page,
+) -> list[object]:
+    cache = page_cache.setdefault(page_number, {})
+    line_rects = cache.get("line_rects")
+    if line_rects is None:
+        line_rects = _collect_underscore_rects(page)
+        cache["line_rects"] = line_rects
+    return line_rects
+
+
+def _get_image_rects(
+    page_cache: dict[int, dict[str, object]],
+    page_number: int,
+    page,
+) -> list[object]:
+    cache = page_cache.setdefault(page_number, {})
+    image_rects = cache.get("image_rects")
+    if image_rects is None:
+        image_rects = _collect_image_rects(page)
+        cache["image_rects"] = image_rects
+    return image_rects
+
+
+def _collect_widget_rects(page) -> tuple[dict[str, object], list[object], list[object]]:
+    mapping: dict[str, object] = {}
+    signature_rects: list[object] = []
+    all_rects: list[object] = []
+    widgets = page.widgets() if hasattr(page, "widgets") else None
+    if not widgets:
+        return mapping, signature_rects, all_rects
+    for widget in widgets:
+        rect = widget.rect
+        name = (widget.field_name or "").strip()
+        if name:
+            mapping[name] = rect
+        all_rects.append(rect)
+        if _is_signature_widget(widget, name):
+            signature_rects.append(rect)
+    return mapping, signature_rects, all_rects
+
+
+def _is_signature_widget(widget, name: str) -> bool:
+    if getattr(widget, "field_type", None) in {getattr(fitz, "PDF_WIDGET_TYPE_SIGNATURE", 6)}:
+        return True
+    if name and _SIGNATURE_NAME_PATTERN.search(name):
+        return True
+    return False
+
+
+def _collect_annot_rects(page) -> tuple[dict[str, object], list[object]]:
+    mapping: dict[str, object] = {}
+    candidates: list[object] = []
+    annot = page.first_annot
+    while annot:
+        name = (getattr(annot, "field_name", None) or getattr(annot, "title", None) or "").strip()
+        if name and name not in mapping:
+            mapping[name] = annot.rect
+        if _is_signature_annotation(annot):
+            candidates.append(annot.rect)
+        annot = annot.next
+    return mapping, candidates
+
+
+def _is_signature_annotation(annot) -> bool:
+    try:
+        annot_type = (
+            annot.type[1] if isinstance(annot.type, tuple) and len(annot.type) > 1 else None
+        )
+    except Exception:  # pragma: no cover - defensive
+        annot_type = None
+    if not annot_type:
+        return False
+    label = str(annot_type).lower()
+    return label in {"stamp", "ink", "freetext", "text"}
+
+
+def _collect_signature_labels(page) -> list[object]:
+    labels: list[object] = []
+    try:
+        blocks = page.get_text("blocks")
+    except Exception:  # pragma: no cover - defensive
+        return labels
+    for block in blocks or []:
+        if not block or len(block) < 5:
+            continue
+        text = str(block[4] or "")
+        if not text:
+            continue
+        if _is_signature_label_text(text):
+            labels.append(fitz.Rect(block[0], block[1], block[2], block[3]))
+    return labels
+
+
+def _is_signature_label_text(text: str) -> bool:
+    normalized = " ".join(text.split())
+    return any(pattern.search(normalized) for pattern in _SIGNATURE_LABEL_PATTERNS)
+
+
+def _collect_text_lines(page) -> list[dict[str, object]]:
+    lines: dict[tuple[int, int], dict[str, object]] = {}
+    try:
+        words = page.get_text("words") or []
+    except Exception:  # pragma: no cover - defensive
+        return []
+    for word in words:
+        if len(word) < 8:
+            continue
+        x0, y0, x1, y1, text, block_no, line_no, *_ = word
+        key = (int(block_no), int(line_no))
+        entry = lines.get(key)
+        if entry is None:
+            entry = {
+                "x0": float(x0),
+                "y0": float(y0),
+                "x1": float(x1),
+                "y1": float(y1),
+                "text": str(text),
+            }
+            lines[key] = entry
+        else:
+            entry["x0"] = min(entry["x0"], float(x0))
+            entry["y0"] = min(entry["y0"], float(y0))
+            entry["x1"] = max(entry["x1"], float(x1))
+            entry["y1"] = max(entry["y1"], float(y1))
+            entry["text"] = f"{entry['text']} {text}"
+    result: list[dict[str, object]] = []
+    for entry in lines.values():
+        text = str(entry["text"]).strip()
+        if not text:
+            continue
+        entry["lower"] = text.lower()
+        entry["rect"] = fitz.Rect(entry["x0"], entry["y0"], entry["x1"], entry["y1"])
+        result.append(entry)
+    return result
+
+
+def _collect_role_text_rects(page) -> dict[str, list[object]]:
+    rects: dict[str, list[object]] = {"client": [], "firm": []}
+    lines = _collect_text_lines(page)
+    for line in lines:
+        text = str(line["text"])
+        lower = str(line["lower"])
+        if len(text) > 60:
+            continue
+        for role, patterns in _ROLE_LABEL_PATTERNS.items():
+            if any(pattern.search(lower) for pattern in patterns):
+                rects[role].append(line["rect"])
+    return rects
+
+
+def _collect_underscore_rects(page) -> list[object]:
+    rects: list[object] = []
+    try:
+        words = page.get_text("words") or []
+    except Exception:  # pragma: no cover - defensive
+        return rects
+    for word in words:
+        if len(word) < 5:
+            continue
+        x0, y0, x1, y1, text, *_ = word
+        text = str(text)
+        if text and set(text) == {"_"} and len(text) >= 4:
+            rects.append(fitz.Rect(float(x0), float(y0), float(x1), float(y1)))
+    return rects
+
+
+def _select_line_bbox(
+    line_rects: list[object],
+    signature: Signature,
+    role_rects: dict[str, list[object]],
+    label_rects: list[object],
+    page_rect,
+) -> tuple[float, float, float, float] | None:
+    if not line_rects:
+        return None
+    role_hint = (signature.Role or "").lower()
+    anchors: list[object] = []
+    if role_hint in {"firm", "attorney"}:
+        anchors = role_rects.get("firm", [])
+    elif role_hint in {"client", "patient", "representative"}:
+        anchors = role_rects.get("client", []) + label_rects
+    else:
+        anchors = label_rects
+
+    if anchors:
+        candidate, score = _select_rect_near_labels_with_score(line_rects, anchors)
+        max_distance = min(page_rect.height * 0.35, 220.0)
+        if candidate is None or score is None or score > max_distance:
+            candidate = None
+    else:
+        candidate = _select_rect_by_order(line_rects, signature, 1, 1)
+
+    if candidate is None:
+        return None
+    expanded = _expand_rect_from_line(candidate, page_rect)
+    if expanded is None:
+        return None
+    bbox = _rect_to_pdf_tuple(expanded, page_rect.height)
+    if _bbox_has_area(bbox):
+        return bbox
+    return None
+
+
+def _select_rect_near_labels_with_score(
+    rects: list[object],
+    label_rects: list[object],
+) -> tuple[object | None, float | None]:
+    if not rects or not label_rects:
+        return None, None
+    best = None
+    best_score: float | None = None
+    for rect in rects:
+        r = fitz.Rect(rect)
+        for label in label_rects:
+            l = fitz.Rect(label)
+            vertical_gap = max(0.0, max(l.y0 - r.y1, r.y0 - l.y1))
+            horizontal_gap = max(0.0, max(l.x0 - r.x1, r.x0 - l.x1))
+            score = vertical_gap * 2.0 + horizontal_gap
+            if best_score is None or score < best_score:
+                best_score = score
+                best = r
+    return best, best_score
+
+
+def _expand_rect_from_line(line_rect, page_rect):
+    rect = fitz.Rect(line_rect)
+    width = rect.width
+    height = rect.height
+    if width <= 0 or height <= 0:
+        return None
+    pad_x = max(8.0, width * 0.05)
+    left = max(page_rect.x0, rect.x0 - pad_x)
+    right = min(page_rect.x1, rect.x1 + pad_x)
+
+    max_height = min(140.0, max(60.0, height * 12.0))
+    gap = max(2.0, height * 1.5)
+    upper = max(page_rect.y0, rect.y0 - gap)
+    lower = max(page_rect.y0, upper - max_height)
+    if upper <= lower:
+        return None
+    return fitz.Rect(left, lower, right, upper)
+
+
+def _select_rect_by_order(
+    rects: list[object],
+    signature: Signature,
+    signature_index: int,
+    signature_count: int,
+) -> object | None:
+    if not rects:
+        return None
+    ordered = sorted(rects, key=lambda rect: rect.y0)
+    if signature_count > 1 and signature_index > 0:
+        return ordered[min(signature_index - 1, len(ordered) - 1)]
+    role_hint = (signature.Role or "").lower()
+    if role_hint in {"patient", "client"}:
+        return ordered[0]
+    if role_hint in {"attorney", "firm"} and len(ordered) > 1:
+        return ordered[min(1, len(ordered) - 1)]
+    return ordered[0]
+
+
+def _select_rect_candidate(
+    rects: list[object],
+    signature: Signature,
+    signature_index: int,
+    signature_count: int,
+    label_rects: list[object] | None,
+) -> object | None:
+    if rects and label_rects:
+        near = _select_rect_near_labels(rects, label_rects)
+        if near is not None:
+            return near
+    return _select_rect_by_order(rects, signature, signature_index, signature_count)
+
+
+def _select_rect_near_labels(rects: list[object], label_rects: list[object]) -> object | None:
+    if not rects or not label_rects:
+        return None
+    best = None
+    best_score = None
+    for rect in rects:
+        r = fitz.Rect(rect)
+        for label in label_rects:
+            l = fitz.Rect(label)
+            vertical_gap = max(0.0, max(l.y0 - r.y1, r.y0 - l.y1))
+            horizontal_gap = max(0.0, max(l.x0 - r.x1, r.x0 - l.x1))
+            score = vertical_gap * 2.0 + horizontal_gap
+            if best_score is None or score < best_score:
+                best_score = score
+                best = r
+    return best
+
+
+def _filter_signature_like_rects(rects: list[object], page_rect) -> list[object]:
+    filtered: list[object] = []
+    for rect in rects:
+        r = fitz.Rect(rect)
+        width = r.width
+        height = r.height
+        if width < 40 or height < 8:
+            continue
+        if height > page_rect.height * 0.4:
+            continue
+        if width / max(height, 1.0) < 1.5:
+            continue
+        filtered.append(r)
+    return filtered
+
+
+def _expand_rect_from_label(label_rect, page_rect):
+    rect = fitz.Rect(label_rect)
+    height = max(16.0, rect.height)
+    width = max(80.0, rect.width)
+    left = max(page_rect.x0, rect.x0 - width * 0.05)
+    right = min(page_rect.x1, rect.x1 + width * 0.35)
+    gap = max(4.0, height * 0.3)
+    max_height = min(120.0, height * 5.5)
+
+    top = min(page_rect.y1, rect.y1 + gap)
+    bottom = min(page_rect.y1, top + max_height)
+    min_height = max(40.0, height * 2.5)
+    if bottom - top < min_height:
+        bottom = max(page_rect.y0, rect.y0 - gap)
+        top = max(page_rect.y0, bottom - max_height)
+    if bottom <= top:
+        return None
+    return fitz.Rect(left, top, right, bottom)
+
+
+def _find_fieldname_text_rects(page, field_name: str) -> list[object]:
+    name = field_name.strip()
+    if not name:
+        return []
+    try:
+        hits = page.search_for(name, flags=fitz.TEXT_IGNORECASE)
+    except Exception:  # pragma: no cover - defensive
+        return []
+    return [fitz.Rect(hit) for hit in hits]
+
+
+def _expand_rect_around_text(text_rect, page_rect):
+    rect = fitz.Rect(text_rect)
+    pad_x = max(6.0, rect.width * 0.2)
+    pad_y = max(4.0, rect.height * 0.8)
+    left = max(page_rect.x0, rect.x0 - pad_x)
+    right = min(page_rect.x1, rect.x1 + pad_x)
+    top = max(page_rect.y0, rect.y0 - pad_y)
+    bottom = min(page_rect.y1, rect.y1 + pad_y)
+    if right <= left or bottom <= top:
+        return None
+    return fitz.Rect(left, top, right, bottom)
+
+
+def _rect_to_pdf_tuple(rect, page_height: float) -> tuple[float, float, float, float]:
+    x0 = float(rect.x0)
+    x1 = float(rect.x1)
+    y0 = page_height - float(rect.y1)
+    y1 = page_height - float(rect.y0)
+    if x1 < x0:
+        x0, x1 = x1, x0
+    if y1 < y0:
+        y0, y1 = y1, y0
+    return (x0, y0, x1, y1)