stationery 0.6.0 → 0.7.0

data/lib/stationery/hyphenation.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Stationery
+  # Liang's hyphenation over the TeX `hyph-utf8` patterns bundled under
+  # hyphenation/patterns/ (see LICENSES.md there). A language loads on first
+  # use and stays cached per process.
+  #
+  #   Stationery::Hyphenation.hyphenate("Silbentrennung", "de") # => ["Sil", "ben", "tren", "nung"]
+  #   Stationery::Hyphenation.points("hyphenation", "en")       # => [2, 6]
+  module Hyphenation
+    PATTERNS = File.expand_path("hyphenation/patterns", __dir__)
+
+    # Language tags accepted by `hyphenate:`, mapped to a bundled pattern set.
+    LANGUAGES = {
+      "en" => "en-us", "en-us" => "en-us", "en_us" => "en-us",
+      "de" => "de-1996", "de-1996" => "de-1996", "de-de" => "de-1996",
+      "sv" => "sv", "sv-se" => "sv"
+    }.freeze
+
+    # Letters kept intact at either end of a word (the pattern sets' own
+    # typesetting minimums).
+    MINIMUMS = { "en-us" => [2, 3], "de-1996" => [2, 2], "sv" => [2, 2] }.freeze
+
+    LOCK = Mutex.new
+
+    # One pattern set: the patterns keyed by their letters, the longest
+    # pattern's length and the exception list.
+    class Patterns
+      attr_reader :left_min, :right_min
+
+      def initialize(tag)
+        @left_min, @right_min = MINIMUMS.fetch(tag)
+        @patterns = {}
+        @longest = 0
+        @exceptions = {}
+        load_patterns(File.join(PATTERNS, "#{tag}.pat.txt"))
+        exceptions = File.join(PATTERNS, "#{tag}.hyp.txt")
+        load_exceptions(exceptions) if File.exist?(exceptions)
+      end
+
+      # Indexes where `word` may break (a break before word[index]),
+      # honouring the minimums.
+      def points(word)
+        key = word.downcase
+        return @exceptions[key] if @exceptions.key?(key)
+
+        levels = levels_for(".#{key}.")
+        (left_min..(word.length - right_min)).select { |index| levels[index].odd? }
+      end
+
+      private
+
+      def load_patterns(path)
+        File.foreach(path, chomp: true) do |line|
+          next if line.empty? || line.start_with?("%")
+
+          letters = line.delete("0-9")
+          values = Array.new(letters.length + 1, 0)
+          position = 0
+          line.each_char do |char|
+            if char.match?(/\d/) then values[position] = char.to_i
+            else position += 1
+            end
+          end
+          @patterns[letters] = values
+          @longest = letters.length if letters.length > @longest
+        end
+      end
+
+      # "as-so-ciate" → { "associate" => [2, 4] }
+      def load_exceptions(path)
+        File.foreach(path, chomp: true) do |line|
+          next if line.empty? || line.start_with?("%")
+
+          pieces = line.downcase.split("-")
+          positions = pieces[0..-2].each_with_object([]) { |piece, list| list << (list.last.to_i + piece.length) }
+          @exceptions[pieces.join] = positions
+        end
+      end
+
+      # Liang: the highest digit any matching pattern puts between two
+      # letters of the dotted word; odd means a break may go there. Index i
+      # in the result is the gap before letter i of the undotted word.
+      def levels_for(dotted)
+        levels = Array.new(dotted.length + 1, 0)
+        dotted.length.times do |start|
+          1.upto([@longest, dotted.length - start].min) do |length|
+            values = @patterns[dotted[start, length]] or next
+            values.each_with_index do |value, offset|
+              levels[start + offset] = value if value > levels[start + offset]
+            end
+          end
+        end
+        levels.drop(1)
+      end
+    end
+
+    module_function
+
+    # The bundled pattern set for a `hyphenate:` value: true is English,
+    # a tag is looked up case-insensitively; nil for false or nil.
+    def tag(value)
+      return nil if value.nil? || value == false
+      return "en-us" if value == true
+
+      LANGUAGES.fetch(value.to_s.downcase) do
+        raise ArgumentError, "unknown hyphenation language #{value.inspect} (bundled: #{LANGUAGES.keys.join(", ")})"
+      end
+    end
+
+    def patterns(language)
+      tag = tag(language)
+      @sets ||= {} # rubocop:disable ThreadSafety/ClassInstanceVariable
+      LOCK.synchronize { @sets[tag] ||= Patterns.new(tag) }
+    end
+
+    # Indexes where `word` may be broken (before word[index]); an empty
+    # array for a word too short to break or holding anything but letters.
+    def points(word, language)
+      return [] unless word.match?(/\A\p{L}+\z/)
+
+      patterns(language).points(word)
+    end
+
+    # The word cut at its break points.
+    def hyphenate(word, language)
+      last = 0
+      pieces = points(word, language).map { |index| word[last...index].tap { last = index } }
+      pieces << word[last..]
+    end
+  end
+end

data/lib/stationery/images/png.rb

@@ -9,6 +9,8 @@ module Stationery
     # mask for grey/RGB tRNS).
     class PNG
       CHANNELS = { 0 => 1, 2 => 3, 3 => 1, 4 => 2, 6 => 4 }.freeze
+      # Colour samples per pixel once palette and alpha are unpacked.
+      COLOR_CHANNELS = { 0 => 1, 2 => 3, 3 => 3, 4 => 1, 6 => 3 }.freeze
 
       attr_reader :width, :height
 
@@ -21,6 +23,13 @@ module Stationery
 
       def inspect = "#<#{self.class} #{@width}x#{@height}>"
 
+      # This image scaled down to `width` pixels (a Resampled), memoised per
+      # width; the same instance is shared through the image cache.
+      def resample(width)
+        @resampled ||= {}
+        @resampled[width] ||= Resampled.new(pixels, width)
+      end
+
       def build(writer)
         return build_with_alpha(writer) if alpha_channel?
 
@@ -38,6 +47,63 @@ module Stationery
 
       private
 
+      # Every sample as 8 bits, colour rows apart from alpha rows: palette and
+      # sub-byte greys expanded, 16-bit samples dropped to their high byte, a
+      # colour-key or palette transparency turned into an alpha row set.
+      def pixels
+        channels = CHANNELS[@color_type]
+        color = []
+        alpha = []
+        Scanlines.each(@idat, @height, [(channels * @bit_depth) / 8, 1].max,
+                       ((@width * channels * @bit_depth) + 7) / 8) do |row|
+          samples = samples_of(row)
+          case @color_type
+          when 3 then palette_pixels(samples, color, alpha)
+          when 4, 6 then split_pixels(samples, channels, color, alpha)
+          else keyed_pixels(samples, channels, color, alpha)
+          end
+        end
+        Pixels.new(width: @width, height: @height, channels: COLOR_CHANNELS[@color_type],
+                   color:, alpha: alpha.empty? ? nil : alpha)
+      end
+
+      # A row's samples at 8 bits.
+      def samples_of(row)
+        case @bit_depth
+        when 8 then row
+        when 16 then row.each_slice(2).map(&:first)
+        else
+          scale = 255 / ((1 << @bit_depth) - 1)
+          bits = row.pack("C*").unpack1("B*")
+          values = bits.scan(/.{#{@bit_depth}}/o).first(@width).map { |b| b.to_i(2) }
+          @color_type == 3 ? values : values.map { |v| v * scale }
+        end
+      end
+
+      def palette_pixels(indexes, color, alpha)
+        palette = @palette.bytes
+        alphas = @transparency&.bytes
+        color << indexes.flat_map { |i| palette[i * 3, 3] }
+        alpha << indexes.map { |i| alphas[i] || 255 } if alphas
+      end
+
+      def split_pixels(samples, channels, color, alpha)
+        color << samples.each_slice(channels).flat_map { |px| px[0...-1] }
+        alpha << samples.each_slice(channels).map(&:last)
+      end
+
+      # Grey or RGB, with a tRNS colour key (compared at the file's bit depth)
+      # becoming a fully transparent alpha.
+      def keyed_pixels(samples, channels, color, alpha)
+        color << samples
+        return unless @transparency
+
+        key = @transparency.unpack("n*").first(channels).map do |v|
+          @bit_depth == 16 ? v >> 8 : v * (255 / ((1 << @bit_depth) - 1))
+        end
+        alpha << samples.each_slice(channels).map { |px| px == key ? 0 : 255 }
+      end
+
       def read_chunks(data)
         pos = PNG_SIGNATURE.bytesize
         while pos + 8 <= data.bytesize

data/lib/stationery/images/resampled.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module Stationery
+  module Images
+    # A decoded image scaled down to a pixel width with a box filter (every
+    # source pixel of a block weighs the same), embedded as 8-bit grey or RGB
+    # with the alpha, when there is one, in a soft mask. Built by
+    # PNG#resample; JPEG data is never decoded, so it never comes here.
+    class Resampled
+      attr_reader :width, :height
+
+      # `pixels` is a Pixels: rows of 8-bit samples, `channels` colour samples
+      # per pixel (1 or 3) and an optional alpha row set.
+      def initialize(pixels, width)
+        @channels = pixels.channels
+        @width = [width, 1].max
+        @height = [(pixels.height * @width / pixels.width.to_f).round, 1].max
+        @color = shrink(pixels.color, pixels.width, pixels.height, @channels)
+        @alpha = pixels.alpha && shrink(pixels.alpha, pixels.width, pixels.height, 1)
+      end
+
+      def inspect = "#<#{self.class} #{@width}x#{@height}>"
+
+      def build(writer)
+        color_space = @channels == 1 ? :DeviceGray : :DeviceRGB
+        dictionary = Images.xobject(@width, @height, color_space, 8).merge(Filter: :FlateDecode)
+        if @alpha
+          mask = Images.xobject(@width, @height, :DeviceGray, 8).merge(Filter: :FlateDecode)
+          dictionary[:SMask] = writer.add(PDF::Stream.new(Zlib::Deflate.deflate(@alpha), mask))
+        end
+        writer.add(PDF::Stream.new(Zlib::Deflate.deflate(@color), dictionary))
+      end
+
+      private
+
+      # Box filter: output pixel (ox, oy) averages the source block whose edges
+      # are the scaled output edges. Row sums are accumulated per output column
+      # first so every source sample is visited once.
+      def shrink(rows, source_width, source_height, channels)
+        columns = spans(source_width, @width)
+        bands = spans(source_height, @height)
+        out = String.new(capacity: @width * @height * channels, encoding: Encoding::BINARY)
+        bands.each do |y0, y1|
+          sums = Array.new(@width * channels, 0)
+          (y0...y1).each { |y| add_row(sums, rows[y], columns, channels) }
+          count = y1 - y0
+          columns.each_with_index do |(x0, x1), ox|
+            n = (x1 - x0) * count
+            channels.times { |c| out << (sums[(ox * channels) + c] / n) }
+          end
+        end
+        out
+      end
+
+      def add_row(sums, row, columns, channels)
+        columns.each_with_index do |(x0, x1), ox|
+          base = ox * channels
+          (x0...x1).each do |x|
+            offset = x * channels
+            channels.times { |c| sums[base + c] += row[offset + c] }
+          end
+        end
+      end
+
+      # [start, end) source indexes for each of `target` output positions;
+      # every source index lands in exactly one span.
+      def spans(source, target)
+        Array.new(target) do |i|
+          [(i * source) / target, (((i + 1) * source) / target).clamp(((i * source) / target) + 1, source)]
+        end
+      end
+    end
+
+    # Decoded PNG samples: `color` and `alpha` are Arrays of rows, each row an
+    # Array of 8-bit sample values (`channels` per pixel for colour, one for alpha).
+    Pixels = Data.define(:width, :height, :channels, :color, :alpha)
+  end
+end

data/lib/stationery/layout/image.rb

@@ -9,14 +9,25 @@ module Stationery
     # `radius:` clips to rounded corners and `rotate:` (degrees, clockwise)
     # turns the painted image around the centre of its rectangle; neither
     # changes the space the image takes up.
+    #
+    # A bitmap keeps its pixels: drawn at more than twice `max_ppi:` (300;
+    # nil disables) it is reported as a Warnings::OversizedImage, and with
+    # `downscale: true` a PNG is resampled to `max_ppi` at its drawn size
+    # instead (a JPEG is never re-encoded; resize it before embedding).
     class Image < Node
+      DEFAULT_MAX_PPI = 300
+
       # `alt:` describes the image in a tagged PDF; `alt: false` marks it decorative.
-      def initialize(source, width: nil, height: nil, fit: nil, opacity: nil, alt: nil, radius: 0, rotate: 0)
+      def initialize(source, width: nil, height: nil, fit: nil, opacity: nil, alt: nil, radius: 0, rotate: 0,
+                     max_ppi: DEFAULT_MAX_PPI, downscale: false)
         raise ArgumentError, "fit: :cover needs width: and height:" if fit == :cover && !(width && height)
 
         super()
         @tag = alt == false ? nil : Tagging::Element.new(:Figure, alt:, kind: :image)
         @image = source.respond_to?(:build) ? source : Images.load(source)
+        @name = source.is_a?(String) || source.is_a?(Pathname) ? File.basename(source.to_s) : "inline image"
+        @max_ppi = max_ppi
+        @downscale = downscale
         @width = width
         @height = height
         @fit = fit
@@ -63,7 +74,22 @@ module Stationery
           w = cw
           h = ch
         end
-        canvas.image(@image, x:, y:, width: w, height: h, opacity: @opacity)
+        canvas.image(bitmap(canvas, w), x:, y:, width: w, height: h, opacity: @opacity)
+      end
+
+      # The image to embed for a drawn width: resampled to the ppi limit when
+      # asked and possible, else the source, reported when it is oversized.
+      def bitmap(canvas, drawn_width)
+        return @image unless @max_ppi
+
+        wanted = (drawn_width / 72.0 * @max_ppi).ceil
+        return @image.resample(wanted) if @downscale && @image.width > wanted && @image.respond_to?(:resample)
+
+        ppi = (@image.width * 72.0 / drawn_width).round
+        if ppi > 2 * @max_ppi && canvas.warnings
+          canvas.warnings << Warnings::OversizedImage.new(source: @name, pixels: @image.width, ppi:, limit: @max_ppi)
+        end
+        @image
       end
 
       def requested

data/lib/stationery/layout/paginator.rb

@@ -62,7 +62,7 @@ module Stationery
         box = page.content_box
         height = head.measure(box.width)
         @warnings << Overflow.new(page: number, height:, available: box.height) if height > box.height + EPSILON
-        canvas = Canvas.new(page, @resources, debug: @debug, tagging: @tagging)
+        canvas = Canvas.new(page, @resources, debug: @debug, tagging: @tagging, warnings: @warnings)
         head.paint(canvas, box.x, box.y, box.width)
         canvas.debug_rect(box.x, box.y, box.width, box.height, :page)
       end

data/lib/stationery/layout/text.rb

@@ -42,9 +42,9 @@ module Stationery
         @min_width ||= @runs.flat_map do |run|
           style = run.style
           font = @context.book.resolve(style).first
-          run.text.split(/[ \t\n]+/).map do |word|
+          run.text.delete(::Stationery::Text::Wrapper::SOFT_HYPHEN).split(/[ \t\n]+/).map do |word|
             font.width_of(word, style.render_size, letter_spacing: style.letter_spacing, kerning: style.kerning,
-                                                   ligatures: style.ligatures)
+                                                   ligatures: style.ligatures, features: style.features)
           end
         end.max || 0
       end

data/lib/stationery/minitest.rb

@@ -17,6 +17,11 @@ module Stationery
       def assert_image_count(subject, count, msg = nil) = assert_pdf(Matchers::HaveImageCount.new(count), subject, msg)
       def assert_bookmark(subject, title, msg = nil) = assert_pdf(Matchers::HaveBookmark.new(title), subject, msg)
       def assert_pdf_language(subject, lang, msg = nil) = assert_pdf(Matchers::HaveLanguage.new(lang), subject, msg)
+
+      def assert_page_labels(subject, labels, msg = nil)
+        assert_pdf(Matchers::HavePageLabels.new(labels), subject, msg)
+      end
+
       def assert_no_pdf_warnings(subject, msg = nil) = assert_pdf(Matchers::HaveNoWarnings.new, subject, msg)
       def assert_pdf_structure(subject, tree, msg = nil) = assert_pdf(Matchers::HaveStructure.new(tree), subject, msg)
       def assert_tagged_content(subject, msg = nil) = assert_pdf(Matchers::HaveTaggedContent.new, subject, msg)

data/lib/stationery/page_templates.rb

@@ -54,7 +54,8 @@ module Stationery
     # Everything a template paints is a pagination artifact in a tagged PDF.
     def paint(page, root, rect, layer = :foreground, subtype: nil)
       mark = page.content.bytesize
-      canvas = Canvas.new(page, @resources, template: true, debug: @debug, tagging: @tagging)
+      canvas = Canvas.new(page, @resources, template: true, debug: @debug, tagging: @tagging,
+                                            warnings: @warnings)
       canvas.artifact(type: :pagination, subtype:) { root.paint(canvas, rect.x, rect.y, rect.width) }
       page.content.prepend(page.content.slice!(mark..)) if layer == :background
     end

data/lib/stationery/pdf/assembler.rb

@@ -5,10 +5,13 @@ module Stationery
     # Writes finished pages, their shared resources and document info as PDF.
     class Assembler
       # `tagging:` (a Tagging::Tree) writes the structure tree of a tagged PDF;
-      # `lang:` is the document's natural language.
-      def initialize(pages:, resources:, info: {}, outline: [], encryption: nil, tagging: nil, lang: nil)
+      # `lang:` is the document's natural language; `page_labels:` is the
+      # /PageLabels number tree from PageLabels.entries.
+      def initialize(pages:, resources:, info: {}, outline: [], encryption: nil, tagging: nil, lang: nil,
+                     page_labels: nil)
         @tagging = tagging
         @lang = lang
+        @page_labels = page_labels
         @pages = pages
         @resources = resources
         @info = info
@@ -34,6 +37,7 @@ module Stationery
 
       def catalog(tree, outlines, form)
         catalog = { Type: :Catalog, Pages: tree }
+        catalog[:PageLabels] = @page_labels if @page_labels
         catalog[:AcroForm] = form if form
         outlines ? catalog.merge(Outlines: outlines, PageMode: :UseOutlines) : catalog
       end

data/lib/stationery/pdf/page_labels.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Stationery
+  module PDF
+    # The /PageLabels number tree: how viewers name pages ("i", "ii", "1",
+    # "A-1"). A spec maps a 1-based first page to the range starting there:
+    #
+    #   { 1 => { style: :roman_lower }, 3 => { style: :decimal, start: 1, prefix: "A-" } }
+    #
+    # Styles are :decimal, :roman, :roman_lower, :alpha, :alpha_lower or nil
+    # (prefix only). Pages before the first range have no label; viewers show
+    # their physical number.
+    module PageLabels
+      STYLES = { decimal: :D, roman: :R, roman_lower: :r, alpha: :A, alpha_lower: :a }.freeze
+      NUMERALS = { D: :decimal, R: :upper_roman, r: :roman, A: :upper_alpha, a: :alpha }.freeze
+      KEYS = %i[style start prefix].freeze
+
+      module_function
+
+      # The number tree dictionary for a spec, or nil for none.
+      def entries(spec)
+        return if spec.nil? || spec.empty?
+
+        nums = spec.sort_by { |page, _| validate_page(page) }.flat_map do |page, range|
+          [page - 1, entry(page, range)]
+        end
+        { Nums: nums }
+      end
+
+      # The label of each of `count` pages from a /Nums array (as read back).
+      def labels(nums, count)
+        ranges = nums.each_slice(2).to_a
+        Array.new(count) do |index|
+          start, dict = ranges.reverse.find { |from, _| from <= index }
+          dict && label(dict, index - start)
+        end
+      end
+
+      def validate_page(page)
+        return page if page.is_a?(Integer) && page >= 1
+
+        raise ArgumentError, "page labels start at page 1, not page #{page.inspect}"
+      end
+
+      def entry(page, range)
+        unknown = range.keys - KEYS
+        raise ArgumentError, "unknown page label option #{unknown.first.inspect} for page #{page}" if unknown.any?
+
+        style = range[:style]
+        raise ArgumentError, "unknown page label style #{style.inspect}" unless style.nil? || STYLES.key?(style)
+
+        start = range[:start]
+        if start && !(start.is_a?(Integer) && start >= 1)
+          raise ArgumentError, "page label start #{start.inspect} for page #{page} must be 1 or more"
+        end
+
+        entry = {}
+        entry[:S] = STYLES[style] if style
+        entry[:St] = start if start
+        entry[:P] = TextString.new(range[:prefix].to_s) if range[:prefix]
+        entry
+      end
+
+      def label(dict, offset)
+        numeral = NUMERALS[dict[:S]&.to_sym]
+        number = (dict[:St] || 1) + offset
+        "#{dict[:P]}#{ListMarkers.numeral(numeral, number) if numeral}"
+      end
+    end
+  end
+end

data/lib/stationery/testing/inspector.rb

@@ -70,6 +70,17 @@ module Stationery
         decode(lang) if lang
       end
 
+      # One label per page from the catalog /PageLabels ("i", "A-1", …), nil
+      # for pages before the first labelled range; empty without labels.
+      def page_labels
+        labels = catalog[:PageLabels]
+        return [] unless labels
+
+        nums = objects.deref_array(objects.deref_hash(labels)[:Nums]).map { |value| objects.deref(value) }
+        nums = nums.map { |value| value.is_a?(Hash) ? value.transform_values { |v| decode_value(v) } : value }
+        PDF::PageLabels.labels(nums, page_count)
+      end
+
       # The structure tree of a tagged PDF as nested arrays; see StructureReader.
       def structure = @structure ||= StructureReader.new(reader).tree
 
@@ -109,6 +120,8 @@ module Stationery
         [decode(item[:Title]), *titles(item[:First]), *titles(item[:Next])]
       end
 
+      def decode_value(value) = value.is_a?(String) ? decode(value) : value
+
       def decode(title)
         return title.dup.force_encoding(Encoding::UTF_8) unless title.b.start_with?(UTF16_BOM)
 

data/lib/stationery/testing/matchers.rb

@@ -110,6 +110,15 @@ module Stationery
         def actual = @inspector.lang ? "got #{@inspector.lang.inspect}" : "got none"
       end
 
+      class HavePageLabels < Base
+        def description = "have page labels #{@expected.inspect}"
+
+        private
+
+        def match?(pdf) = pdf.page_labels == @expected
+        def actual = @inspector.page_labels.empty? ? "got none" : "got #{@inspector.page_labels.inspect}"
+      end
+
       class HaveNoWarnings < Base
         def description = "have no warnings"
 
@@ -150,6 +159,7 @@ module Stationery
       def have_image_count(expected) = HaveImageCount.new(expected)
       def have_bookmark(title) = HaveBookmark.new(title)
       def have_pdf_language(lang) = HaveLanguage.new(lang)
+      def have_page_labels(labels) = HavePageLabels.new(labels)
       def have_no_warnings = HaveNoWarnings.new
       def have_structure(expected) = HaveStructure.new(expected)
       def have_tagged_content = HaveTaggedContent.new

data/lib/stationery/text/entities.rb

@@ -2,23 +2,33 @@
 
 module Stationery
   module Text
-    # Decodes the HTML entities markup text may carry.
+    # Decodes the HTML character references markup text may carry: numeric
+    # (`'`, `'`, `'`) and named (the built-ins below, then the
+    # HTML 4 table). Each reference is decoded once, so `'` yields the
+    # literal text `'`; an unknown name, a malformed reference or a code
+    # point outside Unicode stays as written.
     module Entities
       NAMED = { "amp" => "&", "lt" => "<", "gt" => ">", "quot" => "\"", "apos" => "'", "nbsp" => " " }.freeze
-      PATTERN = /&(#x\h+|#\d+|[a-zA-Z]+);/
+      PATTERN = /&(#[xX]\h+|#\d+|[a-zA-Z]+);/
+      MAX_CODE_POINT = 0x10FFFF
+      SURROGATES = (0xD800..0xDFFF)
 
       module_function
 
       def decode(text)
         text.gsub(PATTERN) do |entity|
           name = Regexp.last_match(1)
-          if name.start_with?("#x") then [name[2..].to_i(16)].pack("U")
-          elsif name.start_with?("#") then [name[1..].to_i].pack("U")
+          if name.start_with?("#x", "#X") then character(name[2..].to_i(16), entity)
+          elsif name.start_with?("#") then character(name[1..].to_i, entity)
           else NAMED.fetch(name) { html4.fetch(name, entity) }
           end
         end
       end
 
+      def character(code, entity)
+        code.between?(1, MAX_CODE_POINT) && !SURROGATES.cover?(code) ? [code].pack("U") : entity
+      end
+
       def html4
         require_relative "entities/html4" unless defined?(HTML4)
         HTML4

data/lib/stationery/text/paragraph.rb

@@ -117,7 +117,7 @@ module Stationery
                                            color: style.color, letter_spacing: style.letter_spacing, rise: style.rise,
                                            opacity: style.opacity, underline: style.underline,
                                            strikethrough: style.strikethrough, kerning: style.kerning,
-                                           ligatures: style.ligatures,
+                                           ligatures: style.ligatures, features: style.features,
                                            synthetic_bold: fragment.face.synthetic_bold,
                                            synthetic_oblique: fragment.face.synthetic_oblique, word_spacing:)
         canvas.link(x, top, width, line.height, style.link, tag: link) if style.link

data/lib/stationery/text/style.rb

@@ -3,15 +3,26 @@
 module Stationery
   module Text
     SCRIPT_SCALE = 0.583
+    NO_FEATURES = [].freeze
 
     # How a run of text looks. Immutable; derive variants with #with.
+    # `hyphenate` is a bundled hyphenation language (see Hyphenation) or nil.
     Style = Data.define(:family, :size, :weight, :style, :color, :letter_spacing,
                         :underline, :strikethrough, :script, :link, :opacity, :kerning,
-                        :ligatures) do
+                        :ligatures, :features, :hyphenate) do
+      # `features:` are OpenType feature tags (`:smcp`, `"onum"`, …) applied on
+      # top of `ligatures:`; kept as sorted frozen Strings so equal sets are
+      # equal styles.
       def initialize(family:, size: 10, weight: :regular, style: :normal, color: "#000000", letter_spacing: 0,
                      underline: false, strikethrough: false, script: nil, link: nil, opacity: nil, kerning: true,
-                     ligatures: true)
-        super
+                     ligatures: true, features: NO_FEATURES, hyphenate: nil)
+        super(family:, size:, weight:, style:, color:, letter_spacing:, underline:, strikethrough:, script:, link:,
+              opacity:, kerning:, ligatures:, features: Style.features(features), hyphenate: Hyphenation.tag(hyphenate))
+      end
+
+      def self.features(tags)
+        tags = Array(tags).map(&:to_s).uniq.sort
+        tags.empty? ? NO_FEATURES : tags.freeze
       end
 
       # The size glyphs are drawn at: smaller for sub- and superscript.