stationery 0.9.0 → 0.10.0

data/lib/stationery/html/css.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require_relative "../css"
+
+module Stationery
+  module HTML
+    # The CSS the html element reads: `<style>` rules (element, class and id
+    # selectors) and inline `style` attributes, for a small set of properties
+    # that map onto the element DSL. Everything else is ignored and reported
+    # once per document through the Report. Values are never fetched or
+    # evaluated: `url()` and `@import` are dropped like any unknown value.
+    class Css
+      # What a document's CSS asked for and did not get: property names, or
+      # `property: value` for a known property with a value not read, and
+      # selectors with combinators.
+      class Report
+        attr_reader :properties, :selectors
+
+        def initialize
+          @properties = []
+          @selectors = []
+        end
+
+        def property(name)
+          @properties << name unless @properties.include?(name)
+          nil
+        end
+
+        def select(text)
+          @selectors << text unless @selectors.include?(text)
+        end
+
+        def any? = @properties.any? || @selectors.any?
+      end
+
+      # Properties read on text (inherited by everything inside the element).
+      INLINE = %w[color font-size font-weight font-style text-decoration].freeze
+      # Properties read on the block an element becomes.
+      BLOCK = %w[text-align background-color margin margin-top margin-bottom padding padding-top padding-right
+                 padding-bottom padding-left border width page-break-before page-break-after break-before
+                 break-after page-break-inside break-inside].freeze
+      FONT_SIZES = { "1" => 0.625, "2" => 0.8125, "3" => 1.0, "4" => 1.125, "5" => 1.5, "6" => 2.0,
+                     "7" => 3.0 }.freeze
+      KEYWORD_SIZES = { "xx-small" => 0.5625, "x-small" => 0.625, "small" => 0.8125, "medium" => 1.0,
+                        "large" => 1.125, "x-large" => 1.5, "xx-large" => 2.0, "smaller" => 0.8333,
+                        "larger" => 1.2 }.freeze
+      NAMED_COLORS = {
+        "black" => "#000000", "white" => "#FFFFFF", "red" => "#FF0000", "green" => "#008000",
+        "blue" => "#0000FF", "yellow" => "#FFFF00", "cyan" => "#00FFFF", "aqua" => "#00FFFF",
+        "magenta" => "#FF00FF", "fuchsia" => "#FF00FF", "gray" => "#808080", "grey" => "#808080",
+        "silver" => "#C0C0C0", "maroon" => "#800000", "olive" => "#808000", "lime" => "#00FF00",
+        "teal" => "#008080", "navy" => "#000080", "purple" => "#800080", "orange" => "#FFA500",
+        "pink" => "#FFC0CB", "brown" => "#A52A2A", "gold" => "#FFD700", "darkgray" => "#A9A9A9",
+        "darkgrey" => "#A9A9A9", "lightgray" => "#D3D3D3", "lightgrey" => "#D3D3D3", "darkred" => "#8B0000",
+        "darkgreen" => "#006400", "darkblue" => "#00008B", "crimson" => "#DC143C", "coral" => "#FF7F50",
+        "salmon" => "#FA8072", "tomato" => "#FF6347", "indigo" => "#4B0082", "violet" => "#EE82EE",
+        "turquoise" => "#40E0D0", "beige" => "#F5F5DC", "ivory" => "#FFFFF0", "khaki" => "#F0E68C",
+        "tan" => "#D2B48C"
+      }.freeze
+      HEX = /\A#(\h{3}|\h{6})\z/
+      RGB = /\Argba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*[\d.]+\s*)?\)\z/i
+      LENGTH = /\A(-?\d*\.?\d+)(px|pt|em|rem|%)?\z/
+      ALIGN = %w[left center right justify].freeze
+      BREAK_PAGE = %w[always page left right].freeze
+      CSS_PX = 0.75
+      LEGACY = %w[font center].freeze
+      NOTHING = [{}.freeze, {}.freeze].freeze
+
+      def self.parse(sheets, report = Report.new) = new(CSS::Stylesheet.parse(sheets.join("\n")), report)
+
+      attr_reader :report
+
+      def initialize(sheet, report)
+        @sheet = sheet
+        @report = report
+        sheet.unsupported.each { |selector| report.select(selector) }
+      end
+
+      # The declarations that apply to `element`: legacy attributes, then the
+      # stylesheet by specificity, then its inline style.
+      def declarations(element)
+        legacy(element).merge(@sheet.declarations(element), CSS.declarations(element.attributes["style"]))
+      end
+
+      # [marks, block]: the text marks the element's content inherits and the
+      # options its block takes.
+      def resolve(element)
+        return NOTHING if plain?(element)
+
+        marks = {}
+        block = {}
+        declarations(element).each do |name, value|
+          value = value.strip
+          next if value.empty?
+
+          if INLINE.include?(name) then inline(name, value, marks)
+          elsif BLOCK.include?(name) then block(name, value, block)
+          else report.property(name)
+          end
+        end
+        [marks, block]
+      end
+
+      private
+
+      # Nothing to read: no rules, no inline style, no legacy attributes.
+      def plain?(element)
+        @sheet.empty? && !element.attributes.key?("style") && !LEGACY.include?(element.name)
+      end
+
+      def legacy(element)
+        case element.name
+        when "font" then font_attributes(element.attributes)
+        when "center" then { "text-align" => "center" }
+        else {}
+        end
+      end
+
+      def font_attributes(attributes)
+        legacy = {}
+        legacy["color"] = attributes["color"] if attributes["color"]
+        legacy["font-size"] = "#{FONT_SIZES.fetch(attributes["size"].to_s.strip, 1.0)}em" if attributes["size"]
+        legacy
+      end
+
+      def inline(name, value, marks)
+        case name
+        when "color" then read(name, value, marks, :color) { color(value) }
+        when "font-size" then font_size(value, marks)
+        when "font-weight" then read(name, value, marks, :bold) { weight(value) }
+        when "font-style" then read(name, value, marks, :italic) { style(value) }
+        when "text-decoration" then decoration(value, marks)
+        end
+      end
+
+      def block(name, value, block)
+        case name
+        when "text-align" then read(name, value, block, :align) { align(value) }
+        when "background-color" then read(name, value, block, :background) { color(value) }
+        when "margin" then read(name, value, block, :margin) { box(value) }
+        when "padding" then read(name, value, block, :padding) { box(value) }
+        when /\A(margin|padding)-/ then read(name, value, block, name.tr("-", "_").to_sym) { points(value) }
+        when "border" then read(name, value, block, :border) { border(value) }
+        when "width" then read(name, value, block, :width) { width(value) }
+        when "page-break-before", "break-before" then read(name, value, block, :break_before) { page_break(value) }
+        when "page-break-after", "break-after" then read(name, value, block, :break_after) { page_break(value) }
+        when "page-break-inside", "break-inside" then read(name, value, block, :keep_together) { avoid(value) }
+        end
+      end
+
+      # Stores what the block yields for `key`, or reports `name: value` when
+      # the value is not one the property reads. `:none` is read and means
+      # "nothing" (a transparent background, no page break): it takes back
+      # what a less specific rule set.
+      def read(name, value, into, key)
+        result = yield
+        return report.property("#{name}: #{value}") if result.nil?
+
+        result == :none ? into.delete(key) : into[key] = result
+      end
+
+      def color(value)
+        return :none if value.casecmp?("transparent")
+        return NAMED_COLORS[value.downcase] if NAMED_COLORS.key?(value.downcase)
+        return value.upcase if value.match?(HEX)
+
+        red, green, blue = value.match(RGB)&.captures&.map { |part| part.to_i.clamp(0, 255) }
+        format("#%<red>02X%<green>02X%<blue>02X", red:, green:, blue:) if red
+      end
+
+      def align(value) = ALIGN.include?(value.downcase) ? value.downcase.to_sym : nil
+
+      def font_size(value, marks)
+        scale = KEYWORD_SIZES[value.downcase]
+        match = value.match(LENGTH)
+        return report.property("font-size: #{value}") unless scale || match
+
+        marks.delete(:size)
+        marks.delete(:scale)
+        number = match && match[1].to_f
+        case match && match[2]
+        when nil then scale ? marks[:scale] = scale : marks[:size] = number * CSS_PX
+        when "em", "rem" then marks[:scale] = number
+        when "%" then marks[:scale] = number / 100
+        when "pt" then marks[:size] = number
+        when "px" then marks[:size] = number * CSS_PX
+        end
+      end
+
+      def weight(value)
+        case value.downcase
+        when "bold", "bolder" then true
+        when "normal", "lighter" then false
+        when /\A\d{3}\z/ then value.to_i >= 600
+        end
+      end
+
+      def style(value)
+        case value.downcase
+        when "italic", "oblique" then true
+        when "normal" then false
+        end
+      end
+
+      def decoration(value, marks)
+        words = value.downcase.split
+        unless words.all? { |word| %w[none underline line-through].include?(word) }
+          return report.property("text-decoration: #{value}")
+        end
+
+        marks[:underline] = words.include?("underline")
+        marks[:strike] = words.include?("line-through")
+      end
+
+      # A length in points: px (at 0.75 pt), pt, or a bare 0.
+      def points(value)
+        match = value.match(LENGTH)
+        return nil unless match
+        return 0.0 if match[1].to_f.zero?
+
+        case match[2]
+        when "pt" then match[1].to_f
+        when "px", nil then match[1].to_f * CSS_PX
+        end
+      end
+
+      # One to four lengths as [top, right, bottom, left].
+      def box(value)
+        sides = value.split.map { |part| points(part) }
+        return nil if sides.empty? || sides.size > 4 || sides.any?(&:nil?)
+
+        top, right, bottom, left = sides
+        [top, right || top, bottom || top, left || right || top]
+      end
+
+      # `1px solid #ccc` in any order; `none` and `0` mean no border.
+      def border(value)
+        parts = value.split
+        return { width: 0 } if [["none"], ["0"]].include?(parts)
+
+        width = parts.filter_map { |part| points(part) }.first
+        colour = parts.filter_map { |part| color(part) }.grep(String).first
+        return nil if width.nil? && colour.nil?
+
+        { width: width || 0.75, color: colour || "#000000" }
+      end
+
+      # Points, or a fraction of the available width for a percentage.
+      def width(value)
+        return :none if value.casecmp?("auto")
+
+        match = value.match(LENGTH)
+        number = match && match[1].to_f
+        return nil unless number&.positive?
+
+        case match[2]
+        when "%" then [number / 100.0, 1.0].min
+        when "pt" then number
+        when "px", nil then number * CSS_PX
+        end
+      end
+
+      def page_break(value)
+        return true if BREAK_PAGE.include?(value.downcase)
+
+        :none if %w[auto avoid].include?(value.downcase)
+      end
+
+      def avoid(value)
+        return true if %w[avoid avoid-page].include?(value.downcase)
+
+        :none if value.casecmp?("auto")
+      end
+    end
+  end
+end

data/lib/stationery/html/document.rb

@@ -8,11 +8,13 @@ module Stationery
   # Lenient HTML to rich-text blocks (see Stationery::Rich).
   module HTML
     # Elements nested deeper than `max_depth` are flattened into the deepest
-    # one kept; the block is then given how deep the source went.
-    def self.parse(source, max_depth: Rich::Nesting::DEFAULT)
+    # one kept; the block is then given how deep the source went. `css:` is a
+    # Css::Report that collects the styles the source asked for and did not
+    # get (see HTML::Css).
+    def self.parse(source, max_depth: Rich::Nesting::DEFAULT, css: nil)
       nesting = Rich::Nesting.new(max_depth)
       Stationery.instrument("parse.stationery", format: :html, bytes: source.bytesize) do
-        TreeBuilder.parse(Tokenizer.tokenize(source), nesting).tap do
+        TreeBuilder.parse(Tokenizer.tokenize(source), nesting, css:).tap do
           yield nesting.deepest if nesting.exceeded? && block_given?
         end
       end

data/lib/stationery/html/tokenizer.rb

@@ -5,12 +5,14 @@ require_relative "../text/entities"
 
 module Stationery
   module HTML
-    # Splits HTML into [:start, name, attributes, self_closing], [:end, name] and [:text, string] tokens.
-    # Names are lowercased, text and attribute values entity-decoded. Comments, declarations and the
-    # content of script, style, template and title elements are skipped; void elements never end.
+    # Splits HTML into [:start, name, attributes, self_closing], [:end, name], [:text, string] and
+    # [:style, css] tokens. Names are lowercased, text and attribute values entity-decoded. Comments,
+    # declarations and the content of script, template and title elements are skipped; a style
+    # element's text is kept raw for the stylesheet; void elements never end.
     class Tokenizer
       VOID = %w[area base br col embed hr img input keygen link meta param source track wbr].freeze
-      SKIPPED = %w[script style template title].freeze
+      SKIPPED = %w[script template title].freeze
+      RAW_END = %r{</style\s*>}i
       COMMENT = /<!--.*?(?:-->|\z)/m
       CDATA = /<!\[CDATA\[(.*?)(?:\]\]>|\z)/m
       DECLARATION = /<[!?][^>]*>?/
@@ -58,10 +60,19 @@ module Stationery
         end
         ending = @scanner.scan(TAG_END) || @scanner.scan_until(/>/) || (@scanner.terminate && "")
         return skip_raw(name) if SKIPPED.include?(name)
+        return style if name == "style"
 
         @tokens << [:start, name, attributes, ending.include?("/") || VOID.include?(name)]
       end
 
+      def style
+        start = @scanner.pos
+        finish = @scanner.skip_until(RAW_END)
+        css = finish ? @scanner.string.byteslice(start, finish - @scanner.matched_size) : @scanner.rest
+        @scanner.terminate unless finish
+        @tokens << [:style, css.force_encoding(@scanner.string.encoding)]
+      end
+
       def finish(name)
         @tokens << [:end, name] unless VOID.include?(name)
       end

data/lib/stationery/html/tree_builder/blocks.rb

@@ -7,7 +7,9 @@ module Stationery
   module HTML
     class TreeBuilder
       # Converts an element tree into rich-text blocks. Containers flatten into their children, inline
-      # elements add marks, and unknown elements keep their content.
+      # elements add marks, and unknown elements keep their content. Each element's CSS (see Css) adds
+      # marks to the text inside it and a style to the block it becomes; `text-align` is handed down
+      # to the blocks inside, the way CSS inherits it.
       class Blocks
         CONTAINERS = %w[
           #root html body div p section article header footer main figure figcaption aside nav address
@@ -23,59 +25,91 @@ module Stationery
           "sub" => { script: :sub }, "sup" => { script: :sup }
         }.freeze
         ALIGN = /\A\s*(left|center|right|justify)\s*\z/i
-        TEXT_ALIGN = /text-align\s*:\s*(left|center|right|justify)/i
+        # What makes a container a block of its own instead of flattening into its parent.
+        BOXED = %i[background padding padding_top padding_right padding_bottom padding_left margin margin_top
+                   margin_bottom break_before break_after keep_together].freeze
+        INHERITED = %i[align].freeze
+        EMPTY = {}.freeze
 
-        def self.convert(root) = new.blocks_of(root, {})
+        def self.convert(root, css = Css.parse([])) = new(css).blocks_of(root, EMPTY, EMPTY)
 
-        def blocks_of(element, marks)
+        def initialize(css = Css.parse([]))
+          @css = css
+        end
+
+        def blocks_of(element, marks, inherited, style = EMPTY)
           collector = Collector.new
-          children(element, marks, collector)
+          collector.boundary(style) { children(element, marks, inherited, collector) }
           collector.blocks
         end
 
         private
 
-        def children(element, marks, out)
-          element.children.each { |child| visit(child, marks, out) }
+        def children(element, marks, inherited, out)
+          element.children.each { |child| visit(child, marks, inherited, out) }
         end
 
-        def visit(node, marks, out)
+        def visit(node, marks, inherited, out)
           return out.text(node, marks) if node.is_a?(String)
 
+          own, block = @css.resolve(node)
+          marks = inherit(marks, own)
+          style = inherited.merge(block)
+          inherited = style.slice(*INHERITED)
           case node.name
-          when *CONTAINERS then out.boundary { children(node, marks, out) }
-          when *HEADINGS then out.block(heading(node, marks))
-          when "ul", "ol" then out.block(list(node, marks))
-          when "blockquote" then out.block(Rich::Blockquote.new(blocks: blocks_of(node, marks)))
-          when "pre" then out.block(code(node))
+          when *CONTAINERS then container(node, marks, inherited, style, out)
+          when *HEADINGS then out.block(heading(node, marks, style))
+          when "ul", "ol" then out.block(list(node, marks, inherited, style.except(*INHERITED)))
+          when "blockquote" then out.block(quote(node, marks, inherited, style.except(*INHERITED)))
+          when "pre" then out.block(code(node, style.except(*INHERITED)))
           when "hr" then out.block(Rich::Rule.new)
           when "br" then out.inline(Rich::Inline.break)
-          when "img" then out.inline(image(node.attributes))
-          when "table" then out.block(table(node, marks))
-          else children(node, marks.merge(marks_for(node)), out)
+          when "wbr" then out.inline(Rich::Inline.new(text: Text::Breaks::ZERO_WIDTH_SPACE, marks:))
+          when "img" then out.inline(image(node.attributes, style))
+          when "table" then out.block(table(node, marks, inherited, style.except(*INHERITED)))
+          else children(node, marks.merge(marks_for(node)), inherited, out)
           end
         end
 
-        def heading(element, marks)
-          inlines = blocks_of(element, marks).grep(Rich::Paragraph).flat_map(&:inlines)
-          Rich::Heading.new(level: element.name[1].to_i, inlines:) unless inlines.empty?
+        # A `p` hands its whole style to its paragraphs. Any other container with a box of its own
+        # (a background, padding, margins, a page-break rule) becomes a Container; without one it
+        # flattens into its parent, as it always did.
+        def container(node, marks, inherited, style, out)
+          return out.boundary(style) { children(node, marks, inherited, out) } if node.name == "p"
+
+          boxed = style.slice(*BOXED)
+          return out.boundary(inherited) { children(node, marks, inherited, out) } if boxed.empty?
+
+          out.block(Rich::Container.new(blocks: blocks_of(node, marks, inherited, inherited), style: boxed))
         end
 
-        def list(element, marks)
+        def heading(element, marks, style)
+          inlines = blocks_of(element, marks, EMPTY).grep(Rich::Paragraph).flat_map(&:inlines)
+          Rich::Heading.new(level: element.name[1].to_i, inlines:, style:) unless inlines.empty?
+        end
+
+        def list(element, marks, inherited, style)
           items = elements(element).map do |item|
-            blocks_of(item.name == "li" ? item : Element.new("li", {}, [item]), marks)
+            item = Element.new("li", {}, [item]) unless item.name == "li"
+            own, block = @css.resolve(item)
+            within = inherited.merge(block.slice(*INHERITED))
+            blocks_of(item, inherit(marks, own), within, within)
           end
           return if items.empty?
 
           ordered = element.name == "ol"
           start = Integer(element.attributes["start"], exception: false) || 1 if ordered
-          Rich::List.new(ordered:, start:, items:)
+          Rich::List.new(ordered:, start:, items:, style:)
+        end
+
+        def quote(element, marks, inherited, style)
+          Rich::Blockquote.new(blocks: blocks_of(element, marks, inherited, inherited), style:)
         end
 
-        def code(element)
+        def code(element, style)
           language = elements(element).find { |child| child.name == "code" }&.attributes&.[]("class")
           Rich::CodeBlock.new(text: raw_text(element).delete_prefix("\n").chomp,
-                              language: language&.[](/lang(?:uage)?-(\S+)/, 1))
+                              language: language&.[](/lang(?:uage)?-(\S+)/, 1), style:)
         end
 
         def raw_text(element)
@@ -86,21 +120,22 @@ module Stationery
           end
         end
 
-        def image(attributes)
+        def image(attributes, style)
           return unless attributes["src"]
 
           Rich::Image.new(src: attributes["src"], alt: attributes["alt"],
-                          width: dimension(attributes["width"]), height: dimension(attributes["height"]))
+                          width: dimension(attributes["width"]), height: dimension(attributes["height"]),
+                          style: style.slice(:width, :align))
         end
 
         def dimension(value) = value&.[](/\A\s*(\d+)/, 1)&.to_i
 
-        def table(element, marks)
+        def table(element, marks, inherited, style)
           rows = rows_of(element).filter_map do |row|
             cells = elements(row).select { |cell| %w[td th].include?(cell.name) }
-            cells.map { |cell| cell(cell, marks) } unless cells.empty?
+            cells.map { |cell| cell(cell, marks, inherited) } unless cells.empty?
           end
-          Rich::Table.new(rows:) unless rows.empty?
+          Rich::Table.new(rows:, style:) unless rows.empty?
         end
 
         def rows_of(element)
@@ -111,23 +146,38 @@ module Stationery
           end
         end
 
-        def cell(element, marks)
-          attributes = element.attributes
-          align = attributes["align"]&.[](ALIGN, 1) || attributes["style"]&.[](TEXT_ALIGN, 1)
-          Rich::Cell.new(header: element.name == "th", align: align&.downcase&.to_sym,
-                         blocks: blocks_of(element, marks))
+        def cell(element, marks, inherited)
+          own, block = @css.resolve(element)
+          marks = inherit(marks, own)
+          align = block[:align] || aligned(element.attributes["align"]) || inherited[:align]
+          Rich::Cell.new(header: element.name == "th", align:, blocks: blocks_of(element, marks, EMPTY),
+                         style: block.except(:align))
+        end
+
+        # The marks an element's text has: its ancestors' with its own over them. A relative size
+        # (em, %) is relative to the size around it, so it multiplies what is inherited.
+        def inherit(marks, own)
+          return marks if own.empty?
+          return marks.merge(own) unless own[:scale]
+
+          merged = marks.merge(own.except(:scale))
+          if marks[:size] then merged[:size] = marks[:size] * own[:scale]
+          else merged[:scale] = marks.fetch(:scale, 1) * own[:scale]
+          end
+          merged
+        end
+
+        # The align attribute of a cell, as a symbol.
+        def aligned(value)
+          name = value && value[ALIGN, 1]
+          name&.downcase&.to_sym
         end
 
         def marks_for(element)
           return MARKS[element.name] if MARKS.key?(element.name)
           return { link: element.attributes["href"] } if element.name == "a" && element.attributes["href"]
-          return {} unless element.name == "span"
 
-          style = element.attributes["style"].to_s
-          marks = {}
-          marks[:bold] = true if style.match?(/font-weight\s*:\s*(bold|[6-9]00)/i)
-          marks[:italic] = true if style.match?(/font-style\s*:\s*italic/i)
-          marks
+          EMPTY
         end
 
         def elements(element) = element.children.grep(TreeBuilder::Element)

data/lib/stationery/html/tree_builder/collector.rb

@@ -7,11 +7,13 @@ module Stationery
   module HTML
     class TreeBuilder
       # Gathers the blocks of one container: loose inline content between blocks becomes a paragraph,
-      # with its whitespace collapsed the way a browser would.
+      # with its whitespace collapsed the way a browser would. The paragraphs of a boundary take the
+      # style it was opened with (a `p` with a text-align, a margin, a background).
       class Collector
         def initialize
           @blocks = []
           @pending = []
+          @style = {}
         end
 
         def text(string, marks) = @pending << Rich::Inline.new(text: string, marks:)
@@ -27,10 +29,14 @@ module Stationery
           @blocks << block
         end
 
-        def boundary
+        def boundary(style = {})
           flush
+          outer = @style
+          @style = style
           yield
           flush
+        ensure
+          @style = outer
         end
 
         def blocks
@@ -41,7 +47,7 @@ module Stationery
         private
 
         def flush
-          @blocks.concat(Rich::Inlines.paragraphs(@pending) { |run| Whitespace.collapse(run) })
+          @blocks.concat(Rich::Inlines.paragraphs(@pending, style: @style) { |run| Whitespace.collapse(run) })
           @pending = []
         end
       end

data/lib/stationery/html/tree_builder.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require_relative "css"
 require_relative "tree_builder/blocks"
 
 module Stationery
@@ -27,13 +28,21 @@ module Stationery
         "thead" => [SECTIONS, %w[table]], "tbody" => [SECTIONS, %w[table]], "tfoot" => [SECTIONS, %w[table]]
       }.freeze
 
-      def self.parse(tokens, nesting = Rich::Nesting.new) = Blocks.convert(new(nesting).build(tokens))
+      # `css` is the Css::Report unsupported styles are told to.
+      def self.parse(tokens, nesting = Rich::Nesting.new, css: nil)
+        builder = new(nesting)
+        root = builder.build(tokens)
+        Blocks.convert(root, Css.parse(builder.sheets, css || Css::Report.new))
+      end
+
+      attr_reader :sheets
 
       def initialize(nesting = Rich::Nesting.new)
         @root = Element.new("#root", {}, [])
         @stack = [@root]
         @nesting = nesting
         @flattened = [] # the names of the open elements left out of the tree
+        @sheets = []
       end
 
       def build(tokens)
@@ -41,6 +50,7 @@ module Stationery
           case type
           when :start then start(*args)
           when :end then finish(*args)
+          when :style then @sheets << args.first
           else @stack.last.children << args.first
           end
         end

data/lib/stationery/layout/flow.rb

@@ -21,10 +21,23 @@ module Stationery
 
       def <<(child)
         @children << child
+        @breaks = nil
         forget_measures
         self
       end
 
+      # A flow holding a page break (at any depth) is cut there even when it
+      # would fit on the page it is on.
+      def breaks?
+        @breaks = @children.any? { |child| child.page_break? || child.breaks? } if @breaks.nil?
+        @breaks
+      end
+
+      def leading_break?
+        first = @children.first
+        !first.nil? && (first.page_break? || first.leading_break?)
+      end
+
       def splittable? = true
       def natural_width = @children.map(&:natural_width).max || 0
       def min_width = @children.map(&:min_width).max || 0
@@ -93,6 +106,8 @@ module Stationery
 
           gap = @placed.empty? ? 0 : @flow.gap
           remaining = @height - @used - gap
+          return broken(child, gap, remaining, rest) if child.breaks?
+
           height = child.measure(child.width_in(@width))
           return fits(child, height + gap, remaining - height, rest) if height <= remaining + EPSILON
           return [part(@placed), part(rest)] if child.is_a?(Spacer)
@@ -106,6 +121,20 @@ module Stationery
           [part(@placed), part(rest)]
         end
 
+        # A child holding a page break: what comes before the break stays on
+        # this page, the rest goes to the next, however much room is left. One
+        # that starts with the break goes to the next page whole.
+        def broken(child, gap, remaining, rest)
+          return [part(@placed), part([child, *rest])] if child.leading_break? && !@placed.empty?
+
+          head, tail = child.split(child.width_in(@width), remaining, fresh: @fresh && @placed.empty?)
+          return split_or_move(child, remaining, rest) unless head
+          return [part(@placed + [head]), part([tail, *rest])] if tail
+
+          height = head.measure(head.width_in(@width))
+          fits(head, height + gap, remaining - height, rest)
+        end
+
         def fits(child, consumed, left_after, rest)
           return [part(@placed), part([child, *rest])] if strand?(child, left_after, rest)