arrolio 0.1.0

data/lib/arrolio/content/table.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Content
+    class Table
+      attr_reader :header, :body, :column_widths, :style_id, :id
+
+      def initialize(header: [], body: [], column_widths: nil,
+                     style_id: :table, id: nil)
+        @header = header.map { |row| coerce_row(row) }.freeze
+        @body = body.map { |row| coerce_row(row) }.freeze
+        @column_widths = column_widths&.map(&:to_f)&.freeze
+        @style_id = style_id.to_sym
+        @id = id
+        freeze
+      end
+
+      def rows
+        @header + @body
+      end
+
+      def column_count
+        rows.map { |r| r.cells.length }.max || 0
+      end
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          header == other.header &&
+          body == other.body &&
+          column_widths == other.column_widths &&
+          style_id == other.style_id &&
+          id == other.id
+      end
+
+      alias eql? ==
+
+      def hash
+        [self.class, header, body, column_widths, style_id, id].hash
+      end
+
+      private
+
+      def coerce_row(row)
+        case row
+        when Row then row
+        when Array then Row.new(row.map { |c| c.is_a?(Cell) ? c : Cell.new(c) })
+        else
+          raise ContentError, "Table row must be an Array or Table::Row (got #{row.class})"
+        end
+      end
+    end
+
+    class Table::Row
+      include Enumerable
+
+      attr_reader :cells
+
+      def initialize(cells)
+        @cells = Array(cells).freeze
+        freeze
+      end
+
+      def each(&block)
+        @cells.each(&block)
+      end
+
+      def length
+        @cells.length
+      end
+
+      def ==(other)
+        other.is_a?(self.class) && cells == other.cells
+      end
+
+      alias eql? ==
+
+      def hash
+        [self.class, cells].hash
+      end
+    end
+
+    class Table::Cell
+      attr_reader :content, :colspan, :rowspan, :style_id, :align
+
+      def initialize(content = [], colspan: 1, rowspan: 1,
+                     style_id: :table_cell, align: nil)
+        @content = Array(content).freeze
+        @colspan = colspan.to_i
+        @rowspan = rowspan.to_i
+        @style_id = style_id.to_sym
+        @align = align
+        freeze
+      end
+
+      def text
+        @content.map do |node|
+          node.is_a?(Paragraph) ? node.text : node.to_s
+        end.join(' ')
+      end
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          content == other.content &&
+          colspan == other.colspan &&
+          rowspan == other.rowspan &&
+          style_id == other.style_id &&
+          align == other.align
+      end
+
+      alias eql? ==
+
+      def hash
+        [self.class, content, colspan, rowspan, style_id, align].hash
+      end
+    end
+  end
+end

data/lib/arrolio/content/term_entry.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Content
+    # A dictionary term entry: optional number, preferred term text,
+    # definition Paragraphs, and optional source citation. Maps to
+    # the `<term>` element in standoc vocabulary. Renders as a
+    # hanging-indent group in the flow builder.
+    class TermEntry
+      attr_reader :number, :preferred, :definition, :source, :id, :style_id
+
+      def initialize(number: nil, preferred: nil, definition: [],
+                     source: nil, id: nil, style_id: :term)
+        @number = number&.to_s
+        @preferred = preferred
+        @definition = Array(definition).freeze
+        @source = source
+        @id = id&.to_s
+        @style_id = style_id.to_sym
+        freeze
+      end
+
+      def empty?
+        @preferred.nil? && @definition.empty? && @number.nil?
+      end
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          number == other.number &&
+          preferred == other.preferred &&
+          definition == other.definition &&
+          source == other.source &&
+          id == other.id &&
+          style_id == other.style_id
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, number, preferred, definition, source, id, style_id].hash
+      end
+    end
+  end
+end

data/lib/arrolio/content.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Content
+    autoload :Document, 'arrolio/content/document'
+    autoload :Section, 'arrolio/content/section'
+    autoload :Paragraph, 'arrolio/content/paragraph'
+    autoload :InlineRun, 'arrolio/content/inline_run'
+    autoload :Heading, 'arrolio/content/heading'
+    autoload :Hyperlink, 'arrolio/content/hyperlink'
+    autoload :Formula, 'arrolio/content/formula'
+    autoload :Preformatted, 'arrolio/content/preformatted'
+    autoload :PageBreak, 'arrolio/content/page_break'
+    autoload :Footnote, 'arrolio/content/footnote'
+    autoload :IndexEntry, 'arrolio/content/index_entry'
+    autoload :FormField, 'arrolio/content/form_field'
+    autoload :Table, 'arrolio/content/table'
+    autoload :List, 'arrolio/content/list'
+    autoload :Image, 'arrolio/content/image'
+    autoload :Builder, 'arrolio/content/builder'
+    autoload :Note, 'arrolio/content/note'
+    autoload :Example, 'arrolio/content/example'
+    autoload :TermEntry, 'arrolio/content/term_entry'
+    autoload :FigureGroup, 'arrolio/content/figure_group'
+    autoload :BibliographyItem, 'arrolio/content/bibliography_item'
+  end
+end

data/lib/arrolio/data_dir.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module DataDir
+    DELIMITER = '/'
+
+    class << self
+      def root
+        File.expand_path('../../data/arrolio', __dir__)
+      end
+
+      def resolve(*segments)
+        path = File.join(root, *segments)
+        raise Arrolio::Error, "missing data file: #{segments.join(DELIMITER)}" unless File.exist?(path)
+
+        path
+      end
+
+      def afm(name)
+        File.join(root, 'afm', "#{name}.afm")
+      end
+
+      def glyphlist
+        File.join(root, 'glyphlist.txt')
+      end
+    end
+  end
+end

data/lib/arrolio/engine/cross_reference_registry.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Engine
+    # Collects heading → page-number mappings during layout and
+    # resolves cross-references for ToC, page citations, and
+    # internal links. The engine records entries during pass 1;
+    # after layout is complete, the registry provides resolved
+    # references for deferred rendering (e.g., ToC page that
+    # appears at the front of the document but needs page numbers
+    # from the body).
+    #
+    # This implements the "deferred rendering" pattern: the ToC
+    # section is rendered last (from the registry's resolved data)
+    # but appears first in the document. The engine's existing
+    # FlowContext#heading_entries feeds into this registry.
+    class CrossReferenceRegistry
+      Entry = Struct.new(:id, :number, :title, :level, :page_number,
+                         keyword_init: true)
+
+      attr_reader :entries
+
+      def initialize
+        @entries = []
+        @by_id = {}
+      end
+
+      # Records a heading during layout pass 1.
+      def record(id:, number:, title:, level:, page_number:)
+        entry = Entry.new(
+          id: id, number: number, title: title,
+          level: level, page_number: page_number
+        )
+        @entries << entry
+        @by_id[id.to_s] = entry if id
+        entry
+      end
+
+      # Resolves a cross-reference target to a page number.
+      # Returns nil if the target hasn't been recorded.
+      def page_number_for(target_id)
+        @by_id[target_id.to_s]&.page_number
+      end
+
+      # Resolves a cross-reference target to its full entry.
+      def entry_for(target_id)
+        @by_id[target_id.to_s]
+      end
+
+      # All entries, suitable for ToC generation. Entries are
+      # in document order (the order they were recorded).
+      # Pass +max_level:+ to filter to a maximum heading level
+      # (e.g., only levels 1-2 for a compact ToC).
+      def toc_entries(max_level: nil)
+        return @entries.dup if max_level.nil?
+
+        @entries.select { |e| e.level <= max_level }
+      end
+
+      def empty?
+        @entries.empty?
+      end
+
+      def count
+        @entries.length
+      end
+    end
+  end
+end

data/lib/arrolio/engine/paged.rb

@@ -0,0 +1,186 @@
+# frozen_string_literal: true
+
+module Arrolio
+  module Engine
+    # Two-pass page-flow driver.
+    class Paged
+      attr_reader :layout_spec, :flowables, :pages, :context
+
+      def initialize(layout_spec:, flowables:)
+        @layout_spec = layout_spec
+        @flowables = flowables
+        @pages = []
+      end
+
+      def layout
+        @pages = []
+        @page_count_opened = 0
+        @footnote_page_map = {} # footnote.id / marker -> first page_number
+        context = FlowContext.new(layout_spec: @layout_spec, page_number: 1)
+        pending = @flowables.dup
+        page_state = open_page(context)
+
+        until pending.empty?
+          flowable = pending.shift
+
+          if flowable.is_a?(Flowables::PageSequenceStart)
+            @current_role = flowable.role
+            @current_header = flowable.header_template
+            @current_footer = flowable.footer_template
+            @current_header_align = flowable.header_align
+            @current_footer_align = flowable.footer_align
+            unless page_state.fresh && page_state.body_boxes.empty?
+              page_state = open_page(context)
+            end
+            page_state.role = @current_role
+            page_state.header = @current_header
+            page_state.footer = @current_footer
+            page_state.header_align = @current_header_align
+            page_state.footer_align = @current_footer_align
+            next
+          end
+
+          if flowable.is_a?(Flowables::PageBreak)
+            page_state = open_page(context)
+            next
+          end
+
+          # Footnote anchors: record on the current page without
+          # consuming frame space (the flowable has zero height).
+          if flowable.is_a?(Flowables::FootnoteMarkerFlowable)
+            key = flowable.footnote.id || flowable.footnote.marker
+            @footnote_page_map[key] ||= page_state.page_number
+            page_state.footnotes << flowable.footnote unless page_state.footnotes.include?(flowable.footnote)
+            next
+          end
+
+          page_state = open_page(context) if flowable.page_break_before? && @pages.any? && !page_state.fresh
+          page_state = open_page(context) if page_state.frame.full?
+
+          width = page_state.frame.width
+          if flowable.keep_together? &&
+             flowable.height(width, context) > page_state.frame.remaining_height &&
+             flowable.height(width, context) <= page_state.frame.height
+            page_state = open_page(context)
+          end
+
+          # Record heading entries for ToC + outline building.
+          if flowable.is_a?(Flowables::HeadingFlowable)
+            context.record_heading(number: flowable.number,
+                                   title: flowable.title,
+                                   level: flowable.level,
+                                   page_number: page_state.page_number,
+                                   id: flowable.id)
+          end
+
+          page_state.fresh = false
+          page_state = place(page_state, flowable, context, pending)
+        end
+
+        @context = context
+        context.page_count = @pages.length
+        finalize_pages
+        @pages
+      end
+
+      private
+
+      def place(page_state, flowable, context, pending)
+        frame = page_state.frame
+        width = frame.width
+        natural = flowable.height(width, context)
+
+        if natural <= frame.remaining_height
+          emit(page_state, flowable, context)
+        elsif flowable.splittable?
+          head, tail = flowable.split(width, frame.remaining_height, context)
+          if head
+            emit(page_state, head, context)
+            pending.unshift(tail) if tail
+          else
+            return page_state unless frame.full?
+
+            new_state = open_page(context)
+            place(new_state, flowable, context, pending)
+          end
+        else
+          emit(page_state, flowable, context)
+        end
+        page_state
+      end
+
+      def emit(page_state, flowable, context)
+        frame = page_state.frame
+        x = frame.x
+        y_top = frame.cursor_y
+        boxes, consumed = flowable.emit(x, y_top, frame.width, context)
+        page_state.body_boxes.concat(boxes)
+        frame.consume!(consumed)
+      end
+
+      def open_page(context)
+        template = @layout_spec.page_template
+        body = template.body_region
+        @page_count_opened = (@page_count_opened || 0) + 1
+        page_number = @page_count_opened
+
+        frame = Frame.new(x: body.x, y: body.y,
+                          width: body.width, height: body.height)
+        context.page_number = page_number
+
+        state = OpenPage.new(
+          template: template,
+          page_number: page_number,
+          frame: frame,
+          body_boxes: [],
+          fresh: true,
+          role: @current_role || :body,
+          header: @current_header,
+          footer: @current_footer,
+          header_align: @current_header_align || :right,
+          footer_align: @current_footer_align || :center,
+          footnotes: []
+        )
+        @pages << state
+        state
+      end
+
+      def finalize_pages
+        total = @pages.length
+        built = @pages.map do |state|
+          template = state.template
+          body = template.body_region
+          region = Output::Region.new(
+            name: :body,
+            x: body.x, y: body.y, width: body.width, height: body.height,
+            placed_boxes: state.body_boxes
+          )
+          Output::Page.new(
+            number: state.page_number,
+            template_name: template.name,
+            template_role: state.role,
+            page_size: template.page_size,
+            regions: { body: region },
+            header_text: format_text(state.header, state.page_number, total),
+            footer_text: format_text(state.footer, state.page_number, total),
+            header_align: state.header_align,
+            footer_align: state.footer_align,
+            footnotes: state.footnotes
+          )
+        end
+        @pages.replace(built)
+      end
+
+      def format_text(template_text, current, _total)
+        return nil if template_text.nil?
+
+        template_text.to_s.gsub('%d', current.to_s)
+      end
+    end
+
+    OpenPage = Struct.new(:template, :page_number, :frame, :body_boxes,
+                          :fresh, :role, :header, :footer,
+                          :header_align, :footer_align, :footnotes,
+                          keyword_init: true)
+  end
+end

data/lib/arrolio/engine.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+# Arrolio::Engine — page-flow layout drivers.
+module Arrolio
+  module Engine
+    autoload :Paged, 'arrolio/engine/paged'
+    autoload :CrossReferenceRegistry, 'arrolio/engine/cross_reference_registry'
+  end
+end

data/lib/arrolio/error.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Arrolio
+  # Base class for every Arrolio failure mode. Subclasses carry
+  # typed metadata that callers can inspect (e.g. +page_number+ on
+  # a +LayoutError+, +oid+ on a +RenderError+).
+  class Error < StandardError; end
+
+  # Raised by Engine::* when a layout pass fails (overflow that
+  # can't be resolved, broken cross-reference, missing template).
+  class LayoutError < Error
+    attr_reader :page_number, :template_name
+
+    def initialize(message, page_number: nil, template_name: nil)
+      @page_number = page_number
+      @template_name = template_name
+      super(message)
+    end
+  end
+
+  # Raised by Renderer::* when the render pass fails.
+  class RenderError < Error
+    attr_reader :missing_fonts
+
+    def initialize(message, missing_fonts: nil)
+      @missing_fonts = missing_fonts
+      super(message)
+    end
+  end
+
+  # Raised when the content tree violates Arrolio's content
+  # contract (e.g. a Section with a non-String title, or a
+  # Paragraph with malformed InlineRuns).
+  class ContentError < Error
+    attr_reader :node
+
+    def initialize(message, node: nil)
+      @node = node
+      super(message)
+    end
+  end
+
+  # Raised when a LayoutSpec is missing required entries or has
+  # invalid values (unknown page-template name, unresolvable style
+  # reference, etc.).
+  class LayoutSpecError < Error
+    attr_reader :spec_field
+
+    def initialize(message, spec_field: nil)
+      @spec_field = spec_field
+      super(message)
+    end
+  end
+
+  # Raised when a flavor is missing required files (manifest.yml,
+  # layout_spec.yml, etc.) or has malformed configuration. Carries
+  # the flavor directory and/or manifest path for diagnosis.
+  class FlavorError < Error
+    attr_reader :flavor_dir, :manifest_path, :missing_fields, :missing_role
+
+    def initialize(message, flavor_dir: nil, manifest_path: nil,
+                   missing_fields: nil, missing_role: nil)
+      @flavor_dir = flavor_dir
+      @manifest_path = manifest_path
+      @missing_fields = missing_fields
+      @missing_role = missing_role
+      super(message)
+    end
+  end
+end

data/lib/arrolio/flavor/manifest.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'yaml'
+require 'arrolio/error'
+
+module Arrolio
+  module Flavor
+    # Typed view over a flavor's manifest.yml. Declares the flavor's
+    # name, version, upstream XSL, required/optional fonts, and the
+    # paths to its three config files. Validates the manifest at load
+    # time so broken flavors fail loudly with `Arrolio::FlavorError`.
+    class Manifest
+      REQUIRED_FIELDS = ['name', 'version', 'config_files'].freeze
+
+      attr_reader :path, :name, :version, :description, :upstream,
+                  :doctypes, :required_fonts, :optional_fonts,
+                  :config_files
+
+      def self.load(flavor_dir)
+        manifest_path = File.join(flavor_dir, 'manifest.yml')
+        unless File.exist?(manifest_path)
+          raise ::Arrolio::FlavorError.new(
+            "manifest.yml not found in #{flavor_dir}",
+            flavor_dir: flavor_dir
+          )
+        end
+
+        data = YAML.safe_load_file(manifest_path, aliases: true)
+        unless data.is_a?(Hash)
+          raise ::Arrolio::FlavorError.new(
+            "manifest.yml at #{manifest_path} is not a YAML mapping",
+            flavor_dir: flavor_dir
+          )
+        end
+
+        validate_required_fields!(data, manifest_path)
+        validate_config_files!(data, manifest_path, flavor_dir)
+
+        new(manifest_path, data)
+      end
+
+      def initialize(path, data)
+        @path = path
+        @name = data.fetch('name')
+        @version = data.fetch('version')
+        @description = data['description']
+        @upstream = data['upstream'] || {}
+        @doctypes = data['doctypes'] || []
+        fonts = data['fonts'] || {}
+        @required_fonts = fonts['required'] || []
+        @optional_fonts = fonts['optional'] || []
+        @config_files = data.fetch('config_files')
+        freeze
+      end
+
+      def config_path_for(role, flavor_dir = File.dirname(@path))
+        file = config_files[role.to_s] || config_files[role.to_sym]
+        return nil unless file
+
+        File.join(flavor_dir, file)
+      end
+
+      def ==(other)
+        other.is_a?(self.class) &&
+          path == other.path &&
+          name == other.name &&
+          version == other.version &&
+          description == other.description &&
+          doctypes == other.doctypes &&
+          required_fonts == other.required_fonts &&
+          optional_fonts == other.optional_fonts &&
+          config_files == other.config_files
+      end
+
+      alias eql? ==
+
+      def hash
+        [self.class, path, name, version, config_files].hash
+      end
+
+      def self.validate_required_fields!(data, manifest_path)
+        missing = REQUIRED_FIELDS.reject { |field| data.key?(field) }
+        return if missing.empty?
+
+        raise ::Arrolio::FlavorError.new(
+          "manifest at #{manifest_path} is missing required fields: #{missing.inspect}",
+          manifest_path: manifest_path, missing_fields: missing
+        )
+      end
+      private_class_method :validate_required_fields!
+
+      def self.validate_config_files!(data, manifest_path, flavor_dir)
+        config_files = data['config_files']
+        return unless config_files.is_a?(Hash)
+
+        ['layout_spec', 'adapter_rules', 'flow_rules'].each do |role|
+          filename = config_files[role]
+          next unless filename
+          next if File.exist?(File.join(flavor_dir, filename))
+
+          raise ::Arrolio::FlavorError.new(
+            "manifest at #{manifest_path} references #{role}=#{filename}, " \
+            'but the file does not exist',
+            manifest_path: manifest_path, missing_role: role
+          )
+        end
+      end
+      private_class_method :validate_config_files!
+    end
+  end
+end