stationery 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21d52a1f02122474b5316373c70965424f3479973757219d2b7b87ed453e8642
-  data.tar.gz: eaa7be7242e9f38e270cb23a533bac9038963c3e61c44c1e57ebaefe0288ef29
+  metadata.gz: '04892e3a1ad9e6da0174cb033f2a57a048c83c77e57e72aff4a98ccfa48e1ba7'
+  data.tar.gz: f9ee80ed8edd77108f3d6ae4f19f5a9d537000e6cf0e1efd8707e2682e89faac
 SHA512:
-  metadata.gz: 0dd292c0de3767e870563e954a9ea1b466beed56af675209d69baa09f7c44e337117a5b7256e41b4a35e39f694f0cfc721f2729cd1af8f7dc6081712a4263034
-  data.tar.gz: 73286d789a65a258a026fc65fe8bbc1287dfd2df6ee13d07177cac13beba4f0e7bbcbdfc4bbafc4b3643d762efeb6a3cfb9cb6ab019e6a14c1351a920bc998db
+  metadata.gz: d5c07272f2ff4480d35caa3decebc77336e12b3e8b7aea4f8ddd06f47529c12438a86606fb41350bf9d0eb59915e1cee13505acf75ef9e7544135ddd6878d5e6
+  data.tar.gz: 4901d1100e09107496cf9d83b6ac0c2a767aacc43090b1c5b87137c35667c3bd009adc8a5c627f09d50bfe1d46dc6172abaddb9dfe0cdfc9fe7426425471814b

data/CHANGELOG.md

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

data/README.md

@@ -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.
 
@@ -405,12 +443,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 +491,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 +499,60 @@ 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"
+  # 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
 
 `to_pdf(debug: true)` outlines every layout rectangle on top of the content: boxes (red, padding dashed),
@@ -712,6 +806,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 +832,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 +846,8 @@ 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: }]`), `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
@@ -804,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
@@ -841,10 +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: 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 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

@@ -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/document.rb

@@ -107,6 +107,21 @@ module Stationery
         config[:factur_x] = { xml: source, **options }
       end
 
+      # Signs every render with a digital signature over the whole file:
+      # `sign certificate: pem, key: pem, reason: "Approved"`. A value may be
+      # a block or callable answering it for the document being rendered (a
+      # method name for certificate:, key:, chain: and passphrase:), and a
+      # block may answer all of them, so keys are read when they are needed.
+      # `field:` names the signature_field it fills; without it the
+      # signature is invisible. See PDF::Signature.
+      def sign(**options, &block)
+        raise ArgumentError, "sign needs certificate: and key:, or a block answering them" unless block || options.any?
+
+        options = PDF::Signature.check(options)
+        PDF::Signature.new(**options) unless block || PDF::Signature.deferred?(options)
+        config[:sign] = block || options
+      end
+
       # Encrypts every render with the standard security handler; see
       # PDF::Encryption::StandardSecurity for the options.
       def encrypt(**)
@@ -141,13 +156,14 @@ module Stationery
     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], attachments: [],
                xmp: metadata[:xmp] != false, conformance: self.class.config[:conformance],
-               factur_x: self.class.config[:factur_x])
+               factur_x: self.class.config[:factur_x], sign: self.class.config[:sign])
       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: }
+                  xmp: xmp || !conformance.nil?, conformance:, invoice:,
+                  signature: PDF::Signature.for(sign, self) }
       Stationery.instrument("render.stationery", document: self.class.name) do |event|
         write(render_pdf(event, **options), target)
       end
@@ -197,12 +213,12 @@ module Stationery
     end
 
     def assemble(pages, resources, outline, encrypt:, tagging:, page_labels:, attachments:, xmp:, conformance:,
-                 invoice:)
+                 invoice:, signature:)
       encryption = encrypt && PDF::Encryption::StandardSecurity.new(**encrypt)
       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)
+                                     xmp_schemas: [invoice&.xmp_schema].compact, signature:)
       Stationery.instrument("write.stationery", document: self.class.name) do |event|
         assembler.render.tap { |pdf| event[:bytes] = pdf.bytesize }
       end

data/lib/stationery/elements/forms.rb

@@ -3,44 +3,49 @@
 module Stationery
   # Interactive form fields. Each takes a name (dotted names group fields,
   # "address.city") and lays out like a box, or at a fixed page position with
-  # `at: [x, y]`.
+  # `at: [x, y]`. Their appearances are set in the text style in effect (the
+  # document's fonts, embedded), and `tooltip:` names a field for assistive
+  # technology (its label or name by default).
   module Elements
     # A text input. `width:` is :full or points; `multiline:`, `max_length:`,
     # `comb:` (a cell count, or true with max_length:), `read_only:`,
     # `required:`, `font_size:`, `border:`, `background:` and `radius:`.
     def text_field(name, value: "", width: :full, height: 22, at: nil, **)
-      field_node(Forms::Field.new(:text, name, value: value.to_s, **), width:, height:, at:)
+      field_node(Forms::Field.new(:text, name, value: value.to_s, typeface: field_typeface, **), width:, height:, at:)
     end
 
     # A check box `size` points square, with an optional label to its right.
     def checkbox(name, checked: false, size: 12, label: nil, at: nil, **)
-      field = Forms::Field.new(:checkbox, name, value: checked == true, **)
+      field = Forms::Field.new(:checkbox, name, value: checked == true, typeface: field_typeface, tooltip: label, **)
       field_node(field, width: size, height: size, at:, label:)
     end
 
     # One choice of the radio group `name`; its `value` becomes the group's
     # value when checked.
     def radio(name, value, checked: false, size: 12, label: nil, at: nil, **)
-      field = Forms::Field.new(:radio, name, value: value.to_s, checked:, **)
+      field = Forms::Field.new(:radio, name, value: value.to_s, checked:, typeface: field_typeface, **)
       field_node(field, width: size, height: size, at:, label:)
     end
 
     # A drop-down (combo box) of `options`; `editable: true` also accepts
     # typed values.
     def select(name, options:, value: nil, width: :full, height: 22, at: nil, **)
-      field = Forms::Field.new(:select, name, value: value&.to_s, options: options.map(&:to_s), **)
+      field = Forms::Field.new(:select, name, value: value&.to_s, options: options.map(&:to_s),
+                                              typeface: field_typeface, **)
       field_node(field, width:, height:, at:)
     end
 
     # An empty signature field for the signer to fill, drawn as a rule over
     # the label.
     def signature_field(name, width: :full, height: 40, label: "Signature", at: nil, **)
-      field = Forms::Field.new(:signature, name, label: label.to_s, **)
+      field = Forms::Field.new(:signature, name, label: label.to_s, typeface: field_typeface, **)
       field_node(field, width:, height:, at:)
     end
 
     private
 
+    def field_typeface = Forms::Typeface.new(@_builder.book, @_builder.style)
+
     def field_node(field, width:, height:, at:, label: nil)
       label &&= field_label(label)
       node = Layout::Field.new(field, height:, width:, label:)

data/lib/stationery/elements/rich.rb

@@ -8,22 +8,29 @@ module Stationery
     # under `base_path:`. Remote images are never fetched. `links:` lists the
     # URL schemes written as links (default http, https, mailto and tel;
     # `#anchor` always is); `:all` keeps every href for trusted sources.
-    def html(source, styles: {}, gap: 6, images: nil, base_path: nil, bookmarks: false, links: nil)
+    # Elements nested deeper than `max_depth:` are flattened into the deepest
+    # one kept (text stays, structure goes) and reported as a NestingLimit
+    # warning, so content from users cannot exhaust the stack.
+    def html(source, max_depth: 64, **)
       require_relative "../html/document"
-      rich(HTML.parse(source.to_s), styles:, gap:, images:, base_path:, bookmarks:, links:)
+      rich(HTML.parse(source.to_s, max_depth:) { |depth| nesting_limit(depth, max_depth) }, **)
     end
 
     # CommonMark (plus GFM tables and strikethrough); options as for html.
-    def markdown(source, styles: {}, gap: 6, images: nil, base_path: nil, bookmarks: false, links: nil)
+    def markdown(source, max_depth: 64, **)
       require_relative "../markdown/document"
-      rich(Markdown.parse(source.to_s), styles:, gap:, images:, base_path:, bookmarks:, links:)
+      rich(Markdown.parse(source.to_s, max_depth:) { |depth| nesting_limit(depth, max_depth) }, **)
     end
 
     private
 
-    def rich(blocks, **)
+    def nesting_limit(depth, limit)
+      @_builder.warnings << Warnings::NestingLimit.new(depth:, limit:)
+    end
+
+    def rich(blocks, styles: {}, gap: 6, images: nil, base_path: nil, bookmarks: false, links: nil)
       require_relative "../rich/renderer"
-      Rich::Renderer.new(self, @_builder, **).render(blocks)
+      Rich::Renderer.new(self, @_builder, styles:, gap:, images:, base_path:, bookmarks:, links:).render(blocks)
     end
   end
 end

data/lib/stationery/elements.rb

@@ -95,9 +95,7 @@ module Stationery
       name = source.to_s.lstrip.start_with?("<") ? "inline" : File.basename(source.to_s)
       source = File.read(source.to_s) unless name == "inline"
       document = SVG::Document.parse(source)
-      if document.unsupported.any?
-        @_builder.warnings << Warnings::UnsupportedSvg.new(elements: document.unsupported, source: name)
-      end
+      svg_warnings(document, name)
       node = Layout::Svg.new(document, width:, height:, color:, context: @_builder.context, alt:)
       @_builder.add(align ? Layout::Flow.new([node], align:) : node)
     end
@@ -154,6 +152,16 @@ module Stationery
 
     private
 
+    # What the drawing uses that is not drawn, and nesting that was flattened.
+    def svg_warnings(document, name)
+      if document.unsupported.any?
+        @_builder.warnings << Warnings::UnsupportedSvg.new(elements: document.unsupported, source: name)
+      end
+      return unless document.nesting
+
+      @_builder.warnings << Warnings::NestingLimit.new(depth: document.nesting, limit: SVG::Parser::MAX_DEPTH)
+    end
+
     # `bookmark:` is a title, or { title:, level:, open: }.
     def mark(node, anchor, bookmark)
       names = [anchor&.to_s]

data/lib/stationery/fonts/font.rb

@@ -33,9 +33,10 @@ module Stationery
         @pairs = {}
         @glyphs = {}
         @blanks = {}
-        @shapes = {}
-        @advances = {}
-        @kerns = {}
+        @shapes = {}.compare_by_identity
+        @metrics = {}.compare_by_identity
+        @keys = { true => {}, false => {} }
+        @frozen_keys = { true => {}.compare_by_identity, false => {}.compare_by_identity }
         @cid_keyed = ttf.cff? && ttf.cff.cid_keyed?
       end
 
@@ -49,10 +50,12 @@ module Stationery
       def width_of(text, size, letter_spacing: 0, kerning: false, ligatures: true, features: NO_FEATURES)
         ligatures &&= letter_spacing.zero?
         key = shape_key(ligatures, features)
-        width = scale(advance_units(text, key), size) + (letter_spacing * shape(text, key).first.size)
+        advance, kern = metrics(text, key)
+        width = scale(advance, size)
+        width += letter_spacing * shape(text, key).first.size unless letter_spacing.zero?
         return width unless kerning
 
-        width + (kerning_units(text, key) * size / 1000.0)
+        width + (kern * size / 1000.0)
       end
 
       # The GSUB feature tags this font can apply.
@@ -126,14 +129,22 @@ module Stationery
       private
 
       # The feature tags to substitute with: `liga` when ligatures are on, plus
-      # the requested features. Frozen and shared, so it keys the memos cheaply.
+      # the requested features. One Array per set of tags, so the memos are
+      # keyed by its identity: measuring a word hashes the word and nothing
+      # else. A style's frozen tags are looked up by identity too; any other
+      # Array is normalised first.
       def shape_key(ligatures, features)
-        features = Text::Style.features(features) unless features.frozen? && features.all?(String)
-        return features unless ligatures
-        return Gsub::LIGA if features.empty?
+        return ligatures ? Gsub::LIGA : NO_FEATURES if features.empty?
 
-        @keys ||= {}
-        @keys[features] ||= (features + Gsub::LIGA).sort.freeze
+        ligatures = ligatures ? true : false
+        return @frozen_keys[ligatures][features] ||= tags_for(ligatures, features) if features.frozen?
+
+        tags_for(ligatures, features)
+      end
+
+      def tags_for(ligatures, features)
+        features = Text::Style.features(features)
+        @keys[ligatures][features] ||= (ligatures ? (features + Gsub::LIGA).sort : features).freeze
       end
 
       # [gids, source text of each glyph, extra advance in font units after
@@ -170,17 +181,16 @@ module Stationery
         width - space
       end
 
-      def advance_units(text, tags)
-        (@advances[tags] ||= {})[text] ||= begin
+      # [advance in font units, kerning in thousandths of an em] of a string,
+      # remembered together so a measurement is one lookup.
+      def metrics(text, tags)
+        (@metrics[tags] ||= {})[text] ||= begin
           gids, _, blanks = shape(text, tags)
-          gids.sum { |gid| @ttf.advance(gid) } + blanks.sum { |units| units || 0 }
+          [gids.sum { |gid| @ttf.advance(gid) } + blanks.sum { |units| units || 0 },
+           gids.each_cons(2).sum { |left, right| pair(left, right) }].freeze
         end
       end
 
-      def kerning_units(text, tags)
-        (@kerns[tags] ||= {})[text] ||= shape(text, tags).first.each_cons(2).sum { |left, right| pair(left, right) }
-      end
-
       # Kerning between two glyphs in thousandths of an em.
       def pair(left, right)
         @pairs[(left << 16) | right] ||= @ttf.kerning.adjust(left, right) * 1000.0 / @ttf.units_per_em