python-pages 0.1.0__py3-none-any.whl

pages/api.py

@@ -0,0 +1,1869 @@
+"""Small python-docx-shaped object model backed by Pages IWA storage."""
+
+from __future__ import annotations
+
+from enum import IntEnum
+from pathlib import Path
+
+from .core_properties import CoreProperties
+from .document import (
+    DOCUMENT_BOTTOM_MARGIN,
+    DOCUMENT_FOOTER_MARGIN,
+    DOCUMENT_HEADER_MARGIN,
+    DOCUMENT_LEFT_MARGIN,
+    DOCUMENT_ORIENTATION,
+    DOCUMENT_PAGE_HEIGHT,
+    DOCUMENT_PAGE_WIDTH,
+    DOCUMENT_RIGHT_MARGIN,
+    DOCUMENT_TOP_MARGIN,
+    SECTION_FIRST_PAGE_DIFFERENT,
+    DocumentLayout,
+)
+from .pages import PagesDocument
+from .stylesheet import (
+    CharacterProperties,
+    LineSpacing,
+    ParagraphProperties,
+    ParagraphTab,
+    RGBColor,
+    character_style_properties,
+    paragraph_style_properties,
+    replace_character_background,
+    is_anonymous_style,
+    style_identifier,
+    style_name,
+)
+from .text import (
+    STORAGE_TABLE_CHAR_STYLE,
+    STORAGE_TABLE_PARA_STYLE,
+    TYPE_CHARACTER_STYLE,
+    TYPE_PARAGRAPH_STYLE,
+    AttributeRun,
+    add_object_reference,
+    codepoint_to_utf16,
+    encode_attribute_table,
+    parse_attribute_table,
+    replace_style_range,
+    replace_storage_text,
+    style_at,
+    utf16_to_codepoint,
+)
+from .components import append_attachment_run
+from .tables import CellStorage, TableStore, body_table_stores, clone_body_table
+from .pictures import ImageStore, body_image_stores, clone_body_image
+from .hyperlinks import HyperlinkStore, storage_hyperlinks
+from .comments import CommentStore, storage_comments
+
+
+class Length(float):
+    """Length stored internally in points."""
+
+    @property
+    def pt(self) -> float:
+        return float(self)
+
+    @property
+    def inches(self) -> float:
+        return float(self) / 72.0
+
+    @property
+    def cm(self) -> float:
+        return self.inches * 2.54
+
+
+class Pt(Length):
+    """Point measure compatible with the common ``Pt(12)`` calling shape."""
+
+    def __new__(cls, value: float):
+        return super().__new__(cls, float(value))
+
+    @property
+    def pt(self) -> float:
+        return float(self)
+
+
+class Inches(Length):
+    def __new__(cls, value: float):
+        return super().__new__(cls, float(value) * 72.0)
+
+
+class Cm(Length):
+    def __new__(cls, value: float):
+        return super().__new__(cls, float(value) * 72.0 / 2.54)
+
+
+class WD_PARAGRAPH_ALIGNMENT(IntEnum):
+    LEFT = 0
+    CENTER = 1
+    RIGHT = 2
+    JUSTIFY = 3
+
+
+WD_ALIGN_PARAGRAPH = WD_PARAGRAPH_ALIGNMENT
+
+
+class WD_LINE_SPACING(IntEnum):
+    SINGLE = 0
+    ONE_POINT_FIVE = 1
+    DOUBLE = 2
+    AT_LEAST = 3
+    EXACTLY = 4
+    MULTIPLE = 5
+
+
+class WD_TAB_ALIGNMENT(IntEnum):
+    LEFT = 0
+    CENTER = 1
+    RIGHT = 2
+    DECIMAL = 3
+
+
+class WD_TAB_LEADER(IntEnum):
+    SPACES = 0
+    DOTS = 1
+    DASHES = 2
+    LINES = 3
+    HEAVY = 4
+    MIDDLE_DOT = 5
+
+
+class WD_ORIENTATION(IntEnum):
+    PORTRAIT = 0
+    LANDSCAPE = 1
+
+
+WD_ORIENT = WD_ORIENTATION
+
+
+class WD_STYLE_TYPE(IntEnum):
+    PARAGRAPH = 1
+    CHARACTER = 2
+    TABLE = 3
+    LIST = 4
+
+
+class WD_COLOR_INDEX(IntEnum):
+    """Standard python-docx highlight-color palette."""
+
+    INHERITED = -1
+    AUTO = 0
+    BLACK = 1
+    BLUE = 2
+    TURQUOISE = 3
+    BRIGHT_GREEN = 4
+    PINK = 5
+    RED = 6
+    YELLOW = 7
+    WHITE = 8
+    DARK_BLUE = 9
+    TEAL = 10
+    GREEN = 11
+    VIOLET = 12
+    DARK_RED = 13
+    DARK_YELLOW = 14
+    GRAY_50 = 15
+    GRAY_25 = 16
+
+
+WD_COLOR = WD_COLOR_INDEX
+
+
+_API_TO_PAGES_ALIGNMENT = {
+    WD_PARAGRAPH_ALIGNMENT.LEFT: 0,
+    WD_PARAGRAPH_ALIGNMENT.RIGHT: 1,
+    WD_PARAGRAPH_ALIGNMENT.CENTER: 2,
+    WD_PARAGRAPH_ALIGNMENT.JUSTIFY: 3,
+}
+_PAGES_TO_API_ALIGNMENT = {value: key for key, value in _API_TO_PAGES_ALIGNMENT.items()}
+_LEADER_TO_STRING = {
+    WD_TAB_LEADER.SPACES: None,
+    WD_TAB_LEADER.DOTS: ".",
+    WD_TAB_LEADER.DASHES: "-",
+    WD_TAB_LEADER.LINES: "_",
+    WD_TAB_LEADER.HEAVY: "•",
+    WD_TAB_LEADER.MIDDLE_DOT: "·",
+}
+_STRING_TO_LEADER = {value: key for key, value in _LEADER_TO_STRING.items()}
+_HIGHLIGHT_TO_RGB = {
+    WD_COLOR_INDEX.AUTO: RGBColor(0x00, 0x00, 0x00),
+    WD_COLOR_INDEX.BLACK: RGBColor(0x00, 0x00, 0x00),
+    WD_COLOR_INDEX.BLUE: RGBColor(0x00, 0x00, 0xFF),
+    WD_COLOR_INDEX.TURQUOISE: RGBColor(0x00, 0xFF, 0xFF),
+    WD_COLOR_INDEX.BRIGHT_GREEN: RGBColor(0x00, 0xFF, 0x00),
+    WD_COLOR_INDEX.PINK: RGBColor(0xFF, 0x00, 0xFF),
+    WD_COLOR_INDEX.RED: RGBColor(0xFF, 0x00, 0x00),
+    WD_COLOR_INDEX.YELLOW: RGBColor(0xFF, 0xFF, 0x00),
+    WD_COLOR_INDEX.WHITE: RGBColor(0xFF, 0xFF, 0xFF),
+    WD_COLOR_INDEX.DARK_BLUE: RGBColor(0x00, 0x00, 0x80),
+    WD_COLOR_INDEX.TEAL: RGBColor(0x00, 0x80, 0x80),
+    WD_COLOR_INDEX.GREEN: RGBColor(0x00, 0x80, 0x00),
+    WD_COLOR_INDEX.VIOLET: RGBColor(0x80, 0x00, 0x80),
+    WD_COLOR_INDEX.DARK_RED: RGBColor(0x80, 0x00, 0x00),
+    WD_COLOR_INDEX.DARK_YELLOW: RGBColor(0x80, 0x80, 0x00),
+    WD_COLOR_INDEX.GRAY_50: RGBColor(0x80, 0x80, 0x80),
+    WD_COLOR_INDEX.GRAY_25: RGBColor(0xC0, 0xC0, 0xC0),
+}
+_RGB_TO_HIGHLIGHT = {
+    rgb: color
+    for color, rgb in _HIGHLIGHT_TO_RGB.items()
+    if color is not WD_COLOR_INDEX.AUTO
+}
+
+_SCRIPT_SUPERSCRIPT = 1
+_SCRIPT_SUBSCRIPT = 2
+
+
+class ColorFormat:
+    def __init__(self, run: "Run"):
+        self._run = run
+
+    @property
+    def rgb(self) -> RGBColor | None:
+        return self._run._properties.color
+
+    @rgb.setter
+    def rgb(self, value: RGBColor | str | tuple[int, int, int] | None) -> None:
+        if isinstance(value, str):
+            value = RGBColor.from_string(value)
+        elif isinstance(value, tuple):
+            value = RGBColor(*value)
+        if value is not None and not isinstance(value, RGBColor):
+            raise TypeError("rgb must be RGBColor, a 3-tuple, a hex string, or None")
+        self._run._set_property("color", value)
+
+
+class Font:
+    def __init__(self, run: "Run"):
+        self._run = run
+
+    @property
+    def name(self) -> str | None:
+        return self._run._properties.font_name
+
+    @name.setter
+    def name(self, value: str | None) -> None:
+        if value is not None and not isinstance(value, str):
+            raise TypeError("font name must be a string or None")
+        self._run._set_property("font_name", value)
+
+    @property
+    def size(self) -> Pt | None:
+        value = self._run._properties.font_size
+        return None if value is None else Pt(value)
+
+    @size.setter
+    def size(self, value: Pt | float | int | None) -> None:
+        self._run._set_property("font_size", None if value is None else float(value))
+
+    @property
+    def color(self) -> ColorFormat:
+        return ColorFormat(self._run)
+
+    @property
+    def bold(self) -> bool | None:
+        return self._run._properties.bold
+
+    @bold.setter
+    def bold(self, value: bool | None) -> None:
+        self._run._set_bool("bold", value)
+
+    @property
+    def italic(self) -> bool | None:
+        return self._run._properties.italic
+
+    @italic.setter
+    def italic(self, value: bool | None) -> None:
+        self._run._set_bool("italic", value)
+
+    @property
+    def underline(self) -> bool | None:
+        return self._run._properties.underline
+
+    @underline.setter
+    def underline(self, value: bool | None) -> None:
+        self._run._set_bool("underline", value)
+
+    @property
+    def strike(self) -> bool | None:
+        return self._run._properties.strike
+
+    @strike.setter
+    def strike(self, value: bool | None) -> None:
+        self._run._set_bool("strike", value)
+
+    @property
+    def subscript(self) -> bool | None:
+        value = self._run._properties.vertical_align
+        return None if value is None else value == _SCRIPT_SUBSCRIPT
+
+    @subscript.setter
+    def subscript(self, value: bool | None) -> None:
+        self._set_script(value, _SCRIPT_SUBSCRIPT, "subscript")
+
+    @property
+    def superscript(self) -> bool | None:
+        value = self._run._properties.vertical_align
+        return None if value is None else value == _SCRIPT_SUPERSCRIPT
+
+    @superscript.setter
+    def superscript(self, value: bool | None) -> None:
+        self._set_script(value, _SCRIPT_SUPERSCRIPT, "superscript")
+
+    def _set_script(self, value: bool | None, target: int, name: str) -> None:
+        if value is not None and not isinstance(value, bool):
+            raise TypeError(f"{name} must be True, False, or None")
+        current = self._run._properties.vertical_align
+        if value is None:
+            replacement = None
+        elif value:
+            replacement = target
+        elif current == target:
+            replacement = None
+        else:
+            return
+        self._run._set_property("vertical_align", replacement)
+
+    @property
+    def highlight_color(self) -> WD_COLOR_INDEX | None:
+        paragraph = self._run._paragraph
+        if paragraph is None:
+            return None
+        return paragraph.highlight_color
+
+    @highlight_color.setter
+    def highlight_color(self, value: WD_COLOR_INDEX | int | None) -> None:
+        if value is None:
+            color = None
+        else:
+            try:
+                palette = WD_COLOR_INDEX(value)
+            except ValueError as error:
+                raise ValueError(f"unsupported highlight color: {value!r}") from error
+            color = (
+                None
+                if palette is WD_COLOR_INDEX.INHERITED
+                else _HIGHLIGHT_TO_RGB[palette]
+            )
+        paragraph = self._run._paragraph
+        if paragraph is None:
+            raise NotImplementedError(
+                "Pages character background is paragraph-scoped; this run has no paragraph"
+            )
+        paragraph.background_color = color
+
+
+class Run:
+    def __init__(
+        self,
+        document: "Document",
+        start_utf16: int,
+        end_utf16: int,
+        paragraph: "Paragraph | None" = None,
+    ):
+        self._document = document
+        self._start_utf16 = start_utf16
+        self._end_utf16 = end_utf16
+        self._paragraph = paragraph
+
+    @property
+    def text(self) -> str:
+        return self._document._text_between(self._start_utf16, self._end_utf16)
+
+    @text.setter
+    def text(self, value: str) -> None:
+        if "\n" in value or "\r" in value:
+            raise ValueError("Run.text cannot contain paragraph separators")
+        delta = self._document._replace_text(self._start_utf16, self._end_utf16, value)
+        self._end_utf16 += delta
+        if self._paragraph is not None:
+            self._paragraph._end_utf16 += delta
+            self._paragraph._next_start_utf16 += delta
+
+    def clear(self) -> "Run":
+        """Remove this run's text while retaining its character formatting."""
+        self.text = ""
+        return self
+
+    def delete(self) -> None:
+        """Remove this run's text from its paragraph."""
+        self.clear()
+
+    @property
+    def _properties(self) -> CharacterProperties:
+        return self._document._properties_at(self._start_utf16)
+
+    def _set_property(self, name: str, value) -> None:
+        props = self._properties.with_value(name, value)
+        self._document._apply_properties(self._start_utf16, self._end_utf16, props)
+
+    def _set_bool(self, name: str, value: bool | None) -> None:
+        if value is not None and not isinstance(value, bool):
+            raise TypeError(f"{name} must be True, False, or None")
+        self._set_property(name, value)
+
+    @property
+    def font(self) -> Font:
+        return Font(self)
+
+    @property
+    def bold(self) -> bool | None:
+        return self.font.bold
+
+    @bold.setter
+    def bold(self, value: bool | None) -> None:
+        self.font.bold = value
+
+    @property
+    def italic(self) -> bool | None:
+        return self.font.italic
+
+    @italic.setter
+    def italic(self, value: bool | None) -> None:
+        self.font.italic = value
+
+    @property
+    def underline(self) -> bool | None:
+        return self.font.underline
+
+    @underline.setter
+    def underline(self, value: bool | None) -> None:
+        self.font.underline = value
+
+    @property
+    def style(self) -> "Style | None":
+        return self._document._style_from_id(
+            self._document._character_style_id_at(self._start_utf16),
+            WD_STYLE_TYPE.CHARACTER,
+        )
+
+    @style.setter
+    def style(self, value: "Style | str | None") -> None:
+        identifier = self._document._coerce_style_id(
+            value, WD_STYLE_TYPE.CHARACTER, none_identifier=None
+        )
+        self._document._apply_character_style_id(
+            self._start_utf16, self._end_utf16, identifier
+        )
+
+
+class TabStop:
+    def __init__(self, spec: ParagraphTab):
+        self._spec = spec
+
+    @property
+    def position(self) -> Pt:
+        return Pt(self._spec.position)
+
+    @property
+    def alignment(self) -> WD_TAB_ALIGNMENT:
+        return WD_TAB_ALIGNMENT(self._spec.alignment)
+
+    @property
+    def leader(self) -> WD_TAB_LEADER:
+        return _STRING_TO_LEADER.get(self._spec.leader, WD_TAB_LEADER.SPACES)
+
+
+class TabStops:
+    def __init__(self, paragraph: "Paragraph"):
+        self._paragraph = paragraph
+
+    def _specs(self) -> tuple[ParagraphTab, ...]:
+        return self._paragraph._paragraph_properties.tabs or ()
+
+    def __len__(self) -> int:
+        return len(self._specs())
+
+    def __iter__(self):
+        return iter([TabStop(spec) for spec in self._specs()])
+
+    def __getitem__(self, index: int) -> TabStop:
+        return TabStop(self._specs()[index])
+
+    def add_tab_stop(
+        self,
+        position: Length | float,
+        alignment: WD_TAB_ALIGNMENT = WD_TAB_ALIGNMENT.LEFT,
+        leader: WD_TAB_LEADER = WD_TAB_LEADER.SPACES,
+    ) -> TabStop:
+        try:
+            alignment = WD_TAB_ALIGNMENT(alignment)
+            leader = WD_TAB_LEADER(leader)
+        except ValueError as error:
+            raise ValueError("unsupported tab alignment or leader") from error
+        spec = ParagraphTab(float(position), int(alignment), _LEADER_TO_STRING[leader])
+        values = tuple(sorted(self._specs() + (spec,), key=lambda item: item.position))
+        self._paragraph._set_paragraph_property("tabs", values)
+        return TabStop(spec)
+
+    def clear_all(self) -> None:
+        self._paragraph._set_paragraph_property("tabs", None)
+
+
+class ParagraphFormat:
+    def __init__(self, paragraph: "Paragraph"):
+        self._paragraph = paragraph
+
+    @property
+    def alignment(self) -> WD_PARAGRAPH_ALIGNMENT | None:
+        value = self._paragraph._paragraph_properties.alignment
+        return _PAGES_TO_API_ALIGNMENT.get(value)
+
+    @alignment.setter
+    def alignment(self, value: WD_PARAGRAPH_ALIGNMENT | None) -> None:
+        if value is None:
+            encoded = None
+        else:
+            try:
+                encoded = _API_TO_PAGES_ALIGNMENT[WD_PARAGRAPH_ALIGNMENT(value)]
+            except (KeyError, ValueError) as error:
+                raise ValueError(f"unsupported paragraph alignment: {value!r}") from error
+        self._paragraph._set_paragraph_property("alignment", encoded)
+
+    @staticmethod
+    def _length(value: float | None) -> Pt | None:
+        return None if value is None else Pt(value)
+
+    @property
+    def first_line_indent(self) -> Pt | None:
+        return self._length(self._paragraph._paragraph_properties.first_line_indent)
+
+    @first_line_indent.setter
+    def first_line_indent(self, value: Length | float | None) -> None:
+        self._paragraph._set_paragraph_property(
+            "first_line_indent", None if value is None else float(value)
+        )
+
+    @property
+    def left_indent(self) -> Pt | None:
+        return self._length(self._paragraph._paragraph_properties.left_indent)
+
+    @left_indent.setter
+    def left_indent(self, value: Length | float | None) -> None:
+        self._paragraph._set_paragraph_property(
+            "left_indent", None if value is None else float(value)
+        )
+
+    @property
+    def right_indent(self) -> Pt | None:
+        return self._length(self._paragraph._paragraph_properties.right_indent)
+
+    @right_indent.setter
+    def right_indent(self, value: Length | float | None) -> None:
+        self._paragraph._set_paragraph_property(
+            "right_indent", None if value is None else float(value)
+        )
+
+    @property
+    def space_before(self) -> Pt | None:
+        return self._length(self._paragraph._paragraph_properties.space_before)
+
+    @space_before.setter
+    def space_before(self, value: Length | float | None) -> None:
+        self._paragraph._set_paragraph_property(
+            "space_before", None if value is None else float(value)
+        )
+
+    @property
+    def space_after(self) -> Pt | None:
+        return self._length(self._paragraph._paragraph_properties.space_after)
+
+    @space_after.setter
+    def space_after(self, value: Length | float | None) -> None:
+        self._paragraph._set_paragraph_property(
+            "space_after", None if value is None else float(value)
+        )
+
+    @property
+    def line_spacing(self) -> float | Pt | None:
+        spacing = self._paragraph._paragraph_properties.line_spacing
+        if spacing is None:
+            return None
+        return spacing.amount if spacing.mode == 0 else Pt(spacing.amount)
+
+    @line_spacing.setter
+    def line_spacing(self, value: Length | float | None) -> None:
+        if value is None:
+            spacing = None
+        elif isinstance(value, Length):
+            spacing = LineSpacing(2, float(value))
+        else:
+            spacing = LineSpacing(0, float(value))
+        self._paragraph._set_paragraph_property("line_spacing", spacing)
+
+    @property
+    def line_spacing_rule(self) -> WD_LINE_SPACING | None:
+        spacing = self._paragraph._paragraph_properties.line_spacing
+        if spacing is None:
+            return None
+        if spacing.mode == 0:
+            if spacing.amount == 1.0:
+                return WD_LINE_SPACING.SINGLE
+            if spacing.amount == 1.5:
+                return WD_LINE_SPACING.ONE_POINT_FIVE
+            if spacing.amount == 2.0:
+                return WD_LINE_SPACING.DOUBLE
+            return WD_LINE_SPACING.MULTIPLE
+        if spacing.mode == 1:
+            return WD_LINE_SPACING.AT_LEAST
+        if spacing.mode == 2:
+            return WD_LINE_SPACING.EXACTLY
+        return WD_LINE_SPACING.MULTIPLE
+
+    @line_spacing_rule.setter
+    def line_spacing_rule(self, value: WD_LINE_SPACING | None) -> None:
+        if value is None:
+            self._paragraph._set_paragraph_property("line_spacing", None)
+            return
+        value = WD_LINE_SPACING(value)
+        current = self._paragraph._paragraph_properties.line_spacing
+        if value == WD_LINE_SPACING.SINGLE:
+            spacing = LineSpacing(0, 1.0)
+        elif value == WD_LINE_SPACING.ONE_POINT_FIVE:
+            spacing = LineSpacing(0, 1.5)
+        elif value == WD_LINE_SPACING.DOUBLE:
+            spacing = LineSpacing(0, 2.0)
+        elif value == WD_LINE_SPACING.AT_LEAST:
+            spacing = LineSpacing(1, current.amount if current else 12.0)
+        elif value == WD_LINE_SPACING.EXACTLY:
+            spacing = LineSpacing(2, current.amount if current else 12.0)
+        else:
+            spacing = LineSpacing(0, current.amount if current else 1.0)
+        self._paragraph._set_paragraph_property("line_spacing", spacing)
+
+    @property
+    def tab_stops(self) -> TabStops:
+        return TabStops(self._paragraph)
+
+
+class Paragraph:
+    def __init__(
+        self,
+        document: "Document",
+        start_utf16: int,
+        end_utf16: int,
+        next_start_utf16: int,
+    ):
+        self._document = document
+        self._start_utf16 = start_utf16
+        self._end_utf16 = end_utf16
+        self._next_start_utf16 = next_start_utf16
+
+    @property
+    def style_id(self) -> int | None:
+        return self._document._paragraph_style_id_at(self._start_utf16)
+
+    @property
+    def style(self) -> "Style | None":
+        return self._document._style_from_id(
+            self.style_id, WD_STYLE_TYPE.PARAGRAPH
+        )
+
+    @style.setter
+    def style(self, value: "Style | str | None") -> None:
+        default = self._document._package.stylesheet().default_paragraph_style()
+        identifier = self._document._coerce_style_id(
+            value,
+            WD_STYLE_TYPE.PARAGRAPH,
+            none_identifier=default.segment.identifier,
+        )
+        self._document._apply_paragraph_style_id(
+            self._start_utf16, self._next_start_utf16, identifier
+        )
+
+    @property
+    def _paragraph_properties(self) -> ParagraphProperties:
+        return self._document._paragraph_properties_at(self._start_utf16)
+
+    @property
+    def background_color(self) -> RGBColor | None:
+        """Direct Pages character background carried by this paragraph style."""
+
+        return self._document._paragraph_character_properties_at(
+            self._start_utf16
+        ).background_color
+
+    @background_color.setter
+    def background_color(
+        self, value: RGBColor | str | tuple[int, int, int] | None
+    ) -> None:
+        if isinstance(value, str):
+            value = RGBColor.from_string(value)
+        elif isinstance(value, tuple):
+            value = RGBColor(*value)
+        if value is not None and not isinstance(value, RGBColor):
+            raise TypeError(
+                "background_color must be RGBColor, a 3-tuple, a hex string, or None"
+            )
+        self._document._apply_paragraph_background(
+            self._start_utf16,
+            self._next_start_utf16,
+            value,
+        )
+
+    @property
+    def highlight_color(self) -> WD_COLOR_INDEX | None:
+        color = self.background_color
+        return None if color is None else _RGB_TO_HIGHLIGHT.get(color)
+
+    @highlight_color.setter
+    def highlight_color(self, value: WD_COLOR_INDEX | int | None) -> None:
+        if value is None:
+            color = None
+        else:
+            try:
+                palette = WD_COLOR_INDEX(value)
+            except ValueError as error:
+                raise ValueError(f"unsupported highlight color: {value!r}") from error
+            color = (
+                None
+                if palette is WD_COLOR_INDEX.INHERITED
+                else _HIGHLIGHT_TO_RGB[palette]
+            )
+        self.background_color = color
+
+    def _set_paragraph_property(self, name: str, value) -> None:
+        props = self._paragraph_properties.with_value(name, value)
+        self._document._apply_paragraph_properties(
+            self._start_utf16,
+            self._next_start_utf16,
+            props,
+        )
+
+    @property
+    def text(self) -> str:
+        return self._document._text_between(self._start_utf16, self._end_utf16)
+
+    @property
+    def runs(self) -> list[Run]:
+        if self._start_utf16 == self._end_utf16:
+            return []
+        boundaries = {self._start_utf16, self._end_utf16}
+        boundaries.update(
+            run.character_index
+            for run in self._document._character_runs()
+            if self._start_utf16 < run.character_index < self._end_utf16
+        )
+        ordered = sorted(boundaries)
+        return [
+            Run(self._document, start, end, self)
+            for start, end in zip(ordered, ordered[1:])
+        ]
+
+    @property
+    def hyperlinks(self) -> list["Hyperlink"]:
+        return [
+            hyperlink
+            for hyperlink in self._document.hyperlinks
+            if self._start_utf16 <= hyperlink._start_utf16
+            and hyperlink._end_utf16 <= self._end_utf16
+        ]
+
+    def add_run(self, text: str | None = None, style=None) -> Run:
+        value = "" if text is None else text
+        if not isinstance(value, str):
+            raise TypeError("run text must be a string or None")
+        if "\n" in value or "\r" in value:
+            raise ValueError("add_run text cannot contain paragraph separators")
+        start = self._end_utf16
+        delta = self._document._replace_text(start, start, value)
+        self._end_utf16 += delta
+        self._next_start_utf16 += delta
+        run = Run(self._document, start, start + delta, self)
+        if style is not None:
+            run.style = style
+        elif delta:
+            # Inserting at an existing run boundary shifts that boundary with
+            # the new text. A python-docx add_run() without an explicit style
+            # starts with inherited formatting, so restore the no-direct-style
+            # boundary across the inserted range.
+            self._document._apply_character_style_id(start, start + delta, None)
+        return run
+
+    def clear(self) -> "Paragraph":
+        """Remove paragraph content while retaining its paragraph mark and style."""
+        delta = self._document._replace_text(
+            self._start_utf16, self._end_utf16, ""
+        )
+        self._end_utf16 += delta
+        self._next_start_utf16 += delta
+        return self
+
+    def delete(self) -> None:
+        """Remove this paragraph and its paragraph separator when possible."""
+        paragraphs = self._document.paragraphs
+        if len(paragraphs) == 1:
+            self.clear()
+            return
+        position = next(
+            (
+                index
+                for index, paragraph in enumerate(paragraphs)
+                if paragraph._start_utf16 == self._start_utf16
+            ),
+            None,
+        )
+        if position is None:
+            raise ValueError("paragraph no longer exists in the document")
+        if position < len(paragraphs) - 1:
+            start, end = self._start_utf16, self._next_start_utf16
+        else:
+            start, end = self._start_utf16 - 1, self._end_utf16
+        self._document._replace_text(start, end, "")
+        self._end_utf16 = self._start_utf16
+        self._next_start_utf16 = self._start_utf16
+
+    @property
+    def paragraph_format(self) -> ParagraphFormat:
+        return ParagraphFormat(self)
+
+    @property
+    def alignment(self) -> WD_PARAGRAPH_ALIGNMENT | None:
+        return self.paragraph_format.alignment
+
+    @alignment.setter
+    def alignment(self, value: WD_PARAGRAPH_ALIGNMENT | None) -> None:
+        self.paragraph_format.alignment = value
+
+
+class HeaderFooterParagraph:
+    """A Pages header/footer fragment exposed with paragraph text semantics."""
+
+    def __init__(self, layout: DocumentLayout, storage):
+        self._layout = layout
+        self._storage = storage
+
+    @property
+    def text(self) -> str:
+        return self._layout.storage_text(self._storage)
+
+    @text.setter
+    def text(self, value: str) -> None:
+        self._layout.set_storage_text(self._storage, value)
+
+
+class HeaderFooter:
+    """Header/footer proxy over Pages' left, center, and right fragments."""
+
+    def __init__(self, layout: DocumentLayout, kind: str, *, footer: bool):
+        self._layout = layout
+        self._kind = kind
+        self._footer = footer
+
+    @property
+    def paragraphs(self) -> list[HeaderFooterParagraph]:
+        return [
+            HeaderFooterParagraph(self._layout, storage)
+            for storage in self._layout.header_footer_storages(
+                self._kind, footer=self._footer
+            )
+        ]
+
+    @property
+    def text(self) -> str:
+        return "\t".join(paragraph.text for paragraph in self.paragraphs)
+
+    @text.setter
+    def text(self, value: str) -> None:
+        self.paragraphs[0].text = value
+
+    @property
+    def is_linked_to_previous(self) -> bool:
+        return False
+
+    @is_linked_to_previous.setter
+    def is_linked_to_previous(self, value: bool) -> None:
+        if value:
+            raise NotImplementedError("Pages single-section mode has no previous section")
+
+
+class Section:
+    """python-docx-shaped facade over the package-wide Pages page settings."""
+
+    _LENGTH_FIELDS = {
+        "page_width": DOCUMENT_PAGE_WIDTH,
+        "page_height": DOCUMENT_PAGE_HEIGHT,
+        "left_margin": DOCUMENT_LEFT_MARGIN,
+        "right_margin": DOCUMENT_RIGHT_MARGIN,
+        "top_margin": DOCUMENT_TOP_MARGIN,
+        "bottom_margin": DOCUMENT_BOTTOM_MARGIN,
+        "header_distance": DOCUMENT_HEADER_MARGIN,
+        "footer_distance": DOCUMENT_FOOTER_MARGIN,
+    }
+
+    def __init__(self, layout: DocumentLayout):
+        self._layout = layout
+
+    def _length(self, name: str) -> Pt | None:
+        value = self._layout.fixed32(self._LENGTH_FIELDS[name])
+        return None if value is None else Pt(value)
+
+    def _set_length(self, name: str, value: Length | float | None) -> None:
+        self._layout.set_fixed32(
+            self._LENGTH_FIELDS[name], None if value is None else float(value)
+        )
+
+    @property
+    def page_width(self) -> Pt | None:
+        return self._length("page_width")
+
+    @page_width.setter
+    def page_width(self, value: Length | float | None) -> None:
+        self._set_length("page_width", value)
+
+    @property
+    def page_height(self) -> Pt | None:
+        return self._length("page_height")
+
+    @page_height.setter
+    def page_height(self, value: Length | float | None) -> None:
+        self._set_length("page_height", value)
+
+    @property
+    def left_margin(self) -> Pt | None:
+        return self._length("left_margin")
+
+    @left_margin.setter
+    def left_margin(self, value: Length | float | None) -> None:
+        self._set_length("left_margin", value)
+
+    @property
+    def right_margin(self) -> Pt | None:
+        return self._length("right_margin")
+
+    @right_margin.setter
+    def right_margin(self, value: Length | float | None) -> None:
+        self._set_length("right_margin", value)
+
+    @property
+    def top_margin(self) -> Pt | None:
+        return self._length("top_margin")
+
+    @top_margin.setter
+    def top_margin(self, value: Length | float | None) -> None:
+        self._set_length("top_margin", value)
+
+    @property
+    def bottom_margin(self) -> Pt | None:
+        return self._length("bottom_margin")
+
+    @bottom_margin.setter
+    def bottom_margin(self, value: Length | float | None) -> None:
+        self._set_length("bottom_margin", value)
+
+    @property
+    def header_distance(self) -> Pt | None:
+        return self._length("header_distance")
+
+    @header_distance.setter
+    def header_distance(self, value: Length | float | None) -> None:
+        self._set_length("header_distance", value)
+
+    @property
+    def footer_distance(self) -> Pt | None:
+        return self._length("footer_distance")
+
+    @footer_distance.setter
+    def footer_distance(self, value: Length | float | None) -> None:
+        self._set_length("footer_distance", value)
+
+    @property
+    def orientation(self) -> WD_ORIENTATION:
+        return WD_ORIENTATION(self._layout.varint(DOCUMENT_ORIENTATION))
+
+    @orientation.setter
+    def orientation(self, value: WD_ORIENTATION | None) -> None:
+        self._layout.set_varint(
+            DOCUMENT_ORIENTATION,
+            None if value is None else int(WD_ORIENTATION(value)),
+        )
+
+    @property
+    def different_first_page_header_footer(self) -> bool:
+        return self._layout.section_flag(SECTION_FIRST_PAGE_DIFFERENT)
+
+    @different_first_page_header_footer.setter
+    def different_first_page_header_footer(self, value: bool) -> None:
+        if not isinstance(value, bool):
+            raise TypeError("different_first_page_header_footer must be bool")
+        self._layout.set_section_flag(SECTION_FIRST_PAGE_DIFFERENT, value)
+
+    @property
+    def header(self) -> HeaderFooter:
+        return HeaderFooter(self._layout, "primary", footer=False)
+
+    @property
+    def footer(self) -> HeaderFooter:
+        return HeaderFooter(self._layout, "primary", footer=True)
+
+    @property
+    def first_page_header(self) -> HeaderFooter:
+        return HeaderFooter(self._layout, "first", footer=False)
+
+    @property
+    def first_page_footer(self) -> HeaderFooter:
+        return HeaderFooter(self._layout, "first", footer=True)
+
+    @property
+    def even_page_header(self) -> HeaderFooter:
+        return HeaderFooter(self._layout, "even", footer=False)
+
+    @property
+    def even_page_footer(self) -> HeaderFooter:
+        return HeaderFooter(self._layout, "even", footer=True)
+
+
+class TableCellFont:
+    """Read-only font facade for a table cell's effective text style."""
+
+    def __init__(self, run: "TableCellRun"):
+        self._run = run
+
+    @property
+    def bold(self) -> bool | None:
+        return self._run._properties.bold
+
+    @property
+    def italic(self) -> bool | None:
+        return self._run._properties.italic
+
+    @property
+    def underline(self) -> bool | None:
+        return self._run._properties.underline
+
+    @property
+    def strike(self) -> bool | None:
+        return self._run._properties.strike
+
+    @property
+    def name(self) -> str | None:
+        return self._run._properties.font_name
+
+    @property
+    def size(self) -> Pt | None:
+        value = self._run._properties.font_size
+        return None if value is None else Pt(value)
+
+
+class TableCellRun:
+    def __init__(self, cell: "TableCell"):
+        self._cell = cell
+
+    @property
+    def text(self) -> str:
+        return self._cell.text
+
+    @text.setter
+    def text(self, value: str) -> None:
+        self._cell.text = value
+
+    @property
+    def _properties(self) -> CharacterProperties:
+        return self._cell._properties
+
+    @property
+    def font(self) -> TableCellFont:
+        return TableCellFont(self)
+
+    @property
+    def bold(self) -> bool | None:
+        return self.font.bold
+
+    @property
+    def italic(self) -> bool | None:
+        return self.font.italic
+
+    @property
+    def underline(self) -> bool | None:
+        return self.font.underline
+
+
+class TableCellParagraph:
+    def __init__(self, cell: "TableCell"):
+        self._cell = cell
+
+    @property
+    def text(self) -> str:
+        return self._cell.text
+
+    @property
+    def runs(self) -> list[TableCellRun]:
+        return [] if not self.text else [TableCellRun(self._cell)]
+
+
+class TableCell:
+    """python-docx-shaped cell facade over one TST tile coordinate."""
+
+    def __init__(self, table: "Table", row: int, column: int):
+        self._table = table
+        self._row = row
+        self._column = column
+
+    @property
+    def _storage(self) -> CellStorage | None:
+        return self._table._store.cell_storage(self._row, self._column)
+
+    @property
+    def _properties(self) -> CharacterProperties:
+        return self._table._store.character_properties(
+            self._row, self._column, self._storage
+        )
+
+    @property
+    def text(self) -> str:
+        storage = self._storage
+        if storage is None:
+            return ""
+        if storage.cell_type != 3 or storage.string_id is None:
+            raise NotImplementedError("this TST cell value type is not textual")
+        return self._table._store.string(storage.string_id)
+
+    @text.setter
+    def text(self, value: str) -> None:
+        if not isinstance(value, str):
+            raise TypeError("cell text must be a string")
+        storage = self._storage
+        if storage is None:
+            raise NotImplementedError(
+                "creating storage for an omitted empty cell is deferred"
+            )
+        if storage.cell_type != 3 or storage.string_id is None:
+            raise NotImplementedError("retyping non-text TST cells is deferred")
+        self._table._store.set_string(storage.string_id, value)
+
+    @property
+    def paragraphs(self) -> list[TableCellParagraph]:
+        return [TableCellParagraph(self)]
+
+    @property
+    def runs(self) -> list[TableCellRun]:
+        return self.paragraphs[0].runs
+
+
+class TableRow:
+    def __init__(self, table: "Table", index: int):
+        self._table = table
+        self._index = index
+
+    @property
+    def cells(self) -> list[TableCell]:
+        return [
+            self._table.cell(self._index, column)
+            for column in range(len(self._table.columns))
+        ]
+
+
+class TableColumn:
+    def __init__(self, table: "Table", index: int):
+        self._table = table
+        self._index = index
+
+    @property
+    def cells(self) -> list[TableCell]:
+        return [
+            self._table.cell(row, self._index)
+            for row in range(len(self._table.rows))
+        ]
+
+
+class Table:
+    def __init__(self, store: TableStore):
+        self._store = store
+
+    @property
+    def name(self) -> str:
+        return self._store.name
+
+    @property
+    def rows(self) -> list[TableRow]:
+        return [TableRow(self, row) for row in range(self._store.rows)]
+
+    @property
+    def columns(self) -> list[TableColumn]:
+        return [TableColumn(self, column) for column in range(self._store.columns)]
+
+    def cell(self, row: int, column: int) -> TableCell:
+        if (
+            not 0 <= row < self._store.rows
+            or not 0 <= column < self._store.columns
+        ):
+            raise IndexError("table cell index is out of range")
+        return TableCell(self, row, column)
+
+
+class InlineShape:
+    """Inline Pages image with package-backed media access."""
+
+    def __init__(self, store: ImageStore):
+        self._store = store
+
+    @property
+    def filename(self) -> str:
+        return self._store.filename
+
+    @property
+    def blob(self) -> bytes:
+        return self._store.blob
+
+    @property
+    def thumbnail_blob(self) -> bytes | None:
+        return self._store.thumbnail_blob
+
+    @property
+    def width(self) -> Pt | None:
+        size = self._store.natural_size
+        return None if size is None else Pt(size[0])
+
+    @property
+    def height(self) -> Pt | None:
+        size = self._store.natural_size
+        return None if size is None else Pt(size[1])
+
+    def replace(
+        self,
+        path: str | Path,
+        thumbnail_path: str | Path | None = None,
+    ) -> "InlineShape":
+        thumbnail = (
+            None if thumbnail_path is None else Path(thumbnail_path).read_bytes()
+        )
+        self._store.replace(Path(path).read_bytes(), thumbnail)
+        return self
+
+
+class Hyperlink:
+    """Text-range facade for a TSWP.HyperlinkFieldArchive."""
+
+    def __init__(self, document: "Document", store: HyperlinkStore):
+        self._document = document
+        self._store = store
+        self._start_utf16 = store.start_utf16
+        self._end_utf16 = store.end_utf16
+
+    @property
+    def text(self) -> str:
+        return self._document._text_between(self._start_utf16, self._end_utf16)
+
+    @text.setter
+    def text(self, value: str) -> None:
+        if not isinstance(value, str):
+            raise TypeError("hyperlink text must be a string")
+        if "\n" in value or "\r" in value:
+            raise ValueError("hyperlink text cannot contain paragraph separators")
+        delta = self._document._replace_text(
+            self._start_utf16, self._end_utf16, value
+        )
+        self._end_utf16 += delta
+
+    @property
+    def url(self) -> str:
+        return self._store.url
+
+    @url.setter
+    def url(self, value: str) -> None:
+        self._store.url = value
+
+    @property
+    def address(self) -> str:
+        return self.url
+
+    @address.setter
+    def address(self, value: str) -> None:
+        self.url = value
+
+    @property
+    def runs(self) -> list[Run]:
+        return [Run(self._document, self._start_utf16, self._end_utf16)]
+
+
+class Style:
+    """Named Pages style exposed with the common python-docx attributes."""
+
+    def __init__(self, document: "Document", obj):
+        self._document = document
+        self._obj = obj
+
+    @property
+    def name(self) -> str:
+        return style_name(self._obj) or str(self._obj.segment.identifier)
+
+    @property
+    def style_id(self) -> str:
+        return style_identifier(self._obj) or str(self._obj.segment.identifier)
+
+    @property
+    def type(self) -> WD_STYLE_TYPE:
+        return (
+            WD_STYLE_TYPE.CHARACTER
+            if self._obj.info.type_id == TYPE_CHARACTER_STYLE
+            else WD_STYLE_TYPE.PARAGRAPH
+        )
+
+
+class Styles:
+    def __init__(self, document: "Document"):
+        self._document = document
+
+    def _items(self) -> list[Style]:
+        return [
+            Style(self._document, obj)
+            for obj in self._document._package.stylesheet().named_styles()
+        ]
+
+    def __len__(self) -> int:
+        return len(self._items())
+
+    def __iter__(self):
+        return iter(self._items())
+
+    def __getitem__(self, name: str) -> Style:
+        for style in self._items():
+            if style.name == name:
+                return style
+        raise KeyError(f"style {name!r} was not found")
+
+
+class Comment:
+    """Pages-backed comment or reply."""
+
+    def __init__(self, document: "Document", store: CommentStore):
+        self._document = document
+        self._store = store
+
+    @property
+    def comment_id(self) -> int:
+        return self._store.comment_id
+
+    @property
+    def text(self) -> str:
+        return self._store.text
+
+    @text.setter
+    def text(self, value: str) -> None:
+        self._store.text = value
+
+    @property
+    def author(self) -> str:
+        return self._store.author
+
+    @property
+    def annotation_color(self) -> RGBColor | None:
+        """Review-highlight color assigned to this comment's author."""
+        return self._store.annotation_color
+
+    @property
+    def initials(self) -> None:
+        """Pages stores no separate initials value for an annotation author."""
+        return None
+
+    @property
+    def timestamp(self):
+        return self._store.timestamp
+
+    @property
+    def replies(self) -> list["Comment"]:
+        return [Comment(self._document, reply) for reply in self._store.replies]
+
+    @property
+    def anchor_start(self) -> int | None:
+        return self._store.start_utf16
+
+    @property
+    def anchor_end(self) -> int | None:
+        return self._store.end_utf16
+
+    @property
+    def anchor_text(self) -> str:
+        if self.anchor_start is None or self.anchor_end is None:
+            return ""
+        return self._document._text_between(self.anchor_start, self.anchor_end)
+
+
+class Comments:
+    """Collection of root comments anchored in the Pages body storage."""
+
+    def __init__(self, document: "Document"):
+        self._document = document
+
+    def _items(self) -> list[Comment]:
+        return [
+            Comment(self._document, store)
+            for store in storage_comments(
+                self._document._package, self._document._storage
+            )
+        ]
+
+    def __len__(self) -> int:
+        return len(self._items())
+
+    def __iter__(self):
+        return iter(self._items())
+
+    def __getitem__(self, index: int) -> Comment:
+        return self._items()[index]
+
+    def get(self, comment_id: int) -> Comment | None:
+        return next(
+            (item for item in self._items() if item.comment_id == comment_id),
+            None,
+        )
+
+    def add_comment(self, *args, **kwargs):
+        raise NotImplementedError(
+            "creating a Pages comment requires author and collaboration-state "
+            "graphs beyond the anchored comment objects"
+        )
+
+
+class AnnotationHighlight:
+    """Review annotation range associated with one Pages comment."""
+
+    def __init__(self, comment: Comment):
+        self._comment = comment
+
+    @property
+    def start_utf16(self) -> int:
+        assert self._comment.anchor_start is not None
+        return self._comment.anchor_start
+
+    @property
+    def end_utf16(self) -> int:
+        assert self._comment.anchor_end is not None
+        return self._comment.anchor_end
+
+    @property
+    def text(self) -> str:
+        return self._comment.anchor_text
+
+    @property
+    def color(self) -> RGBColor | None:
+        return self._comment.annotation_color
+
+    @property
+    def comment(self) -> Comment:
+        return self._comment
+
+
+class Document:
+    """Open a Pages package and expose paragraphs and character-style runs."""
+
+    def __init__(self, path: str | Path | None = None):
+        if path is None:
+            path = Path(__file__).with_name("data") / "default.pages"
+        self._package = PagesDocument.load(path)
+        self._storage = self._package.body_storage()
+        self._text = self._package.text(self._storage)
+        self._core_properties = CoreProperties(self._package)
+        self._tables: list[Table] | None = None
+        self._inline_shapes: list[InlineShape] | None = None
+        self._styles = Styles(self)
+        self._comments = Comments(self)
+
+    @property
+    def paragraphs(self) -> list[Paragraph]:
+        result: list[Paragraph] = []
+        start_cp = 0
+        for end_cp in [
+            index for index, char in enumerate(self._text) if char in ("\n", "\r")
+        ] + [len(self._text)]:
+            start = codepoint_to_utf16(self._text, start_cp)
+            end = codepoint_to_utf16(self._text, end_cp)
+            next_start = end + (1 if end_cp < len(self._text) else 0)
+            result.append(Paragraph(self, start, end, next_start))
+            start_cp = end_cp + 1
+        return result
+
+    def save(self, path: str | Path) -> None:
+        self._package.save(path)
+
+    @property
+    def sections(self) -> list[Section]:
+        return [Section(self._package.document_layout(self._storage))]
+
+    @property
+    def core_properties(self) -> CoreProperties:
+        return self._core_properties
+
+    @property
+    def styles(self) -> Styles:
+        return self._styles
+
+    @property
+    def comments(self) -> Comments:
+        return self._comments
+
+    @property
+    def annotation_highlights(self) -> list[AnnotationHighlight]:
+        return [
+            AnnotationHighlight(comment)
+            for comment in self.comments
+            if comment.anchor_start is not None and comment.anchor_end is not None
+        ]
+
+    def add_comment(self, *args, **kwargs):
+        return self.comments.add_comment(*args, **kwargs)
+
+    @property
+    def tables(self) -> list[Table]:
+        if self._tables is None:
+            self._tables = [
+                Table(store)
+                for store in body_table_stores(self._package, self._storage)
+            ]
+        return list(self._tables)
+
+    def add_table(self, rows: int, cols: int, style=None) -> Table:
+        if (
+            not isinstance(rows, int)
+            or isinstance(rows, bool)
+            or not isinstance(cols, int)
+            or isinstance(cols, bool)
+        ):
+            raise TypeError("rows and cols must be integers")
+        if rows <= 0 or cols <= 0:
+            raise ValueError("rows and cols must be positive")
+        if rows > 256:
+            raise ValueError("template-backed Pages tables currently support at most 256 rows")
+        if style is not None:
+            raise NotImplementedError(
+                "named table styles are not exposed by the Pages stylesheet facade"
+            )
+        store, clone = clone_body_table(self._package, self._storage, rows, cols)
+        position = codepoint_to_utf16(self._text, len(self._text))
+        self._replace_text(position, position, "\n\ufffc")
+        append_attachment_run(self._storage, position + 1, clone.root.segment.identifier)
+        table = Table(store)
+        if self._tables is None:
+            self._tables = [
+                Table(item)
+                for item in body_table_stores(self._package, self._storage)
+            ]
+        else:
+            self._tables.append(table)
+        return table
+
+    @property
+    def inline_shapes(self) -> list[InlineShape]:
+        if self._inline_shapes is None:
+            self._inline_shapes = [
+                InlineShape(store)
+                for store in body_image_stores(self._package, self._storage)
+            ]
+        return list(self._inline_shapes)
+
+    @property
+    def pictures(self) -> list[InlineShape]:
+        """Convenience alias for the Pages-backed inline-shapes collection."""
+        return self.inline_shapes
+
+    @property
+    def hyperlinks(self) -> list[Hyperlink]:
+        return [
+            Hyperlink(self, store)
+            for store in storage_hyperlinks(self._package, self._storage)
+        ]
+
+    def add_picture(
+        self,
+        image_path_or_stream,
+        width: Length | float | None = None,
+        height: Length | float | None = None,
+    ) -> InlineShape:
+        if hasattr(image_path_or_stream, "read"):
+            data = image_path_or_stream.read()
+            filename = Path(getattr(image_path_or_stream, "name", "image.png")).name
+        else:
+            path = Path(image_path_or_stream)
+            data = path.read_bytes()
+            filename = path.name
+        if not isinstance(data, bytes):
+            raise TypeError("image stream must return bytes")
+        for name, value in (("width", width), ("height", height)):
+            if value is not None and (isinstance(value, bool) or float(value) <= 0):
+                raise ValueError(f"{name} must be positive")
+        store, clone = clone_body_image(
+            self._package,
+            self._storage,
+            data,
+            filename,
+            width=None if width is None else float(width),
+            height=None if height is None else float(height),
+        )
+        position = codepoint_to_utf16(self._text, len(self._text))
+        self._replace_text(position, position, "\n\ufffc")
+        append_attachment_run(self._storage, position + 1, clone.root.segment.identifier)
+        shape = InlineShape(store)
+        if self._inline_shapes is None:
+            self._inline_shapes = [
+                InlineShape(item)
+                for item in body_image_stores(self._package, self._storage)
+            ]
+        else:
+            self._inline_shapes.append(shape)
+        return shape
+
+    def add_paragraph(self, text: str = "", style=None) -> Paragraph:
+        if not isinstance(text, str):
+            raise TypeError("paragraph text must be a string")
+        if "\n" in text or "\r" in text:
+            raise ValueError("add_paragraph text cannot contain paragraph separators")
+        stylesheet = self._package.stylesheet()
+        if style is None:
+            style_obj = stylesheet.default_paragraph_style()
+        elif isinstance(style, str):
+            style_obj = stylesheet.named_paragraph_style(style)
+        elif isinstance(style, int):
+            style_obj = stylesheet.paragraph_style(style)
+            if style_obj is None:
+                raise KeyError(f"paragraph style {style} was not found")
+        else:
+            raise TypeError("style must be a paragraph style name, object ID, or None")
+
+        old_end = codepoint_to_utf16(self._text, len(self._text))
+        value = "\n" + text
+        self._replace_text(old_end, old_end, value)
+        start = old_end + 1
+        end = start + codepoint_to_utf16(text, len(text))
+        table = self._storage.message.one(STORAGE_TABLE_PARA_STYLE)
+        if table is None:
+            table = self._storage.message.add_bytes(STORAGE_TABLE_PARA_STYLE, b"")
+        runs = parse_attribute_table(bytes(table.value))
+        runs.append(AttributeRun(start, style_obj.segment.identifier))
+        runs.sort(key=lambda item: item.character_index)
+        table.set_bytes(encode_attribute_table(runs))
+        add_object_reference(self._storage.info, style_obj.segment.identifier)
+        return Paragraph(self, start, end, end)
+
+    def add_heading(self, text: str = "", level: int = 1) -> Paragraph:
+        """Append a heading using the closest built-in Pages heading style."""
+        if not isinstance(level, int) or isinstance(level, bool):
+            raise TypeError("heading level must be an integer")
+        if level < 0 or level > 9:
+            raise ValueError("heading level must be in range 0..9")
+        style = "Title" if level == 0 else f"Heading {level}" if level > 1 else "Heading"
+        try:
+            return self.add_paragraph(text, style=style)
+        except KeyError:
+            # The supplied Pages theme defines Heading through Heading 3. Pages
+            # has no fixed nine-level hierarchy, so deeper docx levels use the
+            # deepest available heading style.
+            return self.add_paragraph(text, style="Heading 3")
+
+    def add_page_break(self) -> Paragraph:
+        """Append the Pages page-break control and return a post-break proxy."""
+        position = codepoint_to_utf16(self._text, len(self._text))
+        self._replace_text(position, position, "\x05")
+        after_break = position + 1
+        return Paragraph(self, after_break, after_break, after_break)
+
+    def _character_runs(self) -> list[AttributeRun]:
+        field = self._storage.message.one(STORAGE_TABLE_CHAR_STYLE)
+        return [] if field is None else parse_attribute_table(bytes(field.value))
+
+    def _paragraph_runs(self) -> list[AttributeRun]:
+        field = self._storage.message.one(STORAGE_TABLE_PARA_STYLE)
+        return [] if field is None else parse_attribute_table(bytes(field.value))
+
+    def _paragraph_style_id_at(self, index: int) -> int | None:
+        return style_at(self._paragraph_runs(), index)
+
+    def _character_style_id_at(self, index: int) -> int | None:
+        return style_at(self._character_runs(), index)
+
+    def _style_from_id(
+        self, identifier: int | None, expected: WD_STYLE_TYPE
+    ) -> Style | None:
+        obj = (
+            self._package.objects().get(identifier)
+            if identifier is not None
+            else None
+        )
+        expected_type = (
+            TYPE_CHARACTER_STYLE
+            if expected == WD_STYLE_TYPE.CHARACTER
+            else TYPE_PARAGRAPH_STYLE
+        )
+        seen: set[int] = set()
+        while (
+            obj is not None
+            and obj.info.type_id == expected_type
+            and is_anonymous_style(obj)
+        ):
+            if obj.segment.identifier in seen:
+                return None
+            seen.add(obj.segment.identifier)
+            try:
+                parent = self._package.stylesheet().parent_identifier(obj)
+            except ValueError:
+                return None
+            obj = self._package.objects().get(parent)
+        return (
+            None
+            if obj is None or obj.info.type_id != expected_type
+            else Style(self, obj)
+        )
+
+    def _coerce_style_id(
+        self,
+        value: Style | str | None,
+        expected: WD_STYLE_TYPE,
+        *,
+        none_identifier: int | None,
+    ) -> int | None:
+        if value is None:
+            return none_identifier
+        style = self.styles[value] if isinstance(value, str) else value
+        if not isinstance(style, Style):
+            raise TypeError("style must be a style name, Style, or None")
+        if style.type != expected:
+            raise ValueError(f"style {style.name!r} has the wrong style type")
+        return style._obj.segment.identifier
+
+    def _apply_character_style_id(
+        self, start_utf16: int, end_utf16: int, identifier: int | None
+    ) -> None:
+        if end_utf16 <= start_utf16:
+            return
+        table = self._storage.message.one(STORAGE_TABLE_CHAR_STYLE)
+        if table is None:
+            table = self._storage.message.add_bytes(STORAGE_TABLE_CHAR_STYLE, b"")
+        runs = parse_attribute_table(bytes(table.value))
+        table.set_bytes(
+            encode_attribute_table(
+                replace_style_range(runs, start_utf16, end_utf16, identifier)
+            )
+        )
+        if identifier is not None:
+            add_object_reference(self._storage.info, identifier)
+
+    def _apply_paragraph_style_id(
+        self, start_utf16: int, end_utf16: int, identifier: int
+    ) -> None:
+        table = self._storage.message.one(STORAGE_TABLE_PARA_STYLE)
+        if table is None:
+            table = self._storage.message.add_bytes(STORAGE_TABLE_PARA_STYLE, b"")
+        runs = parse_attribute_table(bytes(table.value))
+        if end_utf16 <= start_utf16:
+            updated = [run for run in runs if run.character_index != start_utf16]
+            updated.append(AttributeRun(start_utf16, identifier))
+            updated.sort(key=lambda run: run.character_index)
+        else:
+            updated = replace_style_range(
+                runs, start_utf16, end_utf16, identifier, compact=False
+            )
+        table.set_bytes(encode_attribute_table(updated))
+        add_object_reference(self._storage.info, identifier)
+
+    def _paragraph_properties_at(self, index: int) -> ParagraphProperties:
+        style = self._package.stylesheet().paragraph_style(self._paragraph_style_id_at(index))
+        return paragraph_style_properties(style)
+
+    def _paragraph_character_properties_at(
+        self, index: int
+    ) -> CharacterProperties:
+        style = self._package.stylesheet().paragraph_style(
+            self._paragraph_style_id_at(index)
+        )
+        return character_style_properties(style)
+
+    def _text_between(self, start_utf16: int, end_utf16: int) -> str:
+        start = utf16_to_codepoint(self._text, start_utf16)
+        end = utf16_to_codepoint(self._text, end_utf16)
+        return self._text[start:end]
+
+    def _replace_text(self, start_utf16: int, end_utf16: int, value: str) -> int:
+        delta = replace_storage_text(self._storage, start_utf16, end_utf16, value)
+        start = utf16_to_codepoint(self._text, start_utf16)
+        end = utf16_to_codepoint(self._text, end_utf16)
+        self._text = self._text[:start] + value + self._text[end:]
+        return delta
+
+    def _properties_at(self, index: int) -> CharacterProperties:
+        style_id = style_at(self._character_runs(), index)
+        return character_style_properties(self._package.stylesheet().style(style_id))
+
+    def _apply_properties(
+        self, start_utf16: int, end_utf16: int, props: CharacterProperties
+    ) -> None:
+        table = self._storage.message.one(STORAGE_TABLE_CHAR_STYLE)
+        if table is None:
+            table = self._storage.message.add_bytes(STORAGE_TABLE_CHAR_STYLE, b"")
+        runs = parse_attribute_table(bytes(table.value))
+        style_id = None
+        if props.override_count:
+            style, _ = self._package.synthesize_character_style(props)
+            style_id = style.segment.identifier
+            add_object_reference(self._storage.info, style_id)
+        table.set_bytes(
+            encode_attribute_table(replace_style_range(runs, start_utf16, end_utf16, style_id))
+        )
+
+    def _apply_paragraph_properties(
+        self,
+        start_utf16: int,
+        next_start_utf16: int,
+        props: ParagraphProperties,
+    ) -> None:
+        table = self._storage.message.one(STORAGE_TABLE_PARA_STYLE)
+        if table is None:
+            table = self._storage.message.add_bytes(STORAGE_TABLE_PARA_STYLE, b"")
+        runs = parse_attribute_table(bytes(table.value))
+        target_positions = [
+            position
+            for position, run in enumerate(runs)
+            if start_utf16 <= run.character_index < next_start_utf16
+        ]
+        updated = list(runs)
+        if not target_positions or runs[target_positions[0]].character_index != start_utf16:
+            updated.append(AttributeRun(start_utf16, style_at(runs, start_utf16)))
+            target_positions = [len(updated) - 1, *target_positions]
+        for position in target_positions:
+            run = updated[position]
+            parent, character_raw, _ = self._package.stylesheet().paragraph_style_context(
+                run.object_id
+            )
+            style, _ = self._package.synthesize_paragraph_style(
+                parent,
+                props,
+                character_properties=character_raw,
+            )
+            style_id = style.segment.identifier
+            updated[position] = AttributeRun(run.character_index, style_id)
+            add_object_reference(self._storage.info, style_id)
+        updated.sort(key=lambda item: item.character_index)
+        table.set_bytes(encode_attribute_table(updated))
+
+    def _apply_paragraph_background(
+        self,
+        start_utf16: int,
+        next_start_utf16: int,
+        color: RGBColor | None,
+    ) -> None:
+        table = self._storage.message.one(STORAGE_TABLE_PARA_STYLE)
+        if table is None:
+            table = self._storage.message.add_bytes(STORAGE_TABLE_PARA_STYLE, b"")
+        runs = parse_attribute_table(bytes(table.value))
+        target_positions = [
+            position
+            for position, run in enumerate(runs)
+            if start_utf16 <= run.character_index < next_start_utf16
+        ]
+        updated = list(runs)
+        if not target_positions or runs[target_positions[0]].character_index != start_utf16:
+            updated.append(AttributeRun(start_utf16, style_at(runs, start_utf16)))
+            target_positions = [len(updated) - 1, *target_positions]
+        for position in target_positions:
+            run = updated[position]
+            parent, character_raw, paragraph_props = (
+                self._package.stylesheet().paragraph_style_context(run.object_id)
+            )
+            character_raw = replace_character_background(character_raw, color)
+            style, _ = self._package.synthesize_paragraph_style(
+                parent,
+                paragraph_props,
+                character_properties=character_raw,
+            )
+            style_id = style.segment.identifier
+            updated[position] = AttributeRun(run.character_index, style_id)
+            add_object_reference(self._storage.info, style_id)
+        updated.sort(key=lambda item: item.character_index)
+        table.set_bytes(encode_attribute_table(updated))