stationery 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f9e83f23437589a026e0a9a2fde163a39a2c4151c434afc5bdbea38a98891dd
-  data.tar.gz: 67e42695ae205e05049441490b89b908f6468ba94e00c095c1de8eaeae986d65
+  metadata.gz: '04892e3a1ad9e6da0174cb033f2a57a048c83c77e57e72aff4a98ccfa48e1ba7'
+  data.tar.gz: f9ee80ed8edd77108f3d6ae4f19f5a9d537000e6cf0e1efd8707e2682e89faac
 SHA512:
-  metadata.gz: 40756fe30e4c2d400fab7402e490609cf313e8ae06c5317489f6b0337f96fc5ad00d8f2c8b05b348812955b109cc0f9685f9c1668b8f307d1fd16ac9492facad
-  data.tar.gz: 1a7938f3b608b68df057d3385d5824dc6a57338978a76ad39bed42701838ee2a408db1c2d30daccf3a834b03bea9f6d1441ef6405691dff0090611d26cbe05a0
+  metadata.gz: d5c07272f2ff4480d35caa3decebc77336e12b3e8b7aea4f8ddd06f47529c12438a86606fb41350bf9d0eb59915e1cee13505acf75ef9e7544135ddd6878d5e6
+  data.tar.gz: 4901d1100e09107496cf9d83b6ac0c2a767aacc43090b1c5b87137c35667c3bd009adc8a5c627f09d50bfe1d46dc6172abaddb9dfe0cdfc9fe7426425471814b

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.9.0 (2026-09-28)
+
+Forms in the document's fonts, digital signatures, a much faster text and table pipeline, and hardening for untrusted input.
+
+- Digital signatures: `sign certificate:, key:, chain:, passphrase:, reason:, location:, contact:, name:, field:, at:` at class level (values may be callables or method names, resolved per render) or `to_pdf(sign:)`. Fills a named `signature_field` or adds an invisible one, writes `/ETSI.CAdES.detached` CMS with the ESS signing-certificate-v2 attribute (PAdES baseline B-B shape) over the whole file, RSA or ECDSA with SHA-256, built on the stdlib `openssl` (required only when signing). Works with encryption and under PDF/A-3b and PDF/UA-1; `/SigFlags 3` on the form. Verified with `openssl cms -verify`, `pdfsig` and veraPDF; `rake verify:signature`. `Inspector#signatures` (validates the digest and the CMS), `have_signature`, `assert_pdf_signature`. No timestamps, LTV or multiple signatures yet.
+- Forms: field appearances use the document's fonts, embedded and Identity-H encoded with per-character fallback, so values in any script the fonts cover render; check marks and radio dots are vector paths, so no standard-14 font is referenced. An editable field keeps printable ASCII and Latin-1 (plus a select's options) in its font, a `read_only:` field only its value. Every field gets `/TU` from `tooltip:`, `label:` or its name; `NeedAppearances` is dropped under a conformance level. Forms are now allowed under PDF/A-3b and PDF/UA-1 (veraPDF passes `examples/form.rb` as both). Documents without fields are byte-identical.
+- Performance: the wrapper measures each segment once and `Font#width_of` memoises advance and kerning together, keyed by feature-tag identity, undoing the 0.7.0 regression (an 8-page text document 163 → 45 ms, byte-identical); tables carry column widths and row heights across page breaks (also fixing column widths drifting between pages), stroke each cell border as one path (the 1,500-row table's PDF 236 → 134 KB) and place rows on a grid only when a page paints them: 913 → 399 ms. A deterministic metrics gate (`rake metrics`, `benchmark/baseline.json`: allocations, pages, bytes) runs in CI; README performance figures now reproduce.
+- Untrusted input: `html` and `markdown` take `max_depth:` (64); deeper elements, block quotes and lists are flattened into the deepest kept with a `Warnings::NestingLimit`, never a `SystemStackError`. Markdown inline parsing is bounded (brackets, labels, emphasis), so pathological input finishes in milliseconds instead of minutes. SVG keeps 128 levels and caps `use` chains at 32.
+- `image` with an IO source no longer raises `NameError` for `Pathname` in plain Ruby; a spec now renders every feature in a fresh interpreter without the test bundle so a missing stdlib require cannot hide again.
+- SVG: `use`, `symbol`, nested `svg` and `clipPath` shipped in 0.8.0; the docs Forms page and the docs image now include the example fonts, so every `/examples/<name>.pdf` renders on the site.
+
+## 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:`, …). |
@@ -97,13 +97,13 @@ renders them all, or render one with `stationery render examples/report.rb`.
 | `keep_with_next: true \| points` | On `text`, `box` or `group`: never end a page with this node; with a number, keep at least that many points of what follows with it. |
 | `text_style(**style) { }` | Default text style for a block. |
 | `canvas(height:) { \|canvas, rect\| }` | Draw directly: rectangles, rounded rectangles, circles, lines, Bézier paths, clipping, images, links; `rotate(degrees, around:) { }` and `transform([a, b, c, d, e, f]) { }` blocks. |
-| `text_field(name, value:, width:, height:, multiline:, max_length:, comb:, read_only:, required:, font_size:, border:, background:, radius:, at:)` | An interactive text input (AcroForm). `width:` is `:full` or points; dotted names (`"address.city"`) group fields. See [Forms](#forms). |
+| `text_field(name, value:, width:, height:, multiline:, max_length:, comb:, read_only:, required:, font_size:, border:, background:, radius:, tooltip:, at:)` | An interactive text input (AcroForm). `width:` is `:full` or points; dotted names (`"address.city"`) group fields. See [Forms](#forms). |
 | `checkbox(name, checked:, size:, label:, at:)` | An interactive check box, with an optional label drawn to its right. |
 | `radio(name, value, checked:, size:, label:, at:)` | One choice of a radio group: radios sharing `name` form one field whose value is the checked `value`. |
 | `select(name, options:, value:, width:, height:, editable:, at:)` | A drop-down (combo box); `editable: true` also accepts typed values. |
 | `signature_field(name, width:, height:, label:, at:)` | An empty signature field for the signer to fill, drawn as a rule over the label. |
-| `html(source, styles:, gap:, images:, base_path:, bookmarks:, links:)` | Rich text from HTML (ActionText/Trix, CMS output): paragraphs, headings, lists, quotes, code, rules, tables, images, inline marks and links. See [HTML and Markdown](#html-and-markdown). |
-| `markdown(source, styles:, gap:, images:, base_path:, bookmarks:, links:)` | The same from CommonMark (plus GFM tables and strikethrough). |
+| `html(source, styles:, gap:, images:, base_path:, bookmarks:, links:, max_depth:)` | Rich text from HTML (ActionText/Trix, CMS output): paragraphs, headings, lists, quotes, code, rules, tables, images, inline marks and links. See [HTML and Markdown](#html-and-markdown). |
+| `markdown(source, styles:, gap:, images:, base_path:, bookmarks:, links:, max_depth:)` | 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`), `features` (OpenType feature tags, e.g. `%i[smcp onum]`), `hyphenate` (`true` for English, or `"de"`, `"sv"`; default off), `align` (`:left`, `:center`, `:right`, `:justify`), `leading`.
@@ -138,6 +138,33 @@ end
   `DroppedLink` warning. `links: %w[http https]` changes the list, `links: :all` keeps every href
   from a trusted source.
 - `gap:` spaces the blocks (default 6); `bookmarks: true` adds h1–h3 to the PDF outline.
+- `max_depth:` (default 64) is how deep the source may nest: HTML elements inside one another,
+  or Markdown block quotes and lists. What lies deeper is flattened into the deepest element
+  kept, so its text stays and its structure goes, and a `NestingLimit` warning says how deep the
+  source went. Block quotes and lists also stop indenting after twelve levels, where they would
+  leave their text no width; that is reported the same way.
+
+#### Untrusted input
+
+`html` and `markdown` are meant for content you did not write (a CMS body, a comment, an
+ActionText field), and nothing in that content can reach outside the document or take the
+process down:
+
+- **No requests.** Remote images are never fetched; an image is read only from `images:` or from
+  under `base_path:`, and a path that climbs out of it is skipped (`SkippedImage`).
+- **No surprising links.** Only `http`, `https`, `mailto` and `tel` hrefs (and `#anchor`) become
+  links (`DroppedLink` for the rest), so a `javascript:` or `file:` href is plain text.
+- **No scripts or styles.** `script`, `style`, `template` and `title` content is dropped, raw HTML
+  inside Markdown stays literal text, and no CSS is evaluated beyond `text-align` and inline
+  bold and italic.
+- **Bounded nesting.** Five thousand nested `<div>`s, block quotes or lists render flattened,
+  with a `NestingLimit` warning, instead of exhausting the stack (the `svg` element guards its
+  own nesting the same way, at 128 levels). Emphasis nests without recursion, at most 64
+  brackets wait for their `]`, and a link label is at most 999 characters, so parsing takes time
+  in proportion to the input.
+- **Size is yours to bound.** There is no limit on how much text is rendered: a megabyte of
+  input is a few hundred pages. Cap the length of what you accept before you render it, and use
+  `strict` (or read `document.warnings`) when a warning should stop the document.
 
 ### Links, bookmarks and table of contents
 
@@ -190,7 +217,8 @@ keeps its title, with no number and no link.
 ### Forms
 
 Form fields are interactive widgets (an AcroForm) that lay out like boxes, or sit at a fixed page
-position with `at: [x, y]`. They work inside boxes, rows and table cells.
+position with `at: [x, y]`. They work inside boxes, rows and table cells. The
+[Forms guide](https://stationery.zoolutions.llc/docs/forms) lists every option of every field.
 
 ```ruby
 text "Name"
@@ -204,14 +232,24 @@ checkbox "terms", checked: false, label: "I accept the terms"
 signature_field "signature", label: "Signature of the applicant"
 ```
 
-- Every widget carries its own appearance (drawn in Helvetica, ZapfDingbats for the check mark), so
-  the form looks the same in every viewer; `NeedAppearances` is set too, so viewers redraw edited
-  values. Values are Unicode (`/V`); the drawn appearance covers the Windows-1252 range.
+- Every widget carries its own appearance, so the form looks the same in every viewer. Text is set
+  in the text style around the field, in the document's own fonts: embedded, with the fallbacks
+  applied per character, so a value in any script the fonts cover is drawn (`/V` holds it as
+  Unicode). Check marks and radio dots are paths. `NeedAppearances` is set too, so viewers redraw
+  edited values; ZapfDingbats is listed for the ones that redraw a button's mark, never embedded
+  and never used by the appearances themselves.
+- A field that can be edited keeps printable ASCII and Latin-1 in its font beyond the value it shows
+  (and a select the glyphs of every option), about 10 KB per font, so the text a viewer redraws
+  after an edit has its glyphs; what is typed outside that range falls back to the viewer's own
+  font. A `read_only:` field keeps its value's glyphs only.
+- `tooltip:` is a field's accessible name (`/TU`): by default a check box's or signature's `label:`,
+  otherwise the field name. A radio group takes the `tooltip:` of its first choice.
 - Dotted names build the field hierarchy viewers show as groups; widgets sharing a name are one field
   with several widgets. A name used as both a field and a group raises `ArgumentError`.
 - `read_only:`, `required:`, `multiline:`, `max_length:` and `comb:` set the matching field flags.
 - A radio group's value is its checked choice's `value` (`Off` when none is checked); a select box
-  lists its `options:` and draws the chosen `value`; a signature field is left unsigned for the signer.
+  lists its `options:` and draws the chosen `value`; a signature field is left unsigned for the
+  signer, unless `sign field:` signs it (see [Digital signatures](#digital-signatures)).
 - `document.fields` returns `{ name => value }` for the last render (a check box's value is `true` or
   `false`, an unchecked radio group's and a signature field's `nil`). Encrypted documents keep their fields fillable.
 
@@ -294,6 +332,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 +390,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 +408,150 @@ 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 are allowed: their appearances draw with embedded fonts and paths, every
+  field has a `/TU`, and `NeedAppearances` and ZapfDingbats are left out. Only a field made without
+  a font book (`Forms::Field.new` placed with `canvas.widget`) raises, since it draws with the
+  standard Helvetica.
+- 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` and `examples/form.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:`. Form fields and a signature are fine.
+- 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.
+
+### Digital signatures
+
+`sign` signs the file with a certificate and its private key, so a reader can tell who issued it
+and that not a byte changed since. It needs nothing but Ruby's own `openssl`, loaded when the first
+signature is made.
+
+```ruby
+class ContractPdf < Stationery::Document
+  sign certificate: -> { Rails.application.credentials.dig(:signing, :certificate) }, # PEM or OpenSSL object
+       key: -> { Rails.application.credentials.dig(:signing, :key) },                 # read per render
+       chain: -> { [File.read("config/intermediate.pem")] },
+       reason: "Approved", location: "Malmö", contact: "legal@acme.test"
+  # sign { { certificate: signer.certificate, key: signer.key, field: "approval" } }  # or a block for all of it
+
+  def view_template
+    text "Contract"
+    signature_field "approval", label: "Approved by" # `field: "approval"` signs this one
+  end
+end
+
+ContractPdf.new.to_pdf(sign: { certificate:, key:, passphrase: "…" }) # per render; nil for none
+```
+
+- The signature is `/SubFilter /ETSI.CAdES.detached`: a detached CMS over every byte of the file
+  except the signature itself, SHA-256 with an RSA (PKCS #1 v1.5) or EC (ECDSA) key, with the
+  signed attributes PAdES baseline B-B asks for (content type, message digest and the ESS
+  signing-certificate-v2 that binds it to the certificate; the signing time is the dictionary's
+  `/M`). The certificate and its `chain:` travel in the signature.
+- `certificate:` and `chain:` take an `OpenSSL::X509::Certificate` or PEM, `key:` an
+  `OpenSSL::PKey` or PEM (`passphrase:` when it is encrypted). Any value may be a block or callable
+  answering it for the document being rendered, and `certificate:`, `key:`, `chain:` and
+  `passphrase:` a method name, so secrets are read when they are needed and never at class load.
+  A key that is not the certificate's raises `ArgumentError`.
+- `field:` names the `signature_field` to sign, which keeps its appearance. Without it the
+  signature is invisible: a field of its own (`Signature1`) whose widget has no size, on the first
+  page. `name:` is the signer's name (the certificate's common name by default), `at:` the signing
+  time (`Time.now`).
+- The file is written once, with `contents_size:` bytes (8192) kept free for the signature, which
+  is then filled in place. A long certificate chain may need more; a signature that does not fit
+  raises and says so.
+- A signed form asks viewers not to regenerate appearances (`NeedAppearances` is left out) and
+  sets `/SigFlags 3`. `encrypt:` and `conformance` combine with `sign`: the signature is the one
+  string encryption leaves in the clear, and a signed PDF/A-3b or PDF/UA-1 file still validates.
+- Not covered: signature timestamps (PAdES-T) and long-term validation data (LTV), a second
+  signature, and signing a file that already exists. All of them need incremental updates;
+  Stationery signs what it renders, once. Whether a viewer trusts the signer is decided by the
+  certificate and the viewer's trust list, not by the file.
+
+`bundle exec rake verify:signature` signs `examples/invoice.rb` with a throwaway certificate and
+verifies it with `openssl cms -verify` and, when poppler is installed, `pdfsig`;
+`verify:conformance` validates signed PDF/A-3b and PDF/UA-1 renders with veraPDF. In tests,
+`have_signature(name: "Acme Legal")` checks that a signature covers the whole file and verifies
+against the certificate it carries.
 
 ### Debugging
 
@@ -598,6 +803,10 @@ 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_signature(name: "Acme Legal") } # covers the whole file and verifies
   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 +829,10 @@ 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_pdf_signature pdf, name: "Acme Legal"
     assert_tagged_content pdf
     assert_pdf_structure pdf, [[:Document, [[:H1, "Invoice"], [:P, "INV-7"]]]]
   end
@@ -631,7 +844,11 @@ 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: }`), `signatures` (`[{ field:, name:, reason:, location:,
+signed_at:, subfilter:, byte_range:, signer:, valid: }]`), `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
@@ -684,20 +901,26 @@ events attached is the most useful thing to put in an issue.
 
 `bundle exec rake bench` renders two documents with Stationery and with Prawn
 2.5 + prawn-table, both embedding the same Open Sans TTF files
-(`benchmark/`, not part of CI). Apple M2 Max, Ruby 3.4.2 +YJIT, 27 September 2026:
+(`benchmark/`, not part of CI). Apple M2 Max, Ruby 3.4.2 +YJIT, 28 September 2026:
 
 | Document | Engine | Renders/s | Objects allocated | PDF bytes |
 |---|---|---:|---:|---:|
-| Invoice (1 page, `examples/invoice.rb`) | Stationery | 74.6 | 33,231 | 23,525 |
-| | Prawn | 45.4 (1.64x slower) | 88,558 | 33,034 |
-| Table, 1,500 rows × 5 columns, repeating header | Stationery | 1.47 (46 pages) | 4,462,820 | 233,389 |
-| | Prawn | 0.74 (40 pages; 1.99x slower) | 6,901,818 | 2,689,487 |
+| Invoice (1 page, `examples/invoice.rb`) | Stationery | 66.5 | 39,574 | 26,599 |
+| | Prawn | 41.3 (1.61x slower) | 88,558 | 33,034 |
+| Table, 1,500 rows × 5 columns, repeating header | Stationery | 2.31 (46 pages) | 2,596,554 | 133,754 |
+| | Prawn | 0.58 (40 pages; 4.01x slower) | 6,901,811 | 2,689,487 |
 
 Stationery compresses content streams; Prawn does not by default, hence the
 larger file. `PROFILE=1 bundle exec ruby -Ilib benchmark/profile.rb` prints the
 20 hottest frames of the table render under StackProf (wall mode; `MODE=cpu` or
 `MODE=object` for the others).
 
+Time depends on the machine, so CI holds what does not: `bundle exec rake metrics`
+renders six fixed documents and compares the objects each render allocates, its
+page count and its bytes with `benchmark/baseline.json` (allocations may grow 3%,
+bytes 1%, pages not at all). A change that moves them on purpose records a new
+baseline with `bundle exec rake metrics:update` and says why in the commit.
+
 ## Limitations
 
 Fonts: no variable fonts (including CFF2) and no WOFF2 (it needs Brotli; convert to `.ttf` or
@@ -708,8 +931,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 +944,12 @@ 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) and
+no JavaScript. A render carries one signature (`/ETSI.CAdES.detached`, RSA or EC with SHA-256):
+no signature timestamp (PAdES-T) or long-term validation data, no second signature and no signing
+of a file that already exists, all of which need incremental updates.
+Form fields are set in the document's fonts, but text typed into one is drawn by the viewer:
+characters outside the glyphs the field kept (ASCII and Latin-1) use the viewer's own font.
 
 ## 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
@@ -125,9 +144,11 @@ module Stationery
     end
 
     # An interactive form field's widget (a Forms::Field) over the rectangle.
+    # Its appearance is drawn here, so the glyphs it needs are in the fonts
+    # before they are embedded.
     def widget(field, x, y, w, h, tag: nil)
       rect = [x, @page.height - y - h, x + w, @page.height - y].map { |v| num_value(v) }
-      annotation = { rect:, widget: field }
+      annotation = { rect:, widget: field, appearance: Forms::Appearance.new(field, w, h, @resources) }
       @page.annotations << annotation
       adopt(annotation, tag, rect) if tag
     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