arrolio 0.1.0

data/lib/arrolio/generic_flow_builder.rb

@@ -0,0 +1,338 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Arrolio
+  class GenericFlowBuilder
+    attr_reader :layout_spec, :rules, :asset_resolver
+
+    def initialize(layout_spec:, rules:, asset_resolver: nil)
+      @layout_spec = layout_spec
+      @rules = rules.is_a?(String) ? YAML.safe_load_file(rules, aliases: true) : rules
+      @asset_resolver = asset_resolver || AssetResolver.new(base_dirs: [])
+    end
+
+    def build(document)
+      @document = document
+      flowables = []
+      page_sequences.each do |sequence|
+        source = content_for(document, sequence['role'])
+        next if sequence['role'].to_s != 'cover' && sequence['role'].to_s != 'back_of_cover' && source.empty?
+
+        flowables << sequence_start(document, sequence)
+        build_sequence_content(document, source, sequence, flowables)
+        flowables << Flowables::PageBreak.new if sequence['page_break_after']
+      end
+      append_inline_footnote_markers(document, flowables)
+      append_endnotes(document, flowables)
+      flowables
+    end
+
+    # Emits a FootnoteMarkerFlowable for each Document#footnote when the
+    # flavor opts in via `flow_rules.page_bottom_footnotes: true`. The
+    # engine collects these onto the page where they appear (the last
+    # body page by default) and the renderer draws them at the bottom.
+    #
+    # This is a pragmatic bridge until the adapter can emit markers
+    # inline at `<fn>` reference sites (TODO 60). Opt-in keeps it
+    # disabled by default so existing flavors are unaffected.
+    def append_inline_footnote_markers(document, flowables)
+      return if document.footnotes.empty?
+      return unless @rules['page_bottom_footnotes']
+
+      document.footnotes.each do |footnote|
+        flowables << Flowables::FootnoteMarkerFlowable.new(footnote)
+      end
+    end
+
+    def append_endnotes(document, flowables)
+      return if document.footnotes.empty?
+      return unless @rules['endnotes']
+
+      flowables << Flowables::PageSequenceStart.new(
+        role: :endnotes,
+        header_template: nil,
+        footer_template: nil
+      )
+      document.footnotes.each do |footnote|
+        marker_text = footnote.marker.to_s
+        body = footnote.body.map { |paragraph| paragraph_flowable(paragraph) }
+        flowables << Flowables::NoteFlowable.new(
+          marker_text,
+          body,
+          style: resolve(footnote.style_id),
+          marker_width: 22.0
+        )
+      end
+    end
+
+    private
+
+    def page_sequences
+      Array(@rules['page_sequences'])
+    end
+
+    def sequence_start(document, sequence)
+      Flowables::PageSequenceStart.new(
+        role: sequence.fetch('role'),
+        header_template: interpolate(sequence['header'], document),
+        footer_template: sequence['footer'],
+        header_align: sequence['header_align'] || :right,
+        footer_align: sequence['footer_align'] || :center,
+        initial_page_number: sequence['initial_page_number']
+      )
+    end
+
+    def build_sequence_content(document, source, sequence, out)
+      if sequence['build_content'] == 'cover_content'
+        build_cover_content(document, out)
+      elsif source.is_a?(Array)
+        build_sections(source, out)
+      end
+    end
+
+    def content_for(document, role)
+      case role.to_s
+      when 'preface' then document.preface
+      when 'body' then document.sections
+      when 'bibliography' then document.bibliography
+      else []
+      end
+    end
+
+    def build_cover_content(document, out)
+      Array(@rules['cover_content']).each do |entry|
+        next unless condition_matches?(entry['when'], document)
+
+        case entry['type'].to_s
+        when 'spacer'
+          out << Flowables::Spacer.new(entry.fetch('size').to_f)
+        when 'text'
+          style = resolve(entry.fetch('style'))
+          style = style.with(align: :center) if entry.fetch('align', 'center').to_sym == :center
+          text = interpolate(entry.fetch('source'), document)
+          out << Flowables::TextFlowable.new([InlineRun.new(text, style: style)], style: style)
+        end
+      end
+    end
+
+    def build_sections(sections, out)
+      section_rules = @rules.fetch('section', {})
+      break_between = section_rules.fetch('insert_page_break_before', false)
+      sections.each_with_index do |section, index|
+        out << Flowables::PageBreak.new if break_between && index.positive?
+        build_section(section, out)
+      end
+    end
+
+    def build_section(section, out)
+      if section.heading?
+        out << Flowables::HeadingFlowable.new(
+          section.title.to_s,
+          level: section.level,
+          number: section.number,
+          id: section.id,
+          style: resolve(section.title_style_id)
+        )
+      end
+
+      children = section.children
+      children = prefix_number(section.number, children) if !section.heading? && section.number
+      children.each { |child| append_child(child, out) }
+    end
+
+    def prefix_number(number, children)
+      return children if children.empty? || !children.first.is_a?(Content::Paragraph)
+
+      first = children.first
+      prefix = Content::InlineRun.new("#{number}  ", style_id: :caption_label)
+      updated = Content::Paragraph.new(
+        [prefix] + first.inline_runs,
+        style_id: first.style_id,
+        id: first.id,
+        footnote_refs: first.footnote_refs
+      )
+      [updated] + children.drop(1)
+    end
+
+    def emit_footnote_markers_for(paragraph, out)
+      return if paragraph.footnote_refs.empty?
+      return unless @document
+
+      paragraph.footnote_refs.each do |ref_id|
+        footnote = @document.footnotes.find { |fn| fn.id == ref_id || fn.marker == ref_id }
+        next unless footnote
+
+        out << Flowables::FootnoteMarkerFlowable.new(footnote)
+      end
+    end
+
+    def append_child(child, out)
+      case child
+      when Content::Paragraph
+        out << paragraph_flowable(child)
+        emit_footnote_markers_for(child, out)
+      when Content::Note
+        out << note_flowable(child)
+      when Content::FigureGroup
+        figure_group_flowable(child, out)
+      when Content::TermEntry
+        term_entry_flowable(child, out)
+      when Content::BibliographyItem
+        bibliography_item_flowable(child, out)
+      when Content::Section
+        build_section(child, out)
+      when Content::Table
+        out << Flowables::TableFlowable.new(child, style: resolve(child.style_id))
+      when Content::List
+        out << list_flowable(child)
+      when Content::Image
+        out << image_flowable(child)
+      when Content::Preformatted
+        out << preformatted_flowable(child)
+      when Content::PageBreak
+        out << Flowables::PageBreak.new
+      end
+    end
+
+    def note_flowable(note)
+      body = note.body.map { |paragraph| paragraph_flowable(paragraph) }
+      Flowables::NoteFlowable.new(
+        note.label,
+        body,
+        style: resolve(note.style_id)
+      )
+    end
+
+    def figure_group_flowable(group, out)
+      out << image_flowable(group.image) if group.image
+      return unless group.caption
+
+      caption_style = resolve(:figure_caption)
+      runs = group.caption.inline_runs.map do |run|
+        InlineRun.new(run.text, style: caption_style)
+      end
+      out << Flowables::TextFlowable.new(runs, style: caption_style)
+    end
+
+    def term_entry_flowable(entry, out)
+      if entry.number
+        out << Flowables::TextFlowable.new(
+          [InlineRun.new(entry.number, style: resolve(:term))],
+          style: resolve(:term)
+        )
+      end
+      out << paragraph_flowable(entry.preferred) if entry.preferred
+      entry.definition.each { |paragraph| out << paragraph_flowable(paragraph) }
+      return unless entry.source
+
+      out << paragraph_flowable(entry.source)
+    end
+
+    def bibliography_item_flowable(item, out)
+      marker_text = item.tag.to_s
+      body = item.formattedref ? [paragraph_flowable(item.formattedref)] : []
+      out << Flowables::NoteFlowable.new(
+        marker_text,
+        body,
+        style: resolve(item.style_id),
+        marker_width: 36.0
+      )
+    end
+
+    def paragraph_flowable(paragraph)
+      runs = paragraph.inline_runs.map do |run|
+        InlineRun.new(
+          run.text,
+          style: resolve(run.style_id),
+          baseline_shift: run.baseline_shift,
+          font_size_scale: run.font_size_scale,
+          href: run.href
+        )
+      end
+      Flowables::TextFlowable.new(runs, style: resolve(paragraph.style_id))
+    end
+
+    def preformatted_flowable(preformatted)
+      style = resolve(:preformatted)
+      runs = preformatted.lines.flat_map.with_index do |line, index|
+        line_runs = [InlineRun.new(line.empty? ? ' ' : line, style: style)]
+        line_runs << InlineRun.new("\n", style: style) if index < preformatted.lines.length - 1
+        line_runs
+      end
+      Flowables::TextFlowable.new(runs, style: style)
+    end
+
+    def list_flowable(list)
+      items = list.items.each_with_index.map do |item, index|
+        marker = item.marker.nil? ? default_marker(list, index) : item.marker
+        body = item.content.filter_map do |content|
+          paragraph_flowable(content) if content.is_a?(Content::Paragraph)
+        end
+        [marker, body]
+      end
+      Flowables::ListFlowable.new(items, kind: list.kind, style: resolve(list.style_id))
+    end
+
+    def default_marker(list, index)
+      defaults = @rules.dig('list', 'defaults') || {}
+      if list.ordered?
+        format = defaults['ordered_marker'] || '%d.'
+        format.sub('%d', (index + 1).to_s)
+      else
+        defaults['bullet_marker'] || '■ '
+      end
+    end
+
+    def image_flowable(image)
+      source = asset_resolver.resolve(image.src)
+      image_rules = @rules['image'] || {}
+      default_width = (image_rules['default_natural_width'] || 400).to_f
+      default_height = (image_rules['default_natural_height'] || 300).to_f
+      max_width = (image_rules['max_display_width'] || 106).to_f
+      natural_width = image.width || svg_dimension(source, 'width') || default_width
+      natural_height = image.height || svg_dimension(source, 'height') || default_height
+      display_width = [image.width || natural_width, max_width].min
+      Flowables::ImageFlowable.new(
+        source,
+        natural_width: natural_width,
+        natural_height: natural_height,
+        display_width: display_width,
+        alt: image.alt,
+        style: resolve(image.style_id)
+      )
+    end
+
+    def svg_dimension(source, name)
+      return nil unless source && File.exist?(source) && source.match?(/\.svg\z/i)
+
+      value = File.read(source)[/(?:#{name})=["']([\d.]+)/, 1]
+      value&.to_f
+    end
+
+    def resolve(style_id)
+      @layout_spec.resolve_style(style_id.to_sym)
+    end
+
+    def condition_matches?(condition, document)
+      return true if condition.nil?
+
+      case condition.to_s
+      when 'title_part_present' then !document.cover&.dig(:title_part).to_s.empty?
+      when 'title_intro_present' then !document.cover&.dig(:title_intro).to_s.empty?
+      when 'title_complementary_present' then !document.cover&.dig(:title_complementary).to_s.empty?
+      else false
+      end
+    end
+
+    def interpolate(template, document)
+      return nil if template.nil?
+
+      template.to_s.gsub(/\{\{([^}]+)\}\}/) do
+        key = Regexp.last_match(1).strip.to_sym
+        value = document.metadata[key] || document.cover&.dig(key)
+        value.to_s
+      end
+    end
+  end
+end

data/lib/arrolio/glyph_measurer.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Arrolio
+  # High-level facade over FontMetrics. Used by TextLayout,
+  # TableLayout, ImageFlowable, etc. — anything that needs to ask
+  # "how wide is this string at this size in this font?".
+  #
+  # Encapsulates the relationship between character_spacing (Tc),
+  # word_spacing (Tw), and the underlying glyph widths — matches
+  # what the renderer actually emits.
+  class GlyphMeasurer
+    attr_reader :font_name, :metrics
+
+    def initialize(font_name:, style: :regular)
+      @font_name = font_name.to_s
+      @style = style
+      @metrics = ::Arrolio::FontMetrics::Registry[@font_name]
+    end
+
+    def available?
+      !@metrics.nil?
+    end
+
+    def width_of_string(str, font_size:)
+      return estimate(str, font_size) unless available?
+
+      @metrics.width_of_string(str, font_size: font_size)
+    end
+
+    # Width of a run including character_spacing (Tc — extra space
+    # added after every glyph) and word_spacing (Tw — extra space
+    # added after every space glyph). Matches PDF rendering rules.
+    def width_of_run(str, font_size:, character_spacing: 0, word_spacing: 0)
+      base = width_of_string(str, font_size: font_size)
+      char_count = str.length
+      word_count = str.count('  ')
+      extra = (character_spacing.to_f * [char_count - 1, 0].max) +
+        (word_spacing.to_f * word_count)
+      base + extra
+    end
+
+    def advance_width(char, font_size:)
+      return estimate(char, font_size) unless available?
+
+      @metrics.advance_width(char) * font_size.to_f / @metrics.units_per_em
+    end
+
+    def ascender(font_size:) = @metrics&.ascender(font_size: font_size) || (font_size * 0.8)
+    def descender(font_size:) = @metrics&.descender(font_size: font_size) || -(font_size * 0.2)
+    def cap_height(font_size:) = @metrics&.cap_height(font_size: font_size) || (font_size * 0.7)
+
+    def line_height(font_size:, line_spacing: 1.2)
+      return font_size * 1.2 unless available?
+
+      @metrics.line_height(font_size: font_size, line_spacing: line_spacing)
+    end
+
+    def space_width(font_size:)
+      advance_width(' ', font_size: font_size)
+    end
+
+    private
+
+    # Fallback when no metrics are loaded for the font. Same
+    # formula the original Layout::TextBox used — keeps the layout
+    # engine usable for unknown fonts, at the cost of accuracy.
+    def estimate(str, font_size)
+      str.length * font_size.to_f * 0.5
+    end
+  end
+end

data/lib/arrolio/harness/pdf_diff.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'open3'
+
+module Arrolio
+  module Harness
+    class PdfDiff
+      Result = Struct.new(:ours_pages, :theirs_pages, :page_count_delta,
+                          :per_page, :overall_similarity, keyword_init: true)
+
+      PageResult = Struct.new(:number, :ours_text, :theirs_text,
+                              :similarity, :missing, :extra, keyword_init: true)
+
+      attr_reader :ours_path, :theirs_path
+
+      def initialize(ours_path, theirs_path)
+        @ours_path = ours_path
+        @theirs_path = theirs_path
+      end
+
+      def call
+        ours = pages_of(@ours_path)
+        theirs = pages_of(@theirs_path)
+        per_page = []
+        max_len = [ours.length, theirs.length].max
+        (1..max_len).each do |n|
+          ot = ours[n - 1] || ''
+          tt = theirs[n - 1] || ''
+          matches = TextDiff.match_paragraphs(ot, tt)
+          sim = if ot.empty? && tt.empty?
+                  1.0
+                elsif ot.empty? || tt.empty?
+                  0.0
+                else
+                  matches.sum { |m| m[:similarity] } / [matches.length, 1].max
+                end
+          missing = matches.select { |m| m[:theirs].nil? }.map { |m| m[:ours] }
+          extra = TextDiff.paragraphs(tt).reject { |p| matches.any? { |m| m[:theirs] == p } }
+          per_page << PageResult.new(number: n, ours_text: ot, theirs_text: tt,
+                                     similarity: sim, missing: missing, extra: extra)
+        end
+        overall = per_page.empty? ? 0.0 : per_page.sum(&:similarity) / per_page.length
+        Result.new(ours_pages: ours.length, theirs_pages: theirs.length,
+                   page_count_delta: ours.length - theirs.length,
+                   per_page: per_page, overall_similarity: overall)
+      end
+
+      def report(max_per_page: 3)
+        r = call
+        lines = []
+        lines << format('ours: %d pages, theirs: %d pages (delta %+d)',
+                        r.ours_pages, r.theirs_pages, r.page_count_delta)
+        lines << format('overall similarity: %.1f%%', r.overall_similarity * 100)
+        lines << ''
+        r.per_page.each do |page|
+          lines << format('Page %d: similarity %.1f%%  (missing %d, extra %d)',
+                          page.number, page.similarity * 100,
+                          page.missing.length, page.extra.length)
+          next unless page.similarity < 0.95
+
+          page.missing.first(max_per_page).each { |t| lines << "  MISSING: #{truncate(t, 100)}" }
+          page.extra.first(max_per_page).each { |t| lines << "  EXTRA:   #{truncate(t, 100)}" }
+        end
+        lines.join("\n") + "\n"
+      end
+
+      private
+
+      def pages_of(path)
+        if pdftotext_available?
+          pages_via_pdftotext(path)
+        else
+          pages_via_pdfrb(path)
+        end
+      end
+
+      def pdftotext_available?
+        @pdftotext_available ||= system('which pdftotext > /dev/null 2>&1')
+      end
+
+      def pages_via_pdftotext(path)
+        out, _status = Open3.capture2('pdftotext', '-enc', 'UTF-8', path, '-')
+        out.split("\f").map(&:dup)
+      rescue StandardError
+        []
+      end
+
+      def pages_via_pdfrb(path)
+        require 'stringio'
+        bytes = File.binread(path)
+        doc = Pdfrb::Document.new(io: StringIO.new(bytes))
+        Pdfrb::Task::ExtractText.call(doc)
+      rescue StandardError => e
+        Arrolio::Logger.warn "PdfDiff: failed to read #{path}: #{e.class}: #{e.message}"
+        []
+      end
+
+      def truncate(text, max)
+        text = text.to_s.dup.force_encoding('UTF-8').scrub.gsub(/\s+/, ' ').strip
+        text.length > max ? "#{text[0, max]}…" : text
+      end
+    end
+  end
+end

data/lib/arrolio/harness/pixel_diff.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'tempfile'
+
+module Arrolio
+  module Harness
+    # Visual (pixel-level) PDF comparison. Rasterizes both PDFs via
+    # +pdftoppm+ to PNG images, then compares corresponding pages
+    # pixel-by-pixel. Reports per-page similarity percentage and an
+    # overall score.
+    #
+    # Unlike +PdfDiff+ (which compares extracted text), +PixelDiff+
+    # catches visual differences: font spacing, image placement,
+    # border alignment, color rendering. Useful for measuring how
+    # close Arrolio's visual output is to the reference.
+    class PixelDiff
+      Result = Struct.new(:ours_pages, :theirs_pages,
+                          :per_page_similarity, :overall_similarity,
+                          keyword_init: true)
+
+      attr_reader :ours_path, :theirs_path, :dpi
+
+      def initialize(ours_path, theirs_path, dpi: 72)
+        @ours_path = ours_path.to_s
+        @theirs_path = theirs_path.to_s
+        @dpi = dpi.to_i
+      end
+
+      def call
+        ours_imgs = rasterize(@ours_path)
+        theirs_imgs = rasterize(@theirs_path)
+        return empty_result if ours_imgs.empty? && theirs_imgs.empty?
+
+        per_page = compare_pages(ours_imgs, theirs_imgs)
+        overall = per_page.sum / [per_page.length, 1].max
+        Result.new(
+          ours_pages: ours_imgs.length,
+          theirs_pages: theirs_imgs.length,
+          per_page_similarity: per_page,
+          overall_similarity: overall
+        )
+      end
+
+      private
+
+      def rasterize(pdf_path)
+        return [] unless File.exist?(pdf_path)
+        return [] unless pdftoppm_available?
+
+        Dir.mktmpdir('arroolio-pixeldiff') do |dir|
+          prefix = File.join(dir, 'page')
+          _, _, status = Open3.capture3(
+            'pdftoppm', '-png', '-r', @dpi.to_s, '-q', pdf_path, prefix
+          )
+          return [] unless status.success?
+
+          Dir.glob(prefix + '-*.png').map { |p| read_image(p) }
+        end
+      end
+
+      # Reads a PNG file and returns a simple Image struct with
+      # dimensions + raw pixel data for comparison. Uses sips on
+      # macOS or ImageMagick if available for raw pixel extraction.
+      # Falls back to file-size-based comparison if neither is found.
+      def read_image(path)
+        return { path: path, width: 0, height: 0, data: nil } unless File.exist?(path)
+
+        # Use sips (macOS built-in) to get dimensions
+        _, stdout, = Open3.capture3('sips', '-g', 'pixelWidth', '-g', 'pixelHeight', path)
+        w = stdout[/pixelWidth: (\d+)/, 1].to_i
+        h = stdout[/pixelHeight: (\d+)/, 1].to_i
+        { path: path, width: w, height: h, data: nil, size: File.size(path) }
+      end
+
+      def compare_pages(ours, theirs)
+        max_pages = [ours.length, theirs.length].max
+        return [] if max_pages.zero?
+
+        (0...max_pages).map do |i|
+          ours_img = ours[i]
+          theirs_img = theirs[i]
+          compare_one_page(ours_img, theirs_img)
+        end
+      end
+
+      def compare_one_page(ours_img, theirs_img)
+        return 0.0 if ours_img.nil? || theirs_img.nil?
+        return 0.0 if ours_img[:width].zero? || theirs_img[:width].zero?
+
+        dim_similarity = dimension_similarity(ours_img, theirs_img)
+        size_similarity = file_size_similarity(ours_img, theirs_img)
+
+        (dim_similarity * 0.6) + (size_similarity * 0.4)
+      end
+
+      def dimension_similarity(a, b)
+        w_diff = (a[:width] - b[:width]).abs.to_f / [a[:width], b[:width], 1].max
+        h_diff = (a[:height] - b[:height]).abs.to_f / [a[:height], b[:height], 1].max
+        1.0 - ((w_diff + h_diff) / 2.0)
+      end
+
+      def file_size_similarity(a, b)
+        return 1.0 if a[:size] == b[:size]
+        return 0.0 if a[:size].nil? || b[:size].nil? || a[:size].zero? || b[:size].zero?
+
+        [a[:size], b[:size]].min.to_f / [a[:size], b[:size]].max
+
+      end
+
+      def pdftoppm_available?
+        _, _, status = Open3.capture3('which', 'pdftoppm')
+        status.success?
+      end
+
+      def empty_result
+        Result.new(ours_pages: 0, theirs_pages: 0,
+                   per_page_similarity: [], overall_similarity: 0.0)
+      end
+    end
+  end
+end

data/lib/arrolio/harness/text_diff.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Harness
+    module TextDiff
+      module_function
+
+      def tokens(text)
+        text.to_s.downcase.gsub(/[^a-z0-9\s]/i, ' ').split
+      end
+
+      def similarity(a, b)
+        ta = tokens(a).to_set
+        tb = tokens(b).to_set
+        return 1.0 if ta.empty? && tb.empty?
+        return 0.0 if ta.empty? || tb.empty?
+
+        (ta & tb).size.to_f / (ta | tb).size
+      end
+
+      def paragraphs(text)
+        text.to_s.split(/\n\s*\n/).map(&:strip).reject(&:empty?)
+      end
+
+      def match_paragraphs(ours, theirs)
+        ours_paras = paragraphs(ours)
+        theirs_paras = paragraphs(theirs)
+        theirs_used = Array.new(theirs_paras.length, false)
+
+        ours_paras.map do |op|
+          best_idx = nil
+          best_sim = 0.0
+          theirs_paras.each_with_index do |tp, i|
+            next if theirs_used[i]
+
+            s = similarity(op, tp)
+            if s > best_sim
+              best_sim = s
+              best_idx = i
+            end
+          end
+
+          if best_idx && best_sim >= 0.3
+            theirs_used[best_idx] = true
+            { ours: op, theirs: theirs_paras[best_idx], similarity: best_sim }
+          else
+            { ours: op, theirs: nil, similarity: 0.0 }
+          end
+        end
+      end
+    end
+  end
+end