inkfold 0.5.0__py3-none-any.whl

inkfold/__init__.py

@@ -0,0 +1,16 @@
+"""
+inkfold service layer: ``builder`` -> ``delivery`` -> ``gmail`` / ``outlook``.
+
+Two seams hold the chain apart, and both are load-bearing:
+
+**Builder to delivery** — the builder *declares* CID embeds. For every
+``src="cid:X"`` in the HTML, :meth:`Email.assets` has the entry describing
+what to attach as ``X``; delivery *performs* the attachment.
+
+**Delivery to an adapter** — delivery assembles bytes, an adapter transmits
+them. Adapters own their provider's wire contract and error semantics and
+**never** authentication, so inkfold depends on no provider SDK.
+
+This package re-exports nothing: import from ``inkfold.builder``,
+``inkfold.delivery``, ``inkfold.gmail`` or ``inkfold.outlook`` directly.
+"""

inkfold/brochure/__init__.py

@@ -0,0 +1,43 @@
+"""
+The brochure medium: one sheet folded into panels, printed on both sides.
+
+``Brochure`` is the product; ``Panel`` is the layout unit, and flattens in any
+other medium as ``Page`` does; ``FoldFormat`` is the sheet and its fold, and
+its presets are the shipped folds. Imposition, from the reader's order to the
+printer's, is the medium's and never the caller's.
+"""
+
+from .document import Brochure
+from .fit import overflowing_panels
+from .fold import (
+    BI_FOLD_LETTER,
+    FOLD_FORMATS,
+    GATE_FOLD_A4,
+    TRI_FOLD_LETTER,
+    Z_FOLD_LETTER,
+    FoldFormat,
+    FoldKind,
+)
+from .imposition import FACE_NAMES, IMPOSITION, face_name, impose
+from .medium import BROCHURE_MEDIUM, brochure_medium
+from .panel import Panel, PanelBox
+
+__all__ = [
+    "BI_FOLD_LETTER",
+    "BROCHURE_MEDIUM",
+    "FACE_NAMES",
+    "FOLD_FORMATS",
+    "GATE_FOLD_A4",
+    "IMPOSITION",
+    "TRI_FOLD_LETTER",
+    "Z_FOLD_LETTER",
+    "Brochure",
+    "FoldFormat",
+    "FoldKind",
+    "Panel",
+    "PanelBox",
+    "brochure_medium",
+    "face_name",
+    "impose",
+    "overflowing_panels",
+]

inkfold/brochure/checks.py

@@ -0,0 +1,126 @@
+"""
+What a print house rejects, checked before anything renders (#188).
+
+Both checks read facts the brochure already holds at construction: the fold's
+arithmetic and each image's own bytes. Neither is on the medium's
+``constraints``, because a ``Constraint`` sees only the composed markup, and
+neither a panel's inset nor an image's pixel count is in it.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+
+from inkfold.builder.exceptions import PrintQualityWarning, ValidationError, warn_caller
+from inkfold.builder.images import EmailImage, pixel_size
+from inkfold.config import get_config
+
+from .fold import FoldFormat
+from .imposition import face_name, impose
+from .panel import Panel
+
+#: CSS px per inch: every width in the package is px at 96 dpi.
+CSS_DPI = 96
+
+
+def panel_label(fold: FoldFormat, reader: int, panel: Panel) -> str:
+    """How an error names a panel: its face, and its title when it has one."""
+    named = f" ({panel.title!r})" if panel.title else ""
+    return f"the {face_name(fold, reader)}{named}"
+
+
+def validate_safe_area(fold: FoldFormat, panels: Sequence[Panel]) -> None:
+    """
+    Every panel keeps its copy at least ``fold.safe`` from its edges.
+
+    Raises:
+        ValidationError: Naming the first panel that does not, and both distances.
+    """
+    for reader, panel in enumerate(panels, start=1):
+        inset = fold.inset if panel.inset is None else panel.inset
+        if inset < fold.safe:
+            raise ValidationError(
+                f"{panel_label(fold, reader, panel)} keeps its copy {inset}px from the "
+                f"trim, inside the {fold.safe}px safe distance, where a cut can reach it. "
+                f"Give it an inset of at least {fold.safe}."
+            )
+
+
+def validate_inset_room(fold: FoldFormat, panels: Sequence[Panel]) -> None:
+    """
+    Every panel's inset leaves it a content width and a content height (#460).
+
+    The inset is taken from both edges of each axis, so it must stay under half
+    the panel's box. Without this the frame refuses the render, naming neither
+    the panel nor the inset.
+
+    Raises:
+        ValidationError: Naming the first panel with no room, its inset and its box.
+    """
+    for panel_box, (reader, panel) in zip(impose(fold), enumerate(panels, start=1), strict=True):
+        inset = fold.inset if panel.inset is None else panel.inset
+        for axis, length in (("width", panel_box.width), ("height", panel_box.height)):
+            if inset * 2 >= length:
+                raise ValidationError(
+                    f"{panel_label(fold, reader, panel)} has an inset of {inset}px, which leaves "
+                    f"no content {axis} inside its {length}px {axis}: an inset is taken from "
+                    f"both edges. Give it an inset below {length / 2:g}."
+                )
+
+
+def required_pixels(display_width: int | float, dpi: int | None = None) -> int:
+    """Source pixels an image displayed ``display_width`` px wide needs to print at ``dpi``."""
+    return math.ceil(display_width * (dpi or get_config().print_dpi) / CSS_DPI)
+
+
+def validate_image_resolution(
+    images: Sequence[
+        EmailImage
+        | tuple[EmailImage, int | float | None]
+        | tuple[EmailImage, int | float | None, str]
+    ],
+    dpi: int | None = None,
+) -> None:
+    """
+    Every image carries enough pixels to print at ``Config.print_dpi``.
+
+    An entry is an image, displayed at its own ``width`` (or its pixel width
+    when it has none), or an ``(image, display width)`` pair for one that
+    fills a box instead, such as a panel's ground. Below the target warns with
+    a ``PrintQualityWarning``, as the email's 90 KB threshold does; below half of it raises. A
+    hosted image has no bytes to measure, and the PDF exporter refuses it.
+    ``dpi`` sets another target, as a deck sets a screen's (#348). A third
+    element says where the use sits, and the message ends with it (#458).
+
+    Raises:
+        ValidationError: Naming the image, its pixel width and the width it needs.
+    """
+    dpi = dpi or get_config().print_dpi
+    for entry in images:
+        fills: int | float | None = None
+        where: str | None = None
+        if isinstance(entry, EmailImage):
+            image = entry
+        else:
+            image, fills, *rest = entry
+            where = rest[0] if rest else None
+        used = f" It is {where}." if where else ""
+        size = pixel_size(image.data) if image.data else None
+        if size is None:
+            continue
+        pixels = size[0]
+        display = fills or image.width or pixels
+        needed = required_pixels(display, dpi)
+        if pixels * 2 < needed:
+            raise ValidationError(
+                f"the image {image.alt or image.filename!r} is {pixels}px wide and displayed "
+                f"at {display}px, which prints at {pixels * CSS_DPI / display:.0f} dpi. "
+                f"It needs {needed}px to print at {dpi} dpi.{used}"
+            )
+        if pixels < needed:
+            warn_caller(
+                f"the image {image.alt or image.filename!r} is {pixels}px wide and "
+                f"needs {needed}px to print at {dpi} dpi.{used}",
+                PrintQualityWarning,
+            )

inkfold/brochure/document.py

@@ -0,0 +1,197 @@
+"""
+``Brochure`` — panels in the order a reader meets them, printed in the order a press needs.
+
+The brochure counterpart to :class:`~inkfold.document.document.PagedDocument`.
+The caller hands over panels in reader order; the fold's imposition decides
+which side and position each one prints at, and the same three projections
+follow.
+"""
+
+from __future__ import annotations
+
+import copy
+from pathlib import Path
+from typing import Any, ClassVar, Self
+
+from inkfold.builder.containers import Container
+from inkfold.builder.document import Document
+from inkfold.builder.engine import Renderer, TemplateOverlay
+from inkfold.builder.exceptions import ValidationError
+from inkfold.builder.images import EmailImage
+from inkfold.builder.models import DocumentMetadata
+from inkfold.config import Config
+
+from .checks import (
+    panel_label,
+    validate_image_resolution,
+    validate_inset_room,
+    validate_safe_area,
+)
+from .fold import TRI_FOLD_LETTER, FoldFormat, _px
+from .imposition import face_name, impose, sides
+from .medium import brochure_medium
+from .panel import Panel
+
+
+class Brochure(Document):
+    """
+    One sheet, folded: its panels, its fold, and the print it becomes.
+
+    **Reader order is the only order the API speaks.** Panels are given as a
+    reader meets them, front cover first, and no argument takes a printer
+    position: imposition is a rendering fact the fold owns. The plain-text
+    projection is reader order too, because a text reader reads.
+
+    **The panels are fixed at construction**, and their count must be the
+    fold's: a five-panel tri-fold is an error, not a blank face.
+    :meth:`add_section` is refused.
+
+    **Footnotes are refused.** A note floats to the foot of a sheet, and a
+    side's foot runs under three panels that a reader meets separately. So is
+    a panel inset inside the safe distance, and an image too coarse to print.
+
+    Args:
+        metadata:     Mapping of facts, or a ``DocumentMetadata``.
+        panels:       Every face of the sheet, in reader order.
+        fold:         The sheet and its fold. Defaults to a letter tri-fold.
+        template_dir: Root of the templates. Defaults to the packaged copy.
+        config, template_overlay: As ``Document`` takes them; print dpi is a limit.
+
+    Raises:
+        ValidationError: If the panel count is not the fold's, a panel is not
+            a :class:`~inkfold.brochure.panel.Panel`, or a component carries a
+            footnote.
+    """
+
+    METADATA: ClassVar[type[DocumentMetadata]] = DocumentMetadata
+
+    def __init__(
+        self,
+        metadata: dict[str, Any] | DocumentMetadata,
+        panels: list[Panel],
+        fold: FoldFormat = TRI_FOLD_LETTER,
+        template_dir: Path | None = None,
+        *,
+        config: Config | None = None,
+        template_overlay: TemplateOverlay = None,
+    ):
+        super().__init__(
+            metadata,
+            template_dir,
+            brochure_medium(fold),
+            config=config,
+            template_overlay=template_overlay,
+        )
+        self._fold = fold
+        self._proof = False
+        if len(panels) != fold.faces:
+            raise ValidationError(
+                f"a {fold.kind.value}-fold has {fold.faces} panels, "
+                f"{fold.panels} a side; got {len(panels)}. Pass every face in reader "
+                f"order: {', '.join(face_name(fold, n) for n in range(1, fold.faces + 1))}."
+            )
+        for reader, panel in enumerate(panels, start=1):
+            if not isinstance(panel, Panel):
+                raise ValidationError(
+                    f"the {face_name(fold, reader)} must be a Panel, got: {type(panel).__name__}"
+                )
+            Document.add_section(self, panel)
+        if self._footnotes():
+            raise ValidationError(
+                "a brochure cannot carry footnotes: a note floats to the foot of a sheet, "
+                "and a side's foot runs under three panels. Put the note in the panel's copy."
+            )
+        validate_safe_area(fold, panels)
+        validate_inset_room(fold, panels)
+        # One image may ground two panels of different widths, so each use is
+        # measured at its own box and named by it (#458).
+        uses: list[tuple[EmailImage, int | float | None, str]] = []
+        for box, (reader, panel) in zip(impose(fold), enumerate(panels, start=1), strict=True):
+            label = panel_label(fold, reader, panel)
+            if panel.background_image is not None:
+                width = box.ground(fold.bleed, fold.panels)["width"]
+                uses.append((panel.background_image, width, f"the ground of {label}"))
+            uses.extend(
+                (image, None, f"in {label}")
+                for section in panel.sections
+                for image in section.images()
+            )
+        with self.configured():
+            validate_image_resolution(uses)
+
+    @property
+    def fold(self) -> FoldFormat:
+        """The sheet and its fold."""
+        return self._fold
+
+    @property
+    def panels(self) -> list[Panel]:
+        """Every panel, in reader order."""
+        return [section for section in self._sections if isinstance(section, Panel)]
+
+    def add_section(self, container: Container) -> Self:
+        """Refused: a brochure's panels are fixed by its fold, and given at construction."""
+        raise ValidationError(
+            "a brochure's panels are given at construction, all "
+            f"{self._fold.faces} of them; a folded sheet has no room for another section"
+        )
+
+    def render(self, proof: bool | None = None) -> str:
+        """
+        Render both sides of the sheet.
+
+        ``proof=True`` draws a light guide on every fold and labels each panel
+        with its reader index and name, so a designer can check the
+        imposition without folding paper. ``None`` takes this brochure's own
+        setting, which is off unless it came from :meth:`proof`.
+        """
+        standing = self._proof
+        self._proof = standing if proof is None else proof
+        try:
+            return super().render()
+        finally:
+            self._proof = standing
+
+    def proof(self) -> Brochure:
+        """
+        This brochure as a proof: the same panels, rendered with guides and labels.
+
+        A copy, so the brochure a printer is sent never carries the flag, and
+        ``render_pdf(brochure.proof())`` prints a proof through the unchanged
+        exporter.
+        """
+        proof = copy.copy(self)
+        proof._proof = True
+        return proof
+
+    def inset(self, panel: Panel) -> int | float:
+        """The distance ``panel`` keeps its copy from its edges: its own, or the fold's."""
+        return self._fold.inset if panel.inset is None else panel.inset
+
+    def _body_context(self, engine: Renderer, sections: list[Container]) -> dict[str, Any]:
+        """The two sides, each holding its panels in the printer's order, and the print marks."""
+        fold, panels, boxes = self._fold, self.panels, impose(self._fold)
+        rendered = {}
+        for box in boxes:
+            panel = panels[box.reader - 1]
+            rendered[box.reader] = panel.render_box(engine, box, self.inset(panel), fold)
+        sides_html = "\n".join(
+            engine.render(
+                "brochure/side.html",
+                {
+                    "side": side,
+                    "panels_html": "\n".join(rendered[reader] for reader in readers),
+                    "proof": self._proof,
+                    "folds": [_px(edge) for edge in fold.offsets(side)[1:]],
+                    "labels": [
+                        {"box": boxes[reader - 1], "name": face_name(fold, reader)}
+                        for reader in readers
+                    ],
+                },
+            )
+            for side, readers in enumerate(sides(fold), start=1)
+        )
+        # The print engine draws its marks inside the declared bleed, under
+        # whatever is painted there, so the declared bleed is the real bleed
+        # plus a slug the grounds never reach.
+        return {"sections_html": sides_html, "print_bleed": _px(fold.bleed + fold.slug)}

inkfold/brochure/fit.py

@@ -0,0 +1,44 @@
+"""
+Whether every panel's copy fits inside its safe line, asked of the print engine.
+
+A panel clips what overflows it (#186), and a clip is silent in the PDF. This
+lays the brochure out and reads back where each panel's closing sentinel
+landed. It needs the ``[pdf]`` extra, imported only on use.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .document import Brochure
+from .imposition import face_name, impose
+
+if TYPE_CHECKING:  # pragma: no cover - the exporter is imported only on use
+    from inkfold.pdf import Layout
+
+
+def overflowing_panels(brochure: Brochure, laid_out: Layout | None = None) -> list[str]:
+    """
+    Every panel whose copy runs past its safe line, named by reader index and face.
+
+    A panel's sentinel lands below ``height - inset`` when its copy overflows
+    within the sheet, and nowhere at all when it overflows off it: the print
+    engine records no position for an element it did not place on a page.
+    Empty when everything fits. ``laid_out``, a :func:`~inkfold.pdf.layout`
+    of this brochure, is read rather than laying it out again.
+
+    Raises:
+        ValueError: If ``laid_out`` is a layout of another document.
+        inkfold.pdf.BackendMissingError: If WeasyPrint is not installed.
+    """
+    from inkfold.pdf import anchor_tops
+
+    if laid_out is not None and laid_out.document is not brochure:
+        raise ValueError("laid_out is a layout of another document, not this brochure")
+    landed = anchor_tops(brochure if laid_out is None else laid_out)
+    overflowing = []
+    for box, panel in zip(impose(brochure.fold), brochure.panels, strict=True):
+        y = landed.get(f"panel-{box.reader}-end")
+        if y is None or y > box.height - brochure.inset(panel):
+            overflowing.append(f"panel {box.reader} ({face_name(brochure.fold, box.reader)})")
+    return overflowing

inkfold/brochure/fold.py

@@ -0,0 +1,223 @@
+"""
+Fold geometry: a sheet, a fold, and the panels the fold makes of it.
+
+A brochure is laid out on panels, not on the sheet. This module turns a sheet
+and a fold into panel widths, in px at 96 dpi like every size in the package,
+and is the only place those widths are computed.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum
+
+from inkfold.builder.exceptions import ValidationError
+from inkfold.builder.finite import require_finite
+from inkfold.builder.sizing import PageFormat
+
+
+class FoldKind(StrEnum):
+    """How a sheet is folded, which decides both its panel widths and its imposition."""
+
+    #: One fold down the middle: four faces, two a side.
+    BI = "bi"
+    #: A letter, or roll, fold: the right third folds in, the left third over
+    #: it. Six faces; the panel that folds inside is the narrow one.
+    C = "c"
+    #: An accordion: two folds in opposite directions, three equal panels.
+    Z = "z"
+    #: Two flaps fold in from the edges to meet over a double-width centre.
+    GATE = "gate"
+
+
+#: Panels on each side of the sheet, per fold.
+PANELS_PER_SIDE: dict[FoldKind, int] = {
+    FoldKind.BI: 2,
+    FoldKind.C: 3,
+    FoldKind.Z: 3,
+    FoldKind.GATE: 3,
+}
+
+#: The folds whose inner panels must be narrower to close flat. A Z-fold's
+#: panels never nest and a bi-fold's two halves meet edge to edge.
+_TUCKED = frozenset({FoldKind.C, FoldKind.GATE})
+
+
+@dataclass(frozen=True)
+class FoldFormat:
+    """
+    A sheet and how it folds: everything panel geometry is computed from.
+
+    **The tuck is a distance, not a ratio.** A panel that folds inside another
+    must be a few millimetres narrower or it buckles against the crease, and
+    that allowance does not grow with the sheet. So this is not
+    :func:`~inkfold.builder.sizing.column_layout`, which splits a content width by
+    weights with gutters between; `brochure.md` has why it was not widened.
+
+    ``panels`` is derived from ``kind``, as ``Medium.slots`` is from its
+    regions, so the two cannot disagree. Every width is px at 96 dpi, and an
+    ``int`` when whole: the size layers refuse ``356.0``.
+
+    Args:
+        sheet: The flat sheet, landscape, with no margin: a panel insets its
+               own copy, and a sheet margin would inset the edges twice.
+        kind:  The fold.
+        tuck:  How much narrower each inside panel is, in px. Zero for a
+               bi-fold and a Z-fold, which have no panel that nests.
+        inset: How far a panel keeps its copy from its edges unless the
+               panel says otherwise, in px. 24px is 1/4in (6.4mm).
+        safe:  The least inset any panel may keep (#188): copy nearer the
+               trim than this risks being cut. 12px is 1/8in (3.2mm).
+        bleed: How far a panel's ground runs past the trim, so a cut that
+               lands a hair outside leaves no white sliver. 12px, 1/8in.
+        slug:  Room past the bleed for the crop and registration marks.
+               24px, 1/4in.
+    """
+
+    sheet: PageFormat
+    kind: FoldKind
+    tuck: int | float = 0
+    inset: int | float = 24
+    safe: int | float = 12
+    bleed: int | float = 12
+    slug: int | float = 24
+
+    def __post_init__(self) -> None:
+        try:
+            object.__setattr__(self, "kind", FoldKind(self.kind))
+        except ValueError:
+            raise ValidationError(
+                f"'fold.kind' must be one of {[k.value for k in FoldKind]}, got: {self.kind!r}"
+            ) from None
+        if self.sheet.height is None:
+            raise ValidationError("'fold.sheet' must have a height: a continuous page cannot fold")
+        if self.sheet.orientation != "landscape":
+            raise ValidationError(
+                f"'fold.sheet' must be landscape, got {self.sheet.orientation}: the panels "
+                "stand side by side across the sheet's width"
+            )
+        if any(
+            (
+                self.sheet.margin.top,
+                self.sheet.margin.right,
+                self.sheet.margin.bottom,
+                self.sheet.margin.left,
+            )
+        ):
+            raise ValidationError(
+                "'fold.sheet' must have no margin: a panel insets its own copy, so a sheet "
+                "margin would inset the outer panels twice"
+            )
+        if isinstance(self.tuck, bool) or not isinstance(self.tuck, (int, float)):
+            raise ValidationError(f"'fold.tuck' must be a number, got: {type(self.tuck).__name__}")
+        require_finite(self.tuck, "fold.tuck")
+        if self.tuck < 0:
+            raise ValidationError(f"'fold.tuck' must not be negative, got: {self.tuck}")
+        if self.tuck and self.kind not in _TUCKED:
+            raise ValidationError(
+                f"a {self.kind.value}-fold has no panel that folds inside another, so "
+                f"'fold.tuck' must be 0, got: {self.tuck}"
+            )
+        for name in ("inset", "safe", "bleed", "slug"):
+            value = getattr(self, name)
+            require_finite(value, f"fold.{name}")
+            if value < 0:
+                raise ValidationError(f"'fold.{name}' must be a number of px, got: {value!r}")
+        if self.inset < self.safe:
+            raise ValidationError(
+                f"'fold.inset' ({self.inset}) is inside the safe distance ({self.safe}): "
+                "every panel that took the default would be refused"
+            )
+        if min(self.widths) <= 0:
+            raise ValidationError(f"'fold.tuck' ({self.tuck}) leaves a panel with no width")
+
+    @property
+    def panels(self) -> int:
+        """Panels on each side of the sheet."""
+        return PANELS_PER_SIDE[self.kind]
+
+    @property
+    def faces(self) -> int:
+        """Panels a reader meets, both sides together: what a brochure is given."""
+        return 2 * self.panels
+
+    @property
+    def width(self) -> int | float:
+        """The sheet's width."""
+        return self.sheet.width
+
+    @property
+    def height(self) -> int | float:
+        """The sheet's height, which is every panel's height."""
+        assert self.sheet.height is not None  # refused in __post_init__
+        return self.sheet.height
+
+    @property
+    def widths(self) -> tuple[int | float, ...]:
+        """
+        Side 1's panel widths, left to right. Sum exactly to the sheet.
+
+        Side 2 is the mirror: a sheet turned over puts side 1's left panel
+        behind side 2's right, and a panel is one width on both faces. See
+        :meth:`side_widths`.
+        """
+        width, tuck = self.width, self.tuck
+        if self.kind is FoldKind.BI:
+            half = _px(width / 2)
+            return (half, _px(width - half))
+        if self.kind is FoldKind.Z:
+            third = _px(width / 3)
+            return (third, third, _px(width - 2 * third))
+        if self.kind is FoldKind.C:
+            # Two full panels and the tuck panel, which is full less the tuck.
+            # It sits at side 1's left so it backs side 2's right, the panel
+            # that folds in first.
+            full = _px((width + tuck) / 3)
+            return (_px(width - 2 * full), full, full)
+        # GATE: two flaps meeting short of the middle by the tuck, over a
+        # centre panel that takes whatever the flaps leave.
+        flap = _px((width / 2 - tuck) / 2)
+        return (flap, _px(width - 2 * flap), flap)
+
+    def side_widths(self, side: int) -> tuple[int | float, ...]:
+        """One side's panel widths, left to right; ``side`` is 1 or 2."""
+        if side not in (1, 2):
+            raise ValidationError(f"a sheet has sides 1 and 2, got: {side!r}")
+        return self.widths if side == 1 else tuple(reversed(self.widths))
+
+    def offsets(self, side: int) -> tuple[int | float, ...]:
+        """Each panel's left edge on one side, from the sheet's left edge."""
+        edges: list[int | float] = []
+        running: int | float = 0
+        for width in self.side_widths(side):
+            edges.append(_px(running))
+            running += width
+        return tuple(edges)
+
+
+def _px(value: int | float) -> int | float:
+    """A width as an ``int`` when whole, so it never prints as ``356.0px``."""
+    return int(value) if float(value).is_integer() else value
+
+
+#: The flat sheets, landscape, in px at 96 dpi. Letter is 11 x 8.5in; A4 is
+#: 297 x 210mm. No margin: see ``FoldFormat.sheet``.
+LETTER_SHEET = PageFormat(width=1056, height=816)
+A4_SHEET = PageFormat(width=1123, height=794)
+
+#: The shipped folds. Every preset's widths are pinned by a test.
+#:
+#: The C-fold's tuck is 12px, 1/8in (3.2mm): 356 + 356 + 344. The gate's is
+#: 7.5px, 2mm, which leaves each flap a whole 277px over a 569px centre.
+BI_FOLD_LETTER = FoldFormat(sheet=LETTER_SHEET, kind=FoldKind.BI)
+TRI_FOLD_LETTER = FoldFormat(sheet=LETTER_SHEET, kind=FoldKind.C, tuck=12)
+Z_FOLD_LETTER = FoldFormat(sheet=LETTER_SHEET, kind=FoldKind.Z)
+GATE_FOLD_A4 = FoldFormat(sheet=A4_SHEET, kind=FoldKind.GATE, tuck=7.5)
+
+#: Every shipped fold by name, as ``PAGE_FORMATS`` names every page.
+FOLD_FORMATS: dict[str, FoldFormat] = {
+    "bi_fold_letter": BI_FOLD_LETTER,
+    "tri_fold_letter": TRI_FOLD_LETTER,
+    "z_fold_letter": Z_FOLD_LETTER,
+    "gate_fold_a4": GATE_FOLD_A4,
+}