stationery 0.2.0 → 0.4.0

data/lib/stationery/pdf/assembler.rb

@@ -4,37 +4,57 @@ module Stationery
   module PDF
     # Writes finished pages, their shared resources and document info as PDF.
     class Assembler
-      def initialize(pages:, resources:, info: {}, outline: [])
+      # `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)
+        @tagging = tagging
+        @lang = lang
         @pages = pages
         @resources = resources
         @info = info
         @outline = outline
+        @encryption = encryption
       end
 
       def render
-        writer = Writer.new
+        writer = Writer.new(encryption: @encryption)
+        @form = Forms::AcroForm.new(writer)
         tree = writer.reserve
         refs = @resources.build(writer)
         kids = @kids = @pages.map { writer.reserve }
+        @structure = @tagging && Tagging::Writer.new(@tagging, pages: @pages, refs: kids)
         @pages.each_with_index { |page, index| write_page(writer, page, kids[index], tree, refs) }
         writer.set(tree, { Type: :Pages, Kids: kids, Count: kids.size })
-        root = writer.add(catalog(tree, OutlineWriter.new(writer, @outline, kids).write))
+        outlines = OutlineWriter.new(writer, @outline, kids).write
+        root = writer.add(catalog(tree, outlines, @form.write).merge(accessibility(writer)))
         writer.render(root:, info: writer.add(info_dictionary))
       end
 
       private
 
-      def catalog(tree, outlines)
+      def catalog(tree, outlines, form)
         catalog = { Type: :Catalog, Pages: tree }
+        catalog[:AcroForm] = form if form
         outlines ? catalog.merge(Outlines: outlines, PageMode: :UseOutlines) : catalog
       end
 
+      def accessibility(writer)
+        entries = @lang ? { Lang: PDF::TextString.new(@lang.to_s) } : {}
+        return entries unless @structure
+
+        entries.merge!(@structure.write(writer))
+        @info[:Title] ? entries.merge(ViewerPreferences: { DisplayDocTitle: true }) : entries
+      end
+
       def write_page(writer, page, ref, tree, refs)
         dictionary = {
           Type: :Page, Parent: tree, MediaBox: [0, 0, *page.size],
           Contents: writer.add(Stream.new(page.content)), Resources: page_resources(page, refs)
         }
-        dictionary[:Annots] = page.annotations.map { |link| writer.add(annotation(link)) } if page.annotations.any?
+        if page.annotations.any?
+          dictionary[:Annots] = page.annotations.map { |annot| annotation_ref(writer, annot, ref) }
+        end
+        dictionary.merge!(@structure.page_entries(page)) if @structure
         writer.set(ref, dictionary)
       end
 
@@ -44,6 +64,19 @@ module Stationery
         end
       end
 
+      def annotation_ref(writer, annotation, page)
+        if annotation[:widget]
+          return @form.add(annotation[:widget], annotation[:rect], page) do |widget_ref|
+            @structure ? @structure.annotation(annotation, widget_ref) : {}
+          end
+        end
+
+        ref = writer.reserve
+        dictionary = annotation(annotation)
+        dictionary = dictionary.merge(@structure.annotation(annotation, ref)) if @structure
+        writer.set(ref, dictionary)
+      end
+
       def annotation(link)
         target = if (dest = link[:dest])
                    { Dest: [@kids.fetch(dest.page), :XYZ, nil, dest.top, nil] }

data/lib/stationery/pdf/encryption/aes.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Stationery
+  module PDF
+    module Encryption
+      # AES as PDF uses it: object data is CBC with a random IV in front and
+      # PKCS#5 padding; key material (UE, OE, Perms) is unpadded.
+      module AES
+        ZERO_IV = ("\0" * 16).b
+
+        module_function
+
+        def encrypt(key, data)
+          iv = OpenSSL::Random.random_bytes(16)
+          iv + run(cipher(key, "CBC", iv), data)
+        end
+
+        def raw(key, data, iv: ZERO_IV, mode: "CBC")
+          aes = cipher(key, mode, mode == "ECB" ? nil : iv)
+          aes.padding = 0
+          run(aes, data)
+        end
+
+        def cipher(key, mode, iv)
+          aes = OpenSSL::Cipher.new("AES-#{key.bytesize * 8}-#{mode}").encrypt
+          aes.key = key
+          aes.iv = iv if iv
+          aes
+        end
+
+        def run(aes, data) = aes.update(data.b) + aes.final
+      end
+    end
+  end
+end

data/lib/stationery/pdf/encryption/rc4.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Stationery
+  module PDF
+    module Encryption
+      # RC4 in Ruby: OpenSSL 3 builds drop it from the default provider.
+      module RC4
+        module_function
+
+        def crypt(key, data)
+          state = schedule(key.b.bytes)
+          i = j = 0
+          data.b.bytes.map do |byte|
+            i = (i + 1) & 0xFF
+            j = (j + state[i]) & 0xFF
+            state[i], state[j] = state[j], state[i]
+            byte ^ state[(state[i] + state[j]) & 0xFF]
+          end.pack("C*")
+        end
+
+        def schedule(key)
+          state = (0..255).to_a
+          j = 0
+          256.times do |i|
+            j = (j + state[i] + key[i % key.size]) & 0xFF
+            state[i], state[j] = state[j], state[i]
+          end
+          state
+        end
+      end
+    end
+  end
+end

data/lib/stationery/pdf/encryption/revision4.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "digest/md5"
+
+module Stationery
+  module PDF
+    module Encryption
+      # The MD5 key derivation of security handler revisions 3 and 4
+      # (ISO 32000-1 algorithms 1-5) with a 128-bit key. Each object is
+      # encrypted with its own key: RC4 for R3, AES-128 (AESV2) for R4.
+      class Revision4
+        PADDING = ["28BF4E5E4E758A4164004E56FFFA01082E2E00B6D0683E802F0CA9FE6453697A"].pack("H*").freeze
+
+        def initialize(user:, owner:, permissions:, file_id:, aes:)
+          @aes = aes
+          user = pad(user)
+          @owner_key = rounds(stretch(Digest::MD5.digest(pad(owner))), user)
+          @key = stretch(Digest::MD5.digest(user + @owner_key + [permissions].pack("l<") + file_id))
+          @user_key = rounds(@key, Digest::MD5.digest(PADDING + file_id)) + PADDING.byteslice(0, 16)
+        end
+
+        def entries = { O: HexString.new(@owner_key), U: HexString.new(@user_key) }
+
+        def encrypt(data, number, generation)
+          key = object_key(number, generation)
+          @aes ? AES.encrypt(key, data) : RC4.crypt(key, data)
+        end
+
+        private
+
+        def pad(password) = (password.b + PADDING).byteslice(0, 32)
+
+        def stretch(digest) = 50.times.reduce(digest) { |previous, _| Digest::MD5.digest(previous) }
+
+        def rounds(key, data)
+          20.times.reduce(data) { |previous, round| RC4.crypt(xor(key, round), previous) }
+        end
+
+        def xor(key, value) = key.bytes.map { |byte| byte ^ value }.pack("C*")
+
+        def object_key(number, generation)
+          seed = @key + [number].pack("V").byteslice(0, 3) + [generation].pack("v")
+          Digest::MD5.digest(@aes ? "#{seed}sAlT" : seed)
+        end
+      end
+    end
+  end
+end

data/lib/stationery/pdf/encryption/revision6.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "digest/sha2"
+require "openssl"
+
+module Stationery
+  module PDF
+    module Encryption
+      # Security handler revision 6 (ISO 32000-2, AES-256): a random file key
+      # wrapped once per password, with salted SHA-2 hashes that run through
+      # the hash iteration of algorithm 2.B. Every object uses the file key.
+      class Revision6
+        DIGESTS = [Digest::SHA256, Digest::SHA384, Digest::SHA512].freeze
+
+        def initialize(user:, owner:, permissions:)
+          @key = random(32)
+          user = password(user)
+          owner = password(owner)
+          validation = random(8)
+          key_salt = random(8)
+          @user_key = hash(user, validation) + validation + key_salt
+          @user_wrapped = AES.raw(hash(user, key_salt), @key)
+          validation = random(8)
+          key_salt = random(8)
+          @owner_key = hash(owner, validation, @user_key) + validation + key_salt
+          @owner_wrapped = AES.raw(hash(owner, key_salt, @user_key), @key)
+          @perms = AES.raw(@key, "#{[permissions, 0xFFFFFFFF].pack("l<V")}Tadb#{random(4)}", mode: "ECB")
+        end
+
+        def entries
+          { O: @owner_key, U: @user_key, OE: @owner_wrapped, UE: @user_wrapped, Perms: @perms }
+            .transform_values { |bytes| HexString.new(bytes) }
+        end
+
+        def encrypt(data, _number, _generation) = AES.encrypt(@key, data)
+
+        private
+
+        def random(size) = OpenSSL::Random.random_bytes(size)
+
+        def password(value) = value.encode(Encoding::UTF_8).b.byteslice(0, 127)
+
+        def hash(password, salt, user_key = "".b)
+          key = Digest::SHA256.digest(password + salt + user_key)
+          round = 0
+          loop do
+            block = AES.raw(key.byteslice(0, 16), (password + key + user_key) * 64, iv: key.byteslice(16, 16))
+            key = DIGESTS[block.byteslice(0, 16).bytes.sum % 3].digest(block)
+            round += 1
+            return key.byteslice(0, 32) if round >= 64 && block.getbyte(-1) <= round - 32
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stationery/pdf/encryption/standard_security.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Stationery
+  module PDF
+    module Encryption
+      # The standard security handler: passwords, permissions and the
+      # /Encrypt dictionary, plus the per-object encryption the writer applies
+      # to every string and stream.
+      #
+      #   StandardSecurity.new(owner_password: "s3cret", permissions: %i[print copy])
+      class StandardSecurity
+        PERMISSIONS = { print: 3, modify: 4, copy: 5, annotate: 6, fill_forms: 9, extract_accessible: 10,
+                        assemble: 11, print_high: 12 }.freeze
+        ALGORITHMS = {
+          aes_256: { V: 5, R: 6, Length: 256, CFM: :AESV3, key: 32 },
+          aes_128: { V: 4, R: 4, Length: 128, CFM: :AESV2, key: 16 },
+          rc4_128: { V: 2, R: 3, Length: 128 }
+        }.freeze
+
+        # Checks and normalizes the options without deriving any keys.
+        def self.options(owner_password:, user_password: "", permissions: PERMISSIONS.keys, algorithm: :aes_256)
+          raise ArgumentError, "encryption needs an owner_password" if owner_password.to_s.empty?
+
+          permissions = Array(permissions).map(&:to_sym)
+          unknown = permissions - PERMISSIONS.keys
+          raise ArgumentError, "unknown permission #{unknown.first.inspect}" if unknown.any?
+          raise ArgumentError, "unknown algorithm #{algorithm.inspect}" unless ALGORITHMS.key?(algorithm)
+
+          { owner_password: owner_password.to_s, user_password: user_password.to_s, permissions:, algorithm: }
+        end
+
+        # The signed 32-bit /P value: granted bits set, bits 1-2 clear, the rest set.
+        def self.permission_bits(permissions)
+          masks = PERMISSIONS.transform_values { |bit| 1 << (bit - 1) }
+          bits = 0xFFFFFFFC & ~masks.values.sum
+          bits |= permissions.sum { |name| masks.fetch(name) }
+          [bits].pack("L").unpack1("l")
+        end
+
+        attr_reader :file_id
+
+        def initialize(**)
+          options = self.class.options(**)
+          @algorithm = ALGORITHMS.fetch(options[:algorithm])
+          @permissions = self.class.permission_bits(options[:permissions])
+          @file_id = OpenSSL::Random.random_bytes(16)
+          @handler = handler(options[:user_password], options[:owner_password], options[:algorithm])
+        end
+
+        def dictionary
+          { Filter: :Standard, **@algorithm.slice(:V, :R, :Length), P: @permissions, **@handler.entries,
+            **crypt_filters }
+        end
+
+        def encrypt(data, number, generation = 0) = @handler.encrypt(data, number, generation)
+
+        private
+
+        def handler(user, owner, algorithm)
+          if algorithm == :aes_256
+            Revision6.new(user:, owner:, permissions: @permissions)
+          else
+            Revision4.new(user:, owner:, permissions: @permissions, file_id: @file_id, aes: algorithm == :aes_128)
+          end
+        end
+
+        def crypt_filters
+          return {} unless @algorithm[:CFM]
+
+          filter = { CFM: @algorithm[:CFM], AuthEvent: :DocOpen, Length: @algorithm[:key] }
+          { CF: { StdCF: filter }, StmF: :StdCF, StrF: :StdCF }
+        end
+      end
+    end
+  end
+end

data/lib/stationery/pdf/serializer.rb

@@ -7,6 +7,9 @@ module Stationery
     # A plain String is always written as a literal byte string `( … )` — never
     # re-encoded — so a URI stays the 7-bit ASCII the spec requires. Use
     # TextString for human-readable text that may need UTF-16.
+    #
+    # `crypt`, when given, receives every string's bytes (the writer binds it
+    # to the object being written) and the result is written as hex.
     module Serializer
       NAME_ESCAPE = %r{[^\x21-\x7E]|[#%()/<>\[\]{}]}n
       LITERAL_ESCAPE = /[\\()\r]/n
@@ -14,15 +17,15 @@ module Stationery
 
       module_function
 
-      def dump(value)
+      def dump(value, crypt = nil)
         case value
         when Reference then "#{value.id} 0 R"
         when Symbol then name(value)
-        when Hash then "<<#{value.map { |k, v| "#{name(k)} #{dump(v)}" }.join(" ")}>>"
-        when Array then "[#{value.map { |v| dump(v) }.join(" ")}]"
-        when HexString then "<#{value.bytes.unpack1("H*").upcase}>"
-        when TextString then text(value.value)
-        when String then literal(value)
+        when Hash then "<<#{value.map { |k, v| "#{name(k)} #{dump(v, crypt)}" }.join(" ")}>>"
+        when Array then "[#{value.map { |v| dump(v, crypt) }.join(" ")}]"
+        when HexString then hex(value.bytes, crypt)
+        when TextString then text(value.value, crypt)
+        when String then crypt ? hex(value, crypt) : literal(value)
         when Integer, true, false then value.to_s
         when Float then number(value)
         when nil then "null"
@@ -38,6 +41,11 @@ module Stationery
         "(#{value.b.gsub(LITERAL_ESCAPE) { |c| c == "\r" ? "\\r" : "\\#{c}" }})"
       end
 
+      def hex(bytes, crypt = nil)
+        bytes = crypt.call(bytes.b) if crypt
+        "<#{bytes.unpack1("H*").upcase}>"
+      end
+
       def number(value)
         return value.to_s if value.is_a?(Integer)
 
@@ -49,11 +57,11 @@ module Stationery
         str == "-0" ? "0" : str
       end
 
-      def text(value)
+      def text(value, crypt = nil)
         value = value.to_s
-        return literal(value) if value.ascii_only?
+        return dump(value, crypt) if value.ascii_only?
 
-        dump(HexString.new(UTF16_BOM + value.encode(Encoding::UTF_16BE).b))
+        hex(UTF16_BOM + value.encode(Encoding::UTF_16BE).b, crypt)
       end
     end
   end

data/lib/stationery/pdf/writer.rb

@@ -9,8 +9,11 @@ module Stationery
     class Writer
       HEADER = "%PDF-1.7\n%\xE2\xE3\xCF\xD3\n".b
 
-      def initialize
+      # `encryption` (an Encryption::StandardSecurity) encrypts every string
+      # and stream except those of its own /Encrypt dictionary.
+      def initialize(encryption: nil)
         @objects = []
+        @encryption = encryption
       end
 
       # Hands out a reference now and lets the object be set later, so a page
@@ -34,30 +37,46 @@ module Stationery
           raise Error, "object #{missing + 1} reserved but never set"
         end
 
+        @encrypt = @encryption && add(@encryption.dictionary)
         out = HEADER.dup
         offsets = @objects.each_with_index.map { |object, index| write_object(out, index + 1, object) }
         xref = out.bytesize
-        id = HexString.new(Digest::MD5.digest(out))
+        id = HexString.new(@encryption ? @encryption.file_id : Digest::MD5.digest(out))
 
         out << "xref\n0 #{@objects.size + 1}\n0000000000 65535 f \n"
         offsets.each { |offset| out << format("%010d 00000 n \n", offset) }
-        out << "trailer\n" << Serializer.dump({ Size: @objects.size + 1, Root: root, Info: info, ID: [id, id] })
+        out << "trailer\n" << Serializer.dump(trailer(root, info, id))
         out << "\nstartxref\n#{xref}\n%%EOF\n"
       end
 
       private
 
+      def trailer(root, info, id)
+        trailer = { Size: @objects.size + 1, Root: root, Info: info, ID: [id, id] }
+        @encrypt ? trailer.merge(Encrypt: @encrypt) : trailer
+      end
+
       def write_object(out, number, object)
         offset = out.bytesize
+        crypt = crypt_for(number)
         out << "#{number} 0 obj\n"
         if object.is_a?(Stream)
-          out << Serializer.dump(object.dictionary) << "\nstream\n" << object.data << "\nendstream"
+          data = crypt ? crypt.call(object.data) : object.data
+          out << Serializer.dump(object.dictionary.merge(Length: data.bytesize), crypt)
+          out << "\nstream\n" << data << "\nendstream"
         else
-          out << Serializer.dump(object)
+          out << Serializer.dump(object, crypt)
         end
         out << "\nendobj\n"
         offset
       end
+
+      # The Serializer hook: encrypts a string or stream with this object's key.
+      def crypt_for(number)
+        return unless @encrypt && number != @encrypt.id
+
+        ->(bytes) { @encryption.encrypt(bytes, number) }
+      end
     end
   end
 end

data/lib/stationery/resources.rb

@@ -1,13 +1,14 @@
 # frozen_string_literal: true
 
 module Stationery
-  # Document-wide names for fonts, images and graphics states, so each is
+  # Document-wide names for fonts, images, graphics states and shadings, so each is
   # embedded once however many pages use it.
   class Resources
     def initialize
       @fonts = {}
       @images = {}
       @states = {}
+      @shadings = {}
     end
 
     def font(font)
@@ -22,12 +23,17 @@ module Stationery
       @states[value.to_f.round(3)] ||= :"GS#{@states.size + 1}"
     end
 
+    def shading(dictionary)
+      @shadings[dictionary] ||= :"Sh#{@shadings.size + 1}"
+    end
+
     # Writes every resource once; returns { category => { name => ref } }.
     def build(writer)
       {
         Font: @fonts.to_h { |font, name| [name, font.build(writer)] },
         XObject: @images.to_h { |image, name| [name, image.build(writer)] },
-        ExtGState: @states.to_h { |alpha, name| [name, writer.add({ Type: :ExtGState, ca: alpha, CA: alpha })] }
+        ExtGState: @states.to_h { |alpha, name| [name, writer.add({ Type: :ExtGState, ca: alpha, CA: alpha })] },
+        Shading: @shadings.to_h { |dictionary, name| [name, writer.add(dictionary)] }
       }
     end
   end

data/lib/stationery/rich/renderer.rb

@@ -31,7 +31,7 @@ module Stationery
         when Paragraph then paragraph(block.inlines, **@styles[:p])
         when Heading then heading(block)
         when List then list(block)
-        when Blockquote then @component.box(**@styles[:blockquote]) { render(block.blocks) }
+        when Blockquote then @component.box(role: :blockquote, **@styles[:blockquote]) { render(block.blocks) }
         when CodeBlock then code(block)
         when Rule then @component.rule(**@styles[:hr])
         when Table then table(block)
@@ -47,7 +47,7 @@ module Stationery
         style = @styles[:"h#{heading.level}"]
         size = style[:size] || (@builder.style.size * style.fetch(:scale, 1))
         bookmark = heading_bookmark(heading)
-        paragraph(heading.inlines, **style.except(:scale), size:, **({ bookmark: } if bookmark))
+        paragraph(heading.inlines, **style.except(:scale), size:, heading: heading.level, **({ bookmark: } if bookmark))
       end
 
       def heading_bookmark(heading)
@@ -86,7 +86,7 @@ module Stationery
         return unless source
 
         loaded = Images.load(source)
-        @component.image(loaded, **dimensions(node, loaded))
+        @component.image(loaded, alt: node.alt, **dimensions(node, loaded))
       rescue UnsupportedImage => e
         skip(node.src, e.message)
       end

data/lib/stationery/structure.rb

@@ -11,10 +11,13 @@ module Stationery
 
     # 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 self.resolve(pages, warnings:, resources: nil, book: nil, tagging: nil)
+      new(pages, warnings, resources, book, tagging).resolve
+    end
 
-    def initialize(pages, warnings, resources, book)
+    def initialize(pages, warnings, resources, book, tagging = nil)
       @pages = pages
+      @tagging = tagging
       @warnings = warnings
       @resources = resources
       @book = book
@@ -57,19 +60,22 @@ module Stationery
       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)
+      canvas = Canvas.new(page, @resources, tagging: @tagging)
+      link, number = slot.tags
+      canvas.link(*slot.link, "##{slot.anchor}", tag: link) if slot.link
+      canvas.tag(number) do
+        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
     end
 
     def link_to(link, index)
       return link unless link.key?(:dest)
 
       destination = @destinations[link[:dest]]
-      return { rect: link[:rect], dest: destination } if destination
+      return link.merge!(dest: destination) if destination
 
       @warnings << Warnings::UnresolvedLink.new(name: link[:dest], page: index + 1)
       nil

data/lib/stationery/svg/bounds.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Stationery
+  module SVG
+    # A path sink that measures a shape's bounding box in its own user space,
+    # curves by their extrema. Takes the calls Shapes.trace makes on a path.
+    class Bounds
+      def initialize
+        @xs = []
+        @ys = []
+      end
+
+      def move_to(x, y) = add(x, y)
+      def line_to(x, y) = add(x, y)
+      def close = self
+
+      def curve_to(x1, y1, x2, y2, x, y)
+        x0 = @xs.last || 0
+        y0 = @ys.last || 0
+        (extrema(x0, x1, x2, x) + extrema(y0, y1, y2, y)).each do |at|
+          add(cubic(at, x0, x1, x2, x), cubic(at, y0, y1, y2, y))
+        end
+        add(x, y)
+      end
+
+      def rounded_rect(x, y, w, h, _radius)
+        add(x, y)
+        add(x + w, y + h)
+      end
+
+      def ellipse(cx, cy, rx, ry)
+        add(cx - rx, cy - ry)
+        add(cx + rx, cy + ry)
+      end
+
+      # [x, y, width, height], or nil when the shape has no area.
+      def box
+        return nil if @xs.empty?
+
+        width = @xs.max - @xs.min
+        height = @ys.max - @ys.min
+        [@xs.min, @ys.min, width, height] if width.positive? && height.positive?
+      end
+
+      private
+
+      def add(x, y)
+        @xs << x
+        @ys << y
+        self
+      end
+
+      # Parameters in (0, 1) where the cubic's derivative is zero.
+      def extrema(from, first, second, to)
+        a = -from + (3 * first) - (3 * second) + to
+        b = 2 * (from - (2 * first) + second)
+        c = first - from
+        roots(a, b, c).select { |t| t.positive? && t < 1 }
+      end
+
+      def roots(a, b, c)
+        return b.zero? ? [] : [-c.fdiv(b)] if a.zero?
+
+        discriminant = (b**2) - (4 * a * c)
+        return [] if discriminant.negative?
+
+        [1, -1].map { |sign| (-b + (sign * Math.sqrt(discriminant))) / (2.0 * a) }
+      end
+
+      def cubic(at, from, first, second, to)
+        rest = 1 - at
+        ((rest**3) * from) + (3 * (rest**2) * at * first) + (3 * rest * (at**2) * second) + ((at**3) * to)
+      end
+    end
+  end
+end