stationery 0.5.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dab8be06e23e27d74ddd2ec627bc34923a79a9c0cb5fe40da55f43bdcb81e337
-  data.tar.gz: a7f90eadef2004318933e8a65cd1f86841c5b9bfc4cba8ff6191b2f96946b8e5
+  metadata.gz: 0f9e83f23437589a026e0a9a2fde163a39a2c4151c434afc5bdbea38a98891dd
+  data.tar.gz: 67e42695ae205e05049441490b89b908f6468ba94e00c095c1de8eaeae986d65
 SHA512:
-  metadata.gz: ce40fc76233a4c6ba0ca455c9c80ac3a651832ba86ab7003c8f907b2abd8291cbe0a7421302b4a6762e876df284ebe98ed862017eaed7cb4854d609e3fa557ec
-  data.tar.gz: b1c1928f47210a8b29586f73881b8430978c644a2ea7489fab251796b7192213057a414c3145c47502fa267e3c857d5b581f91d8bf2bca394e61384844fc21d8
+  metadata.gz: 40756fe30e4c2d400fab7402e490609cf313e8ae06c5317489f6b0337f96fc5ad00d8f2c8b05b348812955b109cc0f9685f9c1668b8f307d1fd16ac9492facad
+  data.tar.gz: 1a7938f3b608b68df057d3385d5824dc6a57338978a76ad39bed42701838ee2a408db1c2d30daccf3a834b03bea9f6d1441ef6405691dff0090611d26cbe05a0

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.7.0 (2026-09-28)
+
+Typography and images: hyphenation, OpenType features, oversized-image warnings, page labels.
+
+- Hyphenation: `hyphenate: true | "en" | "de" | "sv"` on `text`, `text_style`, `default_text` and the rich `styles:` (`p`, `li`). Liang's algorithm over the TeX `hyph-utf8` patterns for English, German and Swedish (bundled with their licences), so a word that does not fit breaks at the longest hyphenation point that does, with the font's hyphen. A soft hyphen (U+00AD, `­` in HTML) is a break point in any language: never drawn or measured unless the line breaks there, and absent from extracted text. Off by default; unchanged output otherwise.
+- OpenType features: `features: %i[smcp onum tnum ss01]` on the same entry points applies the font's GSUB single substitutions (formats 1 and 2, also behind Extension lookups) before ligatures; `Font#features` lists what a font offers, an absent feature is ignored. Substituted glyphs keep their source characters in ToUnicode. Contextual lookups (`calt`, `clig`, `frac`) stay unsupported and are listed as such.
+- Oversized images: a bitmap drawn at more than twice `max_ppi` (300 by default; `images max_ppi: 220` per document, `image(max_ppi:)` per call, `nil` disables) reports `Warnings::OversizedImage` naming the source, pixel width, effective ppi and the limit, so `strict` catches a 1600 px photo drawn 160 pt wide. `downscale: true` resamples a PNG (grey, RGB, palette, alpha) to the limit before embedding; JPEG is never re-encoded and only warns.
+- Page labels: `page_labels 1 => { style: :roman_lower }, 4 => { style: :decimal }, 12 => { style: :alpha, prefix: "Appendix " }` (or `to_pdf(page_labels:)`) writes the `/PageLabels` number tree; `Inspector#page_labels`, `have_page_labels` and `assert_page_labels` read it back.
+- `text(…, markup: true)` decodes HTML character references (`&amp;`, `&#39;`, `&#x27;`, the named entities the HTML parser knows), so data escaped with `html_escape` before adding your own `<b>` tags renders as intended instead of showing `&#39;`.
+
+## 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.

data/README.md

@@ -70,7 +70,8 @@ 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, fillable form and postcard collage; `bundle exec rake examples`
+`examples/` has a complete, runnable invoice, annual report, letter, packing slip, fillable form, postcard collage and event flyer
+([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`.
 
 ## Elements
@@ -78,12 +79,12 @@ renders them all, or render one with `stationery render examples/report.rb`.
 | Element | What it does |
 |---|---|
 | `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(string, markup: true)` | Reads `<b> <i> <u> <strikethrough> <sub> <sup> <br> <color rgb=""> <font size="" name=""> <link href="">`; decodes numeric (`&#39;`, `&#x27;`) and HTML 4 named entities once, so escape user data (`ERB::Util.html_escape`) before wrapping it in your own tags: `&lt;b&gt;` stays literal text. |
 | `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:, 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:, 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. |
+| `image(path_or_io, width:, height:, fit:, align:, radius:, rotate:, max_ppi:, downscale:)` | 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. Drawn at more than twice `max_ppi:` (300) it is reported as oversized; `downscale: true` resamples a PNG to that resolution instead. |
 | `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. |
@@ -105,7 +106,7 @@ renders them all, or render one with `stationery render examples/report.rb`.
 | `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`.
+`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`.
 `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).
@@ -259,6 +260,10 @@ render Callout.new(color: "#F3F4F6") { text "Amount due" }
   fits a normal page but not the last one continues onto an extra page.
 - With a header or footer, a `page_template`'s `page.content_box` excludes their space (it is the
   body's area).
+- `page_labels 1 => { style: :roman_lower }, 3 => { style: :decimal, start: 1, prefix: "A-" }` names
+  the pages the way viewers show them ("i", "ii", "A-1", …): a 1-based first page mapped to the range
+  that starts there, with `style:` `:decimal`, `:roman`, `:roman_lower`, `:alpha`, `:alpha_lower` or
+  `nil` (prefix only), `start:` and `prefix:`. `to_pdf(page_labels:)` overrides it for one render.
 - Content taller than a page is placed anyway; `document.warnings` lists every overflow.
 - After `to_pdf`, `document.warnings` is an Enumerable of everything the render noticed but did not
   raise on, each with a `#message`: overflows, SVG elements that were skipped (`UnsupportedSvg`), and
@@ -521,16 +526,48 @@ line is never wider than the same line unkerned.
 
 Standard ligatures (fi, fl, ffi, …) come from the font's GSUB `liga` feature
 (LigatureSubst lookups, also behind Extension lookups) and are on by default;
-`ligatures: false` on an element or in `default_text` turns them off. Only
-`liga` applies, not `clig` or `dlig`. Ligatures form within a run of one
-style and font, never across a line break, and letter spacing turns them off.
-The PDF's ToUnicode map sends a ligature glyph back to all of its
-characters, so copied and extracted text still reads "office". Fonts
-without a `liga` feature (such as the bundled Inter) are unaffected.
+`ligatures: false` on an element or in `default_text` turns them off.
+Ligatures form within a run of one style and font, never across a line
+break, and letter spacing turns them off. The PDF's ToUnicode map sends a
+ligature glyph back to all of its characters, so copied and extracted text
+still reads "office". Fonts without a `liga` feature (such as the bundled
+Inter) are unaffected.
+
+Other OpenType features are opt-in per element, `text_style` or
+`default_text`: `features: %i[smcp onum]` applies the font's small caps and
+oldstyle figures, `tnum`/`pnum` pick tabular or proportional figures for
+tables, `zero` a slashed zero, `dlig` discretionary ligatures, `ss01`… the
+stylistic sets. Single (SingleSubst) and ligature (LigatureSubst) lookups
+are applied in the font's own order; a feature the font lacks is ignored,
+and `Font#features` lists what a font offers. Substituted glyphs keep
+their source characters in ToUnicode, so "2026" in oldstyle figures still
+extracts as "2026". Contextual features (`calt`, `clig`, `frac`) need
+lookup types the reader does not implement and do nothing.
+
+Hyphenation is off unless asked for: `hyphenate: "de"` on `text`, `text_style`,
+`default_text` or an `html`/`markdown` style (`styles: { p: { hyphenate: "de" } }`)
+breaks a word that does not fit at the longest point Liang's algorithm allows
+over the bundled TeX patterns (`true` or `"en"` for American English, `"de"`
+for German, `"sv"` for Swedish; `lib/stationery/hyphenation/patterns/LICENSES.md`
+names their authors and licences), drawing a hyphen at the break. A soft hyphen
+(U+00AD, `&shy;` in HTML) names the break points of a word yourself and, as in
+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.
 
 Images are JPEG (grey, RGB, CMYK) and PNG (every colour type, alpha as a soft
 mask). Parsed fonts and images are cached per process.
 
+A bitmap keeps its pixels, so a 1600 px photo drawn 160 pt wide ships all
+1600 px at 720 ppi. An image drawn at more than twice the document's
+`max_ppi` (300, or `images max_ppi: 220` at class level, `nil` to switch the
+check off) is reported as a `Warnings::OversizedImage` naming the file, its
+pixel width and the resolution it lands at. `images downscale: true` (or
+`image(..., downscale: true)`) resamples a PNG to `max_ppi` at its drawn size
+before embedding it, alpha included; a JPEG is embedded byte for byte, so
+resize it before you embed it (an ActiveStorage variant per drawn size,
+preprocessed, keeps a render to a download).
+
 ## Testing
 
 `stationery/rspec` and `stationery/minitest` read a rendered PDF back for
@@ -560,6 +597,7 @@ RSpec.describe InvoicePdf do
   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_page_labels(%w[i ii 1 2]) } # from `page_labels`
   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
@@ -581,6 +619,7 @@ class InvoicePdfTest < Minitest::Test
     assert_pdf_link pdf, /acme\.test/
     assert_no_pdf_warnings pdf
     assert_pdf_language pdf, "en"
+    assert_page_labels pdf, %w[i ii 1 2]
     assert_tagged_content pdf
     assert_pdf_structure pdf, [[:Document, [[:H1, "Invoice"], [:P, "INV-7"]]]]
   end
@@ -592,7 +631,7 @@ The matcher names carry a `pdf_` prefix so they never clash with Capybara's
 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`, `lang`, `warnings`, `tagged?`, `untagged_text` and
+`image_count`, `bookmarks`, `metadata`, `lang`, `page_labels`, `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
@@ -606,6 +645,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
@@ -626,10 +700,28 @@ larger file. `PROFILE=1 bundle exec ruby -Ilib benchmark/profile.rb` prints the
 
 ## Limitations
 
-No variable fonts (including CFF2) or
-WOFF2 (it needs Brotli; convert to `.ttf` or `.woff`); SVG covers the shapes icon sets use
-(no patterns or masks). A box with a fixed `height:` never splits (use
-`min_height:` for a floor that can); a row splits only when every column can.
+Fonts: no variable fonts (including CFF2) and no WOFF2 (it needs Brotli; convert to `.ttf` or
+`.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
+patterns are bundled for English, German and Swedish only (a soft hyphen works in any language),
+and justification only widens spaces.
+
+SVG covers the shapes, gradients, text and stylesheets icon sets use, nothing else: `use`,
+`image`, `clipPath`, `mask`, `pattern`, `filter` and `textPath` are skipped and reported.
+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.
+
+Layout: a box with a fixed `height:` never splits (use `min_height:` for a floor that can); a row
+splits only when every column can; a rotated box and a `stack` move to the next page whole. Text
+does not wrap around images. Link and form-widget rectangles stay in page space inside `rotate`
+and `transform`, and `shadow:` is stacked rectangles, not a blur.
+
+PDF: tagged output is not labelled PDF/UA (no XMP), and there is no PDF/A or PDF/X, no digital
+signing (`signature_field` is an empty field), no embedded files or JavaScript.
+Form-field appearances use Helvetica (Windows-1252), not the document's fonts.
 
 ## License
 

data/lib/stationery/builder.rb

@@ -5,7 +5,7 @@ module Stationery
   # (where the next node goes) and the text defaults in effect.
   class Builder
     STYLE_KEYS = %i[size color weight style letter_spacing underline strikethrough link opacity kerning
-                    ligatures].freeze
+                    ligatures features hyphenate].freeze
 
     # Collects a row's columns; anything that is not already a column box is
     # wrapped in one.
@@ -32,10 +32,12 @@ module Stationery
       end
     end
 
-    attr_reader :root, :book, :list_depth
+    # `images` are the document's bitmap defaults (max_ppi:, downscale:).
+    attr_reader :root, :book, :list_depth, :images
 
-    def initialize(book:, text: {})
+    def initialize(book:, text: {}, images: {})
       @book = book
+      @images = images
       @root = Layout::Flow.new
       @containers = [@root]
       @text = [text]

data/lib/stationery/canvas/text.rb

@@ -8,14 +8,15 @@ module Stationery
 
       # Draws `string` with its baseline at (x, y) in top-left coordinates and
       # returns its advance width. Standard ligatures form unless `ligatures:`
-      # is false or letter spacing is set.
+      # is false or letter spacing is set; `features:` are further OpenType
+      # feature tags (Strings) to apply.
       def text(string, x:, y:, font:, size:, color: "#000000", letter_spacing: 0, rise: 0, opacity: nil,
                synthetic_bold: false, synthetic_oblique: false, underline: false, strikethrough: false,
-               kerning: false, ligatures: true, word_spacing: 0)
+               kerning: false, ligatures: true, features: Fonts::Font::NO_FEATURES, word_spacing: 0)
         return 0 if string.empty?
 
         color = Color.parse(color)
-        run = font.glyph_run(string, kerning:, ligatures: ligatures && letter_spacing.zero?)
+        run = font.glyph_run(string, kerning:, ligatures: ligatures && letter_spacing.zero?, features:)
         run = run.with_word_spacing(word_spacing, size) unless word_spacing.zero?
         width = run.width(size, letter_spacing:)
         graphics(opacity:) do |ops|

data/lib/stationery/canvas.rb

@@ -12,16 +12,19 @@ module Stationery
     CAPS = { butt: 0, round: 1, square: 2 }.freeze
     JOINS = { miter: 0, round: 1, bevel: 2 }.freeze
 
-    attr_reader :page
+    # `warnings` is the render's collector (nil on a bare canvas), for what a
+    # node notices only while painting, such as an oversized image.
+    attr_reader :page, :warnings
 
     # `template: true` records anchors apart, for canvases page templates draw on.
     # `tagging:` (a Tagging::Tree) marks content for a tagged PDF.
-    def initialize(page, resources, template: false, debug: false, tagging: nil)
+    def initialize(page, resources, template: false, debug: false, tagging: nil, warnings: nil)
       @page = page
       @resources = resources
       @template = template
       @debug = debug
       @tagging = tagging
+      @warnings = warnings
       @marked = 0
     end
 

data/lib/stationery/document.rb

@@ -24,7 +24,7 @@ module Stationery
                       superclass.config.transform_values(&:dup)
                     else
                       { page: { size: :letter, margin: 36 }, families: {}, fallbacks: [], text: {}, metadata: {},
-                        templates: [], regions: [], strict: false, tagged: false }
+                        templates: [], regions: [], strict: false, tagged: false, images: {} }
                     end
       end
 
@@ -50,6 +50,21 @@ module Stationery
         config[:metadata] = config[:metadata].merge(info)
       end
 
+      # How viewers name the pages: a 1-based first page mapped to the range
+      # starting there, `page_labels 1 => { style: :roman_lower }, 3 =>
+      # { style: :decimal, start: 1, prefix: "A-" }`; see PDF::PageLabels.
+      def page_labels(spec)
+        PDF::PageLabels.entries(spec)
+        config[:page_labels] = spec
+      end
+
+      # Bitmap defaults: `max_ppi:` (300; nil disables) is the resolution
+      # above twice of which a drawn image is reported as oversized, and
+      # `downscale: true` resamples PNGs to it. See Layout::Image.
+      def images(**options)
+        config[:images] = config[:images].merge(options)
+      end
+
       # Raise WarningsError instead of writing a PDF that produced warnings.
       def strict(value = true) # rubocop:disable Style/OptionalBooleanParameter
         config[:strict] = value
@@ -94,22 +109,10 @@ module Stationery
     def metadata = self.class.config[:metadata]
 
     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)
+               tagged: self.class.config[:tagged], page_labels: self.class.config[:page_labels])
+      Stationery.instrument("render.stationery", document: self.class.name) do |event|
+        write(render_pdf(event, strict:, debug:, encrypt:, tagged:, page_labels:), target)
+      end
     end
 
     # Used by page templates to build nodes into their own root.
@@ -123,18 +126,52 @@ module Stationery
 
     # Builds a page template or region block into a fresh root node.
     def template_root(info, book:, &)
-      builder = Builder.new(book:, text: self.class.config[:text])
+      builder = builder_for(book)
       build_with(builder) { instance_exec(info, &) }
       builder.root
     end
 
     private
 
+    def builder_for(book) = Builder.new(book:, text: self.class.config[:text], images: self.class.config[:images])
+
+    # The PDF bytes; `event` is the render.stationery payload it fills in.
+    def render_pdf(event, strict:, debug:, encrypt:, tagged:, page_labels:)
+      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_for(book)
+      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:, page_labels:).tap { |pdf| event[:bytes] = pdf.bytesize }
+    end
+
+    def assemble(pages, resources, outline, encrypt:, tagging:, page_labels:)
+      encryption = encrypt && PDF::Encryption::StandardSecurity.new(**encrypt)
+      assembler = PDF::Assembler.new(pages:, resources:, info:, outline:, encryption:, tagging:,
+                                     lang: metadata[:lang], page_labels: PDF::PageLabels.entries(page_labels))
+      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.rb

@@ -123,7 +123,7 @@ module Stationery
     # `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, **)
+      node = Layout::Image.new(source, **@_builder.images, **)
       @_builder.add(align ? Layout::Flow.new([node], align:) : node)
     end
 

data/lib/stationery/fonts/fallback.rb

@@ -6,13 +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 (any Unicode White_Space), joiners, variation selectors and
-    # combining marks carry the family of the character before them (or
+    # Whitespace (any Unicode White_Space), soft hyphens, 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 = /[\p{Space}‌‍︀-️\p{M}]/
+      CARRIED = /[\p{Space}­‌‍︀-️\p{M}]/
 
       def self.carried?(char) = CARRIED.match?(char)
 

data/lib/stationery/fonts/font.rb

@@ -23,6 +23,7 @@ module Stationery
                           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
+      NO_FEATURES = [].freeze
 
       attr_reader :ttf
 
@@ -32,9 +33,9 @@ module Stationery
         @pairs = {}
         @glyphs = {}
         @blanks = {}
-        @shapes = { true => {}, false => {} }
-        @advances = { true => {}, false => {} }
-        @kerns = { true => {}, false => {} }
+        @shapes = {}
+        @advances = {}
+        @kerns = {}
         @cid_keyed = ttf.cff? && ttf.cff.cid_keyed?
       end
 
@@ -44,14 +45,19 @@ module Stationery
       # word again (wrapping, then laying out the line) allocates nothing.
       # Letter spacing is added per glyph, so a ligature counts once; any
       # letter spacing turns ligatures off, as it does when drawing.
-      def width_of(text, size, letter_spacing: 0, kerning: false, ligatures: true)
+      # `features:` are OpenType feature tags applied on top of `liga`.
+      def width_of(text, size, letter_spacing: 0, kerning: false, ligatures: true, features: NO_FEATURES)
         ligatures &&= letter_spacing.zero?
-        width = scale(advance_units(text, ligatures), size) + (letter_spacing * shape(text, ligatures).first.size)
+        key = shape_key(ligatures, features)
+        width = scale(advance_units(text, key), size) + (letter_spacing * shape(text, key).first.size)
         return width unless kerning
 
-        width + (kerning_units(text, ligatures) * size / 1000.0)
+        width + (kerning_units(text, key) * size / 1000.0)
       end
 
+      # The GSUB feature tags this font can apply.
+      def features = @ttf.ligatures.features
+
       def ascender(size) = scale(@ttf.ascender, size)
       def descender(size) = -scale(@ttf.descender, size)
       def line_gap(size) = scale(@ttf.line_gap, size)
@@ -69,10 +75,11 @@ module Stationery
 
       def encode(text) = glyph_run(text).gids.map { |gid| code(gid) }.pack("n*")
 
-      # `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, blanks = shape(text, ligatures)
+      # `ligatures:` substitutes the font's standard ligatures and `features:`
+      # any further OpenType features; `kerning:` then fills the adjustments
+      # with pair kerning between the glyphs.
+      def glyph_run(text, kerning: false, ligatures: true, features: NO_FEATURES)
+        gids, chars, blanks = shape(text, shape_key(ligatures, features))
         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
@@ -104,7 +111,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",
@@ -114,19 +125,30 @@ module Stationery
 
       private
 
+      # The feature tags to substitute with: `liga` when ligatures are on, plus
+      # the requested features. Frozen and shared, so it keys the memos cheaply.
+      def shape_key(ligatures, features)
+        features = Text::Style.features(features) unless features.frozen? && features.all?(String)
+        return features unless ligatures
+        return Gsub::LIGA if features.empty?
+
+        @keys ||= {}
+        @keys[features] ||= (features + Gsub::LIGA).sort.freeze
+      end
+
       # [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
+      # each blank or nil], remembered per string and feature tags.
+      def shape(text, tags)
+        (@shapes[tags] ||= {})[text] ||= begin
           gids = text.each_char.map { |char| glyph_for(char) }
-          gids, chars = ligatures ? ligate(gids, text) : [gids, text.chars]
+          gids, chars = tags.empty? ? [gids, text.chars] : substitute(gids, text, tags)
           [gids, chars, chars.map { |char| blank_units(char) }].each(&:freeze).freeze
         end
       end
 
-      def ligate(gids, text)
+      def substitute(gids, text, tags)
         start = 0
-        glyphs = @ttf.ligatures.substitute(gids)
+        glyphs = @ttf.ligatures.substitute(gids, tags)
         chars = glyphs.map { |_gid, count| text[start, count].tap { start += count } }
         [glyphs.map(&:first), chars]
       end
@@ -148,15 +170,15 @@ module Stationery
         width - space
       end
 
-      def advance_units(text, ligatures)
-        @advances[ligatures][text] ||= begin
-          gids, _, blanks = shape(text, ligatures)
+      def advance_units(text, tags)
+        (@advances[tags] ||= {})[text] ||= begin
+          gids, _, blanks = shape(text, tags)
           gids.sum { |gid| @ttf.advance(gid) } + blanks.sum { |units| units || 0 }
         end
       end
 
-      def kerning_units(text, ligatures)
-        @kerns[ligatures][text] ||= shape(text, ligatures).first.each_cons(2).sum { |left, right| pair(left, right) }
+      def kerning_units(text, tags)
+        (@kerns[tags] ||= {})[text] ||= shape(text, tags).first.each_cons(2).sum { |left, right| pair(left, right) }
       end
 
       # Kerning between two glyphs in thousandths of an em.

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/gsub/single_subst.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Fonts
+    class Gsub
+      # SingleSubst (GSUB lookup type 1): one glyph for another. Format 1
+      # adds a delta to every covered glyph, format 2 lists the substitute
+      # for each covered glyph in coverage order. Small caps, oldstyle and
+      # tabular figures, stylistic sets and slashed zero are all this.
+      class SingleSubst
+        def self.read(ttf, offset)
+          format = ttf.u16(offset)
+          coverage = Gpos::Coverage.read(ttf, offset + ttf.u16(offset + 2))
+          case format
+          when 1
+            delta = ttf.i16(offset + 4)
+            new(coverage.to_h { |gid| [gid, (gid + delta) & 0xFFFF] })
+          when 2
+            substitutes = ttf.data.byteslice(offset + 6, ttf.u16(offset + 4) * 2).unpack("n*")
+            new(coverage.zip(substitutes).to_h.compact)
+          end
+        end
+
+        def initialize(map)
+          @map = map.freeze
+          freeze
+        end
+
+        # [substitute gid, 1] for a covered glyph at `index`, or nil.
+        def match(gids, index)
+          gid = @map[gids[index]]
+          [gid, 1] if gid
+        end
+      end
+    end
+  end
+end