stationery 0.2.0 → 0.4.0

data/lib/stationery/layout/box.rb

@@ -8,19 +8,26 @@ module Stationery
     # `:avoid` never). A fragment's cut sides are `open`: `decoration: :slice`
     # drops their padding and border, `:clone` keeps the padding. A
     # fixed-height box can truncate or shrink text that does not fit
-    # (`overflow:`) and never splits.
+    # (`overflow:`) and never splits. `min_height:` is a floor that does split:
+    # the first fragment keeps as much of it as the page holds and the next
+    # one carries only what is left of it.
     class Box < Node
       BORDER = { width: 1, color: "#000000", sides: %i[top right bottom left] }.freeze
 
       attr_reader :content, :width_spec
 
       def initialize(content = Flow.new, padding: 0, background: nil, border: nil, radius: 0, width: nil,
-                     height: nil, overflow: :visible, valign: :top, opacity: nil, link: nil, outset: 0,
-                     open: [], decoration: :slice)
+                     height: nil, min_height: nil, overflow: :visible, valign: :top, opacity: nil, link: nil, outset: 0,
+                     open: [], decoration: :slice, role: nil)
+        raise ArgumentError, "pass height: or min_height:, not both" if height && min_height
+
         super()
+        @tag = role && Tagging::Element.new(Tagging.role(role))
+        @min_height = min_height
         @open = open
         @decoration = decoration
         @link = link
+        @link_tag = link && Tagging::Element.new(:Link)
         @outset = Geometry.box(outset)
         @content = content
         @padding = Geometry.box(padding)
@@ -58,38 +65,54 @@ module Stationery
         available = height - vertical(cut)
         head, tail = @content.split(inner_width(width), available, fresh:)
         return [nil, self] unless head
-        return [with_content(head), nil] unless tail
+        return [with_content(head), nil] unless tail || @min_height.to_f > height + EPSILON
 
-        [with_content(head, cut).tap { |part| part.keep_with_next = nil }, with_content(tail, @open | [:top])]
+        fragments(width, height, head, tail || Flow.new, cut)
       end
 
+      # An empty continuation: open at the top, without a floor.
+      def continued = fragment(Flow.new, @open | [:top], nil)
+
       # A copy holding other content and open sides, every option kept.
       def with_content(content, open = @open) = dup.reopen(content, open)
       def with_open(*sides) = with_content(@content, @open | sides)
 
       def measure(width)
-        @height || memoize_by_width(width) { @content.measure(inner_width(width)) + vertical }
+        @height || memoize_by_width(width) { [@content.measure(inner_width(width)) + vertical, @min_height || 0].max }
       end
 
       def paint(canvas, x, y, width, height = nil, valign: nil, debug_kind: :box, **)
         height ||= measure(width)
-        paint_background(canvas, x, y, width, height)
-        paint_border(canvas, x, y, width, height)
-        paint_content(canvas, x, y, width, height, valign || @valign)
-        canvas.link(x, y, width, height, @link) if @link
+        canvas.structure(@tag) do
+          canvas.structure(@link_tag) do
+            paint_background(canvas, x, y, width, height)
+            paint_border(canvas, x, y, width, height)
+            paint_content(canvas, x, y, width, height, valign || @valign)
+          end
+        end
+        canvas.link(x, y, width, height, @link, tag: @link_tag) if @link
         paint_debug(canvas, Rect.new(x, y, width, height), debug_kind) if canvas.debug?
       end
 
       protected
 
-      def reopen(content, open)
+      def reopen(content, open, min_height = @min_height)
         @content = content
         @open = open
+        @min_height = min_height
         self
       end
 
       private
 
+      def fragment(content, open, min_height) = dup.reopen(content, open, min_height)
+
+      def fragments(width, height, head, tail, cut)
+        first = fragment(head, cut, @min_height && [@min_height, height].min).tap { |part| part.keep_with_next = nil }
+        rest = @min_height.to_f - first.measure(width)
+        [first, fragment(tail, @open | [:top], rest.positive? ? rest : nil)]
+      end
+
       def insets(open = @open)
         border = @border ? @border[:width] : 0
         sides = @border ? @border[:sides] - open : []

data/lib/stationery/layout/field.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Layout
+    # An interactive form field: a widget `height` tall that fills the width
+    # (`width: :full`) or takes `width` points. Its look comes from the
+    # widget's own appearance, so it paints nothing into the page but an
+    # optional `label` node to the right of the widget.
+    class Field < Node
+      LABEL_GAP = 6
+
+      def initialize(field, height:, width: :full, label: nil)
+        super()
+        @field = field
+        @height = height
+        @width = width
+        @label = label
+        @tag = Tagging::Element.new(:Form, kind: :field)
+      end
+
+      def measure(width)
+        @label ? [@height, @label.measure(label_width(width))].max : @height
+      end
+
+      def natural_width = @label ? label_offset + @label.natural_width : fixed_points || 0
+      def min_width = @label ? label_offset + @label.min_width : fixed_points || 0
+
+      def fixed_width(available)
+        return [natural_width, available].min if @label
+
+        fixed_points && [fixed_points, available].min
+      end
+
+      def paint(canvas, x, y, width, _height = nil, **)
+        own = @label ? @width : width
+        total = measure(width)
+        top = y + ((total - @height) / 2.0)
+        canvas.widget(@field, x, top, own, @height, tag: @tag)
+        @label&.paint(canvas, x + label_offset, y + ((total - @label.measure(label_width(width))) / 2.0),
+                      label_width(width))
+        canvas.debug_rect(x, top, own, @height, :field) if canvas.debug?
+      end
+
+      private
+
+      def fixed_points = @width.is_a?(Numeric) ? @width : nil
+      def label_offset = @width + LABEL_GAP
+      def label_width(width) = [width - label_offset, 0].max
+    end
+  end
+end

data/lib/stationery/layout/flow.rb

@@ -10,11 +10,13 @@ module Stationery
     class Flow < Node
       attr_reader :children, :gap, :align
 
-      def initialize(children = [], gap: 0, align: :left)
+      # `tag` groups the children in a tagged PDF (a list's L).
+      def initialize(children = [], gap: 0, align: :left, tag: nil)
         super()
         @children = children
         @gap = gap
         @align = align
+        @tag = tag
       end
 
       def <<(child)
@@ -35,6 +37,20 @@ module Stationery
       end
 
       def paint(canvas, x, y, width, _height = nil, **)
+        canvas.structure(@tag) { paint_children(canvas, x, y, width) }
+      end
+
+      def split(width, height, fresh: false)
+        Splitter.new(self, width, height, fresh).call
+      end
+
+      def with_children(children)
+        self.class.new(children, gap: @gap, align: @align, tag: @tag)
+      end
+
+      private
+
+      def paint_children(canvas, x, y, width)
         cursor = y
         @children.reject(&:page_break?).each_with_index do |child, index|
           cursor += @gap unless index.zero?
@@ -46,14 +62,6 @@ module Stationery
           cursor += height
         end
       end
-
-      def split(width, height, fresh: false)
-        Splitter.new(self, width, height, fresh).call
-      end
-
-      def with_children(children)
-        self.class.new(children, gap: @gap, align: @align)
-      end
     end
 
     # One pass of Flow#split, kept apart so the rules read top to bottom.

data/lib/stationery/layout/image.rb

@@ -6,8 +6,10 @@ module Stationery
     # preserved), never wider than the space it is given. One pixel is one
     # point when no size is given.
     class Image < Node
-      def initialize(source, width: nil, height: nil, fit: nil, opacity: nil)
+      # `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)
         super()
+        @tag = alt == false ? nil : Tagging::Element.new(:Figure, alt:, kind: :image)
         @image = source.respond_to?(:build) ? source : Images.load(source)
         @width = width
         @height = height
@@ -29,7 +31,7 @@ module Stationery
 
       def paint(canvas, x, y, width, _height = nil, **)
         w, h = size(width)
-        canvas.image(@image, x:, y:, width: w, height: h, opacity: @opacity)
+        canvas.tag(@tag, bbox: [x, y, w, h]) { canvas.image(@image, x:, y:, width: w, height: h, opacity: @opacity) }
         canvas.debug_rect(x, y, w, h, :image)
       end
 

data/lib/stationery/layout/list_item.rb

@@ -9,8 +9,12 @@ module Stationery
     class ListItem < Node
       attr_reader :marker, :body, :indent, :marker_gap
 
-      def initialize(marker, body, indent:, marker_gap:)
+      # `tag` and `body_tag` are the item's LI and LBody; a Text marker carries its own Lbl.
+      def initialize(marker, body, indent:, marker_gap:, tag: Tagging::Element.new(:LI),
+                     body_tag: Tagging::Element.new(:LBody))
         super()
+        @tag = tag
+        @body_tag = body_tag
         @marker = marker
         @body = body
         @indent = indent
@@ -31,11 +35,13 @@ module Stationery
       end
 
       def paint(canvas, x, y, width, _height = nil, **)
-        if @marker
-          own = @marker.width_in(column)
-          @marker.paint(canvas, x + column - own, y, own)
+        canvas.structure(@tag) do
+          if @marker
+            own = @marker.width_in(column)
+            @marker.paint(canvas, x + column - own, y, own)
+          end
+          canvas.structure(@body_tag) { @body.paint(canvas, x + @indent, y, body_width(width)) }
         end
-        @body.paint(canvas, x + @indent, y, body_width(width))
       end
 
       def split(width, height, fresh: false)
@@ -51,7 +57,10 @@ module Stationery
 
       def column = [@indent - @marker_gap, 0].max
       def body_width(width) = [width - @indent, 0].max
-      def with(marker, body) = self.class.new(marker, body, indent: @indent, marker_gap: @marker_gap)
+
+      def with(marker, body)
+        self.class.new(marker, body, indent: @indent, marker_gap: @marker_gap, tag: @tag, body_tag: @body_tag)
+      end
     end
 
     # A drawn bullet (:disc, :circle or :square) sized to the text style and

data/lib/stationery/layout/node.rb

@@ -26,6 +26,8 @@ module Stationery
     # - fixed_width(available)    → its own width, or nil when it fills the width
     class Node
       attr_accessor :keep_with_next, :break_inside
+      # The Tagging::Element this node paints into, shared by its fragments.
+      attr_reader :tag
 
       def measure(_width) = raise(NotImplementedError, "#{self.class} must implement measure")
       def paint(_canvas, _x, _y, _width, _height = nil, **) = raise(NotImplementedError, "#{self.class}#paint")

data/lib/stationery/layout/paginator.rb

@@ -7,8 +7,9 @@ module Stationery
     class Paginator
       attr_reader :warnings
 
-      def initialize(resources:, page: {}, warnings: Warnings.new, debug: false, regions: nil)
+      def initialize(resources:, page: {}, warnings: Warnings.new, debug: false, regions: nil, tagging: nil)
         @resources = resources
+        @tagging = tagging
         @debug = debug
         @page_options = page
         @regions = regions
@@ -61,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)
+        canvas = Canvas.new(page, @resources, debug: @debug, tagging: @tagging)
         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/row.rb

@@ -36,7 +36,7 @@ module Stationery
         return [nil, self] if parts.any? { |head, _| head.nil? }
 
         heads = parts.map { |head, _| head.with_open(:bottom) }
-        tails = parts.zip(@columns).map { |(_, tail), column| tail || column.with_content(Flow.new).with_open(:top) }
+        tails = parts.zip(@columns).map { |(_, tail), column| tail || column.continued }
         [with_columns(heads).tap { |row| row.keep_with_next = nil }, with_columns(tails)]
       end
 

data/lib/stationery/layout/svg.rb

@@ -5,9 +5,13 @@ module Stationery
     # A vector drawing at a fixed size: `width:` and/or `height:` (the other
     # follows the viewBox's aspect ratio), never wider than the space given.
     class Svg < Node
-      def initialize(document, width: nil, height: nil, color: "#000000")
+      # `context` gives SVG text its font book and default family.
+      # `alt:` describes the drawing in a tagged PDF; `alt: false` marks it decorative.
+      def initialize(document, width: nil, height: nil, color: "#000000", context: nil, alt: nil)
         super()
+        @tag = alt == false ? nil : Tagging::Element.new(:Figure, alt:, kind: :svg)
         @document = document
+        @context = context
         @width = width
         @height = height
         @color = color
@@ -26,7 +30,10 @@ module Stationery
 
       def paint(canvas, x, y, width, _height = nil, **)
         w, h = size(width)
-        @document.draw(canvas, x:, y:, width: w, height: h, color: @color)
+        canvas.tag(@tag, bbox: [x, y, w, h]) do
+          @document.draw(canvas, x:, y:, width: w, height: h, color: @color, book: @context&.book,
+                                 family: @context&.style&.family)
+        end
         canvas.debug_rect(x, y, w, h, :image)
       end
 

data/lib/stationery/layout/table/cell.rb

@@ -9,7 +9,7 @@ module Stationery
         TEXT_OPTIONS = { size: :size, color: :color, weight: :weight, style: :style, font: :family,
                          letter_spacing: :letter_spacing }.freeze
 
-        attr_reader :content, :options, :colspan, :rowspan
+        attr_reader :content, :options, :colspan, :rowspan, :tag, :row_tag
 
         def initialize(content, options, colspan: 1, rowspan: 1)
           @content = content
@@ -23,7 +23,15 @@ module Stationery
         end
 
         # The same cell holding another node, as a row split into two parts needs.
-        def with_content(node) = Cell.new(node, @options, colspan:, rowspan:)
+        def with_content(node) = Cell.new(node, @options, colspan:, rowspan:).tagged(@tag, @row_tag)
+
+        # Its TH or TD and its row's TR in a tagged PDF; set once, by the
+        # table the cell is first laid out in.
+        def tagged(tag, row_tag)
+          @tag ||= tag
+          @row_tag ||= row_tag
+          self
+        end
 
         # Changes an option and forgets the node built from the old ones.
         def []=(name, value)

data/lib/stationery/layout/table.rb

@@ -10,8 +10,13 @@ module Stationery
       DEFAULT_CELL = { padding: 5, borders: %i[top right bottom left], border_width: 0.5,
                        border_color: "#000000" }.freeze
 
-      def initialize(rows, context:, widths: nil, width: :auto, header: false, split_rows: false, cell: {})
+      # `tag` is the Table element its fragments share; a `continued` fragment
+      # repeats header rows already read on an earlier page.
+      def initialize(rows, context:, widths: nil, width: :auto, header: false, split_rows: false, cell: {},
+                     tag: Tagging::Element.new(:Table), continued: false)
         super()
+        @tag = tag
+        @continued = continued
         @split_rows = split_rows
         @context = context
         @widths = widths
@@ -20,6 +25,7 @@ module Stationery
         defaults = DEFAULT_CELL.merge(cell)
         @cells = rows.map { |row| row.map { |content| build_cell(content, defaults) } }
         check_header
+        tag_cells
         yield self if block_given?
       end
 
@@ -74,11 +80,12 @@ module Stationery
       def paint(canvas, x, y, width, _height = nil, **)
         widths = column_widths(width)
         heights = row_heights(width)
-        grid.placements.each do |p|
-          rect = Rect.new(x + widths[0...p.column].sum, y + heights[0...p.row].sum,
-                          widths[p.columns].sum, heights[p.rows].sum)
-          p.cell.paint(canvas, @context, rect, last_column: p.columns.end == column_count,
-                                               last_row: p.rows.end == row_count)
+        canvas.structure(@tag) do
+          grid.placements.each do |p|
+            rect = Rect.new(x + widths[0...p.column].sum, y + heights[0...p.row].sum,
+                            widths[p.columns].sum, heights[p.rows].sum)
+            paint_cell(canvas, p, rect)
+          end
         end
       end
 
@@ -97,10 +104,34 @@ module Stationery
 
       def grid = @grid ||= Grid.new(@cells)
 
+      def paint_cell(canvas, placement, rect)
+        cell = placement.cell
+        paint = lambda do
+          cell.paint(canvas, @context, rect, last_column: placement.columns.end == column_count,
+                                             last_row: placement.rows.end == row_count)
+        end
+        return canvas.artifact(type: :pagination, &paint) if @continued && placement.row < @header
+
+        canvas.structure(cell.row_tag) { canvas.structure(cell.tag, &paint) }
+      end
+
+      def tag_cells
+        @cells.each_with_index do |row, index|
+          row_tag = Tagging::Element.new(:TR)
+          row.each { |cell| cell.tagged(cell_tag(cell, index < @header), row_tag) }
+        end
+      end
+
+      def cell_tag(cell, header)
+        attributes = { Scope: (:Column if header), ColSpan: (cell.colspan if cell.colspan > 1),
+                       RowSpan: (cell.rowspan if cell.rowspan > 1) }.compact
+        Tagging::Element.new(header ? :TH : :TD, attributes: attributes.empty? ? {} : { Table: attributes })
+      end
+
       def split_before(count)
         return [nil, self] if count == @header
 
-        [with_rows(@cells.first(count)), with_rows(@cells.first(@header) + @cells.drop(count))]
+        [with_rows(@cells.first(count)), with_rows(@cells.first(@header) + @cells.drop(count), continued: true)]
       end
 
       def split_row(row, width, space, fresh:)
@@ -113,7 +144,7 @@ module Stationery
         return unless heads
 
         [with_rows(@cells.first(row) + [heads], widths:),
-         with_rows(@cells.first(@header) + [tails] + @cells.drop(row + 1), widths:)]
+         with_rows(@cells.first(@header) + [tails] + @cells.drop(row + 1), widths:, continued: true)]
       end
 
       def build_cell(content, defaults)
@@ -156,8 +187,9 @@ module Stationery
         @row_heights[width] ||= grid.row_heights(column_widths(width)) { |p, span| p.cell.measure(@context, span) }
       end
 
-      def with_rows(rows, widths: @widths)
-        self.class.new(rows, context: @context, widths:, width: @width, header: @header, split_rows: @split_rows)
+      def with_rows(rows, widths: @widths, continued: @continued)
+        self.class.new(rows, context: @context, widths:, width: @width, header: @header, split_rows: @split_rows,
+                             tag: @tag, continued:)
       end
     end
   end

data/lib/stationery/layout/table_of_contents/entry.rb

@@ -5,7 +5,8 @@ module Stationery
     class TableOfContents
       # One contents row. The title wraps within the room the number slot
       # leaves; the leader and the number sit on its last line, and the whole
-      # row links to the entry's anchor once that anchor has painted.
+      # row links to the entry's anchor once that anchor has painted. Tagged,
+      # it is a TOCI holding the title as a Link and the number as a Reference.
       class Entry < Node
         LEADERS = { dots: { dash: [0, 3], cap: :round, width: 1 }, line: { width: 0.5 } }.freeze
 
@@ -16,20 +17,27 @@ module Stationery
           @options = options
           @slot = slot
           @paragraphs = {}
+          @tag = Tagging::Element.new(:TOCI)
+          @link = Tagging::Element.new(:Link)
+          @reference = Tagging::Element.new(:Reference)
         end
 
         def measure(width) = paragraph(width).height
         def natural_width = paragraph(Float::INFINITY).lines.map(&:width).max.to_f + offset + @slot + @options.gap
 
         def paint(canvas, x, y, width, _height = nil, **)
-          text = paragraph(width)
-          text.draw(canvas, x + offset, y)
-          last = text.lines.last
-          baseline = y + text.height - last.height + last.ascent
-          slot_x = x + width - @slot
-          draw_leader(canvas, x + offset + last.width + 2, slot_x, baseline)
-          canvas.number_slot(@entry.anchor, x: slot_x, baseline:, width: @slot, style: @context.style,
-                                            link: [x + offset, y, width - offset, text.height])
+          canvas.structure(@tag) do
+            text = paragraph(width)
+            text.draw(canvas, x + offset, y, tag: @link)
+            last = text.lines.last
+            baseline = y + text.height - last.height + last.ascent
+            slot_x = x + width - @slot
+            draw_leader(canvas, x + offset + last.width + 2, slot_x, baseline)
+            canvas.structure(@reference) { nil } # its place in reading order; Structure fills it
+            canvas.number_slot(@entry.anchor, x: slot_x, baseline:, width: @slot, style: @context.style,
+                                              link: [x + offset, y, width - offset, text.height],
+                                              tags: [@link, @reference])
+          end
         end
 
         private

data/lib/stationery/layout/table_of_contents.rb

@@ -26,7 +26,7 @@ module Stationery
 
       def rows
         @rows ||= Flow.new(entries.map { |entry| Entry.new(entry, context: @context, options: @options, slot:) },
-                           gap: @options.gap)
+                           gap: @options.gap, tag: Tagging::Element.new(:TOC))
       end
 
       def entries

data/lib/stationery/layout/text.rb

@@ -6,8 +6,9 @@ module Stationery
     class Text < Node
       attr_reader :runs
 
-      def initialize(runs, context:, align: :left, leading: 0, paragraph: nil)
+      def initialize(runs, context:, align: :left, leading: 0, paragraph: nil, tag: Tagging::Element.new(:P))
         super()
+        @tag = tag
         @runs = context.book.fallback(runs)
         @context = context
         @align = align
@@ -21,7 +22,7 @@ module Stationery
       def measure(width) = paragraph(width).height
 
       def paint(canvas, x, y, width, _height = nil, **)
-        paragraph(width).draw(canvas, x, y)
+        paragraph(width).draw(canvas, x, y, tag: @tag)
       end
 
       def split(width, height, **)
@@ -42,7 +43,8 @@ module Stationery
           style = run.style
           font = @context.book.resolve(style).first
           run.text.split(/[ \t\n]+/).map do |word|
-            font.width_of(word, style.render_size, letter_spacing: style.letter_spacing, kerning: style.kerning)
+            font.width_of(word, style.render_size, letter_spacing: style.letter_spacing, kerning: style.kerning,
+                                                   ligatures: style.ligatures)
           end
         end.max || 0
       end
@@ -56,7 +58,7 @@ module Stationery
       end
 
       def from(paragraph)
-        self.class.new(@runs, context: @context, align: @align, leading: @leading, paragraph:)
+        self.class.new(@runs, context: @context, align: @align, leading: @leading, paragraph:, tag: @tag)
       end
     end
   end

data/lib/stationery/minitest.rb

@@ -17,6 +17,8 @@ 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_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)
 
       def refute_pdf_text(subject, expected, msg = nil)
         matcher = Matchers::HaveText.new(expected)

data/lib/stationery/page.rb

@@ -8,8 +8,11 @@ module Stationery
   class Page
     # Room for the page number of `anchor`, right-aligned in `width` from `x`
     # on `baseline` (top-left coordinates), drawn in `style`. `link` is an
-    # [x, y, w, h] area linked to the anchor only once it resolves.
-    Slot = Data.define(:anchor, :x, :baseline, :width, :style, :link)
+    # [x, y, w, h] area linked to the anchor only once it resolves. `tags` are
+    # its [link, number] structure elements in a tagged PDF.
+    Slot = Data.define(:anchor, :x, :baseline, :width, :style, :link, :tags) do
+      def initialize(anchor:, x:, baseline:, width:, style:, link:, tags: nil) = super
+    end
 
     SIZES = {
       a3: [841.89, 1190.55], a4: [595.28, 841.89], a5: [419.53, 595.28],

data/lib/stationery/page_templates.rb

@@ -7,8 +7,9 @@ module Stationery
   # Paints a document's headers, footers and page templates on every
   # finished page.
   class PageTemplates
-    def initialize(document, book:, resources:, debug: false, regions: nil, warnings: [])
+    def initialize(document, book:, resources:, debug: false, regions: nil, warnings: [], tagging: nil)
       @document = document
+      @tagging = tagging
       @debug = debug
       @book = book
       @resources = resources
@@ -38,7 +39,7 @@ module Stationery
         reserved = @regions.height_of(region, info.number)
         overflow(info.number, height, reserved)
         y = slot == :header ? box.y : box.bottom - height
-        paint(page, root, Rect.new(box.x, y, box.width, height))
+        paint(page, root, Rect.new(box.x, y, box.width, height), subtype: slot)
       end
     end
 
@@ -50,9 +51,11 @@ module Stationery
 
     def root(info, block) = @document.template_root(info, book: @book, &block)
 
-    def paint(page, root, rect, layer = :foreground)
+    # 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
-      root.paint(Canvas.new(page, @resources, template: true, debug: @debug), rect.x, rect.y, rect.width)
+      canvas = Canvas.new(page, @resources, template: true, debug: @debug, tagging: @tagging)
+      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
   end