stationery 0.1.0 → 0.3.0

data/lib/stationery/html/tokenizer.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "strscan"
+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.
+    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
+      COMMENT = /<!--.*?(?:-->|\z)/m
+      CDATA = /<!\[CDATA\[(.*?)(?:\]\]>|\z)/m
+      DECLARATION = /<[!?][^>]*>?/
+      START = /<([a-zA-Z][a-zA-Z0-9:-]*)/
+      FINISH = %r{</([a-zA-Z][a-zA-Z0-9:-]*)[^>]*>?}
+      ATTRIBUTE = %r{[\s/]*([^\s"'>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?}
+      TAG_END = %r{\s*/?\s*>}
+
+      def self.tokenize(source) = new(source).tokens
+
+      def initialize(source)
+        @scanner = StringScanner.new(source.to_s)
+        @tokens = []
+      end
+
+      def tokens
+        step until @scanner.eos?
+        @tokens
+      end
+
+      private
+
+      def step
+        if (text = @scanner.scan(/[^<]+/)) then text(Text::Entities.decode(text))
+        elsif @scanner.scan(CDATA) then text(@scanner[1])
+        elsif @scanner.skip(COMMENT) || @scanner.skip(DECLARATION) then nil
+        elsif @scanner.scan(FINISH) then finish(@scanner[1].downcase)
+        elsif @scanner.scan(START) then start(@scanner[1].downcase)
+        else text(@scanner.getch)
+        end
+      end
+
+      def text(string)
+        if @tokens.last&.first == :text
+          @tokens.last[1] += string
+        else
+          @tokens << [:text, string]
+        end
+      end
+
+      def start(name)
+        attributes = {}
+        while @scanner.scan(ATTRIBUTE)
+          attributes[@scanner[1].downcase] ||= Text::Entities.decode(@scanner[2] || @scanner[3] || @scanner[4] || "")
+        end
+        ending = @scanner.scan(TAG_END) || @scanner.scan_until(/>/) || (@scanner.terminate && "")
+        return skip_raw(name) if SKIPPED.include?(name)
+
+        @tokens << [:start, name, attributes, ending.include?("/") || VOID.include?(name)]
+      end
+
+      def finish(name)
+        @tokens << [:end, name] unless VOID.include?(name)
+      end
+
+      def skip_raw(name)
+        @scanner.skip_until(%r{</#{name}\s*>}i) || @scanner.terminate
+      end
+    end
+  end
+end

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

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative "../../rich/nodes"
+require_relative "collector"
+
+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.
+      class Blocks
+        CONTAINERS = %w[
+          #root html body div p section article header footer main figure figcaption aside nav address
+          dl dt dd center details summary form fieldset
+        ].freeze
+        HEADINGS = %w[h1 h2 h3 h4 h5 h6].freeze
+        MARKS = {
+          "strong" => { bold: true }, "b" => { bold: true },
+          "em" => { italic: true }, "i" => { italic: true },
+          "u" => { underline: true }, "ins" => { underline: true },
+          "s" => { strike: true }, "del" => { strike: true }, "strike" => { strike: true },
+          "code" => { code: true }, "kbd" => { code: true }, "samp" => { code: true }, "tt" => { code: true },
+          "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
+
+        def self.convert(root) = new.blocks_of(root, {})
+
+        def blocks_of(element, marks)
+          collector = Collector.new
+          children(element, marks, collector)
+          collector.blocks
+        end
+
+        private
+
+        def children(element, marks, out)
+          element.children.each { |child| visit(child, marks, out) }
+        end
+
+        def visit(node, marks, out)
+          return out.text(node, marks) if node.is_a?(String)
+
+          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 "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)
+          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?
+        end
+
+        def list(element, marks)
+          items = elements(element).map do |item|
+            blocks_of(item.name == "li" ? item : Element.new("li", {}, [item]), marks)
+          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:)
+        end
+
+        def code(element)
+          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))
+        end
+
+        def raw_text(element)
+          element.children.sum("") do |child|
+            next child if child.is_a?(String)
+
+            child.name == "br" ? "\n" : raw_text(child)
+          end
+        end
+
+        def image(attributes)
+          return unless attributes["src"]
+
+          Rich::Image.new(src: attributes["src"], alt: attributes["alt"],
+                          width: dimension(attributes["width"]), height: dimension(attributes["height"]))
+        end
+
+        def dimension(value) = value&.[](/\A\s*(\d+)/, 1)&.to_i
+
+        def table(element, marks)
+          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?
+          end
+          Rich::Table.new(rows:) unless rows.empty?
+        end
+
+        def rows_of(element)
+          elements(element).flat_map do |child|
+            next [child] if child.name == "tr"
+
+            TreeBuilder::SECTIONS.include?(child.name) ? rows_of(child) : []
+          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))
+        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
+        end
+
+        def elements(element) = element.children.grep(TreeBuilder::Element)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require_relative "../../rich/nodes"
+require_relative "../whitespace"
+
+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.
+      class Collector
+        def initialize
+          @blocks = []
+          @pending = []
+        end
+
+        def text(string, marks) = @pending << Rich::Inline.new(text: string, marks:)
+
+        def inline(item)
+          @pending << item if item
+        end
+
+        def block(block)
+          return unless block
+
+          flush
+          @blocks << block
+        end
+
+        def boundary
+          flush
+          yield
+          flush
+        end
+
+        def blocks
+          flush
+          @blocks
+        end
+
+        private
+
+        def flush
+          @blocks.concat(Rich::Inlines.paragraphs(@pending) { |run| Whitespace.collapse(run) })
+          @pending = []
+        end
+      end
+    end
+  end
+end

data/lib/stationery/html/tree_builder.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require_relative "tree_builder/blocks"
+
+module Stationery
+  module HTML
+    # Builds a lenient element tree from tokens, closing what HTML5 closes implicitly (a p before a block,
+    # an li before the next li, cells and rows before the next), ignoring stray end tags, then converts
+    # the tree into rich-text blocks.
+    class TreeBuilder
+      Element = Data.define(:name, :attributes, :children)
+
+      CLOSES_P = %w[
+        address article aside blockquote dd details div dl dt fieldset figcaption figure footer form
+        h1 h2 h3 h4 h5 h6 header hr li main nav ol p pre section table ul
+      ].freeze
+      HEADINGS = %w[h1 h2 h3 h4 h5 h6].freeze
+      SECTIONS = %w[thead tbody tfoot].freeze
+      IMPLIED = {
+        "li" => [%w[li], %w[ul ol]],
+        "dt" => [%w[dt dd], %w[dl]], "dd" => [%w[dt dd], %w[dl]],
+        "td" => [%w[td th], %w[tr table]], "th" => [%w[td th], %w[tr table]],
+        "tr" => [%w[tr], %w[table]],
+        "thead" => [SECTIONS, %w[table]], "tbody" => [SECTIONS, %w[table]], "tfoot" => [SECTIONS, %w[table]]
+      }.freeze
+
+      def self.parse(tokens) = Blocks.convert(new.build(tokens))
+
+      def initialize
+        @root = Element.new("#root", {}, [])
+        @stack = [@root]
+      end
+
+      def build(tokens)
+        tokens.each do |type, *args|
+          case type
+          when :start then start(*args)
+          when :end then finish(*args)
+          else @stack.last.children << args.first
+          end
+        end
+        @root
+      end
+
+      private
+
+      def start(name, attributes, self_closing)
+        close_nearest(%w[p], %w[table td th caption]) if CLOSES_P.include?(name)
+        close_nearest(HEADINGS, []) if HEADINGS.include?(name) && HEADINGS.include?(@stack.last.name)
+        close_nearest(*IMPLIED[name]) if IMPLIED.key?(name)
+        push("tr", {}, false) if %w[td th].include?(name) && %w[table thead tbody tfoot].include?(@stack.last.name)
+        push(name, attributes, self_closing)
+      end
+
+      def push(name, attributes, self_closing)
+        element = Element.new(name, attributes, [])
+        @stack.last.children << element
+        @stack << element unless self_closing
+      end
+
+      def finish(name)
+        index = @stack.rindex { |element| element.name == name }
+        @stack.slice!(index..) if index&.positive?
+      end
+
+      def close_nearest(names, boundary)
+        index = @stack.rindex { |element| names.include?(element.name) || boundary.include?(element.name) }
+        @stack.slice!(index..) if index&.positive? && names.include?(@stack[index].name)
+      end
+    end
+  end
+end

data/lib/stationery/html/whitespace.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Stationery
+  module HTML
+    # Collapses the whitespace of one block's inlines as CSS `white-space: normal` does: runs become one
+    # space, the block's (and each line's) leading and trailing space goes, and U+00A0 is left alone.
+    # A trailing line break after content draws no empty line, so it is dropped too.
+    module Whitespace
+      RUN = /[ \t\n\r\f]+/
+
+      module_function
+
+      def collapse(inlines)
+        collapsed = trim_trailing(trim_leading(inlines))
+        collapsed.pop if collapsed.last&.break? && collapsed[..-2].any? { |i| i.break? || !i.text.empty? }
+        collapsed
+      end
+
+      def trim_leading(inlines)
+        space = true
+        inlines.map do |inline|
+          next inline.tap { space = true } if inline.break?
+
+          text = inline.text.gsub(RUN, " ")
+          text = text.delete_prefix(" ") if space
+          space = text.end_with?(" ") unless text.empty?
+          inline.with(text:)
+        end
+      end
+
+      def trim_trailing(inlines)
+        space = true
+        inlines.reverse_each.map do |inline|
+          next inline.tap { space = true } if inline.break?
+
+          text = space ? inline.text.delete_suffix(" ") : inline.text
+          space = false unless text.empty?
+          inline.with(text:)
+        end.reverse
+      end
+    end
+  end
+end

data/lib/stationery/layout/box.rb

@@ -2,17 +2,31 @@
 
 module Stationery
   module Layout
-    # A container with padding, background, border and corner radius. Boxes
-    # move to the next page whole. A fixed-height box can truncate or shrink
-    # text that does not fit (`overflow:`).
+    # A container with padding, background, border and corner radius. A box
+    # moves to the next page whole when it fits there and continues across
+    # pages when it does not (`break_inside: :auto` splits at any break,
+    # `: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. `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)
+                     height: nil, min_height: nil, overflow: :visible, valign: :top, opacity: nil, link: nil, outset: 0,
+                     open: [], decoration: :slice)
+        raise ArgumentError, "pass height: or min_height:, not both" if height && min_height
+
         super()
+        @min_height = min_height
+        @open = open
+        @decoration = decoration
+        @link = link
+        @outset = Geometry.box(outset)
         @content = content
         @padding = Geometry.box(padding)
         @background = background
@@ -39,47 +53,111 @@ module Stationery
         end
       end
 
+      def splittable? = @height.nil? && @overflow == :visible && @content.splittable?
+      def prefer_whole? = break_inside.nil? && splittable?
+
+      def split(width, height, fresh: false)
+        return [self, nil] if measure(width) <= height + EPSILON
+
+        cut = @open | [:bottom]
+        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 || @min_height.to_f > height + EPSILON
+
+        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 || (@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, **)
+      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
+        paint_debug(canvas, Rect.new(x, y, width, height), debug_kind) if canvas.debug?
+      end
+
+      protected
+
+      def reopen(content, open, min_height = @min_height)
+        @content = content
+        @open = open
+        @min_height = min_height
+        self
       end
 
       private
 
-      def insets
+      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
-        top, right, bottom, left = @padding
-        sides = @border ? @border[:sides] : []
-        [top + (sides.include?(:top) ? border : 0), right + (sides.include?(:right) ? border : 0),
-         bottom + (sides.include?(:bottom) ? border : 0), left + (sides.include?(:left) ? border : 0)]
+        sides = @border ? @border[:sides] - open : []
+        Geometry::SIDES.keys.zip(@padding).map do |side, padding|
+          (open.include?(side) && @decoration == :slice ? 0 : padding) + (sides.include?(side) ? border : 0)
+        end
       end
 
       def horizontal = insets[1] + insets[3]
-      def vertical = insets[0] + insets[2]
+      def vertical(open = @open) = insets(open).values_at(0, 2).sum
       def inner_width(width) = [width - horizontal, 0].max
 
+      # The outset paints the background past the box's own edges (a band that
+      # bleeds into the page margins) without moving the content.
       def paint_background(canvas, x, y, width, height)
         return unless @background
 
-        canvas.rounded_rect(x, y, width, height, radius: @radius, fill: @background, opacity: @opacity)
+        top, right, bottom, left = @outset.each_with_index.map { |v, i| open?(i) ? 0 : v }
+        area = Rect.new(x - left, y - top, width + left + right, height + top + bottom)
+        cut(canvas, area, area) do |shape|
+          canvas.rounded_rect(*shape.to_h.values, radius: @radius, fill: @background, opacity: @opacity)
+        end
       end
 
       def paint_border(canvas, x, y, width, height)
         return unless @border
 
         stroke = @border[:width]
+        area = Rect.new(x, y, width, height)
         if @border[:sides].size == 4 && @radius.positive?
           half = stroke / 2.0
-          canvas.rounded_rect(x + half, y + half, width - stroke, height - stroke,
-                              radius: @radius, stroke: @border[:color], line_width: stroke)
+          cut(canvas, area, area.inset(half, half, half, half)) do |shape|
+            canvas.rounded_rect(*shape.to_h.values, radius: @radius, stroke: @border[:color], line_width: stroke)
+          end
         else
-          @border[:sides].each { |side| border_side(canvas, side, Rect.new(x, y, width, height), stroke) }
+          (@border[:sides] - @open).each { |side| border_side(canvas, side, area, stroke) }
+        end
+      end
+
+      def open?(index) = @open.include?(Geometry::SIDES.key(index))
+
+      # Cut edges are square: the rounded shape runs past them by its radius
+      # and stroke, clipped to the fragment.
+      def cut(canvas, area, shape)
+        return yield(shape) if @open.empty? || !@radius.positive?
+
+        reach = @radius + (@border ? @border[:width] : 0)
+        top = @open.include?(:top) ? reach : 0
+        bottom = @open.include?(:bottom) ? reach : 0
+        canvas.clip(area.x, area.y, area.width, area.height) do
+          yield Rect.new(shape.x, shape.y - top, shape.width, shape.height + top + bottom)
         end
       end
 
@@ -115,6 +193,14 @@ module Stationery
         end
       end
 
+      def paint_debug(canvas, rect, kind)
+        canvas.debug_rect(rect.x, rect.y, rect.width, rect.height, kind)
+        return if insets.all?(&:zero?)
+
+        inner = rect.inset(*insets)
+        canvas.debug_rect(inner.x, inner.y, inner.width, inner.height, :padding)
+      end
+
       def fitted(inner)
         return @content if @overflow == :visible || @height.nil? || @content.measure(inner.width) <= inner.height
         return shrunk(inner) if @overflow == :shrink_to_fit && shrinkable?

data/lib/stationery/layout/flow.rb

@@ -4,8 +4,9 @@ module Stationery
   module Layout
     # Children stacked top to bottom: the document body and every box's
     # content. Splits across pages: a splittable child continues on the next
-    # page, anything else moves there whole, a spacer at the break is dropped
-    # and a child marked keep_with_next moves with its successor.
+    # page (one that prefers staying whole only from the top of a fresh page),
+    # anything else moves there whole, a spacer at the break is dropped and a
+    # child marked keep_with_next moves with its successor.
     class Flow < Node
       attr_reader :children, :gap, :align
 
@@ -18,6 +19,7 @@ module Stationery
 
       def <<(child)
         @children << child
+        forget_measures
         self
       end
 
@@ -26,18 +28,22 @@ module Stationery
       def min_width = @children.map(&:min_width).max || 0
 
       def measure(width)
-        visible = @children.reject(&:page_break?)
-        visible.sum { |child| child.measure(width) } + (@gap * [visible.size - 1, 0].max)
+        memoize_by_width(width) do
+          visible = @children.reject(&:page_break?)
+          visible.sum { |child| child.measure(child.width_in(width)) } + (@gap * [visible.size - 1, 0].max)
+        end
       end
 
       def paint(canvas, x, y, width, _height = nil, **)
         cursor = y
         @children.reject(&:page_break?).each_with_index do |child, index|
           cursor += @gap unless index.zero?
-          own = child.fixed_width(width)
-          left = own ? x + Geometry.align_offset(@align, width, own) : x
-          child.paint(canvas, left, cursor, own || width)
-          cursor += child.measure(width)
+          own = child.width_in(width)
+          left = child.fixed_width(width) ? x + Geometry.align_offset(@align, width, own) : x
+          child.paint(canvas, left, cursor, own)
+          height = child.measure(own)
+          canvas.debug_rect(left, cursor, own, height, :flow)
+          cursor += height
         end
       end
 
@@ -79,7 +85,7 @@ module Stationery
 
           gap = @placed.empty? ? 0 : @flow.gap
           remaining = @height - @used - gap
-          height = child.measure(@width)
+          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)
 
@@ -93,25 +99,52 @@ module Stationery
         end
 
         def fits(child, consumed, left_after, rest)
-          if child.keep_with_next && rest.any? && !@placed.empty? && rest.first.split(@width, left_after).first.nil?
-            return [part(@placed), part([child, *rest])]
-          end
+          return [part(@placed), part([child, *rest])] if strand?(child, left_after, rest)
 
           @placed << child
           @used += consumed
           nil
         end
 
+        # keep_with_next: true needs the start of the next child on this page; a
+        # number needs that many points of what follows (or all of it, if less).
+        def strand?(child, left_after, rest)
+          want = child.keep_with_next
+          return false unless want && rest.any? && !@placed.empty?
+          return !starts?(rest.first, left_after) unless want.is_a?(Numeric)
+
+          following = 0
+          rest.each do |node|
+            following += node.measure(node.width_in(@width))
+            break if following >= want
+          end
+          left_after + EPSILON < [want, following].min
+        end
+
         def split_or_move(child, remaining, rest)
-          unless child.avoid_break?
-            head, tail = child.split(@width, remaining)
-            return [part(@placed + [head]), part([tail, *rest])] if head
+          if may_split?(child)
+            head, tail = child.split(child.width_in(@width), remaining, fresh: @fresh && @placed.empty?)
+            # A nested flow can finish on this page (its trailing spacer
+            # dropped at the break) and hand back no remainder.
+            return [part(@placed + [head]), part([tail, *rest].compact)] if head
           end
           return [part([child]), part(rest)] if @placed.empty? && @fresh
 
           @placed.empty? ? [nil, part([child, *rest])] : [part(@placed), part([child, *rest])]
         end
 
+        def may_split?(child, top: @placed.empty? && @fresh)
+          !child.avoid_break? && (!child.prefer_whole? || top)
+        end
+
+        # Whether any of `node` would be placed in `height` below other content.
+        def starts?(node, height)
+          width = node.width_in(@width)
+          return !node.split(width, height).first.nil? if may_split?(node, top: false)
+
+          node.measure(width) <= height + EPSILON
+        end
+
         def part(children)
           children.empty? ? nil : @flow.with_children(children)
         end

data/lib/stationery/layout/image.rb

@@ -30,6 +30,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.debug_rect(x, y, w, h, :image)
       end
 
       private