stationery 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dabc4e22462e7af56f79f46c814ebb908ee12961948190ae2b73f2f8951478f7
-  data.tar.gz: 9ef6ee24bfa601829d8b51fb514254a55a9470afd98be1429b2935984f6605df
+  metadata.gz: f9ff43b2013eb330ebc103525c440bb5e4cfdaf0d05364baf47fd329c48ad11a
+  data.tar.gz: 718ede92892d3c7c0cdc556708880a2ba53f559611b872cfcb8ac946adb59908
 SHA512:
-  metadata.gz: 1e051af6e9e75e979f763b5bd47eed272fef23d754d1e11116abc890669679c71eee3a2a615305ef63c59f6c626ea3567eeba76a2a9407e81c929626e6ec6139
-  data.tar.gz: d7c7ffab364d4502a568c6496c10413b189bebf2003ffc433e014960fc29fe7cc948097eff9fd292e9e6108aeb5cc51c42ffdba5da18e71d99f2e951b94cfb26
+  metadata.gz: b3a4a85b185b0f06e195a15f81773c86d79086e32e923b1c21c2d39ee528375fd5b75be1581fc3d8180e530071d653939674804c973896d0edb3b57fffbde9fa
+  data.tar.gz: fd368b63884a129cd0e6f03507da714891c79b81b6a1aeadde9cfeafc4987824d7cd525c2f86aa3eba397f432a14516429bc697b61177056a790a602d85369ae

data/CHANGELOG.md

@@ -1,6 +1,26 @@
 # Changelog
 
-## 0.2.0 (unreleased)
+## 0.3.0 (2026-09-27)
+
+The Limitations page, shortened: TrueType collections, WOFF, ligatures, splittable
+`min_height:` boxes, SVG gradients, text and stylesheets, and encryption.
+
+- SVG: `linearGradient` and `radialGradient` fills (`fill="url(#id)"`, also in `style`), with stops, `href`/`xlink:href` inheritance, `objectBoundingBox` and `userSpaceOnUse` units and `gradientTransform`, drawn as PDF axial/radial shadings clipped to the shape. Approximations: `reflect`/`repeat` spreads are drawn as `pad` (reported in `unsupported`), stop opacity is the first stop's for the whole gradient, and a gradient stroke is drawn in the gradient's middle colour. A reference to a missing gradient paints its fallback colour or nothing and is reported as `url(#id)`. `Canvas#shade` paints a shading dictionary inside a path.
+- SVG: `text` and `tspan` (`x`/`y`/`dx`/`dy`, first value each; `font-family`, first family the font book knows — registered, bundled or an installed pack — else the document's default; `font-size`, `font-weight`, `font-style`, `text-anchor`, `fill`, `opacity`, transforms), drawn through the document's fonts so they subset and extract like any text. Whitespace collapses as in browsers. Glyphs stay upright: a transform moves the baseline origin and scales the size uniformly, so rotated or skewed text is approximated; `dominant-baseline` is ignored and a gradient fill uses its middle colour. `Layout::Svg` takes `context:`, `SVG::Document#draw` takes `book:` and `family:`, and `FontBook#known?` tells whether a family resolves without substitution.
+- SVG: `<style>` stylesheets (plain or CDATA) as Illustrator and Inkscape export them. Selectors: element, `.class` (`.a.b`), `#id`, `element.class`, comma lists and `*`; rules with combinators (`g path`, `a > b`, …) are ignored and reported once as `style selectors: …`. Cascade: presentation attributes, then rules by specificity (id > class > element, later wins on ties), then inline `style`. Rules style shapes, text (`font-*`) and gradient stops (`stop-color`, `stop-opacity`); `display: none` skips an element and its children, `visibility: hidden` skips it (a `visible` child draws). `class` takes several classes.
+
+- Encryption with the standard security handler: `to_pdf(encrypt: { owner_password:, user_password:, permissions:, algorithm: })` or `encrypt …` at class level (`to_pdf(encrypt: nil)` opts out). AES-256 (R6, default), AES-128 (R4) and RC4-128 (R3); every string and stream, document info included, is encrypted.
+
+- Standard ligatures from the font's GSUB `liga` feature (LigatureSubst lookups, also behind Extension lookups), **on by default**: "office" in Open Sans draws the ffi ligature, so widths of affected words change slightly. `ligatures: false` on `text`/`text_style` or in `default_text` opts out; any `letter_spacing` turns them off. Text extraction and copy still yield the source characters (ToUnicode maps a ligature glyph to all of them). Fonts without `liga` ligatures, such as the bundled Inter, are unaffected.
+
+### Fonts
+
+- TrueType collections (`.ttc`): `font_family "Brand", regular: "Brand.ttc#0", bold: "Brand.ttc#2"` picks a face by a `#N` suffix (face 0 without one); each face is parsed, cached, subset and embedded on its own. `TrueType.new(data, index:)`, `TrueType.collection?` and `TrueType.faces`; an index out of range raises `ArgumentError` naming the face count.
+- WOFF 1.0 web fonts (`.woff`): `font_family "Web", regular: "Brand.woff"`. Tables are inflated with zlib into an in-memory sfnt (`Fonts::WOFF.unpack`), then measured, subset and embedded like the `.ttf`. WOFF2 is still rejected: it needs Brotli, so convert to `.ttf` or `.woff`.
+
+- `box(min_height:)` and `column(min_height:)`: a height floor that, unlike `height:`, still splits across pages. The first fragment keeps as much of the floor as the page holds and the next carries the rest, so a row of equal-height cards or an empty signature area can span a page break. Passing both `height:` and `min_height:` raises `ArgumentError`.
+
+## 0.2.0 (2026-09-27)
 
 Everything from the three planned milestones ("works out of the box", "typography and layout",
 "documents, Rails and testing") shipped together.

data/README.md

@@ -80,11 +80,11 @@ 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:, 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. `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). |
-| `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. |
+| `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). |
+| `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. |
-| `svg(source_or_path, width:, height:, color:, align:)` | Vector icons and drawings; `currentColor` takes `color:`. |
+| `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). |
 | `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. |
@@ -98,7 +98,7 @@ renders them all, or render one with `stationery render examples/report.rb`.
 | `markdown(source, styles:, gap:, images:, base_path:, bookmarks:)` | 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`), `align` (`:left`, `:center`, `:right`, `:justify`), `leading`.
+`letter_spacing`, `underline`, `strikethrough`, `link`, `opacity`, `kerning` (default `true`), `ligatures` (default `true`), `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).
@@ -228,6 +228,27 @@ render Callout.new(color: "#F3F4F6") { text "Amount due" }
   (with `#warnings`) instead of writing a PDF that produced any; `to_pdf(strict: false)` opts one
   render out again.
 
+### Encryption
+
+```ruby
+class InvoicePdf < Stationery::Document
+  encrypt owner_password: "s3cret", permissions: [:print] # every render
+end
+
+InvoicePdf.new(invoice).to_pdf(encrypt: { user_password: "1234", owner_password: "s3cret",
+                                          permissions: %i[print copy] }) # override for one render
+InvoicePdf.new(invoice).to_pdf(encrypt: nil) # plain
+```
+
+- `owner_password:` is required (`ArgumentError` when missing or empty); it opens the file with every
+  right. `user_password:` defaults to `""`: the file opens without a prompt, but viewers enforce the
+  permissions.
+- `permissions:` is a subset of `%i[print modify copy annotate fill_forms extract_accessible assemble
+  print_high]` (default: all).
+- `algorithm:` picks the standard security handler. `:aes_256` (default, PDF 2.0 / Acrobat X+);
+  `:aes_128` for older viewers; `:rc4_128` only for legacy readers that need it.
+- Every string and stream is encrypted, the document info included.
+
 ### Debugging
 
 `to_pdf(debug: true)` outlines every layout rectangle on top of the content: boxes (red, padding dashed),
@@ -317,7 +338,14 @@ already present are kept unless `--force`. `--from` takes a directory or a
 ## Fonts and images
 
 Fonts are TrueType (`.ttf`) or OpenType/CFF (`.otf`, name-keyed or
-CID-keyed) files. Only the glyphs a document uses are embedded (a CFF font
+CID-keyed) files, WOFF 1.0 web fonts (`.woff`, unwrapped in memory), or
+faces of a TrueType collection (`.ttc`): a `#N` suffix
+on the path picks face N, counted from 0 (face 0 without a suffix):
+
+```ruby
+font_family "Brand", regular: "Brand.ttc#0", bold: "Brand.ttc#2"
+```
+ Only the glyphs a document uses are embedded (a CFF font
 keeps its glyph numbering and subroutines; unused glyphs are blanked), with a
 ToUnicode map so text copies and searches correctly. A style without its own
 file (bold, italic) is synthesised.
@@ -379,6 +407,15 @@ turns it off). Pairs that straddle a style or
 font change are not kerned. Kerning only tightens in practice, so a kerned
 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.
+
 Images are JPEG (grey, RGB, CMYK) and PNG (every colour type, alpha as a soft
 mask). Parsed fonts and images are cached per process.
 
@@ -466,11 +503,11 @@ larger file. `PROFILE=1 bundle exec ruby -Ilib benchmark/profile.rb` prints the
 
 ## Limitations
 
-No ligatures, no TrueType collections, variable fonts (including CFF2) or
-WOFF; SVG covers the shapes icon sets use
-(no text, gradients, patterns, masks or CSS stylesheets); no encryption,
-forms or tagged PDF; fixed-height boxes, and rows holding one,
-never split across pages.
+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); no forms or
+tagged PDF. A box with a fixed `height:` never splits (use
+`min_height:` for a floor that can); a row splits only when every column can.
 
 ## License
 

data/lib/stationery/builder.rb

@@ -4,7 +4,8 @@ module Stationery
   # Collects the nodes a component tree describes. Holds the container stack
   # (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].freeze
+    STYLE_KEYS = %i[size color weight style letter_spacing underline strikethrough link opacity kerning
+                    ligatures].freeze
 
     # Collects a row's columns; anything that is not already a column box is
     # wrapped in one.

data/lib/stationery/canvas/text.rb

@@ -7,15 +7,16 @@ module Stationery
       BOLD_STROKE = 0.03
 
       # Draws `string` with its baseline at (x, y) in top-left coordinates and
-      # returns its advance width.
+      # returns its advance width. Standard ligatures form unless `ligatures:`
+      # is false or letter spacing is set.
       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, word_spacing: 0)
+               kerning: false, ligatures: true, word_spacing: 0)
         return 0 if string.empty?
 
         color = Color.parse(color)
-        run = font.glyph_run(string, kerning:)
-        run = run.with_word_spacing(string, word_spacing, size) unless word_spacing.zero?
+        run = font.glyph_run(string, kerning:, ligatures: ligatures && letter_spacing.zero?)
+        run = run.with_word_spacing(word_spacing, size) unless word_spacing.zero?
         width = run.width(size, letter_spacing:)
         graphics(opacity:) do |ops|
           ops << color.fill

data/lib/stationery/canvas.rb

@@ -58,6 +58,19 @@ module Stationery
       shape(fill:, stroke:, line_width:, cap:, join:, dash:, even_odd:, opacity:, transform:, &)
     end
 
+    # Paints `shading` inside the path the block traces. `matrix` maps the
+    # shading's coordinates into top-left page space.
+    def shade(shading, matrix:, transform: nil, even_odd: false, opacity: nil)
+      path = Path.new(self, transform:)
+      yield path
+      name = @page.use(:Shading, @resources.shading(shading))
+      a, b, c, d, e, f = matrix
+      graphics(opacity:) do |ops|
+        ops << path.to_s << (even_odd ? "W* n" : "W n")
+        ops << "#{[a, -b, c, -d, e, @page.height - f].map { |v| num(v) }.join(" ")} cm" << "/#{name} sh"
+      end
+    end
+
     def image(image, x:, y:, width:, height:, opacity: nil)
       name = @page.use(:XObject, @resources.image(image))
       graphics(opacity:) do |ops|

data/lib/stationery/document.rb

@@ -55,6 +55,12 @@ module Stationery
         config[:strict] = value
       end
 
+      # Encrypts every render with the standard security handler; see
+      # PDF::Encryption::StandardSecurity for the options.
+      def encrypt(**)
+        config[:encrypt] = PDF::Encryption::StandardSecurity.options(**)
+      end
+
       # Runs after pagination on every page. `layer: :background` paints under
       # the page's content.
       def page_template(layer: :foreground, &block)
@@ -79,7 +85,8 @@ module Stationery
     def page_options = self.class.config[:page]
     def metadata = self.class.config[:metadata]
 
-    def to_pdf(target = nil, strict: self.class.config[:strict], debug: false)
+    def to_pdf(target = nil, strict: self.class.config[:strict], debug: false, encrypt: self.class.config[:encrypt])
+      encryption = encrypt && PDF::Encryption::StandardSecurity.new(**encrypt)
       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]))
@@ -92,7 +99,7 @@ module Stationery
       @warnings = warnings
       raise WarningsError, warnings if strict && warnings.any?
 
-      write(PDF::Assembler.new(pages:, resources:, info:, outline:).render, target)
+      write(PDF::Assembler.new(pages:, resources:, info:, outline:, encryption:).render, target)
     end
 
     # Used by page templates to build nodes into their own root.

data/lib/stationery/elements.rb

@@ -73,7 +73,7 @@ module Stationery
       if document.unsupported.any?
         @_builder.warnings << Warnings::UnsupportedSvg.new(elements: document.unsupported, source: name)
       end
-      node = Layout::Svg.new(document, width:, height:, color:)
+      node = Layout::Svg.new(document, width:, height:, color:, context: @_builder.context)
       @_builder.add(align ? Layout::Flow.new([node], align:) : node)
     end
 

data/lib/stationery/fonts/font.rb

@@ -17,11 +17,11 @@ module Stationery
       def initialize(ttf)
         @ttf = ttf
         @used = {}
-        @widths = {}
         @pairs = {}
         @glyphs = {}
-        @advances = {}
-        @kerns = {}
+        @shapes = { true => {}, false => {} }
+        @advances = { true => {}, false => {} }
+        @kerns = { true => {}, false => {} }
         @cid_keyed = ttf.cff? && ttf.cff.cid_keyed?
       end
 
@@ -29,11 +29,14 @@ module Stationery
 
       # Advances and kerning are remembered per string, so measuring the same
       # word again (wrapping, then laying out the line) allocates nothing.
-      def width_of(text, size, letter_spacing: 0, kerning: false)
-        width = scale(advance_units(text), size) + (letter_spacing * text.length)
+      # 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)
+        ligatures &&= letter_spacing.zero?
+        width = scale(advance_units(text, ligatures), size) + (letter_spacing * shape(text, ligatures).first.size)
         return width unless kerning
 
-        width + (kerning_units(text) * size / 1000.0)
+        width + (kerning_units(text, ligatures) * size / 1000.0)
       end
 
       def ascender(size) = scale(@ttf.ascender, size)
@@ -53,15 +56,13 @@ module Stationery
 
       def encode(text) = glyph_run(text).gids.map { |gid| code(gid) }.pack("n*")
 
-      # `kerning:` fills the adjustments with the font's pair kerning.
-      def glyph_run(text, kerning: false)
-        gids = text.each_char.map do |char|
-          gid = @ttf.glyph_id(char.ord)
-          @used[gid] ||= char
-          gid
-        end
+      # `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 }
-        GlyphRun.new(font: self, gids:, adjust:)
+        GlyphRun.new(font: self, gids:, adjust:, chars:)
       end
 
       def used?
@@ -74,7 +75,8 @@ module Stationery
         @cid_keyed ? @ttf.cff.cid_for(gid) : gid
       end
 
-      # { code => character } for every glyph drawn so far.
+      # { code => text } for every glyph drawn so far; a ligature's text is
+      # every character it stands for.
       def used_codes
         @used.to_h { |gid, char| [code(gid), char] }
       end
@@ -91,13 +93,27 @@ module Stationery
 
       private
 
-      def advance_units(text)
-        @advances[text] ||= text.each_char.sum { |char| @widths[char] ||= @ttf.advance(@ttf.glyph_id(char.ord)) }
+      # [gids, source text of each glyph], 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
+        end
+      end
+
+      def ligate(gids, text)
+        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
+      end
+
+      def advance_units(text, ligatures)
+        @advances[ligatures][text] ||= shape(text, ligatures).first.sum { |gid| @ttf.advance(gid) }
       end
 
-      def kerning_units(text)
-        @kerns[text] ||= text.each_char.map { |char| @ttf.glyph_id(char.ord) }
-                             .each_cons(2).sum { |left, right| pair(left, right) }
+      def kerning_units(text, ligatures)
+        @kerns[ligatures][text] ||= shape(text, ligatures).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

@@ -34,6 +34,9 @@ module Stationery
         end
       end
 
+      # Whether `name` is registered, bundled or an installed pack.
+      def known?(name) = !(@families[name.to_s] || bundled(name) || pack(name)).nil?
+
       # The runs split so every character is drawn by a font that has it. Runs
       # this book already split come back as they are.
       def fallback(runs)

data/lib/stationery/fonts/glyph_run.rb

@@ -3,16 +3,17 @@
 module Stationery
   module Fonts
     # Glyph ids for one run of text in one font, with an extra advance after
-    # each glyph in thousandths of the font size (positive widens). All-zero
+    # each glyph in thousandths of the font size (positive widens) and the
+    # source text of each glyph (several characters for a ligature). All-zero
     # adjustments draw as a plain Tj string; otherwise as a TJ array. Glyphs
     # are written as the font's character codes (see Font#code).
-    GlyphRun = Data.define(:font, :gids, :adjust) do
+    GlyphRun = Data.define(:font, :gids, :adjust, :chars) do
       def width(size, letter_spacing: 0)
         units = gids.sum { |gid| font.ttf.advance(gid) }
         (units * size / font.ttf.units_per_em.to_f) + (adjust.sum * size / 1000.0) + (letter_spacing * gids.size)
       end
 
-      def with_word_spacing(chars, extra_points, size)
+      def with_word_spacing(extra_points, size)
         extra = extra_points * 1000.0 / size
         with(adjust: adjust.each_with_index.map { |a, i| chars[i] == " " ? a + extra : a })
       end

data/lib/stationery/fonts/gpos.rb

@@ -15,19 +15,21 @@ module Stationery
         base = ttf.table_offset("GPOS")
         return unless base && ttf.u16(base) == 1
 
-        indices = kern_lookups(ttf, base + ttf.u16(base + 6))
-        return if indices.empty?
-
-        list = base + ttf.u16(base + 8)
-        new(indices.map { |i| lookup(ttf, list + ttf.u16(list + 2 + (i * 2))) })
+        offsets = feature_lookups(ttf, base, "kern")
+        new(offsets.map { |offset| lookup(ttf, offset) }) if offsets.any?
       end
 
-      def self.kern_lookups(ttf, list)
+      # Offsets of the lookups every `tag` feature record of the GSUB or GPOS
+      # table at `base` names, in LookupList order.
+      def self.feature_lookups(ttf, base, tag)
+        list = base + ttf.u16(base + 6)
         records = Array.new(ttf.u16(list)) { |i| list + 2 + (i * 6) }
-        records.select { |record| ttf.data.byteslice(record, 4) == "kern" }.flat_map do |record|
+        indices = records.select { |record| ttf.data.byteslice(record, 4) == tag }.flat_map do |record|
           feature = list + ttf.u16(record + 4)
           Array.new(ttf.u16(feature + 2)) { |j| ttf.u16(feature + 4 + (j * 2)) }
-        end.uniq
+        end
+        lookups = base + ttf.u16(base + 8)
+        indices.uniq.sort.map { |i| lookups + ttf.u16(lookups + 2 + (i * 2)) }
       end
 
       # A lookup's PairPos subtables; other lookup types have none.
@@ -42,7 +44,7 @@ module Stationery
           end
         end.freeze
       end
-      private_class_method :kern_lookups, :lookup
+      private_class_method :lookup
 
       def initialize(lookups)
         @lookups = lookups.freeze

data/lib/stationery/fonts/gsub/ligature_subst.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Fonts
+    class Gsub
+      # LigatureSubst format 1 (GSUB lookup type 4): for each first glyph, the
+      # ligatures starting with it, longest first.
+      class LigatureSubst
+        def self.read(ttf, offset)
+          return unless ttf.u16(offset) == 1
+
+          sets = Gpos::Coverage.read(ttf, offset + ttf.u16(offset + 2)).each_with_index.to_h do |first, i|
+            set = offset + ttf.u16(offset + 6 + (i * 2))
+            [first, ligatures(ttf, set).sort_by.with_index { |(rest, _), j| [-rest.size, j] }.freeze]
+          end
+          new(sets)
+        end
+
+        # [[component gids after the first, ligature gid], ...]
+        def self.ligatures(ttf, set)
+          Array.new(ttf.u16(set)) do |i|
+            ligature = set + ttf.u16(set + 2 + (i * 2))
+            count = ttf.u16(ligature + 2)
+            [ttf.data.byteslice(ligature + 4, (count - 1) * 2).unpack("n*").freeze, ttf.u16(ligature)]
+          end
+        end
+        private_class_method :ligatures
+
+        def initialize(sets)
+          @sets = sets.freeze
+          freeze
+        end
+
+        # [ligature gid, glyphs consumed] for the longest ligature at `index`, or nil.
+        def match(gids, index)
+          @sets[gids[index]]&.each do |components, ligature|
+            return [ligature, components.size + 1] if gids[index + 1, components.size] == components
+          end
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/stationery/fonts/gsub.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Fonts
+    # Standard ligatures from the GSUB `liga` feature: LigatureSubst lookups
+    # (format 1), directly or behind Extension lookups. Only `liga` applies;
+    # contextual (`clig`) and discretionary (`dlig`) ligatures are left out.
+    # Scripts, languages and lookup flags are not distinguished.
+    class Gsub
+      LIGATURE = 4
+      EXTENSION = 7
+
+      # nil when the font has no GSUB table or no `liga` ligatures.
+      def self.parse(ttf)
+        base = ttf.table_offset("GSUB")
+        return unless base && ttf.u16(base) == 1
+
+        lookups = Gpos.feature_lookups(ttf, base, "liga").map { |offset| lookup(ttf, offset) }.reject(&:empty?)
+        new(lookups) if lookups.any?
+      end
+
+      # A lookup's LigatureSubst subtables; other lookup types have none.
+      def self.lookup(ttf, offset)
+        type = ttf.u16(offset)
+        subtables = Array.new(ttf.u16(offset + 4)) { |i| offset + ttf.u16(offset + 6 + (i * 2)) }
+        subtables.filter_map do |subtable|
+          if type == LIGATURE
+            LigatureSubst.read(ttf, subtable)
+          elsif type == EXTENSION && ttf.u16(subtable + 2) == LIGATURE
+            LigatureSubst.read(ttf, subtable + ttf.u32(subtable + 4))
+          end
+        end.freeze
+      end
+      private_class_method :lookup
+
+      def initialize(lookups)
+        @lookups = lookups.freeze
+        freeze
+      end
+
+      # [[gid, number of source glyphs it stands for], ...]. Lookups apply in
+      # order; within one, the first subtable matching at a position wins and
+      # its glyph is not matched again by that lookup.
+      def substitute(gids)
+        @lookups.reduce(gids.map { |gid| [gid, 1] }) { |glyphs, subtables| apply(subtables, glyphs) }
+      end
+
+      private
+
+      def apply(subtables, glyphs)
+        ids = glyphs.map(&:first)
+        result = []
+        i = 0
+        while i < glyphs.size
+          match = nil
+          subtables.find { |subtable| match = subtable.match(ids, i) }
+          length = match ? match.last : 1
+          result << [match ? match.first : ids[i], glyphs[i, length].sum(&:last)]
+          i += length
+        end
+        result
+      end
+    end
+  end
+end

data/lib/stationery/fonts/ligatures.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Fonts
+    # Chooses where a font's ligatures come from. Every source answers
+    # `substitute(gids)` with [[gid, source glyph count], ...].
+    module Ligatures
+      # For fonts without ligatures: every glyph stands for itself.
+      module NONE
+        def self.substitute(gids) = gids.map { |gid| [gid, 1] }
+      end
+
+      def self.for(ttf) = Gsub.parse(ttf) || NONE
+    end
+  end
+end

data/lib/stationery/fonts/registry.rb

@@ -2,21 +2,24 @@
 
 module Stationery
   module Fonts
-    # Process-wide cache of parsed TrueType files, keyed by path and mtime so an
-    # edited font is re-read. Parsing is the expensive part; the per-document
-    # Font objects that track used glyphs are cheap wrappers around a parse.
+    # Process-wide cache of parsed TrueType files, keyed by path, face and
+    # mtime so an edited font is re-read. Parsing is the expensive part; the
+    # per-document Font objects that track used glyphs are cheap wrappers
+    # around a parse. A `#N` suffix on the path picks face N of a collection.
     module Registry
       SIZE = 16
+      FACE = /\A(.+)#(\d+)\z/
       @cache = {}
       @mutex = Mutex.new
 
       class << self
         def load(path)
-          path = File.expand_path(path.to_s)
+          path, index = split(path.to_s)
+          path = File.expand_path(path)
           raise UnsupportedFont, "font file not found: #{path}" unless File.file?(path)
 
           mtime = File.mtime(path)
-          @mutex.synchronize { fetch(path, mtime) }
+          @mutex.synchronize { fetch(path, index, mtime) }
         end
 
         def clear
@@ -25,10 +28,16 @@ module Stationery
 
         private
 
-        def fetch(path, mtime)
-          cached_mtime, ttf = @cache.delete(path)
-          ttf = TrueType.new(File.binread(path)) unless cached_mtime == mtime
-          @cache[path] = [mtime, ttf]
+        def split(path)
+          match = FACE.match(path)
+          match ? [match[1], match[2].to_i] : [path, 0]
+        end
+
+        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
+          @cache[key] = [mtime, ttf]
           @cache.shift while @cache.size > SIZE
           ttf
         end

data/lib/stationery/fonts/to_unicode.rb

@@ -7,7 +7,7 @@ module Stationery
     module ToUnicode
       module_function
 
-      # `chars` is { code => character }.
+      # `chars` is { code => text }; a ligature maps to several characters.
       def cmap(chars)
         mappings = chars.sort.map do |code, char|
           format("<%<code>04X> <%<utf16>s>", code:, utf16: char.encode(Encoding::UTF_16BE).unpack1("H*").upcase)