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

natural_pdf/analyzers/guides.py

@@ -8,17 +8,20 @@ from typing import TYPE_CHECKING, Any, Dict, List, Literal, Optional, Tuple, Uni
 import numpy as np
 from PIL import Image, ImageDraw
 
+from natural_pdf.utils.layout import merge_bboxes
+
 if TYPE_CHECKING:
     from natural_pdf.core.page import Page
     from natural_pdf.elements.base import Element
     from natural_pdf.elements.collections import ElementCollection
     from natural_pdf.elements.region import Region
+    from natural_pdf.flows.region import FlowRegion
 
 logger = logging.getLogger(__name__)
 
 
 def _normalize_markers(
-    markers: Union[str, List[str], "ElementCollection", None], obj: Union["Page", "Region"]
+    markers: Union[str, List[str], "ElementCollection", None], obj: Union["Page", "Region", "FlowRegion"]
 ) -> List[str]:
     """
     Normalize markers parameter to a list of text strings for guide creation.
@@ -37,6 +40,21 @@ def _normalize_markers(
     if markers is None:
         return []
 
+    # Handle FlowRegion by collecting markers from all constituent regions
+    if hasattr(obj, "constituent_regions"):
+        all_markers = []
+        for region in obj.constituent_regions:
+            region_markers = _normalize_markers(markers, region)
+            all_markers.extend(region_markers)
+        # Remove duplicates while preserving order
+        seen = set()
+        unique_markers = []
+        for m in all_markers:
+            if m not in seen:
+                seen.add(m)
+                unique_markers.append(m)
+        return unique_markers
+
     if isinstance(markers, str):
         # Single selector or text string
         if markers.startswith(("text", "region", "line", "rect", "blob", "image")):
@@ -115,7 +133,7 @@ class GuidesList(UserList):
     def from_content(
         self,
         markers: Union[str, List[str], "ElementCollection", None],
-        obj: Optional[Union["Page", "Region"]] = None,
+        obj: Optional[Union["Page", "Region", "FlowRegion"]] = None,
         align: Literal["left", "right", "center", "between"] = "left",
         outer: bool = True,
         tolerance: float = 5,
@@ -131,7 +149,7 @@ class GuidesList(UserList):
                 - List[str]: list of selectors or literal text strings
                 - ElementCollection: collection of elements to extract text from
                 - None: no markers
-            obj: Page/Region to search (uses parent's context if None)
+            obj: Page/Region/FlowRegion to search (uses parent's context if None)
             align: How to align guides relative to found elements
             outer: Whether to add outer boundary guides
             tolerance: Tolerance for snapping to element edges
@@ -143,6 +161,88 @@ class GuidesList(UserList):
         if target_obj is None:
             raise ValueError("No object provided and no context available")
 
+        # Check if parent is in flow mode
+        if self._parent.is_flow_region:
+            # Create guides across all constituent regions
+            all_guides = []
+            for region in self._parent.context.constituent_regions:
+                # Normalize markers for this region
+                marker_texts = _normalize_markers(markers, region)
+                
+                # Create guides for this region
+                region_guides = Guides.from_content(
+                    obj=region,
+                    axis=self._axis,
+                    markers=marker_texts,
+                    align=align,
+                    outer=outer,
+                    tolerance=tolerance,
+                )
+                
+                # Collect guides from this region
+                if self._axis == "vertical":
+                    all_guides.extend(region_guides.vertical)
+                else:
+                    all_guides.extend(region_guides.horizontal)
+            
+            # Update parent's flow guides structure
+            if append:
+                # Append to existing
+                existing = [coord for coord, _ in 
+                           (self._parent._unified_vertical if self._axis == "vertical" 
+                            else self._parent._unified_horizontal)]
+                all_guides = existing + all_guides
+            
+            # Remove duplicates and sort
+            unique_guides = sorted(list(set(all_guides)))
+            
+            # Clear and rebuild unified view
+            if self._axis == "vertical":
+                self._parent._unified_vertical = []
+                for coord in unique_guides:
+                    # Find which region(s) this guide belongs to
+                    for region in self._parent.context.constituent_regions:
+                        if hasattr(region, "bbox"):
+                            x0, _, x1, _ = region.bbox
+                            if x0 <= coord <= x1:
+                                self._parent._unified_vertical.append((coord, region))
+                                break
+                self._parent._vertical_cache = None
+                self.data = unique_guides
+            else:
+                self._parent._unified_horizontal = []
+                for coord in unique_guides:
+                    # Find which region(s) this guide belongs to
+                    for region in self._parent.context.constituent_regions:
+                        if hasattr(region, "bbox"):
+                            _, y0, _, y1 = region.bbox
+                            if y0 <= coord <= y1:
+                                self._parent._unified_horizontal.append((coord, region))
+                                break
+                self._parent._horizontal_cache = None
+                self.data = unique_guides
+            
+            # Update per-region guides
+            for region in self._parent.context.constituent_regions:
+                region_verticals = []
+                region_horizontals = []
+                
+                for coord, r in self._parent._unified_vertical:
+                    if r == region:
+                        region_verticals.append(coord)
+                        
+                for coord, r in self._parent._unified_horizontal:
+                    if r == region:
+                        region_horizontals.append(coord)
+                
+                self._parent._flow_guides[region] = (
+                    sorted(region_verticals),
+                    sorted(region_horizontals)
+                )
+            
+            return self._parent
+        
+        # Original single-region logic
         # Normalize markers to list of text strings
         marker_texts = _normalize_markers(markers, target_obj)
 
@@ -181,7 +281,7 @@ class GuidesList(UserList):
 
     def from_lines(
         self,
-        obj: Optional[Union["Page", "Region"]] = None,
+        obj: Optional[Union["Page", "Region", "FlowRegion"]] = None,
         threshold: Union[float, str] = "auto",
         source_label: Optional[str] = None,
         max_lines: Optional[int] = None,
@@ -198,7 +298,7 @@ class GuidesList(UserList):
         Create guides from detected line elements.
 
         Args:
-            obj: Page/Region to search (uses parent's context if None)
+            obj: Page/Region/FlowRegion to search (uses parent's context if None)
             threshold: Line detection threshold ('auto' or float 0.0-1.0)
             source_label: Filter lines by source label (for vector method)
             max_lines: Maximum lines to use (alias: n)
@@ -236,6 +336,90 @@ class GuidesList(UserList):
             axis_key = "min_gap_h" if self._axis == "horizontal" else "min_gap_v"
             detect_kwargs.setdefault(axis_key, min_gap)
 
+        # Check if parent is in flow mode
+        if self._parent.is_flow_region:
+            # Create guides across all constituent regions
+            all_guides = []
+            
+            for region in self._parent.context.constituent_regions:
+                # Create guides for this specific region
+                region_guides = Guides.from_lines(
+                    obj=region,
+                    axis=self._axis,
+                    threshold=threshold,
+                    source_label=source_label,
+                    max_lines_h=max_lines_h,
+                    max_lines_v=max_lines_v,
+                    outer=outer,
+                    detection_method=detection_method,
+                    resolution=resolution,
+                    **detect_kwargs
+                )
+                
+                # Collect guides from this region
+                if self._axis == "vertical":
+                    all_guides.extend(region_guides.vertical)
+                else:
+                    all_guides.extend(region_guides.horizontal)
+            
+            # Update parent's flow guides structure
+            if append:
+                # Append to existing
+                existing = [coord for coord, _ in 
+                           (self._parent._unified_vertical if self._axis == "vertical" 
+                            else self._parent._unified_horizontal)]
+                all_guides = existing + all_guides
+            
+            # Remove duplicates and sort
+            unique_guides = sorted(list(set(all_guides)))
+            
+            # Clear and rebuild unified view
+            if self._axis == "vertical":
+                self._parent._unified_vertical = []
+                for coord in unique_guides:
+                    # Find which region(s) this guide belongs to
+                    for region in self._parent.context.constituent_regions:
+                        if hasattr(region, "bbox"):
+                            x0, _, x1, _ = region.bbox
+                            if x0 <= coord <= x1:
+                                self._parent._unified_vertical.append((coord, region))
+                                break
+                self._parent._vertical_cache = None
+                self.data = unique_guides
+            else:
+                self._parent._unified_horizontal = []
+                for coord in unique_guides:
+                    # Find which region(s) this guide belongs to
+                    for region in self._parent.context.constituent_regions:
+                        if hasattr(region, "bbox"):
+                            _, y0, _, y1 = region.bbox
+                            if y0 <= coord <= y1:
+                                self._parent._unified_horizontal.append((coord, region))
+                                break
+                self._parent._horizontal_cache = None
+                self.data = unique_guides
+            
+            # Update per-region guides
+            for region in self._parent.context.constituent_regions:
+                region_verticals = []
+                region_horizontals = []
+                
+                for coord, r in self._parent._unified_vertical:
+                    if r == region:
+                        region_verticals.append(coord)
+                        
+                for coord, r in self._parent._unified_horizontal:
+                    if r == region:
+                        region_horizontals.append(coord)
+                
+                self._parent._flow_guides[region] = (
+                    sorted(region_verticals),
+                    sorted(region_horizontals)
+                )
+            
+            return self._parent
+
+        # Original single-region logic
         # Create guides for this axis
         new_guides = Guides.from_lines(
             obj=target_obj,
@@ -274,14 +458,14 @@ class GuidesList(UserList):
         return self._parent
 
     def from_whitespace(
-        self, obj: Optional[Union["Page", "Region"]] = None, min_gap: float = 10,
+        self, obj: Optional[Union["Page", "Region", "FlowRegion"]] = None, min_gap: float = 10,
         *, append: bool = False
     ) -> "Guides":
         """
         Create guides from whitespace gaps.
 
         Args:
-            obj: Page/Region to analyze (uses parent's context if None)
+            obj: Page/Region/FlowRegion to analyze (uses parent's context if None)
             min_gap: Minimum gap size to consider
 
         Returns:
@@ -291,6 +475,83 @@ class GuidesList(UserList):
         if target_obj is None:
             raise ValueError("No object provided and no context available")
 
+        # Check if parent is in flow mode
+        if self._parent.is_flow_region:
+            # Create guides across all constituent regions
+            all_guides = []
+            
+            for region in self._parent.context.constituent_regions:
+                # Create guides for this specific region
+                region_guides = Guides.from_whitespace(
+                    obj=region,
+                    axis=self._axis,
+                    min_gap=min_gap
+                )
+                
+                # Collect guides from this region
+                if self._axis == "vertical":
+                    all_guides.extend(region_guides.vertical)
+                else:
+                    all_guides.extend(region_guides.horizontal)
+            
+            # Update parent's flow guides structure
+            if append:
+                # Append to existing
+                existing = [coord for coord, _ in 
+                           (self._parent._unified_vertical if self._axis == "vertical" 
+                            else self._parent._unified_horizontal)]
+                all_guides = existing + all_guides
+            
+            # Remove duplicates and sort
+            unique_guides = sorted(list(set(all_guides)))
+            
+            # Clear and rebuild unified view
+            if self._axis == "vertical":
+                self._parent._unified_vertical = []
+                for coord in unique_guides:
+                    # Find which region(s) this guide belongs to
+                    for region in self._parent.context.constituent_regions:
+                        if hasattr(region, "bbox"):
+                            x0, _, x1, _ = region.bbox
+                            if x0 <= coord <= x1:
+                                self._parent._unified_vertical.append((coord, region))
+                                break
+                self._parent._vertical_cache = None
+                self.data = unique_guides
+            else:
+                self._parent._unified_horizontal = []
+                for coord in unique_guides:
+                    # Find which region(s) this guide belongs to
+                    for region in self._parent.context.constituent_regions:
+                        if hasattr(region, "bbox"):
+                            _, y0, _, y1 = region.bbox
+                            if y0 <= coord <= y1:
+                                self._parent._unified_horizontal.append((coord, region))
+                                break
+                self._parent._horizontal_cache = None
+                self.data = unique_guides
+            
+            # Update per-region guides
+            for region in self._parent.context.constituent_regions:
+                region_verticals = []
+                region_horizontals = []
+                
+                for coord, r in self._parent._unified_vertical:
+                    if r == region:
+                        region_verticals.append(coord)
+                        
+                for coord, r in self._parent._unified_horizontal:
+                    if r == region:
+                        region_horizontals.append(coord)
+                
+                self._parent._flow_guides[region] = (
+                    sorted(region_verticals),
+                    sorted(region_horizontals)
+                )
+            
+            return self._parent
+
+        # Original single-region logic
         # Create guides for this axis
         new_guides = Guides.from_whitespace(obj=target_obj, axis=self._axis, min_gap=min_gap)
 
@@ -618,9 +879,9 @@ class Guides:
 
     def __init__(
         self,
-        verticals: Optional[Union[List[float], "Page", "Region"]] = None,
+        verticals: Optional[Union[List[float], "Page", "Region", "FlowRegion"]] = None,
         horizontals: Optional[List[float]] = None,
-        context: Optional[Union["Page", "Region"]] = None,
+        context: Optional[Union["Page", "Region", "FlowRegion"]] = None,
         bounds: Optional[Tuple[float, float, float, float]] = None,
         relative: bool = False,
         snap_behavior: Literal["raise", "warn", "ignore"] = "warn",
@@ -629,21 +890,21 @@ class Guides:
         Initialize a Guides object.
 
         Args:
-            verticals: List of x-coordinates for vertical guides, or a Page/Region as context
+            verticals: List of x-coordinates for vertical guides, or a Page/Region/FlowRegion as context
             horizontals: List of y-coordinates for horizontal guides
-            context: Page or Region object these guides were created from
+            context: Page, Region, or FlowRegion object these guides were created from
             bounds: Bounding box (x0, top, x1, bottom) if context not provided
             relative: Whether coordinates are relative (0-1) or absolute
             snap_behavior: How to handle snapping conflicts ('raise', 'warn', or 'ignore')
         """
-        # Handle Guides(page) shorthand
+        # Handle Guides(page) or Guides(flow_region) shorthand
         if (
             verticals is not None
             and not isinstance(verticals, (list, tuple))
             and horizontals is None
             and context is None
         ):
-            # First argument is a page/region, not coordinates
+            # First argument is a page/region/flow_region, not coordinates
             context = verticals
             verticals = None
 
@@ -652,6 +913,19 @@ class Guides:
         self.relative = relative
         self.snap_behavior = snap_behavior
 
+        # Check if we're dealing with a FlowRegion
+        self.is_flow_region = hasattr(context, "constituent_regions")
+        
+        # If FlowRegion, we'll store guides per constituent region
+        if self.is_flow_region:
+            self._flow_guides: Dict["Region", Tuple[List[float], List[float]]] = {}
+            # For unified view across all regions
+            self._unified_vertical: List[Tuple[float, "Region"]] = []
+            self._unified_horizontal: List[Tuple[float, "Region"]] = []
+            # Cache for sorted unique coordinates
+            self._vertical_cache: Optional[List[float]] = None
+            self._horizontal_cache: Optional[List[float]] = None
+
         # Initialize with GuidesList instances
         self._vertical = GuidesList(self, "vertical", sorted([float(x) for x in (verticals or [])]))
         self._horizontal = GuidesList(
@@ -683,11 +957,26 @@ class Guides:
     @property
     def vertical(self) -> GuidesList:
         """Get vertical guide coordinates."""
+        if self.is_flow_region and self._vertical_cache is not None:
+            # Return cached unified view
+            self._vertical.data = self._vertical_cache
+        elif self.is_flow_region and self._unified_vertical:
+            # Build unified view from flow guides
+            all_verticals = []
+            for coord, region in self._unified_vertical:
+                all_verticals.append(coord)
+            # Remove duplicates and sort
+            self._vertical_cache = sorted(list(set(all_verticals)))
+            self._vertical.data = self._vertical_cache
         return self._vertical
 
     @vertical.setter
     def vertical(self, value: Union[List[float], "Guides", None]):
         """Set vertical guides from a list of coordinates or another Guides object."""
+        if self.is_flow_region:
+            # Invalidate cache when setting new values
+            self._vertical_cache = None
+            
         if value is None:
             self._vertical.data = []
         elif isinstance(value, Guides):
@@ -710,11 +999,26 @@ class Guides:
     @property
     def horizontal(self) -> GuidesList:
         """Get horizontal guide coordinates."""
+        if self.is_flow_region and self._horizontal_cache is not None:
+            # Return cached unified view
+            self._horizontal.data = self._horizontal_cache
+        elif self.is_flow_region and self._unified_horizontal:
+            # Build unified view from flow guides
+            all_horizontals = []
+            for coord, region in self._unified_horizontal:
+                all_horizontals.append(coord)
+            # Remove duplicates and sort
+            self._horizontal_cache = sorted(list(set(all_horizontals)))
+            self._horizontal.data = self._horizontal_cache
         return self._horizontal
 
     @horizontal.setter
     def horizontal(self, value: Union[List[float], "Guides", None]):
         """Set horizontal guides from a list of coordinates or another Guides object."""
+        if self.is_flow_region:
+            # Invalidate cache when setting new values
+            self._horizontal_cache = None
+            
         if value is None:
             self._horizontal.data = []
         elif isinstance(value, Guides):
@@ -821,7 +1125,7 @@ class Guides:
     @classmethod
     def from_lines(
         cls,
-        obj: Union["Page", "Region"],
+        obj: Union["Page", "Region", "FlowRegion"],
         axis: Literal["vertical", "horizontal", "both"] = "both",
         threshold: Union[float, str] = "auto",
         source_label: Optional[str] = None,
@@ -836,7 +1140,7 @@ class Guides:
         Create guides from detected line elements.
 
         Args:
-            obj: Page or Region to detect lines from
+            obj: Page, Region, or FlowRegion to detect lines from
             axis: Which orientations to detect
             threshold: Detection threshold ('auto' or float 0.0-1.0) - used for pixel detection
             source_label: Filter for line source (vector method) or label for detected lines (pixel method)
@@ -856,6 +1160,45 @@ class Guides:
         Returns:
             New Guides object with detected line positions
         """
+        # Handle FlowRegion
+        if hasattr(obj, "constituent_regions"):
+            guides = cls(context=obj)
+            
+            # Process each constituent region
+            for region in obj.constituent_regions:
+                # Create guides for this specific region
+                region_guides = cls.from_lines(
+                    region,
+                    axis=axis,
+                    threshold=threshold,
+                    source_label=source_label,
+                    max_lines_h=max_lines_h,
+                    max_lines_v=max_lines_v,
+                    outer=outer,
+                    detection_method=detection_method,
+                    resolution=resolution,
+                    **detect_kwargs
+                )
+                
+                # Store in flow guides
+                guides._flow_guides[region] = (
+                    list(region_guides.vertical),
+                    list(region_guides.horizontal)
+                )
+                
+                # Add to unified view
+                for v in region_guides.vertical:
+                    guides._unified_vertical.append((v, region))
+                for h in region_guides.horizontal:
+                    guides._unified_horizontal.append((h, region))
+            
+            # Invalidate caches to force rebuild on next access
+            guides._vertical_cache = None
+            guides._horizontal_cache = None
+            
+            return guides
+        
+        # Original single-region logic follows...
         # Get bounds for potential outer guides
         if hasattr(obj, "bbox"):
             bounds = obj.bbox
@@ -1028,7 +1371,7 @@ class Guides:
     @classmethod
     def from_content(
         cls,
-        obj: Union["Page", "Region"],
+        obj: Union["Page", "Region", "FlowRegion"],
         axis: Literal["vertical", "horizontal"] = "vertical",
         markers: Union[str, List[str], "ElementCollection", None] = None,
         align: Literal["left", "right", "center", "between"] = "left",
@@ -1039,7 +1382,7 @@ class Guides:
         Create guides based on text content positions.
 
         Args:
-            obj: Page or Region to search for content
+            obj: Page, Region, or FlowRegion to search for content
             axis: Whether to create vertical or horizontal guides
             markers: Content to search for. Can be:
                 - str: single selector (e.g., 'text:contains("Name")') or literal text
@@ -1053,6 +1396,41 @@ class Guides:
         Returns:
             New Guides object aligned to text content
         """
+        # Handle FlowRegion
+        if hasattr(obj, "constituent_regions"):
+            guides = cls(context=obj)
+            
+            # Process each constituent region
+            for region in obj.constituent_regions:
+                # Create guides for this specific region
+                region_guides = cls.from_content(
+                    region,
+                    axis=axis,
+                    markers=markers,
+                    align=align,
+                    outer=outer,
+                    tolerance=tolerance
+                )
+                
+                # Store in flow guides
+                guides._flow_guides[region] = (
+                    list(region_guides.vertical),
+                    list(region_guides.horizontal)
+                )
+                
+                # Add to unified view
+                for v in region_guides.vertical:
+                    guides._unified_vertical.append((v, region))
+                for h in region_guides.horizontal:
+                    guides._unified_horizontal.append((h, region))
+            
+            # Invalidate caches
+            guides._vertical_cache = None
+            guides._horizontal_cache = None
+            
+            return guides
+        
+        # Original single-region logic follows...
         guides_coords = []
         bounds = None
 
@@ -1141,7 +1519,7 @@ class Guides:
     @classmethod
     def from_whitespace(
         cls,
-        obj: Union["Page", "Region"],
+        obj: Union["Page", "Region", "FlowRegion"],
         axis: Literal["vertical", "horizontal", "both"] = "both",
         min_gap: float = 10,
     ) -> "Guides":
@@ -1212,6 +1590,117 @@ class Guides:
             logger.warning("No context available for whitespace detection")
             return self
 
+        # Handle FlowRegion case - collect all text elements across regions
+        if self.is_flow_region:
+            all_text_elements = []
+            region_bounds = {}
+            
+            for region in self.context.constituent_regions:
+                # Get text elements from this region
+                if hasattr(region, "find_all"):
+                    try:
+                        text_elements = region.find_all("text", apply_exclusions=False)
+                        elements = text_elements.elements if hasattr(text_elements, "elements") else text_elements
+                        all_text_elements.extend(elements)
+                        
+                        # Store bounds for each region
+                        if hasattr(region, "bbox"):
+                            region_bounds[region] = region.bbox
+                        elif hasattr(region, "x0"):
+                            region_bounds[region] = (region.x0, region.top, region.x1, region.bottom)
+                    except Exception as e:
+                        logger.warning(f"Error getting text elements from region: {e}")
+            
+            if not all_text_elements:
+                logger.warning("No text elements found across flow regions for whitespace detection")
+                return self
+            
+            # Find whitespace gaps across all regions
+            if axis == "vertical":
+                gaps = self._find_vertical_whitespace_gaps(all_text_elements, min_gap, threshold)
+                # Get all vertical guides across regions
+                all_guides = []
+                guide_to_region_map = {}  # Map guide coordinate to its original list of regions
+                for coord, region in self._unified_vertical:
+                    all_guides.append(coord)
+                    guide_to_region_map.setdefault(coord, []).append(region)
+                    
+                if gaps and all_guides:
+                    # Keep a copy of original guides to maintain mapping
+                    original_guides = all_guides.copy()
+                    
+                    # Snap guides to gaps
+                    self._snap_guides_to_gaps(all_guides, gaps, axis)
+                    
+                    # Update the unified view with snapped positions
+                    self._unified_vertical = []
+                    for i, new_coord in enumerate(all_guides):
+                        # Find the original region for this guide using the original position
+                        original_coord = original_guides[i]
+                        # A guide might be associated with multiple regions, add them all
+                        regions = guide_to_region_map.get(original_coord, [])
+                        for region in regions:
+                            self._unified_vertical.append((new_coord, region))
+                    
+                    # Update individual region guides
+                    for region in self._flow_guides:
+                        region_verticals = []
+                        for coord, r in self._unified_vertical:
+                            if r == region:
+                                region_verticals.append(coord)
+                        self._flow_guides[region] = (
+                            sorted(list(set(region_verticals))), # Deduplicate here
+                            self._flow_guides[region][1]
+                        )
+                    
+                    # Invalidate cache
+                    self._vertical_cache = None
+                    
+            elif axis == "horizontal":
+                gaps = self._find_horizontal_whitespace_gaps(all_text_elements, min_gap, threshold)
+                # Get all horizontal guides across regions
+                all_guides = []
+                guide_to_region_map = {}  # Map guide coordinate to its original list of regions
+                for coord, region in self._unified_horizontal:
+                    all_guides.append(coord)
+                    guide_to_region_map.setdefault(coord, []).append(region)
+                    
+                if gaps and all_guides:
+                    # Keep a copy of original guides to maintain mapping
+                    original_guides = all_guides.copy()
+                    
+                    # Snap guides to gaps
+                    self._snap_guides_to_gaps(all_guides, gaps, axis)
+                    
+                    # Update the unified view with snapped positions
+                    self._unified_horizontal = []
+                    for i, new_coord in enumerate(all_guides):
+                        # Find the original region for this guide using the original position
+                        original_coord = original_guides[i]
+                        regions = guide_to_region_map.get(original_coord, [])
+                        for region in regions:
+                            self._unified_horizontal.append((new_coord, region))
+                    
+                    # Update individual region guides
+                    for region in self._flow_guides:
+                        region_horizontals = []
+                        for coord, r in self._unified_horizontal:
+                            if r == region:
+                                region_horizontals.append(coord)
+                        self._flow_guides[region] = (
+                            self._flow_guides[region][0],
+                            sorted(list(set(region_horizontals))) # Deduplicate here
+                        )
+                    
+                    # Invalidate cache
+                    self._horizontal_cache = None
+            
+            else:
+                raise ValueError("axis must be 'vertical' or 'horizontal'")
+            
+            return self
+        
+        # Original single-region logic
         # Get elements for trough detection
         text_elements = self._get_text_elements()
         if not text_elements:
@@ -1303,14 +1792,47 @@ class Guides:
         combined_verticals = sorted([float(x) for x in set(self.vertical + other.vertical)])
         combined_horizontals = sorted([float(y) for y in set(self.horizontal + other.horizontal)])
 
-        # Use context from self if available
-        return Guides(
+        # Handle FlowRegion context merging
+        new_context = self.context or other.context
+        
+        # If both are flow regions, we might need a more complex merge,
+        # but for now, just picking one context is sufficient.
+        
+        # Create the new Guides object
+        new_guides = Guides(
             verticals=combined_verticals,
             horizontals=combined_horizontals,
-            context=self.context or other.context,
+            context=new_context,
             bounds=self.bounds or other.bounds,
         )
 
+        # If the new context is a FlowRegion, we need to rebuild the flow-related state
+        if new_guides.is_flow_region:
+            # Re-initialize flow guides from both sources
+            # This is a simplification; a true merge would be more complex.
+            # For now, we combine the flow_guides dictionaries.
+            if hasattr(self, "_flow_guides"):
+                new_guides._flow_guides.update(self._flow_guides)
+            if hasattr(other, "_flow_guides"):
+                new_guides._flow_guides.update(other._flow_guides)
+            
+            # Re-initialize unified views
+            if hasattr(self, "_unified_vertical"):
+                new_guides._unified_vertical.extend(self._unified_vertical)
+            if hasattr(other, "_unified_vertical"):
+                new_guides._unified_vertical.extend(other._unified_vertical)
+
+            if hasattr(self, "_unified_horizontal"):
+                new_guides._unified_horizontal.extend(self._unified_horizontal)
+            if hasattr(other, "_unified_horizontal"):
+                new_guides._unified_horizontal.extend(other._unified_horizontal)
+                
+            # Invalidate caches to force rebuild
+            new_guides._vertical_cache = None
+            new_guides._horizontal_cache = None
+
+        return new_guides
+
     def show(self, on=None, **kwargs):
         """
         Display the guides overlaid on a page or region.
@@ -1324,6 +1846,122 @@ class Guides:
         Returns:
             PIL Image with guides drawn on it.
         """
+        # Handle FlowRegion case
+        if self.is_flow_region and (on is None or on == self.context):
+            if not self._flow_guides:
+                raise ValueError("No guides to show for FlowRegion")
+            
+            # Get stacking parameters from kwargs or use defaults
+            stack_direction = kwargs.get('stack_direction', 'vertical')
+            stack_gap = kwargs.get('stack_gap', 5)
+            stack_background_color = kwargs.get('stack_background_color', (255, 255, 255))
+            
+            # First, render all constituent regions without guides to get base images
+            base_images = []
+            region_infos = []  # Store region info for guide coordinate mapping
+            
+            for region in self.context.constituent_regions:
+                try:
+                    # Render region without guides
+                    img = region.to_image(**kwargs)
+                    if img:
+                        base_images.append(img)
+                        
+                        # Calculate scaling factors for this region
+                        scale_x = img.width / region.width
+                        scale_y = img.height / region.height
+                        
+                        region_infos.append({
+                            'region': region,
+                            'img_width': img.width,
+                            'img_height': img.height,
+                            'scale_x': scale_x,
+                            'scale_y': scale_y,
+                            'pdf_x0': region.x0,
+                            'pdf_top': region.top,
+                            'pdf_x1': region.x1,
+                            'pdf_bottom': region.bottom
+                        })
+                except Exception as e:
+                    logger.warning(f"Failed to render region: {e}")
+            
+            if not base_images:
+                raise ValueError("Failed to render any images for FlowRegion")
+            
+            # Calculate final canvas size based on stacking direction
+            if stack_direction == "vertical":
+                final_width = max(img.width for img in base_images)
+                final_height = (
+                    sum(img.height for img in base_images)
+                    + (len(base_images) - 1) * stack_gap
+                )
+            else:  # horizontal
+                final_width = (
+                    sum(img.width for img in base_images)
+                    + (len(base_images) - 1) * stack_gap
+                )
+                final_height = max(img.height for img in base_images)
+            
+            # Create unified canvas
+            canvas = Image.new("RGB", (final_width, final_height), stack_background_color)
+            draw = ImageDraw.Draw(canvas)
+            
+            # Paste base images and track positions
+            region_positions = []  # (region_info, paste_x, paste_y)
+            
+            if stack_direction == "vertical":
+                current_y = 0
+                for i, (img, info) in enumerate(zip(base_images, region_infos)):
+                    paste_x = (final_width - img.width) // 2  # Center horizontally
+                    canvas.paste(img, (paste_x, current_y))
+                    region_positions.append((info, paste_x, current_y))
+                    current_y += img.height + stack_gap
+            else:  # horizontal
+                current_x = 0
+                for i, (img, info) in enumerate(zip(base_images, region_infos)):
+                    paste_y = (final_height - img.height) // 2  # Center vertically
+                    canvas.paste(img, (current_x, paste_y))
+                    region_positions.append((info, current_x, paste_y))
+                    current_x += img.width + stack_gap
+            
+            # Now draw guides on the unified canvas
+            # Draw vertical guides (blue) - these extend through the full canvas height
+            for v_coord in self.vertical:
+                # Find which region(s) this guide intersects
+                for info, paste_x, paste_y in region_positions:
+                    if info['pdf_x0'] <= v_coord <= info['pdf_x1']:
+                        # This guide is within this region's x-bounds
+                        # Convert PDF coordinate to pixel coordinate relative to the region
+                        adjusted_x = v_coord - info['pdf_x0']
+                        pixel_x = adjusted_x * info['scale_x'] + paste_x
+                        
+                        # Draw full-height line on canvas (not clipped to region)
+                        if 0 <= pixel_x <= final_width:
+                            x_pixel = int(pixel_x)
+                            draw.line([(x_pixel, 0), (x_pixel, final_height - 1)], 
+                                    fill=(0, 0, 255, 200), width=2)
+                        break  # Only draw once per guide
+            
+            # Draw horizontal guides (red) - these extend through the full canvas width
+            for h_coord in self.horizontal:
+                # Find which region(s) this guide intersects
+                for info, paste_x, paste_y in region_positions:
+                    if info['pdf_top'] <= h_coord <= info['pdf_bottom']:
+                        # This guide is within this region's y-bounds
+                        # Convert PDF coordinate to pixel coordinate relative to the region
+                        adjusted_y = h_coord - info['pdf_top']
+                        pixel_y = adjusted_y * info['scale_y'] + paste_y
+                        
+                        # Draw full-width line on canvas (not clipped to region)
+                        if 0 <= pixel_y <= final_height:
+                            y_pixel = int(pixel_y)
+                            draw.line([(0, y_pixel), (final_width - 1, y_pixel)], 
+                                    fill=(255, 0, 0, 200), width=2)
+                        break  # Only draw once per guide
+            
+            return canvas
+        
+        # Original single-region logic follows...
         # Determine what to display guides on
         target = on if on is not None else self.context
 
@@ -1950,7 +2588,9 @@ class Guides:
         source: str = "guides",
         cell_padding: float = 0.5,
         include_outer_boundaries: bool = False,
-    ) -> Dict[str, int]:
+        *,
+        multi_page: Literal["auto", True, False] = "auto",
+    ) -> Dict[str, Any]:
         """
         Create table structure (table, rows, columns, cells) from guide coordinates.
 
@@ -1959,11 +2599,331 @@ class Guides:
             source: Source label for created regions (for identification)
             cell_padding: Internal padding for cell regions in points
             include_outer_boundaries: Whether to add boundaries at edges if missing
+            multi_page: Controls multi-page table creation for FlowRegions.
+                - "auto": (default) Creates a multi-page grid if guides span pages.
+                - True: Forces creation of a multi-page grid.
+                - False: Creates separate grids for each page.
 
         Returns:
-            Dictionary with counts: {'table': 1, 'rows': N, 'columns': M, 'cells': N*M}
+            Dictionary with 'counts' and 'regions' created.
+        """
+        # Dispatch to appropriate implementation based on context and flags
+        if self.is_flow_region:
+            spans_pages = self._spans_pages()
+            if multi_page is True or (multi_page == "auto" and spans_pages):
+                return self._build_grid_multi_page(
+                    source=source,
+                    cell_padding=cell_padding,
+                    include_outer_boundaries=include_outer_boundaries,
+                )
+            else:
+                # FlowRegion context, but creating separate tables per page
+                total_counts = {"table": 0, "rows": 0, "columns": 0, "cells": 0}
+                all_regions = {"table": [], "rows": [], "columns": [], "cells": []}
+                
+                for region in self.context.constituent_regions:
+                    if region in self._flow_guides:
+                        verticals, horizontals = self._flow_guides[region]
+                        
+                        region_guides = Guides(
+                            verticals=verticals,
+                            horizontals=horizontals,
+                            context=region
+                        )
+                        
+                        try:
+                            result = region_guides._build_grid_single_page(
+                                target=region,
+                                source=source,
+                                cell_padding=cell_padding,
+                                include_outer_boundaries=include_outer_boundaries
+                            )
+                            
+                            for key in total_counts:
+                                total_counts[key] += result["counts"][key]
+                            
+                            if result["regions"]["table"]:
+                                all_regions["table"].append(result["regions"]["table"])
+                            all_regions["rows"].extend(result["regions"]["rows"])
+                            all_regions["columns"].extend(result["regions"]["columns"])
+                            all_regions["cells"].extend(result["regions"]["cells"])
+                            
+                        except Exception as e:
+                            logger.warning(f"Failed to build grid on region: {e}")
+                
+                logger.info(
+                    f"Created {total_counts['table']} tables, {total_counts['rows']} rows, "
+                    f"{total_counts['columns']} columns, and {total_counts['cells']} cells "
+                    f"from guides across {len(self._flow_guides)} regions"
+                )
+                
+                return {"counts": total_counts, "regions": all_regions}
+
+        # Fallback for single page/region
+        return self._build_grid_single_page(
+            target=target,
+            source=source,
+            cell_padding=cell_padding,
+            include_outer_boundaries=include_outer_boundaries,
+        )
+
+    def _build_grid_multi_page(
+        self,
+        source: str,
+        cell_padding: float,
+        include_outer_boundaries: bool,
+    ) -> Dict[str, Any]:
+        """Builds a single, coherent grid across multiple pages of a FlowRegion."""
+        from natural_pdf.flows.region import FlowRegion
+
+        if not self.is_flow_region or not hasattr(self.context, "flow") or not self.context.flow:
+            raise ValueError("Multi-page grid building requires a FlowRegion with a valid Flow.")
+
+        # Determine flow orientation to guide stitching
+        orientation = self._get_flow_orientation()
+
+        # Phase 1: Build physical grid on each page, clipping guides to that page's region
+        results_by_region = []
+        unified_verticals = self.vertical.data
+        unified_horizontals = self.horizontal.data
+
+        for region in self.context.constituent_regions:
+            bounds = region.bbox
+            if not bounds:
+                continue
+
+            # Clip unified guides to the current region's bounds
+            clipped_verticals = [v for v in unified_verticals if bounds[0] <= v <= bounds[2]]
+            clipped_horizontals = [h for h in unified_horizontals if bounds[1] <= h <= bounds[3]]
+
+            # Ensure the region's own boundaries are included to close off cells at page breaks
+            clipped_verticals = sorted(list(set([bounds[0], bounds[2]] + clipped_verticals)))
+            clipped_horizontals = sorted(list(set([bounds[1], bounds[3]] + clipped_horizontals)))
+            
+            if len(clipped_verticals) < 2 or len(clipped_horizontals) < 2:
+                continue # Not enough guides to form a cell
+
+            region_guides = Guides(
+                verticals=clipped_verticals,
+                horizontals=clipped_horizontals,
+                context=region,
+            )
+
+            grid_parts = region_guides._build_grid_single_page(
+                target=region,
+                source=source,
+                cell_padding=cell_padding,
+                include_outer_boundaries=False, # Boundaries are already handled
+            )
+
+            if grid_parts["counts"]["table"] > 0:
+                results_by_region.append(grid_parts)
+
+        if not results_by_region:
+            return {
+                "counts": {"table": 0, "rows": 0, "columns": 0, "cells": 0},
+                "regions": {"table": None, "rows": [], "columns": [], "cells": []},
+            }
+
+        # Phase 2: Stitch physical regions into logical FlowRegions based on orientation
+        flow = self.context.flow
+
+        # The overall table is always a FlowRegion
+        physical_tables = [res["regions"]["table"] for res in results_by_region]
+        multi_page_table = FlowRegion(
+            flow=flow, constituent_regions=physical_tables, source_flow_element=None
+        )
+        multi_page_table.source = source
+        multi_page_table.region_type = "table"
+        multi_page_table.metadata.update(
+            {"is_multi_page": True, "num_rows": self.n_rows, "num_cols": self.n_cols}
+        )
+        
+        # Initialize final region collections
+        final_rows = []
+        final_cols = []
+        final_cells = []
+
+        orientation = self._get_flow_orientation()
+
+        if orientation == "vertical":
+            # Start with all rows & cells from the first page's grid
+            if results_by_region:
+                # Make copies to modify
+                page_rows = [res["regions"]["rows"] for res in results_by_region]
+                page_cells = [res["regions"]["cells"] for res in results_by_region]
+
+                # Iterate through page breaks to merge split rows/cells
+                for i in range(len(results_by_region) - 1):
+                    region_A = self.context.constituent_regions[i]
+                    
+                    # Check if a guide exists at the boundary
+                    is_break_bounded = any(abs(h - region_A.bottom) < 0.1 for h in self.horizontal.data)
+
+                    if not is_break_bounded and page_rows[i] and page_rows[i+1]:
+                        # No guide at break -> merge last row of A with first row of B
+                        last_row_A = page_rows[i].pop(-1)
+                        first_row_B = page_rows[i+1].pop(0)
+                        
+                        merged_row = FlowRegion(flow, [last_row_A, first_row_B], source_flow_element=None)
+                        merged_row.source = source
+                        merged_row.region_type = "table_row"
+                        merged_row.metadata.update({"row_index": last_row_A.metadata.get("row_index"), "is_multi_page": True})
+                        page_rows[i].append(merged_row) # Add merged row back in place of A's last
+
+                        # Merge the corresponding cells using explicit row/col indices
+                        last_row_idx = last_row_A.metadata.get("row_index")
+                        first_row_idx = first_row_B.metadata.get("row_index")
+
+                        # Cells belonging to those rows
+                        last_cells_A = [c for c in page_cells[i] if c.metadata.get("row_index") == last_row_idx]
+                        first_cells_B = [c for c in page_cells[i+1] if c.metadata.get("row_index") == first_row_idx]
+
+                        # Remove them from their page lists
+                        page_cells[i]   = [c for c in page_cells[i]   if c.metadata.get("row_index") != last_row_idx]
+                        page_cells[i+1] = [c for c in page_cells[i+1] if c.metadata.get("row_index") != first_row_idx]
+
+                        # Sort both lists by column index to keep alignment stable
+                        last_cells_A.sort(key=lambda c: c.metadata.get("col_index", 0))
+                        first_cells_B.sort(key=lambda c: c.metadata.get("col_index", 0))
+
+                        # Pair-wise merge
+                        for cell_A, cell_B in zip(last_cells_A, first_cells_B):
+                            merged_cell = FlowRegion(flow, [cell_A, cell_B], source_flow_element=None)
+                            merged_cell.source = source
+                            merged_cell.region_type = "table_cell"
+                            merged_cell.metadata.update({
+                                "row_index": cell_A.metadata.get("row_index"),
+                                "col_index": cell_A.metadata.get("col_index"),
+                                "is_multi_page": True
+                            })
+                            page_cells[i].append(merged_cell)
+
+                # Flatten the potentially modified lists of rows and cells
+                final_rows = [row for rows_list in page_rows for row in rows_list]
+                final_cells = [cell for cells_list in page_cells for cell in cells_list]
+
+                # Stitch columns, which always span vertically
+                physical_cols_by_index = zip(*(res["regions"]["columns"] for res in results_by_region))
+                for j, physical_cols in enumerate(physical_cols_by_index):
+                    col_fr = FlowRegion(flow=flow, constituent_regions=list(physical_cols), source_flow_element=None)
+                    col_fr.source = source
+                    col_fr.region_type = "table_column"
+                    col_fr.metadata.update({"col_index": j, "is_multi_page": True})
+                    final_cols.append(col_fr)
+
+        elif orientation == "horizontal":
+             # Symmetric logic for horizontal flow (not fully implemented here for brevity)
+             # This would merge last column of A with first column of B if no vertical guide exists
+            logger.warning("Horizontal table stitching not fully implemented.")
+            final_rows = [row for res in results_by_region for row in res["regions"]["rows"]]
+            final_cols = [col for res in results_by_region for col in res["regions"]["columns"]]
+            final_cells = [cell for res in results_by_region for cell in res["regions"]["cells"]]
+        
+        else: # Unknown orientation, just flatten everything
+            final_rows = [row for res in results_by_region for row in res["regions"]["rows"]]
+            final_cols = [col for res in results_by_region for col in res["regions"]["columns"]]
+            final_cells = [cell for res in results_by_region for cell in res["regions"]["cells"]]
+
+        # SMART PAGE-LEVEL REGISTRY: Remove individual tables and replace with multi-page table
+        # This ensures that page.find('table') finds the logical multi-page table, not fragments
+        constituent_pages = set()
+        for region in self.context.constituent_regions:
+            if hasattr(region, 'page') and hasattr(region.page, '_element_mgr'):
+                constituent_pages.add(region.page)
+        
+        # First, remove ONLY the specific individual Region tables that were created during this build
+        # (i.e., the physical_tables), not ALL tables with the same source
+        physical_tables_to_remove = set(physical_tables)  # Convert to set for fast lookup
+        
+        for page in constituent_pages:
+            try:
+                # Find and remove only the specific physical tables that are part of this multi-page table
+                existing_tables = page.find_all('table')
+                tables_to_remove = [
+                    table for table in existing_tables 
+                    if (table in physical_tables_to_remove and 
+                        not isinstance(table, FlowRegion))  # Only remove the specific Region tables we created
+                ]
+                
+                for table in tables_to_remove:
+                    page._element_mgr.remove_element(table, element_type="regions")
+                    logger.debug(f"Removed physical table fragment from page {page.page_number}")
+                
+                # Now register the multi-page table
+                page._element_mgr.add_element(multi_page_table, element_type="regions")
+                logger.debug(f"Registered multi-page table with page {page.page_number}")
+                
+            except Exception as e:
+                logger.warning(f"Failed to register multi-page table with page {page.page_number}: {e}")
+
+        # SMART PAGE-LEVEL REGISTRY: Also register rows, columns, and cells with their respective pages
+        # This ensures that page.find('table_cell') etc. also work across the multi-page structure
+        for row in final_rows:
+            if hasattr(row, 'constituent_regions'):
+                # This is a FlowRegion row spanning multiple pages
+                for constituent_region in row.constituent_regions:
+                    if hasattr(constituent_region, 'page') and hasattr(constituent_region.page, '_element_mgr'):
+                        try:
+                            constituent_region.page._element_mgr.add_element(row, element_type="regions")
+                        except Exception as e:
+                            logger.warning(f"Failed to register multi-page row: {e}")
+        
+        for col in final_cols:
+            if hasattr(col, 'constituent_regions'):
+                # This is a FlowRegion column spanning multiple pages
+                for constituent_region in col.constituent_regions:
+                    if hasattr(constituent_region, 'page') and hasattr(constituent_region.page, '_element_mgr'):
+                        try:
+                            constituent_region.page._element_mgr.add_element(col, element_type="regions")
+                        except Exception as e:
+                            logger.warning(f"Failed to register multi-page column: {e}")
+        
+        for cell in final_cells:
+            if hasattr(cell, 'constituent_regions'):
+                # This is a FlowRegion cell spanning multiple pages
+                for constituent_region in cell.constituent_regions:
+                    if hasattr(constituent_region, 'page') and hasattr(constituent_region.page, '_element_mgr'):
+                        try:
+                            constituent_region.page._element_mgr.add_element(cell, element_type="regions")
+                        except Exception as e:
+                            logger.warning(f"Failed to register multi-page cell: {e}")
+
+        final_counts = {
+            "table": 1,
+            "rows": len(final_rows),
+            "columns": len(final_cols),
+            "cells": len(final_cells),
+        }
+        final_regions = {
+            "table": multi_page_table,
+            "rows": final_rows,
+            "columns": final_cols,
+            "cells": final_cells,
+        }
+
+        logger.info(
+            f"Created 1 multi-page table, {final_counts['rows']} logical rows, "
+            f"{final_counts['columns']} logical columns from guides and registered with all constituent pages"
+        )
+
+        return {"counts": final_counts, "regions": final_regions}
+
+    def _build_grid_single_page(
+        self,
+        target: Optional[Union["Page", "Region"]] = None,
+        source: str = "guides",
+        cell_padding: float = 0.5,
+        include_outer_boundaries: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Private method to create table structure on a single page or region.
+        (Refactored from the original public build_grid method).
         """
-        # Determine target object
+        # This method now only handles a single page/region context.
+        # Looping for FlowRegions is handled by the public `build_grid` method.
+
+        # Original single-region logic follows...
         target_obj = target or self.context
         if not target_obj:
             raise ValueError("No target object available. Provide target parameter or context.")
@@ -2055,8 +3015,9 @@ class Guides:
             f"Building grid with {len(row_boundaries)} row and {len(col_boundaries)} col boundaries"
         )
 
-        # Track creation counts
+        # Track creation counts and regions
         counts = {"table": 0, "rows": 0, "columns": 0, "cells": 0}
+        created_regions = {"table": None, "rows": [], "columns": [], "cells": []}
 
         # Create overall table region
         if len(row_boundaries) >= 2 and len(col_boundaries) >= 2:
@@ -2076,6 +3037,7 @@ class Guides:
             )
             element_manager.add_element(table_region, element_type="regions")
             counts["table"] = 1
+            created_regions["table"] = table_region
 
         # Create row regions
         if len(row_boundaries) >= 2 and len(col_boundaries) >= 2:
@@ -2089,6 +3051,7 @@ class Guides:
                 row_region.metadata.update({"row_index": i, "source_guides": True})
                 element_manager.add_element(row_region, element_type="regions")
                 counts["rows"] += 1
+                created_regions["rows"].append(row_region)
 
         # Create column regions
         if len(col_boundaries) >= 2 and len(row_boundaries) >= 2:
@@ -2102,6 +3065,7 @@ class Guides:
                 col_region.metadata.update({"col_index": j, "source_guides": True})
                 element_manager.add_element(col_region, element_type="regions")
                 counts["columns"] += 1
+                created_regions["columns"].append(col_region)
 
         # Create cell regions
         if len(row_boundaries) >= 2 and len(col_boundaries) >= 2:
@@ -2136,13 +3100,14 @@ class Guides:
                     )
                     element_manager.add_element(cell_region, element_type="regions")
                     counts["cells"] += 1
+                    created_regions["cells"].append(cell_region)
 
         logger.info(
             f"Created {counts['table']} table, {counts['rows']} rows, "
             f"{counts['columns']} columns, and {counts['cells']} cells from guides"
         )
 
-        return counts
+        return {"counts": counts, "regions": created_regions}
 
     def __repr__(self) -> str:
         """String representation of the guides."""
@@ -2157,6 +3122,22 @@ class Guides:
         if not self.context:
             return []
 
+        # Handle FlowRegion context
+        if self.is_flow_region:
+            all_text_elements = []
+            for region in self.context.constituent_regions:
+                if hasattr(region, "find_all"):
+                    try:
+                        text_elements = region.find_all("text", apply_exclusions=False)
+                        elements = (
+                            text_elements.elements if hasattr(text_elements, "elements") else text_elements
+                        )
+                        all_text_elements.extend(elements)
+                    except Exception as e:
+                        logger.warning(f"Error getting text elements from region: {e}")
+            return all_text_elements
+
+        # Original single-region logic
         # Get text elements from the context
         if hasattr(self.context, "find_all"):
             try:
@@ -2171,6 +3152,31 @@ class Guides:
             logger.warning("Context does not support text element search")
             return []
 
+    def _spans_pages(self) -> bool:
+        """Check if any guides are defined across multiple pages in a FlowRegion."""
+        if not self.is_flow_region:
+            return False
+
+        # Check vertical guides
+        v_guide_pages = {}
+        for coord, region in self._unified_vertical:
+            v_guide_pages.setdefault(coord, set()).add(region.page.page_number)
+        
+        for pages in v_guide_pages.values():
+            if len(pages) > 1:
+                return True
+
+        # Check horizontal guides
+        h_guide_pages = {}
+        for coord, region in self._unified_horizontal:
+            h_guide_pages.setdefault(coord, set()).add(region.page.page_number)
+
+        for pages in h_guide_pages.values():
+            if len(pages) > 1:
+                return True
+
+        return False
+
     # -------------------------------------------------------------------------
     # Instance methods for fluent chaining (avoid name conflicts with class methods)
     # -------------------------------------------------------------------------
@@ -2318,3 +3324,24 @@ class Guides:
             self.horizontal = list(set(self.horizontal + new_guides.horizontal))
 
         return self
+
+    def _get_flow_orientation(self) -> Literal["vertical", "horizontal", "unknown"]:
+        """Determines if a FlowRegion's constituent parts are arranged vertically or horizontally."""
+        if not self.is_flow_region or len(self.context.constituent_regions) < 2:
+            return "unknown"
+
+        r1 = self.context.constituent_regions[0]
+        r2 = self.context.constituent_regions[1] # Compare first two regions
+
+        if not r1.bbox or not r2.bbox:
+            return "unknown"
+
+        # Calculate non-overlapping distances.
+        # This determines the primary direction of separation.
+        x_dist = max(0, max(r1.x0, r2.x0) - min(r1.x1, r2.x1))
+        y_dist = max(0, max(r1.top, r2.top) - min(r1.bottom, r2.bottom))
+
+        if y_dist > x_dist:
+            return "vertical"
+        else:
+            return "horizontal"