stationery 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bfd8cada05438bcc43cc85da2535da95b55c2dbf6020bf95607bd8ebb65c8346
-  data.tar.gz: 1115be789042eebfdd48a036fc433994694236c4c133ede893a554478b6174bf
+  metadata.gz: 21d52a1f02122474b5316373c70965424f3479973757219d2b7b87ed453e8642
+  data.tar.gz: eaa7be7242e9f38e270cb23a533bac9038963c3e61c44c1e57ebaefe0288ef29
 SHA512:
-  metadata.gz: 2e55c39993d7c6c7c66373f5097a8796ac655b46eabe34eb148808cca220823112a728d4c26b971c54f163dc2b6c45f50f3b6481c050089871daf5964a4011d6
-  data.tar.gz: 456ca535dc230cbc747dac22322d7a0886ea8da7f70b159bb59224a2afe211dd1cb1a6e79a2a1a7c1f7b0d2007701b465fb49434484953db010a869ae6e4ad97
+  metadata.gz: 0dd292c0de3767e870563e954a9ea1b466beed56af675209d69baa09f7c44e337117a5b7256e41b4a35e39f694f0cfc721f2729cd1af8f7dc6081712a4263034
+  data.tar.gz: 73286d789a65a258a026fc65fe8bbc1287dfd2df6ee13d07177cac13beba4f0e7bbcbdfc4bbafc4b3643d762efeb6a3cfb9cb6ab019e6a14c1351a920bc998db

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.8.0 (2026-09-28)
+
+Compliance: PDF/A-3b, PDF/UA-1 and Factur-X e-invoices, verified with veraPDF and Mustang in CI.
+
+- Factur-X / ZUGFeRD: `factur_x(profile: :en16931) { @invoice.to_cii_xml }` (a block, a method name or the XML itself; also `to_pdf(factur_x:)`) embeds the invoice XML as `factur-x.xml` (`xrechnung.xml` for `:xrechnung`) with the relationship the profile requires, writes the `fx:` XMP properties with their extension-schema description and turns on PDF/A-3b. Profiles `:minimum`, `:basic_wl`, `:basic`, `:en16931`, `:extended`, `:xrechnung`. The gem does not build the XML; `examples/e_invoice.rb` shows a minimal EN 16931 document. `Inspector#factur_x`, `have_factur_x`, `assert_factur_x`; `rake verify:factur_x` validates with Mustang.
+- PDF/A and PDF/UA: `conformance :pdf_a3b` (or `:pdf_a2b`) and `conformance :pdf_ua1`, combinable, at class level or `to_pdf(conformance:)`. PDF/A writes an sRGB output intent (the ICC's `sRGB2014.icc`, bundled with its licence), `pdfaid` identification and printable link annotations, and refuses encryption and, under A-2b, attachments. PDF/UA turns `tagged` on, requires `metadata title:` and `lang:`, writes `pdfuaid:part 1`, tab order and link descriptions, and raises `ConformanceError` for a figure without `alt:`. CMYK colour under PDF/A is reported as `Warnings::ConformanceIssue`. Form fields are refused under every level until their appearances embed their fonts. `Inspector#conformance`, `have_conformance`, `assert_pdf_conformance`; `rake verify:conformance` runs veraPDF through Docker, and CI runs it on the examples.
+- XMP metadata: every document carries an XMP packet mirroring the Info dictionary (`dc:title`, `dc:creator`, `dc:description`, `dc:subject`, `dc:language`, `xmp:CreateDate`/`ModifyDate`/`MetadataDate`, `xmp:CreatorTool`, `pdf:Producer`, `pdf:Keywords`) as an uncompressed `/Metadata` stream; `metadata xmp: false` or `to_pdf(xmp: false)` opts out. `Inspector#xmp` and `#xmp_values`.
+- Embedded files: `attach_file "terms.pdf", data, mime:, description:, relationship:, modified_at:` at class level, `to_pdf(attachments: [...])` per render. Each file is a `/Filespec` in the catalog's `/EmbeddedFiles` name tree and `/AF`, with `/AFRelationship`, size, checksum and date; streams are compressed and encrypted with the document. `Inspector#attachments`, `have_attachment`, `assert_pdf_attachment`.
+- SVG: `use` (`href` or `xlink:href`, onto shapes, groups, text, symbols and other `use` elements, with cycle detection), `symbol` and nested `svg` viewports (`viewBox`, `preserveAspectRatio` with `meet`/`slice`/`none`, clipped unless `overflow="visible"`), and `clipPath` (`clip-path="url(#id)"` on shapes, groups, text and `use`; `clip-rule`, `clipPathUnits="objectBoundingBox"`, nested clip paths). The `color` property feeds `currentColor`, so one sprite symbol can be drawn in several colours. `image`, `mask`, `pattern`, `filter` and `textPath` stay unsupported and reported.
+- CLI: `stationery render file.rb` renders the document the file itself defines, so a file that subclasses a document from another file no longer asks for `--class`.
+
+## 0.7.0 (2026-09-28)
+
+Typography and images: hyphenation, OpenType features, oversized-image warnings, page labels.
+
+- Hyphenation: `hyphenate: true | "en" | "de" | "sv"` on `text`, `text_style`, `default_text` and the rich `styles:` (`p`, `li`). Liang's algorithm over the TeX `hyph-utf8` patterns for English, German and Swedish (bundled with their licences), so a word that does not fit breaks at the longest hyphenation point that does, with the font's hyphen. A soft hyphen (U+00AD, `­` in HTML) is a break point in any language: never drawn or measured unless the line breaks there, and absent from extracted text. Off by default; unchanged output otherwise.
+- OpenType features: `features: %i[smcp onum tnum ss01]` on the same entry points applies the font's GSUB single substitutions (formats 1 and 2, also behind Extension lookups) before ligatures; `Font#features` lists what a font offers, an absent feature is ignored. Substituted glyphs keep their source characters in ToUnicode. Contextual lookups (`calt`, `clig`, `frac`) stay unsupported and are listed as such.
+- Oversized images: a bitmap drawn at more than twice `max_ppi` (300 by default; `images max_ppi: 220` per document, `image(max_ppi:)` per call, `nil` disables) reports `Warnings::OversizedImage` naming the source, pixel width, effective ppi and the limit, so `strict` catches a 1600 px photo drawn 160 pt wide. `downscale: true` resamples a PNG (grey, RGB, palette, alpha) to the limit before embedding; JPEG is never re-encoded and only warns.
+- Page labels: `page_labels 1 => { style: :roman_lower }, 4 => { style: :decimal }, 12 => { style: :alpha, prefix: "Appendix " }` (or `to_pdf(page_labels:)`) writes the `/PageLabels` number tree; `Inspector#page_labels`, `have_page_labels` and `assert_page_labels` read it back.
+- `text(…, markup: true)` decodes HTML character references (`&amp;`, `&#39;`, `&#x27;`, the named entities the HTML parser knows), so data escaped with `html_escape` before adding your own `<b>` tags renders as intended instead of showing `&#39;`.
+
 ## 0.6.0 (2026-09-28)
 
 Instrumentation, so a render shows up in AppSignal and friends, and a faster text pipeline.

data/README.md

@@ -70,7 +70,8 @@ InvoicePdf.new(invoice).to_pdf          # => "%PDF-1.7…" (binary String)
 InvoicePdf.new(invoice).to_pdf("a.pdf") # also writes a path or an IO
 ```
 
-`examples/` has a complete, runnable invoice, annual report, letter, packing slip, fillable form and postcard collage; `bundle exec rake examples`
+`examples/` has a complete, runnable invoice, annual report, letter, packing slip, fillable form, postcard collage, event flyer and Factur-X e-invoice
+([previews and live PDFs](https://stationery.zoolutions.llc/docs/examples)); `bundle exec rake examples`
 renders them all, or render one with `stationery render examples/report.rb`.
 
 ## Elements
@@ -78,13 +79,13 @@ renders them all, or render one with `stationery render examples/report.rb`.
 | Element | What it does |
 |---|---|
 | `text(string, **style)` | A paragraph. Plain strings are literal. |
-| `text(string, markup: true)` | Reads `<b> <i> <u> <strikethrough> <sub> <sup> <br> <color rgb=""> <font size="" name=""> <link href="">`; decodes numeric and HTML 4 named entities. |
+| `text(string, markup: true)` | Reads `<b> <i> <u> <strikethrough> <sub> <sup> <br> <color rgb=""> <font size="" name=""> <link href="">`; decodes numeric (`&#39;`, `&#x27;`) and HTML 4 named entities once, so escape user data (`ERB::Util.html_escape`) before wrapping it in your own tags: `&lt;b&gt;` stays literal text. |
 | `text { b "Total"; plain " due" }` | Styled runs in Ruby. Take a block argument (`{ \|t\| t.b @x }`) to keep your own `self`. |
 | `box(padding:, background:, border:, radius:, width:, height:, min_height:, overflow:, at:, link:, outset:, break_inside:, decoration:, rotate:, shadow:) { }` | A container. Moves to the next page whole when it fits there and continues across pages when it does not; `break_inside: :auto` splits it at any page break, `:avoid` never splits it. At a cut, `decoration: :slice` (default) drops the padding and border, `:clone` keeps the padding. `overflow: :truncate` or `:shrink_to_fit` for fixed heights; a fixed `height:` never splits. `min_height:` is a floor that still splits: the first fragment keeps as much of it as the page holds, the next carries the rest (not combinable with `height:`). `at: [x, y]` pins it to a page position. `link:` makes the whole box clickable. `outset:` bleeds the background past the box (e.g. into the page margins). `rotate: -3` turns the painted box around its centre (layout box unchanged, never splits; a `link:` keeps its unrotated rectangle). `shadow: true` or `{ offset: [0, 4], blur: 8, color:, opacity: 0.15 }` paints a soft drop shadow under it, taking no space. `overflow: :hidden` clips the content to the rounded outline. |
 | `row(gap:, align:, break_inside:) { column(width:) { } }` | Columns side by side. `width:` is points, a fraction (`0.5`), `:auto` or `nil` (equal share). Splits across pages like a box, every column at once; a row with a fixed-height column never splits; columns with `min_height:` do. |
 | `table(rows, widths:, width:, header:, split_rows:, cell:) { \|t\| }` | Tables. Cells are strings, layout nodes, procs built with the DSL (`-> { image logo }`) or components. Style with `t.row(0)`, `t.rows(-1)`, `t.column(1)`, `t.columns(1..)`, chained, plus `t.zebra`. Header rows repeat after a page break. A cell may be `{ content:, colspan:, rowspan: }` plus any cell option; rows list only the cells they start, as in HTML, and pages never break through a rowspan. Spans are set in the rows, not through selections. A row taller than the page continues on the next page, cut through its cells, with the header repeated; `split_rows: true` cuts any row that reaches the page bottom instead of moving it whole. |
-| `image(path_or_io, width:, height:, fit:, align:, radius:, rotate:)` | JPEG or PNG, aspect preserved. `fit: [w, h]` scales to fit inside; `fit: :cover` fills `width:` × `height:` and crops around the centre. `radius:` rounds the corners; `rotate:` turns it (degrees, clockwise) without changing the space it takes. |
-| `svg(source_or_path, width:, height:, color:, align:)` | Vector icons and drawings; `currentColor` takes `color:`. Linear and radial gradients (`fill="url(#id)"`, `href` chains, both gradient units); `text`/`tspan` in the document's fonts; `<style>` stylesheets (element, class, id and `*` selectors). |
+| `image(path_or_io, width:, height:, fit:, align:, radius:, rotate:, max_ppi:, downscale:)` | JPEG or PNG, aspect preserved. `fit: [w, h]` scales to fit inside; `fit: :cover` fills `width:` × `height:` and crops around the centre. `radius:` rounds the corners; `rotate:` turns it (degrees, clockwise) without changing the space it takes. Drawn at more than twice `max_ppi:` (300) it is reported as oversized; `downscale: true` resamples a PNG to that resolution instead. |
+| `svg(source_or_path, width:, height:, color:, align:)` | Vector icons and drawings; `currentColor` takes `color:` (or the `color` an element sets). Linear and radial gradients (`fill="url(#id)"`, `href` chains, both gradient units); `text`/`tspan` in the document's fonts; `<style>` stylesheets (element, class, id and `*` selectors); `use`, `symbol` sprites and nested `svg` viewports (`viewBox`, `preserveAspectRatio`); `clipPath` (both `clipPathUnits`). |
 | `wrap(gap:, row_gap:, align:) { }` | Children side by side at their own widths, wrapping onto new rows (chips, tags). |
 | `stack(gap:, align:) { }` | A base with layers painted over it: ordinary children set the height, `layer` children float over them and take no space. Moves to the next page whole. |
 | `layer(top:, right:, bottom:, left:, width:, height:, **box) { }` | Inside `stack`: a box placed by insets from the stack's edges, in points or as a fraction (`0.4`, `1/3r`) of its width/height; negative insets overhang. Takes every box option (`rotate:`, `shadow:`, `radius:`, …). |
@@ -105,7 +106,7 @@ renders them all, or render one with `stationery render examples/report.rb`.
 | `markdown(source, styles:, gap:, images:, base_path:, bookmarks:, links:)` | The same from CommonMark (plus GFM tables and strikethrough). |
 
 Text style options: `font`, `size`, `weight` (`:regular`, `:bold`), `style` (`:italic`), `color`,
-`letter_spacing`, `underline`, `strikethrough`, `link`, `opacity`, `kerning` (default `true`), `ligatures` (default `true`), `align` (`:left`, `:center`, `:right`, `:justify`), `leading`.
+`letter_spacing`, `underline`, `strikethrough`, `link`, `opacity`, `kerning` (default `true`), `ligatures` (default `true`), `features` (OpenType feature tags, e.g. `%i[smcp onum]`), `hyphenate` (`true` for English, or `"de"`, `"sv"`; default off), `align` (`:left`, `:center`, `:right`, `:justify`), `leading`.
 `align: :justify` stretches the spaces of wrapped lines to the full width; the last line, lines
 ending in a newline and lines without spaces stay left-aligned (tabs are never stretched).
 Colours are `"#RRGGBB"`, `"RRGGBB"`, `"#RGB"`, `[r, g, b]` (0-255) or `[c, m, y, k]` (0-100).
@@ -259,6 +260,10 @@ render Callout.new(color: "#F3F4F6") { text "Amount due" }
   fits a normal page but not the last one continues onto an extra page.
 - With a header or footer, a `page_template`'s `page.content_box` excludes their space (it is the
   body's area).
+- `page_labels 1 => { style: :roman_lower }, 3 => { style: :decimal, start: 1, prefix: "A-" }` names
+  the pages the way viewers show them ("i", "ii", "A-1", …): a 1-based first page mapped to the range
+  that starts there, with `style:` `:decimal`, `:roman`, `:roman_lower`, `:alpha`, `:alpha_lower` or
+  `nil` (prefix only), `start:` and `prefix:`. `to_pdf(page_labels:)` overrides it for one render.
 - Content taller than a page is placed anyway; `document.warnings` lists every overflow.
 - After `to_pdf`, `document.warnings` is an Enumerable of everything the render noticed but did not
   raise on, each with a `#message`: overflows, SVG elements that were skipped (`UnsupportedSvg`), and
@@ -289,6 +294,27 @@ InvoicePdf.new(invoice).to_pdf(encrypt: nil) # plain
   `:aes_128` for older viewers; `:rc4_128` only for legacy readers that need it.
 - Every string and stream is encrypted, the document info included.
 
+### Embedded files
+
+```ruby
+class InvoicePdf < Stationery::Document
+  attach_file "factur-x.xml", invoice_xml, mime: "text/xml", description: "Factur-X",
+              relationship: :alternative # every render
+end
+
+InvoicePdf.new(invoice).to_pdf(attachments: [{ name: "terms.pdf", data: terms, mime: "application/pdf" }])
+```
+
+- Each file becomes a `/Filespec` with an `/EmbeddedFile` stream (`/Subtype` from `mime:`, `/Params`
+  with size, MD5 checksum and `modified_at:`), listed in the catalog's `/EmbeddedFiles` name tree
+  and its `/AF` array; `description:` is the `/Desc` viewers show.
+- `relationship:` writes `/AFRelationship`: `:alternative` (a machine-readable twin, as Factur-X
+  and ZUGFeRD require), `:source`, `:data`, `:supplement` or `:unspecified` (default).
+- Per-render `attachments:` are added to the class-level ones; the same name twice raises
+  `ArgumentError`. An encrypted document encrypts the embedded streams too.
+- For an e-invoice, [`factur_x`](#factur-x--zugferd-e-invoices) embeds the XML, claims PDF/A-3b
+  and writes the identification in one line.
+
 ### Accessibility (tagged PDF)
 
 ```ruby
@@ -326,6 +352,10 @@ and across page breaks: a paragraph continued on the next page stays one `P`.
 - Headers, footers and page templates are pagination artifacts; backgrounds, borders and rules drawn
   outside any element are layout artifacts.
 - `metadata lang:` writes the catalog's `/Lang`; the title is shown instead of the file name.
+- Every document carries an XMP packet (`/Metadata`, uncompressed) mirroring the Info dictionary:
+  `dc:title`, `dc:creator`, `dc:description`, `dc:subject`, `dc:language`, the `xmp:` dates and
+  `pdf:Producer`. PDF/A and PDF/UA identification lives there (see
+  [PDF/A and PDF/UA](#pdfa-and-pdfua)); `metadata xmp: false` or `to_pdf(xmp: false)` leaves it out.
 - An image or drawing without `alt:` (`Warnings::MissingAlt`) and a missing `lang`
   (`Warnings::MissingLanguage`) are warnings, so `strict` catches them.
 - Untagged documents (the default) are written exactly as before.
@@ -340,8 +370,94 @@ expect(ReportPdf.new).to have_structure(
 )
 ```
 
-The PDF is not labelled PDF/UA (no XMP `pdfuaid` metadata), and nothing checks colour contrast or
-reading order you build out of positioned boxes (`box(at:)` joins the reading order where it paints).
+`tagged` alone does not label the file; `conformance :pdf_ua1` does (see
+[PDF/A and PDF/UA](#pdfa-and-pdfua)). Nothing checks colour contrast or the reading order you build
+out of positioned boxes (`box(at:)` joins the reading order where it paints).
+
+### PDF/A and PDF/UA
+
+```ruby
+class InvoicePdf < Stationery::Document
+  conformance :pdf_a3b            # archival: :pdf_a2b or :pdf_a3b
+end
+
+class ReportPdf < Stationery::Document
+  conformance :pdf_a3b, :pdf_ua1  # archival and accessible
+  metadata title: "Annual report 2026", lang: "en"
+end
+
+InvoicePdf.new(invoice).to_pdf(conformance: nil) # one render without the claim, or with another
+```
+
+A level is only claimed when the file keeps it, so what cannot conform raises instead of being
+mislabelled: `ArgumentError` for options that contradict the level, `Stationery::ConformanceError`
+(`levels`, `issues`) for content.
+
+- **PDF/A-2b and PDF/A-3b** (ISO 19005, level B: the look is reproducible): an sRGB
+  `OutputIntent` with the embedded ICC profile (the ICC's `sRGB2014.icc`), `pdfaid:part` and
+  `pdfaid:conformance` in the XMP packet (written even with `xmp: false`), the print flag on every
+  annotation. Fonts are always embedded and subsetted, and transparency is allowed from part 2 on.
+  `encrypt:` raises. Embedded files need `:pdf_a3b` (part 2 only embeds PDF/A files, so
+  `attach_file` raises there). CMYK colours and CMYK JPEGs are not covered by the sRGB intent and
+  are reported as `Warnings::ConformanceIssue`, so `strict` refuses them.
+- **PDF/UA-1** (ISO 14289): turns `tagged` on, needs `metadata title:` and `lang:`, writes
+  `pdfuaid:part`, shows the title in the viewer, orders tabs by structure (`/Tabs /S`) and gives
+  every link annotation a description (`/Contents`: the URL, or the target page). A figure without
+  `alt:` raises; mark decoration with `alt: false`. Encryption is allowed.
+- Combined, the XMP packet also describes the `pdfuaid` schema to PDF/A (`pdfaExtension:schemas`).
+- Interactive form fields raise under every level: their appearances draw with the standard
+  Helvetica and ZapfDingbats, which are not embedded.
+- Without `conformance` nothing changes: the output is byte for byte what it was.
+
+`bundle exec rake verify:conformance` renders `examples/invoice.rb` as PDF/A-3b and
+`examples/report.rb` as PDF/A-3b plus PDF/UA-1 and validates them with
+[veraPDF](https://verapdf.org) through Docker (`verapdf/cli`); CI runs it on every push. Validate
+your own documents the same way:
+
+```sh
+docker run --rm -v "$PWD:/data:ro" verapdf/cli --format text -v --flavour 3b /data/invoice.pdf
+```
+
+In tests, `have_conformance(:pdf_a3b)` checks the claim (not the validity: that is veraPDF's job).
+
+### Factur-X / ZUGFeRD e-invoices
+
+A Factur-X (in Germany: ZUGFeRD) invoice is one PDF that people read and accounting software
+books: a PDF/A-3b file with the invoice as Cross Industry Invoice XML embedded in it.
+
+```ruby
+class InvoicePdf < Stationery::Document
+  metadata title: "Invoice", lang: "en"
+  factur_x(profile: :en16931) { @invoice.to_cii_xml } # evaluated in the document, per render
+  # factur_x :invoice_xml                             # or a method name
+  # factur_x File.read("factur-x.xml")                # or the XML itself
+
+  def initialize(invoice) = (super(); @invoice = invoice)
+end
+
+InvoicePdf.new(invoice).to_pdf(factur_x: { xml:, profile: :extended }) # per render; nil for none
+```
+
+- `factur_x` claims `conformance :pdf_a3b` (added to declared levels such as `:pdf_ua1`;
+  `:pdf_a2b` raises), embeds the XML as `factur-x.xml` (`text/xml`, described as "Factur-X
+  Invoice", stamped with its modification date) and writes the `fx:` identification in XMP
+  (`DocumentType INVOICE`, `DocumentFileName`, `Version`, `ConformanceLevel`) with the extension
+  schema description PDF/A asks for.
+- `profile:` is `:minimum`, `:basic_wl`, `:basic`, `:en16931` (default), `:extended` or
+  `:xrechnung` (embedded as `xrechnung.xml`). The XML is the page's `:alternative`, except for
+  `:minimum` and `:basic_wl`, whose XML is `:data` beside it. `filename:`, `version:` ("1.0")
+  and `relationship:` override the defaults (ZUGFeRD 1.0 used `ZUGFeRD-invoice.xml`).
+- Stationery carries the XML, it does not write or validate it: anything that does not start
+  with `<?xml` or `<rsm:CrossIndustryInvoice` raises `ArgumentError`, and what is inside is your
+  invoicing code's. `examples/e_invoice.rb` builds a minimal EN 16931 document from the example
+  invoice's lines.
+- Everything PDF/A-3b asks applies: no `encrypt:`, no form fields.
+- Without `factur_x` nothing changes.
+
+`bundle exec rake verify:factur_x` validates `examples/e_invoice.rb` with the
+[Mustang](https://www.mustangproject.org) validator through Docker: the PDF/A-3 container and the
+XML against the EN 16931 schema and business rules. CI runs it with `verify:conformance`. In
+tests, `have_factur_x(profile: :en16931)` checks that the invoice is named in XMP and embedded.
 
 ### Debugging
 
@@ -521,16 +637,48 @@ line is never wider than the same line unkerned.
 
 Standard ligatures (fi, fl, ffi, …) come from the font's GSUB `liga` feature
 (LigatureSubst lookups, also behind Extension lookups) and are on by default;
-`ligatures: false` on an element or in `default_text` turns them off. Only
-`liga` applies, not `clig` or `dlig`. Ligatures form within a run of one
-style and font, never across a line break, and letter spacing turns them off.
-The PDF's ToUnicode map sends a ligature glyph back to all of its
-characters, so copied and extracted text still reads "office". Fonts
-without a `liga` feature (such as the bundled Inter) are unaffected.
+`ligatures: false` on an element or in `default_text` turns them off.
+Ligatures form within a run of one style and font, never across a line
+break, and letter spacing turns them off. The PDF's ToUnicode map sends a
+ligature glyph back to all of its characters, so copied and extracted text
+still reads "office". Fonts without a `liga` feature (such as the bundled
+Inter) are unaffected.
+
+Other OpenType features are opt-in per element, `text_style` or
+`default_text`: `features: %i[smcp onum]` applies the font's small caps and
+oldstyle figures, `tnum`/`pnum` pick tabular or proportional figures for
+tables, `zero` a slashed zero, `dlig` discretionary ligatures, `ss01`… the
+stylistic sets. Single (SingleSubst) and ligature (LigatureSubst) lookups
+are applied in the font's own order; a feature the font lacks is ignored,
+and `Font#features` lists what a font offers. Substituted glyphs keep
+their source characters in ToUnicode, so "2026" in oldstyle figures still
+extracts as "2026". Contextual features (`calt`, `clig`, `frac`) need
+lookup types the reader does not implement and do nothing.
+
+Hyphenation is off unless asked for: `hyphenate: "de"` on `text`, `text_style`,
+`default_text` or an `html`/`markdown` style (`styles: { p: { hyphenate: "de" } }`)
+breaks a word that does not fit at the longest point Liang's algorithm allows
+over the bundled TeX patterns (`true` or `"en"` for American English, `"de"`
+for German, `"sv"` for Swedish; `lib/stationery/hyphenation/patterns/LICENSES.md`
+names their authors and licences), drawing a hyphen at the break. A soft hyphen
+(U+00AD, `&shy;` in HTML) names the break points of a word yourself and, as in
+TeX, exempts that word from the patterns; it is never measured or drawn and
+never reaches the PDF. `Stationery::Hyphenation.hyphenate("Silbentrennung", "de")`
+answers `["Sil", "ben", "tren", "nung"]` for your own use.
 
 Images are JPEG (grey, RGB, CMYK) and PNG (every colour type, alpha as a soft
 mask). Parsed fonts and images are cached per process.
 
+A bitmap keeps its pixels, so a 1600 px photo drawn 160 pt wide ships all
+1600 px at 720 ppi. An image drawn at more than twice the document's
+`max_ppi` (300, or `images max_ppi: 220` at class level, `nil` to switch the
+check off) is reported as a `Warnings::OversizedImage` naming the file, its
+pixel width and the resolution it lands at. `images downscale: true` (or
+`image(..., downscale: true)`) resamples a PNG to `max_ppi` at its drawn size
+before embedding it, alpha included; a JPEG is embedded byte for byte, so
+resize it before you embed it (an ActiveStorage variant per drawn size,
+preprocessed, keeps a render to a download).
+
 ## Testing
 
 `stationery/rspec` and `stationery/minitest` read a rendered PDF back for
@@ -560,6 +708,10 @@ RSpec.describe InvoicePdf do
   it { is_expected.to have_image_count(1) }
   it { is_expected.to have_no_warnings }
   it { is_expected.to have_pdf_language("en") } # the catalog /Lang from `metadata lang:`
+  it { is_expected.to have_page_labels(%w[i ii 1 2]) } # from `page_labels`
+  it { is_expected.to have_attachment("factur-x.xml", mime: "text/xml", relationship: :alternative) }
+  it { is_expected.to have_conformance(:pdf_a3b) } # the level claimed in XMP, from `conformance`
+  it { is_expected.to have_factur_x(profile: :en16931) } # the e-invoice XML, named in XMP and embedded
   it { is_expected.to have_tagged_content } # a tagged PDF with every text tagged or an artifact
   it { is_expected.to have_structure([[:Document, [[:H1, "Invoice"], [:P, "INV-7"]]]]) }
 end
@@ -581,6 +733,10 @@ class InvoicePdfTest < Minitest::Test
     assert_pdf_link pdf, /acme\.test/
     assert_no_pdf_warnings pdf
     assert_pdf_language pdf, "en"
+    assert_page_labels pdf, %w[i ii 1 2]
+    assert_pdf_attachment pdf, "factur-x.xml", mime: "text/xml"
+    assert_pdf_conformance pdf, :pdf_a3b
+    assert_factur_x pdf, profile: :en16931
     assert_tagged_content pdf
     assert_pdf_structure pdf, [[:Document, [[:H1, "Invoice"], [:P, "INV-7"]]]]
   end
@@ -592,7 +748,10 @@ The matcher names carry a `pdf_` prefix so they never clash with Capybara's
 titles. The RSpec matchers compose like the built-ins: `.and` / `.or`, and inside
 `all`, `include` or `match`. For anything else, `Stationery::Testing::Inspector.new(subject)`
 exposes `text`, `page_texts`, `page_count`, `links`, `internal_links`,
-`image_count`, `bookmarks`, `metadata`, `lang`, `warnings`, `tagged?`, `untagged_text` and
+`image_count`, `bookmarks`, `metadata`, `xmp` (the packet), `xmp_values` (`{ "dc:title" => …, "dc:creator" => […] }`),
+`lang`, `page_labels`, `attachments`, `conformance` (`[:pdf_a3b, :pdf_ua1]`), `factur_x`
+(`{ profile:, filename:, version:, xml: }`), `warnings`, `tagged?`,
+`untagged_text` and
 `structure` — a tagged PDF's structure tree as nested arrays, each element's text
 read from its marked content: `[type, "text"]`, `[type, [children]]` (its own text
 between the children, as for a `P` holding a `Link`) or `[type]` when empty; a
@@ -661,10 +820,31 @@ larger file. `PROFILE=1 bundle exec ruby -Ilib benchmark/profile.rb` prints the
 
 ## Limitations
 
-No variable fonts (including CFF2) or
-WOFF2 (it needs Brotli; convert to `.ttf` or `.woff`); SVG covers the shapes icon sets use
-(no patterns or masks). A box with a fixed `height:` never splits (use
-`min_height:` for a floor that can); a row splits only when every column can.
+Fonts: no variable fonts (including CFF2) and no WOFF2 (it needs Brotli; convert to `.ttf` or
+`.woff`); shaping stops at pair kerning and single or ligature substitutions (`liga` by default,
+`smcp`, `onum`, `tnum`, `ss01`… on request), so contextual alternates (`calt`, `clig`, `frac`) do
+nothing and scripts that need contextual shaping (Arabic, Indic, Thai) draw glyph by glyph, and colour or emoji glyphs no font
+in the chain has are drawn as `.notdef` and reported. Text runs left to right; hyphenation
+patterns are bundled for English, German and Swedish only (a soft hyphen works in any language),
+and justification only widens spaces.
+
+SVG covers the shapes, gradients, text, stylesheets, `use`/`symbol` sprites and clip paths that icon
+sets and exports use, nothing else: `image`, `mask`, `pattern`, `filter` and `textPath` are skipped
+and reported, text inside a `clipPath` does not clip, and the shapes of a clip path join into one
+path, so overlapping shapes wound in opposite directions cancel where they overlap.
+Images are JPEG and PNG (non-interlaced) and never fetched from a URL; a JPEG is embedded at its
+source resolution (only PNGs can be downscaled), so an oversized one is reported, not resized. `html` and `markdown` render structure and inline marks, not CSS: only `text-align`
+and inline `font-weight`/`font-style` are read, and raw HTML inside Markdown stays literal text.
+
+Layout: a box with a fixed `height:` never splits (use `min_height:` for a floor that can); a row
+splits only when every column can; a rotated box and a `stack` move to the next page whole. Text
+does not wrap around images. Link and form-widget rectangles stay in page space inside `rotate`
+and `transform`, and `shadow:` is stacked rectangles, not a blur.
+
+PDF: PDF/A-2b, PDF/A-3b and PDF/UA-1 only (no PDF/A-1, no level A or U, no PDF/UA-2, no PDF/X); no
+digital signing (`signature_field` is an empty field) and no JavaScript.
+Form-field appearances use Helvetica (Windows-1252), not the document's fonts, which also keeps
+forms out of PDF/A and PDF/UA documents.
 
 ## License
 

data/lib/stationery/builder.rb

@@ -5,7 +5,7 @@ module Stationery
   # (where the next node goes) and the text defaults in effect.
   class Builder
     STYLE_KEYS = %i[size color weight style letter_spacing underline strikethrough link opacity kerning
-                    ligatures].freeze
+                    ligatures features hyphenate].freeze
 
     # Collects a row's columns; anything that is not already a column box is
     # wrapped in one.
@@ -32,10 +32,12 @@ module Stationery
       end
     end
 
-    attr_reader :root, :book, :list_depth
+    # `images` are the document's bitmap defaults (max_ppi:, downscale:).
+    attr_reader :root, :book, :list_depth, :images
 
-    def initialize(book:, text: {})
+    def initialize(book:, text: {}, images: {})
       @book = book
+      @images = images
       @root = Layout::Flow.new
       @containers = [@root]
       @text = [text]

data/lib/stationery/canvas/text.rb

@@ -8,14 +8,15 @@ module Stationery
 
       # Draws `string` with its baseline at (x, y) in top-left coordinates and
       # returns its advance width. Standard ligatures form unless `ligatures:`
-      # is false or letter spacing is set.
+      # is false or letter spacing is set; `features:` are further OpenType
+      # feature tags (Strings) to apply.
       def text(string, x:, y:, font:, size:, color: "#000000", letter_spacing: 0, rise: 0, opacity: nil,
                synthetic_bold: false, synthetic_oblique: false, underline: false, strikethrough: false,
-               kerning: false, ligatures: true, word_spacing: 0)
+               kerning: false, ligatures: true, features: Fonts::Font::NO_FEATURES, word_spacing: 0)
         return 0 if string.empty?
 
         color = Color.parse(color)
-        run = font.glyph_run(string, kerning:, ligatures: ligatures && letter_spacing.zero?)
+        run = font.glyph_run(string, kerning:, ligatures: ligatures && letter_spacing.zero?, features:)
         run = run.with_word_spacing(word_spacing, size) unless word_spacing.zero?
         width = run.width(size, letter_spacing:)
         graphics(opacity:) do |ops|

data/lib/stationery/canvas.rb

@@ -12,16 +12,19 @@ module Stationery
     CAPS = { butt: 0, round: 1, square: 2 }.freeze
     JOINS = { miter: 0, round: 1, bevel: 2 }.freeze
 
-    attr_reader :page
+    # `warnings` is the render's collector (nil on a bare canvas), for what a
+    # node notices only while painting, such as an oversized image.
+    attr_reader :page, :warnings
 
     # `template: true` records anchors apart, for canvases page templates draw on.
     # `tagging:` (a Tagging::Tree) marks content for a tagged PDF.
-    def initialize(page, resources, template: false, debug: false, tagging: nil)
+    def initialize(page, resources, template: false, debug: false, tagging: nil, warnings: nil)
       @page = page
       @resources = resources
       @template = template
       @debug = debug
       @tagging = tagging
+      @warnings = warnings
       @marked = 0
     end
 
@@ -64,6 +67,25 @@ module Stationery
       end
     end
 
+    # A path the block traces in top-left space, under `transform` when given,
+    # for #clip_to.
+    def outline(transform: nil, &)
+      Path.new(self, transform:).tap(&)
+    end
+
+    # Paints the block inside `outlines` (see #outline), joined into one
+    # clipping path under the nonzero rule or, with `even_odd:`, the even-odd
+    # one. Without a path to clip to, nothing is inside and the block is skipped.
+    def clip_to(outlines, even_odd: false)
+      paths = outlines.map(&:to_s).reject(&:empty?)
+      return if paths.empty?
+
+      save do
+        emit(*paths, even_odd ? "W* n" : "W n")
+        yield self
+      end
+    end
+
     def fill_rect(x, y, w, h, color:, opacity: nil)
       shape(fill: color, opacity:) { |p| p.rect(x, y, w, h) }
     end

data/lib/stationery/cli/render.rb

@@ -57,19 +57,19 @@ module Stationery
         OK
       end
 
-      # Documents that are new after loading FILE or whose view_template lives
-      # in it (so a file already loaded by the host still resolves).
+      # Documents that are new after loading FILE or that it defines (so a
+      # file already loaded by the host still resolves).
       def load_documents(path)
         before = descendants(Document)
         load(path)
         after = descendants(Document)
-        (after - before) | after.select { |klass| template_file(klass) == path }
+        (after - before) | after.select { |klass| defined_in?(klass, path) }
       end
 
       def pick(candidates, path)
         return named_class if @options[:class]
 
-        candidates = candidates.reject { |klass| template_file(klass).nil? }
+        candidates = local(candidates.reject { |klass| template_file(klass).nil? }, path)
         raise Error, "no Stationery::Document defined in #{path}" if candidates.empty?
         return candidates.first if candidates.one?
 
@@ -77,6 +77,21 @@ module Stationery
         raise Error, "several documents defined in #{path} (#{names}); choose one with --class NAME"
       end
 
+      # The documents FILE itself defines, when it also loaded others (a
+      # document extending one from a file it requires).
+      def local(candidates, path)
+        defined_here = candidates.select { |klass| defined_in?(klass, path) }
+        defined_here.any? ? defined_here : candidates
+      end
+
+      # Whether FILE opens the class or holds its own view_template.
+      def defined_in?(klass, path)
+        method = klass.instance_method(:view_template)
+        return true if method.owner == klass && method.source_location&.first == path
+
+        !klass.name.nil? && Object.const_source_location(klass.name)&.first == path
+      end
+
       def named_class
         klass = Object.const_get(@options[:class])
         raise Error, "#{klass} is not a Stationery::Document" unless klass.is_a?(Class) && klass < Document

data/lib/stationery/document.rb

@@ -24,7 +24,7 @@ module Stationery
                       superclass.config.transform_values(&:dup)
                     else
                       { page: { size: :letter, margin: 36 }, families: {}, fallbacks: [], text: {}, metadata: {},
-                        templates: [], regions: [], strict: false, tagged: false }
+                        templates: [], regions: [], strict: false, tagged: false, images: {}, attachments: [] }
                     end
       end
 
@@ -50,6 +50,29 @@ module Stationery
         config[:metadata] = config[:metadata].merge(info)
       end
 
+      # How viewers name the pages: a 1-based first page mapped to the range
+      # starting there, `page_labels 1 => { style: :roman_lower }, 3 =>
+      # { style: :decimal, start: 1, prefix: "A-" }`; see PDF::PageLabels.
+      def page_labels(spec)
+        PDF::PageLabels.entries(spec)
+        config[:page_labels] = spec
+      end
+
+      # Embeds a file in every render: `attach_file "invoice.xml", xml,
+      # mime: "text/xml", description: "Factur-X", relationship: :alternative`.
+      # `relationship:` is :alternative, :source, :data, :supplement or
+      # :unspecified (the /AFRelationship); `modified_at:` a Time.
+      def attach_file(name, data, **)
+        config[:attachments] << PDF::Attachments.build(name, data, **)
+      end
+
+      # Bitmap defaults: `max_ppi:` (300; nil disables) is the resolution
+      # above twice of which a drawn image is reported as oversized, and
+      # `downscale: true` resamples PNGs to it. See Layout::Image.
+      def images(**options)
+        config[:images] = config[:images].merge(options)
+      end
+
       # Raise WarningsError instead of writing a PDF that produced warnings.
       def strict(value = true) # rubocop:disable Style/OptionalBooleanParameter
         config[:strict] = value
@@ -62,6 +85,28 @@ module Stationery
         config[:tagged] = value
       end
 
+      # Claims PDF/A-2b, PDF/A-3b and/or PDF/UA-1 (`conformance :pdf_a3b,
+      # :pdf_ua1`) and writes what the level asks for; a render that cannot
+      # keep the claim raises. See PDF::Conformance.
+      def conformance(*levels)
+        PDF::Conformance.for(levels)
+        config[:conformance] = levels.flatten
+      end
+
+      # Makes every render a Factur-X / ZUGFeRD e-invoice: PDF/A-3b with the
+      # invoice XML embedded and identified in XMP. `xml` is the Cross
+      # Industry Invoice as a String, or a method name or block answering it
+      # for the document being rendered: `factur_x(profile: :en16931) {
+      # invoice.to_cii }`. See PDF::FacturX for profiles and options.
+      def factur_x(xml = nil, **options, &block)
+        source = xml || block
+        raise ArgumentError, "factur_x needs the invoice XML, a method name or a block" unless source
+
+        PDF::FacturX.profile(options.fetch(:profile, :en16931))
+        PDF::FacturX.new(source, **options) if source.is_a?(String)
+        config[:factur_x] = { xml: source, **options }
+      end
+
       # Encrypts every render with the standard security handler; see
       # PDF::Encryption::StandardSecurity for the options.
       def encrypt(**)
@@ -94,9 +139,17 @@ module Stationery
     def metadata = self.class.config[:metadata]
 
     def to_pdf(target = nil, strict: self.class.config[:strict], debug: false, encrypt: self.class.config[:encrypt],
-               tagged: self.class.config[:tagged])
+               tagged: self.class.config[:tagged], page_labels: self.class.config[:page_labels], attachments: [],
+               xmp: metadata[:xmp] != false, conformance: self.class.config[:conformance],
+               factur_x: self.class.config[:factur_x])
+      invoice = PDF::FacturX.for(factur_x, self)
+      attachments = PDF::Attachments.merge(self.class.config[:attachments], attachments, invoice&.attachment)
+      conformance = PDF::Conformance.for(invoice ? invoice.conformance(conformance) : conformance)
+      conformance&.validate!(encrypt:, metadata:, attachments:)
+      options = { strict:, debug:, encrypt:, tagged: tagged || conformance&.pdf_ua?, page_labels:, attachments:,
+                  xmp: xmp || !conformance.nil?, conformance:, invoice: }
       Stationery.instrument("render.stationery", document: self.class.name) do |event|
-        write(render_pdf(event, strict:, debug:, encrypt:, tagged:), target)
+        write(render_pdf(event, **options), target)
       end
     end
 
@@ -111,37 +164,45 @@ module Stationery
 
     # Builds a page template or region block into a fresh root node.
     def template_root(info, book:, &)
-      builder = Builder.new(book:, text: self.class.config[:text])
+      builder = builder_for(book)
       build_with(builder) { instance_exec(info, &) }
       builder.root
     end
 
     private
 
+    def builder_for(book) = Builder.new(book:, text: self.class.config[:text], images: self.class.config[:images])
+
     # The PDF bytes; `event` is the render.stationery payload it fills in.
-    def render_pdf(event, strict:, debug:, encrypt:, tagged:)
+    def render_pdf(event, strict:, debug:, tagged:, conformance:, **assembly)
       tagging = Tagging::Tree.new if tagged
       warnings = Warnings.new
       book = Fonts::FontBook.new(self.class.config[:families], fallbacks: self.class.config[:fallbacks], warnings:)
-      builder = Builder.new(book:, text: self.class.config[:text])
+      builder = builder_for(book)
       Stationery.instrument("build.stationery", document: self.class.name) { call(builder) }
       resources = Resources.new
       pages = paginate(builder.root, book:, resources:, warnings:, debug:, tagging:)
       outline = builder.outline.resolve(Structure.resolve(pages, warnings:, resources:, book:, tagging:))
       tagging&.audit(pages, warnings, lang: metadata[:lang])
       @warnings = warnings
+      conformance&.audit!(pages, resources:, warnings:)
       @fields = Forms::AcroForm.values(pages)
       event[:pages] = pages.size
       event[:warnings] = warnings.size
       raise WarningsError, warnings if strict && warnings.any?
 
-      assemble(pages, resources, outline, encrypt:, tagging:).tap { |pdf| event[:bytes] = pdf.bytesize }
+      pdf = assemble(pages, resources, outline, tagging:, conformance:, **assembly)
+      event[:bytes] = pdf.bytesize
+      pdf
     end
 
-    def assemble(pages, resources, outline, encrypt:, tagging:)
+    def assemble(pages, resources, outline, encrypt:, tagging:, page_labels:, attachments:, xmp:, conformance:,
+                 invoice:)
       encryption = encrypt && PDF::Encryption::StandardSecurity.new(**encrypt)
-      assembler = PDF::Assembler.new(pages:, resources:, info:, outline:, encryption:, tagging:,
-                                     lang: metadata[:lang])
+      assembler = PDF::Assembler.new(pages:, resources:, info:, outline:, encryption:, tagging:, xmp:,
+                                     lang: metadata[:lang], page_labels: PDF::PageLabels.entries(page_labels),
+                                     attachments:, conformance:, xmp_extensions: invoice&.xmp_extensions || {},
+                                     xmp_schemas: [invoice&.xmp_schema].compact)
       Stationery.instrument("write.stationery", document: self.class.name) do |event|
         assembler.render.tap { |pdf| event[:bytes] = pdf.bytesize }
       end
@@ -167,7 +228,7 @@ module Stationery
     end
 
     def info
-      metadata.except(:lang).to_h do |key, value|
+      metadata.except(:lang, :xmp).to_h do |key, value|
         [INFO_KEYS.fetch(key.to_sym) { key.to_sym }, value.is_a?(Array) ? value.join(", ") : value]
       end
     end