idml 0.6.1 → 0.7.0

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.1"
+  VERSION = "0.7.0"
 end