stationery 0.6.0 → 0.8.0

data/lib/stationery/hyphenation.rb

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

data/lib/stationery/images/jpeg.rb

@@ -21,9 +21,10 @@ module Stationery
       end
 
       def inspect = "#<#{self.class} #{@width}x#{@height}>"
+      def color_space = COLOR_SPACES.fetch(@components)
 
       def build(writer)
-        dictionary = Images.xobject(@width, @height, COLOR_SPACES.fetch(@components), @bits).merge(Filter: :DCTDecode)
+        dictionary = Images.xobject(@width, @height, color_space, @bits).merge(Filter: :DCTDecode)
         # Adobe CMYK JPEGs store inverted values.
         dictionary[:Decode] = [1, 0] * 4 if @components == 4 && @adobe
         writer.add(PDF::Stream.new(@data, dictionary))

data/lib/stationery/images/png.rb

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

data/lib/stationery/images/resampled.rb

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

data/lib/stationery/layout/image.rb

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

data/lib/stationery/layout/paginator.rb

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

data/lib/stationery/layout/text.rb

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

data/lib/stationery/minitest.rb

@@ -17,6 +17,23 @@ module Stationery
       def assert_image_count(subject, count, msg = nil) = assert_pdf(Matchers::HaveImageCount.new(count), subject, msg)
       def assert_bookmark(subject, title, msg = nil) = assert_pdf(Matchers::HaveBookmark.new(title), subject, msg)
       def assert_pdf_language(subject, lang, msg = nil) = assert_pdf(Matchers::HaveLanguage.new(lang), subject, msg)
+
+      def assert_page_labels(subject, labels, msg = nil)
+        assert_pdf(Matchers::HavePageLabels.new(labels), subject, msg)
+      end
+
+      def assert_pdf_attachment(subject, name, msg = nil, **)
+        assert_pdf(Matchers::HaveAttachment.new(name, **), subject, msg)
+      end
+
+      def assert_pdf_conformance(subject, levels, msg = nil)
+        assert_pdf(Matchers::HaveConformance.new(*levels), subject, msg)
+      end
+
+      def assert_factur_x(subject, msg = nil, profile: nil)
+        assert_pdf(Matchers::HaveFacturX.new(profile:), subject, msg)
+      end
+
       def assert_no_pdf_warnings(subject, msg = nil) = assert_pdf(Matchers::HaveNoWarnings.new, subject, msg)
       def assert_pdf_structure(subject, tree, msg = nil) = assert_pdf(Matchers::HaveStructure.new(tree), subject, msg)
       def assert_tagged_content(subject, msg = nil) = assert_pdf(Matchers::HaveTaggedContent.new, subject, msg)

data/lib/stationery/page_templates.rb

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

data/lib/stationery/pdf/assembler.rb

@@ -5,10 +5,23 @@ module Stationery
     # Writes finished pages, their shared resources and document info as PDF.
     class Assembler
       # `tagging:` (a Tagging::Tree) writes the structure tree of a tagged PDF;
-      # `lang:` is the document's natural language.
-      def initialize(pages:, resources:, info: {}, outline: [], encryption: nil, tagging: nil, lang: nil)
+      # `lang:` is the document's natural language; `page_labels:` is the
+      # /PageLabels number tree from PageLabels.entries; `attachments:` are
+      # PDF::Attachment files to embed; `xmp:` (true) writes the XMP packet,
+      # with `xmp_extensions:` as further schemas and `xmp_schemas:` describing
+      # them to PDF/A (see XMP); `conformance:` (a PDF::Conformance) adds what
+      # PDF/A and PDF/UA ask of the file.
+      def initialize(pages:, resources:, info: {}, outline: [], encryption: nil, tagging: nil, lang: nil,
+                     page_labels: nil, attachments: [], xmp: true, xmp_extensions: {}, xmp_schemas: [],
+                     conformance: nil)
+        @xmp_schemas = xmp_schemas
+        @conformance = conformance
         @tagging = tagging
         @lang = lang
+        @page_labels = page_labels
+        @attachments = attachments
+        @xmp = xmp
+        @xmp_extensions = xmp_extensions
         @pages = pages
         @resources = resources
         @info = info
@@ -26,14 +39,19 @@ module Stationery
         @pages.each_with_index { |page, index| write_page(writer, page, kids[index], tree, refs) }
         writer.set(tree, { Type: :Pages, Kids: kids, Count: kids.size })
         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))
+        now = Time.now
+        info = info_dictionary(now)
+        entries = catalog(tree, outlines, @form.write)
+                  .merge(accessibility(writer), metadata(writer, info, now), Attachments.write(writer, @attachments))
+        entries.merge!(@conformance.catalog_entries(writer)) if @conformance
+        writer.render(root: writer.add(entries), info: writer.add(info))
       end
 
       private
 
       def catalog(tree, outlines, form)
         catalog = { Type: :Catalog, Pages: tree }
+        catalog[:PageLabels] = @page_labels if @page_labels
         catalog[:AcroForm] = form if form
         outlines ? catalog.merge(Outlines: outlines, PageMode: :UseOutlines) : catalog
       end
@@ -55,6 +73,7 @@ module Stationery
           dictionary[:Annots] = page.annotations.map { |annot| annotation_ref(writer, annot, ref) }
         end
         dictionary.merge!(@structure.page_entries(page)) if @structure
+        dictionary.merge!(@conformance.page_entries(page)) if @conformance
         writer.set(ref, dictionary)
       end
 
@@ -73,6 +92,7 @@ module Stationery
 
         ref = writer.reserve
         dictionary = annotation(annotation)
+        dictionary = dictionary.merge(@conformance.annotation_entries(annotation)) if @conformance
         dictionary = dictionary.merge(@structure.annotation(annotation, ref)) if @structure
         writer.set(ref, dictionary)
       end
@@ -86,12 +106,26 @@ module Stationery
         { Type: :Annot, Subtype: :Link, Rect: link[:rect], Border: [0, 0, 0], **target }
       end
 
-      def info_dictionary
+      def info_dictionary(now)
         info = { Producer: "Stationery #{VERSION}" }.merge(@info.compact)
         info = info.transform_values { |value| TextString.new(value.to_s) }
-        info[:CreationDate] = TextString.new(Time.now.utc.strftime("D:%Y%m%d%H%M%SZ"))
+        info[:CreationDate] = TextString.new(now.utc.strftime("D:%Y%m%d%H%M%SZ"))
         info
       end
+
+      def extensions = (@conformance&.xmp_extensions || {}).merge(@xmp_extensions)
+      def schemas = (@conformance&.xmp_schemas || []) + @xmp_schemas
+
+      # The XMP packet as an uncompressed /Metadata stream, mirroring the Info
+      # dictionary at the same instant. An encrypted document encrypts it like
+      # every other stream (/EncryptMetadata defaults to true).
+      def metadata(writer, info, now)
+        return {} unless @xmp
+
+        values = info.except(:CreationDate).transform_values(&:value)
+        packet = XMP.packet(info: values, lang: @lang, time: now, extensions:, schemas:)
+        { Metadata: writer.add(Stream.new(packet, { Type: :Metadata, Subtype: :XML }, compress: false)) }
+      end
     end
   end
 end

data/lib/stationery/pdf/attachments.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "digest/md5"
+
+module Stationery
+  module PDF
+    # A file embedded in the document: its name, bytes, MIME type, an
+    # optional description and how it relates to the document (the
+    # /AFRelationship a Factur-X invoice or a PDF/A-3 attachment declares).
+    Attachment = Data.define(:name, :data, :mime, :description, :relationship, :modified_at)
+
+    # Builds and writes embedded files: each becomes a /Filespec with an
+    # /EmbeddedFile stream, listed in the catalog's /Names /EmbeddedFiles
+    # tree and its /AF array.
+    module Attachments
+      RELATIONSHIPS = { alternative: :Alternative, source: :Source, data: :Data, supplement: :Supplement,
+                        unspecified: :Unspecified }.freeze
+
+      module_function
+
+      def build(name, data, mime: "application/octet-stream", description: nil, relationship: :unspecified,
+                modified_at: nil)
+        name = name.to_s
+        raise ArgumentError, "an attachment needs a name" if name.empty?
+        raise ArgumentError, "attachment #{name.inspect} needs its data as a String" unless data.is_a?(String)
+        unless RELATIONSHIPS.key?(relationship)
+          raise ArgumentError, "unknown attachment relationship #{relationship.inspect}; use one of " \
+                               "#{RELATIONSHIPS.keys.map(&:inspect).join(", ")}"
+        end
+
+        Attachment.new(name:, data: data.b, mime: mime.to_s, description: description&.to_s, relationship:,
+                       modified_at:)
+      end
+
+      # One list from class-level attachments and per-render hashes
+      # (`{ name:, data:, mime:, … }`); the same name twice raises.
+      def merge(*lists)
+        lists.flatten.compact.map { |item| item.is_a?(Attachment) ? item : from_hash(item) }.tap do |all|
+          duplicate = all.map(&:name).tally.find { |_, count| count > 1 }&.first
+          raise ArgumentError, "attachment #{duplicate.inspect} is given twice" if duplicate
+        end
+      end
+
+      def from_hash(hash)
+        hash = hash.to_h.transform_keys(&:to_sym)
+        build(hash[:name], hash[:data], **hash.except(:name, :data))
+      end
+
+      # The catalog entries for the files, written through `writer`; empty without any.
+      def write(writer, attachments)
+        return {} if attachments.nil? || attachments.empty?
+
+        refs = attachments.sort_by(&:name).map do |attachment|
+          [attachment.name, writer.add(filespec(writer, attachment))]
+        end
+        { Names: { EmbeddedFiles: { Names: refs.flatten } }, AF: refs.map(&:last) }
+      end
+
+      def filespec(writer, attachment)
+        spec = { Type: :Filespec, F: attachment.name.b, UF: TextString.new(attachment.name),
+                 AFRelationship: RELATIONSHIPS.fetch(attachment.relationship),
+                 EF: { F: writer.add(stream(attachment)) } }
+        spec[:Desc] = TextString.new(attachment.description) if attachment.description
+        spec
+      end
+
+      def stream(attachment)
+        params = { Size: attachment.data.bytesize, CheckSum: HexString.new(Digest::MD5.digest(attachment.data)) }
+        if attachment.modified_at
+          params[:ModDate] = TextString.new(attachment.modified_at.utc.strftime("D:%Y%m%d%H%M%SZ"))
+        end
+        Stream.new(attachment.data, { Type: :EmbeddedFile, Subtype: attachment.mime.to_sym, Params: params })
+      end
+    end
+  end
+end