stationery 0.10.0 → 0.11.0

data/lib/stationery/fonts/shaping.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Fonts
+    # One font's side of the shaper hook (see Shaper): asks the document's
+    # shaper to place a text, checks the answer and remembers it per size,
+    # features and text, so measuring a stretch and then drawing it asks once.
+    # Like the font's own memos, what is remembered starts over after
+    # Font::MEMO_BYTES of text, so a long document does not keep every line.
+    class Shaping
+      def initialize(font, shaper, path: nil, language: nil)
+        @font = font
+        @shaper = shaper
+        @language = language
+        @path = path
+        @features = {}
+        @runs = {}
+        @memoised = 0
+      end
+
+      # The ShapedRun of `text`, or nil when the shaper declines it.
+      def run(text, size, kerning:, ligatures:, features:)
+        features = switches(kerning ? true : false, ligatures ? true : false, features)
+        runs = ((@runs[size] ||= {}.compare_by_identity)[features] ||= {})
+        runs.fetch(text) do
+          forget if (@memoised += text.bytesize) > Font::MEMO_BYTES
+          runs[text] = shape(text, size, features)
+        end
+      end
+
+      # What the shaper is told about the font.
+      def face
+        @face ||= begin
+          ttf = @font.ttf
+          path, index = Registry::FACE.match(@path.to_s)&.captures || [@path, 0]
+          Shaper::Face.new(path: path && File.expand_path(path.to_s), index: index.to_i, data: ttf.data,
+                           units_per_em: ttf.units_per_em, postscript_name: ttf.postscript_name,
+                           glyph_count: ttf.num_glyphs)
+        end
+      end
+
+      private
+
+      def forget
+        @runs.each_value { |sizes| sizes.each_value(&:clear) }
+        @memoised = 0
+      end
+
+      # { tag => on }, one frozen Hash per set of switches so the runs are
+      # remembered by its identity.
+      def switches(kerning, ligatures, features)
+        tags = Text::Style.features(features)
+        @features[[kerning, ligatures, tags]] ||=
+          { "kern" => kerning, "liga" => ligatures }.merge(tags.to_h { |tag| [tag, true] }).freeze
+      end
+
+      def shape(text, size, features)
+        answer = @shaper.call(text, face, size:, features:, language: @language)
+        answer && ShapedRun.build(@font, size, text, Shaper.glyphs(answer, text, face))
+      end
+    end
+  end
+end

data/lib/stationery/forms/typeface.rb

@@ -30,7 +30,12 @@ module Stationery
       def embedded? = true
       def ascent(size) = primary.ascender(size)
       def descent(size) = primary.descender(size)
-      def width(text, size) = runs(text, size).sum { |font, run| font.width_of(run.text, size, ligatures: false) }
+
+      # A field is not shaped (see Shaper): a viewer that redraws it after an
+      # edit would not shape it either.
+      def width(text, size)
+        runs(text, size).sum { |font, run| font.width_of(run.text, size, ligatures: false, shape: false) }
+      end
 
       # The resource names of the fonts drawn or kept so far.
       def names = @names.values
@@ -40,7 +45,8 @@ module Stationery
 
       # The operators showing `text` at the current text position: a font
       # selection and a string per run of one font. Characters no font has
-      # draw as .notdef and are reported, as in any other text.
+      # draw as .notdef inside a Span with their ActualText (see
+      # Fonts::GlyphRun) and are reported, as in any other text.
       def show(text, size)
         runs(text, size).flat_map do |font, run|
           report(font, run)
@@ -86,7 +92,8 @@ module Stationery
     end
 
     # The standard Helvetica, not embedded: text is Windows-1252 bytes and
-    # characters outside it become "?".
+    # characters outside it become "?". That is a glyph of its own, not
+    # .notdef, so it is shown without ActualText; the field's /V has the value.
     class Standard
       NAME = :Helv
       FONT = { Type: :Font, Subtype: :Type1, BaseFont: :Helvetica, Encoding: :WinAnsiEncoding }.freeze

data/lib/stationery/html/css.rb

@@ -6,7 +6,8 @@ module Stationery
   module HTML
     # The CSS the html element reads: `<style>` rules (element, class and id
     # selectors) and inline `style` attributes, for a small set of properties
-    # that map onto the element DSL. Everything else is ignored and reported
+    # that map onto the element DSL (`float` on an `img` only, which the
+    # `align` attribute also sets). Everything else is ignored and reported
     # once per document through the Report. Values are never fetched or
     # evaluated: `url()` and `@import` are dropped like any unknown value.
     class Css
@@ -38,7 +39,7 @@ module Stationery
       # Properties read on the block an element becomes.
       BLOCK = %w[text-align background-color margin margin-top margin-bottom padding padding-top padding-right
                  padding-bottom padding-left border width page-break-before page-break-after break-before
-                 break-after page-break-inside break-inside].freeze
+                 break-after page-break-inside break-inside column-count column-gap columns].freeze
       FONT_SIZES = { "1" => 0.625, "2" => 0.8125, "3" => 1.0, "4" => 1.125, "5" => 1.5, "6" => 2.0,
                      "7" => 3.0 }.freeze
       KEYWORD_SIZES = { "xx-small" => 0.5625, "x-small" => 0.625, "small" => 0.8125, "medium" => 1.0,
@@ -61,6 +62,7 @@ module Stationery
       RGB = /\Argba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*[\d.]+\s*)?\)\z/i
       LENGTH = /\A(-?\d*\.?\d+)(px|pt|em|rem|%)?\z/
       ALIGN = %w[left center right justify].freeze
+      FLOAT = %w[left right].freeze
       BREAK_PAGE = %w[always page left right].freeze
       CSS_PX = 0.75
       LEGACY = %w[font center].freeze
@@ -95,6 +97,7 @@ module Stationery
 
           if INLINE.include?(name) then inline(name, value, marks)
           elsif BLOCK.include?(name) then block(name, value, block)
+          elsif name == "float" && element.name == "img" then read(name, value, block, :float) { float(value) }
           else report.property(name)
           end
         end
@@ -105,17 +108,26 @@ module Stationery
 
       # Nothing to read: no rules, no inline style, no legacy attributes.
       def plain?(element)
-        @sheet.empty? && !element.attributes.key?("style") && !LEGACY.include?(element.name)
+        @sheet.empty? && !element.attributes.key?("style") && !LEGACY.include?(element.name) &&
+          !(element.name == "img" && element.attributes.key?("align"))
       end
 
       def legacy(element)
         case element.name
         when "font" then font_attributes(element.attributes)
         when "center" then { "text-align" => "center" }
+        when "img" then image_attributes(element.attributes)
         else {}
         end
       end
 
+      # `align="left"` and `align="right"` float an image; the vertical
+      # alignments are not read.
+      def image_attributes(attributes)
+        side = attributes["align"].to_s.strip.downcase
+        FLOAT.include?(side) ? { "float" => side } : {}
+      end
+
       def font_attributes(attributes)
         legacy = {}
         legacy["color"] = attributes["color"] if attributes["color"]
@@ -145,6 +157,8 @@ module Stationery
         when "page-break-before", "break-before" then read(name, value, block, :break_before) { page_break(value) }
         when "page-break-after", "break-after" then read(name, value, block, :break_after) { page_break(value) }
         when "page-break-inside", "break-inside" then read(name, value, block, :keep_together) { avoid(value) }
+        when "column-count", "columns" then read(name, value, block, :columns) { column_count(value) }
+        when "column-gap" then read(name, value, block, :column_gap) { column_gap(value) }
         end
       end
 
@@ -170,6 +184,12 @@ module Stationery
 
       def align(value) = ALIGN.include?(value.downcase) ? value.downcase.to_sym : nil
 
+      def float(value)
+        return :none if value.casecmp?("none")
+
+        FLOAT.include?(value.downcase) ? value.downcase.to_sym : nil
+      end
+
       def font_size(value, marks)
         scale = KEYWORD_SIZES[value.downcase]
         match = value.match(LENGTH)
@@ -271,6 +291,21 @@ module Stationery
 
         :none if value.casecmp?("auto")
       end
+
+      # A number of columns; a column width (`columns: 12em`) is not read.
+      def column_count(value)
+        return :none if value.casecmp?("auto")
+
+        count = Integer(value, 10, exception: false)
+        count if count&.positive?
+      end
+
+      def column_gap(value)
+        return :none if value.casecmp?("normal")
+
+        gap = points(value)
+        gap unless gap&.negative?
+      end
     end
   end
 end

data/lib/stationery/html/tree_builder/blocks.rb

@@ -27,8 +27,13 @@ module Stationery
         ALIGN = /\A\s*(left|center|right|justify)\s*\z/i
         # What makes a container a block of its own instead of flattening into its parent.
         BOXED = %i[background padding padding_top padding_right padding_bottom padding_left margin margin_top
-                   margin_bottom break_before break_after keep_together].freeze
+                   margin_bottom break_before break_after keep_together columns].freeze
+        # What a block of its own takes besides.
+        WITH_BOX = %i[column_gap].freeze
         INHERITED = %i[align].freeze
+        # What an image takes from its style, and what a floated one takes too.
+        IMAGE = %i[width align].freeze
+        FLOATED = %i[width float margin margin_top margin_bottom].freeze
         EMPTY = {}.freeze
 
         def self.convert(root, css = Css.parse([])) = new(css).blocks_of(root, EMPTY, EMPTY)
@@ -72,7 +77,7 @@ module Stationery
         end
 
         # A `p` hands its whole style to its paragraphs. Any other container with a box of its own
-        # (a background, padding, margins, a page-break rule) becomes a Container; without one it
+        # (a background, padding, margins, a page-break rule, columns) becomes a Container; without one it
         # flattens into its parent, as it always did.
         def container(node, marks, inherited, style, out)
           return out.boundary(style) { children(node, marks, inherited, out) } if node.name == "p"
@@ -80,6 +85,7 @@ module Stationery
           boxed = style.slice(*BOXED)
           return out.boundary(inherited) { children(node, marks, inherited, out) } if boxed.empty?
 
+          boxed = style.slice(*BOXED, *WITH_BOX)
           out.block(Rich::Container.new(blocks: blocks_of(node, marks, inherited, inherited), style: boxed))
         end
 
@@ -125,7 +131,7 @@ module Stationery
 
           Rich::Image.new(src: attributes["src"], alt: attributes["alt"],
                           width: dimension(attributes["width"]), height: dimension(attributes["height"]),
-                          style: style.slice(:width, :align))
+                          style: style.slice(*(style[:float] ? FLOATED : IMAGE)))
         end
 
         def dimension(value) = value&.[](/\A\s*(\d+)/, 1)&.to_i

data/lib/stationery/images/images.rb

@@ -1,13 +1,12 @@
 # frozen_string_literal: true
 
 module Stationery
-  # JPEG and PNG images, embedded as image XObjects.
+  # JPEG, PNG and lossless WebP images, embedded as image XObjects.
   module Images
     PNG_SIGNATURE = "\x89PNG\r\n\x1A\n".b
     JPEG_SIGNATURE = "\xFF\xD8".b
-    UNSUPPORTED = {
-      "GIF8" => "GIF", "RIFF" => "WebP", "II*\0" => "TIFF", "MM\0*" => "TIFF", "BM" => "BMP"
-    }.freeze
+    WEBP_SIGNATURE = /\ARIFF.{4}WEBP/mn
+    UNSUPPORTED = { "GIF8" => "GIF", "II*\0" => "TIFF", "MM\0*" => "TIFF", "BM" => "BMP" }.freeze
 
     module_function
 
@@ -17,7 +16,7 @@ module Stationery
       Cache.fetch(data) do
         Stationery.instrument("image.stationery", bytes: data.bytesize) do |event|
           parse(data).tap do |image|
-            event[:format] = image.is_a?(JPEG) ? "JPEG" : "PNG"
+            event[:format] = image.class.name.split("::").last
             event[:width] = image.width
             event[:height] = image.height
           end
@@ -39,11 +38,12 @@ module Stationery
     def parse(data)
       return JPEG.new(data) if data.start_with?(JPEG_SIGNATURE)
       return PNG.new(data) if data.start_with?(PNG_SIGNATURE)
+      return WebP.new(data) if data.match?(WEBP_SIGNATURE)
 
       format = UNSUPPORTED.find { |magic, _| data.start_with?(magic.b) }&.last
       raise UnsupportedImage, "#{format} images are not supported, convert to PNG or JPEG" if format
 
-      raise UnsupportedImage, "only PNG and JPEG images are supported"
+      raise UnsupportedImage, "only JPEG, PNG and lossless WebP images are supported"
     end
 
     def xobject(width, height, color_space, bits)

data/lib/stationery/images/resampled.rb

@@ -7,7 +7,8 @@ module Stationery
     # 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.
+    # PNG#resample and WebP#resample; JPEG data is never decoded, so it
+    # never comes here.
     class Resampled
       attr_reader :width, :height
 
@@ -73,7 +74,7 @@ module Stationery
       end
     end
 
-    # Decoded PNG samples: `color` and `alpha` are Arrays of rows, each row an
+    # Decoded PNG or WebP 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

data/lib/stationery/images/webp/bit_reader.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Images
+    class WebP
+      # Reads a VP8L bitstream least significant bit first. Bits are kept in
+      # one Integer window refilled four bytes at a time; past the end of the
+      # data the window fills with zeros and `overrun?` turns true, so the
+      # decoder's loops stay free of bounds checks and end on their own.
+      class BitReader
+        # Most bits one `read` may ask for; the window then stays a Fixnum.
+        MAX_BITS = 24
+
+        def initialize(data, pos = 0, limit = data.bytesize)
+          @data = data
+          @pos = pos
+          @limit = limit
+          @window = 0
+          @bits = 0
+          @missing = 0
+        end
+
+        def read(count)
+          fill if @bits < count
+          value = @window & ((1 << count) - 1)
+          @window >>= count
+          @bits -= count
+          value
+        end
+
+        # The next symbol of a prefix code, from its lookup table (see
+        # PrefixCode): an entry holds the code's length above bit 16, and one
+        # at LINK or above points into a second-level table for codes longer
+        # than ROOT_BITS.
+        def symbol(table)
+          fill if @bits < MAX_BITS
+          entry = table[@window & PrefixCode::ROOT_MASK]
+          if entry >= PrefixCode::LINK
+            @window >>= PrefixCode::ROOT_BITS
+            @bits -= PrefixCode::ROOT_BITS
+            entry = table[(entry & 0xFFFF) + (@window & ((1 << ((entry >> 16) & 0xF)) - 1))]
+          end
+          length = entry >> 16
+          @window >>= length
+          @bits -= length
+          entry & 0xFFFF
+        end
+
+        # True once more bits were consumed than the data holds.
+        def overrun? = @bits < @missing
+
+        private
+
+        def fill
+          if @pos + 4 <= @limit
+            @window |= @data.unpack1("V", offset: @pos) << @bits
+            @pos += 4
+            @bits += 32
+          else
+            fill_tail
+          end
+        end
+
+        def fill_tail
+          while @bits < MAX_BITS
+            if @pos < @limit
+              @window |= @data.getbyte(@pos) << @bits
+              @pos += 1
+            else
+              @missing += 8
+            end
+            @bits += 8
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stationery/images/webp/container.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Images
+    class WebP
+      # The RIFF container: finds the lossless bitstream, either the file's
+      # only chunk or the image of an extended (VP8X) file, whose colour
+      # profile and metadata chunks are skipped. Lossy and animated files
+      # are refused by name.
+      class Container
+        HEADER_BYTES = 12
+        ANIMATED = 0x02
+        LOSSY = "lossy WebP images are not supported, convert to JPEG, PNG or lossless WebP"
+        ANIMATION = "animated WebP images are not supported, convert to JPEG, PNG or lossless WebP"
+
+        # The canvas size of an extended file, nil for a bare bitstream.
+        attr_reader :canvas
+
+        def initialize(data)
+          @data = data
+          @limit = data.unpack1("V", offset: 4) + 8 if data.bytesize >= HEADER_BYTES
+          raise UnsupportedImage, "truncated WebP image" if @limit.nil? || @limit > data.bytesize
+        end
+
+        # The bytes of the VP8L chunk.
+        def bitstream
+          pos = HEADER_BYTES
+          while pos < @limit
+            type, payload = chunk(pos)
+            case type
+            when "VP8L" then return payload
+            when "VP8X" then read_extension(payload)
+            when "VP8 ", "ALPH" then raise UnsupportedImage, LOSSY
+            when "ANIM", "ANMF" then raise UnsupportedImage, ANIMATION
+            end
+            pos += 8 + payload.bytesize + (payload.bytesize & 1)
+          end
+          raise UnsupportedImage, "invalid WebP image: no image data"
+        end
+
+        private
+
+        def chunk(pos)
+          raise UnsupportedImage, "truncated WebP image" if pos + 8 > @limit
+
+          type, size = @data.unpack("a4V", offset: pos)
+          raise UnsupportedImage, "truncated WebP image" if pos + 8 + size > @limit
+
+          [type, @data.byteslice(pos + 8, size)]
+        end
+
+        def read_extension(payload)
+          raise UnsupportedImage, "invalid WebP image: extended header" if payload.bytesize < 10
+          raise UnsupportedImage, ANIMATION if payload.getbyte(0).anybits?(ANIMATED)
+
+          # Width and height less one, 24 bits each.
+          @canvas = [4, 7].map { |at| "#{payload.byteslice(at, 3)}\0".unpack1("V") + 1 }
+        end
+      end
+    end
+  end
+end

data/lib/stationery/images/webp/image_stream.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Images
+    class WebP
+      # One entropy-coded image of a VP8L bitstream, decoded to an Array of
+      # ARGB Integers: the pixels themselves (with the entropy image choosing
+      # a group of prefix codes per block) and the smaller images the
+      # transforms and the entropy image are stored as.
+      class ImageStream
+        LITERALS = 256
+        LENGTH_CODES = 24
+        DISTANCE_CODES = 40
+        MAX_CACHE_BITS = 11
+        HASH = 0x1E35A7BD
+        # Distance codes 1..120 name a pixel near the current one: the
+        # vertical offset in the high nibble, 8 minus the horizontal one in
+        # the low nibble.
+        NEIGHBOURS = [
+          0x18, 0x07, 0x17, 0x19, 0x28, 0x06, 0x27, 0x29, 0x16, 0x1a, 0x26, 0x2a, 0x38, 0x05, 0x37, 0x39, 0x15, 0x1b,
+          0x36, 0x3a, 0x25, 0x2b, 0x48, 0x04, 0x47, 0x49, 0x14, 0x1c, 0x35, 0x3b, 0x46, 0x4a, 0x24, 0x2c, 0x58, 0x45,
+          0x4b, 0x34, 0x3c, 0x03, 0x57, 0x59, 0x13, 0x1d, 0x56, 0x5a, 0x23, 0x2d, 0x44, 0x4c, 0x55, 0x5b, 0x33, 0x3d,
+          0x68, 0x02, 0x67, 0x69, 0x12, 0x1e, 0x66, 0x6a, 0x22, 0x2e, 0x54, 0x5c, 0x43, 0x4d, 0x65, 0x6b, 0x32, 0x3e,
+          0x78, 0x01, 0x77, 0x79, 0x53, 0x5d, 0x11, 0x1f, 0x64, 0x6c, 0x42, 0x4e, 0x76, 0x7a, 0x21, 0x2f, 0x75, 0x7b,
+          0x31, 0x3f, 0x63, 0x6d, 0x52, 0x5e, 0x00, 0x74, 0x7c, 0x41, 0x4f, 0x10, 0x20, 0x62, 0x6e, 0x30, 0x73, 0x7d,
+          0x51, 0x5f, 0x40, 0x72, 0x7e, 0x61, 0x6f, 0x50, 0x71, 0x7f, 0x60, 0x70
+        ].freeze
+
+        def self.decode(reader, width, height, top: false) = new(reader, width, height).decode(top:)
+
+        # The side of an image stored at one sample per 2**bits pixels.
+        def self.subsample(size, bits) = (size + (1 << bits) - 1) >> bits
+
+        def initialize(reader, width, height)
+          @reader = reader
+          @width = width
+          @height = height
+        end
+
+        # Only the top-level image may carry an entropy image.
+        def decode(top:)
+          read_cache
+          read_entropy_image if top && @reader.read(1) == 1
+          read_groups
+          pixels
+        end
+
+        private
+
+        def read_cache
+          return if @reader.read(1).zero?
+
+          bits = @reader.read(4)
+          raise UnsupportedImage, "invalid WebP image: colour cache size" unless (1..MAX_CACHE_BITS).cover?(bits)
+
+          @cache = Array.new(1 << bits, 0)
+          @shift = 32 - bits
+        end
+
+        def read_entropy_image
+          @block_bits = @reader.read(3) + 2
+          @block_mask = (1 << @block_bits) - 1
+          @blocks_wide = self.class.subsample(@width, @block_bits)
+          image = self.class.decode(@reader, @blocks_wide, self.class.subsample(@height, @block_bits))
+          @entropy = image.map { |argb| (argb >> 8) & 0xFFFF }
+        end
+
+        # Five prefix codes per group: green (with lengths and cache
+        # indexes), red, blue, alpha and distance. Groups no block refers to
+        # are read and dropped.
+        def read_groups
+          used = @entropy ? @entropy.uniq.to_h { |index| [index, true] } : { 0 => true }
+          green = LITERALS + LENGTH_CODES + (@cache ? @cache.size : 0)
+          @groups = Array.new(used.keys.max + 1) do |index|
+            codes = [green, LITERALS, LITERALS, LITERALS, DISTANCE_CODES].map { |size| PrefixCode.read(@reader, size) }
+            codes << literal_base(codes) if used[index]
+          end
+        end
+
+        # Red, blue and alpha in place when all three codes hold one symbol,
+        # so a pixel is one green symbol away; nil otherwise.
+        def literal_base(codes)
+          red, blue, alpha = codes[1, 3].map { |table| table[0] }
+          return if [red, blue, alpha].any? { |entry| entry > 0xFFFF }
+
+          (alpha << 24) | (red << 16) | blue
+        end
+
+        # rubocop:disable-next Metrics/AbcSize, Metrics/MethodLength -- the pixel loop, kept in one frame
+        def pixels
+          out = Array.new(@width * @height, 0)
+          total = out.size
+          reader = @reader
+          cache = @cache
+          group = @groups[0]
+          pos = 0
+          column = 0
+          while pos < total
+            group = group_at(pos) if @entropy && column.nobits?(@block_mask)
+            green = reader.symbol(group[0])
+            if green >= LITERALS && green < LITERALS + LENGTH_CODES
+              pos = copy(out, pos, extent(green - LITERALS), extent(reader.symbol(group[4])))
+              column = pos % @width
+              group = group_at(pos) if @entropy && pos < total
+              next
+            end
+
+            argb = if green >= LITERALS
+                     cache[green - LITERALS - LENGTH_CODES]
+                   elsif (base = group[5])
+                     base | (green << 8)
+                   else
+                     red = reader.symbol(group[1])
+                     blue = reader.symbol(group[2])
+                     (reader.symbol(group[3]) << 24) | (red << 16) | (green << 8) | blue
+                   end
+            out[pos] = argb
+            cache[((argb * HASH) & 0xFFFFFFFF) >> @shift] = argb if cache
+            pos += 1
+            column += 1
+            column = 0 if column == @width
+          end
+          out
+        end
+
+        def group_at(pos)
+          @groups[@entropy[(((pos / @width) >> @block_bits) * @blocks_wide) + ((pos % @width) >> @block_bits)]]
+        end
+
+        # The length or distance code a prefix symbol and its extra bits
+        # stand for.
+        def extent(symbol)
+          return symbol + 1 if symbol < 4
+
+          bits = (symbol - 2) >> 1
+          ((2 + (symbol & 1)) << bits) + @reader.read(bits) + 1
+        end
+
+        # Repeats `length` pixels from `code` back (overlapping on purpose:
+        # a run repeats itself) and returns the position after them.
+        def copy(out, pos, length, code)
+          distance = distance_of(code)
+          stop = pos + length
+          raise UnsupportedImage, "invalid WebP image: backward reference out of range" if distance > pos
+          raise UnsupportedImage, "invalid WebP image: backward reference past the end" if stop > out.size
+
+          cache = @cache
+          source = pos - distance
+          while pos < stop
+            argb = out[source]
+            out[pos] = argb
+            cache[((argb * HASH) & 0xFFFFFFFF) >> @shift] = argb if cache
+            source += 1
+            pos += 1
+          end
+          stop
+        end
+
+        def distance_of(code)
+          return code - NEIGHBOURS.size if code > NEIGHBOURS.size
+
+          neighbour = NEIGHBOURS[code - 1]
+          [((neighbour >> 4) * @width) + 8 - (neighbour & 0xF), 1].max
+        end
+      end
+    end
+  end
+end