stationery 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f9e83f23437589a026e0a9a2fde163a39a2c4151c434afc5bdbea38a98891dd
-  data.tar.gz: 67e42695ae205e05049441490b89b908f6468ba94e00c095c1de8eaeae986d65
+  metadata.gz: 21d52a1f02122474b5316373c70965424f3479973757219d2b7b87ed453e8642
+  data.tar.gz: eaa7be7242e9f38e270cb23a533bac9038963c3e61c44c1e57ebaefe0288ef29
 SHA512:
-  metadata.gz: 40756fe30e4c2d400fab7402e490609cf313e8ae06c5317489f6b0337f96fc5ad00d8f2c8b05b348812955b109cc0f9685f9c1668b8f307d1fd16ac9492facad
-  data.tar.gz: 1a7938f3b608b68df057d3385d5824dc6a57338978a76ad39bed42701838ee2a408db1c2d30daccf3a834b03bea9f6d1441ef6405691dff0090611d26cbe05a0
+  metadata.gz: 0dd292c0de3767e870563e954a9ea1b466beed56af675209d69baa09f7c44e337117a5b7256e41b4a35e39f694f0cfc721f2729cd1af8f7dc6081712a4263034
+  data.tar.gz: 73286d789a65a258a026fc65fe8bbc1287dfd2df6ee13d07177cac13beba4f0e7bbcbdfc4bbafc4b3643d762efeb6a3cfb9cb6ab019e6a14c1351a920bc998db

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # 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.

data/README.md

@@ -70,7 +70,7 @@ 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, postcard collage and event flyer
+`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`.
 
@@ -85,7 +85,7 @@ renders them all, or render one with `stationery render examples/report.rb`.
 | `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:, 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:`. 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). |
+| `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:`, …). |
@@ -294,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
@@ -331,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.
@@ -345,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
 
@@ -598,6 +709,9 @@ RSpec.describe InvoicePdf do
   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
@@ -620,6 +734,9 @@ class InvoicePdfTest < Minitest::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
@@ -631,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`, `page_labels`, `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
@@ -708,8 +828,10 @@ in the chain has are drawn as `.notdef` and reported. Text runs left to right; h
 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 and stylesheets icon sets use, nothing else: `use`,
-`image`, `clipPath`, `mask`, `pattern`, `filter` and `textPath` are skipped and reported.
+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.
@@ -719,9 +841,10 @@ splits only when every column can; a rotated box and a `stack` move to the next
 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: tagged output is not labelled PDF/UA (no XMP), and there is no PDF/A or PDF/X, no digital
-signing (`signature_field` is an empty field), no embedded files or JavaScript.
-Form-field appearances use Helvetica (Windows-1252), not the document's fonts.
+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/canvas.rb

@@ -67,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, images: {} }
+                        templates: [], regions: [], strict: false, tagged: false, images: {}, attachments: [] }
                     end
       end
 
@@ -58,6 +58,14 @@ module Stationery
         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.
@@ -77,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(**)
@@ -109,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], page_labels: self.class.config[:page_labels])
+               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:, page_labels:), target)
+        write(render_pdf(event, **options), target)
       end
     end
 
@@ -136,7 +174,7 @@ module Stationery
     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:, page_labels:)
+    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:)
@@ -147,18 +185,24 @@ module Stationery
       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:, page_labels:).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:, page_labels:)
+    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], page_labels: PDF::PageLabels.entries(page_labels))
+      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
@@ -184,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

data/lib/stationery/errors.rb

@@ -20,4 +20,17 @@ module Stationery
       super("#{lines.size} #{noun}:\n#{lines.join("\n")}")
     end
   end
+
+  # Raised when a render cannot keep the conformance it claims (PDF/A,
+  # PDF/UA): `levels` are the claimed levels, `issues` what breaks them.
+  class ConformanceError < Error
+    attr_reader :levels, :issues
+
+    def initialize(levels, issues)
+      @levels = levels
+      @issues = issues
+      super("not #{levels.map { |level| Stationery::PDF::Conformance.label(level) }.join(" + ")}:\n" \
+            "#{issues.map { |issue| "  #{issue}" }.join("\n")}")
+    end
+  end
 end

data/lib/stationery/images/jpeg.rb

@@ -21,9 +21,10 @@ module Stationery
       end
 
       def inspect = "#<#{self.class} #{@width}x#{@height}>"
+      def color_space = COLOR_SPACES.fetch(@components)
 
       def build(writer)
-        dictionary = Images.xobject(@width, @height, COLOR_SPACES.fetch(@components), @bits).merge(Filter: :DCTDecode)
+        dictionary = Images.xobject(@width, @height, color_space, @bits).merge(Filter: :DCTDecode)
         # Adobe CMYK JPEGs store inverted values.
         dictionary[:Decode] = [1, 0] * 4 if @components == 4 && @adobe
         writer.add(PDF::Stream.new(@data, dictionary))

data/lib/stationery/minitest.rb

@@ -22,6 +22,18 @@ module Stationery
         assert_pdf(Matchers::HavePageLabels.new(labels), subject, msg)
       end
 
+      def assert_pdf_attachment(subject, name, msg = nil, **)
+        assert_pdf(Matchers::HaveAttachment.new(name, **), subject, msg)
+      end
+
+      def assert_pdf_conformance(subject, levels, msg = nil)
+        assert_pdf(Matchers::HaveConformance.new(*levels), subject, msg)
+      end
+
+      def assert_factur_x(subject, msg = nil, profile: nil)
+        assert_pdf(Matchers::HaveFacturX.new(profile:), subject, msg)
+      end
+
       def assert_no_pdf_warnings(subject, msg = nil) = assert_pdf(Matchers::HaveNoWarnings.new, subject, msg)
       def assert_pdf_structure(subject, tree, msg = nil) = assert_pdf(Matchers::HaveStructure.new(tree), subject, msg)
       def assert_tagged_content(subject, msg = nil) = assert_pdf(Matchers::HaveTaggedContent.new, subject, msg)

data/lib/stationery/pdf/assembler.rb

@@ -6,12 +6,22 @@ module Stationery
     class Assembler
       # `tagging:` (a Tagging::Tree) writes the structure tree of a tagged PDF;
       # `lang:` is the document's natural language; `page_labels:` is the
-      # /PageLabels number tree from PageLabels.entries.
+      # /PageLabels number tree from PageLabels.entries; `attachments:` are
+      # PDF::Attachment files to embed; `xmp:` (true) writes the XMP packet,
+      # with `xmp_extensions:` as further schemas and `xmp_schemas:` describing
+      # them to PDF/A (see XMP); `conformance:` (a PDF::Conformance) adds what
+      # PDF/A and PDF/UA ask of the file.
       def initialize(pages:, resources:, info: {}, outline: [], encryption: nil, tagging: nil, lang: nil,
-                     page_labels: nil)
+                     page_labels: nil, attachments: [], xmp: true, xmp_extensions: {}, xmp_schemas: [],
+                     conformance: nil)
+        @xmp_schemas = xmp_schemas
+        @conformance = conformance
         @tagging = tagging
         @lang = lang
         @page_labels = page_labels
+        @attachments = attachments
+        @xmp = xmp
+        @xmp_extensions = xmp_extensions
         @pages = pages
         @resources = resources
         @info = info
@@ -29,8 +39,12 @@ module Stationery
         @pages.each_with_index { |page, index| write_page(writer, page, kids[index], tree, refs) }
         writer.set(tree, { Type: :Pages, Kids: kids, Count: kids.size })
         outlines = OutlineWriter.new(writer, @outline, kids).write
-        root = writer.add(catalog(tree, outlines, @form.write).merge(accessibility(writer)))
-        writer.render(root:, info: writer.add(info_dictionary))
+        now = Time.now
+        info = info_dictionary(now)
+        entries = catalog(tree, outlines, @form.write)
+                  .merge(accessibility(writer), metadata(writer, info, now), Attachments.write(writer, @attachments))
+        entries.merge!(@conformance.catalog_entries(writer)) if @conformance
+        writer.render(root: writer.add(entries), info: writer.add(info))
       end
 
       private
@@ -59,6 +73,7 @@ module Stationery
           dictionary[:Annots] = page.annotations.map { |annot| annotation_ref(writer, annot, ref) }
         end
         dictionary.merge!(@structure.page_entries(page)) if @structure
+        dictionary.merge!(@conformance.page_entries(page)) if @conformance
         writer.set(ref, dictionary)
       end
 
@@ -77,6 +92,7 @@ module Stationery
 
         ref = writer.reserve
         dictionary = annotation(annotation)
+        dictionary = dictionary.merge(@conformance.annotation_entries(annotation)) if @conformance
         dictionary = dictionary.merge(@structure.annotation(annotation, ref)) if @structure
         writer.set(ref, dictionary)
       end
@@ -90,12 +106,26 @@ module Stationery
         { Type: :Annot, Subtype: :Link, Rect: link[:rect], Border: [0, 0, 0], **target }
       end
 
-      def info_dictionary
+      def info_dictionary(now)
         info = { Producer: "Stationery #{VERSION}" }.merge(@info.compact)
         info = info.transform_values { |value| TextString.new(value.to_s) }
-        info[:CreationDate] = TextString.new(Time.now.utc.strftime("D:%Y%m%d%H%M%SZ"))
+        info[:CreationDate] = TextString.new(now.utc.strftime("D:%Y%m%d%H%M%SZ"))
         info
       end
+
+      def extensions = (@conformance&.xmp_extensions || {}).merge(@xmp_extensions)
+      def schemas = (@conformance&.xmp_schemas || []) + @xmp_schemas
+
+      # The XMP packet as an uncompressed /Metadata stream, mirroring the Info
+      # dictionary at the same instant. An encrypted document encrypts it like
+      # every other stream (/EncryptMetadata defaults to true).
+      def metadata(writer, info, now)
+        return {} unless @xmp
+
+        values = info.except(:CreationDate).transform_values(&:value)
+        packet = XMP.packet(info: values, lang: @lang, time: now, extensions:, schemas:)
+        { Metadata: writer.add(Stream.new(packet, { Type: :Metadata, Subtype: :XML }, compress: false)) }
+      end
     end
   end
 end

data/lib/stationery/pdf/attachments.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "digest/md5"
+
+module Stationery
+  module PDF
+    # A file embedded in the document: its name, bytes, MIME type, an
+    # optional description and how it relates to the document (the
+    # /AFRelationship a Factur-X invoice or a PDF/A-3 attachment declares).
+    Attachment = Data.define(:name, :data, :mime, :description, :relationship, :modified_at)
+
+    # Builds and writes embedded files: each becomes a /Filespec with an
+    # /EmbeddedFile stream, listed in the catalog's /Names /EmbeddedFiles
+    # tree and its /AF array.
+    module Attachments
+      RELATIONSHIPS = { alternative: :Alternative, source: :Source, data: :Data, supplement: :Supplement,
+                        unspecified: :Unspecified }.freeze
+
+      module_function
+
+      def build(name, data, mime: "application/octet-stream", description: nil, relationship: :unspecified,
+                modified_at: nil)
+        name = name.to_s
+        raise ArgumentError, "an attachment needs a name" if name.empty?
+        raise ArgumentError, "attachment #{name.inspect} needs its data as a String" unless data.is_a?(String)
+        unless RELATIONSHIPS.key?(relationship)
+          raise ArgumentError, "unknown attachment relationship #{relationship.inspect}; use one of " \
+                               "#{RELATIONSHIPS.keys.map(&:inspect).join(", ")}"
+        end
+
+        Attachment.new(name:, data: data.b, mime: mime.to_s, description: description&.to_s, relationship:,
+                       modified_at:)
+      end
+
+      # One list from class-level attachments and per-render hashes
+      # (`{ name:, data:, mime:, … }`); the same name twice raises.
+      def merge(*lists)
+        lists.flatten.compact.map { |item| item.is_a?(Attachment) ? item : from_hash(item) }.tap do |all|
+          duplicate = all.map(&:name).tally.find { |_, count| count > 1 }&.first
+          raise ArgumentError, "attachment #{duplicate.inspect} is given twice" if duplicate
+        end
+      end
+
+      def from_hash(hash)
+        hash = hash.to_h.transform_keys(&:to_sym)
+        build(hash[:name], hash[:data], **hash.except(:name, :data))
+      end
+
+      # The catalog entries for the files, written through `writer`; empty without any.
+      def write(writer, attachments)
+        return {} if attachments.nil? || attachments.empty?
+
+        refs = attachments.sort_by(&:name).map do |attachment|
+          [attachment.name, writer.add(filespec(writer, attachment))]
+        end
+        { Names: { EmbeddedFiles: { Names: refs.flatten } }, AF: refs.map(&:last) }
+      end
+
+      def filespec(writer, attachment)
+        spec = { Type: :Filespec, F: attachment.name.b, UF: TextString.new(attachment.name),
+                 AFRelationship: RELATIONSHIPS.fetch(attachment.relationship),
+                 EF: { F: writer.add(stream(attachment)) } }
+        spec[:Desc] = TextString.new(attachment.description) if attachment.description
+        spec
+      end
+
+      def stream(attachment)
+        params = { Size: attachment.data.bytesize, CheckSum: HexString.new(Digest::MD5.digest(attachment.data)) }
+        if attachment.modified_at
+          params[:ModDate] = TextString.new(attachment.modified_at.utc.strftime("D:%Y%m%d%H%M%SZ"))
+        end
+        Stream.new(attachment.data, { Type: :EmbeddedFile, Subtype: attachment.mime.to_sym, Params: params })
+      end
+    end
+  end
+end