stationery 0.2.0 → 0.4.0

data/lib/stationery/canvas.rb

@@ -7,6 +7,7 @@ module Stationery
   class Canvas
     include Text
     include Debug
+    include Marking
 
     CAPS = { butt: 0, round: 1, square: 2 }.freeze
     JOINS = { miter: 0, round: 1, bevel: 2 }.freeze
@@ -14,11 +15,14 @@ module Stationery
     attr_reader :page
 
     # `template: true` records anchors apart, for canvases page templates draw on.
-    def initialize(page, resources, template: false, debug: false)
+    # `tagging:` (a Tagging::Tree) marks content for a tagged PDF.
+    def initialize(page, resources, template: false, debug: false, tagging: nil)
       @page = page
       @resources = resources
       @template = template
       @debug = debug
+      @tagging = tagging
+      @marked = 0
     end
 
     def save
@@ -58,6 +62,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|
@@ -68,11 +85,22 @@ module Stationery
 
     # A clickable area opening `target`: a URL, or `#name` for an anchor in
     # this document. Annotation rectangles live in absolute, untransformed
-    # page space, so they ignore clips and path transforms.
-    def link(x, y, w, h, target)
+    # page space, so they ignore clips and path transforms. `tag:` is the
+    # Link element the annotation belongs to in a tagged PDF.
+    def link(x, y, w, h, target, tag: nil)
       target = target.to_s
       rect = [x, @page.height - y - h, x + w, @page.height - y].map { |v| num_value(v) }
-      @page.annotations << (target.start_with?("#") ? { rect:, dest: target[1..] } : { rect:, url: target })
+      annotation = target.start_with?("#") ? { rect:, dest: target[1..] } : { rect:, url: target }
+      @page.annotations << annotation
+      own(annotation, tag) if tag
+    end
+
+    # An interactive form field's widget (a Forms::Field) over the rectangle.
+    def widget(field, x, y, w, h, tag: nil)
+      rect = [x, @page.height - y - h, x + w, @page.height - y].map { |v| num_value(v) }
+      annotation = { rect:, widget: field }
+      @page.annotations << annotation
+      adopt(annotation, tag, rect) if tag
     end
 
     # Names the point `y` on this page as a link target.
@@ -81,9 +109,10 @@ module Stationery
     end
 
     # Leaves room for the page number `anchor` lands on; Structure fills it in
-    # and adds the `link:` area ([x, y, w, h]) when the anchor exists.
-    def number_slot(anchor, x:, baseline:, width:, style:, link: nil)
-      @page.slots << Page::Slot.new(anchor.to_s, x, baseline, width, style, link)
+    # and adds the `link:` area ([x, y, w, h]) when the anchor exists. `tags:`
+    # are the [link, number] elements they belong to in a tagged PDF.
+    def number_slot(anchor, x:, baseline:, width:, style:, link: nil, tags: nil)
+      @page.slots << Page::Slot.new(anchor.to_s, x, baseline, width, style, link, tags)
     end
 
     def num(value) = PDF::Serializer.number(num_value(value))
@@ -128,7 +157,7 @@ module Stationery
       ops = []
       ops << "/#{@page.use(:ExtGState, @resources.opacity(opacity))} gs" if opacity && opacity < 1
       yield ops
-      emit("q", *ops, "Q")
+      artifact { emit("q", *ops, "Q") }
     end
 
     def emit(*ops)

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 }
+                        templates: [], regions: [], strict: false, tagged: false }
                     end
       end
 
@@ -55,6 +55,19 @@ module Stationery
         config[:strict] = value
       end
 
+      # Writes a tagged (accessible) PDF: a structure tree of headings,
+      # paragraphs and figures, and headers and footers marked as artifacts.
+      # Set `metadata lang:` and give images `alt:` text.
+      def tagged(value = true) # rubocop:disable Style/OptionalBooleanParameter
+        config[:tagged] = 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)
@@ -74,25 +87,29 @@ module Stationery
       end
     end
 
-    attr_reader :warnings
+    # `fields` is every form field's name and value from the last render.
+    attr_reader :warnings, :fields
 
     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],
+               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
-      regions = Regions.new(self.class.config[:regions], measure: region_measure(book))
-      paginator = Layout::Paginator.new(resources:, page: page_options, warnings:, debug:, regions:)
-      pages = paginator.paginate(builder.root)
-      PageTemplates.new(self, book:, resources:, debug:, regions:, warnings:).apply(pages)
-      outline = builder.outline.resolve(Structure.resolve(pages, warnings:, resources:, book:))
+      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?
 
-      write(PDF::Assembler.new(pages:, resources:, info:, outline:).render, target)
+      assembler = PDF::Assembler.new(pages:, resources:, info:, outline:, encryption:, tagging:, lang: metadata[:lang])
+      write(assembler.render, target)
     end
 
     # Used by page templates to build nodes into their own root.
@@ -113,6 +130,14 @@ module Stationery
 
     private
 
+    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)
+      end
+    end
+
     def region_measure(book)
       page = Page.new(**page_options)
       lambda do |region, number|
@@ -122,7 +147,7 @@ module Stationery
     end
 
     def info
-      metadata.to_h do |key, value|
+      metadata.except(:lang).to_h do |key, value|
         [INFO_KEYS.fetch(key.to_sym) { key.to_sym }, value.is_a?(Array) ? value.join(", ") : value]
       end
     end

data/lib/stationery/elements/forms.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Stationery
+  # Interactive form fields. Each takes a name (dotted names group fields,
+  # "address.city") and lays out like a box, or at a fixed page position with
+  # `at: [x, y]`.
+  module Elements
+    # A text input. `width:` is :full or points; `multiline:`, `max_length:`,
+    # `comb:` (a cell count, or true with max_length:), `read_only:`,
+    # `required:`, `font_size:`, `border:`, `background:` and `radius:`.
+    def text_field(name, value: "", width: :full, height: 22, at: nil, **)
+      field_node(Forms::Field.new(:text, name, value: value.to_s, **), width:, height:, at:)
+    end
+
+    # A check box `size` points square, with an optional label to its right.
+    def checkbox(name, checked: false, size: 12, label: nil, at: nil, **)
+      field = Forms::Field.new(:checkbox, name, value: checked == true, **)
+      field_node(field, width: size, height: size, at:, label:)
+    end
+
+    # One choice of the radio group `name`; its `value` becomes the group's
+    # value when checked.
+    def radio(name, value, checked: false, size: 12, label: nil, at: nil, **)
+      field = Forms::Field.new(:radio, name, value: value.to_s, checked:, **)
+      field_node(field, width: size, height: size, at:, label:)
+    end
+
+    # A drop-down (combo box) of `options`; `editable: true` also accepts
+    # typed values.
+    def select(name, options:, value: nil, width: :full, height: 22, at: nil, **)
+      field = Forms::Field.new(:select, name, value: value&.to_s, options: options.map(&:to_s), **)
+      field_node(field, width:, height:, at:)
+    end
+
+    # An empty signature field for the signer to fill, drawn as a rule over
+    # the label.
+    def signature_field(name, width: :full, height: 40, label: "Signature", at: nil, **)
+      field = Forms::Field.new(:signature, name, label: label.to_s, **)
+      field_node(field, width:, height:, at:)
+    end
+
+    private
+
+    def field_node(field, width:, height:, at:, label: nil)
+      label &&= field_label(label)
+      node = Layout::Field.new(field, height:, width:, label:)
+      @_builder.add(at ? Layout::Positioned.new(node, x: at[0], y: at[1]) : node)
+    end
+
+    def field_label(label)
+      style = @_builder.style
+      Layout::Text.new([Text::Run.new(label.to_s, style)], context: @_builder.context(style))
+    end
+  end
+end

data/lib/stationery/elements/lists.rb

@@ -4,6 +4,9 @@ module Stationery
   # Bulleted and numbered lists.
   module Elements
     BULLETS = %i[disc circle square].freeze
+    # ListNumbering for tagged PDF, by bullet shape and number format.
+    NUMBERING = { disc: :Disc, circle: :Circle, square: :Square, decimal: :Decimal, alpha: :LowerAlpha,
+                  upper_alpha: :UpperAlpha, roman: :LowerRoman, upper_roman: :UpperRoman }.freeze
 
     # A bulleted list. `style:` is :disc, :circle, :square, :dash or any
     # String; unstyled nested lists cycle disc → circle → square. Every node
@@ -11,7 +14,8 @@ module Stationery
     def ul(style: nil, gap: 4, indent: nil, marker_gap: 6, marker_color: nil, &)
       shape = style || BULLETS[@_builder.list_depth % BULLETS.size]
       marker_style = @_builder.style({ color: marker_color }.compact)
-      list(marker_style, gap:, indent:, marker_gap:, marker: ->(_) { list_bullet(shape, marker_style) }, &)
+      list(marker_style, gap:, indent:, marker_gap:, marker: ->(_) { list_bullet(shape, marker_style) },
+                         numbering: shape, &)
     end
 
     # A numbered list. `format:` is :decimal, :alpha, :upper_alpha, :roman,
@@ -19,7 +23,7 @@ module Stationery
     def ol(format: :decimal, start: 1, suffix: ".", gap: 4, indent: nil, marker_gap: 6, marker_color: nil, &)
       marker_style = @_builder.style({ color: marker_color }.compact)
       label = ->(index) { list_label(ListMarkers.label(format, start + index, suffix), marker_style) }
-      list(marker_style, gap:, indent:, marker_gap:, marker: label, &)
+      list(marker_style, gap:, indent:, marker_gap:, marker: label, numbering: format, &)
     end
 
     # A list item: a String becomes a paragraph (taking every text option),
@@ -32,7 +36,7 @@ module Stationery
 
     private
 
-    def list(marker_style, gap:, indent:, marker_gap:, marker:, &)
+    def list(marker_style, gap:, indent:, marker_gap:, marker:, numbering:, &)
       items = Builder::Items.new
       @_builder.nested_list { @_builder.within(items) { yield_content(&) } }
       markers = items.nodes.each_index.map(&marker)
@@ -40,7 +44,12 @@ module Stationery
       entries = items.nodes.zip(markers).map do |node, mark|
         Layout::ListItem.new(mark, node.is_a?(Layout::Flow) ? node : Layout::Flow.new([node]), indent:, marker_gap:)
       end
-      @_builder.add(Layout::Flow.new(entries, gap:))
+      @_builder.add(Layout::Flow.new(entries, gap:, tag: list_tag(numbering)))
+    end
+
+    def list_tag(numbering)
+      numbering = NUMBERING[numbering] if numbering.is_a?(Symbol)
+      Tagging::Element.new(:L, attributes: numbering ? { List: { ListNumbering: numbering } } : {})
     end
 
     def list_bullet(shape, style)
@@ -52,7 +61,8 @@ module Stationery
     end
 
     def list_label(label, style)
-      Layout::Text.new([Text::Run.new(label, style)], context: @_builder.context(style), align: :right)
+      Layout::Text.new([Text::Run.new(label, style)], context: @_builder.context(style), align: :right,
+                                                      tag: Tagging::Element.new(:Lbl))
     end
   end
 end

data/lib/stationery/elements.rb

@@ -6,21 +6,23 @@ module Stationery
     PARAGRAPH_DEFAULTS = { align: :left, leading: 0 }.freeze
 
     # A paragraph. Plain strings are always literal; pass `markup: true` to
-    # read inline tags, or a block to build styled runs in Ruby.
+    # read inline tags, or a block to build styled runs in Ruby. `heading: 1..6`
+    # tags it as a heading in a tagged PDF.
     def text(content = nil, markup: false, keep_with_next: nil, break_inside: nil, anchor: nil, bookmark: nil,
-             **options, &)
+             heading: nil, **options, &)
       settings = PARAGRAPH_DEFAULTS.merge(@_builder.text_defaults.slice(:align, :leading)).merge(options)
       style = @_builder.style(options)
       runs = text_runs(content, style, markup, &)
       node = Layout::Text.new(runs, context: @_builder.context(style), align: settings[:align],
-                                    leading: settings[:leading])
+                                    leading: settings[:leading], tag: Tagging::Element.new(Tagging.heading(heading)))
       node.keep_with_next = keep_with_next
       node.break_inside = break_inside
       @_builder.add(mark(node, anchor, bookmark))
     end
 
     # A container with padding, background, border and radius. `at: [x, y]`
-    # places it at a fixed page position outside the flow.
+    # places it at a fixed page position outside the flow. `role:` (:section,
+    # :blockquote, :note, :caption, …) groups its content in a tagged PDF.
     # `break_inside: :auto` splits it at any page break, `:avoid` never; by
     # default it splits only when it does not fit on a page of its own.
     def box(at: nil, align: nil, gap: 0, width: nil, keep_with_next: nil, break_inside: nil, anchor: nil, bookmark: nil,
@@ -65,15 +67,15 @@ module Stationery
     end
 
     # An SVG drawing: markup String, or a path to a .svg file. `currentColor`
-    # takes `color:`.
-    def svg(source, width: nil, height: nil, color: "#000000", align: nil)
+    # takes `color:`. `alt:` describes it in a tagged PDF (false: decorative).
+    def svg(source, width: nil, height: nil, color: "#000000", align: nil, alt: nil)
       name = source.to_s.lstrip.start_with?("<") ? "inline" : File.basename(source.to_s)
       source = File.read(source.to_s) unless name == "inline"
       document = SVG::Document.parse(source)
       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, alt:)
       @_builder.add(align ? Layout::Flow.new([node], align:) : node)
     end
 
@@ -95,6 +97,7 @@ module Stationery
       @_builder.add(node)
     end
 
+    # `alt:` describes the image in a tagged PDF (false: decorative).
     def image(source, align: nil, **)
       node = Layout::Image.new(source, **)
       @_builder.add(align ? Layout::Flow.new([node], align:) : node)

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