stationery 0.6.0 → 0.8.0

data/lib/stationery/svg/document.rb

@@ -3,14 +3,17 @@
 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, <style> stylesheets, transforms, linear/radial gradients
-    # and text/tspan. `currentColor` takes the colour you pass.
+    # sets and exports use: path, rect (with rx), circle, ellipse, line,
+    # polyline, polygon and g, with fill, stroke, stroke width/caps/joins,
+    # fill-rule, opacity, inline styles, <style> stylesheets, transforms,
+    # linear/radial gradients and text/tspan; `use` (of shapes, groups, text,
+    # symbols and other uses), `symbol` and nested `svg` viewports with
+    # `preserveAspectRatio`, and `clipPath`. `currentColor` takes the colour
+    # you pass, or the `color` an element sets.
     class Document
-      SHAPES = %w[path rect circle ellipse line polyline polygon].freeze
+      SHAPES = Shapes::NAMES
       QUIET = (SHAPES + %w[svg g title desc metadata style defs linearGradient radialGradient stop text
-                           tspan]).freeze
+                           tspan use symbol clipPath]).freeze
 
       def self.parse(source)
         root = Parser.parse(source)
@@ -26,6 +29,7 @@ module Stationery
         @view_box = read_view_box
         @sheet = Stylesheet.parse(style_text)
         @gradients = Gradient.collect(root, @sheet)
+        @ids = index
         @unsupported = (element_names(root).uniq - QUIET).sort + approximations
       end
 
@@ -41,7 +45,7 @@ module Stationery
         style = Style.new(Style::DEFAULTS, [scale, 0, 0, scale, e, f], color:, sheet: @sheet).child(@root)
         painter = Painter.new(canvas, @gradients, @view_box.last(2))
         text = Text.new(canvas, painter, book || Fonts::FontBook.new, family || Fonts::Bundled::DEFAULT)
-        shapes(@root, style) do |element, own|
+        walker(painter.method(:clip)).children(@root, style) do |element, own|
           element.name == "text" ? text.draw(element, own) : painter.paint(element, own)
         end
       end
@@ -61,6 +65,14 @@ module Stationery
         styles.flat_map(&:children).join(" ")
       end
 
+      # Every element with an id, the first of a repeated id.
+      def index
+        ids = {}
+        Parser.walk(@root) { |element| ids[element.attributes["id"]] ||= element }
+        ids.delete(nil)
+        ids
+      end
+
       def element_names(element)
         element.children.grep(Parser::Element).flat_map { |child| [child.name, *element_names(child)] }
       end
@@ -71,23 +83,15 @@ module Stationery
       end
 
       # Yields every drawn shape and text with its resolved style, in paint
-      # order, skipping undisplayed subtrees and hidden elements.
-      def shapes(parent, parent_style, &)
-        parent.children.each do |element|
-          style = parent_style.child(element)
-          next unless style.displayed?
-
-          if element.name == "g" then shapes(element, style, &)
-          elsif (SHAPES.include?(element.name) || element.name == "text") && style.visible? then yield element, style
-          end
-        end
-      end
+      # order; `clipper` paints what is clipped (see Walker).
+      def walker(clipper = nil) = Walker.new(@ids, @view_box.last(2), clipper:)
 
-      # Paint references to missing gradients, gradient spreads drawn as pad
-      # and stylesheet selectors ignored.
+      # Paint references to missing gradients, gradient spreads drawn as pad,
+      # uses and clip paths that lead nowhere, and stylesheet selectors ignored.
       def approximations
+        walker = self.walker
         missing = []
-        shapes(@root, Style.new(sheet: @sheet).child(@root)) do |_element, style|
+        walker.children(@root, Style.new(sheet: @sheet).child(@root)) do |_element, style|
           [style.fill, style.stroke].grep(Style::Reference).each do |reference|
             missing << "url(##{reference.id})" unless @gradients.key?(reference.id)
           end
@@ -96,7 +100,7 @@ module Stationery
           "#{gradient.kind}Gradient spreadMethod=#{gradient.approximated_spread}" if gradient.approximated_spread
         end
         selectors = @sheet.unsupported.empty? ? [] : ["style selectors: #{@sheet.unsupported.join(", ")}"]
-        (missing + spreads).uniq.sort + selectors
+        (missing + spreads + walker.issues).uniq.sort + selectors
       end
     end
   end

data/lib/stationery/svg/painter.rb

@@ -28,6 +28,17 @@ module Stationery
                      transform: style.matrix) { |path| Shapes.trace(path, element) }
       end
 
+      # Paints the block inside `region` (a clip path's or a viewport's) and
+      # inside the regions around it.
+      def clip(region, &)
+        return clip(region.outer) { clip(region.with(outer: nil), &) } if region.outer
+
+        outlines = region.parts.map do |part|
+          @canvas.outline(transform: part.matrix) { |path| part.shape.trace(path) }
+        end
+        @canvas.clip_to(outlines, even_odd: region.even_odd, &)
+      end
+
       # A paint as one colour: a gradient's middle colour, nil for none.
       def color(paint, style)
         paint = resolve(paint)

data/lib/stationery/svg/region.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Stationery
+  module SVG
+    # What an element is clipped to: the outlines of `parts`, joined into one
+    # clipping path (even-odd when `even_odd`), inside the `outer` region when
+    # there is one. A region without parts has nothing inside it.
+    Region = Data.define(:parts, :even_odd, :outer) do
+      def empty? = parts.empty?
+    end
+
+    class Region
+      # One outline: anything that traces itself on a path (`trace(path)`),
+      # under the transform it is drawn with.
+      Part = Data.define(:matrix, :shape)
+
+      # A shape element as a part's outline.
+      Shape = Data.define(:element) do
+        def trace(path) = Shapes.trace(path, element)
+      end
+
+      EMPTY = new([], false, nil).freeze
+    end
+  end
+end

data/lib/stationery/svg/shapes.rb

@@ -4,6 +4,8 @@ module Stationery
   module SVG
     # Traces one SVG shape element onto a canvas path.
     module Shapes
+      NAMES = %w[path rect circle ellipse line polyline polygon].freeze
+
       module_function
 
       def trace(path, element)

data/lib/stationery/svg/style.rb

@@ -4,13 +4,17 @@ module Stationery
   module SVG
     # Presentation attributes an element inherits from its ancestors, and the
     # transform it draws with. An element's own values cascade: presentation
-    # attributes, then stylesheet rules, then its inline `style`.
+    # attributes, then stylesheet rules, then its inline `style`. `color` sets
+    # what `currentColor` means from the element down.
     class Style
-      INHERITED = %w[fill stroke stroke-width stroke-linecap stroke-linejoin fill-rule opacity fill-opacity
+      INHERITED = %w[fill stroke stroke-width stroke-linecap stroke-linejoin fill-rule clip-rule opacity fill-opacity
                      stroke-opacity font-family font-size font-weight font-style text-anchor visibility].freeze
+      # Properties of the element alone, not handed to its children.
+      LOCAL = %w[display clip-path overflow].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
+      IDENTITY = [1, 0, 0, 1, 0, 0].freeze
       URL = /\Aurl\(\s*['"]?#([^'")\s]+)['"]?\s*\)\s*(.*)\z/
 
       # A paint server reference, `url(#id)`, with its fallback colour (or nil).
@@ -32,34 +36,41 @@ module Stationery
 
       attr_reader :values, :matrix, :color
 
-      def initialize(values = DEFAULTS, matrix = [1, 0, 0, 1, 0, 0], color: "#000000", sheet: Stylesheet::EMPTY,
-                     display: nil)
+      def initialize(values = DEFAULTS, matrix = IDENTITY, color: "#000000", sheet: Stylesheet::EMPTY, local: {})
         @values = values
         @matrix = matrix
         @color = color
         @sheet = sheet
-        @display = display
+        @local = local
       end
 
       def child(element)
         attributes = element.attributes
         own = attributes.merge(@sheet.declarations(element), Style.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, sheet: @sheet, display: own["display"])
+        transform = attributes["transform"]
+        matrix = transform ? Transform.multiply(@matrix, Transform.parse(transform)) : @matrix
+        color = own["color"] ? Style.color(own["color"], @color) : @color
+        Style.new(@values.merge(own.slice(*INHERITED)), matrix, color:, sheet: @sheet, local: own.slice(*LOCAL))
       end
 
-      def displayed? = @display != "none"
+      # This style with `matrix` applied inside its transform: what a `use`
+      # does with its x and y, a viewport with its viewBox.
+      def transformed(matrix) = at(Transform.multiply(@matrix, matrix))
+
+      # This style drawing under another transform altogether.
+      def at(matrix, values = @values) = Style.new(values, matrix, color: @color, sheet: @sheet, local: @local)
+
+      def displayed? = @local["display"] != "none"
       def visible? = !%w[hidden collapse].include?(@values["visibility"])
+      # Whether a viewport clips what it draws: all but `visible` and `auto` do.
+      def clips? = !%w[visible auto].include?(@local["overflow"])
+      # The id of the element's `clip-path: url(#id)`, or nil.
+      def clip_path = @local["clip-path"].to_s.strip[URL, 1]
 
       def fill = paint("fill")
       def stroke = paint("stroke")
       def even_odd? = @values["fill-rule"] == "evenodd"
+      def clip_even_odd? = @values["clip-rule"] == "evenodd"
       def cap = @values["stroke-linecap"]&.to_sym
       def join = @values["stroke-linejoin"]&.to_sym
 

data/lib/stationery/svg/viewport.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Stationery
+  module SVG
+    # The rectangle a symbol or a nested svg draws into, and how its viewBox
+    # is fitted there by `preserveAspectRatio`. Lengths may be percentages of
+    # the viewport around it (`parent`, [width, height]); without a size it
+    # fills that viewport. A symbol sits at the origin of its `use`
+    # (`origin: false`), a nested svg at its own x and y.
+    class Viewport
+      ALIGNMENT = /\Ax(Min|Mid|Max)Y(Min|Mid|Max)(?:\s+(meet|slice))?\z/
+      FRACTIONS = { "Min" => 0.0, "Mid" => 0.5, "Max" => 1.0 }.freeze
+
+      attr_reader :x, :y, :width, :height
+
+      def initialize(attributes, parent, origin: true)
+        @x = origin ? length(attributes["x"], parent[0], 0) : 0
+        @y = origin ? length(attributes["y"], parent[1], 0) : 0
+        @width = length(attributes["width"], parent[0], parent[0])
+        @height = length(attributes["height"], parent[1], parent[1])
+        @view_box = read_view_box(attributes["viewBox"])
+        @aspect = attributes["preserveAspectRatio"].to_s.strip
+      end
+
+      def drawable?
+        @width.positive? && @height.positive? && (@view_box.nil? || @view_box.last(2).all?(&:positive?))
+      end
+
+      # The size percentages inside resolve against.
+      def size = @view_box ? @view_box.last(2) : [@width, @height]
+
+      # Content space to the user space the viewport sits in.
+      def matrix
+        return [1, 0, 0, 1, @x, @y] unless @view_box
+
+        vx, vy, vw, vh = @view_box
+        sx, sy = scales(@width.fdiv(vw), @height.fdiv(vh))
+        align_x, align_y = alignment
+        [sx, 0, 0, sy, @x + (align_x * (@width - (vw * sx))) - (vx * sx),
+         @y + (align_y * (@height - (vh * sy))) - (vy * sy)].map { |value| tidy(value) }
+      end
+
+      # Traces the viewport's rectangle, for clipping what overflows it.
+      def trace(path) = path.rounded_rect(@x, @y, @width, @height, 0)
+
+      private
+
+      def scales(horizontal, vertical)
+        return [horizontal, vertical] if @aspect == "none"
+
+        scale = slice? ? [horizontal, vertical].max : [horizontal, vertical].min
+        [scale, scale]
+      end
+
+      def slice? = @aspect.match(ALIGNMENT)&.[](3) == "slice"
+
+      # The share of the spare room put before the content on each axis.
+      def alignment
+        match = @aspect.match(ALIGNMENT)
+        match ? [FRACTIONS.fetch(match[1]), FRACTIONS.fetch(match[2])] : [0.5, 0.5]
+      end
+
+      def read_view_box(source)
+        values = source.to_s.split(/[\s,]+/).reject(&:empty?).map { |value| tidy(value.to_f) }
+        values if values.size == 4
+      end
+
+      def length(value, reference, default)
+        value = value.to_s.strip
+        return default if value.empty?
+
+        tidy(value.end_with?("%") ? value.to_f * reference / 100 : value.to_f)
+      end
+
+      def tidy(value) = value == value.round ? value.round : value
+    end
+  end
+end

data/lib/stationery/svg/walker.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Stationery
+  module SVG
+    # Walks a document in paint order and yields every drawn shape and text
+    # with its resolved style. A `use` draws what it refers to at its x and
+    # y, a symbol (through `use` only) and a nested svg draw into their
+    # viewport, and what has a `clip-path` or overflows a viewport is walked
+    # inside `clipper`: a callable given the Region and a block, left out
+    # when the document is only read. What cannot be followed is in `issues`.
+    class Walker
+      RENDERED = (Shapes::NAMES + %w[text g use svg]).freeze
+      VIEWPORTS = %w[symbol svg].freeze
+
+      attr_reader :issues
+
+      # `ids` are the document's elements by id, `viewport` the [width,
+      # height] percentages resolve against at the root.
+      def initialize(ids, viewport, clipper: nil)
+        @ids = ids
+        @viewports = [viewport]
+        @clipper = clipper
+        @clip_paths = ClipPath.new(ids, self)
+        @issues = []
+        @measuring = false
+      end
+
+      # Yields what the children of `parent` draw; `style` is the parent's.
+      # `chain` holds the ids of the `use` targets being drawn.
+      def children(parent, style, chain = [], &)
+        parent.children.grep(Parser::Element).each { |element| node(element, style.child(element), chain, &) }
+      end
+
+      # The box of what `element` draws, in its own user space, clipping
+      # and text aside: [x, y, width, height], or nil when it has no area.
+      def box(element, style)
+        bounds = Bounds.new
+        measuring do
+          node(element, style.at(Style::IDENTITY), []) do |shape, own|
+            corners(shape, own.matrix).each { |x, y| bounds.line_to(x, y) } unless shape.name == "text"
+          end
+        end
+        bounds.box
+      end
+
+      def issue(message)
+        @issues << message unless @measuring
+        nil
+      end
+
+      private
+
+      # Anything else (defs, symbol, clipPath, a gradient, …) draws nothing
+      # where it stands.
+      def node(element, style, chain, &)
+        return unless RENDERED.include?(element.name) && style.displayed?
+
+        clipped(element, style) do
+          case element.name
+          when "g" then children(element, style, chain, &)
+          when "use" then use(element, style, chain, &)
+          when "svg" then viewport(element, element.attributes, style, chain, &)
+          else yield element, style if style.visible?
+          end
+        end
+      end
+
+      def use(element, style, chain, &)
+        target, id = target_of(element)
+        return unless target
+        return issue("use: circular reference ##{id}") if chain.include?(id)
+
+        attributes = element.attributes
+        placed = style.transformed([1, 0, 0, 1, Shapes.f(attributes, "x"), Shapes.f(attributes, "y")])
+        instance(target, placed.child(target), attributes.slice("width", "height"), chain + [id], &)
+      end
+
+      # A symbol or an svg drawn by a use takes the use's width and height.
+      def instance(target, style, size, chain, &)
+        return node(target, style, chain, &) unless VIEWPORTS.include?(target.name)
+        return unless style.displayed?
+
+        clipped(target, style) { viewport(target, target.attributes.merge(size), style, chain, &) }
+      end
+
+      def target_of(element)
+        href = (element.attributes["href"] || element.attributes["xlink:href"]).to_s.strip
+        return issue("use: no href") if href.empty?
+
+        id = href[/\A#(.+)/, 1]
+        target = @ids[id]
+        target ? [target, id] : issue("use: #{href} not found")
+      end
+
+      def viewport(element, attributes, style, chain, &)
+        port = Viewport.new(attributes, @viewports.last, origin: element.name == "svg")
+        return unless port.drawable?
+
+        region = Region.new([Region::Part.new(style.matrix, port)], false, nil) if style.clips?
+        clip(region) { within(port) { children(element, style.transformed(port.matrix), chain, &) } }
+      end
+
+      def within(port)
+        @viewports.push(port.size)
+        yield
+      ensure
+        @viewports.pop
+      end
+
+      def clipped(element, style, &)
+        id = style.clip_path
+        return yield if id.nil? || @measuring
+
+        region = @clip_paths.region(id, element, style)
+        region ? clip(region, &) : yield
+      end
+
+      def clip(region, &)
+        return yield if region.nil? || @measuring
+        return if region.empty?
+
+        @clipper ? @clipper.call(region, &) : yield
+      end
+
+      def measuring
+        previous = @measuring
+        @measuring = true
+        yield
+      ensure
+        @measuring = previous
+      end
+
+      def corners(shape, matrix)
+        x, y, width, height = Bounds.new.tap { |bounds| Shapes.trace(bounds, shape) }.box
+        return [] unless x
+
+        [[x, y], [x + width, y], [x, y + height], [x + width, y + height]]
+          .map { |corner_x, corner_y| Transform.apply(matrix, corner_x, corner_y) }
+      end
+    end
+  end
+end

data/lib/stationery/testing/inspector.rb

@@ -12,6 +12,9 @@ module Stationery
     # Needs the pdf-reader gem, loaded on first use.
     class Inspector
       UTF16_BOM = "\xFE\xFF".b
+      XMP_PROPERTY = %r{^\s*<((?!rdf:)[\w.-]+:[\w.-]+)>(.*?)</\1>$}
+      XMP_ITEM = %r{<rdf:li[^>]*>(.*?)</rdf:li>}
+      XMP_ENTITIES = { "&amp;" => "&", "&lt;" => "<", "&gt;" => ">", "&quot;" => '"' }.freeze
 
       def initialize(subject)
         @subject = subject
@@ -39,6 +42,45 @@ module Stationery
       def page_texts = @page_texts ||= reader.pages.map { |page| page.text.squeeze(" ").strip }
       def text = page_texts.join("\n")
       def metadata = reader.info
+
+      # The XMP packet (the catalog's /Metadata stream) as a String, or nil.
+      def xmp
+        return unless catalog[:Metadata]
+
+        objects.deref!(catalog[:Metadata]).unfiltered_data.dup.force_encoding(Encoding::UTF_8)
+      end
+
+      # The packet's properties by prefixed name (`"dc:title"`): a plain value
+      # as a String, an rdf:Alt as its default String, an rdf:Seq or rdf:Bag as
+      # an Array. Reads the packets Stationery writes (one property per line).
+      def xmp_values
+        packet = xmp
+        return {} unless packet
+
+        packet.scan(XMP_PROPERTY).to_h { |name, body| [name, xmp_value(body)] }
+      end
+
+      # The conformance levels the XMP packet claims, as PDF::Conformance
+      # names them: `[:pdf_a3b, :pdf_ua1]`, or [] without a claim.
+      def conformance
+        values = xmp_values
+        part, level, accessible = values.values_at("pdfaid:part", "pdfaid:conformance", "pdfuaid:part")
+        [part && :"pdf_a#{part}#{level.to_s.downcase}", accessible && :"pdf_ua#{accessible}"].compact
+      end
+
+      # The Factur-X / ZUGFeRD invoice the XMP packet names: `{ profile:
+      # :en16931, filename:, version:, xml: }` (xml nil when the file it
+      # names is not embedded), or nil for any other PDF.
+      def factur_x
+        values = xmp_values
+        filename = values["fx:DocumentFileName"]
+        return unless filename
+
+        file = attachments.find { |attachment| attachment[:name] == filename }
+        { profile: PDF::FacturX::PROFILES.key(values["fx:ConformanceLevel"]), filename:,
+          version: values["fx:Version"], xml: file && file[:bytes].dup.force_encoding(Encoding::UTF_8) }
+      end
+
       def image_count = pdf.scan(%r{/Subtype\s*/Image\b}).size
 
       def warnings
@@ -70,6 +112,27 @@ module Stationery
         decode(lang) if lang
       end
 
+      # One label per page from the catalog /PageLabels ("i", "A-1", …), nil
+      # for pages before the first labelled range; empty without labels.
+      def page_labels
+        labels = catalog[:PageLabels]
+        return [] unless labels
+
+        nums = objects.deref_array(objects.deref_hash(labels)[:Nums]).map { |value| objects.deref(value) }
+        nums = nums.map { |value| value.is_a?(Hash) ? value.transform_values { |v| decode_value(v) } : value }
+        PDF::PageLabels.labels(nums, page_count)
+      end
+
+      # Every embedded file from the catalog's /EmbeddedFiles name tree:
+      # `{ name:, mime:, bytes:, description:, relationship: }` (bytes inflated).
+      def attachments
+        names = catalog.dig(:Names, :EmbeddedFiles)
+        return [] unless names
+
+        entries = objects.deref_array(objects.deref_hash(names)[:Names])
+        entries.each_slice(2).map { |_name, ref| attachment(objects.deref_hash(ref)) }
+      end
+
       # The structure tree of a tagged PDF as nested arrays; see StructureReader.
       def structure = @structure ||= StructureReader.new(reader).tree
 
@@ -97,6 +160,22 @@ module Stationery
         end
       end
 
+      def attachment(spec)
+        stream = objects.deref(objects.deref_hash(spec[:EF])[:F])
+        relationship = PDF::Attachments::RELATIONSHIPS.key(spec[:AFRelationship]) || spec[:AFRelationship]
+        { name: decode(spec[:UF] || spec[:F]), mime: stream.hash[:Subtype].to_s, bytes: stream.unfiltered_data,
+          description: spec[:Desc] && decode(spec[:Desc]), relationship: }
+      end
+
+      def xmp_value(body)
+        items = body.scan(XMP_ITEM).flatten.map { |item| xmp_text(item) }
+        return xmp_text(body) if items.empty?
+
+        body.start_with?("<rdf:Alt>") ? items.first : items
+      end
+
+      def xmp_text(value) = value.gsub(/&(amp|lt|gt|quot);/, XMP_ENTITIES)
+
       def destination(dest)
         return dest.to_s unless dest.is_a?(Array)
 
@@ -109,6 +188,8 @@ module Stationery
         [decode(item[:Title]), *titles(item[:First]), *titles(item[:Next])]
       end
 
+      def decode_value(value) = value.is_a?(String) ? decode(value) : value
+
       def decode(title)
         return title.dup.force_encoding(Encoding::UTF_8) unless title.b.start_with?(UTF16_BOM)
 

data/lib/stationery/testing/matchers.rb

@@ -110,6 +110,79 @@ module Stationery
         def actual = @inspector.lang ? "got #{@inspector.lang.inspect}" : "got none"
       end
 
+      class HavePageLabels < Base
+        def description = "have page labels #{@expected.inspect}"
+
+        private
+
+        def match?(pdf) = pdf.page_labels == @expected
+        def actual = @inspector.page_labels.empty? ? "got none" : "got #{@inspector.page_labels.inspect}"
+      end
+
+      class HaveConformance < Base
+        def initialize(*levels) = super(levels.flatten.map(&:to_sym))
+
+        def description = "conform to #{labels(@expected)}"
+
+        private
+
+        def labels(levels) = levels.map { |level| PDF::Conformance.label(level) }.join(" and ")
+        def match?(pdf) = (@expected - pdf.conformance).empty?
+        def actual = @inspector.conformance.empty? ? "got no claim" : "got #{labels(@inspector.conformance)}"
+      end
+
+      class HaveFacturX < Base
+        def initialize(profile: nil) = super(profile&.to_sym)
+
+        def description
+          @expected ? "be a Factur-X invoice of profile #{@expected.inspect}" : "be a Factur-X invoice"
+        end
+
+        private
+
+        def match?(pdf)
+          invoice = pdf.factur_x
+          !invoice.nil? && !invoice[:xml].nil? && (@expected.nil? || invoice[:profile] == @expected)
+        end
+
+        def actual
+          invoice = @inspector.factur_x
+          return "got no invoice" unless invoice
+          return "got #{invoice[:filename]} named in XMP but not embedded" unless invoice[:xml]
+
+          "got profile #{invoice[:profile].inspect}"
+        end
+      end
+
+      class HaveAttachment < Base
+        def initialize(name, mime: nil, relationship: nil)
+          super(name)
+          @mime = mime
+          @relationship = relationship
+        end
+
+        def description
+          extra = { mime: @mime, relationship: @relationship }.compact.map { |k, v| " #{k} #{v.inspect}" }.join
+          "have an attachment #{show(@expected)}#{extra}"
+        end
+
+        private
+
+        def match?(pdf)
+          pdf.attachments.any? do |file|
+            file[:name] == @expected && (@mime.nil? || file[:mime] == @mime) &&
+              (@relationship.nil? || file[:relationship] == @relationship)
+          end
+        end
+
+        def actual
+          files = @inspector.attachments
+          return "got none" if files.empty?
+
+          "got #{files.map { |file| "#{file[:name]} (#{file[:mime]}, #{file[:relationship]})" }.inspect}"
+        end
+      end
+
       class HaveNoWarnings < Base
         def description = "have no warnings"
 
@@ -150,6 +223,10 @@ module Stationery
       def have_image_count(expected) = HaveImageCount.new(expected)
       def have_bookmark(title) = HaveBookmark.new(title)
       def have_pdf_language(lang) = HaveLanguage.new(lang)
+      def have_page_labels(labels) = HavePageLabels.new(labels)
+      def have_attachment(name, **) = HaveAttachment.new(name, **)
+      def have_conformance(*levels) = HaveConformance.new(*levels)
+      def have_factur_x(profile: nil) = HaveFacturX.new(profile:)
       def have_no_warnings = HaveNoWarnings.new
       def have_structure(expected) = HaveStructure.new(expected)
       def have_tagged_content = HaveTaggedContent.new