python-pages 0.1.0__py3-none-any.whl

pages/stylesheet.py

@@ -0,0 +1,892 @@
+"""TSS stylesheet registration and TSWP character-style synthesis."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field as dataclass_field, fields
+import struct
+from typing import TYPE_CHECKING
+
+from .iwa import ArchiveSegment, MessageInfo
+from .metadata import (
+    package_revision_identifier,
+    register_component_object,
+    register_external_reference,
+)
+from .protobuf import Message
+from .text import (
+    STYLE_CHAR_PROPERTIES,
+    STYLE_SUPER,
+    TYPE_CHARACTER_STYLE,
+    TYPE_PARAGRAPH_STYLE,
+    LocatedObject,
+    add_object_reference,
+    make_reference,
+    parse_reference,
+)
+
+if TYPE_CHECKING:
+    from .pages import PagesDocument
+
+
+TYPE_STYLESHEET = 401
+STYLESHEET_STYLES = 1
+STYLESHEET_PARENT_TO_CHILDREN = 5
+STYLE_PARENT = 3
+STYLE_ANONYMOUS = 4
+STYLE_PARA_PROPERTIES = 12
+
+CHAR_BOLD = 1
+CHAR_ITALIC = 2
+CHAR_FONT_SIZE = 3
+CHAR_FONT_NAME_NULL = 4
+CHAR_FONT_NAME = 5
+CHAR_FONT_COLOR_NULL = 6
+CHAR_FONT_COLOR = 7
+CHAR_SUPERSCRIPT = 10
+CHAR_UNDERLINE = 11
+CHAR_STRIKE = 12
+CHAR_BASELINE_SHIFT = 14
+CHAR_BACKGROUND_COLOR_NULL = 25
+CHAR_BACKGROUND_COLOR = 26
+CHAR_TSD_STROKE_NULL = 43
+CHAR_TSD_STROKE = 44
+CHAR_TSD_FILL_NULL = 45
+CHAR_TSD_FILL = 46
+CHAR_TSD_FILL_SHOULD_FILL_TEXT_CONTAINER = 47
+
+KNOWN_CHARACTER_FIELDS = {
+    CHAR_BOLD,
+    CHAR_ITALIC,
+    CHAR_FONT_SIZE,
+    CHAR_FONT_NAME_NULL,
+    CHAR_FONT_NAME,
+    CHAR_FONT_COLOR_NULL,
+    CHAR_FONT_COLOR,
+    CHAR_SUPERSCRIPT,
+    CHAR_UNDERLINE,
+    CHAR_STRIKE,
+    CHAR_BASELINE_SHIFT,
+    CHAR_BACKGROUND_COLOR_NULL,
+    CHAR_BACKGROUND_COLOR,
+    CHAR_TSD_FILL_NULL,
+    CHAR_TSD_FILL,
+    CHAR_TSD_FILL_SHOULD_FILL_TEXT_CONTAINER,
+}
+CACHEABLE_CHARACTER_FIELDS = KNOWN_CHARACTER_FIELDS - {
+    CHAR_FONT_NAME_NULL,
+    CHAR_FONT_COLOR_NULL,
+    CHAR_BACKGROUND_COLOR_NULL,
+    CHAR_TSD_FILL_NULL,
+}
+
+PARA_ALIGNMENT = 1
+PARA_FIRST_LINE_INDENT = 7
+PARA_LEFT_INDENT = 11
+PARA_LINE_SPACING_NULL = 12
+PARA_LINE_SPACING = 13
+PARA_PAGE_BREAK_BEFORE = 14
+PARA_RIGHT_INDENT = 19
+PARA_SPACE_AFTER = 20
+PARA_SPACE_BEFORE = 21
+PARA_TABS_NULL = 24
+PARA_TABS = 25
+
+KNOWN_PARAGRAPH_FIELDS = {
+    PARA_ALIGNMENT,
+    PARA_FIRST_LINE_INDENT,
+    PARA_LEFT_INDENT,
+    PARA_LINE_SPACING,
+    PARA_PAGE_BREAK_BEFORE,
+    PARA_RIGHT_INDENT,
+    PARA_SPACE_AFTER,
+    PARA_SPACE_BEFORE,
+    PARA_TABS,
+}
+
+
+@dataclass(frozen=True)
+class RGBColor:
+    """An sRGB color represented by 8-bit red, green, and blue channels."""
+
+    red: int
+    green: int
+    blue: int
+
+    def __post_init__(self) -> None:
+        if any(channel < 0 or channel > 255 for channel in self):
+            raise ValueError("RGB channels must be in range 0..255")
+
+    def __iter__(self):
+        return iter((self.red, self.green, self.blue))
+
+    def __str__(self) -> str:
+        return f"{self.red:02X}{self.green:02X}{self.blue:02X}"
+
+    @classmethod
+    def from_string(cls, value: str) -> "RGBColor":
+        value = value.removeprefix("#")
+        if len(value) != 6:
+            raise ValueError("RGB color must contain six hexadecimal digits")
+        return cls(*(int(value[index : index + 2], 16) for index in (0, 2, 4)))
+
+
+@dataclass(frozen=True)
+class CharacterProperties:
+    bold: bool | None = None
+    italic: bool | None = None
+    underline: bool | None = None
+    strike: bool | None = None
+    font_name: str | None = None
+    font_size: float | None = None
+    color: RGBColor | None = None
+    vertical_align: int | None = None
+    baseline_shift: float | None = None
+    background_color: RGBColor | None = None
+
+    @property
+    def override_count(self) -> int:
+        return sum(getattr(self, item.name) is not None for item in fields(self))
+
+    def with_value(self, name: str, value) -> "CharacterProperties":
+        if name not in {item.name for item in fields(self)}:
+            raise AttributeError(name)
+        values = {item.name: getattr(self, item.name) for item in fields(self)}
+        values[name] = value
+        return CharacterProperties(**values)
+
+
+@dataclass(frozen=True)
+class LineSpacing:
+    mode: int
+    amount: float
+    baseline_rule: float | None = None
+
+
+@dataclass(frozen=True)
+class ParagraphTab:
+    position: float
+    alignment: int = 0
+    leader: str | None = None
+
+
+@dataclass(frozen=True)
+class ParagraphProperties:
+    alignment: int | None = None
+    line_spacing: LineSpacing | None = None
+    page_break_before: bool | None = None
+    space_before: float | None = None
+    space_after: float | None = None
+    left_indent: float | None = None
+    right_indent: float | None = None
+    first_line_indent: float | None = None
+    tabs: tuple[ParagraphTab, ...] | None = None
+    unknown_fields: tuple[bytes, ...] = dataclass_field(default=(), repr=False)
+
+    @property
+    def override_count(self) -> int:
+        known = sum(
+            getattr(self, item.name) is not None
+            for item in fields(self)
+            if item.name != "unknown_fields"
+        )
+        return known + len(self.unknown_fields)
+
+    def with_value(self, name: str, value) -> "ParagraphProperties":
+        public = {item.name for item in fields(self) if item.name != "unknown_fields"}
+        if name not in public:
+            raise AttributeError(name)
+        values = {item.name: getattr(self, item.name) for item in fields(self)}
+        values[name] = value
+        null_marker = {
+            "line_spacing": PARA_LINE_SPACING_NULL,
+            "tabs": PARA_TABS_NULL,
+        }.get(name)
+        if null_marker is not None:
+            values["unknown_fields"] = tuple(
+                raw
+                for raw in self.unknown_fields
+                if Message.parse(raw).fields[0].number != null_marker
+            )
+        return ParagraphProperties(**values)
+
+
+def _float_bits(value: float) -> int:
+    return int.from_bytes(struct.pack("<f", float(value)), "little")
+
+
+def _bits_float(value: int) -> float:
+    return struct.unpack("<f", int(value).to_bytes(4, "little"))[0]
+
+
+def encode_color(color: RGBColor) -> bytes:
+    message = Message()
+    message.add_varint(1, 1)  # RGB model
+    message.add_fixed32(3, _float_bits(color.red / 255.0))
+    message.add_fixed32(4, _float_bits(color.green / 255.0))
+    message.add_fixed32(5, _float_bits(color.blue / 255.0))
+    message.add_fixed32(6, _float_bits(1.0))
+    message.add_varint(12, 1)  # sRGB
+    # Pages 15 writes this additional 1.0 field in every sample RGB color.
+    message.add_fixed32(13, _float_bits(1.0))
+    return message.encode()
+
+
+def decode_color(data: bytes) -> RGBColor | None:
+    message = Message.parse(data)
+    model = message.one(1)
+    channels = [message.one(number) for number in (3, 4, 5)]
+    if model is None or int(model.value) != 1 or any(item is None for item in channels):
+        return None
+    return RGBColor(*(max(0, min(255, round(_bits_float(item.value) * 255))) for item in channels))
+
+
+def encode_fill(color: RGBColor) -> bytes:
+    fill = Message()
+    fill.add_bytes(1, encode_color(color))
+    return fill.encode()
+
+
+def decode_fill(data: bytes) -> RGBColor | None:
+    fill = Message.parse(data)
+    color = fill.one(1)
+    return None if color is None else decode_color(bytes(color.value))
+
+
+def encode_character_properties(props: CharacterProperties) -> bytes:
+    message = Message()
+    if props.bold is not None:
+        message.add_varint(CHAR_BOLD, int(props.bold))
+    if props.italic is not None:
+        message.add_varint(CHAR_ITALIC, int(props.italic))
+    if props.font_size is not None:
+        message.add_fixed32(CHAR_FONT_SIZE, _float_bits(props.font_size))
+    if props.font_name is not None:
+        message.add_bytes(CHAR_FONT_NAME, props.font_name.encode("utf-8"))
+    if props.color is not None:
+        message.add_bytes(CHAR_FONT_COLOR, encode_color(props.color))
+    if props.vertical_align is not None:
+        message.add_varint(CHAR_SUPERSCRIPT, props.vertical_align)
+    if props.underline is not None:
+        message.add_varint(CHAR_UNDERLINE, int(props.underline))
+    if props.strike is not None:
+        message.add_varint(CHAR_STRIKE, int(props.strike))
+    if props.baseline_shift is not None:
+        message.add_fixed32(CHAR_BASELINE_SHIFT, _float_bits(props.baseline_shift))
+    if props.background_color is not None:
+        # The Pages-authored character-background fixture contains field 26
+        # alone: no null marker and no TSD fill/container fields.
+        message.add_bytes(CHAR_BACKGROUND_COLOR, encode_color(props.background_color))
+    # Foreground character color uses field 7 plus a synchronized TSD fill.
+    if props.color is not None:
+        message.add_bytes(CHAR_TSD_FILL, encode_fill(props.color))
+    return message.encode()
+
+
+def decode_character_properties(data: bytes) -> CharacterProperties:
+    message = Message.parse(data)
+
+    def boolean(number: int) -> bool | None:
+        field = message.one(number)
+        return None if field is None else bool(field.value)
+
+    size = message.one(CHAR_FONT_SIZE)
+    name = message.one(CHAR_FONT_NAME)
+    color = message.one(CHAR_FONT_COLOR)
+    vertical_align = message.one(CHAR_SUPERSCRIPT)
+    baseline_shift = message.one(CHAR_BASELINE_SHIFT)
+    background_color = message.one(CHAR_BACKGROUND_COLOR)
+    font_color_null = message.one(CHAR_FONT_COLOR_NULL)
+    background_color_null = message.one(CHAR_BACKGROUND_COLOR_NULL)
+    fill = message.one(CHAR_TSD_FILL)
+    fill_null = message.one(CHAR_TSD_FILL_NULL)
+    fill_container = message.one(CHAR_TSD_FILL_SHOULD_FILL_TEXT_CONTAINER)
+    fill_color = (
+        None
+        if fill_null is not None and bool(fill_null.value)
+        else decode_fill(bytes(fill.value))
+        if fill
+        else None
+    )
+    fills_background = bool(fill_container.value) if fill_container else False
+    decoded_font_color = None
+    if font_color_null is None or not bool(font_color_null.value):
+        if color is not None:
+            decoded_font_color = decode_color(bytes(color.value))
+        elif not fills_background:
+            decoded_font_color = fill_color
+    decoded_background_color = None
+    if background_color_null is None or not bool(background_color_null.value):
+        if background_color is not None:
+            decoded_background_color = decode_color(bytes(background_color.value))
+        elif fills_background:
+            decoded_background_color = fill_color
+    return CharacterProperties(
+        bold=boolean(CHAR_BOLD),
+        italic=boolean(CHAR_ITALIC),
+        underline=boolean(CHAR_UNDERLINE),
+        strike=boolean(CHAR_STRIKE),
+        font_name=bytes(name.value).decode("utf-8", "replace") if name else None,
+        font_size=_bits_float(size.value) if size else None,
+        color=decoded_font_color,
+        vertical_align=int(vertical_align.value) if vertical_align else None,
+        baseline_shift=(
+            _bits_float(baseline_shift.value) if baseline_shift else None
+        ),
+        background_color=decoded_background_color,
+    )
+
+
+def replace_character_background(
+    data: bytes, color: RGBColor | None
+) -> bytes:
+    """Replace only the Pages character-background fields in raw properties.
+
+    Paragraph styles can carry character properties in field 11.  Keeping the
+    raw message here is important: changing a paragraph background must not
+    discard character-property fields that this library does not yet model.
+    """
+
+    message = Message.parse(data)
+    message.fields = [
+        field
+        for field in message.fields
+        if field.number not in (CHAR_BACKGROUND_COLOR_NULL, CHAR_BACKGROUND_COLOR)
+    ]
+    if color is not None:
+        message.add_bytes(CHAR_BACKGROUND_COLOR, encode_color(color))
+    return message.encode()
+
+
+def character_style_properties(style: LocatedObject | None) -> CharacterProperties:
+    if style is None:
+        return CharacterProperties()
+    field = style.message.one(STYLE_CHAR_PROPERTIES)
+    return CharacterProperties() if field is None else decode_character_properties(bytes(field.value))
+
+
+def encode_paragraph_properties(props: ParagraphProperties) -> bytes:
+    message = Message()
+    if props.alignment is not None:
+        message.add_varint(PARA_ALIGNMENT, props.alignment)
+    if props.first_line_indent is not None:
+        message.add_fixed32(PARA_FIRST_LINE_INDENT, _float_bits(props.first_line_indent))
+    if props.left_indent is not None:
+        message.add_fixed32(PARA_LEFT_INDENT, _float_bits(props.left_indent))
+    if props.line_spacing is not None:
+        spacing = Message()
+        spacing.add_varint(1, props.line_spacing.mode)
+        spacing.add_fixed32(2, _float_bits(props.line_spacing.amount))
+        if props.line_spacing.baseline_rule is not None:
+            spacing.add_fixed32(3, _float_bits(props.line_spacing.baseline_rule))
+        message.add_bytes(PARA_LINE_SPACING, spacing.encode())
+    if props.page_break_before is not None:
+        message.add_varint(PARA_PAGE_BREAK_BEFORE, int(props.page_break_before))
+    if props.right_indent is not None:
+        message.add_fixed32(PARA_RIGHT_INDENT, _float_bits(props.right_indent))
+    if props.space_after is not None:
+        message.add_fixed32(PARA_SPACE_AFTER, _float_bits(props.space_after))
+    if props.space_before is not None:
+        message.add_fixed32(PARA_SPACE_BEFORE, _float_bits(props.space_before))
+    if props.tabs is not None:
+        tabs = Message()
+        for tab in props.tabs:
+            item = Message()
+            item.add_fixed32(1, _float_bits(tab.position))
+            if tab.alignment:
+                item.add_varint(2, tab.alignment)
+            if tab.leader:
+                item.add_bytes(3, tab.leader.encode("utf-8"))
+            tabs.add_bytes(1, item.encode())
+        message.add_bytes(PARA_TABS, tabs.encode())
+    for raw in props.unknown_fields:
+        message.fields.extend(Message.parse(raw).fields)
+    return message.encode()
+
+
+def decode_paragraph_properties(data: bytes) -> ParagraphProperties:
+    message = Message.parse(data)
+
+    def floating(number: int) -> float | None:
+        item = message.one(number)
+        return None if item is None else _bits_float(item.value)
+
+    alignment = message.one(PARA_ALIGNMENT)
+    page_break_before = message.one(PARA_PAGE_BREAK_BEFORE)
+    spacing_field = message.one(PARA_LINE_SPACING)
+    spacing = None
+    if spacing_field is not None:
+        spacing_message = Message.parse(bytes(spacing_field.value))
+        mode = spacing_message.one(1)
+        amount = spacing_message.one(2)
+        baseline = spacing_message.one(3)
+        if mode is not None and amount is not None:
+            spacing = LineSpacing(
+                int(mode.value),
+                _bits_float(amount.value),
+                _bits_float(baseline.value) if baseline else None,
+            )
+
+    tabs_field = message.one(PARA_TABS)
+    tabs = None
+    if tabs_field is not None:
+        parsed_tabs = Message.parse(bytes(tabs_field.value))
+        values = []
+        for raw in parsed_tabs.get(1):
+            tab = Message.parse(bytes(raw.value))
+            position = tab.one(1)
+            if position is None:
+                continue
+            alignment_field = tab.one(2)
+            leader = tab.one(3)
+            values.append(
+                ParagraphTab(
+                    _bits_float(position.value),
+                    int(alignment_field.value) if alignment_field else 0,
+                    bytes(leader.value).decode("utf-8", "replace") if leader else None,
+                )
+            )
+        tabs = tuple(values)
+
+    unknown = tuple(
+        item.original or item.encode()
+        for item in message.fields
+        if item.number not in KNOWN_PARAGRAPH_FIELDS
+    )
+    return ParagraphProperties(
+        alignment=int(alignment.value) if alignment else None,
+        line_spacing=spacing,
+        page_break_before=(
+            bool(page_break_before.value) if page_break_before is not None else None
+        ),
+        space_before=floating(PARA_SPACE_BEFORE),
+        space_after=floating(PARA_SPACE_AFTER),
+        left_indent=floating(PARA_LEFT_INDENT),
+        right_indent=floating(PARA_RIGHT_INDENT),
+        first_line_indent=floating(PARA_FIRST_LINE_INDENT),
+        tabs=tabs,
+        unknown_fields=unknown,
+    )
+
+
+def is_anonymous_style(style: LocatedObject | None) -> bool:
+    if style is None:
+        return False
+    super_field = style.message.one(STYLE_SUPER)
+    if super_field is None:
+        return False
+    marker = Message.parse(bytes(super_field.value)).one(STYLE_ANONYMOUS)
+    return marker is not None and int(marker.value) == 1
+
+
+def style_name(style: LocatedObject | None) -> str | None:
+    if style is None:
+        return None
+    super_field = style.message.one(STYLE_SUPER)
+    if super_field is None:
+        return None
+    name = Message.parse(bytes(super_field.value)).one(1)
+    return None if name is None else bytes(name.value).decode("utf-8", "replace")
+
+
+def style_identifier(style: LocatedObject | None) -> str | None:
+    if style is None:
+        return None
+    super_field = style.message.one(STYLE_SUPER)
+    if super_field is None:
+        return None
+    identifier = Message.parse(bytes(super_field.value)).one(2)
+    return (
+        None
+        if identifier is None
+        else bytes(identifier.value).decode("utf-8", "replace")
+    )
+
+
+def paragraph_style_properties(style: LocatedObject | None) -> ParagraphProperties:
+    if style is None or not is_anonymous_style(style):
+        return ParagraphProperties()
+    field = style.message.one(STYLE_PARA_PROPERTIES)
+    return ParagraphProperties() if field is None else decode_paragraph_properties(bytes(field.value))
+
+
+class Stylesheet:
+    """Mutation facade for a document's TSS.StylesheetArchive."""
+
+    def __init__(self, document: "PagesDocument"):
+        self.document = document
+        matches = [obj for obj in document.object_messages() if obj.info.type_id == TYPE_STYLESHEET]
+        if len(matches) != 1:
+            raise ValueError(f"expected one TSS.StylesheetArchive, found {len(matches)}")
+        self.archive = matches[0]
+        self._cache: dict[CharacterProperties, LocatedObject] = {}
+        self._paragraph_cache: dict[
+            tuple[int, bytes, ParagraphProperties], LocatedObject
+        ] = {}
+        self._index_styles()
+
+    def _index_styles(self) -> None:
+        registered = {
+            parse_reference(bytes(field.value)) for field in self.archive.message.get(STYLESHEET_STYLES)
+        }
+        for obj in self.document.object_messages():
+            if obj.info.type_id != TYPE_CHARACTER_STYLE or obj.segment.identifier not in registered:
+                continue
+            raw = obj.message.one(STYLE_CHAR_PROPERTIES)
+            if raw is None:
+                continue
+            message = Message.parse(bytes(raw.value))
+            if all(field.number in CACHEABLE_CHARACTER_FIELDS for field in message.fields):
+                self._cache.setdefault(decode_character_properties(bytes(raw.value)), obj)
+        for obj in self.document.object_messages():
+            if obj.info.type_id != TYPE_PARAGRAPH_STYLE or obj.segment.identifier not in registered:
+                continue
+            if not is_anonymous_style(obj):
+                continue
+            try:
+                parent = self.parent_identifier(obj)
+            except ValueError:
+                continue
+            character = obj.message.one(STYLE_CHAR_PROPERTIES)
+            character_raw = bytes(character.value) if character else b""
+            paragraph = obj.message.one(STYLE_PARA_PROPERTIES)
+            props = (
+                decode_paragraph_properties(bytes(paragraph.value))
+                if paragraph
+                else ParagraphProperties()
+            )
+            self._paragraph_cache.setdefault((parent, character_raw, props), obj)
+
+    def style(self, identifier: int | None) -> LocatedObject | None:
+        if identifier is None:
+            return None
+        obj = self.document.objects().get(identifier)
+        return obj if obj is not None and obj.info.type_id == TYPE_CHARACTER_STYLE else None
+
+    def paragraph_style(self, identifier: int | None) -> LocatedObject | None:
+        if identifier is None:
+            return None
+        obj = self.document.objects().get(identifier)
+        return obj if obj is not None and obj.info.type_id == TYPE_PARAGRAPH_STYLE else None
+
+    @staticmethod
+    def parent_identifier(style: LocatedObject) -> int:
+        super_field = style.message.one(STYLE_SUPER)
+        if super_field is None:
+            raise ValueError("style lacks TSS.StyleArchive super")
+        super_message = Message.parse(bytes(super_field.value))
+        parent = super_message.one(STYLE_PARENT)
+        if parent is None:
+            raise ValueError("style template has no parent style")
+        identifier = parse_reference(bytes(parent.value))
+        if identifier is None:
+            raise ValueError("style parent reference is empty")
+        return identifier
+
+    def _template(self) -> LocatedObject:
+        choices: list[LocatedObject] = []
+        for obj in self.document.object_messages():
+            if obj.info.type_id != TYPE_CHARACTER_STYLE:
+                continue
+            super_field = obj.message.one(STYLE_SUPER)
+            if super_field is None:
+                continue
+            super_message = Message.parse(bytes(super_field.value))
+            anonymous = super_message.one(STYLE_ANONYMOUS)
+            if anonymous is not None and int(anonymous.value) == 1 and super_message.one(STYLE_PARENT):
+                choices.append(obj)
+        if not choices:
+            raise ValueError("document has no anonymous character style with a parent")
+        choices.sort(key=lambda obj: obj.segment.identifier)
+        return choices[0]
+
+    def _paragraph_template(self) -> LocatedObject:
+        choices = [
+            obj
+            for obj in self.document.object_messages()
+            if obj.info.type_id == TYPE_PARAGRAPH_STYLE
+            and is_anonymous_style(obj)
+            and obj.message.one(STYLE_SUPER)
+        ]
+        choices = [obj for obj in choices if Message.parse(bytes(obj.message.one(1).value)).one(3)]
+        if not choices:
+            raise ValueError("document has no anonymous paragraph style with a parent")
+        choices.sort(key=lambda obj: obj.segment.identifier)
+        return choices[0]
+
+    def default_paragraph_style(self) -> LocatedObject:
+        named = []
+        for obj in self.document.object_messages():
+            if obj.info.type_id != TYPE_PARAGRAPH_STYLE or is_anonymous_style(obj):
+                continue
+            super_field = obj.message.one(STYLE_SUPER)
+            if super_field is None:
+                continue
+            name = Message.parse(bytes(super_field.value)).one(1)
+            if name is not None:
+                named.append((bytes(name.value).decode("utf-8", "replace"), obj))
+        for name, obj in named:
+            if name == "Body":
+                return obj
+        if not named:
+            raise ValueError("document has no named paragraph style")
+        return named[0][1]
+
+    def named_paragraph_style(self, name: str) -> LocatedObject:
+        for obj in self.document.object_messages():
+            if obj.info.type_id != TYPE_PARAGRAPH_STYLE or is_anonymous_style(obj):
+                continue
+            super_field = obj.message.one(STYLE_SUPER)
+            if super_field is None:
+                continue
+            name_field = Message.parse(bytes(super_field.value)).one(1)
+            if name_field is not None and bytes(name_field.value).decode("utf-8", "replace") == name:
+                return obj
+        raise KeyError(f"paragraph style {name!r} was not found")
+
+    def named_character_style(self, name: str) -> LocatedObject:
+        for obj in self.document.object_messages():
+            if obj.info.type_id != TYPE_CHARACTER_STYLE or is_anonymous_style(obj):
+                continue
+            if style_name(obj) == name:
+                return obj
+        raise KeyError(f"character style {name!r} was not found")
+
+    def named_styles(self) -> list[LocatedObject]:
+        registered = {
+            parse_reference(bytes(field.value))
+            for field in self.archive.message.get(STYLESHEET_STYLES)
+        }
+        return [
+            obj
+            for obj in self.document.object_messages()
+            if obj.segment.identifier in registered
+            and obj.info.type_id in (TYPE_CHARACTER_STYLE, TYPE_PARAGRAPH_STYLE)
+            and not is_anonymous_style(obj)
+            and style_name(obj) is not None
+        ]
+
+    def register_style(self, style: LocatedObject, parent_identifier: int) -> None:
+        identifier = style.segment.identifier
+        existing = {
+            parse_reference(bytes(field.value)) for field in self.archive.message.get(STYLESHEET_STYLES)
+        }
+        if identifier not in existing:
+            self.archive.message.add_bytes(STYLESHEET_STYLES, make_reference(identifier))
+
+        selected_field = None
+        selected = None
+        for field in self.archive.message.get(STYLESHEET_PARENT_TO_CHILDREN):
+            entry = Message.parse(bytes(field.value))
+            parent = entry.one(1)
+            if parent and parse_reference(bytes(parent.value)) == parent_identifier:
+                selected_field, selected = field, entry
+                break
+        if selected is None:
+            selected = Message()
+            selected.add_bytes(1, make_reference(parent_identifier))
+            selected_field = self.archive.message.add_bytes(
+                STYLESHEET_PARENT_TO_CHILDREN, selected.encode()
+            )
+        children = {parse_reference(bytes(field.value)) for field in selected.get(2)}
+        if identifier not in children:
+            selected.add_bytes(2, make_reference(identifier))
+            selected_field.set_bytes(selected.encode())
+
+        add_object_reference(self.archive.info, identifier)
+
+    def synthesize_character_style(
+        self,
+        props: CharacterProperties,
+        *,
+        experimental_allow_paragraph_background: bool = False,
+    ) -> tuple[LocatedObject, dict]:
+        if props.override_count == 0:
+            raise ValueError("cannot synthesize an empty character style")
+        if (
+            props.background_color is not None
+            and not experimental_allow_paragraph_background
+        ):
+            raise ValueError(
+                "Pages field-26 background is paragraph-scoped; use "
+                "Paragraph.background_color or Paragraph.highlight_color"
+            )
+        cached = self._cache.get(props)
+        if cached is not None:
+            return cached, {"style_cache_hit": True, "style_id": cached.segment.identifier}
+
+        template = self._template()
+        package = self.document.package_metadata()
+        identifier = self.document.allocate_object_identifier()
+        payload = Message.parse(template.message.encode())
+        properties = payload.one(STYLE_CHAR_PROPERTIES)
+        encoded_properties = encode_character_properties(props)
+        if properties is None:
+            payload.add_bytes(STYLE_CHAR_PROPERTIES, encoded_properties)
+        else:
+            properties.set_bytes(encoded_properties)
+        override_count = payload.one(10)
+        if override_count is None:
+            payload.add_varint(10, props.override_count)
+        else:
+            override_count.set_varint(props.override_count)
+
+        header = Message.parse(template.segment.header.encode())
+        header_identifier = header.one(1)
+        if header_identifier is None:
+            raise ValueError("style ArchiveInfo lacks identifier")
+        header_identifier.set_varint(identifier)
+        info_fields = header.get(2)
+        if len(info_fields) != 1:
+            raise ValueError("style template must contain exactly one MessageInfo")
+        info_field = info_fields[0]
+        info_message = Message.parse(bytes(info_field.value))
+        length_field = info_message.one(3)
+        if length_field is None:
+            raise ValueError("style MessageInfo lacks payload length")
+        new_info = MessageInfo(info_field, info_message, TYPE_CHARACTER_STYLE, int(length_field.value))
+        new_info.update_length(len(payload.encode()))
+        segment = ArchiveSegment(header, b"", identifier, [new_info], [payload], [b""])
+        self.document.iwa_files[template.filename].segments.append(segment)
+        created = LocatedObject(template.filename, segment, new_info, payload)
+
+        parent_identifier = self.parent_identifier(created)
+        self.register_style(created, parent_identifier)
+        revision = package_revision_identifier(package.message)
+        signature = repr(props)
+        object_uuid, component_id = register_component_object(
+            package.message,
+            "DocumentStylesheet",
+            identifier,
+            uuid_seed=f"python-pages:{revision}:{identifier}:{signature}",
+        )
+        register_external_reference(package.message, "Document", component_id, identifier)
+        self._cache[props] = created
+        return created, {
+            "style_cache_hit": False,
+            "style_template_id": template.segment.identifier,
+            "style_id": identifier,
+            "parent_style_id": parent_identifier,
+            "override_count": props.override_count,
+            "object_uuid": object_uuid,
+            "component_id": component_id,
+        }
+
+    def paragraph_style_context(
+        self, identifier: int | None
+    ) -> tuple[int, bytes, ParagraphProperties]:
+        style = self.paragraph_style(identifier)
+        if style is None:
+            return self.default_paragraph_style().segment.identifier, b"", ParagraphProperties()
+        if not is_anonymous_style(style):
+            return style.segment.identifier, b"", ParagraphProperties()
+        parent = self.parent_identifier(style)
+        character = style.message.one(STYLE_CHAR_PROPERTIES)
+        character_raw = bytes(character.value) if character else b""
+        return parent, character_raw, paragraph_style_properties(style)
+
+    def synthesize_paragraph_style(
+        self,
+        parent_identifier: int,
+        props: ParagraphProperties,
+        *,
+        character_properties: bytes = b"",
+    ) -> tuple[LocatedObject, dict]:
+        key = (parent_identifier, character_properties, props)
+        cached = self._paragraph_cache.get(key)
+        if cached is not None:
+            return cached, {"style_cache_hit": True, "style_id": cached.segment.identifier}
+
+        if props.override_count == 0 and not character_properties:
+            parent = self.paragraph_style(parent_identifier)
+            if parent is None:
+                raise ValueError(f"paragraph parent style {parent_identifier} was not found")
+            return parent, {"style_cache_hit": True, "style_id": parent_identifier}
+
+        template = self._paragraph_template()
+        package = self.document.package_metadata()
+        identifier = self.document.allocate_object_identifier()
+        payload = Message.parse(template.message.encode())
+        super_field = payload.one(STYLE_SUPER)
+        if super_field is None:
+            raise ValueError("paragraph style template lacks TSS.StyleArchive super")
+        super_message = Message.parse(bytes(super_field.value))
+        parent_field = super_message.one(STYLE_PARENT)
+        if parent_field is None:
+            super_message.add_bytes(STYLE_PARENT, make_reference(parent_identifier))
+        else:
+            parent_field.set_bytes(make_reference(parent_identifier))
+        anonymous = super_message.one(STYLE_ANONYMOUS)
+        if anonymous is None:
+            super_message.add_varint(STYLE_ANONYMOUS, 1)
+        else:
+            anonymous.set_varint(1)
+        super_field.set_bytes(super_message.encode())
+
+        payload.fields = [
+            item for item in payload.fields if item.number not in (10, 11, STYLE_PARA_PROPERTIES)
+        ]
+        total_overrides = props.override_count
+        if character_properties:
+            total_overrides += len(Message.parse(character_properties).fields)
+        payload.add_varint(10, total_overrides)
+        if character_properties:
+            payload.add_bytes(STYLE_CHAR_PROPERTIES, character_properties)
+        if props.override_count:
+            payload.add_bytes(STYLE_PARA_PROPERTIES, encode_paragraph_properties(props))
+        elif character_properties:
+            # Pages-authored anonymous type-2022 styles with character-only
+            # overrides retain an explicit empty ParagraphStylePropertiesArchive
+            # field. Match that observed wire shape exactly.
+            payload.add_bytes(STYLE_PARA_PROPERTIES, b"")
+
+        header = Message.parse(template.segment.header.encode())
+        header_identifier = header.one(1)
+        if header_identifier is None:
+            raise ValueError("paragraph style ArchiveInfo lacks identifier")
+        header_identifier.set_varint(identifier)
+        info_fields = header.get(2)
+        if len(info_fields) != 1:
+            raise ValueError("paragraph style template must contain exactly one MessageInfo")
+        info_field = info_fields[0]
+        info_message = Message.parse(bytes(info_field.value))
+        type_field = info_message.one(1)
+        length_field = info_message.one(3)
+        if (
+            type_field is None
+            or int(type_field.value) != TYPE_PARAGRAPH_STYLE
+            or length_field is None
+        ):
+            raise ValueError("paragraph style template has incompatible MessageInfo")
+        new_info = MessageInfo(
+            info_field,
+            info_message,
+            TYPE_PARAGRAPH_STYLE,
+            int(length_field.value),
+        )
+        new_info.update_length(len(payload.encode()))
+        segment = ArchiveSegment(header, b"", identifier, [new_info], [payload], [b""])
+        self.document.iwa_files[template.filename].segments.append(segment)
+        created = LocatedObject(template.filename, segment, new_info, payload)
+
+        self.register_style(created, parent_identifier)
+        revision = package_revision_identifier(package.message)
+        object_uuid, component_id = register_component_object(
+            package.message,
+            "DocumentStylesheet",
+            identifier,
+            uuid_seed=(
+                f"python-pages:{revision}:{identifier}:paragraph:"
+                f"{parent_identifier}:{character_properties.hex()}:{props!r}"
+            ),
+        )
+        register_external_reference(package.message, "Document", component_id, identifier)
+        self._paragraph_cache[key] = created
+        return created, {
+            "style_cache_hit": False,
+            "style_template_id": template.segment.identifier,
+            "style_id": identifier,
+            "parent_style_id": parent_identifier,
+            "override_count": total_overrides,
+            "object_uuid": object_uuid,
+            "component_id": component_id,
+        }