arrolio 0.1.0

data/lib/arrolio/text_layout/knuth_plass/breaker.rb

@@ -0,0 +1,265 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module TextLayout
+    module KnuthPlass
+      # Optimal line breaking via dynamic programming (Knuth & Plass,
+      # 1981). Finds the set of break points that minimizes the total
+      # "badness" — the sum of squared adjustment ratios across all
+      # lines, plus penalties for flagged breaks.
+      #
+      # The algorithm runs in O(n²) worst case (n = item count) but
+      # converges in O(n) for typical text because most candidate
+      # breaks are pruned early.
+      #
+      # Produces TextLayout::Line[] output — compatible with the
+      # existing Greedy breaker so the engine can swap freely.
+      class Breaker
+        Infinity = Float::INFINITY
+
+        # Tolerance for adjustment ratio — lines with ratio above
+        # this are considered "underfull" and penalized.
+        TOLERANCE = 100.0
+
+        # Extra penalty for consecutive flagged breaks (hyphens).
+        FLAGGED_PENALTY = 3000.0
+
+        # Extra penalty for the last line being underfull.
+        DEMERITS_LAST_LINE = 50.0
+
+        attr_reader :items, :line_widths, :runs, :measurer, :align
+
+        # +items:+ Array of KnuthPlass::Item (Box, Glue, Penalty).
+        # +line_widths:+ Array of Float — width available per line.
+        #   If shorter than the number of lines, the last width repeats.
+        # +runs:+ Array of InlineRun — for building placed runs.
+        # +measurer:+ GlyphMeasurer for width lookups.
+        # +align:+ :left, :right, :center, :justify.
+        def initialize(items:, line_widths:, runs:, measurer:, align: :left)
+          @items = items
+          @line_widths = line_widths
+          @runs = runs
+          @measurer = measurer
+          @align = align
+        end
+
+        def layout
+          nodes = active_nodes
+          return [] if nodes.empty?
+
+          # Only consider nodes that reached the end of the items
+          # (the FINISHED penalty at the last position).
+          final_nodes = nodes.select { |n| n.position == @items.length - 1 }
+          return [] if final_nodes.empty?
+
+          # Backtrack from the best final node.
+          breaks = reconstruct_breaks(best_final_node(final_nodes))
+
+          # Build Line objects from the break points.
+          lines = []
+          prev_item = 0
+          breaks.each_with_index do |br, line_idx|
+            width = line_width_for(line_idx)
+            placed = build_placed_runs(prev_item, br, width)
+            used = compute_line_width(prev_item, br)
+            lines << Line.new(placed, width: used, max_width: width, align: @align)
+            prev_item = br
+          end
+          lines
+        end
+
+        # Internal: a node in the dynamic programming graph.
+        Node = Struct.new(:position, :line, :fitness, :total_demerits,
+                          :previous, keyword_init: true)
+
+        private
+
+        # Active-node dynamic programming. Each active node represents
+        # a feasible break position. We iterate through items and
+        # try breaking at each feasible position.
+        def active_nodes
+          @active = [Node.new(position: -1, line: 0, fitness: 1,
+                              total_demerits: 0, previous: nil)]
+          @items.each_with_index do |_item, i|
+            next unless feasible_break?(i)
+
+            @active = @active.reject { |a| prune?(a, i) }
+            candidates = @active.filter_map { |a| try_break(a, i) }
+            best = best_candidate(candidates)
+            @active << best if best
+          end
+          @active
+        end
+
+        def feasible_break?(i)
+          item = @items[i]
+          (item.penalty? && !item.no_break?) || (item.glue? && i.positive? && @items[i - 1].box?)
+        end
+
+        def prune?(node, _current)
+          node.line >= @line_widths.length + 10
+        end
+
+        def try_break(node, break_pos)
+          item = @items[break_pos]
+          width = line_width_for(node.line)
+          line_w = compute_line_width(node.position + 1, break_pos)
+
+          is_forced = item.penalty? && item.forced_break?
+          ratio = adjustment_ratio(line_w, width, break_pos)
+
+          # Forced breaks are always accepted but still penalized
+          # for bad ratios so the algorithm prefers shorter lines.
+          unless is_forced
+            return nil if ratio.abs > TOLERANCE
+          end
+
+          ratio = 0.0 if ratio == Infinity || ratio == -Infinity
+          demerits = demerits_for(ratio, break_pos)
+          total = node.total_demerits + demerits
+          fitness = fitness_class(ratio)
+
+          Node.new(
+            position: break_pos,
+            line: node.line + 1,
+            fitness: fitness,
+            total_demerits: total,
+            previous: node
+          )
+        end
+
+        def best_candidate(candidates)
+          candidates.min_by(&:total_demerits)
+        end
+
+        def best_final_node(nodes)
+          nodes.min_by(&:total_demerits)
+        end
+
+        # Adjustment ratio: how stretched (positive) or shrunk
+        # (negative) a line is. 0 = perfect fit.
+        def adjustment_ratio(natural_width, target_width, break_pos)
+          glue_stretch = total_stretch(break_pos)
+          glue_shrink = total_shrink(break_pos)
+
+          if natural_width < target_width
+            glue_stretch.positive? ? (target_width - natural_width) / glue_stretch : Infinity
+          elsif natural_width > target_width
+            glue_shrink.positive? ? (target_width - natural_width) / glue_shrink : -Infinity
+          else
+            0.0
+          end
+        end
+
+        def demerits_for(ratio, break_pos)
+          penalty = @items[break_pos].penalty? ? @items[break_pos].penalty : 0
+          badness = if ratio.negative?
+            (100 * ((-ratio) ** 3)).to_i
+          else
+            0
+                    end
+          # Standard Knuth-Plass demerits. Forced breaks (penalty =
+          # -Infinity) use d = (1 + badness)^2 — the penalty term
+          # drops out because there's no choice about breaking.
+          d = if penalty.infinite?
+                (1 + badness) ** 2
+              elsif penalty >= 0
+                (1 + badness + penalty) ** 2
+              else
+                ((1 + badness) ** 2) - (penalty ** 2)
+              end
+          flagged = @items[break_pos].penalty? && @items[break_pos].flagged ? FLAGGED_PENALTY : 0
+          d + flagged
+        end
+
+        def fitness_class(ratio)
+          case ratio
+          when -Infinity..-0.5 then 0 # tight
+          when -0.5..0.5 then 1       # normal
+          when 0.5..1.0 then 2        # loose
+          else 3                       # very loose
+          end
+        end
+
+        # Sum of widths from item +start+ to item +stop+ (exclusive).
+        # Discards trailing glue at the break point.
+        def compute_line_width(start, stop)
+          return 0.0 if start >= stop
+
+          sum = 0.0
+          (start...stop).each do |i|
+            item = @items[i]
+            next if item.nil?
+
+            # Trailing glue after last box is discarded at break.
+            last_box = last_box_index_in(start, stop)
+            sum += item.width if i <= last_box
+          end
+          sum
+        end
+
+        def last_box_index_in(start, stop)
+          idx = start - 1
+          (start...stop).each do |i|
+            idx = i if @items[i]&.box?
+          end
+          idx
+        end
+
+        def total_stretch(break_pos)
+          sum = 0.0
+          @items[0..break_pos].each { |item| sum += item.stretch if item.glue? }
+          sum
+        end
+
+        def total_shrink(break_pos)
+          sum = 0.0
+          @items[0..break_pos].each { |item| sum += item.shrink if item.glue? }
+          sum
+        end
+
+        def line_width_for(line_idx)
+          @line_widths[[line_idx, @line_widths.length - 1].min]
+        end
+
+        def reconstruct_breaks(final_node)
+          breaks = []
+          node = final_node
+          while node&.previous
+            breaks << node.position
+            node = node.previous
+          end
+          breaks.reverse
+        end
+
+        def build_placed_runs(start_item, stop_item, _width)
+          placed = []
+          x_offset = 0.0
+          (start_item...stop_item).each do |i|
+            item = @items[i]
+            next unless item&.box?
+
+            run = @runs[item.run_index]
+            next unless run
+
+            slice = run.text[item.char_offset, item.char_length]
+            next if slice.nil? || slice.empty?
+
+            sub = InlineRun.new(slice, style: run.style,
+                                       baseline_shift: run.baseline_shift,
+                                       font_size_scale: run.font_size_scale,
+                                       href: run.href)
+            placed << Line::PlacedRun.new(run: sub, x_offset: x_offset)
+            x_offset += item.width
+          end
+          placed
+        end
+
+        def finalize_node(position, line, fitness, total_demerits, previous)
+          Node.new(position: position, line: line, fitness: fitness,
+                   total_demerits: total_demerits, previous: previous)
+        end
+      end
+    end
+  end
+end

data/lib/arrolio/text_layout/knuth_plass/item.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module TextLayout
+    module KnuthPlass
+      # Base class for items in the Knuth-Plass line-breaking model.
+      # Every item has a width. Box and Glue are "content"; Penalty
+      # is a potential break point.
+      class Item
+        attr_reader :width
+
+        def initialize(width:)
+          @width = width.to_f
+        end
+
+        def box? = false
+        def glue? = false
+        def penalty? = false
+      end
+
+      # A box is a unit of content that cannot be broken across
+      # lines (a word, a glyph cluster). Has a fixed width.
+      class Box < Item
+        attr_reader :run_index, :char_offset, :char_length
+
+        def initialize(width:, run_index:, char_offset:, char_length:)
+          super(width: width)
+          @run_index = run_index
+          @char_offset = char_offset
+          @char_length = char_length
+        end
+
+        def box? = true
+      end
+
+      # Glue represents inter-word space. Has a natural width plus
+      # stretchability (how much it can grow) and shrinkability
+      # (how much it can shrink). At a break point, trailing glue
+      # is discarded (doesn't contribute to line width).
+      class Glue < Item
+        attr_reader :stretch, :shrink, :run_index, :char_offset
+
+        def initialize(width:, stretch:, shrink:, run_index: nil, char_offset: nil)
+          super(width: width)
+          @stretch = stretch.to_f
+          @shrink = shrink.to_f
+          @run_index = run_index
+          @char_offset = char_offset
+        end
+
+        def glue? = true
+      end
+
+      # A penalty represents a potential break point. Width is the
+      # width of the hyphen (or 0 if no hyphen). Flagged penalties
+      # (e.g., hyphenation) incur extra cost. A penalty of +Infinity+
+      # means "never break here"; -Infinity means "always break".
+      class Penalty < Item
+        attr_reader :penalty, :flagged, :run_index, :char_offset
+
+        def initialize(penalty:, width: 0, flagged: false, run_index: nil, char_offset: nil)
+          super(width: width)
+          @penalty = penalty.to_f
+          @flagged = flagged
+          @run_index = run_index
+          @char_offset = char_offset
+        end
+
+        def penalty? = true
+
+        def forced_break?
+          @penalty == -Float::INFINITY
+        end
+
+        def no_break?
+          @penalty == Float::INFINITY
+        end
+      end
+
+      # A forced break at the end of a paragraph.
+      FINISHED = Penalty.new(penalty: -Float::INFINITY).freeze
+    end
+  end
+end

data/lib/arrolio/text_layout/knuth_plass/item_builder.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module TextLayout
+    module KnuthPlass
+      # Converts a list of InlineRun values into KnuthPlass::Item
+      # sequences (Box, Glue, Penalty). Each word becomes a Box;
+      # spaces become Glue; potential break points become Penalty
+      # items.
+      class ItemBuilder
+        HYPHEN_PENALTY = 50.0
+
+        attr_reader :runs, :measurer
+
+        def initialize(runs, measurer:)
+          @runs = runs
+          @measurer = measurer
+        end
+
+        def build
+          items = []
+          @runs.each_with_index do |run, run_idx|
+            build_items_for_run(run, run_idx, items)
+          end
+          items << FINISHED
+          items
+        end
+
+        private
+
+        def build_items_for_run(run, run_idx, items)
+          text = run.text
+          return if text.nil? || text.empty?
+
+          # Handle forced breaks first.
+          if text.include?("\n")
+            build_newline_items(run, run_idx, text, items)
+            return
+          end
+
+          words = text.split(/(\s+)/)
+          offset = 0
+          words.each do |word|
+            if word.match?(/\s+/)
+              width = measure(word, run)
+              stretch = measure(' ', run) * 0.5
+              shrink = measure(' ', run) * 0.33
+              items << Glue.new(width: width, stretch: stretch, shrink: shrink,
+                                run_index: run_idx, char_offset: offset)
+            elsif word.include?('-')
+              build_hyphenated_word(word, run, run_idx, offset, items)
+            elsif !word.empty?
+              width = measure(word, run)
+              items << Box.new(width: width, run_index: run_idx,
+                               char_offset: offset, char_length: word.length)
+            end
+            offset += word.length
+          end
+        end
+
+        def build_newline_items(run, run_idx, text, items)
+          segments = text.split("\n")
+          segments.each_with_index do |seg, i|
+            unless seg.empty?
+              width = measure(seg, run)
+              items << Box.new(width: width, run_index: run_idx,
+                               char_offset: text.index(seg) || 0,
+                               char_length: seg.length)
+            end
+            items << Penalty.new(penalty: -Float::INFINITY, run_index: run_idx) if i < segments.length - 1
+          end
+        end
+
+        def build_hyphenated_word(word, run, run_idx, offset, items)
+          parts = word.split(/(-)/)
+          part_offset = offset
+          parts.each do |part|
+            next if part.empty?
+
+            width = measure(part, run)
+            items << Box.new(width: width, run_index: run_idx,
+                             char_offset: part_offset, char_length: part.length)
+            if part == '-'
+              items << Penalty.new(width: 0, penalty: HYPHEN_PENALTY,
+                                   flagged: true, run_index: run_idx,
+                                   char_offset: part_offset)
+            end
+            part_offset += part.length
+          end
+        end
+
+        def measure(text, run)
+          @measurer.width_of_run(
+            text,
+            font_size: run.style.font_size * run.font_size_scale,
+            character_spacing: run.style.character_spacing,
+            word_spacing: 0
+          )
+        end
+      end
+    end
+  end
+end

data/lib/arrolio/text_layout/knuth_plass.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Arrolio::TextLayout::KnuthPlass — optimal line breaking.
+module Arrolio
+  module TextLayout
+    module KnuthPlass
+      autoload :Item, 'arrolio/text_layout/knuth_plass/item'
+      autoload :Breaker, 'arrolio/text_layout/knuth_plass/breaker'
+      autoload :ItemBuilder, 'arrolio/text_layout/knuth_plass/item_builder'
+    end
+  end
+end

data/lib/arrolio/text_layout/line.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module TextLayout
+    # One laid-out line: a list of PlacedRun tuples plus the
+    # line's content width, target width, and alignment.
+    class Line
+      PlacedRun = Struct.new(:run, :x_offset, keyword_init: true) do
+        def freeze
+          run.freeze
+          super
+        end
+      end
+
+      attr_reader :placed_runs, :width, :max_width, :align
+
+      def initialize(placed_runs, width:, max_width:, align: :left)
+        @placed_runs = placed_runs.freeze
+        @width = width.to_f
+        @max_width = max_width.to_f
+        @align = align
+        freeze
+      end
+
+      def empty?
+        @placed_runs.empty?
+      end
+
+      def x_offset
+        case @align
+        when :center then ((@max_width - @width) / 2.0)
+        when :right then (@max_width - @width)
+        else 0.0
+        end
+      end
+
+      def justified?
+        @align == :justify
+      end
+
+      def justify_stretch
+        return 0.0 unless justified?
+        return 0.0 if @width >= @max_width
+
+        gaps = word_gap_count
+        return 0.0 if gaps.zero?
+
+        (@max_width - @width) / gaps.to_f
+      end
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          placed_runs == other.placed_runs &&
+          width == other.width &&
+          max_width == other.max_width &&
+          align == other.align
+      end
+
+      alias eql? ==
+
+      def hash
+        [self.class, placed_runs, width, max_width, align].hash
+      end
+
+      private
+
+      def word_gap_count
+        @placed_runs.sum { |pr| pr.run.text.count(' ') }
+      end
+    end
+  end
+end

data/lib/arrolio/text_layout.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Arrolio::TextLayout — paragraph line-breaking. Pure + stateless.
+module Arrolio
+  module TextLayout
+    autoload :Greedy, 'arrolio/text_layout/greedy'
+    autoload :Line, 'arrolio/text_layout/line'
+    autoload :BreakOpportunity, 'arrolio/text_layout/break_opportunity'
+    autoload :KnuthPlass, 'arrolio/text_layout/knuth_plass'
+  end
+end

data/lib/arrolio/toc_builder.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module TocBuilder
+    module_function
+
+    def build_flowables(context, layout_spec, rules: {})
+      styles = rules.fetch('styles', {})
+      entries = context.heading_entries
+      entries.map do |entry|
+        number = entry[:number]
+        title = entry[:title].to_s
+        label = number ? "#{number} #{title}" : title
+        style_id = style_id_for(entry[:level], styles)
+        style = layout_spec.resolve_style(style_id)
+        Flowables::TocLineFlowable.new(
+          label,
+          entry[:page_number],
+          level: entry[:level] || 1,
+          style: style
+        )
+      end
+    end
+
+    def style_id_for(level, styles)
+      key = level.to_i >= 2 ? 'sub' : 'entry'
+      default_style = key == 'sub' ? 'toc_entry_sub' : 'toc_entry'
+      (styles[key] || default_style).to_sym
+    end
+  end
+end

data/lib/arrolio/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Arrolio
+  VERSION = '0.1.0'
+end

data/lib/arrolio/writing_mode.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Arrolio
+  # Writing mode enumeration for vertical/RTL layout. Controls
+  # the inline and block progression directions used by the
+  # layout engine. The values map to XSL-FO writing-mode
+  # property values.
+  #
+  # +LR_TB+ — left-to-right inline, top-to-bottom block (Latin, CJK).
+  # +RL_TB+ — right-to-left inline, top-to-bottom block (Arabic, Hebrew).
+  # +TB_RL+ — top-to-bottom inline, right-to-left block (vertical CJK).
+  class WritingMode
+    LR_TB = :lr_tb
+    RL_TB = :rl_tb
+    TB_RL = :tb_rl
+    DEFAULT = LR_TB
+
+    ALL = [LR_TB, RL_TB, TB_RL].freeze
+
+    attr_reader :mode
+
+    def initialize(mode = DEFAULT)
+      @mode = mode.to_sym
+      freeze
+    end
+
+    def vertical?
+      @mode == TB_RL
+    end
+
+    def rtl?
+      @mode == RL_TB
+    end
+
+    def ltr?
+      @mode == LR_TB
+    end
+
+    # Returns the inline progression direction as a 2D vector.
+    # +[1, 0]+ = rightward, +[-1, 0]+ = leftward, +[0, 1]+ = downward.
+    def inline_direction
+      case @mode
+      when LR_TB then [1, 0]
+      when RL_TB then [-1, 0]
+      when TB_RL then [0, 1]
+      end
+    end
+
+    # Returns the block progression direction as a 2D vector.
+    def block_direction
+      case @mode
+      when LR_TB, RL_TB then [0, -1]
+      when TB_RL then [-1, 0]
+      end
+    end
+
+    def ==(other)
+      other.is_a?(self.class) && mode == other.mode
+    end
+    alias eql? ==
+
+    def hash
+      [self.class, mode].hash
+    end
+
+    def self.parse(value)
+      case value.to_s.downcase.tr('-', '_')
+      when 'lr_tb', 'lrtb' then new(LR_TB)
+      when 'rl_tb', 'rltb' then new(RL_TB)
+      when 'tb_rl', 'tbrl' then new(TB_RL)
+      else new(DEFAULT)
+      end
+    end
+  end
+end