natural-pdf 0.1.40__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"]:
+    def highlights(self, show: bool = False) -> "HighlightContext":
         """
-        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.
+        Create a highlight context for accumulating highlights.
 
-        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.
+        This allows for clean syntax to show multiple highlight groups:
 
-        Returns:
-            PIL Image of the rendered pages with highlighted regions, or None if rendering fails.
-        """
-        if not self.constituent_regions:
-            logger.info("FlowRegion.show() called with no constituent regions.")
-            return None
+        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()
 
-        # 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.")
-
-        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
+        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
 
-        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"] = []
-
-        # 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]
-
-        # 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.")
+        Args:
+            show: If True, automatically show highlights when exiting context
 
-            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.")
+        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_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."""
@@ -637,6 +961,7 @@ class FlowRegion:
         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.
@@ -650,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.
 
@@ -661,6 +991,7 @@ class FlowRegion:
         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
@@ -679,9 +1010,11 @@ class FlowRegion:
         # Resolve stitch_rows predicate -------------------------------------------------------
         predicate: Optional[
             Callable[[List[Optional[str]], List[Optional[str]], int, "PhysicalRegion"], bool]
-        ] = stitch_rows if callable(stitch_rows) else None
+        ] = (stitch_rows if callable(stitch_rows) else None)
 
-        def _default_merge(prev_row: List[Optional[str]], cur_row: List[Optional[str]]) -> List[Optional[str]]:
+        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
 
@@ -694,6 +1027,10 @@ class FlowRegion:
             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_idx, region in enumerate(self.constituent_regions):
             try:
@@ -717,6 +1054,59 @@ class FlowRegion:
                 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
@@ -733,6 +1123,26 @@ class FlowRegion:
                     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(
@@ -799,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