stationery 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '04892e3a1ad9e6da0174cb033f2a57a048c83c77e57e72aff4a98ccfa48e1ba7'
-  data.tar.gz: f9ee80ed8edd77108f3d6ae4f19f5a9d537000e6cf0e1efd8707e2682e89faac
+  metadata.gz: 41ce5a83b1405e6756b6b2238b4796d1c7331e82f1abb51df2747befa61dbc26
+  data.tar.gz: a1c9fab02c1ce65eb761c96084c81b72117aee45ac2c0db8c1326ce94651f7a4
 SHA512:
-  metadata.gz: d5c07272f2ff4480d35caa3decebc77336e12b3e8b7aea4f8ddd06f47529c12438a86606fb41350bf9d0eb59915e1cee13505acf75ef9e7544135ddd6878d5e6
-  data.tar.gz: 4901d1100e09107496cf9d83b6ac0c2a767aacc43090b1c5b87137c35667c3bd009adc8a5c627f09d50bfe1d46dc6172abaddb9dfe0cdfc9fe7426425471814b
+  metadata.gz: 9c1a85c89e74b002d14d6dd2aaa7153e34e746636ad6059b8db6a83f302b7058d4efb7430346463fc614ba0b61b7991226c44d724b62479d22ab5b1a007b419a
+  data.tar.gz: dfc30baf5b1803d38d7087eed1b24960fe79c3021f119b859d695458e128ed23baf74d961779b2bdb39f1071a0ed7cd09f51d1aa3881eb3076190f1a8d5a63b0

data/CHANGELOG.md

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

data/README.md

@@ -102,11 +102,12 @@ renders them all, or render one with `stationery render examples/report.rb`.
 | `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:, 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). |
+| `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,12 +139,59 @@ 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
@@ -154,9 +202,10 @@ process down:
   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.
+- **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
@@ -510,7 +559,8 @@ 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"
+       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
@@ -536,19 +586,31 @@ ContractPdf.new.to_pdf(sign: { certificate:, key:, passphrase: "…" }) # per re
   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.
+- `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: 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.
+- 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`;
+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.
@@ -570,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
@@ -759,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.
@@ -847,7 +927,8 @@ 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: }`), `signatures` (`[{ field:, name:, reason:, location:,
-signed_at:, subfilter:, byte_range:, signer:, valid: }]`), `warnings`, `tagged?`,
+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
@@ -858,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.
@@ -899,21 +983,43 @@ 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, 28 September 2026:
-
-| Document | Engine | Renders/s | Objects allocated | PDF bytes |
-|---|---|---:|---:|---:|
-| 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).
+`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
@@ -927,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.
 
@@ -936,8 +1043,10 @@ 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
@@ -946,7 +1055,7 @@ 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) 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
+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.

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

data/lib/stationery/document.rb

@@ -113,7 +113,8 @@ module Stationery
       # 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.
+      # signature is invisible. `timestamp:` is the URL of a time-stamping
+      # authority whose token makes it PAdES baseline B-T. See PDF::Signature.
       def sign(**options, &block)
         raise ArgumentError, "sign needs certificate: and key:, or a block answering them" unless block || options.any?
 
@@ -153,19 +154,28 @@ module Stationery
     def page_options = self.class.config[:page]
     def metadata = self.class.config[:metadata]
 
+    # The PDF as a binary String, also written to `target` when given: a
+    # path or an IO. With a block the file is streamed to it in pieces as it
+    # is written and the call answers the number of bytes: the first bytes
+    # leave before the last page is assembled and no output buffer is built.
+    # Layout runs in full first either way, so peak memory does not drop.
     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], sign: self.class.config[:sign])
+               factur_x: self.class.config[:factur_x], sign: self.class.config[:sign], &block)
       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:)
+      signature = PDF::Signature.for(sign, self)
+      raise ArgumentError, "a signed document cannot be streamed to a block: sign needs the whole file" if
+        signature && block
+      raise ArgumentError, "pass a target or a block, not both" if target && block
+
       options = { strict:, debug:, encrypt:, tagged: tagged || conformance&.pdf_ua?, page_labels:, attachments:,
-                  xmp: xmp || !conformance.nil?, conformance:, invoice:,
-                  signature: PDF::Signature.for(sign, self) }
+                  xmp: xmp || !conformance.nil?, conformance:, invoice:, signature:, sink: block }
       Stationery.instrument("render.stationery", document: self.class.name) do |event|
-        write(render_pdf(event, **options), target)
+        block ? render_pdf(event, **options) : write(render_pdf(event, **options), target)
       end
     end
 
@@ -208,22 +218,24 @@ module Stationery
       raise WarningsError, warnings if strict && warnings.any?
 
       pdf = assemble(pages, resources, outline, tagging:, conformance:, **assembly)
-      event[:bytes] = pdf.bytesize
+      event[:bytes] = byte_count(pdf)
       pdf
     end
 
     def assemble(pages, resources, outline, encrypt:, tagging:, page_labels:, attachments:, xmp:, conformance:,
-                 invoice:, signature:)
+                 invoice:, signature:, sink:)
       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, signature:)
+                                     xmp_schemas: [invoice&.xmp_schema].compact, signature:, sink:)
       Stationery.instrument("write.stationery", document: self.class.name) do |event|
-        assembler.render.tap { |pdf| event[:bytes] = pdf.bytesize }
+        assembler.render.tap { |pdf| event[:bytes] = byte_count(pdf) }
       end
     end
 
+    def byte_count(pdf) = pdf.is_a?(String) ? pdf.bytesize : pdf
+
     def paginate(root, book:, resources:, warnings:, debug:, tagging:)
       Stationery.instrument("paginate.stationery", document: self.class.name) do |event|
         regions = Regions.new(self.class.config[:regions], measure: region_measure(book))

data/lib/stationery/elements/rich.rb

@@ -10,10 +10,18 @@ module Stationery
     # `#anchor` always is); `:all` keeps every href for trusted sources.
     # 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.
+    # warning, so content from users cannot exhaust the stack. `<style>`
+    # rules and inline styles are read for the properties HTML::Css knows;
+    # the rest is reported once as an UnsupportedCss warning.
     def html(source, max_depth: 64, **)
       require_relative "../html/document"
-      rich(HTML.parse(source.to_s, max_depth:) { |depth| nesting_limit(depth, max_depth) }, **)
+      css = HTML::Css::Report.new
+      blocks = HTML.parse(source.to_s, max_depth:, css:) { |depth| nesting_limit(depth, max_depth) }
+      if css.any?
+        @_builder.warnings << Warnings::UnsupportedCss.new(properties: css.properties,
+                                                           selectors: css.selectors)
+      end
+      rich(blocks, **)
     end
 
     # CommonMark (plus GFM tables and strikethrough); options as for html.

data/lib/stationery/elements.rb

@@ -3,18 +3,21 @@
 module Stationery
   # The element DSL available inside every component's view_template.
   module Elements
-    PARAGRAPH_DEFAULTS = { align: :left, leading: 0 }.freeze
+    PARAGRAPH_DEFAULTS = { align: :left, leading: 0, orphans: 1, widows: 1 }.freeze
 
     # A paragraph. Plain strings are always literal; pass `markup: true` to
     # read inline tags, or a block to build styled runs in Ruby. `heading: 1..6`
-    # tags it as a heading in a tagged PDF.
+    # tags it as a heading in a tagged PDF. `orphans:` and `widows:` are the
+    # fewest lines a page break may leave behind and carry over (default 1).
     def text(content = nil, markup: false, keep_with_next: nil, break_inside: nil, anchor: nil, bookmark: nil,
              heading: nil, **options, &)
-      settings = PARAGRAPH_DEFAULTS.merge(@_builder.text_defaults.slice(:align, :leading)).merge(options)
+      settings = PARAGRAPH_DEFAULTS.merge(@_builder.text_defaults.slice(:align, :leading, :orphans, :widows))
+                                   .merge(options)
       style = @_builder.style(options)
       runs = text_runs(content, style, markup, &)
       node = Layout::Text.new(runs, context: @_builder.context(style), align: settings[:align],
-                                    leading: settings[:leading], tag: Tagging::Element.new(Tagging.heading(heading)))
+                                    leading: settings[:leading], orphans: settings[:orphans], widows: settings[:widows],
+                                    tag: Tagging::Element.new(Tagging.heading(heading)))
       node.keep_with_next = keep_with_next
       node.break_inside = break_inside
       @_builder.add(mark(node, anchor, bookmark))
@@ -183,10 +186,12 @@ module Stationery
       end
     end
 
+    # A Hash is a cell with options: `{ content:, background:, borders:, padding:, … }`.
     def cell_content(content)
       case content
       when Proc then container(&content)
       when Component then container { render content }
+      when Hash then content.merge(content: cell_content(content[:content]))
       else content
       end
     end

data/lib/stationery/errors.rb

@@ -21,6 +21,10 @@ module Stationery
     end
   end
 
+  # Raised when a signature cannot be made as asked: the time-stamping
+  # authority is unreachable, refuses, or answers for something else.
+  class SignatureError < Error; end
+
   # Raised when a render cannot keep the conformance it claims (PDF/A,
   # PDF/UA): `levels` are the claimed levels, `issues` what breaks them.
   class ConformanceError < Error

data/lib/stationery/fonts/fallback.rb

@@ -12,7 +12,7 @@ module Stationery
     # stay with their base; whitespace a font lacks draws as a blank of the
     # right width (see Font::WHITESPACE).
     class Fallback
-      CARRIED = /[\p{Space}­‌‍︀-️\p{M}]/
+      CARRIED = /[\p{Space}­​‌‍︀-️\p{M}]/
 
       def self.carried?(char) = CARRIED.match?(char)