stationery 0.3.0 → 0.4.0

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/svg.rb

@@ -6,8 +6,10 @@ module Stationery
     # follows the viewBox's aspect ratio), never wider than the space given.
     class Svg < Node
       # `context` gives SVG text its font book and default family.
-      def initialize(document, width: nil, height: nil, color: "#000000", context: nil)
+      # `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
@@ -28,8 +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, book: @context&.book,
-                               family: @context&.style&.family)
+        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, **)
@@ -57,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

data/lib/stationery/pdf/assembler.rb

@@ -4,7 +4,11 @@ module Stationery
   module PDF
     # Writes finished pages, their shared resources and document info as PDF.
     class Assembler
-      def initialize(pages:, resources:, info: {}, outline: [], encryption: nil)
+      # `tagging:` (a Tagging::Tree) writes the structure tree of a tagged PDF;
+      # `lang:` is the document's natural language.
+      def initialize(pages:, resources:, info: {}, outline: [], encryption: nil, tagging: nil, lang: nil)
+        @tagging = tagging
+        @lang = lang
         @pages = pages
         @resources = resources
         @info = info
@@ -14,28 +18,43 @@ module Stationery
 
       def render
         writer = Writer.new(encryption: @encryption)
+        @form = Forms::AcroForm.new(writer)
         tree = writer.reserve
         refs = @resources.build(writer)
         kids = @kids = @pages.map { writer.reserve }
+        @structure = @tagging && Tagging::Writer.new(@tagging, pages: @pages, refs: kids)
         @pages.each_with_index { |page, index| write_page(writer, page, kids[index], tree, refs) }
         writer.set(tree, { Type: :Pages, Kids: kids, Count: kids.size })
-        root = writer.add(catalog(tree, OutlineWriter.new(writer, @outline, kids).write))
+        outlines = OutlineWriter.new(writer, @outline, kids).write
+        root = writer.add(catalog(tree, outlines, @form.write).merge(accessibility(writer)))
         writer.render(root:, info: writer.add(info_dictionary))
       end
 
       private
 
-      def catalog(tree, outlines)
+      def catalog(tree, outlines, form)
         catalog = { Type: :Catalog, Pages: tree }
+        catalog[:AcroForm] = form if form
         outlines ? catalog.merge(Outlines: outlines, PageMode: :UseOutlines) : catalog
       end
 
+      def accessibility(writer)
+        entries = @lang ? { Lang: PDF::TextString.new(@lang.to_s) } : {}
+        return entries unless @structure
+
+        entries.merge!(@structure.write(writer))
+        @info[:Title] ? entries.merge(ViewerPreferences: { DisplayDocTitle: true }) : entries
+      end
+
       def write_page(writer, page, ref, tree, refs)
         dictionary = {
           Type: :Page, Parent: tree, MediaBox: [0, 0, *page.size],
           Contents: writer.add(Stream.new(page.content)), Resources: page_resources(page, refs)
         }
-        dictionary[:Annots] = page.annotations.map { |link| writer.add(annotation(link)) } if page.annotations.any?
+        if page.annotations.any?
+          dictionary[:Annots] = page.annotations.map { |annot| annotation_ref(writer, annot, ref) }
+        end
+        dictionary.merge!(@structure.page_entries(page)) if @structure
         writer.set(ref, dictionary)
       end
 
@@ -45,6 +64,19 @@ module Stationery
         end
       end
 
+      def annotation_ref(writer, annotation, page)
+        if annotation[:widget]
+          return @form.add(annotation[:widget], annotation[:rect], page) do |widget_ref|
+            @structure ? @structure.annotation(annotation, widget_ref) : {}
+          end
+        end
+
+        ref = writer.reserve
+        dictionary = annotation(annotation)
+        dictionary = dictionary.merge(@structure.annotation(annotation, ref)) if @structure
+        writer.set(ref, dictionary)
+      end
+
       def annotation(link)
         target = if (dest = link[:dest])
                    { Dest: [@kids.fetch(dest.page), :XYZ, nil, dest.top, nil] }

data/lib/stationery/rich/renderer.rb

@@ -31,7 +31,7 @@ module Stationery
         when Paragraph then paragraph(block.inlines, **@styles[:p])
         when Heading then heading(block)
         when List then list(block)
-        when Blockquote then @component.box(**@styles[:blockquote]) { render(block.blocks) }
+        when Blockquote then @component.box(role: :blockquote, **@styles[:blockquote]) { render(block.blocks) }
         when CodeBlock then code(block)
         when Rule then @component.rule(**@styles[:hr])
         when Table then table(block)
@@ -47,7 +47,7 @@ module Stationery
         style = @styles[:"h#{heading.level}"]
         size = style[:size] || (@builder.style.size * style.fetch(:scale, 1))
         bookmark = heading_bookmark(heading)
-        paragraph(heading.inlines, **style.except(:scale), size:, **({ bookmark: } if bookmark))
+        paragraph(heading.inlines, **style.except(:scale), size:, heading: heading.level, **({ bookmark: } if bookmark))
       end
 
       def heading_bookmark(heading)
@@ -86,7 +86,7 @@ module Stationery
         return unless source
 
         loaded = Images.load(source)
-        @component.image(loaded, **dimensions(node, loaded))
+        @component.image(loaded, alt: node.alt, **dimensions(node, loaded))
       rescue UnsupportedImage => e
         skip(node.src, e.message)
       end

data/lib/stationery/structure.rb

@@ -11,10 +11,13 @@ module Stationery
 
     # Returns the destinations by name; unresolved links are dropped.
     # Runs before resources are written, so slot digits join the font subset.
-    def self.resolve(pages, warnings:, resources: nil, book: nil) = new(pages, warnings, resources, book).resolve
+    def self.resolve(pages, warnings:, resources: nil, book: nil, tagging: nil)
+      new(pages, warnings, resources, book, tagging).resolve
+    end
 
-    def initialize(pages, warnings, resources, book)
+    def initialize(pages, warnings, resources, book, tagging = nil)
       @pages = pages
+      @tagging = tagging
       @warnings = warnings
       @resources = resources
       @book = book
@@ -57,19 +60,22 @@ module Stationery
       font, face = @book.resolve(slot.style)
       style = slot.style
       width = font.width_of(label, style.render_size, letter_spacing: style.letter_spacing)
-      canvas = Canvas.new(page, @resources)
-      canvas.link(*slot.link, "##{slot.anchor}") if slot.link
-      canvas.text(label, x: slot.x + slot.width - width, y: slot.baseline, font:,
-                         size: style.render_size, color: style.color,
-                         letter_spacing: style.letter_spacing, opacity: style.opacity,
-                         synthetic_bold: face.synthetic_bold, synthetic_oblique: face.synthetic_oblique)
+      canvas = Canvas.new(page, @resources, tagging: @tagging)
+      link, number = slot.tags
+      canvas.link(*slot.link, "##{slot.anchor}", tag: link) if slot.link
+      canvas.tag(number) do
+        canvas.text(label, x: slot.x + slot.width - width, y: slot.baseline, font:,
+                           size: style.render_size, color: style.color,
+                           letter_spacing: style.letter_spacing, opacity: style.opacity,
+                           synthetic_bold: face.synthetic_bold, synthetic_oblique: face.synthetic_oblique)
+      end
     end
 
     def link_to(link, index)
       return link unless link.key?(:dest)
 
       destination = @destinations[link[:dest]]
-      return { rect: link[:rect], dest: destination } if destination
+      return link.merge!(dest: destination) if destination
 
       @warnings << Warnings::UnresolvedLink.new(name: link[:dest], page: index + 1)
       nil

data/lib/stationery/tagging/element.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Stationery
+  # Tagged (accessible) PDF: a structure tree of standard structure types
+  # (ISO 32000-1 §14.8.4) whose leaves point at marked content on the pages.
+  module Tagging
+    # Grouping roles a box can take, as standard structure types.
+    ROLES = { section: :Sect, div: :Div, blockquote: :BlockQuote, note: :Note, caption: :Caption,
+              article: :Art, part: :Part }.freeze
+
+    # One marked-content sequence: the page it is on and its MCID there.
+    MarkedContent = Data.define(:page, :mcid)
+
+    # An annotation (the page's link Hash) that belongs to an element.
+    ObjectRef = Data.define(:page, :annotation)
+
+    def self.role(role)
+      ROLES.fetch(role) { raise ArgumentError, "unknown role #{role.inspect} (use #{ROLES.keys.join(", ")})" }
+    end
+
+    def self.heading(level)
+      return :P unless level
+      raise ArgumentError, "heading: takes 1 to 6, got #{level.inspect}" unless (1..6).cover?(level)
+
+      :"H#{level}"
+    end
+
+    # A structure element. Layout nodes create one per source node and share
+    # it with every fragment a split produces, so content continued on the
+    # next page stays one element. It joins the tree where it first paints.
+    class Element
+      CELLS = %i[TD TH].freeze
+
+      attr_reader :type, :alt, :kind, :kids, :parent, :attributes
+
+      # `alt` is a Figure's alternate text; `kind` names what drew it in
+      # warnings; `attributes` are { owner => { key => value } } (/A entries).
+      def initialize(type, alt: nil, kind: nil, attributes: {})
+        @type = type
+        @alt = alt
+        @kind = kind
+        @attributes = attributes.transform_values(&:dup)
+        @kids = []
+      end
+
+      def attached? = !@parent.nil?
+
+      def attach(parent)
+        return if @parent
+
+        @parent = parent
+        parent.kids << self
+      end
+
+      # A bounding box in PDF space, kept from the first fragment painted.
+      def place(bbox)
+        (@attributes[:Layout] ||= {})[:BBox] ||= bbox
+        self
+      end
+
+      def bbox = @attributes.dig(:Layout, :BBox)
+      def marked_content = @kids.grep(MarkedContent)
+      def elements = @kids.grep(Element)
+
+      # Holds no content, so the writer leaves it out; an empty table cell
+      # stays, keeping its row's columns in place.
+      def empty?
+        return false if CELLS.include?(@type)
+
+        @kids.none?(MarkedContent) && @kids.none?(ObjectRef) && elements.all?(&:empty?)
+      end
+    end
+  end
+end

data/lib/stationery/tagging/tree.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Tagging
+    # One render's structure: the Document element and, per page, the element
+    # each MCID belongs to (what the parent tree maps back from).
+    class Tree
+      attr_reader :root
+
+      def initialize
+        @root = Element.new(:Document)
+        @pages = {}.compare_by_identity
+      end
+
+      # The next MCID on `page`, recorded as marked content of `element`.
+      def mark(page, element)
+        marked = (@pages[page] ||= [])
+        marked << element
+        element.kids << MarkedContent.new(page, marked.size - 1)
+        marked.size - 1
+      end
+
+      def marked(page) = @pages.fetch(page, [])
+
+      # Records the accessibility gaps `strict` should catch.
+      def audit(pages, warnings, lang:)
+        warnings << Warnings::MissingLanguage.new unless lang
+        figures(@root).each do |figure|
+          next if figure.alt
+
+          page = pages.index(figure.marked_content.first.page) + 1
+          warnings << Warnings::MissingAlt.new(kind: figure.kind, page:)
+        end
+      end
+
+      private
+
+      def figures(element)
+        element.elements.flat_map { |kid| kid.type == :Figure ? [kid] : figures(kid) }
+      end
+    end
+  end
+end