stationery 0.7.0 → 0.9.0

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/rich/nesting.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Rich
+    # How deep one html or markdown source may nest, and how deep it went.
+    # Parsing, layout and painting all recurse over the nesting, so a parser
+    # flattens what lies deeper than `limit` into the deepest element it kept
+    # (text stays, structure goes) and records the depth it saw here.
+    class Nesting
+      DEFAULT = 64
+
+      attr_reader :limit, :deepest
+
+      def initialize(limit = DEFAULT)
+        unless limit.is_a?(Integer) && limit.positive?
+          raise ArgumentError, "max_depth must be a positive Integer (got #{limit.inspect})"
+        end
+
+        @limit = limit
+        @deepest = 0
+      end
+
+      def record(depth)
+        @deepest = depth if depth > @deepest
+      end
+
+      def exceeded? = @deepest > @limit
+    end
+  end
+end

data/lib/stationery/rich/renderer/indents.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Rich
+    class Renderer
+      # Block quotes and lists each indent what they hold, so nested deep
+      # enough they leave their text no width and it is lost. Past LIMIT
+      # levels the content is drawn where the last indented level put it:
+      # a block quote without its bar, list items without their markers.
+      module Indents
+        LIMIT = 12
+
+        private
+
+        def indented(block)
+          return flat(block) if @indents >= LIMIT
+
+          @indents += 1
+          begin
+            yield
+          ensure
+            @indents -= 1
+          end
+        end
+
+        def flat(block) = group(block.is_a?(List) ? block.items.flatten(1) : block.blocks)
+
+        # How many block quotes and lists deep the blocks go.
+        def indents_of(blocks)
+          blocks.map do |block|
+            case block
+            when Blockquote then 1 + indents_of(block.blocks)
+            when List then 1 + (block.items.map { |item| indents_of(item) }.max || 0)
+            when Table then block.rows.flatten.map { |cell| indents_of(cell.blocks) }.max || 0
+            else 0
+            end
+          end.max || 0
+        end
+      end
+    end
+  end
+end

data/lib/stationery/rich/renderer.rb

@@ -2,6 +2,7 @@
 
 require_relative "nodes"
 require_relative "styles"
+require_relative "renderer/indents"
 require_relative "renderer/inlines"
 require_relative "renderer/links"
 
@@ -9,8 +10,12 @@ module Stationery
   module Rich
     # Draws rich-text blocks with a component's element DSL. Images come from
     # `images:` (a callable given the src, returning a path, an IO or nil) or
-    # from files under `base_path:`; remote URLs are never fetched.
+    # from files under `base_path:`; remote URLs are never fetched. Block
+    # quotes and lists nested deeper than Indents::LIMIT stop indenting, which
+    # is reported as a NestingLimit warning.
     class Renderer
+      include Indents
+
       REMOTE = /\A[a-z][a-z0-9+.-]*:/i
       LINK_SCHEMES = %w[http https mailto tel].freeze
 
@@ -23,18 +28,25 @@ module Stationery
         @base_path = base_path && File.expand_path(base_path.to_s)
         @bookmarks = bookmarks
         @links = Links.new(links || LINK_SCHEMES, builder.warnings)
+        @indents = 0
       end
 
-      def render(blocks) = @component.group(gap: @gap) { blocks.each { |block| block(block) } }
+      def render(blocks)
+        depth = indents_of(blocks)
+        @builder.warnings << Warnings::NestingLimit.new(depth:, limit: Indents::LIMIT) if depth > Indents::LIMIT
+        group(blocks)
+      end
 
       private
 
+      def group(blocks) = @component.group(gap: @gap) { blocks.each { |block| block(block) } }
+
       def block(block)
         case block
         when Paragraph then paragraph(block.inlines, **@styles[:p])
         when Heading then heading(block)
-        when List then list(block)
-        when Blockquote then @component.box(role: :blockquote, **@styles[:blockquote]) { render(block.blocks) }
+        when List then indented(block) { list(block) }
+        when Blockquote then indented(block) { blockquote(block) }
         when CodeBlock then code(block)
         when Rule then @component.rule(**@styles[:hr])
         when Table then table(block)
@@ -59,11 +71,15 @@ module Stationery
         { title: heading.inlines.grep(Inline).map(&:text).join, level: heading.level }
       end
 
+      def blockquote(quote)
+        @component.box(role: :blockquote, **@styles[:blockquote]) { group(quote.blocks) }
+      end
+
       def list(list)
         options = list.ordered ? { **@styles[:ol], start: list.start || 1 } : @styles[:ul]
         @component.public_send(list.ordered ? :ol : :ul, **options) do
           list.items.each do |blocks|
-            @component.li { @component.text_style(**@styles[:li]) { render(blocks) } }
+            @component.li { @component.text_style(**@styles[:li]) { group(blocks) } }
           end
         end
       end
@@ -81,7 +97,7 @@ module Stationery
 
       def cell_content(cell)
         style = cell.header ? @styles[:table][:header] : {}
-        -> { @component.text_style(**style, align: cell.align) { render(cell.blocks) } }
+        -> { @component.text_style(**style, align: cell.align) { group(cell.blocks) } }
       end
 
       def image(node)

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,29 +3,37 @@
 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)
+        nesting = nil
+        root = Parser.parse(source) { |depth| nesting = depth }
         raise Error, "not an svg document" unless root&.name == "svg"
 
-        new(root)
+        new(root, nesting:)
       end
 
-      attr_reader :view_box, :unsupported
+      # `nesting` is how deep the source nested when that was deeper than
+      # Parser::MAX_DEPTH (and was flattened there), else nil.
+      attr_reader :view_box, :unsupported, :nesting
 
-      def initialize(root)
+      def initialize(root, nesting: nil)
         @root = root
+        @nesting = nesting
         @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 +49,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 +69,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 +87,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 +104,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/parser.rb

@@ -8,10 +8,15 @@ module Stationery
     # Comments, processing instructions and doctypes are skipped; text content
     # (CDATA included) is kept only inside text, tspan and style, as String
     # children with entities decoded and each whitespace run one space.
+    #
+    # An element nested deeper than MAX_DEPTH is not descended into: it takes
+    # its place in the deepest element kept and so does what it holds, so
+    # nothing that walks the tree recurses deeper than that.
     module Parser
       Element = Data.define(:name, :attributes, :children)
 
       TEXT = %w[text tspan style].freeze
+      MAX_DEPTH = 128
 
       IGNORED = /<!--.*?-->|<\?.*?\?>|<!DOCTYPE[^>]*>/m
       CDATA = /<!\[CDATA\[(.*?)\]\]>/m
@@ -21,17 +26,19 @@ module Stationery
 
       module_function
 
-      def parse(source)
+      # The root element. The block is given how deep the source nested when
+      # that was deeper than `max_depth`.
+      def parse(source, max_depth: MAX_DEPTH)
         source = source.to_s.gsub(IGNORED, "").gsub(CDATA) { Regexp.last_match(1).gsub(/[&<>]/, ESCAPES) }
         scanner = StringScanner.new(source)
-        root = Element.new("document", {}, [])
-        stack = [root]
+        tree = Tree.new(max_depth)
         while (content = scanner.scan_until(/(?=<)/))
-          keep(stack.last, content)
+          keep(tree.open, content)
           tag = scanner.scan(TAG) or (scanner.getch && next)
-          handle(stack, *tag.match(TAG).captures)
+          tree.tag(*tag.match(TAG).captures)
         end
-        root.children.first
+        yield tree.deepest if block_given? && tree.deepest > max_depth
+        tree.root
       end
 
       # Yields the element and every element below it, depth first.
@@ -46,12 +53,45 @@ module Stationery
         element.children << Stationery::Text::Entities.decode(content).gsub(/\s+/, " ")
       end
 
-      def handle(stack, closing, name, attributes, self_closing)
-        return stack.pop if closing == "/" && stack.size > 1
+      # The elements open while the source is read. `hoisted` counts the open
+      # ones too deep to descend into; their end tags are counted off again.
+      class Tree
+        attr_reader :deepest
 
-        element = Element.new(name, attributes.scan(ATTRIBUTE).to_h { |k, *v| [k, v.compact.first] }, [])
-        stack.last.children << element
-        stack << element if self_closing.empty?
+        def initialize(max_depth)
+          @document = Element.new("document", {}, [])
+          @stack = [@document]
+          @max_depth = max_depth
+          @hoisted = 0
+          @deepest = 0
+        end
+
+        def root = @document.children.first
+        def open = @stack.last
+
+        def tag(closing, name, attributes, self_closing)
+          return close if closing == "/"
+
+          element = Element.new(name, attributes.scan(ATTRIBUTE).to_h { |k, *v| [k, v.compact.first] }, [])
+          open.children << element
+          descend(element) if self_closing.empty?
+        end
+
+        private
+
+        def close
+          return @hoisted -= 1 if @hoisted.positive?
+
+          @stack.pop if @stack.size > 1
+        end
+
+        def descend(element)
+          depth = @stack.size + @hoisted
+          @deepest = depth if depth > @deepest
+          return @stack << element if @stack.size <= @max_depth
+
+          @hoisted += 1
+        end
       end
     end
   end

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)