natural-pdf 0.1.38__py3-none-any.whl → 0.2.0__py3-none-any.whl

natural_pdf/flows/region.py

@@ -1,11 +1,13 @@
 import logging
-from typing import TYPE_CHECKING, Any, Callable, Dict, List, Optional, Tuple, Union
+import warnings
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Literal, Optional, Tuple, Union
 
 from pdfplumber.utils.geometry import merge_bboxes  # Import merge_bboxes directly
 
 # For runtime image manipulation
 from PIL import Image as PIL_Image_Runtime
 
+from natural_pdf.core.render_spec import RenderSpec, Visualizable
 from natural_pdf.tables import TableResult
 
 if TYPE_CHECKING:
@@ -13,7 +15,7 @@ if TYPE_CHECKING:
 
     from natural_pdf.core.page import Page as PhysicalPage
     from natural_pdf.elements.base import Element as PhysicalElement
-    from natural_pdf.elements.collections import ElementCollection
+    from natural_pdf.elements.element_collection import ElementCollection
     from natural_pdf.elements.region import Region as PhysicalRegion
 
     from .element import FlowElement
@@ -22,7 +24,7 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
-class FlowRegion:
+class FlowRegion(Visualizable):
     """
     Represents a selected area within a Flow, potentially composed of multiple
     physical Region objects (constituent_regions) that might span across
@@ -65,17 +67,156 @@ class FlowRegion:
         self._cached_elements: Optional["ElementCollection"] = None  # Stringized
         self._cached_bbox: Optional[Tuple[float, float, float, float]] = None
 
+    def _get_highlighter(self):
+        """Get the highlighting service from constituent regions."""
+        if not self.constituent_regions:
+            raise RuntimeError("FlowRegion has no constituent regions to get highlighter from")
+
+        # Get highlighter from first constituent region
+        first_region = self.constituent_regions[0]
+        if hasattr(first_region, "_highlighter"):
+            return first_region._highlighter
+        elif hasattr(first_region, "page") and hasattr(first_region.page, "_highlighter"):
+            return first_region.page._highlighter
+        else:
+            raise RuntimeError(
+                f"Cannot find HighlightingService from FlowRegion constituent regions. "
+                f"First region type: {type(first_region).__name__}"
+            )
+
+    def _get_render_specs(
+        self,
+        mode: Literal["show", "render"] = "show",
+        color: Optional[Union[str, Tuple[int, int, int]]] = None,
+        highlights: Optional[List[Dict[str, Any]]] = None,
+        crop: Union[bool, Literal["content"]] = False,
+        crop_bbox: Optional[Tuple[float, float, float, float]] = None,
+        **kwargs,
+    ) -> List[RenderSpec]:
+        """Get render specifications for this flow region.
+
+        Args:
+            mode: Rendering mode - 'show' includes highlights, 'render' is clean
+            color: Color for highlighting this region in show mode
+            highlights: Additional highlight groups to show
+            crop: Whether to crop to constituent regions
+            crop_bbox: Explicit crop bounds
+            **kwargs: Additional parameters
+
+        Returns:
+            List of RenderSpec objects, one per page with constituent regions
+        """
+        if not self.constituent_regions:
+            return []
+
+        # Group constituent regions by page
+        regions_by_page = {}
+        for region in self.constituent_regions:
+            if hasattr(region, "page") and region.page:
+                page = region.page
+                if page not in regions_by_page:
+                    regions_by_page[page] = []
+                regions_by_page[page].append(region)
+
+        if not regions_by_page:
+            return []
+
+        # Create RenderSpec for each page
+        specs = []
+        for page, page_regions in regions_by_page.items():
+            spec = RenderSpec(page=page)
+
+            # Handle cropping
+            if crop_bbox:
+                spec.crop_bbox = crop_bbox
+            elif crop == "content" or crop is True:
+                # Calculate bounds of regions on this page
+                x_coords = []
+                y_coords = []
+                for region in page_regions:
+                    if hasattr(region, "bbox") and region.bbox:
+                        x0, y0, x1, y1 = region.bbox
+                        x_coords.extend([x0, x1])
+                        y_coords.extend([y0, y1])
+
+                if x_coords and y_coords:
+                    spec.crop_bbox = (min(x_coords), min(y_coords), max(x_coords), max(y_coords))
+
+            # Add highlights in show mode
+            if mode == "show":
+                # Highlight constituent regions
+                for i, region in enumerate(page_regions):
+                    # Label each part if multiple regions
+                    label = None
+                    if len(self.constituent_regions) > 1:
+                        # Find global index
+                        try:
+                            global_idx = self.constituent_regions.index(region)
+                            label = f"FlowPart_{global_idx + 1}"
+                        except ValueError:
+                            label = f"FlowPart_{i + 1}"
+                    else:
+                        label = "FlowRegion"
+
+                    spec.add_highlight(
+                        bbox=region.bbox,
+                        polygon=region.polygon if region.has_polygon else None,
+                        color=color or "fuchsia",
+                        label=label,
+                    )
+
+                # Add additional highlight groups if provided
+                if highlights:
+                    for group in highlights:
+                        group_elements = group.get("elements", [])
+                        group_color = group.get("color", color)
+                        group_label = group.get("label")
+
+                        for elem in group_elements:
+                            # Only add if element is on this page
+                            if hasattr(elem, "page") and elem.page == page:
+                                spec.add_highlight(
+                                    element=elem, color=group_color, label=group_label
+                                )
+
+            specs.append(spec)
+
+        return specs
+
     def __getattr__(self, name: str) -> Any:
         """
-        Dynamically proxy attribute access to the source FlowElement if the
-        attribute is not found in this instance.
+        Dynamically proxy attribute access to the source FlowElement for safe attributes only.
+        Spatial methods (above, below, left, right) are explicitly implemented to prevent
+        silent failures and incorrect behavior.
         """
         if name in self.__dict__:
             return self.__dict__[name]
-        elif self.source_flow_element is not None:
-            return getattr(self.source_flow_element, name)
-        else:
-            raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{name}'")
+
+        # List of methods that should NOT be proxied - they need proper FlowRegion implementation
+        spatial_methods = {"above", "below", "left", "right", "to_region"}
+
+        if name in spatial_methods:
+            raise AttributeError(
+                f"'{self.__class__.__name__}' object has no attribute '{name}'. "
+                f"This method requires proper FlowRegion implementation to handle spatial relationships correctly."
+            )
+
+        # Only proxy safe attributes and methods
+        if self.source_flow_element is not None:
+            try:
+                attr = getattr(self.source_flow_element, name)
+                # Only proxy non-callable attributes and explicitly safe methods
+                if not callable(attr) or name in {"page", "document"}:  # Add safe methods as needed
+                    return attr
+                else:
+                    raise AttributeError(
+                        f"Method '{name}' cannot be safely proxied from FlowElement to FlowRegion. "
+                        f"It may need explicit implementation."
+                    )
+            except AttributeError:
+                pass
+
+        raise AttributeError(f"'{self.__class__.__name__}' object has no attribute '{name}'")
 
     @property
     def bbox(self) -> Optional[Tuple[float, float, float, float]]:
@@ -90,10 +231,12 @@ class FlowRegion:
 
         # Use merge_bboxes from pdfplumber.utils.geometry to merge bboxes
         # Extract bbox tuples from regions first
-        region_bboxes = [region.bbox for region in self.constituent_regions if hasattr(region, "bbox")]
+        region_bboxes = [
+            region.bbox for region in self.constituent_regions if hasattr(region, "bbox")
+        ]
         if not region_bboxes:
             return None
-            
+
         self._cached_bbox = merge_bboxes(region_bboxes)
         return self._cached_bbox
 
@@ -171,7 +314,7 @@ class FlowRegion:
         Returns:
             An ElementCollection containing all unique elements.
         """
-        from natural_pdf.elements.collections import (
+        from natural_pdf.elements.element_collection import (
             ElementCollection as RuntimeElementCollection,  # Local import
         )
 
@@ -257,7 +400,7 @@ class FlowRegion:
         chains each region's native ``find_all`` call and concatenates their
         results into a single ElementCollection while preserving flow order.
         """
-        from natural_pdf.elements.collections import (
+        from natural_pdf.elements.element_collection import (
             ElementCollection as RuntimeElementCollection,
         )
 
@@ -268,9 +411,7 @@ class FlowRegion:
 
         for region in self.constituent_regions:
             try:
-                region_matches = region.find_all(
-            selector=selector, text=text, **kwargs
-                )
+                region_matches = region.find_all(selector=selector, text=text, **kwargs)
                 if region_matches:
                     # ``region_matches`` is an ElementCollection – extend with its
                     # underlying list so we don't create nested collections.
@@ -312,200 +453,33 @@ class FlowRegion:
             region.highlight(label=current_label, color=color, **kwargs)
         return self
 
-    def show(
-        self,
-        resolution: Optional[float] = None,
-        labels: bool = True,
-        legend_position: str = "right",
-        color: Optional[Union[Tuple, str]] = "fuchsia",
-        label_prefix: Optional[str] = "FlowPart",
-        width: Optional[int] = None,
-        stack_direction: str = "vertical",
-        stack_gap: int = 5,
-        stack_background_color: Tuple[int, int, int] = (255, 255, 255),
-        crop: bool = False,
-        **kwargs,
-    ) -> Optional["PIL_Image"]:
-        """
-        Generates and returns a PIL Image of relevant pages with constituent regions highlighted.
-        If multiple pages are involved, they are stacked into a single image.
-
-        Args:
-            resolution: Resolution in DPI for page rendering. If None, uses global setting or defaults to 144 DPI.
-            labels: Whether to include a legend for highlights.
-            legend_position: Position of the legend ('right', 'bottom', 'top', 'left').
-            color: Color for highlighting the constituent regions.
-            label_prefix: Prefix for region labels (e.g., 'FlowPart').
-            width: Optional width for the output image (overrides resolution).
-            stack_direction: Direction to stack multiple pages ('vertical' or 'horizontal').
-            stack_gap: Gap in pixels between stacked pages.
-            stack_background_color: RGB background color for the stacked image.
-            crop: If True, crop each rendered page to the bounding box of constituent regions on that page.
-            **kwargs: Additional arguments passed to the underlying rendering methods.
-
-        Returns:
-            PIL Image of the rendered pages with highlighted regions, or None if rendering fails.
+    def highlights(self, show: bool = False) -> "HighlightContext":
         """
-        if not self.constituent_regions:
-            logger.info("FlowRegion.show() called with no constituent regions.")
-            return None
+        Create a highlight context for accumulating highlights.
 
-        # 1. Group constituent regions by their physical page
-        regions_by_page: Dict["PhysicalPage", List["PhysicalRegion"]] = {}
-        for region in self.constituent_regions:
-            if region.page:
-                if region.page not in regions_by_page:
-                    regions_by_page[region.page] = []
-                regions_by_page[region.page].append(region)
-            else:
-                raise ValueError(f"Constituent region {region.bbox} has no page.")
+        This allows for clean syntax to show multiple highlight groups:
 
-        if not regions_by_page:
-            logger.info("FlowRegion.show() found no constituent regions with associated pages.")
-            return None
-
-        # 2. Get a highlighter service (e.g., from the first page involved)
-        first_page_with_regions = next(iter(regions_by_page.keys()), None)
-        highlighter_service = None
-        if first_page_with_regions and hasattr(first_page_with_regions, "_highlighter"):
-            highlighter_service = first_page_with_regions._highlighter
+        Example:
+            with flow_region.highlights() as h:
+                h.add(flow_region.find_all('table'), label='tables', color='blue')
+                h.add(flow_region.find_all('text:bold'), label='bold text', color='red')
+                h.show()
 
-        if not highlighter_service:
-            raise ValueError(
-                "Cannot get highlighter service for FlowRegion.show(). "
-                "Ensure constituent regions' pages are initialized with a highlighter."
-            )
-
-        output_page_images: List["PIL_Image_Runtime"] = []
+        Or with automatic display:
+            with flow_region.highlights(show=True) as h:
+                h.add(flow_region.find_all('table'), label='tables')
+                h.add(flow_region.find_all('text:bold'), label='bold')
+                # Automatically shows when exiting the context
 
-        # Sort pages by index for consistent output order
-        sorted_pages = sorted(
-            regions_by_page.keys(),
-            key=lambda p: p.index if hasattr(p, "index") else getattr(p, "page_number", 0),
-        )
-
-        # 3. Render each page with its relevant constituent regions highlighted
-        for page_idx, page_obj in enumerate(sorted_pages):
-            constituent_regions_on_this_page = regions_by_page[page_obj]
-            if not constituent_regions_on_this_page:
-                continue
-
-            temp_highlights_for_page = []
-            for i, region_part in enumerate(constituent_regions_on_this_page):
-                part_label = None
-                if labels and label_prefix:  # Ensure labels is True for label_prefix to apply
-                    # If FlowRegion consists of multiple parts on this page, or overall
-                    count_indicator = ""
-                    if (
-                        len(self.constituent_regions) > 1
-                    ):  # If flow region has multiple parts overall
-                        # Find global index of this region_part in self.constituent_regions
-                        try:
-                            global_idx = self.constituent_regions.index(region_part)
-                            count_indicator = f"_{global_idx + 1}"
-                        except ValueError:  # Should not happen if region_part is from the list
-                            count_indicator = f"_p{page_idx}i{i+1}"  # fallback local index
-                    elif (
-                        len(constituent_regions_on_this_page) > 1
-                    ):  # If multiple parts on *this* page, but FR is single part overall
-                        count_indicator = f"_{i+1}"
-
-                    part_label = f"{label_prefix}{count_indicator}" if label_prefix else None
-
-                temp_highlights_for_page.append(
-                    {
-                        "page_index": (
-                            page_obj.index
-                            if hasattr(page_obj, "index")
-                            else getattr(page_obj, "page_number", 1) - 1
-                        ),
-                        "bbox": region_part.bbox,
-                        "polygon": region_part.polygon if region_part.has_polygon else None,
-                        "color": color,  # Use the passed color
-                        "label": part_label,
-                        "use_color_cycling": False,  # Keep specific color
-                    }
-                )
-
-            if not temp_highlights_for_page:
-                continue
-
-            # Calculate crop bbox if cropping is enabled
-            crop_bbox = None 
-            if crop and constituent_regions_on_this_page:
-                # Calculate the bounding box that encompasses all constituent regions on this page
-                min_x0 = min(region.bbox[0] for region in constituent_regions_on_this_page)
-                min_y0 = min(region.bbox[1] for region in constituent_regions_on_this_page)
-                max_x1 = max(region.bbox[2] for region in constituent_regions_on_this_page)
-                max_y1 = max(region.bbox[3] for region in constituent_regions_on_this_page)
-                crop_bbox = (min_x0, min_y0, max_x1, max_y1)
-
-            page_image = highlighter_service.render_preview(
-                page_index=(
-                    page_obj.index
-                    if hasattr(page_obj, "index")
-                    else getattr(page_obj, "page_number", 1) - 1
-                ),
-                temporary_highlights=temp_highlights_for_page,
-                resolution=resolution,
-                width=width,
-                labels=labels,  # Pass through labels
-                legend_position=legend_position,
-                crop_bbox=crop_bbox,
-                **kwargs,
-            )
-            if page_image:
-                output_page_images.append(page_image)
-
-        # 4. Stack the generated page images if multiple
-        if not output_page_images:
-            logger.info("FlowRegion.show() produced no page images to concatenate.")
-            return None
-
-        if len(output_page_images) == 1:
-            return output_page_images[0]
+        Args:
+            show: If True, automatically show highlights when exiting context
 
-        # Stacking logic (same as in FlowRegionCollection.show)
-        if stack_direction == "vertical":
-            final_width = max(img.width for img in output_page_images)
-            final_height = (
-                sum(img.height for img in output_page_images)
-                + (len(output_page_images) - 1) * stack_gap
-            )
-            if final_width == 0 or final_height == 0:
-                raise ValueError("Cannot create concatenated image with zero width or height.")
+        Returns:
+            HighlightContext for accumulating highlights
+        """
+        from natural_pdf.core.highlighting_service import HighlightContext
 
-            concatenated_image = PIL_Image_Runtime.new(
-                "RGB", (final_width, final_height), stack_background_color
-            )
-            current_y = 0
-            for img in output_page_images:
-                paste_x = (final_width - img.width) // 2
-                concatenated_image.paste(img, (paste_x, current_y))
-                current_y += img.height + stack_gap
-            return concatenated_image
-        elif stack_direction == "horizontal":
-            final_width = (
-                sum(img.width for img in output_page_images)
-                + (len(output_page_images) - 1) * stack_gap
-            )
-            final_height = max(img.height for img in output_page_images)
-            if final_width == 0 or final_height == 0:
-                raise ValueError("Cannot create concatenated image with zero width or height.")
-
-            concatenated_image = PIL_Image_Runtime.new(
-                "RGB", (final_width, final_height), stack_background_color
-            )
-            current_x = 0
-            for img in output_page_images:
-                paste_y = (final_height - img.height) // 2
-                concatenated_image.paste(img, (current_x, paste_y))
-                current_x += img.width + stack_gap
-            return concatenated_image
-        else:
-            raise ValueError(
-                f"Invalid stack_direction '{stack_direction}' for FlowRegion.show(). Must be 'vertical' or 'horizontal'."
-            )
+        return HighlightContext(self, show_on_exit=show)
 
     def to_images(
         self,
@@ -523,9 +497,8 @@ class FlowRegion:
         cropped_images: List["PIL_Image"] = []
         for region_part in self.constituent_regions:
             try:
-                img = region_part.to_image(
-                    resolution=resolution, crop=True, include_highlights=False, **kwargs
-                )
+                # Use render() for clean image without highlights
+                img = region_part.render(resolution=resolution, crop=True, **kwargs)
                 if img:
                     cropped_images.append(img)
             except Exception as e:
@@ -536,73 +509,424 @@ class FlowRegion:
 
         return cropped_images
 
-    def to_image(self, background_color=(255, 255, 255), **kwargs) -> Optional["PIL_Image"]:
+    def __repr__(self) -> str:
+        return (
+            f"<FlowRegion constituents={len(self.constituent_regions)}, flow={self.flow}, "
+            f"source_bbox={self.source_flow_element.bbox if self.source_flow_element else 'N/A'}>"
+        )
+
+    def expand(
+        self,
+        left: float = 0,
+        right: float = 0,
+        top: float = 0,
+        bottom: float = 0,
+        width_factor: float = 1.0,
+        height_factor: float = 1.0,
+    ) -> "FlowRegion":
         """
-        Creates a single composite image by stacking the images of its constituent regions.
-        Stacking direction is based on the Flow's arrangement.
-        Individual region images are obtained by calling to_images(**kwargs).
+        Create a new FlowRegion with all constituent regions expanded.
 
         Args:
-            background_color: Tuple for RGB background color of the composite image.
-            **kwargs: Additional arguments passed to to_images() for rendering individual parts
-                      (e.g., resolution).
+            left: Amount to expand left edge (positive value expands leftwards)
+            right: Amount to expand right edge (positive value expands rightwards)
+            top: Amount to expand top edge (positive value expands upwards)
+            bottom: Amount to expand bottom edge (positive value expands downwards)
+            width_factor: Factor to multiply width by (applied after absolute expansion)
+            height_factor: Factor to multiply height by (applied after absolute expansion)
 
         Returns:
-            A single PIL.Image.Image object, or None if no constituent images.
+            New FlowRegion with expanded constituent regions
         """
-        # Use PIL_Image_Runtime for creating new images at runtime
-        images = self.to_images(**kwargs)
-        if not images:
-            return None
-        if len(images) == 1:
-            return images[0]
+        if not self.constituent_regions:
+            return FlowRegion(
+                flow=self.flow,
+                constituent_regions=[],
+                source_flow_element=self.source_flow_element,
+                boundary_element_found=self.boundary_element_found,
+            )
+
+        expanded_regions = []
+        for idx, region in enumerate(self.constituent_regions):
+            # Determine which adjustments to apply based on flow arrangement
+            apply_left = left
+            apply_right = right
+            apply_top = top
+            apply_bottom = bottom
+
+            if self.flow.arrangement == "vertical":
+                # In a vertical flow, only the *first* region should react to `top`
+                # and only the *last* region should react to `bottom`.  This keeps
+                # the virtual contiguous area intact while allowing users to nudge
+                # the flow boundaries.
+                if idx != 0:
+                    apply_top = 0
+                if idx != len(self.constituent_regions) - 1:
+                    apply_bottom = 0
+                # left/right apply to every region (same column width change)
+            else:  # horizontal flow
+                # In a horizontal flow, only the first region reacts to `left`
+                # and only the last region reacts to `right`.
+                if idx != 0:
+                    apply_left = 0
+                if idx != len(self.constituent_regions) - 1:
+                    apply_right = 0
+                # top/bottom apply to every region in horizontal flows
+
+            # Skip no-op expansion to avoid extra Region objects
+            needs_expansion = (
+                any(
+                    v not in (0, 1.0)  # compare width/height factor logically later
+                    for v in (apply_left, apply_right, apply_top, apply_bottom)
+                )
+                or width_factor != 1.0
+                or height_factor != 1.0
+            )
+
+            try:
+                expanded_region = (
+                    region.expand(
+                        left=apply_left,
+                        right=apply_right,
+                        top=apply_top,
+                        bottom=apply_bottom,
+                        width_factor=width_factor,
+                        height_factor=height_factor,
+                    )
+                    if needs_expansion
+                    else region
+                )
+                expanded_regions.append(expanded_region)
+            except Exception as e:
+                logger.warning(
+                    f"FlowRegion.expand: Error expanding constituent region {region.bbox}: {e}",
+                    exc_info=False,
+                )
+                expanded_regions.append(region)
+
+        # Create new FlowRegion with expanded constituent regions
+        new_flow_region = FlowRegion(
+            flow=self.flow,
+            constituent_regions=expanded_regions,
+            source_flow_element=self.source_flow_element,
+            boundary_element_found=self.boundary_element_found,
+        )
+
+        # Copy metadata
+        new_flow_region.source = self.source
+        new_flow_region.region_type = self.region_type
+        new_flow_region.metadata = self.metadata.copy()
+
+        # Clear caches since the regions have changed
+        new_flow_region._cached_text = None
+        new_flow_region._cached_elements = None
+        new_flow_region._cached_bbox = None
+
+        return new_flow_region
+
+    def above(
+        self,
+        height: Optional[float] = None,
+        width: str = "full",
+        include_source: bool = False,
+        until: Optional[str] = None,
+        include_endpoint: bool = True,
+        **kwargs,
+    ) -> "FlowRegion":
+        """
+        Create a FlowRegion with regions above this FlowRegion.
+
+        For vertical flows: Only expands the topmost constituent region upward.
+        For horizontal flows: Expands all constituent regions upward.
+
+        Args:
+            height: Height of the region above, in points
+            width: Width mode - "full" for full page width or "element" for element width
+            include_source: Whether to include this FlowRegion in the result
+            until: Optional selector string to specify an upper boundary element
+            include_endpoint: Whether to include the boundary element in the region
+            **kwargs: Additional parameters
+
+        Returns:
+            New FlowRegion with regions above
+        """
+        if not self.constituent_regions:
+            return FlowRegion(
+                flow=self.flow,
+                constituent_regions=[],
+                source_flow_element=self.source_flow_element,
+                boundary_element_found=self.boundary_element_found,
+            )
+
+        new_regions = []
 
         if self.flow.arrangement == "vertical":
-            # Stack vertically
-            composite_width = max(img.width for img in images)
-            composite_height = sum(img.height for img in images)
-            if composite_width == 0 or composite_height == 0:
-                return None  # Avoid zero-size image
-
-            new_image = PIL_Image_Runtime.new(
-                "RGB", (composite_width, composite_height), background_color
+            # For vertical flow, use FLOW ORDER (index 0 is earliest). Only expand the
+            # first constituent region in that order.
+            first_region = self.constituent_regions[0]
+            for idx, region in enumerate(self.constituent_regions):
+                if idx == 0:  # Only expand the first region (earliest in flow)
+                    above_region = region.above(
+                        height=height,
+                        width="element",  # Keep original column width
+                        include_source=include_source,
+                        until=until,
+                        include_endpoint=include_endpoint,
+                        **kwargs,
+                    )
+                    new_regions.append(above_region)
+                elif include_source:
+                    new_regions.append(region)
+        else:  # horizontal flow
+            # For horizontal flow, expand all regions upward
+            for region in self.constituent_regions:
+                above_region = region.above(
+                    height=height,
+                    width=width,
+                    include_source=include_source,
+                    until=until,
+                    include_endpoint=include_endpoint,
+                    **kwargs,
+                )
+                new_regions.append(above_region)
+
+        return FlowRegion(
+            flow=self.flow,
+            constituent_regions=new_regions,
+            source_flow_element=self.source_flow_element,
+            boundary_element_found=self.boundary_element_found,
+        )
+
+    def below(
+        self,
+        height: Optional[float] = None,
+        width: str = "full",
+        include_source: bool = False,
+        until: Optional[str] = None,
+        include_endpoint: bool = True,
+        **kwargs,
+    ) -> "FlowRegion":
+        """
+        Create a FlowRegion with regions below this FlowRegion.
+
+        For vertical flows: Only expands the bottommost constituent region downward.
+        For horizontal flows: Expands all constituent regions downward.
+
+        Args:
+            height: Height of the region below, in points
+            width: Width mode - "full" for full page width or "element" for element width
+            include_source: Whether to include this FlowRegion in the result
+            until: Optional selector string to specify a lower boundary element
+            include_endpoint: Whether to include the boundary element in the region
+            **kwargs: Additional parameters
+
+        Returns:
+            New FlowRegion with regions below
+        """
+        if not self.constituent_regions:
+            return FlowRegion(
+                flow=self.flow,
+                constituent_regions=[],
+                source_flow_element=self.source_flow_element,
+                boundary_element_found=self.boundary_element_found,
             )
-            current_y = 0
-            for img in images:
-                # Default to left alignment for vertical stacking
-                new_image.paste(img, (0, current_y))
-                current_y += img.height
-            return new_image
-
-        elif self.flow.arrangement == "horizontal":
-            # Stack horizontally
-            composite_width = sum(img.width for img in images)
-            composite_height = max(img.height for img in images)
-            if composite_width == 0 or composite_height == 0:
-                return None
-
-            new_image = PIL_Image_Runtime.new(
-                "RGB", (composite_width, composite_height), background_color
+
+        new_regions = []
+
+        if self.flow.arrangement == "vertical":
+            # For vertical flow, expand only the LAST constituent region in flow order.
+            last_idx = len(self.constituent_regions) - 1
+            for idx, region in enumerate(self.constituent_regions):
+                if idx == last_idx:
+                    below_region = region.below(
+                        height=height,
+                        width="element",
+                        include_source=include_source,
+                        until=until,
+                        include_endpoint=include_endpoint,
+                        **kwargs,
+                    )
+                    new_regions.append(below_region)
+                elif include_source:
+                    new_regions.append(region)
+        else:  # horizontal flow
+            # For horizontal flow, expand all regions downward
+            for region in self.constituent_regions:
+                below_region = region.below(
+                    height=height,
+                    width=width,
+                    include_source=include_source,
+                    until=until,
+                    include_endpoint=include_endpoint,
+                    **kwargs,
+                )
+                new_regions.append(below_region)
+
+        return FlowRegion(
+            flow=self.flow,
+            constituent_regions=new_regions,
+            source_flow_element=self.source_flow_element,
+            boundary_element_found=self.boundary_element_found,
+        )
+
+    def left(
+        self,
+        width: Optional[float] = None,
+        height: str = "full",
+        include_source: bool = False,
+        until: Optional[str] = None,
+        include_endpoint: bool = True,
+        **kwargs,
+    ) -> "FlowRegion":
+        """
+        Create a FlowRegion with regions to the left of this FlowRegion.
+
+        For vertical flows: Expands all constituent regions leftward.
+        For horizontal flows: Only expands the leftmost constituent region leftward.
+
+        Args:
+            width: Width of the region to the left, in points
+            height: Height mode - "full" for full page height or "element" for element height
+            include_source: Whether to include this FlowRegion in the result
+            until: Optional selector string to specify a left boundary element
+            include_endpoint: Whether to include the boundary element in the region
+            **kwargs: Additional parameters
+
+        Returns:
+            New FlowRegion with regions to the left
+        """
+        if not self.constituent_regions:
+            return FlowRegion(
+                flow=self.flow,
+                constituent_regions=[],
+                source_flow_element=self.source_flow_element,
+                boundary_element_found=self.boundary_element_found,
             )
-            current_x = 0
-            for img in images:
-                # Default to top alignment for horizontal stacking
-                new_image.paste(img, (current_x, 0))
-                current_x += img.width
-            return new_image
-        else:
-            # Should not happen if flow.arrangement is validated
-            logger.warning(
-                f"Unknown flow arrangement: {self.flow.arrangement}. Cannot stack images."
+
+        new_regions = []
+
+        if self.flow.arrangement == "vertical":
+            # For vertical flow, expand all regions leftward
+            for region in self.constituent_regions:
+                left_region = region.left(
+                    width=width,
+                    height="element",
+                    include_source=include_source,
+                    until=until,
+                    include_endpoint=include_endpoint,
+                    **kwargs,
+                )
+                new_regions.append(left_region)
+        else:  # horizontal flow
+            # For horizontal flow, only expand the leftmost region leftward
+            leftmost_region = min(self.constituent_regions, key=lambda r: r.x0)
+            for region in self.constituent_regions:
+                if region == leftmost_region:
+                    # Expand this region leftward
+                    left_region = region.left(
+                        width=width,
+                        height="element",
+                        include_source=include_source,
+                        until=until,
+                        include_endpoint=include_endpoint,
+                        **kwargs,
+                    )
+                    new_regions.append(left_region)
+                elif include_source:
+                    # Include other regions unchanged if include_source is True
+                    new_regions.append(region)
+
+        return FlowRegion(
+            flow=self.flow,
+            constituent_regions=new_regions,
+            source_flow_element=self.source_flow_element,
+            boundary_element_found=self.boundary_element_found,
+        )
+
+    def right(
+        self,
+        width: Optional[float] = None,
+        height: str = "full",
+        include_source: bool = False,
+        until: Optional[str] = None,
+        include_endpoint: bool = True,
+        **kwargs,
+    ) -> "FlowRegion":
+        """
+        Create a FlowRegion with regions to the right of this FlowRegion.
+
+        For vertical flows: Expands all constituent regions rightward.
+        For horizontal flows: Only expands the rightmost constituent region rightward.
+
+        Args:
+            width: Width of the region to the right, in points
+            height: Height mode - "full" for full page height or "element" for element height
+            include_source: Whether to include this FlowRegion in the result
+            until: Optional selector string to specify a right boundary element
+            include_endpoint: Whether to include the boundary element in the region
+            **kwargs: Additional parameters
+
+        Returns:
+            New FlowRegion with regions to the right
+        """
+        if not self.constituent_regions:
+            return FlowRegion(
+                flow=self.flow,
+                constituent_regions=[],
+                source_flow_element=self.source_flow_element,
+                boundary_element_found=self.boundary_element_found,
             )
-            return None
 
-    def __repr__(self) -> str:
-        return (
-            f"<FlowRegion constituents={len(self.constituent_regions)}, flow={self.flow}, "
-            f"source_bbox={self.source_flow_element.bbox if self.source_flow_element else 'N/A'}>"
+        new_regions = []
+
+        if self.flow.arrangement == "vertical":
+            # For vertical flow, expand all regions rightward
+            for region in self.constituent_regions:
+                right_region = region.right(
+                    width=width,
+                    height="element",
+                    include_source=include_source,
+                    until=until,
+                    include_endpoint=include_endpoint,
+                    **kwargs,
+                )
+                new_regions.append(right_region)
+        else:  # horizontal flow
+            # For horizontal flow, only expand the rightmost region rightward
+            rightmost_region = max(self.constituent_regions, key=lambda r: r.x1)
+            for region in self.constituent_regions:
+                if region == rightmost_region:
+                    # Expand this region rightward
+                    right_region = region.right(
+                        width=width,
+                        height="element",
+                        include_source=include_source,
+                        until=until,
+                        include_endpoint=include_endpoint,
+                        **kwargs,
+                    )
+                    new_regions.append(right_region)
+                elif include_source:
+                    # Include other regions unchanged if include_source is True
+                    new_regions.append(region)
+
+        return FlowRegion(
+            flow=self.flow,
+            constituent_regions=new_regions,
+            source_flow_element=self.source_flow_element,
+            boundary_element_found=self.boundary_element_found,
         )
 
+    def to_region(self) -> "FlowRegion":
+        """
+        Convert this FlowRegion to a region (returns a copy).
+        This is equivalent to calling expand() with no arguments.
+
+        Returns:
+            Copy of this FlowRegion
+        """
+        return self.expand()
+
     @property
     def is_empty(self) -> bool:
         """Checks if the FlowRegion contains no constituent regions or if all are empty."""
@@ -631,6 +955,13 @@ class FlowRegion:
         text_options: Optional[Dict] = None,
         cell_extraction_func: Optional[Callable[["PhysicalRegion"], Optional[str]]] = None,
         show_progress: bool = False,
+        # Optional row-level merge predicate. If provided, it decides whether
+        # the current row (first row of a segment/page) should be merged with
+        # the previous one (to handle multi-page spill-overs).
+        stitch_rows: Optional[
+            Callable[[List[Optional[str]], List[Optional[str]], int, "PhysicalRegion"], bool]
+        ] = None,
+        merge_headers: Optional[bool] = None,
         **kwargs,
     ) -> TableResult:
         """Extracts a single logical table from the FlowRegion.
@@ -644,6 +975,11 @@ class FlowRegion:
             method, table_settings, use_ocr, ocr_config, text_options, cell_extraction_func, show_progress:
                 Same as in :pymeth:`Region.extract_table` and are forwarded as-is
                 to each physical region.
+            merge_headers: Whether to merge tables by removing repeated headers from subsequent
+                pages/segments. If None (default), auto-detects by checking if the first row
+                of each segment matches the first row of the first segment. If segments have
+                inconsistent header patterns (some repeat, others don't), raises ValueError.
+                Useful for multi-page tables where headers repeat on each page.
             **kwargs: Additional keyword arguments forwarded to the underlying
                 ``Region.extract_table`` implementation.
 
@@ -651,6 +987,16 @@ class FlowRegion:
             A TableResult object containing the aggregated table data.  Rows returned from
             consecutive constituent regions are appended in document order.  If
             no tables are detected in any region, an empty TableResult is returned.
+
+        stitch_rows parameter:
+            Controls whether the first rows of subsequent segments/regions should be merged
+            into the previous row (to handle spill-over across page breaks).
+            Applied AFTER header removal if merge_headers is enabled.
+
+            • None (default) – no merging (behaviour identical to previous versions).
+            • Callable – custom predicate taking
+                   (prev_row, cur_row, row_idx_in_segment, segment_object) → bool.
+               Return True to merge `cur_row` into `prev_row` (default column-wise merge is used).
         """
 
         if table_settings is None:
@@ -661,9 +1007,32 @@ class FlowRegion:
         if not self.constituent_regions:
             return TableResult([])
 
+        # Resolve stitch_rows predicate -------------------------------------------------------
+        predicate: Optional[
+            Callable[[List[Optional[str]], List[Optional[str]], int, "PhysicalRegion"], bool]
+        ] = (stitch_rows if callable(stitch_rows) else None)
+
+        def _default_merge(
+            prev_row: List[Optional[str]], cur_row: List[Optional[str]]
+        ) -> List[Optional[str]]:
+            """Column-wise merge – concatenates non-empty strings with a space."""
+            from itertools import zip_longest
+
+            merged: List[Optional[str]] = []
+            for p, c in zip_longest(prev_row, cur_row, fillvalue=""):
+                if (p or "").strip() and (c or "").strip():
+                    merged.append(f"{p} {c}".strip())
+                else:
+                    merged.append((p or "") + (c or ""))
+            return merged
+
         aggregated_rows: List[List[Optional[str]]] = []
+        header_row: Optional[List[Optional[str]]] = None
+        merge_headers_enabled = False
+        headers_warned = False  # Track if we've already warned about dropping headers
+        segment_has_repeated_header = []  # Track which segments have repeated headers
 
-        for region in self.constituent_regions:
+        for region_idx, region in enumerate(self.constituent_regions):
             try:
                 region_result = region.extract_table(
                     method=method,
@@ -676,15 +1045,104 @@ class FlowRegion:
                     **kwargs,
                 )
 
-                # region_result is now a TableResult object, extract the rows
-                if region_result:
-                    aggregated_rows.extend(region_result)
+                # Convert result to list of rows
+                if not region_result:
+                    continue
+
+                if isinstance(region_result, TableResult):
+                    segment_rows = list(region_result)
+                else:
+                    segment_rows = list(region_result)
+
+                # Handle header detection and merging for multi-page tables
+                if region_idx == 0:
+                    # First segment: capture potential header row
+                    if segment_rows:
+                        header_row = segment_rows[0]
+                        # Determine if we should merge headers
+                        if merge_headers is None:
+                            # Auto-detect: we'll check all subsequent segments
+                            merge_headers_enabled = False  # Will be determined later
+                        else:
+                            merge_headers_enabled = merge_headers
+                        # Track that first segment exists (for consistency checking)
+                        segment_has_repeated_header.append(False)  # First segment doesn't "repeat"
+                elif region_idx == 1 and merge_headers is None:
+                    # Auto-detection: check if first row of second segment matches header
+                    has_header = segment_rows and header_row and segment_rows[0] == header_row
+                    segment_has_repeated_header.append(has_header)
+
+                    if has_header:
+                        merge_headers_enabled = True
+                        # Remove the detected repeated header from this segment
+                        segment_rows = segment_rows[1:]
+                        if not headers_warned:
+                            warnings.warn(
+                                "Detected repeated headers in multi-page table. Merging by removing "
+                                "repeated headers from subsequent pages.",
+                                UserWarning,
+                                stacklevel=2,
+                            )
+                            headers_warned = True
+                    else:
+                        merge_headers_enabled = False
+                elif region_idx > 1:
+                    # Check consistency: all segments should have same pattern
+                    has_header = segment_rows and header_row and segment_rows[0] == header_row
+                    segment_has_repeated_header.append(has_header)
+
+                    # Remove header if merging is enabled and header is present
+                    if merge_headers_enabled and has_header:
+                        segment_rows = segment_rows[1:]
+                elif region_idx > 0 and merge_headers_enabled:
+                    # Explicit merge_headers=True: remove headers from subsequent segments
+                    if segment_rows and header_row and segment_rows[0] == header_row:
+                        segment_rows = segment_rows[1:]
+                        if not headers_warned:
+                            warnings.warn(
+                                "Removing repeated headers from multi-page table during merge.",
+                                UserWarning,
+                                stacklevel=2,
+                            )
+                            headers_warned = True
+
+                # Process remaining rows with stitch_rows logic
+                for row_idx, row in enumerate(segment_rows):
+                    if (
+                        predicate is not None
+                        and aggregated_rows
+                        and predicate(aggregated_rows[-1], row, row_idx, region)
+                    ):
+                        # Merge with previous row
+                        aggregated_rows[-1] = _default_merge(aggregated_rows[-1], row)
+                    else:
+                        aggregated_rows.append(row)
             except Exception as e:
                 logger.error(
                     f"FlowRegion.extract_table: Error extracting table from constituent region {region}: {e}",
                     exc_info=True,
                 )
 
+        # Check for inconsistent header patterns after processing all segments
+        if merge_headers is None and len(segment_has_repeated_header) > 2:
+            # During auto-detection, check for consistency across all segments
+            expected_pattern = segment_has_repeated_header[1]  # Pattern from second segment
+            for seg_idx, has_header in enumerate(segment_has_repeated_header[2:], 2):
+                if has_header != expected_pattern:
+                    # Inconsistent pattern detected
+                    segments_with_headers = [
+                        i for i, has_h in enumerate(segment_has_repeated_header[1:], 1) if has_h
+                    ]
+                    segments_without_headers = [
+                        i for i, has_h in enumerate(segment_has_repeated_header[1:], 1) if not has_h
+                    ]
+                    raise ValueError(
+                        f"Inconsistent header pattern in multi-page table: "
+                        f"segments {segments_with_headers} have repeated headers, "
+                        f"but segments {segments_without_headers} do not. "
+                        f"All segments must have the same header pattern for reliable merging."
+                    )
+
         return TableResult(aggregated_rows)
 
     def extract_tables(
@@ -751,3 +1209,39 @@ class FlowRegion:
         This is an alias for normalized_type.
         """
         return self.normalized_type
+
+    def get_highlight_specs(self) -> List[Dict[str, Any]]:
+        """
+        Get highlight specifications for all constituent regions.
+
+        This implements the highlighting protocol for FlowRegions, returning
+        specs for each constituent region so they can be highlighted on their
+        respective pages.
+
+        Returns:
+            List of highlight specification dictionaries, one for each
+            constituent region.
+        """
+        specs = []
+
+        for region in self.constituent_regions:
+            if not hasattr(region, "page") or region.page is None:
+                continue
+
+            if not hasattr(region, "bbox") or region.bbox is None:
+                continue
+
+            spec = {
+                "page": region.page,
+                "page_index": region.page.index if hasattr(region.page, "index") else 0,
+                "bbox": region.bbox,
+                "element": region,  # Reference to the constituent region
+            }
+
+            # Add polygon if available
+            if hasattr(region, "polygon") and hasattr(region, "has_polygon") and region.has_polygon:
+                spec["polygon"] = region.polygon
+
+            specs.append(spec)
+
+        return specs