idml 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46b15814f26a45f5df5c3170df66846ff831727ce3dcf4b7ebe1b1c0377d8c0e
-  data.tar.gz: d4041eacffab33e437330116d3b1268577b6ad8afbc0f2ee4cc1e015c07ec3a4
+  metadata.gz: 0f40610210789018b1fbe0625c1541cfe3611169d0004543891ebb9efd6c74ea
+  data.tar.gz: 6998d5c66bd56eed147dfb88d60a602be32fee2adb9b9fa9f08413af4cb2103f
 SHA512:
-  metadata.gz: 45e7dcb9c7bad255b0bc4fbe2e97e741c7a1b1ff52a6bf899ffdffdf838f310780c1e90832b54f9cbd5a0044b7b908f9c3791fd8274b4272fe1f40506b0ce793
-  data.tar.gz: b928db59ed416b59431bb638e1d86630488247dff7a3aaa6361954029920d3cb053095fdba28d7d7a00ec386e1b7f6153c89a7478135ad44523a3cb000cba840
+  metadata.gz: 02c03bf2c81b2ebb81b04ae4b413b25d484adf806b1d8c7c0768e557323bca7c30de46d5174cff27c90e2275f6f89070ac5f981df567cb20867e5c17382b0c42
+  data.tar.gz: 642103e8e48d2b5b52a4b669d7e09329f5706e4f165f4da8de6df51ef38125686ca75db28de194a974f94cdc9273a193c76a653bf8727b3a16f6b5ac2a9c5f3c

data/Gemfile

@@ -6,7 +6,7 @@ gemspec
 
 gem "logger"
 gem "lutaml-model", "~> 0.8.0"
-gem "pdfrb", github: "claricle/pdfrb", ref: "629c72a"
+gem "pdfrb", "~> 0.7"
 gem "rake"
 gem "rspec"
 gem "rubocop"

data/TODO.pdf/100-character-level-styling.md

@@ -1,6 +1,16 @@
 # TODO PDF 100: Character-level styling (underline, strikethrough, caps, color)
 
-## Status: OPEN — gap identified in 2026-08-08 audit
+## Status: DONE — new `Render::CharacterStyle` helper applies
+per-run fill color, draws underline / strike-through rules, and
+handles Capitalization (AllCaps/SmallCaps → uppercase) and Position
+(Superscript/Subscript → shrunk font + baseline offset).
+TextFrameRenderer.emit_line wraps canvas.text via CharacterStyle.
+StyledRun extended with underline_offset/weight, strike_through_offset/weight
+attrs from CSR.
+
+Open follow-ups (lower priority): glyph horizontal/vertical scaling
+(needs pdfrb text-matrix support), tracking (needs Shaper-level
+width adjustment), text stroke outline.
 
 ## Problem
 

data/TODO.pdf/104-table-schema-completion.md

@@ -1,6 +1,11 @@
 # TODO PDF 104: Schema-faithful Table model completion
 
-## Status: OPEN — gap identified in 2026-08-08 audit
+## Status: PARTIAL — added the rendering-relevant subset (column_count,
+single_column_width, header/body/footer row counts, table_direction,
+outer-border strokes). The remaining ~150 schema attributes (alternating
+stroke rows, column rules, table-flavor bits) aren't needed for
+rendering and would be pure model bloat. Add incrementally as use
+cases demand.
 
 ## Problem
 

data/TODO.pdf/105-whole-package-round-trip.md

@@ -1,6 +1,9 @@
 # TODO PDF 105: Whole-package round-trip suite (byte-equivalent)
 
-## Status: OPEN — gap identified in 2026-08-08 audit
+## Status: DONE — `spec/idml/round_trip_all_fixtures_spec.rb` already
+runs byte-equivalent round-trip for every fixture .idml (28 examples,
+all passing). `spec/idml/package_spec.rb:140` verifies the mimetype
+entry is stored and first.
 
 ## Problem
 

data/TODO.pdf/94-text-frame-vertical-layout.md

@@ -1,6 +1,10 @@
 # TODO PDF 94: TextFrameRenderer should delegate to VerticalLayout
 
-## Status: OPEN — gap identified in 2026-08-08 audit
+## Status: DONE — VerticalLayout refactored to block-style API
+(`layout_block` returns positioned lines + next cursor y);
+TextFrameRenderer now uses StyleResolver.extract_paragraphs +
+VerticalLayout.layout_block for proper vertical stacking across
+paragraphs and runs.
 
 ## Problem
 

data/TODO.pdf/95-paragraph-spacing-indents.md

@@ -1,6 +1,7 @@
 # TODO PDF 95: Paragraph spacing and indents (SpaceBefore, SpaceAfter, FirstLineIndent)
 
-## Status: OPEN — gap identified in 2026-08-08 audit
+## Status: DONE — Paragraph struct carries these from PSR; renderer
+passes them to VerticalLayout.layout_block.
 
 ## Problem
 

data/TODO.pdf/96-text-frame-insets-actual.md

@@ -1,6 +1,8 @@
 # TODO PDF 96: TextFramePreference insets honored in layout
 
-## Status: OPEN — gap identified in 2026-08-08 audit
+## Status: DONE — layout_frame helper reads TextFramePreference
+insets and passes them to the Frame struct; VerticalLayout honors
+them in positioning and wrap_width.
 
 ## Problem
 

data/TODO.pdf/97-table-cell-rendering-fidelity.md

@@ -1,6 +1,9 @@
 # TODO PDF 97: Table cell rendering — fill, stroke, insets, vertical justification
 
-## Status: OPEN — gap identified in 2026-08-08 audit
+## Status: DONE — cell fill_color renders as background; per-cell
+TextTopInset/Left/Bottom/Right honored (was hardcoded 4.0);
+VerticalJustification positions text Top/Bottom/Center; per-cell
+PSR walks typed runs with their own font/size.
 
 ## Problem
 

data/TODO.pdf/98-rowspan-columnspan.md

@@ -1,6 +1,9 @@
 # TODO PDF 98: RowSpan / ColumnSpan (merged cells) in TableRenderer
 
-## Status: OPEN — gap identified in 2026-08-08 audit
+## Status: DONE — SchemaLayout reads cell.column_span and cell.row_span,
+multiplies width/height by the span, tracks a coverage set, and skips
+positions covered by a spanning cell. Spanning cell renders once at
+its top-left corner.
 
 ## Problem
 

data/TODO.pdf/99-table-column-widths.md

@@ -1,6 +1,10 @@
 # TODO PDF 99: Table column widths from ColumnAttributes
 
-## Status: OPEN — gap identified in 2026-08-08 audit
+## Status: DONE — Table now models `column_count` and
+`single_column_width`; SchemaLayout uses SingleColumnWidth when
+declared, else falls back to even division. (IDML has no separate
+ColumnAttributes element — column widths live on Table directly
+when uniform.)
 
 ## Problem
 

data/idml.gemspec

@@ -31,7 +31,7 @@ Gem::Specification.new do |spec|
   spec.add_dependency "bigdecimal"
   spec.add_dependency "logger"
   spec.add_dependency "lutaml-model", "~> 0.8.18"
-  spec.add_dependency "pdfrb", "~> 0.6"
+  spec.add_dependency "pdfrb", "~> 0.7"
   spec.add_dependency "rubyzip"
   spec.add_dependency "thor"
 

data/lib/idml/elements/table.rb

@@ -2,10 +2,16 @@
 
 module Idml
   module Elements
-    # `<Table>` — a table page item. Carries geometry attributes and a
-    # collection of TableRow children. The table's width and height are
-    # typically derived from PathPointArray anchors, but rendered here
-    # using the ItemTransform + a bounding-box approximation.
+    # `<Table>` — a table page item. Carries geometry, body/header
+    # row counts, column layout, and border styling. Two child
+    # collections hold the table's content:
+    #
+    # - `row` — schema-faithful `<Row>` siblings (real IDML).
+    # - `cell` — schema-faithful `<Cell>` siblings (real IDML).
+    # - `table_row` — legacy nested `<TableRow><TableCell>` form
+    #   (synthetic test fixture only; see TODO 84).
+    #
+    # The renderer auto-detects which layout is present.
     class Table < Lutaml::Model::Serializable
       attribute :self_attr, :string
       attribute :name, :string
@@ -15,6 +21,28 @@ module Idml
       attribute :fill_color, :string
       attribute :stroke_color, :string
       attribute :stroke_weight, :float
+
+      # Schema-faithful layout attributes (from Table_Object in
+      # Stories/Story.rnc). The renderer consults these to compute
+      # column widths and to clip body/header/footer regions.
+      attribute :header_row_count, :integer
+      attribute :footer_row_count, :integer
+      attribute :body_row_count, :integer
+      attribute :column_count, :integer
+      attribute :single_column_width, :float
+      attribute :table_direction, :string
+
+      # Outer-border strokes (TopBorderStrokeWeight, etc.). Useful
+      # when the renderer draws the table's bounding rectangle.
+      attribute :top_border_stroke_weight, :float
+      attribute :top_border_stroke_color, :string
+      attribute :left_border_stroke_weight, :float
+      attribute :left_border_stroke_color, :string
+      attribute :bottom_border_stroke_weight, :float
+      attribute :bottom_border_stroke_color, :string
+      attribute :right_border_stroke_weight, :float
+      attribute :right_border_stroke_color, :string
+
       attribute :table_row, Idml::Elements::TableRow, collection: true
       attribute :cell, Idml::Elements::Cell, collection: true
       attribute :row, Idml::Elements::Row, collection: true
@@ -30,6 +58,22 @@ module Idml
         map_attribute "FillColor", to: :fill_color
         map_attribute "StrokeColor", to: :stroke_color
         map_attribute "StrokeWeight", to: :stroke_weight
+        map_attribute "HeaderRowCount", to: :header_row_count
+        map_attribute "FooterRowCount", to: :footer_row_count
+        map_attribute "BodyRowCount", to: :body_row_count
+        map_attribute "ColumnCount", to: :column_count
+        map_attribute "SingleColumnWidth", to: :single_column_width
+        map_attribute "TableDirection", to: :table_direction
+        map_attribute "TopBorderStrokeWeight", to: :top_border_stroke_weight
+        map_attribute "TopBorderStrokeColor", to: :top_border_stroke_color
+        map_attribute "LeftBorderStrokeWeight", to: :left_border_stroke_weight
+        map_attribute "LeftBorderStrokeColor", to: :left_border_stroke_color
+        map_attribute "BottomBorderStrokeWeight",
+                      to: :bottom_border_stroke_weight
+        map_attribute "BottomBorderStrokeColor",
+                      to: :bottom_border_stroke_color
+        map_attribute "RightBorderStrokeWeight", to: :right_border_stroke_weight
+        map_attribute "RightBorderStrokeColor", to: :right_border_stroke_color
         map_element "TableRow", to: :table_row
         map_element "Cell", to: :cell
         map_element "Row", to: :row

data/lib/idml/render/character_style.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # Applies character-level styling from a `StyleResolver::StyledRun`
+    # around a text-emitting block. Centralizes the IDML → PDF mapping
+    # for run-level visual properties (text color, underline rule,
+    # strike-through rule, capitalization, super/subscript position).
+    #
+    # Used by `TextFrameRenderer` so character-level effects live in
+    # one place (DRY). The block typically calls `canvas.text` (or
+    # `canvas.text_rich`); this helper sets the surrounding graphics
+    # state and emits the rule lines after the block returns.
+    module CharacterStyle
+      UNDERLINE_THICKNESS_FACTOR = 0.05
+      UNDERLINE_DROP_FACTOR = 0.10
+      STRIKE_THICKNESS_FACTOR = 0.05
+      STRIKE_RISE_FACTOR = 0.25
+
+      # Yields with the run's fill color applied, then draws underline
+      # and/or strike-through rules above/below the text baseline.
+      # `x`, `y`, `width`, `size` describe the line's geometry so the
+      # rules can be positioned correctly.
+      def self.apply(canvas, run, context, x:, y:, width:, size:)
+        apply_fill_color(canvas, run, context)
+        yield
+        draw_underline(canvas, run, x, y, width, size)
+        draw_strike_through(canvas, run, x, y, width, size)
+      end
+
+      # Transforms the text per the CSR's Capitalization attribute.
+      # AllCaps/SmallCaps → uppercase (true small-caps would require
+      # an OpenType feature; deferred). Other values pass through.
+      def self.transform_text(text, capitalization)
+        return text unless %w[AllCaps SmallCaps].include?(capitalization)
+
+        text.upcase
+      end
+
+      # Returns `[font_size, baseline_offset]` for the CSR's Position
+      # attribute. Superscript/subscript shrink the font and shift
+      # the baseline. Normal / nil returns the size unchanged.
+      def self.position_scale(position, font_size)
+        case position
+        when "Superscript" then [font_size * 0.583, font_size * 0.333]
+        when "Subscript" then [font_size * 0.583, -font_size * 0.0833]
+        else [font_size, 0.0]
+        end
+      end
+
+      def self.apply_fill_color(canvas, run, context)
+        return unless run.fill_color
+        return if run.fill_color == "Color/None"
+
+        color = context.color_resolver&.resolve(run.fill_color)
+        return unless color
+
+        canvas.fill_color(ColorHelper.to_canvas(color))
+      end
+      private_class_method :apply_fill_color
+
+      def self.draw_underline(canvas, run, x, y, width, size)
+        return unless run.underline
+
+        thickness = rule_thickness(run.underline_weight, size,
+                                   UNDERLINE_THICKNESS_FACTOR)
+        drop = rule_offset(run.underline_offset, size,
+                           UNDERLINE_DROP_FACTOR)
+        canvas.rectangle(x, y - drop, width, thickness)
+        canvas.fill
+      end
+      private_class_method :draw_underline
+
+      def self.draw_strike_through(canvas, run, x, y, width, size)
+        return unless run.strike_thru
+
+        thickness = rule_thickness(run.strike_through_weight, size,
+                                   STRIKE_THICKNESS_FACTOR)
+        rise = rule_offset(run.strike_through_offset, size,
+                           STRIKE_RISE_FACTOR)
+        canvas.rectangle(x, y + rise - thickness, width, thickness)
+        canvas.fill
+      end
+      private_class_method :draw_strike_through
+
+      def self.rule_thickness(declared, size, factor)
+        declared&.positive? ? declared : (size * factor)
+      end
+      private_class_method :rule_thickness
+
+      def self.rule_offset(declared, size, factor)
+        return size * factor unless declared
+        return size * factor if declared.zero?
+
+        declared
+      end
+      private_class_method :rule_offset
+    end
+  end
+end

data/lib/idml/render/renderers/table_renderer.rb

@@ -4,9 +4,8 @@ module Idml
   module Render
     module Renderers
       # Renders an IDML Table. Draws the cell grid via rectangle
-      # ops, then renders inline text in each cell via
-      # `canvas.text_rich`. Cells with no text render as empty
-      # rectangles.
+      # ops, then renders inline text in each cell. Cells with no
+      # text render as empty rectangles.
       #
       # Two table layouts are supported:
       #
@@ -19,9 +18,20 @@ module Idml
       #      `table_cell` collection. Nested structure.
       #
       # The renderer auto-detects which layout is present.
+      #
+      # Honors per-cell:
+      # - `fill_color` / `fill_tint` — background fill before stroke.
+      # - `top_inset` / `left_inset` / `bottom_inset` / `right_inset`
+      #   — text insets (replaces fixed `INSET = 4.0`).
+      # - `vertical_justification` — Top / Center / Bottom / Justify.
+      # - `paragraph_style_range` → typed runs (per-run font + size).
+      #
+      # Honors per-table:
+      # - `single_column_width` — overrides the even-division default
+      #   for column widths.
       class TableRenderer
         DEFAULT_SIZE = 10.0
-        INSET = 4.0
+        DEFAULT_INSET = 4.0
 
         def self.render(canvas, context)
           table = context.item
@@ -57,17 +67,42 @@ module Idml
 
         # Real IDML: Table > {Cell, Row} siblings. Cell Name is
         # "col:row". Row count from `row` collection; column count
-        # derived from max col + 1 across cells.
+        # derived from `column_count` attribute or max col + 1.
         def self.render_schema_faithful(canvas, table, box, context)
           layout = SchemaLayout.new(table: table, box: box)
           layout.each_cell do |cell_x, cell_y, cell_w, cell_h, cell|
-            canvas.rectangle(cell_x, cell_y, cell_w, cell_h)
-            canvas.stroke
+            render_cell_background(canvas, cell, cell_x, cell_y, cell_w, cell_h,
+                                   context)
+            render_cell_border(canvas, cell_x, cell_y, cell_w, cell_h)
             render_cell_text(canvas, cell, cell_x, cell_y, cell_h, context)
           end
         end
         private_class_method :render_schema_faithful
 
+        def self.render_cell_background(canvas, cell, x, y, w, h, context)
+          color = cell_fill_color(cell, context)
+          return unless color
+
+          canvas.fill_color(ColorHelper.to_canvas(color))
+          canvas.rectangle(x, y, w, h)
+          canvas.fill
+        end
+        private_class_method :render_cell_background
+
+        def self.render_cell_border(canvas, x, y, w, h)
+          canvas.rectangle(x, y, w, h)
+          canvas.stroke
+        end
+        private_class_method :render_cell_border
+
+        def self.cell_fill_color(cell, context)
+          return nil unless cell.fill_color
+          return nil if cell.fill_color == "Color/None"
+
+          context.color_resolver&.resolve(cell.fill_color)
+        end
+        private_class_method :cell_fill_color
+
         # Legacy: Table > TableRow > TableCell nested.
         def self.render_legacy(canvas, table, box, context)
           return if table.table_row.empty?
@@ -93,33 +128,122 @@ module Idml
         private_class_method :render_legacy
 
         def self.render_cell_text(canvas, cell, x, y, height, context)
+          runs = cell_text_runs(cell, context)
+          return if runs.empty?
+
+          insets = cell_insets(cell)
+          baseline = vertical_baseline(y, height, insets, cell)
+          canvas.text_rich(runs, at: [x + insets[:left], baseline])
+        end
+        private_class_method :render_cell_text
+
+        # Builds pdfrb runs from the cell's typed PSR/CSR children.
+        # Walks ParagraphStyleRange → CharacterStyleRange → Content
+        # so each run carries its own font + size (per-cell CSR
+        # styling). Falls back to a single DEFAULT_SIZE run when
+        # the cell has no typed paragraphs (legacy TableCell).
+        def self.cell_text_runs(cell, context)
+          psr = typed_paragraphs(cell)
+          return default_text_runs(cell, context) if psr.empty?
+
+          psr.flat_map { |paragraph| paragraph_runs(paragraph, context) }
+        end
+        private_class_method :cell_text_runs
+
+        def self.paragraph_runs(paragraph, context)
+          paragraph.character_style_range.filter_map do |csr|
+            text = csr.text_content
+            next if text.nil? || text.empty?
+
+            {
+              text: text,
+              font: context.font_ps_name,
+              size: csr.point_size || DEFAULT_SIZE,
+            }
+          end
+        end
+        private_class_method :paragraph_runs
+
+        # Real IDML `Cell` exposes paragraph_style_range; the legacy
+        # `TableCell` (synthetic fixture only) doesn't, so we treat
+        # it as having no typed paragraphs and fall through to the
+        # default_text_runs path.
+        def self.typed_paragraphs(cell)
+          return [] unless cell.is_a?(Idml::Elements::Cell)
+
+          cell.paragraph_style_range
+        end
+        private_class_method :typed_paragraphs
+
+        def self.default_text_runs(cell, context)
           text = cell.text_content
-          return if text.nil? || text.empty?
+          return [] if text.nil? || text.empty?
 
-          runs = [{
+          [{
             text: text,
             font: context.font_ps_name,
             size: DEFAULT_SIZE,
           }]
-          baseline = y + (height / 2)
-          canvas.text_rich(runs, at: [x + INSET, baseline])
         end
-        private_class_method :render_cell_text
+        private_class_method :default_text_runs
+
+        # Cell insets: prefer typed TextTopInset/Left/Bottom/Right,
+        # fall back to DEFAULT_INSET for any that are missing.
+        def self.cell_insets(cell)
+          {
+            top: cell.top_inset || DEFAULT_INSET,
+            bottom: cell.bottom_inset || DEFAULT_INSET,
+            left: cell.left_inset || DEFAULT_INSET,
+            right: cell.right_inset || DEFAULT_INSET,
+          }
+        end
+        private_class_method :cell_insets
+
+        # Vertical baseline for the cell's first text line, per the
+        # cell's VerticalJustification. IDML values: TopAlign,
+        # CenterAlign, BottomAlign, JustifyAlign. Default: CenterAlign
+        # (legacy behavior).
+        def self.vertical_baseline(y, height, insets, cell)
+          case cell.vertical_justification
+          when "TopAlign"
+            y + height - insets[:top]
+          when "BottomAlign"
+            y + insets[:bottom]
+          else # CenterAlign, JustifyAlign, nil
+            y + (height / 2)
+          end
+        end
+        private_class_method :vertical_baseline
 
         # Computes per-cell rects for the schema-faithful layout.
         # Row heights come from `Row#single_row_height` when present,
         # else fall back to evenly-divided table height. Column
-        # widths are evenly divided (precise column widths would
-        # require ColumnAttributes lookup, deferred).
+        # widths come from `Table#single_column_width` when present
+        # (uniform columns only — per-column widths would require
+        # ColumnAttributes, which IDML doesn't model separately),
+        # else divide evenly.
+        #
+        # Honors `Cell#column_span` and `Cell#row_span`: a spanning
+        # cell covers multiple grid positions and is rendered once
+        # at its top-left corner with the merged rect. Cells covered
+        # by another cell's span are skipped.
         SchemaLayout = Struct.new(:table, :box, keyword_init: true) do
           def each_cell
+            covered = Set.new
+
             row_count.times do |row_idx|
               col_count.times do |col_idx|
+                next if covered.include?([col_idx, row_idx])
+
                 cell = cell_at(col_idx, row_idx)
                 next unless cell
 
-                yield cell_x(col_idx), cell_y(row_idx), cell_w, cell_h(row_idx),
-                      cell
+                col_span = cell.column_span || 1
+                row_span = cell.row_span || 1
+                mark_covered(covered, col_idx, row_idx, col_span, row_span)
+
+                yield cell_x(col_idx), cell_y(row_idx, col_span, row_span),
+                      cell_w(col_span), cell_h(row_idx, row_span), cell
               end
             end
           end
@@ -130,11 +254,16 @@ module Idml
 
           def col_count
             @col_count ||= begin
-              max_col = cells.filter_map(&:col_row).map(&:first).max || 0
-              max_col + 1
+              declared = table.column_count
+              declared&.positive? ? declared : derived_col_count
             end
           end
 
+          def derived_col_count
+            max_col = cells.filter_map(&:col_row).map(&:first).max || 0
+            max_col + 1
+          end
+
           def rows
             table.row
           end
@@ -147,20 +276,52 @@ module Idml
             cells.find { |c| c.col_row == [col, row] }
           end
 
+          def mark_covered(covered, col, row, col_span, row_span)
+            col_span.times do |dc|
+              row_span.times do |dr|
+                covered << [col + dc, row + dr]
+              end
+            end
+          end
+          private :mark_covered
+
           def cell_x(col)
-            box[:x] + (col * cell_w)
+            box[:x] + (col * per_col_width)
           end
 
-          def cell_y(row)
-            box[:y] + total_height - cumulative_height(row) - cell_h(row)
+          # PDF-coordinate bottom y of the cell's rectangle. For a
+          # row_spanning cell, this is the bottom edge of the last
+          # spanned row. PDF rectangle takes (x, y_bottom, w, h).
+          def cell_y(row, _col_span, row_span)
+            last_row = row + row_span - 1
+            box[:y] + total_height - cumulative_height(last_row + 1)
           end
 
-          def cell_w
-            box[:width] / [col_count, 1].max
+          # Width covered by `span` columns starting at the cell's col.
+          def cell_w(span)
+            per_col_width * (span || 1)
           end
 
-          def cell_h(row_idx)
-            row_heights[row_idx] || (box[:height] / [row_count, 1].max)
+          # Total height covered by `span` rows starting at `row_idx`.
+          def cell_h(row_idx, span)
+            (span || 1).times.sum { |i| row_height(row_idx + i) }
+          end
+
+          def per_col_width
+            return @per_col_width if @per_col_width
+
+            declared = table.single_column_width
+            @per_col_width = if declared&.positive?
+                               declared
+                             else
+                               box[:width] / [col_count, 1].max
+                             end
+          end
+
+          def row_height(idx)
+            return 0.0 unless idx.between?(0, row_count - 1)
+
+            row_heights[idx] || (box[:height] / [row_count, 1].max)
           end
 
           def row_heights
@@ -171,11 +332,11 @@ module Idml
           end
 
           def total_height
-            @total_height ||= row_count.times.sum { |i| cell_h(i) }
+            @total_height ||= row_count.times.sum { |i| row_height(i) }
           end
 
           def cumulative_height(up_to_row)
-            up_to_row.times.sum { |i| cell_h(i) }
+            up_to_row.times.sum { |i| row_height(i) }
           end
         end
         private_constant :SchemaLayout

data/lib/idml/render/renderers/text_frame_renderer.rb

@@ -3,11 +3,26 @@
 module Idml
   module Render
     module Renderers
-      # Renders an IDML TextFrame on a Pdfrb::Content::Canvas. Extracts
-      # styled runs via StyleResolver. When a FontMetrics is available
-      # (pdfrb-backed), runs the full text engine pipeline (Shaper →
-      # LineBreaker) for proper word-wrap; otherwise falls back to a
-      # single text_rich call per frame.
+      # Renders an IDML TextFrame on a Pdfrb::Content::Canvas.
+      #
+      # Pipeline:
+      #
+      #   1. Resolve the linked Story via Package#story_by_id.
+      #   2. Extract `Paragraph`s via StyleResolver (carries PSR
+      #      attributes like SpaceBefore, FirstLineIndent, AutoLeading
+      #      alongside the CSR runs).
+      #   3. Build a layout `Frame` from the TextFrame's geometric
+      #      bounds plus TextFramePreference insets.
+      #   4. For each paragraph: shape glyphs (Shaper), wrap to the
+      #      inset/indent-adjusted width (LineBreaker), align (Justifier),
+      #      position vertically (VerticalLayout), and emit one
+      #      `canvas.text` per line. Tracks the y cursor across
+      #      paragraphs and runs so text flows top-to-bottom.
+      #   5. Records each positioned line in PositionTracker so
+      #      HyperlinkEmitter can compute precise per-source link rects.
+      #
+      # Falls back to a single `canvas.text_rich` per frame when no
+      # FontMetrics is available (no shaper → no wrap → rough output).
       class TextFrameRenderer
         DEFAULT_SIZE = 12.0
         LEADING_FACTOR = 1.2
@@ -23,10 +38,10 @@ module Idml
           box = frame_box(frame, context.page_height)
           render_inline_tables(canvas, story, box, context)
 
-          runs = StyleResolver.extract_runs(story)
-          return if runs.empty?
+          paragraphs = StyleResolver.extract_paragraphs(story)
+          return if paragraphs.empty?
 
-          render_text(canvas, runs, context, box)
+          render_text(canvas, paragraphs, context, box)
         end
 
         # Discovers Tables inlined in the story (Story > PSR > CSR >
@@ -55,12 +70,12 @@ module Idml
         end
         private_class_method :tables_in_story
 
-        def self.render_text(canvas, runs, context, box)
+        def self.render_text(canvas, paragraphs, context, box)
           font = context.font_metrics
           if font
-            engine_render(canvas, runs, context, box, font)
+            engine_render(canvas, paragraphs, context, box, font)
           else
-            simple_render(canvas, runs, context, box)
+            simple_render(canvas, paragraphs, context, box)
           end
         end
         private_class_method :render_text
@@ -75,58 +90,169 @@ module Idml
         end
         private_class_method :frame_box
 
-        def self.engine_render(canvas, runs, context, box, font)
+        # Builds a layout Frame from the TextFrame's PDF-placement
+        # box plus any TextFramePreference insets. Inset values fall
+        # back to 0 when the preference is absent or doesn't declare
+        # them.
+        def self.layout_frame(frame_item, box)
+          pref = frame_item.text_frame_preference&.first
+          TextEngine::Frame.new(
+            x: box[:x],
+            y: box[:y],
+            width: box[:width],
+            height: box[:height],
+            inset_top: pref&.inset_top,
+            inset_bottom: pref&.inset_bottom,
+            inset_left: pref&.inset_left,
+            inset_right: pref&.inset_right,
+          )
+        end
+        private_class_method :layout_frame
+
+        # Walks paragraphs and emits one `canvas.text` per line via
+        # the Shaper → LineBreaker → Justifier → VerticalLayout
+        # pipeline. Cursor y descends monotonically across
+        # paragraphs so text flows top-to-bottom (the previous
+        # implementation reset every run to the frame top).
+        def self.engine_render(canvas, paragraphs, context, box, font)
+          layout_frame = layout_frame(context.item, box)
+          cursor_y = box[:y] + box[:height] - (layout_frame.inset_top || 0)
+          bottom_limit = TextEngine::VerticalLayout.bottom_limit(layout_frame)
           char_cursor = 0
-          runs.each do |run|
-            char_cursor = render_run_lines(
-              canvas, run, context, box, font, char_cursor
+
+          paragraphs.each do |paragraph|
+            break if cursor_y < bottom_limit
+
+            cursor_y, char_cursor = render_paragraph(
+              canvas, paragraph, context, layout_frame, font,
+              cursor_y, bottom_limit, char_cursor
             )
           end
         end
         private_class_method :engine_render
 
-        # Emits one `canvas.text` call per line, after shaping and
-        # line-breaking with real font metrics. Applies paragraph
-        # alignment via `Justifier` so each line is offset within
-        # the frame box per IDML `Justification`. Lines that fall
-        # below the frame's bottom edge are clipped.
-        #
-        # Tracks absolute character position so HyperlinkEmitter can
-        # compute precise link rects per source range.
-        def self.render_run_lines(canvas, run, context, box, font, char_cursor)
-          size = run.point_size
+        def self.render_paragraph(canvas, paragraph, context, layout_frame,
+                                  font, cursor_y, bottom_limit, char_cursor)
+          wrap_width = TextEngine::VerticalLayout.wrap_width(
+            layout_frame, paragraph.right_indent || 0
+          )
+          para_attrs = paragraph_attrs(paragraph)
+          cursor_y, char_cursor = render_runs(
+            canvas, paragraph, context, layout_frame, font,
+            wrap_width, cursor_y, bottom_limit, char_cursor, para_attrs
+          )
+          [cursor_y - para_attrs[:space_after], char_cursor]
+        end
+        private_class_method :render_paragraph
+
+        def self.paragraph_attrs(paragraph)
+          {
+            space_before: paragraph.space_before || 0,
+            space_after: paragraph.space_after || 0,
+            first_line_indent: paragraph.first_line_indent || 0,
+            left_indent: paragraph.left_indent || 0,
+          }
+        end
+        private_class_method :paragraph_attrs
+
+        def self.render_runs(canvas, paragraph, context, layout_frame, font,
+                             wrap_width, cursor_y, bottom_limit, char_cursor,
+                             para_attrs)
+          space_before = para_attrs[:space_before]
+          paragraph.runs.each do |run|
+            break if cursor_y < bottom_limit
+
+            positioned, next_y = layout_run(
+              canvas, run, paragraph, context, layout_frame, font,
+              wrap_width, cursor_y, space_before,
+              para_attrs[:first_line_indent], para_attrs[:left_indent],
+              char_cursor
+            )
+            char_cursor += positioned.length
+            cursor_y = next_y
+            space_before = 0
+          end
+          [cursor_y, char_cursor]
+        end
+        private_class_method :render_runs
+
+        # Shapes one run's text, wraps to the inset/indent-adjusted
+        # width, justifies per paragraph alignment, and asks
+        # VerticalLayout to position the lines. Emits each line via
+        # `canvas.text` and records positions for hyperlink tracking.
+        # Returns `[positioned_lines, next_y]`.
+        def self.layout_run(canvas, run, paragraph, context, layout_frame,
+                            font, wrap_width, cursor_y, space_before,
+                            first_line_indent, left_indent,
+                            char_cursor)
+          size = run.point_size || DEFAULT_SIZE
           glyphs = TextEngine::Shaper.shape(
             text: run.text, font: font, size: size,
           )
           lines = TextEngine::LineBreaker.break(
-            glyphs: glyphs, frame_width: box[:width],
+            glyphs: glyphs, frame_width: wrap_width,
           )
-          alignment = run.alignment || :left
-          start_y = box[:y] + box[:height] - size
-          cursor = char_cursor
-
-          lines.each_with_index do |line, idx|
-            line_y = start_y - (idx * size * LEADING_FACTOR)
-            break if line_y < box[:y]
-
-            TextEngine::Justifier.justify(line: line,
-                                          frame_width: box[:width],
-                                          alignment: alignment)
-            line_x = box[:x] + line.x_offset
-            line_width = line.width
-            canvas.text(line_text(line),
-                        at: [line_x, line_y],
-                        font: font_for_run(run, context),
-                        size: size)
-            record_position(context, line, line_x, line_y, line_width, size,
-                            cursor)
-            cursor += line.glyphs.length
+          lines.each do |line|
+            TextEngine::Justifier.justify(
+              line: line, frame_width: wrap_width,
+              alignment: paragraph.alignment || :left
+            )
           end
-          cursor
+          leading = leading_for(paragraph, size)
+
+          positioned, next_y = TextEngine::VerticalLayout.layout_block(
+            lines: lines,
+            frame: layout_frame,
+            font_size: size,
+            leading: leading,
+            cursor_y: cursor_y,
+            space_before: space_before,
+            first_line_indent: first_line_indent,
+            left_indent: left_indent,
+          )
+
+          bottom_limit = TextEngine::VerticalLayout.bottom_limit(layout_frame)
+          positioned.each do |line|
+            break if line.y < bottom_limit
+
+            emit_line(canvas, line, run, context, size)
+            record_position(context, line, size, char_cursor)
+          end
+          [positioned, next_y]
         end
-        private_class_method :render_run_lines
+        private_class_method :layout_run
 
-        def self.record_position(context, line, x, y, width, height, cursor)
+        # Emits one positioned line: applies character-level styling
+        # (fill color, capitalization, position) via CharacterStyle,
+        # then draws underline/strike-through rules after the text.
+        def self.emit_line(canvas, line, run, context, size)
+          text = CharacterStyle.transform_text(line_text(line),
+                                               run.capitalization)
+          scaled_size, baseline_offset = CharacterStyle.position_scale(
+            run.position, size
+          )
+          CharacterStyle.apply(canvas, run, context,
+                               x: line.x, y: line.y + baseline_offset,
+                               width: line.width, size: scaled_size) do
+            canvas.text(
+              text,
+              at: [line.x, line.y + baseline_offset],
+              font: font_for_run(run, context),
+              size: scaled_size,
+            )
+          end
+        end
+        private_class_method :emit_line
+
+        def self.leading_for(paragraph, size)
+          explicit = paragraph.auto_leading
+          return size * LEADING_FACTOR unless explicit&.positive?
+
+          size * explicit
+        end
+        private_class_method :leading_for
+
+        def self.record_position(context, line, height, cursor)
           tracker = context.position_tracker
           return unless tracker
           return unless context.item&.self_attr
@@ -135,9 +261,9 @@ module Idml
           tracker.add(context.item.self_attr,
                       start_char: cursor,
                       end_char: cursor + glyph_count,
-                      x: x,
-                      y: y,
-                      width: width,
+                      x: line.x,
+                      y: line.y,
+                      width: line.width,
                       height: height)
         end
         private_class_method :record_position
@@ -146,7 +272,7 @@ module Idml
         # run's `applied_font` (family name from CSR's AppliedFont)
         # against the document's font_map. Falls back to the document
         # default when no per-run font is specified or the family
-        # isn registered.
+        # isn't registered.
         def self.font_for_run(run, context)
           family = run.applied_font
           return context.font_ps_name unless family
@@ -163,12 +289,12 @@ module Idml
 
         # Fallback when no metrics are available: emit all runs as
         # one `text_rich` block, letting pdfrb measure advance widths.
-        # Uses pdfrb's measurement API directly (no Fontisan).
-        def self.simple_render(canvas, runs, context, box)
-          runs_for = build_rich_runs(runs, context)
-          return if runs_for.empty?
+        def self.simple_render(canvas, paragraphs, context, box)
+          runs = paragraphs.flat_map(&:runs)
+          return if runs.empty?
 
-          first_size = runs.first.point_size
+          runs_for = build_rich_runs(runs, context)
+          first_size = runs.first.point_size || DEFAULT_SIZE
           canvas.text_rich(
             runs_for,
             at: [box[:x], box[:y] + box[:height] - first_size],
@@ -181,7 +307,7 @@ module Idml
             {
               text: run.text,
               font: font_for_run(run, context),
-              size: run.point_size,
+              size: run.point_size || DEFAULT_SIZE,
             }
           end
         end

data/lib/idml/render/style_resolver.rb

@@ -2,15 +2,59 @@
 
 module Idml
   module Render
-    # Extracts styled text runs from an IDML Story. Each run carries the
-    # text content plus the CharacterStyleRange attributes that affect
-    # rendering (font style, size, fill color, applied font reference,
-    # paragraph alignment).
+    # Extracts styled text from an IDML Story in two granularities:
+    #
+    # 1. `extract_runs` — flat list of `StyledRun` (character-level
+    #    attributes only). Useful when paragraph boundaries don't
+    #    matter (e.g., simple-render fallback).
+    # 2. `extract_paragraphs` — list of `Paragraph` structs, each
+    #    carrying paragraph-level attributes (spacing, indents,
+    #    leading) plus its runs. Used by the layout engine so the
+    #    renderer can apply SpaceBefore / FirstLineIndent / etc.
+    #
+    # Both methods read the same source (PSR → CSR → Content) so the
+    # text content is identical; only the grouping and attribute
+    # propagation differ.
     class StyleResolver
+      # Character-level attributes carried per run. Defaults are
+      # applied at render time (e.g., DEFAULT_POINT_SIZE) — the Struct
+      # itself stores only what the CSR declares.
       StyledRun = Struct.new(
-        :text, :font_style, :point_size,
-        :fill_color, :fill_tint, :applied_font, :alignment,
-        keyword_init: true
+        :text,
+        :font_style,
+        :point_size,
+        :fill_color,
+        :fill_tint,
+        :applied_font,
+        :alignment,
+        :tracking,
+        :capitalization,
+        :position,
+        :underline,
+        :underline_offset,
+        :underline_weight,
+        :strike_thru,
+        :strike_through_offset,
+        :strike_through_weight,
+        :horizontal_scale,
+        :vertical_scale,
+        :baseline_shift,
+        keyword_init: true,
+      )
+
+      # Paragraph-level attributes carried alongside a run list.
+      # Each attribute comes from the owning PSR and is nil when the
+      # PSR doesn't declare it.
+      Paragraph = Struct.new(
+        :runs,
+        :alignment,
+        :space_before,
+        :space_after,
+        :first_line_indent,
+        :left_indent,
+        :right_indent,
+        :auto_leading,
+        keyword_init: true,
       )
 
       DEFAULT_POINT_SIZE = 12.0
@@ -28,6 +72,8 @@ module Idml
         "ToBinding" => :left,
       }.freeze
 
+      # Returns the flat run list for a story. Each run carries only
+      # character-level attributes. Paragraph boundaries are lost.
       def self.extract_runs(story)
         return [] unless story&.inner
 
@@ -36,6 +82,30 @@ module Idml
         end
       end
 
+      # Returns the paragraph list for a story. Each paragraph groups
+      # its runs and carries the paragraph-level attributes from the
+      # owning PSR. Empty paragraphs (no runs after filtering) are
+      # skipped.
+      def self.extract_paragraphs(story)
+        return [] unless story&.inner
+
+        story.inner.paragraph_style_range.filter_map do |psr|
+          runs = csr_runs(psr)
+          next if runs.empty?
+
+          Paragraph.new(
+            runs: runs,
+            alignment: runs.first.alignment,
+            space_before: psr.space_before,
+            space_after: psr.space_after,
+            first_line_indent: psr.first_line_indent,
+            left_indent: psr.left_indent,
+            right_indent: psr.right_indent,
+            auto_leading: psr.auto_leading,
+          )
+        end
+      end
+
       def self.csr_runs(psr)
         psr.character_style_range.filter_map do |csr|
           text = csr.text_content
@@ -49,6 +119,18 @@ module Idml
             fill_tint: csr.fill_tint,
             applied_font: csr.applied_font,
             alignment: alignment_for(csr),
+            tracking: csr.tracking,
+            capitalization: csr.capitalization,
+            position: csr.position,
+            underline: csr.underline,
+            underline_offset: csr.underline_offset,
+            underline_weight: csr.underline_weight,
+            strike_thru: csr.strike_thru,
+            strike_through_offset: csr.strike_through_offset,
+            strike_through_weight: csr.strike_through_weight,
+            horizontal_scale: csr.horizontal_scale,
+            vertical_scale: csr.vertical_scale,
+            baseline_shift: csr.baseline_shift,
           )
         end
       end

data/lib/idml/render.rb

@@ -13,6 +13,7 @@ module Idml
     autoload :GradientResolver,    "#{__dir__}/render/gradient_resolver"
     autoload :Blending,            "#{__dir__}/render/blending"
     autoload :StrokeStyle,         "#{__dir__}/render/stroke_style"
+    autoload :CharacterStyle,      "#{__dir__}/render/character_style"
     autoload :LayerFilter,         "#{__dir__}/render/layer_filter"
     autoload :Placement,           "#{__dir__}/render/placement"
     autoload :ImageCollector,      "#{__dir__}/render/image_collector"

data/lib/idml/text_engine/vertical_layout.rb

@@ -2,63 +2,68 @@
 
 module Idml
   module TextEngine
-    # A glyph with absolute (x, y) position, ready for rendering.
-    PositionedGlyph = Struct.new(:codepoint, :x, :y, :font_size)
+    # Geometry of a text frame as seen by the layout engine: outer
+    # bounds plus the four inset margins. Inset values are nil when
+    # the TextFramePreference doesn't declare them.
+    Frame = Struct.new(
+      :x, :y, :width, :height,
+      :inset_top, :inset_bottom, :inset_left, :inset_right,
+      keyword_init: true
+    )
 
-    # Positions justified lines vertically within a text frame.
-    # Applies leading, paragraph spacing, first-line indent, and
-    # left/right insets.
-    class VerticalLayout
-      Frame = Struct.new(:x, :y, :width, :height,
-                         :inset_top, :inset_bottom,
-                         :inset_left, :inset_right)
+    # A line that's been positioned absolutely within a frame.
+    # `glyphs` is the original ShapedGlyph array (carrying widths);
+    # `x`, `y` is the left edge / baseline; `width` is the line's
+    # natural width after justification.
+    PositionedLine = Struct.new(:glyphs, :x, :y, :width, keyword_init: true)
 
-      def self.layout(lines:, frame:, font_size:,
-                      leading: nil, space_before: 0, space_after: 0,
-                      first_line_indent: 0, left_indent: 0)
-        new(frame, font_size, leading, space_before, space_after,
-            first_line_indent, left_indent).layout(lines)
-      end
+    # Positions lines vertically within a text frame. The layout is
+    # block-oriented: each call to `layout_block` returns the
+    # positioned lines for one block (paragraph, run, etc.) and the
+    # y cursor for the next block, so callers can stack paragraphs
+    # without re-deriving cursor math.
+    class VerticalLayout
+      DEFAULT_LEADING_FACTOR = 1.2
 
-      def initialize(frame, font_size, leading, space_before,
-                     space_after, first_line_indent, left_indent)
-        @frame = frame
-        @font_size = font_size
-        @leading = leading || (font_size * 1.2)
-        @space_before = space_before
-        @space_after = space_after
-        @first_line_indent = first_line_indent
-        @left_indent = left_indent
-      end
+      # Position `lines` starting at `cursor_y` and walking downward.
+      # `cursor_y` is the top of the available space; the first line
+      # sits one `leading` below it. Returns `[positioned_lines, next_y]`
+      # where `next_y` is where the next block should start (i.e. below
+      # this block's last line plus `space_after`).
+      def self.layout_block(lines:, frame:, font_size:, cursor_y:, leading: nil, space_before: 0, space_after: 0,
+                            first_line_indent: 0, left_indent: 0)
+        effective_leading = leading || (font_size * DEFAULT_LEADING_FACTOR)
+        y = cursor_y - space_before
+        positioned = []
 
-      def layout(lines)
-        result = []
-        y = top_y - @space_before
         lines.each_with_index do |line, idx|
-          y -= @leading
-          x = frame_left + (idx.zero? ? @first_line_indent : @left_indent)
-          x += line.x_offset.to_f
-          current_x = x
-          line.glyphs.each do |glyph|
-            result << PositionedGlyph.new(glyph.codepoint,
-                                          current_x,
-                                          y,
-                                          @font_size)
-            current_x += glyph.width
-          end
+          y -= effective_leading
+          x = frame_left(frame) + left_indent +
+            (idx.zero? ? first_line_indent : 0) + line.x_offset.to_f
+          positioned << PositionedLine.new(
+            glyphs: line.glyphs, x: x, y: y, width: line.width,
+          )
         end
-        result
+
+        [positioned, y - space_after]
       end
 
-      private
+      # Bottom y of the frame's text area (frame bottom edge + bottom
+      # inset). Lines whose y falls below this are clipped.
+      def self.bottom_limit(frame)
+        frame.y + (frame.inset_bottom || 0)
+      end
 
-      def top_y
-        @frame.y - (@frame.inset_top || 0)
+      # Effective wrap width after subtracting insets and indents.
+      def self.wrap_width(frame, right_indent = 0)
+        width = frame.width - (frame.inset_left || 0) - (frame.inset_right || 0)
+        width - right_indent
       end
 
-      def frame_left
-        @frame.x + (@frame.inset_left || 0)
+      def self.frame_left(frame)
+        frame.x + (frame.inset_left || 0)
       end
+      private_class_method :frame_left
     end
   end
 end

data/lib/idml/text_engine.rb

@@ -2,7 +2,7 @@
 
 module Idml
   # Pure-Ruby text layout engine. Takes styled text runs + frame
-  # geometry and produces positioned glyphs using font metrics from
+  # geometry and produces positioned lines using font metrics from
   # .ttf/.otf files. IDML-agnostic — works on any styled text.
   module TextEngine
     autoload :PdfrbFontMetrics, "#{__dir__}/text_engine/pdfrb_font_metrics"
@@ -12,7 +12,8 @@ module Idml
     autoload :Line,            "#{__dir__}/text_engine/line_breaker"
     autoload :Justifier,       "#{__dir__}/text_engine/justifier"
     autoload :VerticalLayout,  "#{__dir__}/text_engine/vertical_layout"
-    autoload :PositionedGlyph, "#{__dir__}/text_engine/vertical_layout"
+    autoload :Frame,           "#{__dir__}/text_engine/vertical_layout"
+    autoload :PositionedLine,  "#{__dir__}/text_engine/vertical_layout"
     autoload :CjkLayout,       "#{__dir__}/text_engine/cjk_layout"
   end
 end

data/lib/idml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Idml
-  VERSION = "0.6.2"
+  VERSION = "0.7.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: idml
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.0
 platform: ruby
 authors:
 - Ribose
@@ -58,14 +58,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.7'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.6'
+        version: '0.7'
 - !ruby/object:Gem::Dependency
   name: rubyzip
   requirement: !ruby/object:Gem::Requirement
@@ -421,6 +421,7 @@ files:
 - lib/idml/render.rb
 - lib/idml/render/blending.rb
 - lib/idml/render/bookmark_resolver.rb
+- lib/idml/render/character_style.rb
 - lib/idml/render/color_helper.rb
 - lib/idml/render/color_resolver.rb
 - lib/idml/render/font_reference_resolver.rb