stationery 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21d52a1f02122474b5316373c70965424f3479973757219d2b7b87ed453e8642
-  data.tar.gz: eaa7be7242e9f38e270cb23a533bac9038963c3e61c44c1e57ebaefe0288ef29
+  metadata.gz: 41ce5a83b1405e6756b6b2238b4796d1c7331e82f1abb51df2747befa61dbc26
+  data.tar.gz: a1c9fab02c1ce65eb761c96084c81b72117aee45ac2c0db8c1326ce94651f7a4
 SHA512:
-  metadata.gz: 0dd292c0de3767e870563e954a9ea1b466beed56af675209d69baa09f7c44e337117a5b7256e41b4a35e39f694f0cfc721f2729cd1af8f7dc6081712a4263034
-  data.tar.gz: 73286d789a65a258a026fc65fe8bbc1287dfd2df6ee13d07177cac13beba4f0e7bbcbdfc4bbafc4b3643d762efeb6a3cfb9cb6ab019e6a14c1351a920bc998db
+  metadata.gz: 9c1a85c89e74b002d14d6dd2aaa7153e34e746636ad6059b8db6a83f302b7058d4efb7430346463fc614ba0b61b7991226c44d724b62479d22ab5b1a007b419a
+  data.tar.gz: dfc30baf5b1803d38d7087eed1b24960fe79c3021f119b859d695458e128ed23baf74d961779b2bdb39f1071a0ed7cd09f51d1aa3881eb3076190f1a8d5a63b0

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.10.0 (2026-09-28)
+
+CSS for `html`, better line and page breaking, timestamped signatures, and streaming to a block.
+
+- `html` reads CSS: `<style>` rules (element, `.class`, `#id`, compound selectors, comma lists, `*`; also inside `@media print`/`all`) and inline `style`, cascaded after `styles:` by specificity. Properties: `color`, `font-size` (`px`, `pt`, `em`, `rem`, `%`, keywords), `font-weight`, `font-style`, `text-decoration`, `text-align`, `background-color` and `padding` on blocks and cells, `margin-top`/`margin-bottom`, `border` on `table`/`td`/`th`, `width` on `img`, `table` and cells, `page-break-before`/`-after`/`-inside` and the `break-*` forms. `<font color size>` and `<center>` are read too. Anything else, and selectors with combinators or pseudo-classes, is ignored and reported once as `Warnings::UnsupportedCss`; `url()` and `@import` are never read. HTML without styles renders as before.
+- Orphans and widows: `orphans:` and `widows:` on `text`, `text_style`, `default_text` and rich `styles:` (`p`, `li`), default 1 and 1. A paragraph that would leave too few lines behind moves whole; one that would carry too few takes more with it; at the top of a fresh page it splits rather than overflow.
+- Line breaking: a zero-width space (U+200B) and `<wbr>` are break opportunities that draw nothing and never reach the file. Lines may break between CJK characters (ideographs, kana, Hangul, fullwidth forms) with kinsoku rules: no break before closing punctuation, small kana and iteration marks, none after an opening bracket. Hyphenation and the character-break fallback leave CJK runs alone.
+- Signature timestamps: `sign(…, timestamp: "https://tsa.example/tsr")` (or a Hash with `url:`, `username:`, `password:`, `hash:`, `client:`) requests an RFC 3161 token over the signature and embeds it as `id-aa-signatureTimeStampToken`, giving a PAdES-B-T signature. A TSA that cannot be reached, refuses, or answers for another imprint or nonce raises `Stationery::SignatureError`; nothing is written untimestamped. `Inspector#signatures` entries gain `timestamp: { time:, tsa:, valid: }`.
+- Streaming: `to_pdf { |chunk| … }` hands the file over in pieces as objects are written (first bytes sooner, no output buffer) and returns the byte count. Layout still runs in full first, so peak memory is unchanged. Every other form of `to_pdf` returns the String and is byte for byte what it was. A block with `sign:` or with a target raises `ArgumentError`.
+- **Behaviour changes:** a `page_break` inside a `group` now breaks the page (it was ignored unless the group overflowed). `image(width: 0.5)`: a Float up to 1 is a share of the available width, as for boxes and columns, so `width: 1.0` is full width, not one point. A table cell may be a Hash of cell options around its content. In SVG and HTML stylesheets an at-rule no longer swallows the rule after it.
+- `Stationery::CSS` holds the selector and stylesheet parsers SVG and HTML share (`SVG::Selector` and `SVG::Stylesheet` remain as constants). `Text::RunsBuilder#scale` and `#with`.
+- Benchmarks: `rake bench` compares three engines when the `:benchmark` group has sghtmltopdf (Prawn and stationery otherwise) and reports the best render, allocations, bytes and pages; the docs gain a Comparison page with a feature matrix against Prawn and sghtmltopdf.
+
+## 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.

data/README.md

@@ -97,16 +97,17 @@ 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, styled by a CSS subset (`<style>` rules and inline `style`). 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`.
+`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`,
+`orphans` and `widows` (the fewest lines a page break may leave behind and carry over; default 1, a paragraph that cannot meet them moves whole).
 `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).
@@ -138,6 +139,81 @@ 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.
+- `html` reads a subset of CSS from `<style>` elements and inline `style` attributes (see
+  [What CSS is read](#what-css-is-read)); what it does not read is reported once as an
+  `UnsupportedCss` warning. `markdown` reads none.
+- `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.
+
+#### What CSS is read
+
+`html` applies `<style>` rules and inline `style` attributes on top of `styles:`. The cascade is
+the usual one: the element's defaults from `styles:`, then stylesheet rules by specificity (id over
+class over element, the later rule winning a tie), then the inline style, then the element's own
+mark (`<b>`, `<i>`, `<u>`, `<s>`).
+
+Selectors are an element name, `.class`, `#id`, any compound of them (`p.lead`, `td.n.total`),
+comma lists and `*`. Selectors with combinators or pseudo-classes (`ul li`, `a > b`, `a:hover`) are
+ignored and reported. At-rules are skipped, except that rules inside `@media print` and
+`@media all` are read.
+
+| Property | Values | Applies to |
+| --- | --- | --- |
+| `color` | `#rgb`, `#rrggbb`, `rgb()`, `rgba()` (alpha ignored), the common colour names | text, inherited |
+| `font-size` | `px` (0.75 pt), `pt`, `em`, `%`, `xx-small` to `xx-large`, `smaller`, `larger`; relative sizes multiply the size around them | text, inherited |
+| `font-weight` | `bold`, `normal`, `100`–`900` (600 and up is bold) | text, inherited |
+| `font-style` | `italic`, `oblique`, `normal` | text, inherited |
+| `text-decoration` | `underline`, `line-through`, `none` | text, inherited |
+| `text-align` | `left`, `center`, `right`, `justify` | paragraphs, headings, cells, images; inherited from a container |
+| `background-color` | as `color`, or `transparent` | `p`, `div` and other containers, `blockquote`, `pre`, `table`, `td`, `th` |
+| `padding`, `padding-top` … `padding-left` | one to four lengths in `px` or `pt` | the same |
+| `margin`, `margin-top`, `margin-bottom` | lengths in `px` or `pt`; top and bottom only, added to `gap:` | blocks |
+| `border` | `1px solid #ccc` in any order, `none` | `table` (every cell), `td`, `th` |
+| `width` | `px`, `pt`, `%`, `auto` | `img`, `table`, and `td`/`th` (column widths, when every cell of the first row has one) |
+| `page-break-before`, `page-break-after`, `break-before`, `break-after` | `always`, `page`, `auto` | blocks |
+| `page-break-inside`, `break-inside` | `avoid`, `auto` | blocks |
+
+`<font color size>` and `<center>` are read the same way. Everything else (`display`, `float`,
+`position`, `font-family`, `line-height`, `em` lengths outside `font-size`, `url()` values,
+inline backgrounds) is ignored and named in the `UnsupportedCss` warning, so `strict` catches
+content that expects more than this. No value is ever fetched: `url()` and `@import` are dropped.
+
+```ruby
+html <<~HTML
+  <style>
+    .note { background-color: #FEF3C7; padding: 8pt; margin: 6pt 0; break-inside: avoid }
+    td.amount { text-align: right; width: 25% }
+    h2 { page-break-before: always; color: #0F766E }
+  </style>
+  <div class="note"><p><b>Note.</b> Prices include VAT.</p></div>
+HTML
+```
+
+#### 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, no fetched styles.** `script`, `template` and `title` content is dropped and raw
+  HTML inside Markdown stays literal text. CSS is read only for the fixed list of properties
+  above: `url()` and `@import` are dropped unread, and nothing in a style can position content
+  outside the flow or hide it.
+- **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 +266,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 +281,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.
 
@@ -405,12 +492,14 @@ mislabelled: `ArgumentError` for options that contradict the level, `Stationery:
   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.
+- 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` as PDF/A-3b plus PDF/UA-1 and validates them with
+`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:
 
@@ -451,7 +540,7 @@ InvoicePdf.new(invoice).to_pdf(factur_x: { xml:, profile: :extended }) # per ren
   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.
+- 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
@@ -459,6 +548,73 @@ InvoicePdf.new(invoice).to_pdf(factur_x: { xml:, profile: :extended }) # per ren
 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",
+       timestamp: "https://tsa.example/tsr"                                          # optional: PAdES B-T
+  # 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`).
+- `timestamp: "https://tsa.example/tsr"` asks an RFC 3161 time-stamping authority (TSA) to sign the
+  signature value and the time it saw it, and carries that token in the signature's unsigned
+  attributes: PAdES baseline B-T. A reader can then trust the signing time, and the signature, after
+  the signer's certificate has expired. It is one HTTP request per render, with Ruby's own
+  `net/http`; `timestamp: { url:, username:, password:, hash: :sha256 }` adds HTTP basic auth or
+  another digest (`:sha384`, `:sha512`), and `client:` (a callable given the request DER and
+  answering the response DER) replaces the HTTP client. A TSA that cannot be reached, refuses, or
+  answers for another request or another digest raises `Stationery::SignatureError`: the document
+  is never written without the timestamp it was asked for.
+- The file is written once, with `contents_size:` bytes kept free for the signature (8192, or
+  16384 with a timestamp, whose token brings the TSA's certificates along), 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: long-term validation data (LTV: the revocation answers and document timestamps of
+  PAdES B-LT and B-LTA), 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, or the TSA, is decided by their certificates 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`; with
+`TSA_URL=http://timestamp.digicert.com` it also timestamps a PDF/A-3b render at that authority and
+checks the token (`verify:timestamp`, not part of CI: it needs the network).
+`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
 
 `to_pdf(debug: true)` outlines every layout rectangle on top of the content: boxes (red, padding dashed),
@@ -476,6 +632,20 @@ Invoice.new.to_pdf("invoice.pdf", debug: %i[cell cell_padding])
 gem "stationery", require: "stationery/rails"
 ```
 
+### Large documents
+
+`to_pdf { |chunk| … }` streams the file to the block in pieces as it is written and answers the
+number of bytes: the first bytes leave sooner and no output buffer is built. Peak memory does
+not drop. Layout runs in full before the first byte (pagination has to see every page) and the
+laid-out pages are what a render holds: a 938-page document peaks at 187 MB as a String and
+185 MB streamed. The streamed file lists its objects in the order they were written, a page's
+before the next page's and fonts, the structure tree and the catalog last; the String keeps them
+in numbered order. Both are the same document. A signed document cannot go to a block, since the
+signature covers every byte (`ArgumentError`). `to_pdf`, `to_pdf(path)` and `to_pdf(io)` build the
+String and return it. In a controller with `ActionController::Live`,
+`document.to_pdf { |chunk| response.stream.write(chunk) }` streams a download; `send_pdf` and
+`render pdf:` buffer.
+
 Controllers gain `render pdf:` and `send_pdf`:
 
 ```ruby
@@ -665,6 +835,10 @@ names their authors and licences), drawing a hyphen at the break. A soft hyphen
 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.
+Lines also break at a zero-width space (U+200B, `<wbr>` in HTML), which is never
+drawn, and between ideographic characters (CJK ideographs, kana, Hangul), keeping
+a closing mark such as 。」 on the line before it and an opening bracket with what
+follows, so Japanese, Chinese and Korean text wraps without spaces.
 
 Images are JPEG (grey, RGB, CMYK) and PNG (every colour type, alpha as a soft
 mask). Parsed fonts and images are cached per process.
@@ -712,6 +886,7 @@ RSpec.describe InvoicePdf do
   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
@@ -737,6 +912,7 @@ class InvoicePdfTest < Minitest::Test
     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
@@ -750,7 +926,9 @@ titles. The RSpec matchers compose like the built-ins: `.and` / `.or`, and insid
 exposes `text`, `page_texts`, `page_count`, `links`, `internal_links`,
 `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?`,
+(`{ profile:, filename:, version:, xml: }`), `signatures` (`[{ field:, name:, reason:, location:,
+signed_at:, subfilter:, byte_range:, signer:, valid:, timestamp: }]`, the timestamp `nil` or
+`{ time:, tsa:, 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
@@ -761,6 +939,9 @@ between the children, as for a `P` holding a `Link`) or `[type]` when empty; a
 
 - **Prawn** is an imperative cursor API: every document does its own layout
   arithmetic. Stationery is a layout engine with a component DSL.
+- **sghtmltopdf** renders HTML and CSS in Rust, fast and with a real CSS layout
+  engine, but writes no outline, forms, tagged PDF, PDF/A, encryption or
+  signatures, and is a native extension.
 - **Headless Chrome** (Grover, ferrum_pdf) renders HTML beautifully but runs
   a browser per worker; stray processes and memory are the price.
 - **Typst** is excellent but a native extension and a second template language.
@@ -802,21 +983,49 @@ events attached is the most useful thing to put in an issue.
 
 ## Performance
 
-`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:
-
-| 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 |
-
-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).
+`bundle exec rake bench` renders three documents with Stationery, with Prawn 2.5 +
+prawn-table, and with [sghtmltopdf](https://github.com/waka/sghtmltopdf) 0.5.1, an
+HTML-to-PDF engine written in Rust, given HTML/CSS twins of the same documents. Every
+engine embeds the same Open Sans TTF files (`benchmark/`, not part of CI). Apple M2 Max,
+Ruby 3.4.2 +YJIT, 28 September 2026, warm caches, the best of three runs:
+
+| Document | Engine | Best render | Renders/s | Objects allocated | PDF bytes | Pages |
+|---|---|---:|---:|---:|---:|---:|
+| Invoice (`examples/invoice.rb`) | Stationery | 13.1 ms | 70.1 | 39,562 | 26,599 | 1 |
+| | Prawn | 18.3 ms | 45.2 | 88,558 | 33,034 | 1 |
+| | sghtmltopdf | 3.4 ms | 259.4 | 53 | 36,693 | 1 |
+| Table, 1,500 rows × 5 columns, repeating header | Stationery | 395 ms | 2.45 | 2,596,598 | 133,754 | 46 |
+| | Prawn | 1,373 ms | 0.71 | 6,901,807 | 2,689,487 | 40 |
+| | sghtmltopdf | 96 ms | 9.99 | 53 | 369,338 | 45 |
+| Cover photo and six illustrated sections | Stationery | 9.0 ms | 99.8 | 45,866 | 41,531 | 3 |
+| | Prawn | 29.7 ms | 30.9 | 102,967 | 55,391 | 2 |
+| | sghtmltopdf | 6.7 ms | 136.8 | 53 | 43,031 | 2 |
+
+sghtmltopdf is the fastest: 3.9x Stationery on the invoice, 4.1x on the table and 1.3x on
+the photo document. That is native code against Ruby, and its 53 objects are the binding's:
+the engine allocates outside the Ruby heap. Stationery is 1.4x, 3.5x and 3.3x faster than
+Prawn and writes the smallest files of the three (28%, 64% and 3% smaller than
+sghtmltopdf's). Stationery compresses content streams; Prawn does not by default, hence its
+larger files. Page counts differ where the engines' line heights and table padding do.
+"Best render" is the fastest single render, the figure other work on the machine disturbs
+least; renders per second is the average over five seconds.
+
+What Stationery optimises for is not the last millisecond: it is pure Ruby with no native
+extension to compile or precompile, its output is the same bytes on every platform, and the
+PDF features (tagged output, PDF/A, forms, signatures) live in the same process as your
+models. See the [comparison](https://stationery.zoolutions.llc/docs/comparison) for what
+each engine does.
+
+`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).
+`SGHTMLTOPDF=0 bundle exec rake bench` leaves the third engine out, as does a machine
+without its gem.
+
+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
 
@@ -824,7 +1033,8 @@ Fonts: no variable fonts (including CFF2) and no WOFF2 (it needs Brotli; convert
 `.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
+in the chain has are drawn as `.notdef` and reported. Text runs left to right (CJK text wraps between
+ideographs, but there is no vertical layout); hyphenation
 patterns are bundled for English, German and Swedish only (a soft hyphen works in any language),
 and justification only widens spaces.
 
@@ -833,18 +1043,22 @@ sets and exports use, nothing else: `image`, `mask`, `pattern`, `filter` and `te
 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.
+source resolution (only PNGs can be downscaled), so an oversized one is reported, not resized. `html` reads a fixed subset of CSS (colours, sizes, weights, alignment, margins, padding, table
+borders and widths, page breaks; see [What CSS is read](#what-css-is-read)), not a layout
+engine's worth: no `display`, floats, positioning, `font-family` or selectors with combinators.
+`markdown` reads no CSS, 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.
+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 long-term validation data (PAdES B-LT), 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

@@ -144,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/{svg → css}/selector.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Stationery
-  module SVG
+  module CSS
     # A compound CSS selector: an element name or `*`, then any number of
     # `.class` and `#id` parts. Combinators, pseudo-classes and attribute
     # selectors are not read.

data/lib/stationery/{svg → css}/stylesheet.rb

@@ -1,25 +1,30 @@
 # frozen_string_literal: true
 
 module Stationery
-  module SVG
+  module CSS
     # The rules of a document's <style> elements. An element's declarations
     # are those of every matching rule, the more specific winning and the
-    # later winning among equals. At-rules are skipped and `!important` is
-    # read as a plain declaration; rules whose selectors use combinators are
-    # ignored and listed in #unsupported.
+    # later winning among equals. At-rules are skipped (`@import`, `@font-face`,
+    # `@page`, `@media screen`), except that the rules inside `@media print`
+    # and `@media all` are read; `!important` is read as a plain declaration;
+    # rules whose selectors use combinators are ignored and listed in
+    # #unsupported.
     class Stylesheet
       Rule = Data.define(:selector, :declarations, :index)
 
       RULE = /([^{}]+)\{([^{}]*)\}/
       COMMENT = %r{/\*.*?\*/}m
+      STATEMENT = /@[\w-]+[^;{}]*;/
+      AT_BLOCK = /@([\w-]+)([^{};]*)\{((?:[^{}]*\{[^{}]*\})*[^{}]*)\}/
+      PRINTED = /\b(print|all)\b/i
 
       def self.parse(css)
         rules = []
         unsupported = []
-        css.gsub(COMMENT, "").scan(RULE).each do |selectors, body|
+        plain(css).scan(RULE).each do |selectors, body|
           next if selectors.strip.start_with?("@")
 
-          declarations = Style.declarations(body).transform_values { |value| value.sub(/\s*!important\z/, "") }
+          declarations = CSS.declarations(body).transform_values { |value| value.sub(/\s*!important\z/, "") }
           selectors.split(",").map(&:strip).each do |text|
             selector = Selector.parse(text)
             selector ? rules << Rule.new(selector, declarations, rules.size) : unsupported << text
@@ -28,6 +33,13 @@ module Stationery
         new(rules, unsupported)
       end
 
+      # The rules outside at-rules, plus those a print medium would read.
+      def self.plain(css)
+        css.gsub(COMMENT, "").gsub(STATEMENT, "").gsub(AT_BLOCK) do
+          Regexp.last_match(1).casecmp?("media") && Regexp.last_match(2).match?(PRINTED) ? Regexp.last_match(3) : ""
+        end
+      end
+
       attr_reader :unsupported
 
       def initialize(rules, unsupported)
@@ -37,6 +49,8 @@ module Stationery
 
       EMPTY = new([], []).freeze
 
+      def empty? = @rules.empty?
+
       def declarations(element)
         @rules.select { |rule| rule.selector.match?(element) }
               .sort_by { |rule| [rule.selector.specificity, rule.index] }

data/lib/stationery/css.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require_relative "css/selector"
+require_relative "css/stylesheet"
+
+module Stationery
+  # The CSS the svg and html elements read: `<style>` rules with element,
+  # class and id selectors, and inline `style` declarations.
+  module CSS
+    module_function
+
+    # `"a: 1; b : 2"` → `{ "a" => "1", "b" => "2" }`; names lowercased.
+    def declarations(style)
+      style.to_s.split(";").filter_map do |declaration|
+        key, value = declaration.split(":", 2)&.map(&:strip)
+        [key.downcase, value] if key && value && !key.empty?
+      end.to_h
+    end
+  end
+end