class HtmlPageSplitter:
    """Split HTML into pages,
    preserving HTML tags while respecting the original document structure.
    """

    def __init__(
        self,
        content: str = "",
        *,
        root: etree._Element | None = None,
        target_length: int = PAGE_LENGTH_TARGET,
        error_tolerance: float = PAGE_LENGTH_ERROR_TOLERANCE,
    ) -> None:
        """Initialize the HTML page splitter.

        Args:
            content: HTML content string to split (optional if root is provided)
            root: Parsed lxml element tree root (optional if content is provided)
            target_length: Target size for each page in characters
            error_tolerance: Tolerance for page size variation (default 0.25)
        """
        self.target_page_size = target_length
        self.max_size = int(target_length * (1 + error_tolerance))
        self.max_error = self.max_size - target_length

        if root is not None:
            self.root = root
        elif content is not None and content.strip():
            self.root = parse_partial_html(content)
        else:
            self.root = None

    def pages(self) -> Iterator[str]:
        """Split content into pages."""
        if self.root is None:
            return
        current_page: list[etree.Element] = []
        current_size = 0

        for element in self._split_element(self.root):
            element_size = self._get_element_size(element)

            # Check if adding this element would exceed page size
            if current_size + element_size > self.max_size and current_page:
                yield self._render_page(current_page)
                current_page = []
                current_size = 0

            current_page.append(element)
            current_size += element_size

        # Yield final page if there's content
        if current_page:
            yield self._render_page(current_page)

    def _split_element(self, element: etree._Element) -> Iterator[etree._Element]:  # noqa: PLR0915,PLR0912,C901
        """Recursively split an element if it's too large."""
        element_size = self._get_element_size(element)

        # If element is small enough, yield it as is
        if element_size <= self.max_size:
            # Special handling for body elements - yield their children instead
            if getattr(element, "tag", None) == "body":
                for child in element:
                    yield copy.deepcopy(child)
                return
            yield copy.deepcopy(element)
            return

        # Element is too large - try to split it

        if getattr(element, "tag", None) == "body":
            # Treat body's children as if they were at the root level
            for child in element:
                yield from self._split_element(child)
            return

        # If element has no children, it must have large text content or tail
        if len(element) == 0:
            yield from self._split_text_element(element)
            return

        # Element has children - we need to handle:
        # 1. element.text (before first child)
        # 2. each child and its tail text
        # We'll build up a list of content items and then group them into pages

        content_items: list[tuple[str, Any]] = []

        # Handle text before first child
        if element.text and element.text.strip():
            if len(element.text) > self.max_size:
                # Split the text
                text_chunks = self._split_text(element.text)
                content_items.extend(("text", chunk) for chunk in text_chunks)
            else:
                content_items.append(("text", element.text))

        # Process each child and its tail
        for child in element:
            # Recursively split the child
            content_items.extend(
                ("element", split_child) for split_child in self._split_element(child)
            )
            # Handle tail text of the original child
            if child.tail and child.tail.strip():
                if len(child.tail) > self.target_page_size:
                    # Split the tail text
                    tail_chunks = self._split_text(child.tail)
                    content_items.extend(("tail", chunk) for chunk in tail_chunks)
                else:
                    content_items.append(("tail", child.tail))

        # Now group content items into pages
        nsmap = _get_nsmap(element.attrib)
        current_shell = etree.Element(element.tag, nsmap=nsmap)
        _set_attributes(current_shell, element.attrib, nsmap)
        current_size = 0

        for item_type, item_content in content_items:
            item_size = 0  # initialized here only to satisfy type checker
            if item_type == "text":
                # This is text that goes at the beginning of the element
                if not current_shell.text:
                    current_shell.text = item_content
                else:
                    current_shell.text += item_content
                item_size = len(item_content)
            elif item_type == "element":
                # This is a child element
                item_size = self._get_element_size(item_content)
                if current_size + item_size > self.target_page_size and (
                    len(current_shell) > 0 or current_shell.text
                ):
                    # Yield current shell and start a new one
                    yield current_shell
                    current_shell = etree.Element(element.tag, nsmap=nsmap)
                    _set_attributes(current_shell, element.attrib, nsmap)
                    current_size = 0
                current_shell.append(item_content)
            elif item_type == "tail":
                # This is tail text that should follow the last child
                item_size = len(item_content)
                if current_size + item_size > self.target_page_size and (
                    len(current_shell) > 0 or current_shell.text
                ):
                    # Yield current shell and start a new one
                    yield current_shell
                    current_shell = etree.Element(element.tag, nsmap=nsmap)
                    _set_attributes(current_shell, element.attrib, nsmap)
                    current_size = 0

                if len(current_shell) > 0:
                    # Add as tail to the last child
                    last_child = current_shell[-1]
                    if last_child.tail:
                        last_child.tail += item_content
                    else:
                        last_child.tail = item_content
                # No children yet, add as text
                elif current_shell.text:
                    current_shell.text += item_content
                else:
                    current_shell.text = item_content

            current_size += item_size

        # Yield final shell if it has content
        if len(current_shell) > 0 or current_shell.text:
            yield current_shell

    def _split_text_element(self, element: etree._Element) -> Iterator[etree._Element]:
        """Split an element that has only text content."""
        text = element.text or ""
        if not text:
            yield copy.deepcopy(element)
            return

        chunks = self._split_text(text)
        nsmap = _get_nsmap(element.attrib)
        for chunk in chunks:
            new_elem = etree.Element(element.tag, nsmap=nsmap)
            _set_attributes(new_elem, element.attrib, nsmap)
            new_elem.text = chunk
            yield new_elem

    def _split_text(self, text: str) -> list[str]:
        """Split text into chunks that fit within page size."""
        if not text or len(text) <= self.target_page_size:
            return [text]

        chunks = []
        start = 0

        while start < len(text):
            # Find end position for this chunk
            end = start + self.target_page_size

            if end >= len(text):
                chunks.append(text[start:])
                break

            # Find a good break point
            break_pos = self._find_break_point(text, start, end)
            chunks.append(text[start:break_pos])
            start = break_pos

        return chunks

    def _find_break_point(self, text: str, start: int, target_end: int) -> int:
        """Find the best position to break text."""
        if target_end >= len(text):
            return len(text)

        # Look for break points in order of preference
        break_sequences = [
            "\n\n",  # Paragraph break
            ".\n",  # Sentence end with newline
            "!\n",  # Exclamation with newline
            "?\n",  # Question with newline
            ". ",  # Sentence end
            "! ",  # Exclamation
            "? ",  # Question
            "\n",  # Line break
            "; ",  # Semicolon
            ", ",  # Comma
            " ",  # Space
        ]

        search_start = max(start, target_end - self.max_error)
        search_end = min(len(text), target_end + self.max_error)

        for break_seq in break_sequences:
            # Search backward from target
            for pos in range(target_end, search_start, -1):
                if text[pos : pos + len(break_seq)] == break_seq:
                    return pos + len(break_seq)

            # Search forward from target (but not too far to avoid exceeding limits)
            for pos in range(target_end, search_end):
                if text[pos : pos + len(break_seq)] == break_seq:
                    return pos + len(break_seq)

        # No good break point found - break at target
        return target_end

    def _get_element_size(self, element: etree._Element) -> int:
        """Calculate the size of an element in characters."""
        return len(etree.tostring(element, method="text", encoding="unicode").strip())

    def _render_page(self, elements: list[etree._Element]) -> str:
        """Render a page from a list of elements."""
        if len(elements) == 1:
            return etree_to_str(elements[0])
        return "".join(etree_to_str(elem) for elem in elements)

class PageSplitter:
    """Split pure text into pages at natural break points such as paragraphs or sentences."""

    def __init__(
        self,
        text: str,
        *,
        start: int = 0,
        end: int = 0,
        target_length: int = PAGE_LENGTH_TARGET,
        error_tolerance: float = PAGE_LENGTH_ERROR_TOLERANCE,
    ):
        self.text = text
        self.start = start
        self.end = len(text) if end == 0 else end
        assert 0 < error_tolerance < 1
        self.target_length = target_length
        self.error_tolerance = error_tolerance
        self.min_length = int(
            self.target_length * (1 - self.error_tolerance),
        )
        self.max_length = int(
            self.target_length * (1 + self.error_tolerance),
        )

    def pages(self) -> Iterator[str]:
        """Split a text into pages of approximately equal length.

        Also clear headings and recollect them during pages generation.
        """
        chapter_detector = ChapterDetector()
        start = self.start
        page_num = 0
        while start < self.end:
            page_num += 1
            end = self.find_nearest_page_end(start)

            # Check for chapters near the end of the current page segment
            chapter_search_text = self.text[start + self.min_length : start + self.max_length]
            if chapters := chapter_detector.get_chapters(chapter_search_text):
                # Find the chapter position that is nearest to the target page size
                target_position = start + self.target_length
                # Use the position field from ChapterMatch to find the nearest chapter
                nearest_chapter_idx = min(
                    range(len(chapters)),
                    key=lambda i: abs(
                        (start + self.min_length + chapters[i].position) - target_position,
                    ),
                )
                # Set end to the start of the nearest chapter
                end = start + self.min_length + chapters[nearest_chapter_idx].position

            yield self.normalize(self.text[start:end])
            assert end > start
            start = end

    def normalize(self, text: str) -> str:
        text = re.sub(r"\r", "", text)
        return re.sub(r"[ \t]+", " ", text)

    def find_nearest_page_end_match(
        self,
        page_start_index: int,
        pattern: re.Pattern[str],
    ) -> int | None:
        """Find the nearest regex match around expected end of page.

        In no such match in the vicinity, return None.
        Calculate the vicinity based on the expected PAGE_LENGTH_TARGET
        and PAGE_LENGTH_ERROR_TOLERANCE.
        """
        end_pos = min(
            page_start_index + int(self.max_length),
            self.end,
        )
        start_pos = max(
            page_start_index + int(self.min_length),
            self.start,
        )
        ends = [match.end() for match in pattern.finditer(self.text, start_pos, end_pos)]
        return (
            min(ends, key=lambda x: abs(x - (page_start_index + self.target_length)))
            if ends
            else None
        )

    def find_nearest_page_end(self, page_start_index: int) -> int:
        """Find the nearest page end."""
        patterns = [  # sorted by priority
            re.compile(r"(\r?\n|\u2028|\u2029)(\s*(\r?\n|\u2028|\u2029))+"),  # Paragraph end
            re.compile(r"(\r?\n|\u2028|\u2029)"),  # Line end
            re.compile(r"[^\s.!?]*\w[^\s.!?]*[.!?]\s"),  # Sentence end
            re.compile(r"\w+\b"),  # Word end
        ]

        for pattern in patterns:
            if nearest_page_end := self.find_nearest_page_end_match(
                page_start_index,
                pattern,
            ):
                return self.handle_p_tag_split(page_start_index, nearest_page_end)

        # If no suitable end found, return the maximum allowed length
        return min(page_start_index + self.end, page_start_index + self.target_length)

    def handle_p_tag_split(self, page_start_index: int, nearest_page_end: int) -> int:
        """Find the position of the last closing </p> tag before the split."""
        # todo: remove that - we work with with plain text here
        last_open_p_tag_pos = self.text.find("<p", page_start_index, nearest_page_end)
        last_close_p_tag_pos = self.text.rfind("</p>", page_start_index, nearest_page_end)

        if last_open_p_tag_pos != -1 and (
            last_close_p_tag_pos == -1 or last_close_p_tag_pos < last_open_p_tag_pos
        ):
            # Split <p> between pages
            self.text = f"{self.text[:nearest_page_end]}</p><p>{self.text[nearest_page_end:]}"
            nearest_page_end += len("</p>")

        return nearest_page_end

class ChapterDetector:
    """Detect chapters in pure text to create a Table of Contents."""

    def __init__(self, min_chapter_distance: int = MIN_CHAPTER_DISTANCE) -> None:
        """
        min_chapter_distance: Minimum character distance required between chapters.
            Chapter signatures detected within this threshold from previously detected chapters
            will be ignored. Default is 20 characters.
        """
        self.min_chapter_distance = min_chapter_distance

    def get_chapters(self, page_text: str) -> list[Chapter]:
        """Detect chapter headings in the text.

        Return a list of Chapter objects containing:
        - title: The chapter title
        - position: The character position in the text where the chapter starts
        """
        patterns = self.prepare_chapter_patterns()
        chapters: list[Chapter] = []
        for pattern in patterns:
            for match in pattern.finditer(page_text):
                title = re.sub(r"([\s\r\t\n]|<br/>)+", " ", match.group("title")).strip()
                position = match.start("title")
                chapters.append(
                    Chapter(
                        title=title,
                        position=position,
                    ),
                )
        return self._deduplicate_chapters(chapters)

    def _deduplicate_chapters(self, chapters: list[Chapter]) -> list[Chapter]:
        """Deduplicate chapters based on position and title."""
        if not chapters:
            return []
        sorted_chapters = sorted(chapters, key=lambda c: c.position)

        deduplicated: list[Chapter] = []
        seen_titles = set()

        for chapter in sorted_chapters:
            if chapter.title in seen_titles:
                continue
            if (
                not deduplicated
                or abs(deduplicated[-1].position - chapter.position) >= self.min_chapter_distance
            ):
                deduplicated.append(chapter)
                seen_titles.add(chapter.title)
        return deduplicated

    def prepare_chapter_patterns(self) -> list[re.Pattern[str]]:  # pylint: disable=too-many-locals
        """Prepare regex patterns for detecting chapter headings."""
        # Form 1: Chapter I, Chapter 1, Chapter the First, CHAPTER 1
        # Ways of enumerating chapters, e.g.
        space = r"[ \t]"
        line_sep = rf"{space}*(\r?\n|\u2028|\u2029|{space}*<br\/>{space}*)"
        arabic_numerals = r"\d+"
        roman_numerals = "(?=[MDCLXVI])M{0,3}(CM|CD|D?C{0,3})(XC|XL|L?X{0,3})(IX|IV|V?I{0,3})"
        number_words_by_tens_list = [
            "twenty",
            "thirty",
            "forty",
            "fifty",
            "sixty",
            "seventy",
            "eighty",
            "ninety",
        ]
        number_words_list = [
            "one",
            "two",
            "three",
            "four",
            "five",
            "six",
            "seven",
            "eight",
            "nine",
            "ten",
            "eleven",
            "twelve",
            "thirteen",
            "fourteen",
            "fifteen",
            "sixteen",
            "seventeen",
            "eighteen",
            "nineteen",
        ] + number_words_by_tens_list
        number_word = "(" + "|".join(number_words_list) + ")"
        ordinal_number_words_by_tens_list = [
            "twentieth",
            "thirtieth",
            "fortieth",
            "fiftieth",
            "sixtieth",
            "seventieth",
            "eightieth",
            "ninetieth",
        ] + number_words_by_tens_list
        ordinal_number_words_list = (
            [
                "first",
                "second",
                "third",
                "fourth",
                "fifth",
                "sixth",
                "seventh",
                "eighth",
                "ninth",
                "twelfth",
                "last",
            ]
            + [f"{numberWord}th" for numberWord in number_words_list]
        ) + ordinal_number_words_by_tens_list
        ordinal_word = "(the )?(" + "|".join(ordinal_number_words_list) + ")"
        enumerators = rf"({arabic_numerals}|{roman_numerals}|{number_word}|{ordinal_word})"
        chapter_name = r"[\w \t '`\"\.’\?!:\/-]{1,120}"
        name_line = rf"{line_sep}{space}*{chapter_name}{space}*"

        templ_key_word = (
            rf"(chapter|glava|глава|часть|том){space}+"
            rf"({enumerators}(\.|{space}){space}*)?({space}*{chapter_name})?({name_line})?"
        )
        templ_numbered = (
            rf"({arabic_numerals}|{roman_numerals})\.{space}*({chapter_name})?({name_line})?"
        )
        templ_numbered_dbl_empty_line = (
            rf"({arabic_numerals}|{roman_numerals})"
            rf"(\.|{space}){space}*({chapter_name})?({name_line})?{line_sep}"
        )
        prefix = rf"({line_sep}{line_sep}|\A)"
        return [
            re.compile(
                rf"{prefix}(?P<title>{templ_key_word}){line_sep}{line_sep}",
                re.IGNORECASE,
            ),
            re.compile(
                rf"{prefix}(?P<title>{templ_numbered}){line_sep}{line_sep}",
                re.IGNORECASE,
            ),
            re.compile(
                rf"{prefix}(?P<title>{templ_numbered_dbl_empty_line}){line_sep}{line_sep}",
                re.IGNORECASE,
            ),
        ]