stationery 0.12.1 → 0.12.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab0f207d1a92bc13494a61e91f50d1af6df807978f878f4cf613536d96f072b6
-  data.tar.gz: feb1a51466ae5020b1afcc0f5e7be4fd0389c8217e14b06d18044f61a5f5e67b
+  metadata.gz: 43646ec58820f24924dfbcaaf0bdd8170d5251699f8a0e052560b03dde2d343a
+  data.tar.gz: 651b72e03ce4cd1d31cf713e729b58024bc9145fe7d3c31ea3732e87436771ae
 SHA512:
-  metadata.gz: 2707d1a55f7bef5d7f22a6a6117b45bb5f73c41641da1ae9786b37c463ff68323c24ec75d5cf3ab88274b5b8d600cde5fe49d456f776a29afdbf152624d15a28
-  data.tar.gz: f6954e7b30c7e211c0d9f83055b9cdac5cb628773c8aba34ec38fce37ba0bb39ac958e0a245fb840200be0da43722175ecb3615a48278958b300aa562fb91a6a
+  metadata.gz: daf443749aecd4818744fc05248a138b65b14226e318bf5877ff14618b34255b45f5ce1126562aee70722386f83544502bd8769edc5125809d3add8904003146
+  data.tar.gz: 72fc71f0732f1e9b202eb5a48cfedf47cf499808bb150dffb67a88f425e200f4bbd6b038aab2e89ab280e0cf9594b2d6e2045de85b27ef3e8c02eee332d4d15b

data/CHANGELOG.md

@@ -2,7 +2,11 @@
 
 ## Unreleased
 
+- Text fields and selects take `font_size: :fit` (#218): the size `font_size: :auto` draws (one line, a `comb:` field's cells or a `multiline:` value, within `min_font_size:` and `max_font_size:`), written in `/DA` as that number instead of `0`, so a viewer that redraws the field keeps the size; Firefox's editable input, which showed `:auto` at 9 px, now shows the number, capped at the field's height ÷ 1.35 and set in the browser's own face. A longer value typed afterwards does not shrink, and an empty field is written at its largest size, so a field left empty to be filled in wants `:auto`. A field placed in several places writes its first widget's size. `Inspector#layout` and `stationery inspect` report the number. `text_field "price", value: "4 990 kr", font_size: :fit, max_font_size: 96, height: 110`. The price card example uses it. A field that does not is written as it was. `Forms::Field`, `Forms::Appearance`.
+- Text fields and selects take `align:`, `color:` and `font_size: :auto` (#216): `align:` (`:left`, `:center`, `:right`) is written as `/Q`, `color:` (any colour the gem takes, black by default) as the colour operator of `/DA`, and `font_size: :auto` as `0 Tf`, within `min_font_size:` (4 by default) and `max_font_size:` (the field's height by default). The gem's own appearance aligns, colours and sizes the value the same way, so a field looks the same before and after a viewer redraws it: one line at the largest tenth of a point that fits the field's height and width, a `comb:` field's widest character in its cell, a `multiline:` value wrapped to the width and fitted to the height. `comb:` ignores `align:`. `text_field "price", value: "4 990 kr", align: :center, color: "#DC2626", font_size: :auto, height: 110`. A field that uses none of them is written as it was. Under `monochrome` a `color:` is checked like any other colour (`Warnings::NotMonochrome`, or black with `snap: true`); `Inspector#layout` and `stationery inspect` report a text field's or choice's `align:`, `font_size:` and `color:`. A price card example (`examples/price_card.rb`). `Forms::Field`, `Forms::Appearance`, `Forms::AutoSize`, `Testing::Layout`. **Behaviour change:** under PDF/A, a CMYK colour in a form field's appearance or `/DA` is reported as `Warnings::ConformanceIssue` (`CMYK colour in form field "price"`), its `border:` and `background:` included, which were not checked before.
+- The skill (`stationery skill install`) and the README it is written from are corrected (#209): the `max_pages` example renders before it reads `warnings`; a preview reads `params.fetch("id") { … }`, so its default is not looked up when `id` is given; the streamed-table example preloads what its rows read; the invoice recipe computes VAT with `Rational`, not Float, and says when a document may derive its totals; the report recipe escapes the chart labels it writes into SVG (`ERB::Util.html_escape`); the form recipe gives its fields a `tooltip:` and says a field without one is announced by its field name; the label recipe sizes a native QR code by the printer's dpi (a module of at most 720 / dpi points) and says what a barcode left in the picture loses. Statements that overstated are qualified: `encrypt` under a conformance level raises `ArgumentError`, not `ConformanceError`; `NeedAppearances` is left out under a conformance level or a signature; what the untrusted-input guarantees cover; and what a B-T timestamp proves once the certificate has expired. Run `stationery skill install` again to update an installed copy.
 - A tagged render is written with object streams (#206): its structure elements, and every other object that is not a stream, are packed 200 to a deflated `/Type /ObjStm`, with a cross-reference stream in place of the table and trailer (ISO 32000-1, 7.5.7 and 7.5.8). A table of 300 rows, 8 pages, is 115 KB tagged where it was 501 KB, 36 objects where it was 4,544; the tagged examples are 9 to 65% smaller. It is on by default for a render that is tagged (`tagged`, `to_pdf(tagged: true)`, `conformance :pdf_ua1`), and `object_streams false` at class level or `to_pdf(object_streams: false)` writes the classic table for a reader that cannot read object streams; `to_pdf(object_streams: true)` packs an untagged render too. Streams, the `/Encrypt` dictionary and a signature's dictionary stay out, so an encrypted, a signed and an incremental render are packed too, and PDF/A-2b, PDF/A-3b and PDF/UA-1 pass veraPDF packed. `to_png` and `to_zpl` refuse `object_streams:` as a PDF option. `Document#page_count` is how many pages the last render laid out, which `stationery render` now reports. In `PDF::Writer` (`object_streams:`, `add_unpacked`) and `PDF::ObjectStreams`.
+- `stationery verify` checks PDFs in the engines viewers are built on (#210): qpdf (the file's structure), Poppler (Evince, Okular), MuPDF, PDFium (Chrome, Edge), pdf.js (Firefox) and PDFKit (Preview, Safari). Each engine reads the file and what it reads is held against what pdf-reader reads of it: the page count, each page's text lines (found, not compared: NFKC, no whitespace, no soft hyphens, a list item's marker may be read apart, as a column of markers), that a page with text or an image paints something, links and their targets, outline titles, form fields with their values and appearances, attachments, signatures (and `pdfsig`'s verdict), a tagged file's structure tree, and every font embedded with a ToUnicode map. Any error or warning an engine gives fails the check, but for the three messages `Stationery::Verify::Allowlist` names with why each is the check's environment and not the file. `stationery verify invoice.pdf report.rb --engines qpdf,pdfjs --password P --json` renders a Ruby file first, as `inspect` does, runs every engine installed without `--engines`, and exits 0, 1 or 2 (usage); it prints one line per file and engine, the problems under it, and the engines not installed with the line that installs each. The engines are tools you install (`brew install qpdf poppler mupdf`, `pip install pypdfium2`, `npm i pdfjs-dist`; PDFKit on macOS), or run in the image `ghcr.io/zoolutions/stationery-verify`, published with each release, which has every engine but PDFKit: `docker run --rm -v "$PWD:/data:ro" ghcr.io/zoolutions/stationery-verify /data/invoice.pdf`. The gem gains no dependency: `stationery verify` needs `pdf-reader`, as `inspect` does, and `require "stationery"` does not load it, so a render allocates and writes what it did. `bundle exec rake verify:readers` renders every example, the conformance renders, an encrypted invoice, a packed invoice and an unpacked tagged report to `tmp/readers/` and checks them; CI runs it through the image on Linux and with qpdf, Poppler, MuPDF and PDFKit on macOS. `Testing::Inspector.new(subject, password:)` opens an encrypted file. `Stationery::Verify`, `Stationery::CLI::Verify`.
 - **Behaviour changes:** a tagged render is packed: its catalog, pages, annotations and structure elements are inside deflated object streams, so a test or tool that searches the file's bytes for them (`/StructParent`, `/Type /Page`) finds nothing (`document.page_count` has the pages), and the file ends in a cross-reference stream, not `xref` and `trailer`. A reader of PDF 1.4 and earlier cannot open it; `object_streams: false` writes it as 0.12.0 did, byte for byte. A tagged render streamed to a block is a few bytes longer than the String, as each flush closes an object stream. Untagged documents are byte for byte what they were in 0.12.0.
 
 ## 0.12.0 (2026-09-29)

data/README.md

@@ -96,7 +96,7 @@ 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, shipping label, fillable form, postcard collage, magazine article, event flyer, two-column newsletter and Factur-X e-invoice,
 and one per thing people build: a 2,000-row price list written `incremental`, a contract with initials
 on every page and signature fields, a landscape certificate, a two-column résumé with its body in HTML,
-a restaurant menu in `columns` with floats, a till receipt on an 80 mm roll, a PDF/UA-1 accessible report and a notice in English, German
+a restaurant menu in `columns` with floats, a till receipt on an 80 mm roll, a shop-window price card whose fields centre, colour and size their values, a PDF/UA-1 accessible report and a notice in English, German
 and Swedish, each hyphenated in its language
 ([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`.
@@ -139,10 +139,10 @@ ls "$(bundle show stationery)/examples"      # or: gem contents stationery
 | `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:, tooltip:, 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:, min_font_size:, max_font_size:, align:, color:, border:, background:, radius:, tooltip:, at:)` | An interactive text input (AcroForm). `width:` is `:full` or points; `font_size:` is points, `:auto` or `:fit`; `align:` is `:left`, `:center` or `:right`; 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. |
+| `select(name, options:, value:, width:, height:, editable:, font_size:, min_font_size:, max_font_size:, align:, color:, 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:, 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). |
@@ -305,8 +305,9 @@ 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:
+ActionText field). Nothing in that content can reach outside the document, and parsing it is
+bounded: nesting is capped and time grows with the input's length. How much input you accept,
+and so how many pages it renders to, is yours to bound:
 
 - **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`).
@@ -385,6 +386,7 @@ text_field "applicant.name", value: @applicant.name, required: true
 text_field "applicant.notes", multiline: true, height: 60
 text_field "applicant.pin", comb: 6                      # six cells; sets max_length
 select "applicant.country", options: %w[Sweden Norway Denmark], value: "Sweden"
+text_field "price", value: "4 990 kr", align: :center, color: "#DC2626", font_size: :auto, height: 110
 radio "plan", "basic", label: "Basic"                    # radios sharing a name form one group
 radio "plan", "pro", checked: true, label: "Pro"
 checkbox "terms", checked: false, label: "I accept the terms"
@@ -396,9 +398,10 @@ signature_field "signature", label: "Signature of the applicant"
   applied per character, so a value in any script the fonts cover is drawn (`/V` holds it as
   Unicode). A character no font has is drawn as `.notdef` inside a `Span` whose `ActualText` is the
   character, as in any other text (or as the font's stand-in under `conformance` with
-  `missing_glyphs: :replace`), so the appearance still extracts as written. 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.
+  `missing_glyphs: :replace`), so the appearance still extracts as written. Check marks and radio
+  dots are paths. `NeedAppearances` is set too, so viewers redraw edited values, except under a
+  conformance level or a signature, which leave it out; 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
@@ -408,9 +411,23 @@ signature_field "signature", label: "Signature of the applicant"
 - 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.
+- `align:` (`:left`, `:center`, `:right`), `color:` and `font_size: :auto` style a text field's or a
+  select's value, both in the file and in the appearance, so the field looks the same before and
+  after a viewer redraws it: `align:` is written as `/Q` and the value is placed within the box less
+  its padding; `color:` (any colour the gem takes, black by default) is the colour operator of `/DA`;
+  `font_size: :auto` writes `0 Tf` and the appearance draws the largest size, in tenths of a point,
+  at which one line fits the field's height and width (a `comb:` field's cells; a `multiline:`
+  field wrapped to its width and height), within `min_font_size:` (4 by default) and
+  `max_font_size:` (the height by default). `font_size: :fit` sizes the value the same way and writes
+  the number it chose in `/DA`, so every viewer reads a size, where `0 Tf` showed 9 px in Firefox's
+  editable input (which still caps a size at the field's height ÷ 1.35 and sets it in its own face).
+  A longer value typed afterwards does not shrink, and an empty field is sized to its bound, so a
+  field left empty to be filled in wants `:auto`. `min_font_size:` and `max_font_size:` go with
+  either. A `comb:` field ignores `align:`, its cells place each character. Under `monochrome`, `color:` is checked like any other colour; under PDF/A a CMYK one
+  is reported. A field that uses none of them is written as it was.
 - 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, unless `sign field:` signs it (see [Digital signatures](#digital-signatures)).
+  signer, unless `sign` names it with `field:` (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.
 - In tests, `document.fields` is what the form was filled with, and `have_pdf_text("Astrid", fields:
@@ -495,6 +512,8 @@ render Callout.new(color: "#F3F4F6") { text "Amount due" }
     max_pages 1
   end
 
+  label = ShippingLabel.new
+  label.to_pdf                              # warnings are there after a render
   label.warnings.map(&:message)
   # => ["the document may have 1 page and needs 2: page 2 starts with a Code 128 barcode"]
   ```
@@ -993,6 +1012,66 @@ docker run --rm -v "$PWD:/data:ro" verapdf/cli --format text -v --flavour 3b /da
 
 In tests, `have_conformance(:pdf_a3b)` checks the claim (not the validity: that is veraPDF's job).
 
+### Viewers: stationery verify
+
+veraPDF answers whether a file keeps PDF/A or PDF/UA, not whether it works where people open it.
+A file can pass PDF/A-3b and still trip a viewer, and open everywhere and still fail PDF/A. No
+validator answers "works in every viewer", so `stationery verify` reads the file with the engines
+the viewers are built on and holds what each reads against what the file holds, as pdf-reader
+reads it (`stationery verify` needs the `pdf-reader` gem, as `inspect` does):
+
+| Engine | Viewers | Checks |
+|---|---|---|
+| qpdf | (the file's structure) | `--check` without an error or a warning; the page count |
+| Poppler | Evince, Okular, the Linux desktop | pages; text; each page with content paints; every font embedded, with a ToUnicode map; attachments; signatures (`pdfsig`); a tagged file's structure tree |
+| MuPDF | SumatraPDF, mobile viewers | pages; text; each page with content paints |
+| PDFium | Chrome, Edge | pages; text; painting; links; outline; form fields and their appearances; signatures |
+| pdf.js | Firefox | pages; text; painting operators; links; outline; form fields; attachments; a tagged file's structure tree |
+| PDFKit | Preview, Safari (macOS) | pages; text; painting; links; outline; form fields |
+
+Any error or warning from any engine fails the check. Text is found, not compared: both sides lose
+their whitespace and soft hyphens and are NFKC-normalized, and each text line of a page must be in
+what the engine reads of it, whole; a list's item may have its marker read apart, as a column of
+markers before the items, since the page draws them apart. A page drawn blank on purpose passes;
+one with text or an image that an engine paints all white fails. The few messages that are the
+check's environment and not the file (pdf.js warns it has no OffscreenCanvas in Node, pdfsig that
+the machine has no certificate store, Debian's mutool that it was built without colour management)
+are listed with why in `Stationery::Verify::Allowlist`.
+
+```sh
+stationery verify invoice.pdf report.pdf                 # every engine installed
+stationery verify invoice.rb                             # render it first
+stationery verify invoice.pdf --engines qpdf,poppler     # these, and fail if one is missing
+stationery verify locked.pdf --password 1234 --json
+```
+
+It exits 0 when every engine passes every file, 1 otherwise (or when no engine is installed), 2 on
+a usage error, and prints one line per file and engine, the problems under it, then the engines not
+installed with the line that installs each. The engines are tools you install; the gem depends on
+none of them:
+
+```sh
+brew install qpdf poppler mupdf        # apt-get install qpdf poppler-utils mupdf-tools
+pip install pypdfium2                  # Python 3.11+; STATIONERY_PYTHON=/path/to/python names another
+npm i pdfjs-dist                       # STATIONERY_PDFJS=/path/to/node_modules/pdfjs-dist
+```
+
+PDFKit needs macOS and Swift (`xcode-select --install`). Poppler and MuPDF take `--password` on
+their command lines, where other processes of the machine can see it; qpdf reads it from a file and
+the scripted engines from the environment. pdfsig takes no password, so an encrypted file's
+signatures are not read by Poppler. A Docker image has every engine but PDFKit:
+
+```sh
+docker run --rm -v "$PWD:/data:ro" ghcr.io/zoolutions/stationery-verify /data/invoice.pdf
+```
+
+`bundle exec rake verify:readers` renders every example, the renders `verify:conformance`
+validates, an encrypted invoice, an invoice packed with object streams and a tagged report without
+them to `tmp/readers/`, and checks them (`ENGINES=qpdf,pdfkit` to choose). CI checks them with the
+image on Linux and with qpdf, Poppler, MuPDF and PDFKit on macOS. Adobe Acrobat cannot be driven
+in CI: before a release, the maintainer opens a fixed set of them in Acrobat Reader on macOS and
+Windows (see `AGENTS.md`).
+
 ### Factur-X / ZUGFeRD e-invoices
 
 A Factur-X (in Germany: ZUGFeRD) invoice is one PDF that people read and accounting software
@@ -1072,9 +1151,10 @@ ContractPdf.new.to_pdf(sign: { certificate:, key:, passphrase: "…" }) # per re
   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
+  attributes: PAdES baseline B-T. The token proves when the signature existed, by a clock other
+  than the signer's. Whether a viewer still accepts the signature once the signer's certificate
+  has expired depends on its trust settings and on revocation data (B-LT), which the file does
+  not carry. 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
@@ -1196,7 +1276,8 @@ reach them, and holds the rows of the page being filled and the one after them,
 its first page:
 
 ```ruby
-rows = [%w[Order Customer Total]].each + Order.find_each.lazy.map { |o| [o.number, o.customer, o.total] }
+orders = Order.preload(:customer).find_each.lazy.map { |o| [o.number, o.customer.name, o.total] }
+rows = [%w[Order Customer Total]].each + orders
 table(rows, header: true, widths: [80, 0.5, 90]) do |t|
   t.row(0).weight = :bold
   t.columns(2).align = :right
@@ -1265,7 +1346,7 @@ document.
 # spec/pdfs/previews/invoice_pdf_preview.rb
 class InvoicePdfPreview < Stationery::Preview
   def paid = InvoicePdf.new(Invoice.paid.first)
-  def overdue(params) = InvoicePdf.new(Invoice.find(params.fetch("id", Invoice.overdue.first.id)))
+  def overdue(params) = InvoicePdf.new(Invoice.find(params.fetch("id") { Invoice.overdue.first.id }))
 end
 ```
 
@@ -1350,6 +1431,16 @@ Page 1  595.3 x 841.9 pt
      329.2  596.5  65.6 x 11.6  mailto:hello@acme.test
 ```
 
+```sh
+stationery verify invoice.pdf                            # in every engine installed
+stationery verify invoice.rb --engines qpdf,pdfjs --json
+```
+
+`verify` reads PDFs, or the documents Ruby files define, with the engines
+viewers are built on (qpdf, Poppler, MuPDF, PDFium, pdf.js, PDFKit) and fails
+when one of them errs, warns or reads something the file does not hold. See
+[Viewers](#viewers-stationery-verify).
+
 ```sh
 stationery fonts list                                    # packs, licenses, what is in vendor/fonts
 stationery fonts install noto_sans liberation_serif      # into vendor/fonts/<pack>/
@@ -1794,8 +1885,9 @@ A text line is a run of one font and size on one baseline, so a word set in bold
 own; lines read top to bottom, then left to right. An image is `{ x:, y:, width:, height:, pixels:
 [w, h] }` in the order drawn (the rectangle it fills, before any clip); a link has its `uri:`, or the
 `page:` and `top:` it goes to; a field has its full `name:`, `type:` (`:text`, `:choice`,
-`:checkbox`, `:radio`, `:button`, `:signature`), `value:` and, for a button, the `state:` that turns
-it on. `outline` is the bookmarks as `{ title:, page:, top:, children: }`. `metadata` leaves out the
+`:checkbox`, `:radio`, `:button`, `:signature`), `value:`, for a button the `state:` that turns
+it on, and for a text field or a choice the `align:`, `font_size:` (`:auto` for `0 Tf`, the number for `:fit`) and `color:`
+(`"#RRGGBB"`) its value is drawn in. `outline` is the bookmarks as `{ title:, page:, top:, children: }`. `metadata` leaves out the
 dates, which change with every render, so two renders of one document have the same layout.
 `warnings` are the render's messages when the subject is a document.
 

data/examples/price_card.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# A shop-window price card a person fills in on screen and prints: the
+# product's name centred and shrunk to fit its line, the price large,
+# centred and red, the price per unit right-aligned in grey and a select of
+# units. The name and price are fitted by the gem and the size it chose is
+# written to the file (`font_size: :fit`), so every viewer shows them at
+# that size. The fields have no border and no background, so the printed
+# card shows the values alone; a viewer that redraws a field after an edit
+# keeps its alignment, colour and size (/Q and /DA). Run it to write
+# examples/price_card.pdf:
+#
+#   ruby -Ilib examples/price_card.rb
+#   ruby -Ilib exe/stationery render examples/price_card.rb
+require "stationery"
+
+class ExamplePriceCard < Stationery::Document
+  INK = "#0F172A"
+  SALE = "#DC2626"
+  MUTED = "#64748B"
+  HAIRLINE = "#E2E8F0"
+  UNITS = ["per piece", "per kg", "per litre", "per pack"].freeze
+  BARE = { border: nil, background: nil }.freeze
+
+  page size: :a5, layout: :landscape, margin: 36
+  default_text size: 12, color: INK
+  metadata title: "Price card", author: "Corner Coffee Shop", creator: "stationery example", lang: "en"
+
+  footer do
+    rule height: 0.5, color: HAIRLINE
+    spacer 6
+    text "All prices include 25% VAT · Corner Coffee Shop, Stortorget 4, Lund", size: 8, color: MUTED,
+                                                                                align: :center
+  end
+
+  def self.preview
+    new(product: "Espresso machine Deluxe 3000 with milk frother", price: "4 990 kr",
+        unit_price: "Was 5 990 kr · save 1 000 kr", unit: "per piece")
+  end
+
+  def initialize(product: "", price: "", unit_price: "", unit: UNITS.first)
+    super()
+    @product = product
+    @price = price
+    @unit_price = unit_price
+    @unit = unit
+  end
+
+  def view_template
+    text "Corner Coffee Shop", size: 16, weight: :bold, align: :center
+    spacer 4
+    rule height: 1.5, color: INK
+    spacer 10
+    label "Product"
+    text_style(weight: :bold) do
+      text_field "product", value: @product, height: 44, font_size: :fit, max_font_size: 32, align: :center,
+                            tooltip: "Product", **BARE
+    end
+    rule height: 0.5, color: HAIRLINE
+    spacer 10
+    label "Price"
+    text_style(weight: :bold) do
+      text_field "price", value: @price, height: 150, font_size: :fit, max_font_size: 120, align: :center,
+                          color: SALE, tooltip: "Price", **BARE
+    end
+    spacer 6
+    row(gap: 12) do
+      column(width: 150) do
+        select "unit", options: UNITS, value: @unit, height: 22, align: :center, tooltip: "Unit", **BARE
+      end
+      column do
+        text_field "note", value: @unit_price, height: 22, align: :right, color: MUTED, tooltip: "Note", **BARE
+      end
+    end
+  end
+
+  private
+
+  def label(title) = text(title.upcase, size: 8, color: MUTED, letter_spacing: 1, align: :center)
+end
+
+if $PROGRAM_NAME == __FILE__
+  card = ExamplePriceCard.preview
+  card.to_pdf(File.expand_path("price_card.pdf", __dir__))
+  warn card.warnings.map(&:message) if card.warnings.any?
+  puts "wrote examples/price_card.pdf"
+end

data/lib/stationery/cli/layout_text.rb

@@ -53,7 +53,7 @@ module Stationery
            "#{box(image)}  #{image[:pixels].join(" x ")} px"
          end,
          *section("Links (x, y, width x height, target)", page[:links]) { |link| "#{box(link)}  #{target(link)}" },
-         *section("Fields (x, y, width x height, name, type, value)", page[:fields]) do |field|
+         *section("Fields (x, y, width x height, name, type, value, alignment, size, colour)", page[:fields]) do |field|
            "#{box(field)}  #{field_text(field)}"
          end]
       end
@@ -84,7 +84,19 @@ module Stationery
 
       def field_text(field)
         value = field[:value].is_a?(Array) ? field[:value].inspect : field[:value]&.inspect
-        [field[:name], field[:type], field[:state] && "on: #{field[:state]}", value].compact.join("  ")
+        [field[:name], field[:type], field[:state] && "on: #{field[:state]}", value, *style(field)].compact.join("  ")
+      end
+
+      # What is not the default of a field's alignment, size and colour.
+      def style(field)
+        return [] unless field.key?(:align)
+
+        size = field[:font_size]
+        [field[:align] == :left ? nil : field[:align],
+         if size == :auto then "auto"
+         elsif size != Forms::Field::DEFAULTS[:font_size] then "#{number(size)} pt"
+         end,
+         field[:color] == "#000000" ? nil : field[:color]]
       end
 
       def structure

data/lib/stationery/cli/verify.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "json"
+require "tmpdir"
+
+module Stationery
+  class CLI
+    # `stationery verify FILE…`: reads each PDF in the engines viewers are
+    # built on (Stationery::Verify) and fails when any of them errs, warns
+    # or reads something other than the file holds. A Ruby file is rendered
+    # first, as `render` finds its document. Needs the pdf-reader gem, and
+    # at least one engine installed.
+    class Verify < Render
+      SUMMARY = "Check PDFs (or the documents Ruby files define) in the engines viewers are built on"
+
+      def run(argv)
+        parser.parse!(argv)
+        return OK if @options[:help]
+        raise OptionParser::MissingArgument, "FILE" if argv.empty?
+
+        require "stationery/verify"
+        verify(argv, engines)
+      rescue OptionParser::ParseError => e
+        @err.puts "stationery verify: #{e.message}", parser
+        USAGE
+      end
+
+      private
+
+      def parser
+        @parser ||= OptionParser.new do |opts|
+          opts.banner = "Usage: stationery verify FILE… [options]   (each FILE a .pdf, or a .rb defining a document)"
+          opts.on("--engines LIST", Array, "The engines to run (default: every one installed): " \
+                                           "#{%w[qpdf poppler mupdf pdfium pdfjs pdfkit].join(",")}") do |names|
+            @options[:engines] = names
+          end
+          opts.on("--password PASSWORD", "The user password of encrypted files (other local processes can see",
+                  "it on the command lines of Poppler and MuPDF)") { |password| @options[:password] = password }
+          opts.on("--json", "Print the report as JSON") { @options[:json] = true }
+          opts.on("-c", "--class NAME", "The document class to render when a Ruby FILE defines several") do |name|
+            @options[:class] = name
+          end
+          opts.on("-h", "--help", "Show this help") do
+            @out.puts opts
+            @options[:help] = true
+          end
+        end
+      end
+
+      def engines
+        Stationery::Verify.adapters(*[@options[:engines]].compact)
+      rescue ArgumentError => e
+        raise OptionParser::InvalidArgument, e.message
+      end
+
+      def verify(files, engines)
+        installed!(engines)
+        Dir.mktmpdir("stationery-verify") do |dir|
+          labels = files.to_h { |file| [pdf(file, dir), file] }
+          report = Stationery::Verify.run(labels.keys, engines:, password: @options[:password])
+          report = report.with(results: report.results.map { |result| result.with(file: labels.fetch(result.file)) })
+          @out.puts(@options[:json] ? JSON.pretty_generate(report.to_h) : report.lines)
+          report.passed? ? OK : FAILURE
+        end
+      rescue Stationery::Error => e
+        raise Error, e.message
+      end
+
+      def installed!(engines)
+        missing = engines.reject(&:available?)
+        return if missing.empty? || (!@options[:engines] && missing.size < engines.size)
+
+        installs = missing.map { |engine| "#{engine.name} (#{engine.install})" }.join(", ")
+        raise Error, "not installed: #{installs}" if @options[:engines]
+
+        raise Error, "no engine is installed; install one of: #{installs}"
+      end
+
+      # The PDF to read for FILE: itself, or the render of the document a
+      # Ruby FILE defines, written into `dir`.
+      def pdf(file, dir)
+        path = File.expand_path(file)
+        raise Error, "no such file: #{file}" unless File.file?(path)
+        return render_into(path, dir) if File.extname(path) == ".rb"
+        raise Error, "not a PDF or a Ruby file: #{file}" unless File.binread(path, 5) == "%PDF-"
+
+        path
+      end
+
+      def render_into(path, dir)
+        document = instantiate(pick(load_documents(path), path))
+        File.join(Dir.mktmpdir(nil, dir), "#{File.basename(path, ".rb")}.pdf").tap { |target| document.to_pdf(target) }
+      end
+    end
+
+    register "verify", Verify
+  end
+end

data/lib/stationery/cli.rb

@@ -77,3 +77,4 @@ require_relative "cli/examples"
 require_relative "cli/layout_text"
 require_relative "cli/inspect"
 require_relative "cli/skill"
+require_relative "cli/verify"

data/lib/stationery/elements/forms.rb

@@ -9,7 +9,9 @@ module Stationery
   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:`.
+    # `required:`, `font_size:` (points, or :auto or :fit with `min_font_size:`
+    # and `max_font_size:`), `align:` (:left, :center, :right), `color:`,
+    # `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, typeface: field_typeface, **), width:, height:, at:)
     end
@@ -28,7 +30,7 @@ module Stationery
     end
 
     # A drop-down (combo box) of `options`; `editable: true` also accepts
-    # typed values.
+    # typed values. `font_size:`, `align:` and `color:` as a text field's.
     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),
                                               typeface: field_typeface, **)

data/lib/stationery/forms/appearance.rb

@@ -16,14 +16,21 @@ module Stationery
       # The check mark's corners in the unit square (y down) and its stroke.
       CHECK = { points: [[0.22, 0.52], [0.42, 0.72], [0.78, 0.28]], stroke: 0.12 }.freeze
       DOT = 0.45
+      # What /DA and the appearance say when the value is black.
+      BLACK = "0 g"
       SIGNATURE = { rule: 14, label_size: 7, label_baseline: 4, label_gray: 0.42 }.freeze
 
+      # The size the value is drawn at: the field's, or what `font_size:
+      # :auto` or `:fit` fits (see AutoSize).
+      attr_reader :size
+
       # `resources` are the render's, where the field's fonts get their names.
       def initialize(field, width, height, resources = nil)
         @field = field
         @width = width
         @height = height
         @type = field.typeface.with(resources)
+        @size = field.sized? ? AutoSize.new(field, @type, width, height).size : field.font_size
         @contents = contents
         keep
       end
@@ -34,14 +41,19 @@ module Stationery
       # The resource names of the fonts it draws with or keeps for editing.
       def font_names = @type.names
 
-      # What the field's /DA says: the font and size a viewer redraws the
-      # value with. nil for a field without variable text.
+      # What the field's /DA says: the font, size (0 for `:auto`, the fitted
+      # number for `:fit`) and colour a viewer redraws the value with. nil for
+      # a field without variable text.
       def default_appearance
         return unless @field.variable_text?
 
-        "/#{@type.name} #{num(@field.font_size)} Tf 0 g"
+        "/#{@type.name} #{@field.auto_size? ? 0 : num(size)} Tf #{text_color}"
       end
 
+      # What it paints: its content streams and its /DA, for a check of the
+      # colours they use (see PDF::Conformance).
+      def paints = [*(@contents.is_a?(Hash) ? @contents.values : @contents), default_appearance].compact
+
       # One stream, or a Hash of streams by appearance state for buttons.
       # `fonts` are the references by resource name.
       def streams(fonts)
@@ -54,7 +66,7 @@ module Stationery
       private
 
       def options = @field.options
-      def size = @field.font_size
+      def text_color = @field.color == Field::BLACK ? BLACK : @field.color.fill
       def num(value) = PDF::Serializer.number(value.is_a?(Float) && value == value.round ? value.round : value)
 
       def contents
@@ -98,29 +110,23 @@ module Stationery
         return comb_cells if options[:comb]
         return multiline_runs if options[:multiline]
 
-        [[PADDING, middle_baseline, @field.value.to_s]]
+        value = @field.value.to_s
+        [[start(value), middle_baseline, value]]
       end
 
       def multiline_runs
         top = @height - PADDING - @type.ascent(size)
-        wrap(@field.value.to_s, @width - (2 * PADDING)).each_with_index.map do |line, index|
-          [PADDING, top - (index * size * LEADING), line]
+        AutoSize.wrap(@type, @field.value.to_s, @width - (2 * PADDING), size).each_with_index.map do |line, index|
+          [start(line), top - (index * size * LEADING), line]
         end
       end
 
-      # The value broken into lines no wider than `width`, keeping its own
-      # line breaks; a word wider than a line stands alone.
-      def wrap(text, width)
-        text.split("\n", -1).flat_map do |paragraph|
-          paragraph.split.each_with_object([+""]) do |word, lines|
-            candidate = lines.last.empty? ? word : "#{lines.last} #{word}"
-            if lines.last.empty? || @type.width(candidate, size) <= width
-              lines[-1] = candidate
-            else
-              lines << word
-            end
-          end
-        end
+      # Where a line starts: aligned within the box less its padding, as a
+      # viewer does (PDF 32000-1, 12.7.3.3).
+      def start(line)
+        return PADDING if @field.align == :left
+
+        PADDING + Geometry.align_offset(@field.align, @width - (2 * PADDING), @type.width(line, size))
       end
 
       def comb_cells
@@ -131,7 +137,7 @@ module Stationery
       end
 
       def variable_text(runs)
-        ops = ["/Tx BMC", "q", "1 1 #{num(@width - 2)} #{num(@height - 2)} re W n", "0 g"]
+        ops = ["/Tx BMC", "q", "1 1 #{num(@width - 2)} #{num(@height - 2)} re W n", text_color]
         runs.reject { |_, _, text| text.empty? }.each do |x, y, text|
           ops.push("BT", "#{num(x)} #{num(y)} Td", *@type.show(text, size), "ET")
         end