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

natural_pdf/flows/flow.py

@@ -1,19 +1,43 @@
 import logging
-from typing import TYPE_CHECKING, Any, List, Literal, Optional, Union
+import warnings
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Dict,
+    List,
+    Literal,
+    Optional,
+    Tuple,
+    Union,
+    overload,
+)
 
 if TYPE_CHECKING:
+    from PIL.Image import Image as PIL_Image
+
     from natural_pdf.core.page import Page
+    from natural_pdf.core.page_collection import PageCollection
     from natural_pdf.elements.base import Element as PhysicalElement
-    from natural_pdf.elements.collections import ElementCollection as PhysicalElementCollection
+    from natural_pdf.elements.element_collection import (
+        ElementCollection as PhysicalElementCollection,
+    )
     from natural_pdf.elements.region import Region as PhysicalRegion
 
     from .collections import FlowElementCollection
     from .element import FlowElement
 
+# Import required classes for the new methods
+# 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
+
 logger = logging.getLogger(__name__)
 
 
-class Flow:
+class Flow(Visualizable):
     """Defines a logical flow or sequence of physical Page or Region objects.
 
     A Flow represents a continuous logical document structure that spans across
@@ -81,7 +105,7 @@ class Flow:
 
     def __init__(
         self,
-        segments: List[Union["Page", "PhysicalRegion"]],
+        segments: Union[List[Union["Page", "PhysicalRegion"]], "PageCollection"],
         arrangement: Literal["vertical", "horizontal"],
         alignment: Literal["start", "center", "end", "top", "left", "bottom", "right"] = "start",
         segment_gap: float = 0.0,
@@ -91,7 +115,8 @@ class Flow:
 
         Args:
             segments: An ordered list of natural_pdf.core.page.Page or
-                      natural_pdf.elements.region.Region objects that constitute the flow.
+                      natural_pdf.elements.region.Region objects that constitute the flow,
+                      or a PageCollection containing pages.
             arrangement: The primary direction of the flow.
                          - "vertical": Segments are stacked top-to-bottom.
                          - "horizontal": Segments are arranged left-to-right.
@@ -106,6 +131,10 @@ class Flow:
                        - "bottom" (or "end"): Align bottom edges.
             segment_gap: The virtual gap (in PDF points) between segments.
         """
+        # Handle PageCollection input
+        if hasattr(segments, "pages"):  # It's a PageCollection
+            segments = list(segments.pages)
+
         if not segments:
             raise ValueError("Flow segments cannot be empty.")
         if arrangement not in ["vertical", "horizontal"]:
@@ -165,6 +194,103 @@ class Flow:
                 f"Valid options are: {valid_alignments[self.arrangement]}"
             )
 
+    def _get_highlighter(self):
+        """Get the highlighting service from the first segment."""
+        if not self.segments:
+            raise RuntimeError("Flow has no segments to get highlighter from")
+
+        # Get highlighter from first segment
+        first_segment = self.segments[0]
+        if hasattr(first_segment, "_highlighter"):
+            return first_segment._highlighter
+        elif hasattr(first_segment, "page") and hasattr(first_segment.page, "_highlighter"):
+            return first_segment.page._highlighter
+        else:
+            raise RuntimeError(
+                f"Cannot find HighlightingService from Flow segments. "
+                f"First segment type: {type(first_segment).__name__}"
+            )
+
+    def show(
+        self,
+        *,
+        # Basic rendering options
+        resolution: Optional[float] = None,
+        width: Optional[int] = None,
+        # Highlight options
+        color: Optional[Union[str, Tuple[int, int, int]]] = None,
+        labels: bool = True,
+        label_format: Optional[str] = None,
+        highlights: Optional[List[Dict[str, Any]]] = None,
+        # Layout options for multi-page/region
+        layout: Literal["stack", "grid", "single"] = "stack",
+        stack_direction: Literal["vertical", "horizontal"] = "vertical",
+        gap: int = 5,
+        columns: Optional[int] = None,  # For grid layout
+        # Cropping options
+        crop: Union[bool, Literal["content"]] = False,
+        crop_bbox: Optional[Tuple[float, float, float, float]] = None,
+        # Flow-specific options
+        in_context: bool = False,
+        separator_color: Optional[Tuple[int, int, int]] = None,
+        separator_thickness: int = 2,
+        **kwargs,
+    ) -> Optional["PIL_Image"]:
+        """Generate a preview image with highlights.
+
+        If in_context=True, shows segments as cropped images stacked together
+        with separators between segments.
+
+        Args:
+            resolution: DPI for rendering (default from global settings)
+            width: Target width in pixels (overrides resolution)
+            color: Default highlight color
+            labels: Whether to show labels for highlights
+            label_format: Format string for labels
+            highlights: Additional highlight groups to show
+            layout: How to arrange multiple pages/regions
+            stack_direction: Direction for stack layout
+            gap: Pixels between stacked images
+            columns: Number of columns for grid layout
+            crop: Whether to crop
+            crop_bbox: Explicit crop bounds
+            in_context: If True, use special Flow visualization with separators
+            separator_color: RGB color for separator lines (default: red)
+            separator_thickness: Thickness of separator lines
+            **kwargs: Additional parameters passed to rendering
+
+        Returns:
+            PIL Image object or None if nothing to render
+        """
+        if in_context:
+            # Use the special in_context visualization
+            return self._show_in_context(
+                resolution=resolution or 150,
+                width=width,
+                stack_direction=stack_direction,
+                stack_gap=gap,
+                separator_color=separator_color or (255, 0, 0),
+                separator_thickness=separator_thickness,
+                **kwargs,
+            )
+
+        # Otherwise use the standard show method
+        return super().show(
+            resolution=resolution,
+            width=width,
+            color=color,
+            labels=labels,
+            label_format=label_format,
+            highlights=highlights,
+            layout=layout,
+            stack_direction=stack_direction,
+            gap=gap,
+            columns=columns,
+            crop=crop,
+            crop_bbox=crop_bbox,
+            **kwargs,
+        )
+
     def find(
         self,
         selector: Optional[str] = None,
@@ -213,7 +339,10 @@ class Flow:
     ) -> "FlowElementCollection":
         """
         Finds all elements within the flow that match the given selector or text criteria.
-        Elements are collected segment by segment, preserving the flow order.
+
+        This method efficiently groups segments by their parent pages, searches at the page level,
+        then filters results appropriately for each segment. This ensures elements that intersect
+        with flow segments (but aren't fully contained) are still found.
 
         Elements found are wrapped as FlowElement objects, anchored to this Flow,
         and returned in a FlowElementCollection.
@@ -221,13 +350,42 @@ class Flow:
         from .collections import FlowElementCollection
         from .element import FlowElement
 
+        # Step 1: Group segments by their parent pages (like in analyze_layout)
+        segments_by_page = {}  # Dict[Page, List[Segment]]
+
+        for i, segment in enumerate(self.segments):
+            # Determine the page for this segment - fix type detection
+            if hasattr(segment, "page") and hasattr(segment.page, "find_all"):
+                # It's a Region object (has a parent page)
+                page_obj = segment.page
+                segment_type = "region"
+            elif (
+                hasattr(segment, "find_all")
+                and hasattr(segment, "width")
+                and hasattr(segment, "height")
+                and not hasattr(segment, "page")
+            ):
+                # It's a Page object (has find_all but no parent page)
+                page_obj = segment
+                segment_type = "page"
+            else:
+                logger.warning(f"Segment {i+1} does not support find_all, skipping")
+                continue
+
+            if page_obj not in segments_by_page:
+                segments_by_page[page_obj] = []
+            segments_by_page[page_obj].append((segment, segment_type))
+
+        if not segments_by_page:
+            logger.warning("No segments with searchable pages found")
+            return FlowElementCollection([])
+
+        # Step 2: Search each unique page only once
         all_flow_elements: List["FlowElement"] = []
 
-        # Iterate through segments in their defined flow order
-        for physical_segment in self.segments:
-            # Find all matching physical elements within the current segment
-            # Region.find_all() should return elements in local reading order.
-            matches_in_segment: "PhysicalElementCollection" = physical_segment.find_all(
+        for page_obj, page_segments in segments_by_page.items():
+            # Find all matching elements on this page
+            page_matches = page_obj.find_all(
                 selector=selector,
                 text=text,
                 apply_exclusions=apply_exclusions,
@@ -235,16 +393,56 @@ class Flow:
                 case=case,
                 **kwargs,
             )
-            if matches_in_segment:
-                # Wrap each found physical element as a FlowElement and add to the list
-                # This preserves the order from matches_in_segment.elements
-                for phys_elem in matches_in_segment.elements:
-                    all_flow_elements.append(FlowElement(physical_object=phys_elem, flow=self))
 
-        # The global sort that was here previously has been removed.
-        # The order is now determined by segment sequence, then by local order within each segment.
+            if not page_matches:
+                continue
+
+            # Step 3: For each segment on this page, collect relevant elements
+            for segment, segment_type in page_segments:
+                if segment_type == "page":
+                    # Full page segment: include all elements
+                    for phys_elem in page_matches.elements:
+                        all_flow_elements.append(FlowElement(physical_object=phys_elem, flow=self))
+
+                elif segment_type == "region":
+                    # Region segment: filter to only intersecting elements
+                    for phys_elem in page_matches.elements:
+                        try:
+                            # Check if element intersects with this flow segment
+                            if segment.intersects(phys_elem):
+                                all_flow_elements.append(
+                                    FlowElement(physical_object=phys_elem, flow=self)
+                                )
+                        except Exception as intersect_error:
+                            logger.debug(
+                                f"Error checking intersection for element: {intersect_error}"
+                            )
+                            # Include the element anyway if intersection check fails
+                            all_flow_elements.append(
+                                FlowElement(physical_object=phys_elem, flow=self)
+                            )
+
+        # Step 4: Remove duplicates (can happen if multiple segments intersect the same element)
+        unique_flow_elements = []
+        seen_element_ids = set()
+
+        for flow_elem in all_flow_elements:
+            # Create a unique identifier for the underlying physical element
+            phys_elem = flow_elem.physical_object
+            elem_id = (
+                (
+                    getattr(phys_elem.page, "index", id(phys_elem.page))
+                    if hasattr(phys_elem, "page")
+                    else id(phys_elem)
+                ),
+                phys_elem.bbox if hasattr(phys_elem, "bbox") else id(phys_elem),
+            )
+
+            if elem_id not in seen_element_ids:
+                unique_flow_elements.append(flow_elem)
+                seen_element_ids.add(elem_id)
 
-        return FlowElementCollection(all_flow_elements)
+        return FlowElementCollection(unique_flow_elements)
 
     def __repr__(self) -> str:
         return (
@@ -252,6 +450,807 @@ class Flow:
             f"arrangement='{self.arrangement}', alignment='{self.alignment}', gap={self.segment_gap}>"
         )
 
+    @overload
+    def extract_table(
+        self,
+        method: Optional[str] = None,
+        table_settings: Optional[dict] = None,
+        use_ocr: bool = False,
+        ocr_config: Optional[dict] = None,
+        text_options: Optional[dict] = None,
+        cell_extraction_func: Optional[Any] = None,
+        show_progress: bool = False,
+        content_filter: Optional[Any] = None,
+        stitch_rows: Callable[[List[Optional[str]]], bool] = None,
+    ) -> TableResult: ...
+
+    @overload
+    def extract_table(
+        self,
+        method: Optional[str] = None,
+        table_settings: Optional[dict] = None,
+        use_ocr: bool = False,
+        ocr_config: Optional[dict] = None,
+        text_options: Optional[dict] = None,
+        cell_extraction_func: Optional[Any] = None,
+        show_progress: bool = False,
+        content_filter: Optional[Any] = None,
+        stitch_rows: Callable[
+            [List[Optional[str]], List[Optional[str]], int, Union["Page", "PhysicalRegion"]],
+            bool,
+        ] = None,
+    ) -> TableResult: ...
+
+    def extract_table(
+        self,
+        method: Optional[str] = None,
+        table_settings: Optional[dict] = None,
+        use_ocr: bool = False,
+        ocr_config: Optional[dict] = None,
+        text_options: Optional[dict] = None,
+        cell_extraction_func: Optional[Any] = None,
+        show_progress: bool = False,
+        content_filter: Optional[Any] = None,
+        stitch_rows: Optional[Callable] = None,
+        merge_headers: Optional[bool] = None,
+    ) -> TableResult:
+        """
+        Extract table data from all segments in the flow, combining results sequentially.
+
+        This method extracts table data from each segment in flow order and combines
+        the results into a single logical table. This is particularly useful for
+        multi-page tables or tables that span across columns.
+
+        Args:
+            method: Method to use: 'tatr', 'pdfplumber', 'text', 'stream', 'lattice', or None (auto-detect).
+            table_settings: Settings for pdfplumber table extraction.
+            use_ocr: Whether to use OCR for text extraction (currently only applicable with 'tatr' method).
+            ocr_config: OCR configuration parameters.
+            text_options: Dictionary of options for the 'text' method.
+            cell_extraction_func: Optional callable function that takes a cell Region object
+                                  and returns its string content. For 'text' method only.
+            show_progress: If True, display a progress bar during cell text extraction for the 'text' method.
+            content_filter: Optional content filter to apply during cell text extraction.
+            merge_headers: Whether to merge tables by removing repeated headers from subsequent
+                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.
+            stitch_rows: Optional callable to determine when rows should be merged across
+                         segment boundaries. Applied AFTER header removal if merge_headers
+                         is enabled. Two overloaded signatures are supported:
+
+                         • func(current_row) -> bool
+                           Called only on the first row of each segment (after the first).
+                           Return True to merge this first row with the last row from
+                           the previous segment.
+
+                         • func(prev_row, current_row, row_index, segment) -> bool
+                           Called for every row. Return True to merge current_row with
+                           the previous row in the aggregated results.
+
+                         When True is returned, rows are concatenated cell-by-cell.
+                         This is useful for handling table rows split across page
+                         boundaries or segments. If None, rows are never merged.
+
+        Returns:
+            TableResult object containing the aggregated table data from all segments.
+
+        Example:
+            Multi-page table extraction:
+            ```python
+            pdf = npdf.PDF("multi_page_table.pdf")
+
+            # Create flow for table spanning pages 2-4
+            table_flow = Flow(
+                segments=[pdf.pages[1], pdf.pages[2], pdf.pages[3]],
+                arrangement='vertical'
+            )
+
+            # Extract table as if it were continuous
+            table_data = table_flow.extract_table()
+            df = table_data.df  # Convert to pandas DataFrame
+
+            # Custom row stitching - single parameter (simple case)
+            table_data = table_flow.extract_table(
+                stitch_rows=lambda row: row and not (row[0] or "").strip()
+            )
+
+            # Custom row stitching - full parameters (advanced case)
+            table_data = table_flow.extract_table(
+                stitch_rows=lambda prev, curr, idx, seg: idx == 0 and curr and not (curr[0] or "").strip()
+            )
+            ```
+        """
+        logger.info(
+            f"Extracting table from Flow with {len(self.segments)} segments (method: {method or 'auto'})"
+        )
+
+        if not self.segments:
+            logger.warning("Flow has no segments, returning empty table")
+            return TableResult([])
+
+        # Resolve predicate and determine its signature
+        predicate: Optional[Callable] = None
+        predicate_type: str = "none"
+
+        if callable(stitch_rows):
+            import inspect
+
+            sig = inspect.signature(stitch_rows)
+            param_count = len(sig.parameters)
+
+            if param_count == 1:
+                predicate = stitch_rows
+                predicate_type = "single_param"
+            elif param_count == 4:
+                predicate = stitch_rows
+                predicate_type = "full_params"
+            else:
+                logger.warning(
+                    f"stitch_rows function has {param_count} parameters, expected 1 or 4. Ignoring."
+                )
+                predicate = None
+                predicate_type = "none"
+
+        def _default_merge(
+            prev_row: List[Optional[str]], cur_row: List[Optional[str]]
+        ) -> List[Optional[str]]:
+            from itertools import zip_longest
+
+            merged: List[Optional[str]] = []
+            for p, c in zip_longest(prev_row, cur_row, fillvalue=""):
+                if (p or "").strip() and (c or "").strip():
+                    merged.append(f"{p} {c}".strip())
+                else:
+                    merged.append((p or "") + (c or ""))
+            return merged
+
+        aggregated_rows: List[List[Optional[str]]] = []
+        processed_segments = 0
+        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 seg_idx, segment in enumerate(self.segments):
+            try:
+                logger.debug(f"  Extracting table from segment {seg_idx+1}/{len(self.segments)}")
+
+                segment_result = segment.extract_table(
+                    method=method,
+                    table_settings=table_settings.copy() if table_settings else None,
+                    use_ocr=use_ocr,
+                    ocr_config=ocr_config,
+                    text_options=text_options.copy() if text_options else None,
+                    cell_extraction_func=cell_extraction_func,
+                    show_progress=show_progress,
+                    content_filter=content_filter,
+                )
+
+                if not segment_result:
+                    continue
+
+                if hasattr(segment_result, "_rows"):
+                    segment_rows = list(segment_result._rows)
+                else:
+                    segment_rows = list(segment_result)
+
+                if not segment_rows:
+                    logger.debug(f"    No table data found in segment {seg_idx+1}")
+                    continue
+
+                # Handle header detection and merging for multi-page tables
+                if seg_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 seg_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:]
+                        logger.debug(
+                            f"    Auto-detected repeated header in segment {seg_idx+1}, removed"
+                        )
+                        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
+                        logger.debug(f"    No repeated header detected in segment {seg_idx+1}")
+                elif seg_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:]
+                        logger.debug(f"    Removed repeated header from segment {seg_idx+1}")
+                elif seg_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:]
+                        logger.debug(f"    Removed repeated header from segment {seg_idx+1}")
+                        if not headers_warned:
+                            warnings.warn(
+                                "Removing repeated headers from multi-page table during merge.",
+                                UserWarning,
+                                stacklevel=2,
+                            )
+                            headers_warned = True
+
+                for row_idx, row in enumerate(segment_rows):
+                    should_merge = False
+
+                    if predicate is not None and aggregated_rows:
+                        if predicate_type == "single_param":
+                            # For single param: only call on first row of segment (row_idx == 0)
+                            # and pass the current row
+                            if row_idx == 0:
+                                should_merge = predicate(row)
+                        elif predicate_type == "full_params":
+                            # For full params: call with all arguments
+                            should_merge = predicate(aggregated_rows[-1], row, row_idx, segment)
+
+                    if should_merge:
+                        aggregated_rows[-1] = _default_merge(aggregated_rows[-1], row)
+                    else:
+                        aggregated_rows.append(row)
+
+                processed_segments += 1
+                logger.debug(
+                    f"    Added {len(segment_rows)} rows (post-merge) from segment {seg_idx+1}"
+                )
+
+            except Exception as e:
+                logger.error(f"Error extracting table from segment {seg_idx+1}: {e}", exc_info=True)
+                continue
+
+        # 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."
+                    )
+
+        logger.info(
+            f"Flow table extraction complete: {len(aggregated_rows)} total rows from {processed_segments}/{len(self.segments)} segments"
+        )
+        return TableResult(aggregated_rows)
+
+    def analyze_layout(
+        self,
+        engine: Optional[str] = None,
+        options: Optional[Any] = None,
+        confidence: Optional[float] = None,
+        classes: Optional[List[str]] = None,
+        exclude_classes: Optional[List[str]] = None,
+        device: Optional[str] = None,
+        existing: str = "replace",
+        model_name: Optional[str] = None,
+        client: Optional[Any] = None,
+    ) -> "PhysicalElementCollection":
+        """
+        Analyze layout across all segments in the flow.
+
+        This method efficiently groups segments by their parent pages, runs layout analysis
+        only once per unique page, then filters results appropriately for each segment.
+        This avoids redundant analysis when multiple flow segments come from the same page.
+
+        Args:
+            engine: Name of the layout engine (e.g., 'yolo', 'tatr'). Uses manager's default if None.
+            options: Specific LayoutOptions object for advanced configuration.
+            confidence: Minimum confidence threshold.
+            classes: Specific classes to detect.
+            exclude_classes: Classes to exclude.
+            device: Device for inference.
+            existing: How to handle existing detected regions: 'replace' (default) or 'append'.
+            model_name: Optional model name for the engine.
+            client: Optional client for API-based engines.
+
+        Returns:
+            ElementCollection containing all detected Region objects from all segments.
+
+        Example:
+            Multi-page layout analysis:
+            ```python
+            pdf = npdf.PDF("document.pdf")
+
+            # Create flow for first 3 pages
+            page_flow = Flow(
+                segments=pdf.pages[:3],
+                arrangement='vertical'
+            )
+
+            # Analyze layout across all pages (efficiently)
+            all_regions = page_flow.analyze_layout(engine='yolo')
+
+            # Find all tables across the flow
+            tables = all_regions.filter('region[type=table]')
+            ```
+        """
+        from natural_pdf.elements.element_collection import ElementCollection
+
+        logger.info(
+            f"Analyzing layout across Flow with {len(self.segments)} segments (engine: {engine or 'default'})"
+        )
+
+        if not self.segments:
+            logger.warning("Flow has no segments, returning empty collection")
+            return ElementCollection([])
+
+        # Step 1: Group segments by their parent pages to avoid redundant analysis
+        segments_by_page = {}  # Dict[Page, List[Segment]]
+
+        for i, segment in enumerate(self.segments):
+            # Determine the page for this segment
+            if hasattr(segment, "analyze_layout"):
+                # It's a Page object
+                page_obj = segment
+                segment_type = "page"
+            elif hasattr(segment, "page") and hasattr(segment.page, "analyze_layout"):
+                # It's a Region object
+                page_obj = segment.page
+                segment_type = "region"
+            else:
+                logger.warning(f"Segment {i+1} does not support layout analysis, skipping")
+                continue
+
+            if page_obj not in segments_by_page:
+                segments_by_page[page_obj] = []
+            segments_by_page[page_obj].append((segment, segment_type))
+
+        if not segments_by_page:
+            logger.warning("No segments with analyzable pages found")
+            return ElementCollection([])
+
+        logger.debug(
+            f"  Grouped {len(self.segments)} segments into {len(segments_by_page)} unique pages"
+        )
+
+        # Step 2: Analyze each unique page only once
+        all_detected_regions: List["PhysicalRegion"] = []
+        processed_pages = 0
+
+        for page_obj, page_segments in segments_by_page.items():
+            try:
+                logger.debug(
+                    f"  Analyzing layout for page {getattr(page_obj, 'number', '?')} with {len(page_segments)} segments"
+                )
+
+                # Run layout analysis once for this page
+                page_results = page_obj.analyze_layout(
+                    engine=engine,
+                    options=options,
+                    confidence=confidence,
+                    classes=classes,
+                    exclude_classes=exclude_classes,
+                    device=device,
+                    existing=existing,
+                    model_name=model_name,
+                    client=client,
+                )
+
+                # Extract regions from results
+                if hasattr(page_results, "elements"):
+                    # It's an ElementCollection
+                    page_regions = page_results.elements
+                elif isinstance(page_results, list):
+                    # It's a list of regions
+                    page_regions = page_results
+                else:
+                    logger.warning(
+                        f"Page {getattr(page_obj, 'number', '?')} returned unexpected layout analysis result type: {type(page_results)}"
+                    )
+                    continue
+
+                if not page_regions:
+                    logger.debug(
+                        f"    No layout regions found on page {getattr(page_obj, 'number', '?')}"
+                    )
+                    continue
+
+                # Step 3: For each segment on this page, collect relevant regions
+                segments_processed_on_page = 0
+                for segment, segment_type in page_segments:
+                    if segment_type == "page":
+                        # Full page segment: include all detected regions
+                        all_detected_regions.extend(page_regions)
+                        segments_processed_on_page += 1
+                        logger.debug(f"    Added {len(page_regions)} regions for full-page segment")
+
+                    elif segment_type == "region":
+                        # Region segment: filter to only intersecting regions
+                        intersecting_regions = []
+                        for region in page_regions:
+                            try:
+                                if segment.intersects(region):
+                                    intersecting_regions.append(region)
+                            except Exception as intersect_error:
+                                logger.debug(
+                                    f"Error checking intersection for region: {intersect_error}"
+                                )
+                                # Include the region anyway if intersection check fails
+                                intersecting_regions.append(region)
+
+                        all_detected_regions.extend(intersecting_regions)
+                        segments_processed_on_page += 1
+                        logger.debug(
+                            f"    Added {len(intersecting_regions)} intersecting regions for region segment {segment.bbox}"
+                        )
+
+                processed_pages += 1
+                logger.debug(
+                    f"    Processed {segments_processed_on_page} segments on page {getattr(page_obj, 'number', '?')}"
+                )
+
+            except Exception as e:
+                logger.error(
+                    f"Error analyzing layout for page {getattr(page_obj, 'number', '?')}: {e}",
+                    exc_info=True,
+                )
+                continue
+
+        # Step 4: Remove duplicates (can happen if multiple segments intersect the same region)
+        unique_regions = []
+        seen_region_ids = set()
+
+        for region in all_detected_regions:
+            # Create a unique identifier for this region (page + bbox)
+            region_id = (
+                getattr(region.page, "index", id(region.page)),
+                region.bbox if hasattr(region, "bbox") else id(region),
+            )
+
+            if region_id not in seen_region_ids:
+                unique_regions.append(region)
+                seen_region_ids.add(region_id)
+
+        dedupe_removed = len(all_detected_regions) - len(unique_regions)
+        if dedupe_removed > 0:
+            logger.debug(f"  Removed {dedupe_removed} duplicate regions")
+
+        logger.info(
+            f"Flow layout analysis complete: {len(unique_regions)} unique regions from {processed_pages} pages"
+        )
+        return ElementCollection(unique_regions)
+
+    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,
+        label_prefix: Optional[str] = "FlowSegment",
+        **kwargs,
+    ) -> List[RenderSpec]:
+        """Get render specifications for this flow.
+
+        Args:
+            mode: Rendering mode - 'show' includes highlights, 'render' is clean
+            color: Color for highlighting segments in show mode
+            highlights: Additional highlight groups to show
+            crop: Whether to crop to segments
+            crop_bbox: Explicit crop bounds
+            label_prefix: Prefix for segment labels
+            **kwargs: Additional parameters
+
+        Returns:
+            List of RenderSpec objects, one per page with segments
+        """
+        if not self.segments:
+            return []
+
+        # Group segments by their physical pages
+        segments_by_page = {}  # Dict[Page, List[PhysicalRegion]]
+
+        for i, segment in enumerate(self.segments):
+            # Get the page for this segment
+            if hasattr(segment, "page") and segment.page is not None:
+                # It's a Region, use its page
+                page_obj = segment.page
+                if page_obj not in segments_by_page:
+                    segments_by_page[page_obj] = []
+                segments_by_page[page_obj].append(segment)
+            elif (
+                hasattr(segment, "index")
+                and hasattr(segment, "width")
+                and hasattr(segment, "height")
+            ):
+                # It's a full Page object, create a full-page region for it
+                page_obj = segment
+                full_page_region = segment.region(0, 0, segment.width, segment.height)
+                if page_obj not in segments_by_page:
+                    segments_by_page[page_obj] = []
+                segments_by_page[page_obj].append(full_page_region)
+            else:
+                logger.warning(f"Segment {i+1} has no identifiable page, skipping")
+                continue
+
+        if not segments_by_page:
+            return []
+
+        # Create RenderSpec for each page
+        specs = []
+
+        # Sort pages by index for consistent output order
+        sorted_pages = sorted(
+            segments_by_page.keys(),
+            key=lambda p: p.index if hasattr(p, "index") else getattr(p, "page_number", 0),
+        )
+
+        for page_idx, page_obj in enumerate(sorted_pages):
+            segments_on_this_page = segments_by_page[page_obj]
+            if not segments_on_this_page:
+                continue
+
+            spec = RenderSpec(page=page_obj)
+
+            # Handle cropping
+            if crop_bbox:
+                spec.crop_bbox = crop_bbox
+            elif crop == "content" or crop is True:
+                # Calculate bounds of segments on this page
+                x_coords = []
+                y_coords = []
+                for segment in segments_on_this_page:
+                    if hasattr(segment, "bbox") and segment.bbox:
+                        x0, y0, x1, y1 = segment.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 segments
+                for i, segment in enumerate(segments_on_this_page):
+                    segment_label = None
+                    if label_prefix:
+                        # Create label for this segment
+                        global_segment_idx = None
+                        try:
+                            # Find the global index of this segment in the original flow
+                            global_segment_idx = self.segments.index(segment)
+                        except ValueError:
+                            # If it's a generated full-page region, find its source page
+                            for idx, orig_segment in enumerate(self.segments):
+                                if (
+                                    hasattr(orig_segment, "index")
+                                    and hasattr(segment, "page")
+                                    and orig_segment.index == segment.page.index
+                                ):
+                                    global_segment_idx = idx
+                                    break
+
+                        if global_segment_idx is not None:
+                            segment_label = f"{label_prefix}_{global_segment_idx + 1}"
+                        else:
+                            segment_label = f"{label_prefix}_p{page_idx + 1}s{i + 1}"
+
+                    spec.add_highlight(
+                        bbox=segment.bbox,
+                        polygon=segment.polygon if segment.has_polygon else None,
+                        color=color or "blue",
+                        label=segment_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_obj:
+                                spec.add_highlight(
+                                    element=elem, color=group_color, label=group_label
+                                )
+
+            specs.append(spec)
+
+        return specs
+
+    def _show_in_context(
+        self,
+        resolution: float,
+        width: Optional[int] = None,
+        stack_direction: str = "vertical",
+        stack_gap: int = 5,
+        stack_background_color: Tuple[int, int, int] = (255, 255, 255),
+        separator_color: Tuple[int, int, int] = (255, 0, 0),
+        separator_thickness: int = 2,
+        **kwargs,
+    ) -> Optional["PIL_Image"]:
+        """
+        Show segments as cropped images stacked together with separators between segments.
+
+        Args:
+            resolution: Resolution in DPI for rendering segment images
+            width: Optional width for segment images
+            stack_direction: Direction to stack segments ('vertical' or 'horizontal')
+            stack_gap: Gap in pixels between segments
+            stack_background_color: RGB background color for the final image
+            separator_color: RGB color for separator lines between segments
+            separator_thickness: Thickness in pixels of separator lines
+            **kwargs: Additional arguments passed to segment rendering
+
+        Returns:
+            PIL Image with all segments stacked together
+        """
+        from PIL import Image, ImageDraw
+
+        segment_images = []
+        segment_pages = []
+
+        # Determine stacking direction
+        final_stack_direction = stack_direction
+        if stack_direction == "auto":
+            final_stack_direction = self.arrangement
+
+        # Get cropped images for each segment
+        for i, segment in enumerate(self.segments):
+            # Get the page reference for this segment
+            if hasattr(segment, "page") and segment.page is not None:
+                segment_page = segment.page
+                # Get cropped image of the segment
+                # Use render() for clean image without highlights
+                segment_image = segment.render(
+                    resolution=resolution,
+                    crop=True,
+                    width=width,
+                    **kwargs,
+                )
+
+            elif (
+                hasattr(segment, "index")
+                and hasattr(segment, "width")
+                and hasattr(segment, "height")
+            ):
+                # It's a full Page object
+                segment_page = segment
+                # Use render() for clean image without highlights
+                segment_image = segment.render(resolution=resolution, width=width, **kwargs)
+            else:
+                raise ValueError(
+                    f"Segment {i+1} has no identifiable page. Segment type: {type(segment)}, attributes: {dir(segment)}"
+                )
+
+            if segment_image is not None:
+                segment_images.append(segment_image)
+                segment_pages.append(segment_page)
+            else:
+                logger.warning(f"Segment {i+1} render() returned None, skipping")
+
+        # Check if we have any valid images
+        if not segment_images:
+            logger.error("No valid segment images could be rendered")
+            return None
+
+        # We should have at least one segment image by now (or an exception would have been raised)
+        if len(segment_images) == 1:
+            return segment_images[0]
+
+        # Calculate dimensions for the final stacked image
+        if final_stack_direction == "vertical":
+            # Stack vertically
+            final_width = max(img.width for img in segment_images)
+
+            # Calculate total height including gaps and separators
+            total_height = sum(img.height for img in segment_images)
+            total_height += (len(segment_images) - 1) * stack_gap
+
+            # Add separator thickness between all segments
+            num_separators = len(segment_images) - 1 if len(segment_images) > 1 else 0
+            total_height += num_separators * separator_thickness
+
+            # Create the final image
+            final_image = Image.new("RGB", (final_width, total_height), stack_background_color)
+            draw = ImageDraw.Draw(final_image)
+
+            current_y = 0
+
+            for i, img in enumerate(segment_images):
+                # Add separator line before each segment (except the first one)
+                if i > 0:
+                    # Draw separator line
+                    draw.rectangle(
+                        [(0, current_y), (final_width, current_y + separator_thickness)],
+                        fill=separator_color,
+                    )
+                    current_y += separator_thickness
+
+                # Paste the segment image
+                paste_x = (final_width - img.width) // 2  # Center horizontally
+                final_image.paste(img, (paste_x, current_y))
+                current_y += img.height
+
+                # Add gap after segment (except for the last one)
+                if i < len(segment_images) - 1:
+                    current_y += stack_gap
+
+            return final_image
+
+        elif final_stack_direction == "horizontal":
+            # Stack horizontally
+            final_height = max(img.height for img in segment_images)
+
+            # Calculate total width including gaps and separators
+            total_width = sum(img.width for img in segment_images)
+            total_width += (len(segment_images) - 1) * stack_gap
+
+            # Add separator thickness between all segments
+            num_separators = len(segment_images) - 1 if len(segment_images) > 1 else 0
+            total_width += num_separators * separator_thickness
+
+            # Create the final image
+            final_image = Image.new("RGB", (total_width, final_height), stack_background_color)
+            draw = ImageDraw.Draw(final_image)
+
+            current_x = 0
+
+            for i, img in enumerate(segment_images):
+                # Add separator line before each segment (except the first one)
+                if i > 0:
+                    # Draw separator line
+                    draw.rectangle(
+                        [(current_x, 0), (current_x + separator_thickness, final_height)],
+                        fill=separator_color,
+                    )
+                    current_x += separator_thickness
+
+                # Paste the segment image
+                paste_y = (final_height - img.height) // 2  # Center vertically
+                final_image.paste(img, (current_x, paste_y))
+                current_x += img.width
+
+                # Add gap after segment (except for the last one)
+                if i < len(segment_images) - 1:
+                    current_x += stack_gap
+
+            return final_image
+
+        else:
+            raise ValueError(
+                f"Invalid stack_direction '{final_stack_direction}' for in_context. Must be 'vertical' or 'horizontal'."
+            )
+
     # --- Helper methods for coordinate transformations and segment iteration ---
     # These will be crucial for FlowElement's directional methods.
 
@@ -290,3 +1289,643 @@ class Flow:
         raise NotImplementedError(
             "Translating element coordinates to a unified flow coordinate system is not yet implemented."
         )
+
+    def get_sections(
+        self,
+        start_elements=None,
+        end_elements=None,
+        new_section_on_page_break: bool = False,
+        include_boundaries: str = "both",
+    ) -> "ElementCollection":
+        """
+        Extract logical sections from the Flow based on *start* and *end* boundary
+        elements, mirroring the behaviour of PDF/PageCollection.get_sections().
+
+        This implementation is a thin wrapper that converts the Flow into a
+        temporary PageCollection (constructed from the unique pages that the
+        Flow spans) and then delegates the heavy‐lifting to that existing
+        implementation.  Any FlowElement / FlowElementCollection inputs are
+        automatically unwrapped to their underlying physical elements so that
+        PageCollection can work with them directly.
+
+        Args:
+            start_elements: Elements or selector string that mark the start of
+                sections (optional).
+            end_elements: Elements or selector string that mark the end of
+                sections (optional).
+            new_section_on_page_break: Whether to start a new section at page
+                boundaries (default: False).
+            include_boundaries: How to include boundary elements: 'start',
+                'end', 'both', or 'none' (default: 'both').
+
+        Returns:
+            ElementCollection of Region/FlowRegion objects representing the
+            extracted sections.
+        """
+        # ------------------------------------------------------------------
+        # Unwrap FlowElement(-Collection) inputs and selector strings so we
+        # can reason about them generically.
+        # ------------------------------------------------------------------
+        from natural_pdf.flows.collections import FlowElementCollection
+        from natural_pdf.flows.element import FlowElement
+
+        def _unwrap(obj):
+            """Convert Flow-specific wrappers to their underlying physical objects.
+
+            Keeps selector strings as-is; converts FlowElement to its physical
+            element; converts FlowElementCollection to list of physical
+            elements; passes through ElementCollection by taking .elements.
+            """
+
+            if obj is None or isinstance(obj, str):
+                return obj
+
+            if isinstance(obj, FlowElement):
+                return obj.physical_object
+
+            if isinstance(obj, FlowElementCollection):
+                return [fe.physical_object for fe in obj.flow_elements]
+
+            if hasattr(obj, "elements"):
+                return obj.elements
+
+            if isinstance(obj, (list, tuple, set)):
+                out = []
+                for item in obj:
+                    if isinstance(item, FlowElement):
+                        out.append(item.physical_object)
+                    else:
+                        out.append(item)
+                return out
+
+            return obj  # Fallback – unknown type
+
+        start_elements_unwrapped = _unwrap(start_elements)
+        end_elements_unwrapped = _unwrap(end_elements)
+
+        # ------------------------------------------------------------------
+        # PRIMARY IMPLEMENTATION – operate on each Flow **segment region**
+        # independently so that sectioning happens *per-region*, not per page.
+        # ------------------------------------------------------------------
+        from natural_pdf.elements.element_collection import ElementCollection
+
+        aggregated_sections = []
+
+        # Helper to decide if an element lies inside a segment (Region)
+        def _element_in_segment(elem, segment_region):
+            try:
+                return segment_region.intersects(elem)  # Region method – robust
+            except Exception:
+                # Fallback to bounding-box containment checks
+                if not hasattr(elem, "bbox"):
+                    return False
+                ex0, etop, ex1, ebottom = elem.bbox
+                sx0, stop, sx1, sbottom = segment_region.bbox
+                return not (ex1 < sx0 or ex0 > sx1 or ebottom < stop or etop > sbottom)
+
+        for seg in self.segments:
+            # Each *seg* is guaranteed to be a Region (see _normalize_segments)
+
+            # Resolve segment-specific boundary arguments
+            seg_start_elems = None
+            seg_end_elems = None
+
+            # --- Handle selector strings ---
+            if isinstance(start_elements_unwrapped, str):
+                seg_start_elems = seg.find_all(start_elements_unwrapped).elements
+            elif start_elements_unwrapped is not None:
+                seg_start_elems = [
+                    e for e in start_elements_unwrapped if _element_in_segment(e, seg)
+                ]
+
+            if isinstance(end_elements_unwrapped, str):
+                seg_end_elems = seg.find_all(end_elements_unwrapped).elements
+            elif end_elements_unwrapped is not None:
+                seg_end_elems = [e for e in end_elements_unwrapped if _element_in_segment(e, seg)]
+
+            # Call Region.get_sections – this returns ElementCollection[Region]
+            seg_sections = seg.get_sections(
+                start_elements=seg_start_elems,
+                end_elements=seg_end_elems,
+                include_boundaries=include_boundaries,
+            )
+
+            if seg_sections:
+                aggregated_sections.extend(seg_sections.elements)
+
+            # Optionally, handle new_section_on_page_break – interpreted here as
+            # *new_section_on_segment_break*: if True and there were *no* explicit
+            # boundaries, treat the entire segment as a single section.
+            if (
+                new_section_on_page_break
+                and not seg_sections
+                and start_elements_unwrapped is None
+                and end_elements_unwrapped is None
+            ):
+                aggregated_sections.append(seg)
+
+        # ------------------------------------------------------------------
+        # CROSS-SEGMENT SECTION DETECTION: Check if we have boundaries that
+        # span multiple segments and create FlowRegions for those cases.
+        # ------------------------------------------------------------------
+
+        # If we have explicit start/end elements, check for cross-segment sections
+        if start_elements_unwrapped is not None and end_elements_unwrapped is not None:
+            # Find all start and end elements across all segments
+            all_start_elements = []
+            all_end_elements = []
+
+            # Map elements to their segments for tracking
+            element_to_segment = {}
+
+            for seg_idx, seg in enumerate(self.segments):
+                if isinstance(start_elements_unwrapped, str):
+                    seg_starts = seg.find_all(start_elements_unwrapped).elements
+                else:
+                    seg_starts = [
+                        e for e in start_elements_unwrapped if _element_in_segment(e, seg)
+                    ]
+
+                if isinstance(end_elements_unwrapped, str):
+                    seg_ends = seg.find_all(end_elements_unwrapped).elements
+                else:
+                    seg_ends = [e for e in end_elements_unwrapped if _element_in_segment(e, seg)]
+
+                for elem in seg_starts:
+                    all_start_elements.append((elem, seg_idx))
+                    element_to_segment[id(elem)] = seg_idx
+
+                for elem in seg_ends:
+                    all_end_elements.append((elem, seg_idx))
+                    element_to_segment[id(elem)] = seg_idx
+
+            # Sort by segment index, then by position within segment
+            all_start_elements.sort(key=lambda x: (x[1], x[0].top, x[0].x0))
+            all_end_elements.sort(key=lambda x: (x[1], x[0].top, x[0].x0))
+
+            # Look for cross-segment pairs (start in one segment, end in another)
+            cross_segment_sections = []
+            used_starts = set()
+            used_ends = set()
+
+            for start_elem, start_seg_idx in all_start_elements:
+                if id(start_elem) in used_starts:
+                    continue
+
+                # Find the next end element that comes after this start
+                matching_end = None
+                for end_elem, end_seg_idx in all_end_elements:
+                    if id(end_elem) in used_ends:
+                        continue
+
+                    # Check if this end comes after the start (by segment order or position)
+                    if end_seg_idx > start_seg_idx or (
+                        end_seg_idx == start_seg_idx
+                        and (
+                            end_elem.top > start_elem.top
+                            or (end_elem.top == start_elem.top and end_elem.x0 >= start_elem.x0)
+                        )
+                    ):
+                        matching_end = (end_elem, end_seg_idx)
+                        break
+
+                if matching_end is not None:
+                    end_elem, end_seg_idx = matching_end
+
+                    # If start and end are in different segments, create FlowRegion
+                    if start_seg_idx != end_seg_idx:
+                        cross_segment_sections.append(
+                            (start_elem, start_seg_idx, end_elem, end_seg_idx)
+                        )
+                        used_starts.add(id(start_elem))
+                        used_ends.add(id(end_elem))
+
+            # Create FlowRegions for cross-segment sections
+            from natural_pdf.elements.region import Region
+            from natural_pdf.flows.element import FlowElement
+            from natural_pdf.flows.region import FlowRegion
+
+            for start_elem, start_seg_idx, end_elem, end_seg_idx in cross_segment_sections:
+                # Build constituent regions spanning from start segment to end segment
+                constituent_regions = []
+
+                # First segment: from start element to bottom
+                start_seg = self.segments[start_seg_idx]
+                first_region = Region(
+                    start_seg.page, (start_seg.x0, start_elem.top, start_seg.x1, start_seg.bottom)
+                )
+                constituent_regions.append(first_region)
+
+                # Middle segments: full segments
+                for seg_idx in range(start_seg_idx + 1, end_seg_idx):
+                    constituent_regions.append(self.segments[seg_idx])
+
+                # Last segment: from top to end element
+                if end_seg_idx != start_seg_idx:
+                    end_seg = self.segments[end_seg_idx]
+                    last_region = Region(
+                        end_seg.page, (end_seg.x0, end_seg.top, end_seg.x1, end_elem.bottom)
+                    )
+                    constituent_regions.append(last_region)
+
+                # Create FlowRegion
+                flow_element = FlowElement(physical_object=start_elem, flow=self)
+                flow_region = FlowRegion(
+                    flow=self,
+                    constituent_regions=constituent_regions,
+                    source_flow_element=flow_element,
+                    boundary_element_found=end_elem,
+                )
+
+                # Remove any single-segment sections that are now covered by this FlowRegion
+                # This prevents duplication of content
+                aggregated_sections = [
+                    s
+                    for s in aggregated_sections
+                    if not any(
+                        cr.intersects(s)
+                        for cr in constituent_regions
+                        if hasattr(cr, "intersects") and hasattr(s, "intersects")
+                    )
+                ]
+
+                aggregated_sections.append(flow_region)
+
+        # ------------------------------------------------------------------
+        # NEW APPROACH: First collect ALL boundary elements across all segments,
+        # then pair them up to create sections (either single-segment Regions
+        # or multi-segment FlowRegions).
+        # ------------------------------------------------------------------
+        from natural_pdf.elements.element_collection import ElementCollection
+        from natural_pdf.elements.region import Region
+        from natural_pdf.flows.element import FlowElement
+        from natural_pdf.flows.region import FlowRegion
+
+        # Helper to decide if an element lies inside a segment (Region)
+        def _element_in_segment(elem, segment_region):
+            try:
+                return segment_region.intersects(elem)  # Region method – robust
+            except Exception:
+                # Fallback to bounding-box containment checks
+                if not hasattr(elem, "bbox"):
+                    return False
+                ex0, etop, ex1, ebottom = elem.bbox
+                sx0, stop, sx1, sbottom = segment_region.bbox
+                return not (ex1 < sx0 or ex0 > sx1 or ebottom < stop or etop > sbottom)
+
+        # Collect ALL boundary elements across all segments with their segment indices
+        all_start_elements = []
+        all_end_elements = []
+
+        for seg_idx, seg in enumerate(self.segments):
+            # Find start elements in this segment
+            if isinstance(start_elements_unwrapped, str):
+                seg_starts = seg.find_all(start_elements_unwrapped).elements
+            elif start_elements_unwrapped is not None:
+                seg_starts = [e for e in start_elements_unwrapped if _element_in_segment(e, seg)]
+            else:
+                seg_starts = []
+
+            logger.debug(f"\n=== Processing segment {seg_idx} ===")
+            logger.debug(f"Segment bbox: {seg.bbox}")
+            logger.debug(
+                f"Segment page: {seg.page.number if hasattr(seg.page, 'number') else 'unknown'}"
+            )
+
+            logger.debug(f"Found {len(seg_starts)} start elements in segment {seg_idx}")
+            for i, elem in enumerate(seg_starts):
+                logger.debug(
+                    f"  Start {i}: bbox={elem.bbox}, text='{getattr(elem, 'text', 'N/A')[:50]}...'"
+                )
+
+            # Find end elements in this segment
+            if isinstance(end_elements_unwrapped, str):
+                seg_ends = seg.find_all(end_elements_unwrapped).elements
+            elif end_elements_unwrapped is not None:
+                seg_ends = [e for e in end_elements_unwrapped if _element_in_segment(e, seg)]
+            else:
+                seg_ends = []
+
+            logger.debug(f"Found {len(seg_ends)} end elements in segment {seg_idx}")
+            for i, elem in enumerate(seg_ends):
+                logger.debug(
+                    f"  End {i}: bbox={elem.bbox}, text='{getattr(elem, 'text', 'N/A')[:50]}...'"
+                )
+
+            # Add to global lists with segment index
+            for elem in seg_starts:
+                all_start_elements.append((elem, seg_idx))
+            for elem in seg_ends:
+                all_end_elements.append((elem, seg_idx))
+
+        # Sort by flow order: segment index first, then position within segment
+        all_start_elements.sort(key=lambda x: (x[1], x[0].top, x[0].x0))
+        all_end_elements.sort(key=lambda x: (x[1], x[0].top, x[0].x0))
+
+        logger.debug(f"\n=== Total boundary elements found ===")
+        logger.debug(f"Total start elements: {len(all_start_elements)}")
+        logger.debug(f"Total end elements: {len(all_end_elements)}")
+
+        # Pair up start and end elements to create sections
+        sections = []
+        used_starts = set()
+        used_ends = set()
+
+        for start_elem, start_seg_idx in all_start_elements:
+            if id(start_elem) in used_starts:
+                continue
+
+            logger.debug(f"\n--- Pairing start element from segment {start_seg_idx} ---")
+            logger.debug(
+                f"Start: bbox={start_elem.bbox}, text='{getattr(start_elem, 'text', 'N/A')[:30]}...'"
+            )
+
+            # Find the next unused end element that comes after this start
+            matching_end = None
+            for end_elem, end_seg_idx in all_end_elements:
+                if id(end_elem) in used_ends:
+                    continue
+
+                # Check if this end comes after the start in flow order
+                if end_seg_idx > start_seg_idx or (
+                    end_seg_idx == start_seg_idx
+                    and (
+                        end_elem.top > start_elem.top
+                        or (end_elem.top == start_elem.top and end_elem.x0 >= start_elem.x0)
+                    )
+                ):
+                    matching_end = (end_elem, end_seg_idx)
+                    break
+
+            if matching_end is not None:
+                end_elem, end_seg_idx = matching_end
+                used_starts.add(id(start_elem))
+                used_ends.add(id(end_elem))
+
+                logger.debug(f"  Matched! Start seg={start_seg_idx}, End seg={end_seg_idx}")
+
+                # Create section based on whether it spans segments
+                if start_seg_idx == end_seg_idx:
+                    # Single segment section - use Region.get_section_between
+                    seg = self.segments[start_seg_idx]
+                    section = seg.get_section_between(start_elem, end_elem, include_boundaries)
+                    sections.append(section)
+                    logger.debug(f"  Created single-segment Region")
+                else:
+                    # Multi-segment section - create FlowRegion
+                    logger.debug(
+                        f"  Creating multi-segment FlowRegion spanning segments {start_seg_idx} to {end_seg_idx}"
+                    )
+                    constituent_regions = []
+
+                    # First segment: from start element to bottom
+                    start_seg = self.segments[start_seg_idx]
+                    if include_boundaries in ["start", "both"]:
+                        first_top = start_elem.top
+                    else:
+                        first_top = start_elem.bottom
+                    first_region = Region(
+                        start_seg.page, (start_seg.x0, first_top, start_seg.x1, start_seg.bottom)
+                    )
+                    constituent_regions.append(first_region)
+
+                    # Middle segments: full segments
+                    for seg_idx in range(start_seg_idx + 1, end_seg_idx):
+                        constituent_regions.append(self.segments[seg_idx])
+
+                    # Last segment: from top to end element
+                    end_seg = self.segments[end_seg_idx]
+                    if include_boundaries in ["end", "both"]:
+                        last_bottom = end_elem.bottom
+                    else:
+                        last_bottom = end_elem.top
+                    last_region = Region(
+                        end_seg.page, (end_seg.x0, end_seg.top, end_seg.x1, last_bottom)
+                    )
+                    constituent_regions.append(last_region)
+
+                    # Create FlowRegion
+                    flow_element = FlowElement(physical_object=start_elem, flow=self)
+                    flow_region = FlowRegion(
+                        flow=self,
+                        constituent_regions=constituent_regions,
+                        source_flow_element=flow_element,
+                        boundary_element_found=end_elem,
+                    )
+                    sections.append(flow_region)
+
+        # Handle special cases when only start or only end elements are provided
+        if start_elements_unwrapped is not None and end_elements_unwrapped is None:
+            logger.debug(f"\n=== Handling start-only elements (no end elements provided) ===")
+            for i, (start_elem, start_seg_idx) in enumerate(all_start_elements):
+                if id(start_elem) in used_starts:
+                    continue
+
+                # Find next start element
+                next_start = None
+                if i + 1 < len(all_start_elements):
+                    next_start_elem, next_start_seg_idx = all_start_elements[i + 1]
+                    # Create section from this start to just before next start
+                    if start_seg_idx == next_start_seg_idx:
+                        # Same segment
+                        seg = self.segments[start_seg_idx]
+                        # Find element just before next start
+                        all_elems = seg.get_elements()
+                        all_elems.sort(key=lambda e: (e.top, e.x0))
+                        try:
+                            next_idx = all_elems.index(next_start_elem)
+                            if next_idx > 0:
+                                end_elem = all_elems[next_idx - 1]
+                                section = seg.get_section_between(
+                                    start_elem, end_elem, include_boundaries
+                                )
+                                sections.append(section)
+                        except ValueError:
+                            pass
+                    elif next_start_seg_idx == start_seg_idx + 1:
+                        # Next start is in the immediately following segment in the flow
+                        # Create a FlowRegion that spans from current start to just before next start
+                        logger.debug(f"  Next start is in next flow segment - creating FlowRegion")
+
+                        constituent_regions = []
+
+                        # First segment: from start element to bottom
+                        start_seg = self.segments[start_seg_idx]
+                        if include_boundaries in ["start", "both"]:
+                            first_top = start_elem.top
+                        else:
+                            first_top = start_elem.bottom
+                        first_region = Region(
+                            start_seg.page,
+                            (start_seg.x0, first_top, start_seg.x1, start_seg.bottom),
+                        )
+                        constituent_regions.append(first_region)
+
+                        # Next segment: from top to just before next start
+                        next_seg = self.segments[next_start_seg_idx]
+                        # Find element just before next start in the next segment
+                        next_seg_elems = next_seg.get_elements()
+                        next_seg_elems.sort(key=lambda e: (e.top, e.x0))
+
+                        last_bottom = next_start_elem.top  # Default to just before the next start
+                        try:
+                            next_idx = next_seg_elems.index(next_start_elem)
+                            if next_idx > 0:
+                                # Use the bottom of the element before next start
+                                prev_elem = next_seg_elems[next_idx - 1]
+                                last_bottom = prev_elem.bottom
+                        except ValueError:
+                            pass
+
+                        last_region = Region(
+                            next_seg.page, (next_seg.x0, next_seg.top, next_seg.x1, last_bottom)
+                        )
+                        constituent_regions.append(last_region)
+
+                        # Create FlowRegion
+                        flow_element = FlowElement(physical_object=start_elem, flow=self)
+                        flow_region = FlowRegion(
+                            flow=self,
+                            constituent_regions=constituent_regions,
+                            source_flow_element=flow_element,
+                            boundary_element_found=None,
+                        )
+                        sections.append(flow_region)
+                        logger.debug(
+                            f"  Created FlowRegion with {len(constituent_regions)} constituent regions"
+                        )
+                    else:
+                        # Next start is more than one segment away - just end at current segment
+                        start_seg = self.segments[start_seg_idx]
+                        if include_boundaries in ["start", "both"]:
+                            region_top = start_elem.top
+                        else:
+                            region_top = start_elem.bottom
+                        section = Region(
+                            start_seg.page,
+                            (start_seg.x0, region_top, start_seg.x1, start_seg.bottom),
+                        )
+                        sections.append(section)
+                        logger.debug(
+                            f"  Next start is {next_start_seg_idx - start_seg_idx} segments away - ending at current segment"
+                        )
+                else:
+                    # Last start element: section goes to end of flow
+                    # This could span multiple segments
+                    if start_seg_idx == len(self.segments) - 1:
+                        # Only in last segment
+                        seg = self.segments[start_seg_idx]
+                        if include_boundaries in ["start", "both"]:
+                            region_top = start_elem.top
+                        else:
+                            region_top = start_elem.bottom
+                        section = Region(seg.page, (seg.x0, region_top, seg.x1, seg.bottom))
+                        sections.append(section)
+                    else:
+                        # Spans to end of flow - create FlowRegion
+                        constituent_regions = []
+
+                        # First segment
+                        start_seg = self.segments[start_seg_idx]
+                        if include_boundaries in ["start", "both"]:
+                            first_top = start_elem.top
+                        else:
+                            first_top = start_elem.bottom
+                        first_region = Region(
+                            start_seg.page,
+                            (start_seg.x0, first_top, start_seg.x1, start_seg.bottom),
+                        )
+                        constituent_regions.append(first_region)
+
+                        # Remaining segments
+                        for seg_idx in range(start_seg_idx + 1, len(self.segments)):
+                            constituent_regions.append(self.segments[seg_idx])
+
+                        flow_element = FlowElement(physical_object=start_elem, flow=self)
+                        flow_region = FlowRegion(
+                            flow=self,
+                            constituent_regions=constituent_regions,
+                            source_flow_element=flow_element,
+                            boundary_element_found=None,
+                        )
+                        sections.append(flow_region)
+
+        # Handle new_section_on_page_break when no explicit boundaries
+        if (
+            new_section_on_page_break
+            and start_elements_unwrapped is None
+            and end_elements_unwrapped is None
+        ):
+            # Each segment becomes its own section
+            sections = list(self.segments)
+
+        # Sort sections by their position in the flow
+        def _section_sort_key(section):
+            if hasattr(section, "constituent_regions"):
+                # FlowRegion - use first constituent region
+                first_region = (
+                    section.constituent_regions[0] if section.constituent_regions else None
+                )
+                if first_region:
+                    # Find which segment this region belongs to
+                    for idx, seg in enumerate(self.segments):
+                        try:
+                            if seg.intersects(first_region):
+                                return (
+                                    idx,
+                                    getattr(first_region, "top", 0),
+                                    getattr(first_region, "x0", 0),
+                                )
+                        except:
+                            pass
+            else:
+                # Regular Region
+                for idx, seg in enumerate(self.segments):
+                    try:
+                        if seg.intersects(section):
+                            return (idx, getattr(section, "top", 0), getattr(section, "x0", 0))
+                    except:
+                        pass
+            return (float("inf"), 0, 0)
+
+        sections.sort(key=_section_sort_key)
+
+        logger.debug(f"\n=== Section creation complete ===")
+        logger.debug(f"Total sections created: {len(sections)}")
+        for i, section in enumerate(sections):
+            if hasattr(section, "constituent_regions"):
+                logger.debug(
+                    f"Section {i}: FlowRegion with {len(section.constituent_regions)} constituent regions"
+                )
+            else:
+                logger.debug(f"Section {i}: Region with bbox={section.bbox}")
+
+        return ElementCollection(sections)
+
+    def highlights(self, show: bool = False) -> "HighlightContext":
+        """
+        Create a highlight context for accumulating highlights.
+
+        This allows for clean syntax to show multiple highlight groups:
+
+        Example:
+            with flow.highlights() as h:
+                h.add(flow.find_all('table'), label='tables', color='blue')
+                h.add(flow.find_all('text:bold'), label='bold text', color='red')
+                h.show()
+
+        Or with automatic display:
+            with flow.highlights(show=True) as h:
+                h.add(flow.find_all('table'), label='tables')
+                h.add(flow.find_all('text:bold'), label='bold')
+                # Automatically shows when exiting the context
+
+        Args:
+            show: If True, automatically show highlights when exiting context
+
+        Returns:
+            HighlightContext for accumulating highlights
+        """
+        from natural_pdf.core.highlighting_service import HighlightContext
+
+        return HighlightContext(self, show_on_exit=show)