stationery 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dc2011ee51b715eb946943e60d0512157f2215acd871133433c6edf4f81bb9a9
-  data.tar.gz: a5a9c654b4c415ab77ba005eb228ba67fae05f87af1adeb39871ccb3353a00a3
+  metadata.gz: bfd8cada05438bcc43cc85da2535da95b55c2dbf6020bf95607bd8ebb65c8346
+  data.tar.gz: 1115be789042eebfdd48a036fc433994694236c4c133ede893a554478b6174bf
 SHA512:
-  metadata.gz: 239ad178900f1cce55589e1e6882fda2e713631df0a0d732945eefd0d8df762e9baa0a44efde7ea13fa643e6ee0dd038594886cd09cc14aac2cb0486ef88f05b
-  data.tar.gz: 0ac757cdf6a15a654c83b26fa80c5be99e20e9e28e09653c31c299627a5c46c5cfb3965cfa58e58c2c6ade241c3b86f07fbe37a761ad2738e09207ce0711c200
+  metadata.gz: 2e55c39993d7c6c7c66373f5097a8796ac655b46eabe34eb148808cca220823112a728d4c26b971c54f163dc2b6c45f50f3b6481c050089871daf5964a4011d6
+  data.tar.gz: 456ca535dc230cbc747dac22322d7a0886ea8da7f70b159bb59224a2afe211dd1cb1a6e79a2a1a7c1f7b0d2007701b465fb49434484953db010a869ae6e4ad97

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.6.0 (2026-09-28)
+
+Instrumentation, so a render shows up in AppSignal and friends, and a faster text pipeline.
+
+- Instrumentation: `Stationery.instrument` emits `render.stationery` (the whole `to_pdf`: `document:`, `pages:`, `bytes:`, `warnings:`), `build.stationery`, `paginate.stationery`, `write.stationery` (serialise, subset, deflate), `image.stationery` (each decode on a cache miss: `format:`, `width:`, `height:`, `bytes:`), `font.stationery` (`action: :parse` on a cache miss, `action: :subset` per embedded font with `glyphs:`) and `parse.stationery` (`format: :html | :markdown`). `Stationery.instrumenter` is `ActiveSupport::Notifications` when it is loaded (the Railtie pins it), so AppSignal, Skylight and log subscribers pick the events up with no setup; otherwise a no-op. Assign any object responding to `instrument(name, payload, &block)` to plug something else in. Output is unchanged.
+- `FontBook#resolve` memoises by family, weight and style instead of hashing the whole 13-field `Text::Style` on every measurement: the lookup is 4x faster and a photo-heavy 4-page document renders 22% faster.
+
+## 0.5.0 (2026-09-27)
+
+Rotated, overlapping, cropped photos (the collage look), and fixes from the first weeks of use.
+
+- `stack { … }` and `layer(top:, right:, bottom:, left:, width:, height:, **box) { … }`: overlapping content. The stack's ordinary children set its height; each layer is a box placed with CSS-inset semantics relative to the stack (points, or fractions of the stack's width/height; negative insets overhang) and takes no flow height. A stack moves to the next page whole. `examples/postcard.rb` shows the collage: a cover photo with two tilted, framed, shadowed photos over its corners.
+- `box(rotate:)` turns a box clockwise around its centre without moving its layout rectangle (a rotated box never splits); `box(shadow: true | { offset:, blur:, color:, opacity: })` paints a soft drop shadow as stacked rounded rectangles at fading opacity, an artifact taking no space; `box(overflow: :hidden)` clips the content to the rounded outline. `column` takes the same options.
+- `image(fit: :cover, width:, height:)` scales up to fill the box and clips the excess around the centre; `image(radius:)` clips to rounded corners; `image(rotate:)` turns the painted image around its centre. Sizing, measuring and the tagged `Figure` bbox are unchanged; plain images are byte-for-byte as before.
+- `Canvas#rotate(degrees, around: [x, y]) { … }` and `Canvas#transform([a, b, c, d, e, f]) { … }` wrap a block in a `cm` transform given in top-left space, clockwise like CSS `rotate()`. Link and form-widget rectangles are annotations in page space, so they stay unrotated.
+- `html`/`markdown` write link annotations only for `http`, `https`, `mailto` and `tel` hrefs (and `#anchor`); anything else (`javascript:`, `data:`, a relative path) keeps its text without a link and is reported as a `Warnings::DroppedLink`. `links: %w[http https]` changes the list, `links: :all` keeps every href from a trusted source.
+- `html`/`markdown` `styles:` take `ul:` and `ol:` (`gap:`, `indent:`, `marker_gap:`, `marker_color:`, plus `style:` for `ul` and `format:`/`suffix:` for `ol`), passed straight to the list elements, so dense documents can tighten the 4pt item gap.
+- Whitespace no font has (an ideographic space U+3000, a figure space U+2007, a narrow no-break space U+202F, thin and hair spaces, …) is drawn as a blank of the character's conventional width instead of `.notdef`, and no longer reports `MissingGlyph`; font fallback keeps every Unicode White_Space character with its neighbours.
+- Testing: the RSpec matchers include `RSpec::Matchers::Composable`, so `have_pdf_text(…).and have_bookmark(…)`, `.or` and use inside `all`/`include` work. `Inspector#lang` reads the catalog `/Lang`; `have_pdf_language("de")` and `assert_pdf_language` assert it.
+- Previews: `Stationery::Preview#around_render(name, params)` wraps both the preview method and `to_pdf`, for an I18n locale or `CurrentAttributes` that must be in effect while the document renders (`?locale=de`); `Preview#to_pdf(name, params, debug:)` is the entry point the previews controller uses.
+
 ## 0.4.0 (2026-09-27)
 
 Interactive forms and tagged (accessible) PDF.

data/README.md

@@ -70,7 +70,7 @@ InvoicePdf.new(invoice).to_pdf          # => "%PDF-1.7…" (binary String)
 InvoicePdf.new(invoice).to_pdf("a.pdf") # also writes a path or an IO
 ```
 
-`examples/` has a complete, runnable invoice, annual report, letter, packing slip and fillable form; `bundle exec rake examples`
+`examples/` has a complete, runnable invoice, annual report, letter, packing slip, fillable form and postcard collage; `bundle exec rake examples`
 renders them all, or render one with `stationery render examples/report.rb`.
 
 ## Elements
@@ -80,12 +80,14 @@ renders them all, or render one with `stationery render examples/report.rb`.
 | `text(string, **style)` | A paragraph. Plain strings are literal. |
 | `text(string, markup: true)` | Reads `<b> <i> <u> <strikethrough> <sub> <sup> <br> <color rgb=""> <font size="" name=""> <link href="">`; decodes numeric and HTML 4 named entities. |
 | `text { b "Total"; plain " due" }` | Styled runs in Ruby. Take a block argument (`{ \|t\| t.b @x }`) to keep your own `self`. |
-| `box(padding:, background:, border:, radius:, width:, height:, min_height:, overflow:, at:, link:, outset:, break_inside:, decoration:) { }` | A container. Moves to the next page whole when it fits there and continues across pages when it does not; `break_inside: :auto` splits it at any page break, `:avoid` never splits it. At a cut, `decoration: :slice` (default) drops the padding and border, `:clone` keeps the padding. `overflow: :truncate` or `:shrink_to_fit` for fixed heights; a fixed `height:` never splits. `min_height:` is a floor that still splits: the first fragment keeps as much of it as the page holds, the next carries the rest (not combinable with `height:`). `at: [x, y]` pins it to a page position. `link:` makes the whole box clickable. `outset:` bleeds the background past the box (e.g. into the page margins). |
+| `box(padding:, background:, border:, radius:, width:, height:, min_height:, overflow:, at:, link:, outset:, break_inside:, decoration:, rotate:, shadow:) { }` | A container. Moves to the next page whole when it fits there and continues across pages when it does not; `break_inside: :auto` splits it at any page break, `:avoid` never splits it. At a cut, `decoration: :slice` (default) drops the padding and border, `:clone` keeps the padding. `overflow: :truncate` or `:shrink_to_fit` for fixed heights; a fixed `height:` never splits. `min_height:` is a floor that still splits: the first fragment keeps as much of it as the page holds, the next carries the rest (not combinable with `height:`). `at: [x, y]` pins it to a page position. `link:` makes the whole box clickable. `outset:` bleeds the background past the box (e.g. into the page margins). `rotate: -3` turns the painted box around its centre (layout box unchanged, never splits; a `link:` keeps its unrotated rectangle). `shadow: true` or `{ offset: [0, 4], blur: 8, color:, opacity: 0.15 }` paints a soft drop shadow under it, taking no space. `overflow: :hidden` clips the content to the rounded outline. |
 | `row(gap:, align:, break_inside:) { column(width:) { } }` | Columns side by side. `width:` is points, a fraction (`0.5`), `:auto` or `nil` (equal share). Splits across pages like a box, every column at once; a row with a fixed-height column never splits; columns with `min_height:` do. |
 | `table(rows, widths:, width:, header:, split_rows:, cell:) { \|t\| }` | Tables. Cells are strings, layout nodes, procs built with the DSL (`-> { image logo }`) or components. Style with `t.row(0)`, `t.rows(-1)`, `t.column(1)`, `t.columns(1..)`, chained, plus `t.zebra`. Header rows repeat after a page break. A cell may be `{ content:, colspan:, rowspan: }` plus any cell option; rows list only the cells they start, as in HTML, and pages never break through a rowspan. Spans are set in the rows, not through selections. A row taller than the page continues on the next page, cut through its cells, with the header repeated; `split_rows: true` cuts any row that reaches the page bottom instead of moving it whole. |
-| `image(path_or_io, width:, height:, fit:, align:)` | JPEG or PNG, aspect preserved. |
+| `image(path_or_io, width:, height:, fit:, align:, radius:, rotate:)` | JPEG or PNG, aspect preserved. `fit: [w, h]` scales to fit inside; `fit: :cover` fills `width:` × `height:` and crops around the centre. `radius:` rounds the corners; `rotate:` turns it (degrees, clockwise) without changing the space it takes. |
 | `svg(source_or_path, width:, height:, color:, align:)` | Vector icons and drawings; `currentColor` takes `color:`. Linear and radial gradients (`fill="url(#id)"`, `href` chains, both gradient units); `text`/`tspan` in the document's fonts; `<style>` stylesheets (element, class, id and `*` selectors). |
 | `wrap(gap:, row_gap:, align:) { }` | Children side by side at their own widths, wrapping onto new rows (chips, tags). |
+| `stack(gap:, align:) { }` | A base with layers painted over it: ordinary children set the height, `layer` children float over them and take no space. Moves to the next page whole. |
+| `layer(top:, right:, bottom:, left:, width:, height:, **box) { }` | Inside `stack`: a box placed by insets from the stack's edges, in points or as a fraction (`0.4`, `1/3r`) of its width/height; negative insets overhang. Takes every box option (`rotate:`, `shadow:`, `radius:`, …). |
 | `ul(style:, gap:, indent:, marker_gap:, marker_color:) { li "…" }` | Bulleted list. `style:` is `:disc`, `:circle`, `:square`, `:dash` or any String; unstyled nested lists cycle disc → circle → square. Any node added inside (not only `li`) becomes an item. Items split across pages; the marker stays with the first line. |
 | `ol(format:, start:, suffix:, gap:, indent:, marker_gap:, marker_color:) { }` | Numbered list. `format:` is `:decimal`, `:alpha`, `:upper_alpha`, `:roman`, `:upper_roman` or a Proc `(n) -> String`; `suffix:` defaults to `"."`. Markers right-align so bodies line up. |
 | `li(string, **style)`, `li(gap:) { }` | A list item: a paragraph, or a block of any elements (including nested lists). |
@@ -93,14 +95,14 @@ renders them all, or render one with `stationery render examples/report.rb`.
 | `group(keep_together: true, align:) { }` | Keep a block on one page. |
 | `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. |
+| `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). |
 | `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:)` | 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:)` | The same from CommonMark (plus GFM tables and strikethrough). |
+| `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). |
 
 Text style options: `font`, `size`, `weight` (`:regular`, `:bold`), `style` (`:italic`), `color`,
 `letter_spacing`, `underline`, `strikethrough`, `link`, `opacity`, `kerning` (default `true`), `ligatures` (default `true`), `align` (`:left`, `:center`, `:right`, `:justify`), `leading`.
@@ -128,7 +130,12 @@ end
   points; bold, `keep_with_next`), `p`, `a` (colour, underline), `code` (`font:`; register a
   monospace family for inline and block code, otherwise the text font is used), `pre` and
   `blockquote` (box options), `hr` (rule options), `table` (`cell:` options, `header:` text style),
-  `li` (text style) and `img` (`max_width:`).
+  `ul` and `ol` (list options: `gap:`, `indent:`, `marker_gap:`, `marker_color:`, plus `style:` for
+  `ul` and `format:`/`suffix:` for `ol`), `li` (text style) and `img` (`max_width:`).
+- Links are written only for `http`, `https`, `mailto` and `tel` hrefs (and `#anchor`); anything
+  else (`javascript:`, `data:`, a relative path) keeps its text without a link and is reported as a
+  `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.
 
 ### Links, bookmarks and table of contents
@@ -393,6 +400,21 @@ that take an argument (`?id=42`); `?debug=1` passes `debug: true` to `to_pdf`
 when the document supports it. Preview files are re-`load`ed on every request,
 so edits show up on refresh.
 
+Anything that must be in effect *while* the document renders (an I18n locale,
+`CurrentAttributes`, a time zone) goes in `around_render`, which wraps both the
+preview method and `to_pdf`:
+
+```ruby
+class FlyerPdfPreview < Stationery::Preview
+  def month(params) = FlyerPdf.new(Event.upcoming)
+
+  def around_render(_name, params) = I18n.with_locale(params.fetch("locale", I18n.default_locale)) { yield }
+end
+```
+
+`/rails/stationery/previews/flyer_pdf/month?locale=de` renders in German.
+`Preview#to_pdf(name, params, debug:)` is the same entry point for your own code.
+
 The gem has no Rails dependency; the Railtie loads only inside a Rails app.
 
 ## CLI
@@ -481,9 +503,12 @@ end
 ```
 
 Spaces, joiners, variation selectors and combining marks stay with the
-character before them. A glyph no font has is drawn as the family's
-`.notdef` and reported as a `Warnings::MissingGlyph` counting each drawn
-occurrence (so `strict` raises on it). Fallback covers every text element,
+character before them. Whitespace no font has (an ideographic space U+3000,
+a figure space, a narrow no-break space, …) is drawn as a blank of the
+character's conventional width, never as `.notdef`. Any other glyph no font
+has is drawn as the family's `.notdef` and reported as a
+`Warnings::MissingGlyph` counting each drawn occurrence (so `strict` raises
+on it). Fallback covers every text element,
 table cell, list marker, table of contents entry and page template text;
 direct `canvas.text` calls draw with the font they are given.
 
@@ -534,6 +559,7 @@ RSpec.describe InvoicePdf do
   it { is_expected.to have_pdf_link("mailto:hello@acme.test") }
   it { is_expected.to have_image_count(1) }
   it { is_expected.to have_no_warnings }
+  it { is_expected.to have_pdf_language("en") } # the catalog /Lang from `metadata lang:`
   it { is_expected.to have_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
@@ -554,6 +580,7 @@ class InvoicePdfTest < Minitest::Test
     assert_page_count pdf, 2
     assert_pdf_link pdf, /acme\.test/
     assert_no_pdf_warnings pdf
+    assert_pdf_language pdf, "en"
     assert_tagged_content pdf
     assert_pdf_structure pdf, [[:Document, [[:H1, "Invoice"], [:P, "INV-7"]]]]
   end
@@ -562,9 +589,10 @@ end
 
 The matcher names carry a `pdf_` prefix so they never clash with Capybara's
 `have_text` and `have_link`. `have_bookmark` / `assert_bookmark` match outline
-titles. For anything else, `Stationery::Testing::Inspector.new(subject)`
+titles. The RSpec matchers compose like the built-ins: `.and` / `.or`, and inside
+`all`, `include` or `match`. For anything else, `Stationery::Testing::Inspector.new(subject)`
 exposes `text`, `page_texts`, `page_count`, `links`, `internal_links`,
-`image_count`, `bookmarks`, `metadata`, `warnings`, `tagged?`, `untagged_text` and
+`image_count`, `bookmarks`, `metadata`, `lang`, `warnings`, `tagged?`, `untagged_text` and
 `structure` — a tagged PDF's structure tree as nested arrays, each element's text
 read from its marked content: `[type, "text"]`, `[type, [children]]` (its own text
 between the children, as for a `P` holding a `Link`) or `[type]` when empty; a
@@ -578,6 +606,41 @@ between the children, as for a `P` holding a `Link`) or `[type]` when empty; a
   a browser per worker; stray processes and memory are the price.
 - **Typst** is excellent but a native extension and a second template language.
 
+## Instrumentation
+
+Every render reports its phases as events named `<phase>.stationery`, so an
+APM that subscribes to `ActiveSupport::Notifications` (AppSignal, Skylight,
+Rails' own log subscribers) shows where a slow PDF spends its time with no
+setup: AppSignal groups them under "stationery" in the event tree. Outside
+Rails the events go to a null instrumenter that costs one method call.
+
+| Event | Around | Payload |
+|---|---|---|
+| `render.stationery` | the whole `to_pdf` | `document:`, `pages:`, `bytes:`, `warnings:` (count) |
+| `build.stationery` | building the component tree | `document:` |
+| `paginate.stationery` | layout, page breaks and page templates | `document:`, `pages:` |
+| `write.stationery` | serialising, subsetting and deflating | `document:`, `bytes:` |
+| `image.stationery` | decoding one image (cache misses only) | `format:`, `width:`, `height:`, `bytes:` |
+| `font.stationery` | parsing a font file (`action: :parse`, cache misses only) or subsetting one for a document (`action: :subset`, `glyphs:`) | `path:` or `font:`, `action:` |
+| `parse.stationery` | parsing an `html` or `markdown` source | `format:`, `bytes:` |
+
+Payload values known only afterwards (`pages:`, `bytes:`) are filled in
+before the event finishes, so subscribers always see them. Log every phase
+slower than 100 ms:
+
+```ruby
+ActiveSupport::Notifications.subscribe(/\.stationery\z/) do |name, start, finish, _id, payload|
+  ms = (finish - start) * 1000
+  Rails.logger.info("#{name} #{ms.round}ms #{payload.inspect}") if ms > 100
+end
+```
+
+Any object answering `instrument(name, payload) { |payload| }` can take the
+events instead (`Stationery.instrumenter = MyInstrumenter.new`), and
+`Stationery.instrument("custom.stationery", key: value) { … }` adds your own
+spans inside a document. When you hit a slow render, a trace with these
+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

data/lib/stationery/builder.rb

@@ -62,6 +62,17 @@ module Stationery
       @containers.pop
     end
 
+    # Whether nodes are being added straight into a stack's flow (where a
+    # layer may go).
+    def in_stack? = stacks.include?(@containers.last)
+
+    def stack(flow, &)
+      stacks << flow
+      within(flow, &)
+    ensure
+      stacks.delete(flow)
+    end
+
     def with_text(**overrides)
       @text << text_defaults.merge(overrides.compact)
       yield
@@ -70,6 +81,7 @@ module Stationery
     end
 
     def text_defaults = @text.last
+    def stacks = @stacks ||= []
     def outline = @outline ||= Outline.new
     def warnings = @book.warnings
 

data/lib/stationery/canvas/debug.rb

@@ -9,7 +9,7 @@ module Stationery
       DEBUG_COLORS = {
         box: "#E11D48", padding: "#E11D48", column: "#2563EB", cell: "#16A34A", cell_padding: "#16A34A",
         flow: "#9CA3AF", positioned: "#DB2777", image: "#0D9488", page: "#06B6D4", region: "#0EA5E9",
-        field: "#7C3AED"
+        field: "#7C3AED", stack: "#F59E0B"
       }.freeze
       DEBUG_DASHES = { padding: [2, 2], cell_padding: [2, 2], flow: [1, 2] }.freeze
 

data/lib/stationery/canvas.rb

@@ -31,6 +31,32 @@ module Stationery
       emit("Q")
     end
 
+    # Paints the block with the affine `matrix` [a, b, c, d, e, f] applied,
+    # given in top-left space (x' = ax + cy + e, y' = bx + dy + f with y
+    # growing downwards). Annotations (`link`, `widget`) keep their
+    # untransformed page rectangles.
+    def transform(matrix)
+      a, b, c, d, e, f = matrix
+      height = @page.height
+      pdf_matrix = [a, -b, -c, d, (c * height) + e, height - (d * height) - f]
+      save do
+        emit("#{pdf_matrix.map { |v| num(v) }.join(" ")} cm")
+        yield self
+      end
+    end
+
+    # Paints the block rotated `degrees` clockwise around the page point
+    # `around` ([x, y]), as CSS `rotate()` turns an element. Zero just yields.
+    def rotate(degrees, around:, &)
+      return yield self if degrees.zero?
+
+      radians = degrees * Math::PI / 180
+      cos = Math.cos(radians)
+      sin = Math.sin(radians)
+      cx, cy = around
+      transform([cos, sin, -sin, cos, cx - (cx * cos) + (cy * sin), cy - (cx * sin) - (cy * cos)], &)
+    end
+
     def clip(x, y, w, h, radius: 0)
       save do
         emit(Path.new(self).rounded_rect(x, y, w, h, radius).to_s, "W n")

data/lib/stationery/document.rb

@@ -95,21 +95,9 @@ module Stationery
 
     def to_pdf(target = nil, strict: self.class.config[:strict], debug: false, encrypt: self.class.config[:encrypt],
                tagged: self.class.config[:tagged])
-      encryption = encrypt && PDF::Encryption::StandardSecurity.new(**encrypt)
-      tagging = Tagging::Tree.new if tagged
-      warnings = Warnings.new
-      book = Fonts::FontBook.new(self.class.config[:families], fallbacks: self.class.config[:fallbacks], warnings:)
-      call(builder = Builder.new(book:, text: self.class.config[:text]))
-      resources = Resources.new
-      pages = paginate(builder.root, book:, resources:, warnings:, debug:, tagging:)
-      outline = builder.outline.resolve(Structure.resolve(pages, warnings:, resources:, book:, tagging:))
-      tagging&.audit(pages, warnings, lang: metadata[:lang])
-      @warnings = warnings
-      @fields = Forms::AcroForm.values(pages)
-      raise WarningsError, warnings if strict && warnings.any?
-
-      assembler = PDF::Assembler.new(pages:, resources:, info:, outline:, encryption:, tagging:, lang: metadata[:lang])
-      write(assembler.render, target)
+      Stationery.instrument("render.stationery", document: self.class.name) do |event|
+        write(render_pdf(event, strict:, debug:, encrypt:, tagged:), target)
+      end
     end
 
     # Used by page templates to build nodes into their own root.
@@ -130,11 +118,43 @@ module Stationery
 
     private
 
+    # The PDF bytes; `event` is the render.stationery payload it fills in.
+    def render_pdf(event, strict:, debug:, encrypt:, tagged:)
+      tagging = Tagging::Tree.new if tagged
+      warnings = Warnings.new
+      book = Fonts::FontBook.new(self.class.config[:families], fallbacks: self.class.config[:fallbacks], warnings:)
+      builder = Builder.new(book:, text: self.class.config[:text])
+      Stationery.instrument("build.stationery", document: self.class.name) { call(builder) }
+      resources = Resources.new
+      pages = paginate(builder.root, book:, resources:, warnings:, debug:, tagging:)
+      outline = builder.outline.resolve(Structure.resolve(pages, warnings:, resources:, book:, tagging:))
+      tagging&.audit(pages, warnings, lang: metadata[:lang])
+      @warnings = warnings
+      @fields = Forms::AcroForm.values(pages)
+      event[:pages] = pages.size
+      event[:warnings] = warnings.size
+      raise WarningsError, warnings if strict && warnings.any?
+
+      assemble(pages, resources, outline, encrypt:, tagging:).tap { |pdf| event[:bytes] = pdf.bytesize }
+    end
+
+    def assemble(pages, resources, outline, encrypt:, tagging:)
+      encryption = encrypt && PDF::Encryption::StandardSecurity.new(**encrypt)
+      assembler = PDF::Assembler.new(pages:, resources:, info:, outline:, encryption:, tagging:,
+                                     lang: metadata[:lang])
+      Stationery.instrument("write.stationery", document: self.class.name) do |event|
+        assembler.render.tap { |pdf| event[:bytes] = pdf.bytesize }
+      end
+    end
+
     def paginate(root, book:, resources:, warnings:, debug:, tagging:)
-      regions = Regions.new(self.class.config[:regions], measure: region_measure(book))
-      paginator = Layout::Paginator.new(resources:, page: page_options, warnings:, debug:, regions:, tagging:)
-      paginator.paginate(root).tap do |pages|
-        PageTemplates.new(self, book:, resources:, debug:, regions:, warnings:, tagging:).apply(pages)
+      Stationery.instrument("paginate.stationery", document: self.class.name) do |event|
+        regions = Regions.new(self.class.config[:regions], measure: region_measure(book))
+        paginator = Layout::Paginator.new(resources:, page: page_options, warnings:, debug:, regions:, tagging:)
+        paginator.paginate(root).tap do |pages|
+          PageTemplates.new(self, book:, resources:, debug:, regions:, warnings:, tagging:).apply(pages)
+          event[:pages] = pages.size
+        end
       end
     end
 

data/lib/stationery/elements/rich.rb

@@ -5,16 +5,18 @@ module Stationery
   module Elements
     # HTML such as ActionText's `record.body.to_s`. `images:` resolves an
     # image src to a path or IO (nil skips it); otherwise it is read from
-    # under `base_path:`. Remote images are never fetched.
-    def html(source, styles: {}, gap: 6, images: nil, base_path: nil, bookmarks: false)
+    # 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)
       require_relative "../html/document"
-      rich(HTML.parse(source.to_s), styles:, gap:, images:, base_path:, bookmarks:)
+      rich(HTML.parse(source.to_s), styles:, gap:, images:, base_path:, bookmarks:, links:)
     end
 
     # CommonMark (plus GFM tables and strikethrough); options as for html.
-    def markdown(source, styles: {}, gap: 6, images: nil, base_path: nil, bookmarks: false)
+    def markdown(source, styles: {}, gap: 6, images: nil, base_path: nil, bookmarks: false, links: nil)
       require_relative "../markdown/document"
-      rich(Markdown.parse(source.to_s), styles:, gap:, images:, base_path:, bookmarks:)
+      rich(Markdown.parse(source.to_s), styles:, gap:, images:, base_path:, bookmarks:, links:)
     end
 
     private

data/lib/stationery/elements.rb

@@ -51,6 +51,29 @@ module Stationery
       @_builder.add(node)
     end
 
+    # A base with layers painted over it: every ordinary child is part of the
+    # base (which sets the height), every `layer` floats over it relative to
+    # the stack's rectangle, taking no space. The stack moves to the next
+    # page whole. Layers may overhang; wrap the stack in `box(padding:)` to
+    # keep them inside the page.
+    def stack(gap: 0, align: nil, &)
+      flow = Layout::Flow.new([], gap:, align: align || :left)
+      @_builder.stack(flow) { align ? @_builder.with_text(align:) { yield_content(&) } : yield_content(&) }
+      layers, base = flow.children.partition { |child| child.is_a?(Layout::Layer) }
+      @_builder.add(Layout::Stack.new(flow.with_children(base), layers))
+    end
+
+    # A box placed over the enclosing `stack` by insets from its edges:
+    # points, or a fraction (`0.4`, `1/3r`) of the stack's width or height;
+    # negative values overhang. Takes every box option (`rotate:`, `shadow:`,
+    # `padding:`, `background:`, `radius:`, `height:`, …).
+    def layer(top: nil, right: nil, bottom: nil, left: nil, width: nil, height: nil, align: nil, gap: 0, **, &)
+      raise ArgumentError, "layer must be inside a stack" unless @_builder.in_stack?
+
+      box = Layout::Box.new(container(align:, gap:, &), **)
+      @_builder.add(Layout::Layer.new(box, top:, right:, bottom:, left:, width:, height:))
+    end
+
     # Children kept in one vertical group; `keep_together: true` moves the
     # whole group to the next page rather than splitting it.
     def group(gap: 0, align: nil, keep_together: false, keep_with_next: nil, anchor: nil, bookmark: nil, &)
@@ -97,7 +120,8 @@ module Stationery
       @_builder.add(node)
     end
 
-    # `alt:` describes the image in a tagged PDF (false: decorative).
+    # `alt:` describes the image in a tagged PDF (false: decorative). Sizing,
+    # `fit: :cover`, `radius:` and `rotate:` as for Layout::Image.
     def image(source, align: nil, **)
       node = Layout::Image.new(source, **)
       @_builder.add(align ? Layout::Flow.new([node], align:) : node)

data/lib/stationery/fonts/fallback.rb

@@ -6,11 +6,13 @@ module Stationery
     # run's family, then the book's fallbacks in order, then bundled Inter. A
     # glyph no font has stays in the run's family and draws as .notdef.
     #
-    # Whitespace, joiners, variation selectors and combining marks carry the
-    # family of the character before them (or after them at the start of a
-    # run) so words are not chopped and marks stay with their base.
+    # Whitespace (any Unicode White_Space), joiners, variation selectors and
+    # combining marks carry the family of the character before them (or
+    # after them at the start of a run) so words are not chopped and marks
+    # stay with their base; whitespace a font lacks draws as a blank of the
+    # right width (see Font::WHITESPACE).
     class Fallback
-      CARRIED = /[\s‌‍︀-️\p{M}]/
+      CARRIED = /[\p{Space}‌‍︀-️\p{M}]/
 
       def self.carried?(char) = CARRIED.match?(char)
 

data/lib/stationery/fonts/font.rb

@@ -12,6 +12,18 @@ module Stationery
     class Font
       OBLIQUE_SKEW = Math.tan(12 * Math::PI / 180)
 
+      # Whitespace the font lacks draws as its space glyph advanced to the
+      # character's conventional width: a fraction of the em for the fixed
+      # spaces, a digit's or a period's advance for the figure and
+      # punctuation spaces, the space's own width for the rest (no-break,
+      # line and paragraph separators, ogham mark, …). Nothing is painted,
+      # nothing is .notdef.
+      WHITESPACE = /\A\p{Space}\z/
+      SPACE_FRACTIONS = { 0x2000 => 0.5, 0x2001 => 1.0, 0x2002 => 0.5, 0x2003 => 1.0, 0x2004 => 1.0 / 3,
+                          0x2005 => 0.25, 0x2006 => 1.0 / 6, 0x2009 => 0.2, 0x200A => 0.125, 0x205F => 4.0 / 18,
+                          0x3000 => 1.0 }.freeze
+      SPACE_LIKE = { 0x2007 => "0", 0x2008 => "." }.freeze
+
       attr_reader :ttf
 
       def initialize(ttf)
@@ -19,6 +31,7 @@ module Stationery
         @used = {}
         @pairs = {}
         @glyphs = {}
+        @blanks = {}
         @shapes = { true => {}, false => {} }
         @advances = { true => {}, false => {} }
         @kerns = { true => {}, false => {} }
@@ -59,12 +72,20 @@ module Stationery
       # `ligatures:` substitutes the font's standard ligatures; `kerning:`
       # then fills the adjustments with pair kerning between the glyphs.
       def glyph_run(text, kerning: false, ligatures: true)
-        gids, chars = shape(text, ligatures)
-        gids.each_with_index { |gid, i| @used[gid] ||= chars[i] }
-        adjust = gids.each_with_index.map { |gid, i| kerning && i + 1 < gids.size ? pair(gid, gids[i + 1]) : 0 }
+        gids, chars, blanks = shape(text, ligatures)
+        gids.each_with_index { |gid, i| @used[gid] ||= blanks[i] ? " " : chars[i] }
+        adjust = gids.each_with_index.map do |gid, i|
+          kern = kerning && i + 1 < gids.size ? pair(gid, gids[i + 1]) : 0
+          blanks[i] ? kern + (blanks[i] * 1000.0 / @ttf.units_per_em) : kern
+        end
         GlyphRun.new(font: self, gids:, adjust:, chars:)
       end
 
+      # Whether a character the font lacks is drawn as a blank (see WHITESPACE).
+      def blank?(char)
+        @blanks.fetch(char) { @blanks[char] = WHITESPACE.match?(char) && !glyph?(char) && glyph?(" ") }
+      end
+
       def used?
         @used.any?
       end
@@ -83,7 +104,11 @@ module Stationery
 
       def build(writer)
         embedding = (@ttf.cff? ? Embedding::CFF : Embedding::TrueType).new(self)
-        name, cid_font = embedding.build(writer, @used.keys.sort)
+        gids = @used.keys.sort
+        name, cid_font = Stationery.instrument("font.stationery", font: @ttf.postscript_name, action: :subset,
+                                                                  glyphs: gids.size) do
+          embedding.build(writer, gids)
+        end
 
         writer.add(
           Type: :Font, Subtype: :Type0, BaseFont: name, Encoding: :"Identity-H",
@@ -93,11 +118,13 @@ module Stationery
 
       private
 
-      # [gids, source text of each glyph], remembered per string.
+      # [gids, source text of each glyph, extra advance in font units after
+      # each blank or nil], remembered per string.
       def shape(text, ligatures)
         @shapes[ligatures][text] ||= begin
-          gids = text.each_char.map { |char| @ttf.glyph_id(char.ord) }
-          ligatures ? ligate(gids, text) : [gids, text.chars].each(&:freeze).freeze
+          gids = text.each_char.map { |char| glyph_for(char) }
+          gids, chars = ligatures ? ligate(gids, text) : [gids, text.chars]
+          [gids, chars, chars.map { |char| blank_units(char) }].each(&:freeze).freeze
         end
       end
 
@@ -105,11 +132,31 @@ module Stationery
         start = 0
         glyphs = @ttf.ligatures.substitute(gids)
         chars = glyphs.map { |_gid, count| text[start, count].tap { start += count } }
-        [glyphs.map(&:first), chars].each(&:freeze).freeze
+        [glyphs.map(&:first), chars]
+      end
+
+      def glyph_for(char)
+        blank?(char) ? @ttf.glyph_id(" ".ord) : @ttf.glyph_id(char.ord)
+      end
+
+      # How much wider (or narrower) than a space a blank's advance is.
+      def blank_units(char)
+        return unless blank?(char)
+
+        space = @ttf.advance(@ttf.glyph_id(" ".ord))
+        like = SPACE_LIKE[char.ord]
+        width = if (fraction = SPACE_FRACTIONS[char.ord]) then @ttf.units_per_em * fraction
+                elsif like && glyph?(like) then @ttf.advance(@ttf.glyph_id(like.ord))
+                else space
+                end
+        width - space
       end
 
       def advance_units(text, ligatures)
-        @advances[ligatures][text] ||= shape(text, ligatures).first.sum { |gid| @ttf.advance(gid) }
+        @advances[ligatures][text] ||= begin
+          gids, _, blanks = shape(text, ligatures)
+          gids.sum { |gid| @ttf.advance(gid) } + blanks.sum { |units| units || 0 }
+        end
       end
 
       def kerning_units(text, ligatures)

data/lib/stationery/fonts/font_book.rb

@@ -26,9 +26,14 @@ module Stationery
         @families[name.to_s] = Family.build(name, **paths)
       end
 
-      # Returns [Font, Family::Face] for a Text::Style, memoised per style.
+      # Returns [Font, Family::Face] for a Text::Style, memoised by the three
+      # fields that pick a face (family, weight, style) in nested hashes: a
+      # style's size, colour and the rest do not matter here, and hashing a
+      # 13-field Data on every text measurement did.
       def resolve(style)
-        @resolved[style] ||= begin
+        weights = (@resolved[style.family] ||= {})
+        styles = (weights[style.weight] ||= {})
+        styles[style.style] ||= begin
           face = family(style.family).face(weight: style.weight, style: style.style)
           [@fonts[face.path] ||= Font.new(Registry.load(face.path)), face].freeze
         end

data/lib/stationery/fonts/registry.rb

@@ -36,11 +36,17 @@ module Stationery
         def fetch(path, index, mtime)
           key = [path, index]
           cached_mtime, ttf = @cache.delete(key)
-          ttf = TrueType.new(File.binread(path), index:) unless cached_mtime == mtime
+          ttf = parse(path, index) unless cached_mtime == mtime
           @cache[key] = [mtime, ttf]
           @cache.shift while @cache.size > SIZE
           ttf
         end
+
+        def parse(path, index)
+          Stationery.instrument("font.stationery", path: File.basename(path), action: :parse) do
+            TrueType.new(File.binread(path), index:)
+          end
+        end
       end
     end
   end

data/lib/stationery/html/document.rb

@@ -6,6 +6,10 @@ require_relative "tree_builder"
 module Stationery
   # Lenient HTML to rich-text blocks (see Stationery::Rich).
   module HTML
-    def self.parse(source) = TreeBuilder.parse(Tokenizer.tokenize(source))
+    def self.parse(source)
+      Stationery.instrument("parse.stationery", format: :html, bytes: source.bytesize) do
+        TreeBuilder.parse(Tokenizer.tokenize(source))
+      end
+    end
   end
 end

data/lib/stationery/images/images.rb

@@ -14,7 +14,15 @@ module Stationery
     # Accepts a path, a Pathname or an IO-like object (read from its start).
     def load(source)
       data = read(source)
-      Cache.fetch(data) { parse(data) }
+      Cache.fetch(data) do
+        Stationery.instrument("image.stationery", bytes: data.bytesize) do |event|
+          parse(data).tap do |image|
+            event[:format] = image.is_a?(JPEG) ? "JPEG" : "PNG"
+            event[:width] = image.width
+            event[:height] = image.height
+          end
+        end
+      end
     end
 
     def read(source)