stationery 0.1.0 → 0.2.0

data/lib/stationery/rspec.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+require "stationery"
+require_relative "testing/matchers"
+
+RSpec.configure { |config| config.include Stationery::Testing::Matchers }

data/lib/stationery/structure.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Stationery
+  # Resolves internal links (`#name`) against the anchors painted on the
+  # finished pages and fills page-number slots with the pages their anchors
+  # landed on. Anchors drawn by page templates repeat on every page, so they
+  # resolve to their first page and never count as duplicates.
+  class Structure
+    # Where a named anchor sits: a zero-based page index and a PDF-space top.
+    Destination = Data.define(:page, :top)
+
+    # Returns the destinations by name; unresolved links are dropped.
+    # Runs before resources are written, so slot digits join the font subset.
+    def self.resolve(pages, warnings:, resources: nil, book: nil) = new(pages, warnings, resources, book).resolve
+
+    def initialize(pages, warnings, resources, book)
+      @pages = pages
+      @warnings = warnings
+      @resources = resources
+      @book = book
+      @destinations = {}
+    end
+
+    def resolve
+      collect
+      collect_templates
+      @pages.each_with_index do |page, index|
+        page.slots.each { |slot| fill(page, slot) }
+        page.annotations.replace(page.annotations.filter_map { |link| link_to(link, index) })
+      end
+      @destinations
+    end
+
+    private
+
+    def collect
+      @pages.each_with_index do |page, index|
+        page.anchors.each do |name, top|
+          if @destinations.key?(name)
+            @warnings << Warnings::DuplicateAnchor.new(name:, page: index + 1)
+          else
+            @destinations[name] = Destination.new(index, top)
+          end
+        end
+      end
+    end
+
+    def collect_templates
+      @pages.each_with_index do |page, index|
+        page.template_anchors.each { |name, top| @destinations[name] ||= Destination.new(index, top) }
+      end
+    end
+
+    def fill(page, slot)
+      destination = @destinations[slot.anchor] or return
+      label = (destination.page + 1).to_s
+      font, face = @book.resolve(slot.style)
+      style = slot.style
+      width = font.width_of(label, style.render_size, letter_spacing: style.letter_spacing)
+      canvas = Canvas.new(page, @resources)
+      canvas.link(*slot.link, "##{slot.anchor}") if slot.link
+      canvas.text(label, x: slot.x + slot.width - width, y: slot.baseline, font:,
+                         size: style.render_size, color: style.color,
+                         letter_spacing: style.letter_spacing, opacity: style.opacity,
+                         synthetic_bold: face.synthetic_bold, synthetic_oblique: face.synthetic_oblique)
+    end
+
+    def link_to(link, index)
+      return link unless link.key?(:dest)
+
+      destination = @destinations[link[:dest]]
+      return { rect: link[:rect], dest: destination } if destination
+
+      @warnings << Warnings::UnresolvedLink.new(name: link[:dest], page: index + 1)
+      nil
+    end
+  end
+end

data/lib/stationery/svg/arc.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Stationery
+  module SVG
+    # An SVG elliptical arc as cubic Bezier segments (SVG 1.1 appendix F.6.5:
+    # endpoint to centre parameterisation, then at most 90 degrees a segment).
+    class Arc
+      def initialize(x1, y1, rx, ry, rotation, large, sweep, x2, y2)
+        @x1 = x1.to_f
+        @y1 = y1.to_f
+        @x2 = x2
+        @y2 = y2
+        @rx = rx.to_f
+        @ry = ry.to_f
+        @phi = rotation * Math::PI / 180
+        @large = large == 1
+        @sweep = sweep == 1
+      end
+
+      def curves
+        centre
+        count = [(@delta.abs / (Math::PI / 2)).ceil, 1].max
+        step = @delta / count
+        curves = Array.new(count) { |i| segment(@theta + (i * step), step) }
+        curves.last[4] = @x2
+        curves.last[5] = @y2
+        curves
+      end
+
+      private
+
+      def centre
+        cos = Math.cos(@phi)
+        sin = Math.sin(@phi)
+        dx = (@x1 - @x2) / 2.0
+        dy = (@y1 - @y2) / 2.0
+        x1p = (cos * dx) + (sin * dy)
+        y1p = (-sin * dx) + (cos * dy)
+        scale_radii(x1p, y1p)
+        cxp, cyp = centre_prime(x1p, y1p)
+        @cx = (cos * cxp) - (sin * cyp) + ((@x1 + @x2) / 2.0)
+        @cy = (sin * cxp) + (cos * cyp) + ((@y1 + @y2) / 2.0)
+        angles(x1p, y1p, cxp, cyp)
+      end
+
+      def scale_radii(x1p, y1p)
+        lambda = ((x1p**2) / (@rx**2)) + ((y1p**2) / (@ry**2))
+        return unless lambda > 1
+
+        @rx *= Math.sqrt(lambda)
+        @ry *= Math.sqrt(lambda)
+      end
+
+      def centre_prime(x1p, y1p)
+        rx2 = @rx**2
+        ry2 = @ry**2
+        numerator = (rx2 * ry2) - (rx2 * (y1p**2)) - (ry2 * (x1p**2))
+        denominator = (rx2 * (y1p**2)) + (ry2 * (x1p**2))
+        coefficient = Math.sqrt([numerator, 0].max / denominator) * (@large == @sweep ? -1 : 1)
+        [coefficient * @rx * y1p / @ry, -coefficient * @ry * x1p / @rx]
+      end
+
+      def angles(x1p, y1p, cxp, cyp)
+        ux = (x1p - cxp) / @rx
+        uy = (y1p - cyp) / @ry
+        vx = (-x1p - cxp) / @rx
+        vy = (-y1p - cyp) / @ry
+        @theta = Math.atan2(uy, ux)
+        @delta = Math.atan2((ux * vy) - (uy * vx), (ux * vx) + (uy * vy))
+        @delta -= 2 * Math::PI if !@sweep && @delta.positive?
+        @delta += 2 * Math::PI if @sweep && @delta.negative?
+      end
+
+      def segment(start, step)
+        t = 4.0 / 3 * Math.tan(step / 4)
+        a1 = start
+        a2 = start + step
+        p1 = point(Math.cos(a1) - (t * Math.sin(a1)), Math.sin(a1) + (t * Math.cos(a1)))
+        p2 = point(Math.cos(a2) + (t * Math.sin(a2)), Math.sin(a2) - (t * Math.cos(a2)))
+        p3 = point(Math.cos(a2), Math.sin(a2))
+        [*p1, *p2, *p3]
+      end
+
+      def point(ux, uy)
+        x = @rx * ux
+        y = @ry * uy
+        [(Math.cos(@phi) * x) - (Math.sin(@phi) * y) + @cx, (Math.sin(@phi) * x) + (Math.cos(@phi) * y) + @cy]
+      end
+    end
+  end
+end

data/lib/stationery/svg/document.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Stationery
+  module SVG
+    # A parsed SVG drawn as vector paths on a canvas. Supports the subset icon
+    # sets use: path, rect (with rx), circle, ellipse, line, polyline, polygon
+    # and g, with fill, stroke, stroke width/caps/joins, fill-rule, opacity,
+    # inline styles and transforms. `currentColor` takes the colour you pass.
+    class Document
+      SHAPES = %w[path rect circle ellipse line polyline polygon].freeze
+      QUIET = (SHAPES + %w[svg g title desc metadata]).freeze
+
+      def self.parse(source)
+        root = Parser.parse(source)
+        raise Error, "not an svg document" unless root&.name == "svg"
+
+        new(root)
+      end
+
+      attr_reader :view_box, :unsupported
+
+      def initialize(root)
+        @root = root
+        @view_box = read_view_box
+        @unsupported = element_names(root).uniq.sort - QUIET
+      end
+
+      def aspect = @view_box[2].to_f / @view_box[3]
+
+      # Scales the viewBox into the box (aspect ratio kept, centred).
+      def draw(canvas, x:, y:, width:, height:, color: "#000000")
+        vx, vy, vw, vh = @view_box
+        scale = [width.to_f / vw, height.to_f / vh].min
+        e = x + ((width - (vw * scale)) / 2.0) - (vx * scale)
+        f = y + ((height - (vh * scale)) / 2.0) - (vy * scale)
+        style = Style.new(Style::DEFAULTS, [scale, 0, 0, scale, e, f], color:).child(@root.attributes)
+        @root.children.each { |element| draw_element(canvas, element, style) }
+      end
+
+      private
+
+      def read_view_box
+        values = @root.attributes["viewBox"]&.split(/[\s,]+/)&.map { |v| number(v) }
+        return values if values&.size == 4
+
+        [0, 0, number(@root.attributes.fetch("width", "100")), number(@root.attributes.fetch("height", "100"))]
+      end
+
+      def element_names(element)
+        element.children.flat_map { |child| [child.name, *element_names(child)] }
+      end
+
+      def number(value)
+        float = value.to_s.to_f
+        float == float.round ? float.round : float
+      end
+
+      def draw_element(canvas, element, parent)
+        style = parent.child(element.attributes)
+        return element.children.each { |child| draw_element(canvas, child, style) } if element.name == "g"
+        return unless SHAPES.include?(element.name)
+
+        fill = style.fill
+        stroke = style.stroke
+        return if fill.nil? && stroke.nil?
+
+        canvas.path(fill:, stroke:, line_width: style.line_width, cap: style.cap || :butt, join: style.join || :miter,
+                    even_odd: style.even_odd?, opacity: style.opacity < 1 ? style.opacity : nil,
+                    transform: style.matrix) { |path| Shapes.trace(path, element) }
+      end
+    end
+  end
+end

data/lib/stationery/svg/parser.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module Stationery
+  module SVG
+    # A minimal XML reader for SVG documents: elements, attributes and nesting.
+    # Comments, processing instructions, doctypes and text content are skipped.
+    module Parser
+      Element = Data.define(:name, :attributes, :children)
+
+      IGNORED = /<!--.*?-->|<\?.*?\?>|<!DOCTYPE[^>]*>|<!\[CDATA\[.*?\]\]>/m
+      TAG = %r{<(/?)([a-zA-Z][\w:.-]*)((?:\s+[\w:.-]+\s*=\s*(?:"[^"]*"|'[^']*'))*)\s*(/?)>}m
+      ATTRIBUTE = /([\w:.-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/
+
+      module_function
+
+      def parse(source)
+        scanner = StringScanner.new(source.to_s.gsub(IGNORED, ""))
+        root = Element.new("document", {}, [])
+        stack = [root]
+        while scanner.skip_until(/(?=<)/)
+          tag = scanner.scan(TAG) or (scanner.getch && next)
+          handle(stack, *tag.match(TAG).captures)
+        end
+        root.children.first
+      end
+
+      def handle(stack, closing, name, attributes, self_closing)
+        return stack.pop if closing == "/" && stack.size > 1
+
+        element = Element.new(name, attributes.scan(ATTRIBUTE).to_h { |k, *v| [k, v.compact.first] }, [])
+        stack.last.children << element
+        stack << element if self_closing.empty?
+      end
+    end
+  end
+end

data/lib/stationery/svg/path_data.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require "strscan"
+
+module Stationery
+  module SVG
+    class Error < Stationery::Error; end
+
+    # Parses SVG path data into absolute segments:
+    #
+    #   [:move, x, y] [:line, x, y] [:curve, x1, y1, x2, y2, x, y] [:close]
+    #
+    # Quadratic curves become cubics and elliptical arcs become cubic segments
+    # of at most 90 degrees, so a drawing backend needs only move, line, curve
+    # and close.
+    class PathData
+      ARITY = { "M" => 2, "L" => 2, "T" => 2, "H" => 1, "V" => 1, "C" => 6, "S" => 4, "Q" => 4, "A" => 7,
+                "Z" => 0 }.freeze
+      NUMBER = /[-+]?(?:\d+\.?\d*|\.\d+)(?:[eE][-+]?\d+)?/
+      FLAG = /[01]/
+      SEPARATORS = /[\s,]*/
+
+      def self.parse(data) = new(data).segments
+
+      def initialize(data)
+        @scanner = StringScanner.new(data.to_s)
+        @segments = []
+        @x = @y = @start_x = @start_y = 0
+        @control = nil
+        @command = nil
+      end
+
+      def segments
+        loop do
+          @scanner.skip(SEPARATORS)
+          break if @scanner.eos?
+
+          if (letter = @scanner.scan(/[MmLlHhVvCcSsQqTtAaZz]/))
+            @command = letter
+            next close_path if letter.upcase == "Z"
+          end
+          raise Error, "unreadable path data near #{@scanner.rest[0, 12].inspect}" unless @command
+
+          apply(@command, arguments(@command))
+        end
+        @segments
+      end
+
+      private
+
+      def arguments(command)
+        Array.new(ARITY.fetch(command.upcase)) do |index|
+          @scanner.skip(SEPARATORS)
+          token = @scanner.scan(command.upcase == "A" && [3, 4].include?(index) ? FLAG : NUMBER)
+          raise Error, "unreadable path data near #{@scanner.rest[0, 12].inspect}" unless token
+
+          number(token)
+        end
+      end
+
+      def number(token)
+        token.match?(/[.eE]/) ? token.to_f : token.to_i
+      end
+
+      def apply(command, args)
+        relative = command == command.downcase
+        case command.upcase
+        when "M" then move(*absolute(args, relative))
+        when "L" then line(*absolute(args, relative))
+        when "H" then line(relative ? @x + args[0] : args[0], @y)
+        when "V" then line(@x, relative ? @y + args[0] : args[0])
+        when "C" then curve(*absolute(args, relative))
+        when "S" then curve(*reflected_control, *absolute(args, relative))
+        when "Q" then quadratic(*absolute(args, relative))
+        when "T" then quadratic(*reflected_control, *absolute(args, relative))
+        else arc(*args.first(5), *absolute(args.last(2), relative))
+        end
+      end
+
+      def absolute(args, relative)
+        return args unless relative
+
+        args.each_with_index.map { |value, index| value + (index.even? ? @x : @y) }
+      end
+
+      def move(x, y)
+        @segments << [:move, x, y]
+        @x = @start_x = x
+        @y = @start_y = y
+        @control = nil
+        # Coordinates after a move are implicit lines.
+        @command = @command == "m" ? "l" : "L"
+      end
+
+      def line(x, y)
+        @segments << [:line, x, y]
+        @x = x
+        @y = y
+        @control = nil
+      end
+
+      def curve(x1, y1, x2, y2, x, y)
+        @segments << [:curve, x1, y1, x2, y2, x, y]
+        @x = x
+        @y = y
+        @control = [x2, y2]
+      end
+
+      def quadratic(qx, qy, x, y)
+        curve(@x + ((2 * (qx - @x)) / 3.0), @y + ((2 * (qy - @y)) / 3.0),
+              x + ((2 * (qx - x)) / 3.0), y + ((2 * (qy - y)) / 3.0), x, y)
+        @control = [qx, qy]
+      end
+
+      def reflected_control
+        return [@x, @y] unless @control
+
+        [(2 * @x) - @control[0], (2 * @y) - @control[1]]
+      end
+
+      def close_path
+        @segments << [:close]
+        @x = @start_x
+        @y = @start_y
+        @control = nil
+      end
+
+      def arc(rx, ry, rotation, large, sweep, x, y)
+        return line(x, y) if rx.zero? || ry.zero?
+
+        Arc.new(@x, @y, rx.abs, ry.abs, rotation, large, sweep, x, y).curves.each { |c| curve(*c) }
+        @x = x
+        @y = y
+      end
+    end
+  end
+end

data/lib/stationery/svg/shapes.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Stationery
+  module SVG
+    # Traces one SVG shape element onto a canvas path.
+    module Shapes
+      module_function
+
+      def trace(path, element)
+        a = element.attributes
+        case element.name
+        when "path" then trace_data(path, PathData.parse(a["d"]))
+        when "rect" then path.rounded_rect(f(a, "x"), f(a, "y"), f(a, "width"), f(a, "height"), f(a, "rx", f(a, "ry")))
+        when "circle" then path.ellipse(f(a, "cx"), f(a, "cy"), f(a, "r"), f(a, "r"))
+        when "ellipse" then path.ellipse(f(a, "cx"), f(a, "cy"), f(a, "rx"), f(a, "ry"))
+        when "line" then trace_points(path, [[f(a, "x1"), f(a, "y1")], [f(a, "x2"), f(a, "y2")]], close: false)
+        else trace_points(path, points(a["points"]), close: element.name == "polygon")
+        end
+      end
+
+      def trace_data(path, segments)
+        segments.each do |kind, *args|
+          case kind
+          when :move then path.move_to(*args)
+          when :line then path.line_to(*args)
+          when :curve then path.curve_to(*args)
+          else path.close
+          end
+        end
+      end
+
+      def trace_points(path, points, close:)
+        return if points.empty?
+
+        path.move_to(*points.first)
+        points.drop(1).each { |point| path.line_to(*point) }
+        path.close if close
+      end
+
+      def points(source)
+        source.to_s.scan(PathData::NUMBER).map { |v| v.match?(/[.eE]/) ? v.to_f : v.to_i }.each_slice(2)
+              .select { |pair| pair.size == 2 }
+      end
+
+      def f(attributes, key, default = 0)
+        value = attributes[key]
+        return default if value.nil? || value.empty?
+
+        number = value.to_f
+        number == number.round ? number.round : number
+      end
+    end
+  end
+end

data/lib/stationery/svg/style.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Stationery
+  module SVG
+    # Presentation attributes an element inherits from its ancestors, and the
+    # transform it draws with.
+    class Style
+      INHERITED = %w[fill stroke stroke-width stroke-linecap stroke-linejoin fill-rule opacity fill-opacity
+                     stroke-opacity].freeze
+      NAMED = { "black" => "#000000", "white" => "#FFFFFF", "red" => "#FF0000", "green" => "#008000",
+                "blue" => "#0000FF", "gray" => "#808080", "grey" => "#808080" }.freeze
+      DEFAULTS = { "fill" => "black", "stroke" => "none", "stroke-width" => "1" }.freeze
+
+      attr_reader :values, :matrix
+
+      def initialize(values = DEFAULTS, matrix = [1, 0, 0, 1, 0, 0], color: "#000000")
+        @values = values
+        @matrix = matrix
+        @color = color
+      end
+
+      def child(attributes)
+        own = attributes.merge(declarations(attributes["style"]))
+        values = @values.merge(own.slice(*INHERITED))
+        matrix = if attributes["transform"]
+                   Transform.multiply(@matrix,
+                                      Transform.parse(attributes["transform"]))
+                 else
+                   @matrix
+                 end
+        Style.new(values, matrix, color: @color)
+      end
+
+      def fill = paint("fill")
+      def stroke = paint("stroke")
+      def even_odd? = @values["fill-rule"] == "evenodd"
+      def cap = @values["stroke-linecap"]&.to_sym
+      def join = @values["stroke-linejoin"]&.to_sym
+
+      # Stroke width scales with the drawing, by the transform's area factor.
+      def line_width
+        a, b, c, d, = @matrix
+        @values["stroke-width"].to_f * Math.sqrt(((a * d) - (b * c)).abs)
+      end
+
+      def opacity
+        %w[opacity fill-opacity stroke-opacity].filter_map { |key| @values[key]&.to_f }.reduce(1.0, :*)
+      end
+
+      private
+
+      def paint(key)
+        value = @values[key].to_s.strip
+        return nil if value.empty? || %w[none transparent].include?(value)
+        return @color if value == "currentColor"
+
+        NAMED.fetch(value.downcase, value)
+      end
+
+      def declarations(style)
+        style.to_s.split(";").filter_map do |declaration|
+          key, value = declaration.split(":", 2).map(&:strip)
+          [key, value] if key && value
+        end.to_h
+      end
+    end
+  end
+end

data/lib/stationery/svg/transform.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Stationery
+  module SVG
+    # SVG `transform` attributes as affine matrices [a, b, c, d, e, f].
+    module Transform
+      FUNCTION = /(matrix|translate|scale|rotate|skewX|skewY)\s*\(([^)]*)\)/
+
+      module_function
+
+      def parse(source)
+        source.scan(FUNCTION).reduce([1, 0, 0, 1, 0, 0]) do |matrix, (name, args)|
+          multiply(matrix, function(name, args.split(/[\s,]+/).reject(&:empty?).map(&:to_f)))
+        end
+      end
+
+      def function(name, args)
+        case name
+        when "matrix" then args
+        when "translate" then [1, 0, 0, 1, args[0], args[1] || 0]
+        when "scale" then [args[0], 0, 0, args[1] || args[0], 0, 0]
+        when "rotate" then rotate(*args)
+        when "skewX" then [1, 0, Math.tan(args[0] * Math::PI / 180), 1, 0, 0]
+        else [1, Math.tan(args[0] * Math::PI / 180), 0, 1, 0, 0]
+        end
+      end
+
+      def rotate(degrees, cx = 0, cy = 0)
+        r = degrees * Math::PI / 180
+        rotation = [Math.cos(r), Math.sin(r), -Math.sin(r), Math.cos(r), 0, 0]
+        multiply(multiply([1, 0, 0, 1, cx, cy], rotation), [1, 0, 0, 1, -cx, -cy])
+      end
+
+      # The transform that applies `inner` first, then `outer`.
+      def multiply(outer, inner)
+        a, b, c, d, e, f = outer
+        ia, ib, ic, id, ie, if_ = inner
+        [(a * ia) + (c * ib), (b * ia) + (d * ib), (a * ic) + (c * id), (b * ic) + (d * id),
+         (a * ie) + (c * if_) + e, (b * ie) + (d * if_) + f]
+      end
+    end
+  end
+end

data/lib/stationery/testing/inspector.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require "pathname"
+require "stringio"
+require "stationery"
+
+module Stationery
+  module Testing
+    # Reads a rendered PDF back for assertions. The subject is a
+    # Stationery::Document, PDF bytes, a path (String or Pathname) or an IO.
+    # Needs the pdf-reader gem, loaded on first use.
+    class Inspector
+      UTF16_BOM = "\xFE\xFF".b
+
+      def initialize(subject)
+        @subject = subject
+      end
+
+      def pdf
+        @pdf ||= case @subject
+                 when Document then @subject.to_pdf
+                 when String then @subject.start_with?("%PDF") ? @subject : File.binread(@subject)
+                 when Pathname then File.binread(@subject)
+                 else @subject.read
+                 end
+      end
+
+      def reader
+        @reader ||= begin
+          require "pdf/reader"
+          ::PDF::Reader.new(StringIO.new(pdf))
+        rescue LoadError
+          raise Stationery::Error, 'Stationery::Testing needs pdf-reader: add gem "pdf-reader" to your test group'
+        end
+      end
+
+      def page_count = reader.page_count
+      def page_texts = @page_texts ||= reader.pages.map { |page| page.text.squeeze(" ").strip }
+      def text = page_texts.join("\n")
+      def metadata = reader.info
+      def image_count = pdf.scan(%r{/Subtype\s*/Image\b}).size
+
+      def warnings
+        return [] unless @subject.is_a?(Document)
+
+        pdf
+        @subject.warnings.to_a
+      end
+
+      def links
+        annotations.filter_map { |annot| annot.dig(:A, :URI) if annot.dig(:A, :S) == :URI }
+      end
+
+      def internal_links
+        annotations.filter_map do |annot|
+          dest = annot[:Dest] || (annot.dig(:A, :D) if annot.dig(:A, :S) == :GoTo)
+          destination(dest) if dest
+        end
+      end
+
+      def bookmarks
+        outlines = objects.deref!(objects.trailer[:Root])[:Outlines]
+        outlines ? titles(outlines[:First]) : []
+      end
+
+      private
+
+      def objects = reader.objects
+
+      def annotations
+        reader.pages.flat_map do |page|
+          Array(objects.deref_array(page.attributes[:Annots])).map do |ref|
+            annot = objects.deref_hash(ref)
+            annot.merge(A: objects.deref_hash(annot[:A]))
+          end
+        end
+      end
+
+      def destination(dest)
+        return dest.to_s unless dest.is_a?(Array)
+
+        objects.page_references.index(dest.first) + 1
+      end
+
+      def titles(item)
+        return [] unless item
+
+        [decode(item[:Title]), *titles(item[:First]), *titles(item[:Next])]
+      end
+
+      def decode(title)
+        return title.dup.force_encoding(Encoding::UTF_8) unless title.b.start_with?(UTF16_BOM)
+
+        title.b.byteslice(2..).force_encoding(Encoding::UTF_16BE).encode(Encoding::UTF_8)
+      end
+    end
+  end
+end