stationery 0.2.0 → 0.4.0

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)

data/lib/stationery/fonts/true_type.rb

@@ -3,9 +3,9 @@
 module Stationery
   module Fonts
     # Reads the sfnt tables of a static font needed to measure text and to
-    # embed it: TrueType outlines (.ttf) or CFF outlines (.otf). Variable CFF2
-    # fonts, font collections and web font wrappers are rejected with a named
-    # reason.
+    # embed it: TrueType outlines (.ttf) or CFF outlines (.otf), alone or as one
+    # face of a collection (.ttc), or unwrapped from a WOFF web font. Variable
+    # CFF2 fonts and WOFF2 are rejected with a named reason.
     class TrueType
       include SfntMetrics
 
@@ -13,10 +13,9 @@ module Stationery
       OUTLINE_TABLES = { "OTTO" => ["CFF "] }.freeze
       GLYF_TABLES = %w[loca glyf].freeze
       SFNT_VERSIONS = ["\x00\x01\x00\x00".b, "true", "OTTO"].freeze
+      COLLECTION = "ttcf"
       SIGNATURES = {
-        "ttcf" => "TrueType collections (.ttc) are not supported, use a single TrueType (.ttf) font",
-        "wOFF" => "WOFF web fonts are not supported, use the TrueType (.ttf) file",
-        "wOF2" => "WOFF2 web fonts are not supported, use the TrueType (.ttf) file"
+        "wOF2" => "WOFF2 needs Brotli; convert to .ttf or .woff"
       }.freeze
 
       attr_reader :data, :tables, :units_per_em, :bbox, :ascender, :descender, :line_gap, :num_glyphs,
@@ -24,9 +23,12 @@ module Stationery
                   :strikeout_position, :strikeout_size, :cap_height, :x_height, :weight, :postscript_name
 
       # A subset embedded in a PDF carries no cmap (the PDF maps glyphs itself),
-      # so reading one back passes `cmap: false`.
-      def initialize(data, cmap: true)
+      # so reading one back passes `cmap: false`. `index:` picks a face of a
+      # collection, face 0 by default.
+      def initialize(data, cmap: true, index: nil)
         @data = data.b
+        @data = WOFF.unpack(@data) if @data.start_with?(WOFF::SIGNATURE)
+        @sfnt = face_offset(index || 0)
         check_signature
         read_table_directory(cmap)
         parse_head
@@ -40,6 +42,12 @@ module Stationery
         @postscript_name = NameTable.postscript_name(self)
       end
 
+      def self.collection?(data) = data.byteslice(0, 4) == COLLECTION
+
+      def self.faces(data)
+        collection?(data) ? data.byteslice(8, 4).unpack1("N") : 1
+      end
+
       def inspect = "#<#{self.class} #{@postscript_name} glyphs=#{@num_glyphs}>"
 
       def glyph_id(codepoint)
@@ -68,6 +76,11 @@ module Stationery
         @kerning ||= Kerning.for(self)
       end
 
+      # Standard ligatures, read on first use and shared like #kerning.
+      def ligatures
+        @ligatures ||= Ligatures.for(self)
+      end
+
       def cff?
         @tables.key?("CFF ")
       end
@@ -106,8 +119,19 @@ module Stationery
 
       private
 
+      # Table offsets in a collection are already absolute, so a face is read
+      # from the shared data at its own table directory.
+      def face_offset(index)
+        count = self.class.faces(@data)
+        unless index.between?(0, count - 1)
+          raise ArgumentError, "font face #{index} is out of range (numFonts #{count})"
+        end
+
+        self.class.collection?(@data) ? u32(12 + (index * 4)) : 0
+      end
+
       def check_signature
-        signature = @data.byteslice(0, 4)
+        signature = @data.byteslice(@sfnt, 4)
         return if SFNT_VERSIONS.include?(signature)
 
         raise UnsupportedFont, SIGNATURES.fetch(signature, "not a TrueType font")
@@ -115,13 +139,13 @@ module Stationery
 
       def read_table_directory(cmap)
         @tables = {}
-        u16(4).times do |i|
-          record = 12 + (i * 16)
+        u16(@sfnt + 4).times do |i|
+          record = @sfnt + 12 + (i * 16)
           @tables[@data.byteslice(record, 4)] = [u32(record + 8), u32(record + 12)]
         end
         raise UnsupportedFont, "variable CFF2 fonts are not supported" if @tables.key?("CFF2")
 
-        required = REQUIRED_TABLES + OUTLINE_TABLES.fetch(@data.byteslice(0, 4), GLYF_TABLES)
+        required = REQUIRED_TABLES + OUTLINE_TABLES.fetch(@data.byteslice(@sfnt, 4), GLYF_TABLES)
         required += ["cmap"] if cmap
         missing = required.reject { |tag| @tables.key?(tag) }
         raise UnsupportedFont, "font is missing the #{missing.map(&:strip).join(", ")} table" if missing.any?

data/lib/stationery/fonts/woff.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module Stationery
+  module Fonts
+    # Unwraps a WOFF 1.0 web font into the sfnt it was made from: each table is
+    # inflated (or copied when stored) and laid out behind a fresh table
+    # directory, 4-byte aligned in directory order. Metadata and private data
+    # blocks are dropped.
+    module WOFF
+      SIGNATURE = "wOFF"
+      HEADER = 44
+      ENTRY = 20
+
+      module_function
+
+      def unpack(data)
+        data = data.b
+        flavor = data.byteslice(4, 4)
+        tables = Array.new(data.byteslice(12, 2).unpack1("n")) do |i|
+          tag, offset, compressed, length, checksum = data.byteslice(HEADER + (i * ENTRY), ENTRY).unpack("a4NNNN")
+          [tag, checksum, table(tag, data.byteslice(offset, compressed), length)]
+        end
+        assemble(flavor, tables)
+      end
+
+      def table(tag, bytes, length)
+        return bytes if bytes.bytesize >= length
+
+        Zlib::Inflate.inflate(bytes)
+      rescue Zlib::Error
+        raise UnsupportedFont, "corrupt WOFF table #{tag}"
+      end
+
+      def assemble(flavor, tables)
+        entry_selector = Math.log2(tables.size).floor
+        search_range = (2**entry_selector) * 16
+        directory = [flavor, tables.size, search_range, entry_selector, (tables.size * 16) - search_range]
+                    .pack("a4nnnn")
+        body = String.new(encoding: Encoding::BINARY)
+        offset = 12 + (tables.size * 16)
+
+        tables.each do |tag, checksum, bytes|
+          directory << [tag, checksum, offset + body.bytesize, bytes.bytesize].pack("a4NNN")
+          body << bytes << ("\0".b * (-bytes.bytesize % 4))
+        end
+        directory << body
+      end
+    end
+  end
+end

data/lib/stationery/forms/acro_form.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Forms
+    # Collects the widgets pages place and writes the document's interactive
+    # form: one field per name, parent fields for dotted names, the shared
+    # Helvetica and ZapfDingbats resources and the catalog's /AcroForm.
+    class AcroForm
+      FONTS = { Helv: :Helvetica, ZaDb: :ZapfDingbats }.freeze
+
+      # A widget placed on a page: its field, PDF-space rect, page and the
+      # reference the page's /Annots already points at.
+      Widget = Data.define(:field, :rect, :page, :ref, :extra)
+
+      # A name segment: widgets when it is a field, children when a group.
+      Node = Struct.new(:name, :widgets, :children)
+
+      # { full name => value } for every field widget on `pages`.
+      def self.values(pages)
+        pages.flat_map(&:annotations).each_with_object({}) do |annotation, values|
+          field = annotation[:widget] or next
+          value = field.data_value
+          values[field.name] = value unless value.nil? && values.key?(field.name)
+        end
+      end
+
+      def initialize(writer)
+        @writer = writer
+        @widgets = []
+      end
+
+      # Reserves the widget annotation for `field` at `rect` on `page`.
+      # `extra` entries for the widget dictionary may be computed from its
+      # reference (a tagged PDF's /StructParent).
+      def add(field, rect, page)
+        ref = @writer.reserve
+        @widgets << Widget.new(field, rect, page, ref, block_given? ? yield(ref) : {})
+        ref
+      end
+
+      # Writes every field; returns the /AcroForm dictionary, or nil without
+      # fields.
+      def write
+        return if @widgets.empty?
+
+        @fonts = FONTS.transform_values { |base| @writer.add(font(base)) }
+        fields = tree.children.values.map { |node| write_node(node, nil) }
+        { Fields: fields, NeedAppearances: true, DA: "/#{Field::FONT} 0 Tf 0 g", DR: { Font: @fonts } }
+      end
+
+      private
+
+      def font(base)
+        font = { Type: :Font, Subtype: :Type1, BaseFont: base }
+        base == :Helvetica ? font.merge(Encoding: :WinAnsiEncoding) : font
+      end
+
+      def tree
+        root = Node.new(nil, [], {})
+        @widgets.each do |widget|
+          node = widget.field.segments.reduce(root) do |parent, segment|
+            parent.children[segment] ||= Node.new(segment, [], {})
+          end
+          node.widgets << widget
+        end
+        root.children.each_value { |node| validate(node, node.name) }
+        root
+      end
+
+      def validate(node, path)
+        if node.widgets.any? && node.children.any?
+          raise ArgumentError, "field name #{path.inspect} is both a field and a group"
+        end
+        if node.widgets.map { |widget| widget.field.kind }.uniq.size > 1
+          raise ArgumentError, "field name #{path.inspect} is used by fields of different kinds"
+        end
+
+        node.children.each_value { |child| validate(child, "#{path}.#{child.name}") }
+      end
+
+      def write_node(node, parent)
+        own = { T: PDF::TextString.new(node.name) }
+        own[:Parent] = parent if parent
+        return write_field(node.widgets, own) if node.widgets.any?
+
+        ref = @writer.reserve
+        @writer.set(ref, own.merge(Kids: node.children.values.map { |child| write_node(child, ref) }))
+      end
+
+      # One widget is merged with its field; several, or radios, become the
+      # field's kids. A radio group's value is its checked choice.
+      def write_field(widgets, own)
+        field = widgets.first.field
+        unless field.radio? || !widgets.one?
+          return @writer.set(widgets.first.ref, own.merge(field.field_entries, widget(widgets.first)))
+        end
+
+        ref = @writer.reserve
+        value = field.radio? ? widgets.map(&:field).find(&:checked?)&.on_state || :Off : nil
+        widgets.each { |kid| @writer.set(kid.ref, widget(kid, value).merge(Parent: ref)) }
+        entries = value ? field.field_entries(value) : field.field_entries
+        @writer.set(ref, own.merge(entries, Kids: widgets.map(&:ref)))
+      end
+
+      def widget(widget, group_value = nil)
+        x1, y1, x2, y2 = widget.rect
+        state = group_value && (widget.field.on_state == group_value ? group_value : :Off)
+        entries = widget.field.widget_entries(x2 - x1, y2 - y1, @fonts, state:)
+        normal = entries.dig(:AP, :N)
+        normal = normal.is_a?(Hash) ? normal.transform_values { |stream| @writer.add(stream) } : @writer.add(normal)
+        entries.merge(AP: { N: normal }, Rect: widget.rect, P: widget.page, **widget.extra)
+      end
+    end
+  end
+end

data/lib/stationery/forms/appearance.rb

@@ -0,0 +1,119 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Forms
+    # A widget's normal appearance: the form XObject(s) every viewer draws, so
+    # a form looks right without relying on the viewer to regenerate it.
+    # Variable text sits between `/Tx BMC … EMC`, the part a viewer redraws
+    # when the value changes.
+    class Appearance
+      PADDING = 2
+      LEADING = 1.15
+      CHECK = { glyph: "4", width: 0.846, middle: 0.345 }.freeze
+      DOT = 0.45
+      SIGNATURE = { rule: 14, label_size: 7, label_baseline: 4, label_gray: 0.42 }.freeze
+
+      def initialize(field, width, height, fonts)
+        @field = field
+        @width = width
+        @height = height
+        @fonts = fonts
+      end
+
+      # One stream, or a Hash of streams by appearance state for buttons.
+      def normal
+        case @field.kind
+        when :text, :select then stream(frame + variable_text(text_lines))
+        when :checkbox then { @field.on_state => stream(frame + check), Off: stream(frame) }
+        when :radio then { @field.on_state => stream(circle + dot), Off: stream(circle) }
+        when :signature then stream(signature)
+        end
+      end
+
+      private
+
+      def options = @field.options
+      def size = @field.font_size
+      def num(value) = PDF::Serializer.number(value.is_a?(Float) && value == value.round ? value.round : value)
+
+      def stream(content)
+        PDF::Stream.new(content, { Type: :XObject, Subtype: :Form, BBox: [0, 0, @width, @height],
+                                   Resources: { Font: @fonts } })
+      end
+
+      def frame
+        return +"" unless options[:background] || options[:border]
+
+        draw do |canvas|
+          canvas.rounded_rect(0.5, 0.5, @width - 1, @height - 1,
+                              radius: options[:radius], fill: options[:background], stroke: options[:border])
+        end
+      end
+
+      # [x, baseline, WinAnsi bytes] runs in PDF space.
+      def text_lines
+        return comb_cells if options[:comb]
+        return multiline_runs if options[:multiline]
+
+        [[PADDING, (@height / 2.0) - (size * (Metrics::ASCENT + Metrics::DESCENT) / 2), Metrics.encode(@field.value)]]
+      end
+
+      def multiline_runs
+        top = @height - PADDING - (size * Metrics::ASCENT)
+        Metrics.wrap(@field.value, @width - (2 * PADDING), size).each_with_index.map do |line, index|
+          [PADDING, top - (index * size * LEADING), line]
+        end
+      end
+
+      def comb_cells
+        cell = @width.fdiv(@field.max_length)
+        baseline = (@height / 2.0) - (size * (Metrics::ASCENT + Metrics::DESCENT) / 2)
+        Metrics.encode(@field.value)[0, @field.max_length].chars.each_with_index.map do |char, index|
+          [(index * cell) + ((cell - Metrics.width(char, size)) / 2), baseline, char]
+        end
+      end
+
+      def variable_text(runs)
+        ops = ["/Tx BMC", "q", "1 1 #{num(@width - 2)} #{num(@height - 2)} re W n", "0 g"]
+        runs.reject { |_, _, bytes| bytes.empty? }.each do |x, y, bytes|
+          ops.push("BT", "/#{Field::FONT} #{num(size)} Tf", "#{num(x)} #{num(y)} Td",
+                   "#{PDF::Serializer.literal(bytes)} Tj", "ET")
+        end
+        ops.push("Q", "EMC").join("\n") << "\n"
+      end
+
+      def circle
+        draw { |canvas| canvas.circle(*center, radius - 0.5, fill: options[:background], stroke: options[:border]) }
+      end
+
+      def dot = draw { |canvas| canvas.circle(*center, radius * DOT, fill: "#000000") }
+      def center = [@width / 2.0, @height / 2.0]
+      def radius = [@width, @height].min / 2.0
+
+      def signature
+        y = @height - SIGNATURE[:rule]
+        content = draw { |canvas| canvas.line(PADDING, y, @width - PADDING, y, color: options[:border], width: 0.75) }
+        label = Metrics.encode(options[:label])
+        return content if label.empty?
+
+        ops = ["q", "#{SIGNATURE[:label_gray]} g", "BT", "/#{Field::FONT} #{SIGNATURE[:label_size]} Tf",
+               "#{PADDING} #{SIGNATURE[:label_baseline]} Td", "#{PDF::Serializer.literal(label)} Tj", "ET", "Q"]
+        "#{content}#{ops.join("\n")}\n"
+      end
+
+      def draw
+        page = Page.new(size: [@width, @height])
+        yield Canvas.new(page, nil)
+        page.content
+      end
+
+      def check
+        glyph = [@width, @height].min * 0.8
+        x = (@width - (glyph * CHECK[:width])) / 2
+        y = (@height / 2.0) - (glyph * CHECK[:middle])
+        ["q", "0 g", "BT", "/ZaDb #{num(glyph)} Tf", "#{num(x)} #{num(y)} Td", "(#{CHECK[:glyph]}) Tj", "ET", "Q"]
+          .join("\n") << "\n"
+      end
+    end
+  end
+end

data/lib/stationery/forms/field.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+module Stationery
+  # Interactive form fields (AcroForm): what each one holds and how it is
+  # written, apart from where the layout puts it.
+  module Forms
+    # One form field widget: its kind, full (dotted) name, value and options.
+    # Widgets sharing a name form one field (a radio group); dotted names are
+    # grouped under parent fields.
+    class Field
+      TYPES = { text: :Tx, checkbox: :Btn, radio: :Btn, select: :Ch, signature: :Sig }.freeze
+      # Field flag bit positions (PDF 32000-1, 12.7.3.1 and 12.7.4).
+      BITS = { read_only: 1, required: 2, multiline: 13, no_toggle_to_off: 15, radio: 16, combo: 18, edit: 19,
+               comb: 25 }.freeze
+      DEFAULTS = { font_size: 10, read_only: false, required: false, border: "#9CA3AF", background: "#FFFFFF",
+                   radius: 2 }.freeze
+      OPTIONS = {
+        text: %i[multiline max_length comb], checkbox: [], radio: %i[checked], select: %i[options editable],
+        signature: %i[label]
+      }.freeze
+      FONT = "Helv"
+
+      attr_reader :kind, :name, :value, :options
+
+      def initialize(kind, name, value: nil, **options)
+        @kind = kind
+        @name = validate_name(name.to_s)
+        @value = value
+        unknown = options.keys - DEFAULTS.keys - OPTIONS.fetch(kind)
+        raise ArgumentError, "unknown #{kind} field option: #{unknown.join(", ")}" if unknown.any?
+
+        @options = DEFAULTS.merge(options)
+        validate_comb
+      end
+
+      def segments = @name.split(".")
+      def type = TYPES.fetch(@kind)
+      def font_size = @options[:font_size]
+      def default_appearance = "/#{FONT} #{PDF::Serializer.number(font_size)} Tf 0 g"
+      def max_length = @options[:comb].is_a?(Integer) ? @options[:comb] : @options[:max_length]
+      def radio? = @kind == :radio
+      def checked? = radio? ? @options[:checked] == true : @value == true
+
+      # The on-state of a button: /Yes, or a radio's export value.
+      def on_state = radio? ? @value.to_s.to_sym : :Yes
+
+      def flags
+        set = %i[read_only required].select { |key| @options[key] }
+        set += kind_flags
+        set.sum { |key| 1 << (BITS.fetch(key) - 1) }
+      end
+
+      # The field-level entries; the widget's come from #widget_entries.
+      # `value` overrides this widget's own: a radio group's checked choice.
+      def field_entries(value = field_value)
+        entries = { FT: type, DA: default_appearance }
+        entries[:Ff] = flags if flags.positive?
+        entries[:V] = value unless value.nil?
+        entries[:MaxLen] = max_length if max_length
+        entries[:Opt] = @options[:options].map { |option| PDF::TextString.new(option.to_s) } if @kind == :select
+        entries
+      end
+
+      # What Document#fields reports for this field.
+      def data_value
+        case @kind
+        when :checkbox then checked?
+        when :radio then checked? ? @value : nil
+        else @value
+        end
+      end
+
+      # `state` overrides the button's own appearance state.
+      def widget_entries(width, height, fonts, state: nil)
+        normal = Appearance.new(self, width, height, fonts).normal
+        entries = { Type: :Annot, Subtype: :Widget, F: 4, AP: { N: normal } }
+        entries[:MK] = appearance_characteristics unless @kind == :signature
+        entries[:AS] = state || (checked? ? on_state : :Off) if normal.is_a?(Hash)
+        entries
+      end
+
+      private
+
+      def field_value
+        case @kind
+        when :checkbox, :radio then checked? ? on_state : :Off
+        when :signature then nil
+        else @value.nil? ? nil : PDF::TextString.new(@value.to_s)
+        end
+      end
+
+      def kind_flags
+        case @kind
+        when :text then %i[multiline comb].select { |key| @options[key] }
+        when :radio then %i[radio no_toggle_to_off]
+        when :select then @options[:editable] ? %i[combo edit] : %i[combo]
+        else []
+        end
+      end
+
+      def appearance_characteristics
+        mk = {}
+        mk[:BG] = Color.parse(@options[:background]).components if @options[:background]
+        mk[:BC] = Color.parse(@options[:border]).components if @options[:border]
+        mk[:CA] = radio? ? "l" : "4" if type == :Btn
+        mk
+      end
+
+      def validate_name(name)
+        return name unless name.empty? || name.split(".", -1).any?(&:empty?)
+
+        raise ArgumentError, "invalid field name #{name.inspect}: use non-empty, dot-separated segments"
+      end
+
+      def validate_comb
+        return unless @options[:comb] && !max_length
+
+        raise ArgumentError, "a comb field needs max_length: (or comb: <cells>)"
+      end
+    end
+  end
+end

data/lib/stationery/forms/metrics.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Forms
+    # Helvetica's advance widths (the standard-14 AFM, in 1/1000 em) for the
+    # printable ASCII range, enough to lay out a field's appearance; other
+    # WinAnsi characters count as a digit's width.
+    module Metrics
+      ASCII = [
+        278, 278, 355, 556, 556, 889, 667, 191, 333, 333, 389, 584, 278, 333, 278, 278, # space - /
+        556, 556, 556, 556, 556, 556, 556, 556, 556, 556, 278, 278, 584, 584, 584, 556, # 0 - ?
+        1015, 667, 667, 722, 722, 667, 611, 778, 722, 278, 500, 667, 556, 833, 722, 778, # @ - O
+        667, 778, 722, 667, 611, 722, 667, 944, 667, 667, 611, 278, 278, 278, 469, 556, # P - _
+        333, 556, 556, 500, 556, 556, 278, 556, 556, 222, 222, 500, 222, 833, 556, 556, # ` - o
+        556, 556, 333, 500, 278, 556, 500, 722, 500, 500, 500, 334, 260, 334, 584 # p - ~
+      ].freeze
+      DEFAULT = 556
+      ASCENT = 0.718
+      DESCENT = -0.207
+
+      module_function
+
+      # WinAnsi bytes for an appearance stream; unmappable characters become "?".
+      def encode(text)
+        text.to_s.encode(Encoding::Windows_1252, invalid: :replace, undef: :replace).b
+      end
+
+      # The width of WinAnsi `bytes` at `size`.
+      def width(bytes, size)
+        bytes.each_byte.sum { |byte| (byte in 32..126) ? ASCII[byte - 32] : DEFAULT } * size / 1000.0
+      end
+
+      # `text` broken into WinAnsi lines no wider than `width`, keeping its own
+      # line breaks; a word wider than a line stands alone.
+      def wrap(text, width, size)
+        encode(text).split("\n", -1).flat_map do |paragraph|
+          paragraph.split.each_with_object([+""]) do |word, lines|
+            candidate = lines.last.empty? ? word : "#{lines.last} #{word}"
+            if lines.last.empty? || width(candidate, size) <= width
+              lines[-1] = candidate
+            else
+              lines << word
+            end
+          end
+        end
+      end
+    end
+  end
+end