stationery 0.7.0 → 0.8.0

data/lib/stationery/pdf/conformance.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Stationery
+  module PDF
+    # The archival and accessibility standards a render claims, and what each
+    # asks of the file: PDF/A-2b and PDF/A-3b (ISO 19005-2/3, level B) and
+    # PDF/UA-1 (ISO 14289-1). Levels combine: `Conformance.new(:pdf_a3b, :pdf_ua1)`.
+    #
+    # A claim is only written when the document keeps it: what cannot be made
+    # conformant raises (ArgumentError for options that contradict the level,
+    # ConformanceError for content), so a file is never mislabelled.
+    class Conformance
+      LEVELS = {
+        pdf_a2b: { standard: :pdf_a, part: 2, conformance: "B", label: "PDF/A-2b" },
+        pdf_a3b: { standard: :pdf_a, part: 3, conformance: "B", label: "PDF/A-3b" },
+        pdf_ua1: { standard: :pdf_ua, part: 1, label: "PDF/UA-1" }
+      }.freeze
+      PDFA_ID = "http://www.aiim.org/pdfa/ns/id/"
+      PDFUA_ID = "http://www.aiim.org/pdfua/ns/id/"
+      # PDF/A knows its own schema; PDF/UA's has to be described to it.
+      PDFUA_SCHEMA = {
+        name: "PDF/UA identification schema", uri: PDFUA_ID, prefix: "pdfuaid",
+        properties: [{ name: "part", type: "Integer", category: "internal",
+                       description: "The part of ISO 14289 the document conforms to" }]
+      }.freeze
+      ICC_PROFILE = File.expand_path("icc/sRGB2014.icc", __dir__)
+      OUTPUT_CONDITION = "sRGB IEC61966-2.1"
+      PRINT = 4
+      CMYK_OPERATOR = /^(?:-?[\d.]+ ){4}[kK]$/
+
+      attr_reader :levels
+
+      def self.label(level) = LEVELS.dig(level.to_sym, :label) || level.to_s
+
+      # The Conformance for `levels` (a Symbol, an Array or nil); nil without any.
+      def self.for(levels)
+        levels = Array(levels).flatten.compact
+        levels.empty? ? nil : new(*levels)
+      end
+
+      def initialize(*levels)
+        @levels = levels.flatten.map(&:to_sym).uniq
+        unknown = @levels - LEVELS.keys
+        raise ArgumentError, "unknown conformance #{unknown.map(&:inspect).join(", ")} (use #{names})" if unknown.any?
+        raise ArgumentError, "conformance takes one PDF/A level, got #{archival.join(" and ")}" if archival.size > 1
+      end
+
+      def pdf_a? = archival.any?
+      def pdf_ua? = @levels.include?(:pdf_ua1)
+      # The PDF/A part (2 or 3), nil without one.
+      def part = archival.first && LEVELS.dig(archival.first, :part)
+
+      # What can be refused before anything is drawn: options and metadata.
+      def validate!(encrypt:, metadata:, attachments:)
+        raise ArgumentError, "PDF/A forbids encryption: drop encrypt: or the conformance level" if pdf_a? && encrypt
+        if part == 2 && attachments.any?
+          raise ArgumentError, "PDF/A-2b only embeds PDF/A files: use conformance :pdf_a3b to attach " \
+                               "#{attachments.map(&:name).join(", ")}"
+        end
+
+        missing = pdf_ua? ? %i[title lang].select { |key| metadata[key].to_s.strip.empty? } : []
+        raise ConformanceError.new(@levels, missing.map { |key| "metadata #{key}: is missing" }) if missing.any?
+      end
+
+      # What only the finished pages show. Colour that the sRGB output intent
+      # does not cover is reported; what breaks the claim outright raises.
+      def audit!(pages, resources:, warnings:)
+        cmyk(pages, resources).each { |subject| warnings << Warnings::ConformanceIssue.new(level: archival.first, subject:) }
+        issues = fields(pages) + alternatives(warnings)
+        raise ConformanceError.new(@levels, issues) if issues.any?
+      end
+
+      # The identification schemas for the XMP packet (see XMP.packet).
+      def xmp_extensions
+        extensions = {}
+        extensions[PDFA_ID] = { prefix: "pdfaid", "part" => part, "conformance" => "B" } if pdf_a?
+        extensions[PDFUA_ID] = { prefix: "pdfuaid", "part" => 1 } if pdf_ua?
+        extensions
+      end
+
+      # Schemas PDF/A has to be told about: PDF/UA's, when both are claimed.
+      def xmp_schemas = pdf_a? && pdf_ua? ? [PDFUA_SCHEMA] : []
+
+      # The catalog's entries: the sRGB output intent of a PDF/A file.
+      def catalog_entries(writer)
+        return {} unless pdf_a?
+
+        profile = writer.add(Stream.new(File.binread(ICC_PROFILE), { N: 3 }))
+        { OutputIntents: [{ Type: :OutputIntent, S: :GTS_PDFA1, DestOutputProfile: profile,
+                            OutputConditionIdentifier: TextString.new(OUTPUT_CONDITION),
+                            Info: TextString.new(OUTPUT_CONDITION) }] }
+      end
+
+      # A page's entries: PDF/UA tabs through annotations in structure order.
+      def page_entries(page) = pdf_ua? && page.annotations.any? ? { Tabs: :S } : {}
+
+      # A link annotation's entries: printable, and described for PDF/UA.
+      def annotation_entries(link)
+        entries = { F: PRINT }
+        entries[:Contents] = TextString.new(description(link)) if pdf_ua?
+        entries
+      end
+
+      private
+
+      def archival = @levels.select { |level| LEVELS.dig(level, :standard) == :pdf_a }
+      def names = LEVELS.keys.map(&:inspect).join(", ")
+
+      def description(link)
+        link[:url] || "Page #{link[:dest].page + 1}"
+      end
+
+      # Form fields draw with the standard Helvetica and ZapfDingbats, which
+      # are not embedded, and ask the viewer to regenerate appearances:
+      # neither PDF/A nor PDF/UA accepts that.
+      def fields(pages)
+        names = pages.flat_map(&:annotations).filter_map { |annotation| annotation[:widget]&.name }.uniq
+        names.map { |name| %(form field "#{name}" draws with a font that is not embedded) }
+      end
+
+      def alternatives(warnings)
+        return [] unless pdf_ua?
+
+        warnings.grep(Warnings::MissingAlt).map(&:message)
+      end
+
+      def cmyk(pages, resources)
+        return [] unless pdf_a?
+
+        images = resources.images.any? { |image| image.respond_to?(:color_space) && image.color_space == :DeviceCMYK }
+        subjects = images ? ["a CMYK image"] : []
+        pages.each_with_index do |page, index|
+          subjects << "CMYK colour on page #{index + 1}" if page.content.match?(CMYK_OPERATOR)
+        end
+        subjects
+      end
+    end
+  end
+end

data/lib/stationery/pdf/factur_x.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Stationery
+  module PDF
+    # A Factur-X / ZUGFeRD e-invoice: the invoice's Cross Industry Invoice XML
+    # embedded in a PDF/A-3b file and identified in XMP, so the one document
+    # is read by people and booked by machines.
+    #
+    # Stationery carries the XML, it does not write or validate it: `xml` is
+    # the finished document as a String, or a method name, block or callable
+    # that answers it for the document being rendered.
+    class FacturX
+      NAMESPACE = "urn:factur-x:pdfa:CrossIndustryDocument:invoice:1p0#"
+      PROFILES = { minimum: "MINIMUM", basic_wl: "BASIC WL", basic: "BASIC", en16931: "EN 16931",
+                   extended: "EXTENDED", xrechnung: "XRECHNUNG" }.freeze
+      # Profiles too small to stand for the invoice: their XML is data beside
+      # the page, not an alternative to it.
+      DATA_ONLY = %i[minimum basic_wl].freeze
+      FILENAMES = { xrechnung: "xrechnung.xml" }.freeze
+      DEFAULT_FILENAME = "factur-x.xml"
+      DESCRIPTION = "Factur-X Invoice"
+      ROOTS = ["<?xml", "<rsm:CrossIndustryInvoice"].freeze
+      SCHEMA = {
+        name: "Factur-X PDFA Extension Schema", uri: NAMESPACE, prefix: "fx",
+        properties: [
+          { name: "DocumentFileName", type: "Text", category: "external",
+            description: "The name of the embedded XML document" },
+          { name: "DocumentType", type: "Text", category: "external",
+            description: "The type of the hybrid document in capital letters, e.g. INVOICE or ORDER" },
+          { name: "Version", type: "Text", category: "external",
+            description: "The actual version of the standard applying to the embedded XML document" },
+          { name: "ConformanceLevel", type: "Text", category: "external",
+            description: "The conformance level of the embedded XML document" }
+        ].freeze
+      }.freeze
+
+      attr_reader :xml, :profile, :filename, :version
+
+      # The invoice for `spec` (`{ xml:, profile:, filename:, version:,
+      # relationship: }`, as `factur_x` and `to_pdf(factur_x:)` take it)
+      # resolved for `document`; nil without a spec.
+      def self.for(spec, document)
+        return unless spec
+
+        spec = spec.to_h.transform_keys(&:to_sym)
+        new(resolve(spec[:xml], document), **spec.except(:xml))
+      end
+
+      def self.resolve(xml, document)
+        case xml
+        when Symbol then document.send(xml)
+        when Proc then xml.arity.zero? ? document.instance_exec(&xml) : xml.call(document)
+        else xml.respond_to?(:call) ? xml.call(document) : xml
+        end
+      end
+
+      def self.profile(name)
+        name = name.to_s.downcase.to_sym
+        return name if PROFILES.key?(name)
+
+        raise ArgumentError, "unknown Factur-X profile #{name.inspect} (use #{PROFILES.keys.map(&:inspect).join(", ")})"
+      end
+
+      def self.invoice?(xml) = xml.is_a?(String) && xml.delete_prefix("").lstrip.start_with?(*ROOTS)
+
+      def initialize(xml, profile: :en16931, filename: nil, version: "1.0", relationship: nil)
+        @profile = self.class.profile(profile)
+        unless self.class.invoice?(xml)
+          raise ArgumentError, "factur_x needs the invoice XML (a String starting with #{ROOTS.join(" or ")}), " \
+                               "#{got(xml)}"
+        end
+
+        @xml = xml
+        @filename = (filename || FILENAMES.fetch(@profile, DEFAULT_FILENAME)).to_s
+        @version = version.to_s
+        @relationship = relationship || (DATA_ONLY.include?(@profile) ? :data : :alternative)
+      end
+
+      # The fx:ConformanceLevel of the profile ("EN 16931").
+      def level = PROFILES.fetch(@profile)
+
+      # The declared conformance levels with the PDF/A-3b the invoice needs.
+      def conformance(levels)
+        levels = Array(levels).flatten.compact.map(&:to_sym)
+        if levels.include?(:pdf_a2b)
+          raise ArgumentError, "Factur-X embeds its XML, which needs PDF/A-3b: drop conformance :pdf_a2b"
+        end
+
+        levels.include?(:pdf_a3b) ? levels : levels + [:pdf_a3b]
+      end
+
+      # The XML as the file to embed, stamped `at` (its /ModDate).
+      def attachment(at: Time.now)
+        Attachments.build(@filename, @xml, mime: "text/xml", description: DESCRIPTION, relationship: @relationship,
+                                           modified_at: at)
+      end
+
+      # The invoice's identification for the XMP packet (see XMP.packet).
+      def xmp_extensions
+        { NAMESPACE => { prefix: "fx", "DocumentType" => "INVOICE", "DocumentFileName" => @filename,
+                         "Version" => @version, "ConformanceLevel" => level } }
+      end
+
+      # The description of the `fx` schema PDF/A asks for.
+      def xmp_schema = SCHEMA
+
+      private
+
+      def got(xml)
+        return "got #{xml.nil? ? "nil" : "a #{xml.class}"}" unless xml.is_a?(String)
+        return "got an empty String" if xml.strip.empty?
+
+        "got #{xml[0, 40].inspect}"
+      end
+    end
+  end
+end

data/lib/stationery/pdf/icc/LICENSE.md

@@ -0,0 +1,14 @@
+# sRGB2014.icc
+
+`sRGB2014.icc` is the ICC's sRGB v2 profile ("sRGB2014", copyright International Color
+Consortium, 2015), downloaded unmodified from
+<https://registry.color.org/rgb-registry/profiles/sRGB2014.icc>
+(SHA-256 `384b832de3412066743b52a75ee906b6fb9fb8d9e09e936fc2c43223815c6e0a`).
+Stationery embeds it as the output intent of PDF/A documents.
+
+The ICC's terms for profiles it owns (<https://www.color.org/profiles2.xalter#license>):
+
+> This profile is made available by the International Color Consortium, and may be copied,
+> distributed, embedded, made, used, and sold without restriction. Altered versions of this
+> profile shall have the original identification and copyright information removed and shall
+> not be misrepresented as the original profile.

data/lib/stationery/pdf/stream.rb

@@ -5,15 +5,17 @@ require "zlib"
 module Stationery
   module PDF
     # A stream object. Data is Flate-compressed unless the dictionary already
-    # names a filter (JPEG's DCTDecode, or PNG data that is already zlib).
+    # names a filter (JPEG's DCTDecode, or PNG data that is already zlib) or
+    # `compress: false` asks for it plain (XMP metadata, which PDF/A readers
+    # scan for without decoding).
     class Stream
       attr_reader :dictionary, :data
 
-      def initialize(data, dictionary = {})
+      def initialize(data, dictionary = {}, compress: !dictionary.key?(:Filter))
         data = data.b
         dictionary = dictionary.dup
 
-        unless dictionary.key?(:Filter)
+        if compress
           data = Zlib::Deflate.deflate(data)
           dictionary[:Filter] = :FlateDecode
         end

data/lib/stationery/pdf/xmp.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+module Stationery
+  module PDF
+    # The XMP metadata packet (ISO 16684-1) mirroring the document info:
+    # Dublin Core title, creator, description, subject and language, the
+    # `xmp:` dates and creator tool, and `pdf:` producer and keywords. Later
+    # identification schemas (PDF/A, PDF/UA, Factur-X) go in `extensions:`.
+    #
+    # The packet is deterministic for the same info and time: no instance
+    # ids, so two renders of one document are byte-identical.
+    module XMP
+      PACKET_ID = "W5M0MpCehiHzreSzNTczkc9d"
+      PADDING = "#{" " * 63}\n" * 32 # 2 KB of whitespace, as the spec suggests
+      DC = "http://purl.org/dc/elements/1.1/"
+      XMP_NS = "http://ns.adobe.com/xap/1.0/"
+      PDF_NS = "http://ns.adobe.com/pdf/1.3/"
+      RDF = "http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+      PDFA_EXTENSION = { "pdfaExtension" => "http://www.aiim.org/pdfa/ns/extension/",
+                         "pdfaSchema" => "http://www.aiim.org/pdfa/ns/schema#",
+                         "pdfaProperty" => "http://www.aiim.org/pdfa/ns/property#" }.freeze
+
+      module_function
+
+      # `info` is the Info dictionary's keys (`:Title`, `:Author`, `:Subject`,
+      # `:Keywords`, `:Creator`, `:Producer`), `lang` the catalog language,
+      # `time` the creation instant, and `extensions` further schemas as
+      # `{ namespace_uri => { prefix: "pdfaid", "part" => 3, "conformance" => "B" } }`:
+      # each becomes one `rdf:Description`; Array values become an `rdf:Bag`.
+      # `schemas` describes extension schemas PDF/A does not know by itself:
+      # `[{ name:, uri:, prefix:, properties: [{ name:, type:, category:, description: }] }]`.
+      def packet(info: {}, lang: nil, time: Time.now, extensions: {}, schemas: [])
+        descriptions = [dublin_core(info, lang), xmp_schema(info, time), pdf_schema(info)]
+        descriptions << extension_schemas(schemas)
+        descriptions.concat(extensions.map { |uri, values| extension(uri, values) })
+        body = <<~XML.gsub(/^ *\n/, "")
+          <?xpacket begin="" id="#{PACKET_ID}"?>
+          <x:xmpmeta xmlns:x="adobe:ns:meta/">
+           <rdf:RDF xmlns:rdf="#{RDF}">
+          #{descriptions.compact.join("\n")}
+           </rdf:RDF>
+          </x:xmpmeta>
+        XML
+        "#{body}#{PADDING}<?xpacket end=\"w\"?>\n"
+      end
+
+      def escape(value)
+        value.to_s.gsub("&", "&amp;").gsub("<", "&lt;").gsub(">", "&gt;").gsub('"', "&quot;")
+      end
+
+      def dublin_core(info, lang)
+        keywords = info[:Keywords].to_s.split(/,\s*/).reject(&:empty?)
+        elements = [
+          alt("dc:title", info[:Title]),
+          seq("dc:creator", info[:Author]),
+          alt("dc:description", info[:Subject]),
+          bag("dc:subject", keywords),
+          bag("dc:language", lang && [lang])
+        ]
+        description(DC, "dc", elements)
+      end
+
+      def xmp_schema(info, time)
+        stamp = time.utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+        elements = [
+          element("xmp:CreateDate", stamp), element("xmp:ModifyDate", stamp), element("xmp:MetadataDate", stamp),
+          element("xmp:CreatorTool", info[:Creator])
+        ]
+        description(XMP_NS, "xmp", elements)
+      end
+
+      def pdf_schema(info)
+        description(PDF_NS, "pdf", [element("pdf:Producer", info[:Producer]), element("pdf:Keywords", info[:Keywords])])
+      end
+
+      def extension(uri, values)
+        prefix = values.fetch(:prefix) { raise ArgumentError, "XMP extension #{uri} needs a :prefix" }
+        elements = values.except(:prefix).map do |name, value|
+          value.is_a?(Array) ? bag("#{prefix}:#{name}", value) : element("#{prefix}:#{name}", value)
+        end
+        description(uri, prefix, elements)
+      end
+
+      # The PDF/A extension schema container describing each of `schemas`.
+      def extension_schemas(schemas)
+        return if schemas.empty?
+
+        namespaces = PDFA_EXTENSION.map { |prefix, uri| %(xmlns:#{prefix}="#{uri}") }.join(" ")
+        items = schemas.map { |schema| "  #{schema_item(schema)}\n" }.join
+        <<~XML.chomp.gsub(/^/, "  ")
+          <rdf:Description rdf:about="" #{namespaces}>
+           <pdfaExtension:schemas><rdf:Bag>
+          #{items.chomp}
+           </rdf:Bag></pdfaExtension:schemas>
+          </rdf:Description>
+        XML
+      end
+
+      def schema_item(schema)
+        properties = schema.fetch(:properties).map do |property|
+          resource("pdfaProperty", name: property.fetch(:name), valueType: property.fetch(:type),
+                                   category: property.fetch(:category), description: property.fetch(:description))
+        end
+        head = { schema: schema.fetch(:name), namespaceURI: schema.fetch(:uri), prefix: schema.fetch(:prefix) }
+        resource("pdfaSchema", **head) do
+          "<pdfaSchema:property><rdf:Seq>#{properties.join}</rdf:Seq></pdfaSchema:property>"
+        end
+      end
+
+      def resource(prefix, **values)
+        elements = values.map { |name, value| element("#{prefix}:#{name}", value) }.join
+        %(<rdf:li rdf:parseType="Resource">#{elements}#{yield if block_given?}</rdf:li>)
+      end
+
+      def description(uri, prefix, elements)
+        elements = elements.compact
+        return if elements.empty?
+
+        "  <rdf:Description rdf:about=\"\" xmlns:#{prefix}=\"#{escape(uri)}\">\n" \
+          "#{elements.map { |line| "   #{line}\n" }.join}  </rdf:Description>"
+      end
+
+      def element(name, value)
+        return if blank?(value)
+
+        "<#{name}>#{escape(value)}</#{name}>"
+      end
+
+      def alt(name, value)
+        return if blank?(value)
+
+        "<#{name}><rdf:Alt><rdf:li xml:lang=\"x-default\">#{escape(value)}</rdf:li></rdf:Alt></#{name}>"
+      end
+
+      def seq(name, value) = list(name, "rdf:Seq", value)
+      def bag(name, value) = list(name, "rdf:Bag", value)
+
+      def list(name, container, values)
+        values = Array(values).reject { |value| blank?(value) }
+        return if values.empty?
+
+        items = values.map { |value| "<rdf:li>#{escape(value)}</rdf:li>" }.join
+        "<#{name}><#{container}>#{items}</#{container}></#{name}>"
+      end
+
+      def blank?(value) = value.nil? || value.to_s.empty?
+    end
+  end
+end

data/lib/stationery/resources.rb

@@ -11,6 +11,9 @@ module Stationery
       @shadings = {}
     end
 
+    # Every image drawn so far.
+    def images = @images.keys
+
     def font(font)
       @fonts[font] ||= :"F#{@fonts.size + 1}"
     end

data/lib/stationery/svg/clip_path.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Stationery
+  module SVG
+    # Turns `clip-path: url(#id)` into the Region an element is painted in.
+    # The shapes of the clipPath (and the shapes its `use` children refer to)
+    # are outlined in the user space of the clipped element, under the clip
+    # path's own transform and theirs; `clipPathUnits="objectBoundingBox"`
+    # scales them to the element's box. They join into one clipping path, so
+    # overlapping shapes wound in opposite directions cancel where they
+    # overlap. A clip path's own clip-path is the region around it. Text in
+    # a clip path is skipped and reported.
+    class ClipPath
+      OUTLINED = (Shapes::NAMES + %w[text]).freeze
+
+      def initialize(ids, walker)
+        @ids = ids
+        @walker = walker
+      end
+
+      # The Region for `element`, drawn with `style`; nil without such a clip
+      # path, when the element is painted unclipped.
+      def region(id, element, style, seen = [])
+        clip = @ids[id]
+        return @walker.issue("clip-path: ##{id} not found") unless clip&.name == "clipPath"
+        return @walker.issue("clip-path: circular reference ##{id}") if seen.include?(id)
+
+        base = user_space(clip, element, style) or return Region::EMPTY
+        own = base.child(clip)
+        outlines = clip.children.grep(Parser::Element).filter_map { |child| outline(child, own.child(child), id) }
+        outer = own.clip_path && region(own.clip_path, element, style, seen + [id])
+        Region.new(outlines.map(&:first), outlines.any?(&:last), outer)
+      end
+
+      private
+
+      # The style the clip path's content starts from; nil when the units
+      # are the element's box and it has none.
+      def user_space(clip, element, style)
+        space = style.at(style.matrix, Style::DEFAULTS)
+        return space unless clip.attributes["clipPathUnits"] == "objectBoundingBox"
+
+        x, y, width, height = @walker.box(element, style)
+        space.transformed([width, 0, 0, height, x, y]) if x
+      end
+
+      # [part, even-odd?] for a child that outlines something.
+      def outline(child, style, id)
+        return unless style.displayed? && style.visible?
+
+        case child.name
+        when "use" then used(child, style, id)
+        when "text" then @walker.issue("clipPath ##{id}: text")
+        when *Shapes::NAMES then [Region::Part.new(style.matrix, Region::Shape.new(child)), style.clip_even_odd?]
+        end
+      end
+
+      # A use in a clip path refers to a shape or a text, not to a group.
+      def used(child, style, id)
+        attributes = child.attributes
+        target = @ids[(attributes["href"] || attributes["xlink:href"]).to_s[/\A#(.+)/, 1]]
+        return unless target && OUTLINED.include?(target.name)
+
+        placed = style.transformed([1, 0, 0, 1, Shapes.f(attributes, "x"), Shapes.f(attributes, "y")])
+        outline(target, placed.child(target), id)
+      end
+    end
+  end
+end

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)