arrolio 0.1.0

data/lib/arrolio/flowables/text_flowable.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Flowables
+    # A paragraph of flowing text. Selects a line-breaking strategy
+    # based on the style's +line_break+ attribute (:greedy or
+    # :knuth_plass). Both strategies produce TextLayout::Line[]
+    # with the same shape, so the rest of the pipeline is agnostic.
+    class TextFlowable < Flowable
+      attr_reader :runs, :measurer
+
+      def initialize(runs, style: Style::Definition.new, measurer: nil)
+        super(style: style)
+        @runs = Array(runs)
+        @measurer = measurer || GlyphMeasurer.new(font_name: style.font_name)
+      end
+
+      def height(width, _context = nil)
+        laid_out(width).length * line_height
+      end
+
+      def emit(x, y, width, _context = nil)
+        lines = laid_out(width)
+        return [[], 0.0] if lines.empty?
+
+        box = Output::PlacedBox.text(
+          x: x, y: y - (line_height * lines.length),
+          width: width, height: line_height * lines.length,
+          lines: lines, line_height: line_height, style: @style
+        )
+        [[box], box.height]
+      end
+
+      def splittable?
+        true
+      end
+
+      def do_split(width, remaining_height, _context = nil)
+        lines = laid_out(width)
+        line_h = line_height
+        head_count = (remaining_height.to_f / line_h).floor
+        head_count = [head_count, lines.length].min
+        head_count = 1 if head_count < 1 && lines.any?
+
+        head_lines = lines[0...head_count]
+        tail_lines = lines[head_count..] || []
+
+        head_runs = collect_runs(head_lines)
+        tail_runs = collect_runs(tail_lines)
+
+        head = head_runs.empty? ? nil : self.class.new(head_runs, style: @style, measurer: @measurer)
+        tail = tail_runs.empty? ? nil : self.class.new(tail_runs, style: @style, measurer: @measurer)
+        [head, tail]
+      end
+
+      private
+
+      def laid_out(width)
+        case @style.line_break
+        when :knuth_plass
+          layout_knuth_plass(width)
+        else
+          layout_greedy(width)
+        end
+      end
+
+      def layout_greedy(width)
+        TextLayout::Greedy.new(@runs, measurer: @measurer,
+                                      width: width,
+                                      align: @style.align).layout
+      end
+
+      def layout_knuth_plass(width)
+        items = TextLayout::KnuthPlass::ItemBuilder.new(@runs, measurer: @measurer).build
+        TextLayout::KnuthPlass::Breaker.new(
+          items: items, line_widths: [width], runs: @runs,
+          measurer: @measurer, align: @style.align
+        ).layout
+      end
+
+      def line_height
+        @measurer.line_height(font_size: @style.font_size,
+                              line_spacing: @style.line_spacing)
+      end
+
+      def collect_runs(lines)
+        runs = []
+        lines.each do |line|
+          line.placed_runs.each { |pr| runs << pr.run }
+        end
+        runs
+      end
+    end
+  end
+end

data/lib/arrolio/flowables/toc_line_flowable.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Flowables
+    # One ToC line: title + dot-leader + page number. One line tall.
+    class TocLineFlowable < Flowable
+      attr_reader :title, :page_number, :level
+
+      def initialize(title, page_number, level: 1, style: Style::Definition.new)
+        super(style: style)
+        @title = title.to_s
+        @page_number = page_number.to_i
+        @level = level.to_i
+      end
+
+      def height(_width, _context = nil)
+        GlyphMeasurer.new(font_name: @style.font_name)
+                     .line_height(font_size: @style.font_size,
+                                  line_spacing: @style.line_spacing)
+      end
+
+      def emit(x, y, width, context = nil)
+        page_str = @page_number.to_s
+        measurer = GlyphMeasurer.new(font_name: @style.font_name)
+        title_w = measurer.width_of_string(@title, font_size: @style.font_size)
+        page_w = measurer.width_of_string(page_str, font_size: @style.font_size)
+        gap = width - title_w - page_w - 10
+        dots = gap.positive? ? ('.' * (gap / measurer.space_width(font_size: @style.font_size)).floor) : ' '
+        text = "#{@title} #{dots} #{page_str}"
+        tf = TextFlowable.new([InlineRun.new(text, style: @style)], style: @style)
+        tf.emit(x, y, width, context)
+      end
+    end
+  end
+end

data/lib/arrolio/flowables/two_column_block.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Flowables
+    # Two-column layout for a cover-page header. Renders left and right
+    # content blocks side-by-side without table borders, matching the
+    # reference PDF's two-column fo:table layout. Used by flow builders
+    # to place flavor-specific cover text in two columns.
+    class TwoColumnBlock < Flowable
+      attr_reader :left_flowables, :right_flowables, :left_ratio, :style
+
+      # +left_flowables:+ Array of TextFlowable for the left column.
+      # +right_flowables:+ Array of TextFlowable for the right column.
+      # +left_ratio:+ Fraction of width for the left column (default 0.5).
+      def initialize(left_flowables:, right_flowables:, left_ratio: 0.5,
+                     style: Style::Definition.new)
+        super(style: style)
+        @left_flowables = Array(left_flowables)
+        @right_flowables = Array(right_flowables)
+        @left_ratio = left_ratio.to_f
+      end
+
+      def height(width, context = nil)
+        left_w = width * @left_ratio
+        right_w = width * (1.0 - @left_ratio)
+        left_h = @left_flowables.sum { |f| f.height(left_w, context) }
+        right_h = @right_flowables.sum { |f| f.height(right_w, context) }
+        [left_h, right_h].max
+      end
+
+      def emit(x, y, width, context = nil)
+        left_w = width * @left_ratio
+        right_w = width * (1.0 - @left_ratio)
+        right_x = x + left_w
+        boxes = []
+
+        left_cursor = y
+        @left_flowables.each do |f|
+          fboxes, consumed = f.emit(x, left_cursor, left_w, context)
+          boxes.concat(fboxes)
+          left_cursor -= consumed
+        end
+
+        right_cursor = y
+        @right_flowables.each do |f|
+          fboxes, consumed = f.emit(right_x, right_cursor, right_w, context)
+          boxes.concat(fboxes)
+          right_cursor -= consumed
+        end
+
+        consumed = [y - left_cursor, y - right_cursor].max
+        [boxes, consumed]
+      end
+    end
+  end
+end

data/lib/arrolio/flowables.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+# Arrolio::Flowables — concrete Flowable subclasses.
+module Arrolio
+  module Flowables
+    autoload :TextFlowable, 'arrolio/flowables/text_flowable'
+    autoload :Spacer, 'arrolio/flowables/spacer'
+    autoload :PageBreak, 'arrolio/flowables/page_break'
+    autoload :HeadingFlowable, 'arrolio/flowables/heading_flowable'
+    autoload :PageSequenceStart, 'arrolio/flowables/page_sequence_start'
+    autoload :ListFlowable, 'arrolio/flowables/list_flowable'
+    autoload :NoteFlowable, 'arrolio/flowables/note_flowable'
+    autoload :ImageFlowable, 'arrolio/flowables/image_flowable'
+    autoload :TocLineFlowable, 'arrolio/flowables/toc_line_flowable'
+    autoload :TwoColumnBlock, 'arrolio/flowables/two_column_block'
+    autoload :TableFlowable, 'arrolio/flowables/table_flowable'
+    autoload :FootnoteMarkerFlowable, 'arrolio/flowables/footnote_marker_flowable'
+  end
+end

data/lib/arrolio/font/embedder.rb

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+require 'fontisan'
+
+module Arrolio
+  module Font
+    class Embedder
+      attr_reader :document, :font_path, :base_font_name
+
+      def initialize(document, font_path, base_font_name: nil)
+        @document = document
+        @font_path = font_path
+        @base_font_name = base_font_name || File.basename(font_path, '.*')
+        @fontisan_font = Fontisan::FontLoader.load(font_path)
+        @unicode_to_gid = @fontisan_font.table('cmap').unicode_mappings.transform_keys(&:to_i)
+        @subset_cp_to_gid = nil
+        @subset_gid_to_cp = nil
+      end
+
+      def glyph_id_for_codepoint(codepoint)
+        @unicode_to_gid[codepoint.to_i] || 0
+      end
+
+      def subset_gid_for_codepoint(codepoint)
+        return glyph_id_for_codepoint(codepoint) unless @subset_cp_to_gid
+        @subset_cp_to_gid[codepoint.to_i] || 0
+      end
+
+      def subset(codepoints)
+        gids = codepoints.map { |cp| glyph_id_for_codepoint(cp) }.uniq.sort
+        gids << 0
+        options = Fontisan::Subset::Options.new(profile: 'pdf')
+        builder = Fontisan::Subset::Builder.new(@fontisan_font, gids, options)
+        { bytes: builder.build, gid_map: builder.mapping }
+      end
+
+      def embed(codepoints)
+        sub = subset(codepoints)
+        bytes = sub[:bytes]
+        extract_subset_cmap(bytes)
+        stream = @document.add(
+          { Length: bytes.bytesize, Length1: bytes.bytesize },
+          type: Pdfrb::Model::Cos::Stream
+        )
+        stream.stream = bytes
+        font_file2 = Pdfrb::Model::Reference.new(stream.oid, stream.gen)
+        descriptor = @document.add(
+          { Type: :FontDescriptor, FontName: @base_font_name.to_sym,
+            Flags: 32, FontBBox: font_bbox, ItalicAngle: 0,
+            Ascent: ascent, Descent: descent, CapHeight: cap_height,
+            StemV: 80, FontFile2: font_file2 },
+          type: Pdfrb::Model::Type::FontDescriptor
+        )
+        cid_font = @document.add(
+          { Type: :Font, Subtype: :CIDFontType2,
+            BaseFont: @base_font_name.to_sym,
+            CIDSystemInfo: { Registry: 'Adobe', Ordering: 'Identity', Supplement: 0 },
+            CIDToGIDMap: :Identity,
+            FontDescriptor: Pdfrb::Model::Reference.new(descriptor.oid, descriptor.gen),
+            W: widths_array },
+          type: Pdfrb::Model::Type::CIDFont
+        )
+        tounicode_data = build_tounicode_stream
+        tounicode = @document.add(
+          { Length: tounicode_data.bytesize },
+          type: Pdfrb::Model::Cos::Stream
+        )
+        tounicode.stream = tounicode_data
+        type0 = @document.add(
+          { Type: :Font, Subtype: :Type0,
+            BaseFont: @base_font_name.to_sym,
+            Encoding: :'Identity-H',
+            DescendantFonts: [Pdfrb::Model::Reference.new(cid_font.oid, cid_font.gen)],
+            ToUnicode: Pdfrb::Model::Reference.new(tounicode.oid, tounicode.gen) },
+          type: Pdfrb::Model::Type::FontType0
+        )
+        Pdfrb::Model::Reference.new(type0.oid, type0.gen)
+      end
+
+      private
+
+      def extract_subset_cmap(bytes)
+        require 'tmpdir'
+        Dir.mktmpdir do |dir|
+          path = File.join(dir, 'subset.ttf')
+          File.binwrite(path, bytes)
+          sf = Fontisan::FontLoader.load(path)
+          cm = sf.table('cmap').unicode_mappings
+          @subset_cp_to_gid = cm.transform_keys(&:to_i)
+          @subset_gid_to_cp = @subset_cp_to_gid.invert
+        end
+      rescue StandardError => e
+        Arrolio::Logger.warn "subset cmap extract failed: #{e.message[0,80]}"
+        @subset_cp_to_gid = @unicode_to_gid
+        @subset_gid_to_cp = @unicode_to_gid.invert
+      end
+
+      def build_tounicode_stream
+        gid_to_cp = @subset_gid_to_cp || @unicode_to_gid.invert
+        lines = []
+        lines << '/CIDInit /ProcSet findresource begin'
+        lines << '12 dict begin'
+        lines << 'begincmap'
+        lines << '/CIDSystemInfo << /Registry (Adobe) /Ordering (UCS) /Supplement 0 >> def'
+        lines << '/CMapName /Adobe-Identity-UCS def'
+        lines << '/CMapType 2 def'
+        lines << '1 begincodespacerange'
+        lines << '<0000> <FFFF>'
+        lines << 'endcodespacerange'
+        entries = gid_to_cp.map { |gid, cp| "<#{format('%04X', gid)}> <#{format('%04X', cp)}>" }
+        entries.each_slice(100) do |slice|
+          lines << "#{slice.length} beginbfchar"
+          slice.each { |e| lines << e }
+          lines << 'endbfchar'
+        end
+        lines << 'endcmap'
+        lines << 'CMapName currentdict /CMap defineresource pop'
+        lines << 'end'
+        lines << 'end'
+        lines.join("\n") + "\n"
+      end
+
+      def widths_array
+        return [] unless @subset_gid_to_cp
+        upem = head_units_per_em
+        hmtx = @fontisan_font.table('hmtx')
+        return [] unless hmtx
+        groups = {}
+        @subset_gid_to_cp.each do |subset_gid, cp|
+          orig_gid = @unicode_to_gid[cp]
+          next unless orig_gid
+          metric = hmtx.metric_for(orig_gid)
+          w = (metric && metric[:advance_width]) || 0
+          groups[subset_gid] = (w * 1000 / upem).to_i
+        end
+        result = []
+        sorted = groups.keys.sort
+        cur_s = nil
+        cur_w = []
+        sorted.each do |gid|
+          if cur_s.nil?
+            cur_s = gid
+            cur_w = [groups[gid]]
+          elsif gid == cur_s + cur_w.length
+            cur_w << groups[gid]
+          else
+            result << cur_s << cur_w
+            cur_s = gid
+            cur_w = [groups[gid]]
+          end
+        end
+        result << cur_s << cur_w if cur_s
+        result
+      end
+
+      def head_units_per_em
+        head = @fontisan_font.table('head')
+        head ? head.units_per_em : 1000
+      rescue StandardError
+        1000
+      end
+
+      def font_bbox
+        head = @fontisan_font.table('head')
+        return [0, 0, 1000, 1000] unless head
+        s = 1000.0 / head.units_per_em
+        [(head.x_min * s).to_i, (head.y_min * s).to_i, (head.x_max * s).to_i, (head.y_max * s).to_i]
+      rescue StandardError
+        [0, 0, 1000, 1000]
+      end
+
+      def ascent
+        hhea = @fontisan_font.table('hhea')
+        return 800 unless hhea
+        (hhea.ascender * 1000 / head_units_per_em).to_i
+      rescue StandardError
+        800
+      end
+
+      def descent
+        hhea = @fontisan_font.table('hhea')
+        return -200 unless hhea
+        (hhea.descender * 1000 / head_units_per_em).to_i
+      rescue StandardError
+        -200
+      end
+
+      def cap_height
+        os2 = @fontisan_font.table('OS/2')
+        return 700 unless os2
+        (os2.cap_height * 1000 / head_units_per_em).to_i
+      rescue StandardError
+        700
+      end
+    end
+  end
+end

data/lib/arrolio/font/manifest.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Font
+    # Declarative font configuration. Maps family names to variant
+    # file paths (regular, bold, italic, bold_italic) and provides
+    # fallback chain resolution. Replaces the flat +font_paths+
+    # hash on LayoutSpec with a richer structure.
+    #
+    # Manifest format (YAML):
+    #   families:
+    #     "Body Font":
+    #       regular: /path/to/times.ttf
+    #       bold: /path/to/timesbd.ttf
+    #       italic: /path/to/timesi.ttf
+    #       bold_italic: /path/to/timesbi.ttf
+    #   fallback: ["Fallback1", "Fallback2"]
+    class Manifest
+      attr_reader :families, :fallback_chain
+
+      # +families:+ Hash mapping family name (String) to a Hash of
+      #   variant → file path. Variants: :regular, :bold, :italic,
+      #   :bold_italic.
+      # +fallback_chain:+ Array of family names tried in order when
+      #   the primary family doesn't have a needed variant.
+      def initialize(families:, fallback_chain: [])
+        @families = normalize_families(families)
+        @fallback_chain = Array(fallback_chain).map(&:to_s)
+        freeze
+      end
+
+      # Resolves a font name + weight + style to a file path.
+      # Tries the primary family first, then the fallback chain.
+      # Returns nil if no path is found.
+      def resolve(font_name, weight: :regular, style: :regular)
+        variant = variant_key(weight, style)
+        path = lookup(@families[font_name.to_s], variant)
+        return path if path
+
+        @fallback_chain.each do |family|
+          path = lookup(@families[family], variant)
+          return path if path
+        end
+        nil
+      end
+
+      # Returns all (family, variant, path) triples as a flat hash
+      # suitable for the existing +font_paths+ API.
+      def to_flat_paths
+        result = {}
+        @families.each do |family, variants|
+          variants.each do |variant, path|
+            key = variant_name(family, variant)
+            result[key] = path if path && File.exist?(path)
+          end
+        end
+        result
+      end
+
+      # Factory: builds a Manifest from a YAML/Hash representation.
+      def self.from_hash(hash)
+        new(
+          families: hash.fetch('families', hash.fetch(:families, {})),
+          fallback_chain: hash.fetch('fallback', hash.fetch(:fallback_chain, []))
+        )
+      end
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          families == other.families &&
+          fallback_chain == other.fallback_chain
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, families, fallback_chain].hash
+      end
+
+      private
+
+      def normalize_families(raw)
+        raw.to_h.transform_keys(&:to_s).transform_values do |variants|
+          variants.to_h.transform_keys(&:to_sym)
+        end
+      end
+
+      def variant_key(weight, style)
+        is_bold = weight.to_s.downcase == 'bold'
+        is_italic = style.to_s.downcase == 'italic'
+        if is_bold && is_italic then :bold_italic
+        elsif is_bold then :bold
+        elsif is_italic then :italic
+        else :regular
+        end
+      end
+
+      def lookup(family_variants, variant)
+        return nil unless family_variants
+
+        family_variants[variant] || family_variants[:regular]
+      end
+
+      def variant_name(family, variant)
+        case variant
+        when :regular then family
+        when :bold then "#{family} Bold"
+        when :italic then "#{family} Italic"
+        when :bold_italic then "#{family} BoldItalic"
+        else family
+        end
+      end
+    end
+  end
+end

data/lib/arrolio/font/resolver.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module Arrolio
+  module Font
+    # Resolves font family names to absolute TTF paths using a
+    # configurable chain of resolvers. Replaces the absolute-path
+    # entries in `layout_spec.yml` with portable family-name
+    # declarations.
+    #
+    # Resolution order (first hit wins):
+    #   1. FontManifest (explicit mapping in the flavor)
+    #   2. font_paths from layout_spec (legacy explicit paths)
+    #   3. fontist manifest (if the +fontist+ gem is available at
+    #      runtime; otherwise this step is skipped silently)
+    #   4. PDF standard 14 fallback (e.g. "Helvetica" → built-in)
+    #
+    # Strict mode (strict: true) raises RenderError listing every
+    # unresolved required font; lenient mode silently produces nil
+    # entries and the renderer falls back to a default.
+    class Resolver
+      STANDARD_14 = [
+        'Helvetica', 'Helvetica-Bold', 'Helvetica-Oblique', 'Helvetica-BoldOblique',
+        'Times-Roman', 'Times-Bold', 'Times-Italic', 'Times-BoldItalic',
+        'Courier', 'Courier-Bold', 'Courier-Oblique', 'Courier-BoldOblique',
+        'Symbol', 'ZapfDingbats'
+      ].freeze
+
+      attr_reader :manifest, :font_paths, :use_fontist, :strict,
+                  :resolved, :unresolved
+
+      def initialize(manifest: nil, font_paths: {}, use_fontist: true,
+                     strict: false)
+        @manifest = manifest
+        @font_paths = font_paths.transform_keys(&:to_s)
+        @use_fontist = use_fontist
+        @strict = strict
+        @resolved = {}
+        @unresolved = []
+      end
+
+      # Resolve a single family name. Returns the absolute path (String)
+      # or nil if not found. Does NOT raise in strict mode — use
+      # +#resolve_all!+ for that.
+      def resolve(family_name)
+        return resolved[family_name.to_s] if resolved.key?(family_name.to_s)
+
+        path = lookup(family_name.to_s)
+        resolved[family_name.to_s] = path
+        track_unresolved(family_name.to_s, path)
+        path
+      end
+
+      # Resolve every family declared by the manifest or font_paths.
+      # In strict mode, raises RenderError with the full unresolved
+      # list. Returns a Hash { family => path } otherwise.
+      def resolve_all!
+        families_to_resolve.each { |family| resolve(family) }
+        return resolved unless strict && unresolved.any?
+
+        raise ::Arrolio::RenderError.new(
+          "strict mode: unresolved required fonts: #{unresolved.join(', ')}",
+          missing_fonts: unresolved.map { |name| [name, nil] }
+        )
+      end
+
+      def self.from_layout_spec(layout_spec, strict: false)
+        new(
+          manifest: layout_font_manifest(layout_spec),
+          font_paths: layout_spec.font_paths,
+          use_fontist: true,
+          strict: strict
+        )
+      end
+
+      def self.standard_14?(family_name)
+        STANDARD_14.include?(family_name.to_s)
+      end
+
+      private
+
+      def lookup(family)
+        return manifest_path(family) if @manifest&.path_for(family)
+        return @font_paths[family] if @font_paths.key?(family) && File.exist?(@font_paths[family].to_s)
+
+        fontist_path = fontist_lookup(family)
+        return fontist_path if fontist_path
+
+        STANDARD_14.include?(family) ? family : nil
+      end
+
+      def manifest_path(family)
+        path = @manifest.path_for(family)
+        path && File.exist?(path) ? path : nil
+      end
+
+      def fontist_lookup(family)
+        return nil unless @use_fontist
+        return nil unless fontist_available?
+
+        fontist_manifest = ::Fontist.manifest
+        fontist_manifest.install(family) unless fontist_manifest.any? { |e| e.name == family }
+        ::Fontist::Font.find(family).paths.first
+      rescue StandardError
+        nil
+      end
+
+      def fontist_available?
+        Object.const_defined?(:Fontist)
+      end
+
+      def families_to_resolve
+        required = @manifest ? @manifest.required_families : []
+        (required + @font_paths.keys).uniq
+      end
+
+      def track_unresolved(family, path)
+        return if path
+
+        is_standard = self.class.standard_14?(family)
+        @unresolved << family unless is_standard
+      end
+
+      def self.layout_font_manifest(layout_spec)
+        return nil unless layout_spec.is_a?(::Arrolio::LayoutSpec)
+
+        config = layout_spec.font_manifest_config
+        return nil unless config && config['families']
+
+        FontManifest.new(config['families'], config.fetch('fallback', []))
+      end
+      private_class_method :layout_font_manifest
+    end
+
+    # Internal lightweight view over a `font_manifest:` block in
+    # layout_spec.yml. Maps family names to variant paths and exposes
+    # the required-family list.
+    class FontManifest
+      attr_reader :families, :fallback
+
+      def initialize(families, fallback = [])
+        @families = families.transform_keys(&:to_s)
+        @fallback = Array(fallback)
+        freeze
+      end
+
+      def path_for(family)
+        entry = @families[family.to_s]
+        return nil unless entry
+
+        path = entry['regular'] || entry[:regular]
+        path&.to_s
+      end
+
+      def required_families
+        @families.keys
+      end
+    end
+  end
+end