idml 0.8.9 → 0.9.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d58f00746f6afb4233e161dfa9cdeb116d714eed0c238ec543a0f039b4167f0e
-  data.tar.gz: 1a000e34996525fe34cdc441625c9eaa303f121c836ae3f3b07b73c12712abb1
+  metadata.gz: a82b32708ab694d0d794c39f33d74de7b39a9bdc38b7a6315b99a2156dcef271
+  data.tar.gz: 7eee074d6ecf3a46798139fa6ed6fc36c975bcaf93059c52e68e597e7b1a87f3
 SHA512:
-  metadata.gz: 15001cbf1427dc278c701cd4980b837ff4b015f6c5657eeb5c88c0c8774933934e606439c40fa3c900368ef2959fc1170cd12841a9caadc0c025a199dd18cd68
-  data.tar.gz: 41f45b1b2db245e1dd2d5ef40aa60990fc3c957930b3d16a633974d1f267149e8b2c5cf638b7b3549b4318bf8ea62f378fbb5d0f98ad32d4d50fbce0e3cb9505
+  metadata.gz: 6c561f3cd1a83d7688291a2ef3dc23d42616bce723b5ff82a77a641104fae0731247c4cbc50cae2d9d5d5aa979c31ac8e90ff0b38f107235793bdfd7fda4019a
+  data.tar.gz: e42f707ec01db8ce171244e95ba378420bdf44c4a195c1f2f285ac7d56e91777c4750f5d5f4b05dc6ac60fb2f59beebaa50755f6c1ee3bb2de13957a7b44edab

data/TODO.pdf/101-paragraph-rules-borders.md

@@ -1,47 +1,44 @@
 # TODO PDF 101: Paragraph borders and rules (RuleAbove, RuleBelow, ParagraphBorder)
 
-## Status: PARTIAL — RuleAbove and RuleBelow implemented via new
-`Render::ParagraphRules` helper; TextFrameRenderer emits them at
-paragraph top/bottom. Rule color comes from PSR#stroke_color (IDML's
-PSR doesn't have a dedicated RuleAboveColor attribute). RuleAboveWidth
-"Text" vs "Column" honored. Tint scaling + line weight + offset honored.
-
-ParagraphBorder and ParagraphShading remain open — they need the
-paragraph's bounding rect, which the renderer doesn't currently
-expose to ParagraphRules. Will add when a real document fixture
-exercises them.
-
-## Problem
-
-`ParagraphStyleRange` carries:
-
-- `RuleAbove`, `RuleAboveLineWeight`, `RuleAboveTint`, `RuleAboveOffset`,
-  `RuleAboveLeftIndent`, `RuleAboveRightIndent`, `RuleAboveWidth`
-- `RuleBelow`, `RuleBelowLineWeight`, `RuleBelowTint`, `RuleBelowOffset`,
-  `RuleBelowLeftIndent`, `RuleBelowRightIndent`, `RuleBelowWidth`
-- `ParagraphBorderOn`, `ParagraphBorderTopLineWeight`,
-  `ParagraphBorderLeftLineWeight`, etc.
-- `ParagraphShadingOn`, `ParagraphShadingTint`, `ParagraphShadingColor`
-
-None of these are rendered today. Real-world documents use RuleAbove
-heavily for headings ("section divider line"), and ParagraphShading
-for callouts.
-
-## What needs to happen
-
-1. After laying out a paragraph, emit RuleAbove as a horizontal line
-   above the first line, with the rule's weight/tint/color/offset/indent.
-2. Emit RuleBelow similarly below the last line.
-3. Optionally emit ParagraphBorder as a rectangle around the paragraph.
-4. Optionally emit ParagraphShading as a fill behind the paragraph.
+## Status: COMPLETE — implemented 2026-08-17
+
+## What was built
+
+- RuleAbove / RuleBelow (earlier milestone): horizontal rules at
+  paragraph top/bottom with weight / tint / offset / indent /
+  TextWidth-ColumnWidth modes, via `Render::ParagraphRules`.
+- Rule colors now resolve from `Properties > RuleAboveColor` /
+  `RuleBelowColor` (typed value elements) with StrokeColor fallback —
+  modeled via `Elements::TypedValue` + Properties mapping, PSR/CSR
+  now carry `properties` collections.
+- ParagraphShading: fill rect behind the paragraph block. Color from
+  `Properties > ParagraphShadingColor`, tint scaling, ParagraphShading
+  width mode (ColumnWidth default / TextWidth), four outward offsets.
+  `TextEngine::Measurement` pre-measures the paragraph's height so
+  the rect is known before the lines are laid out (clamped to the
+  frame's bottom limit when the paragraph splits).
+- ParagraphBorder: per-side strokes around the same block rect, each
+  side with its own line weight and the border offsets/tint/color
+  (Properties > ParagraphBorderColor). Shading and border share one
+  extent so they always agree.
+
+## Known limitations
+
+- Border corner radii and gap colors are parsed on the model but not
+  rendered; MergeConsecutiveParaBorders (merged rects across like-
+  bordered paragraphs) is not modeled.
+- DisplayIfSplits: when a paragraph splits across frames, both
+  shading and border are drawn around the rendered portion only.
 
 ## Acceptance criteria
 
-- [ ] PSR with RuleAbove=true and RuleAboveLineWeight=2 draws a 2pt
-      horizontal line above the paragraph.
-- [ ] PSR with RuleAboveOffset=4 leaves 4pt gap between rule and text.
-- [ ] PSR with ParagraphShadingOn=true and tint fills the paragraph rect.
+- [x] PSR with RuleAbove=true and RuleAboveLineWeight=2 draws the
+      rule above the paragraph.
+- [x] PSR with RuleAboveOffset=4 leaves a 4pt gap.
+- [x] PSR with ParagraphShadingOn=true and tint fills the paragraph
+      rect.
+- [x] ParagraphBorderOn draws per-side strokes.
 
 ## Dependencies
 
-- TODO 94 (VerticalLayout knows the paragraph's rect).
+- TODO 94 (VerticalLayout knows the paragraph's rect) — satisfied.

data/TODO.pdf/13-cjk-text-layout.md

@@ -1,9 +1,25 @@
 # TODO PDF 13: CJK text layout
 
-## Status: PARTIAL — `Idml::TextEngine::CjkLayout` handles CJK glyph
-measurement and basic horizontal layout. Vertical writing mode,
-kinsoku shori, tate-chu-yoko, and ruby remain stretch goals as
-flagged in the original TODO. See `lib/idml/text_engine/cjk_layout.rb`.
+## Status: PARTIAL — horizontal-mode CJK complete (2026-08-17):
+CJK glyph measurement, kinsoku shori, and ruby annotations render.
+Vertical writing mode, tate-chu-yoko, and mojikumi remain OPEN
+stretch goals — they need a vertical (rotated) layout engine and
+real vertical-mode fixtures to build against. See
+`lib/idml/text_engine/cjk_layout.rb`.
+
+## Progress 2026-08-17
+
+- Kinsoku shori is now LIVE in the pipeline: LineBreaker.break
+  post-processes any run containing CJK glyphs through
+  CjkLayout.apply_kinsoku, so no rendered line starts with
+  、。，」etc. or ends with 「 etc. (previously the logic existed
+  but was never called).
+- Ruby (phonetic annotations) render: CSR RubyString /
+  RubyFontSize / RubyPosition extract onto the run; the renderer
+  emits the annotation centered above the run's first line (half
+  the base size by default; Below* positions place it under).
+  Approximation: IDML attaches ruby to a character range; we
+  annotate the whole first line.
 
 ## Goal
 

data/lib/idml/elements/character_style_range.rb

@@ -298,6 +298,7 @@ module Idml
       attribute :content, Idml::Elements::Content, collection: true
       attribute :hyperlink_text_source, Idml::Elements::HyperlinkTextSource,
                 collection: true
+      attribute :properties, Idml::Elements::Properties, collection: true
       attribute :table, Idml::Elements::Table, collection: true
       attribute :xml_element, Idml::Elements::XmlElement, collection: true
       attribute :footnote, Idml::Elements::Footnote, collection: true
@@ -664,6 +665,7 @@ module Idml
         map_element "CharacterStyleRange", to: :character_style_range
         map_element "Content", to: :content
         map_element "HyperlinkTextSource", to: :hyperlink_text_source
+        map_element "Properties", to: :properties
         map_element "Table", to: :table
         map_element "XMLElement", to: :xml_element
         map_element "Footnote", to: :footnote

data/lib/idml/elements/paragraph_style_range.rb

@@ -298,6 +298,7 @@ module Idml
                 collection: true
       attribute :content, Idml::Elements::Content, collection: true
       attribute :xml_element, Idml::Elements::XmlElement, collection: true
+      attribute :properties, Idml::Elements::Properties, collection: true
 
       xml do
         root "ParagraphStyleRange"
@@ -651,6 +652,7 @@ module Idml
         map_element "ParagraphStyleRange", to: :paragraph_style_range
         map_element "Content", to: :content
         map_element "XMLElement", to: :xml_element
+        map_element "Properties", to: :properties
       end
 
       def text_content

data/lib/idml/elements/properties.rb

@@ -2,18 +2,31 @@
 
 module Idml
   module Elements
-    # `<Properties>` — a common child element on page items. Carries
-    # optional PathBoundingBox, PathGeometry, and Label. Only the
-    # modeled children are populated from XML; others are ignored.
+    # `<Properties>` — a common child element on page items and
+    # story style ranges. Carries optional PathBoundingBox,
+    # PathGeometry, Label, and the paragraph-decoration color value
+    # elements (RuleAboveColor, ParagraphShadingColor, …) used on
+    # PSR/CSR Properties. Only the modeled children are populated
+    # from XML; others are ignored.
     class Properties < Lutaml::Model::Serializable
       attribute :path_bounding_box, :string
       attribute :path_geometry, Idml::Elements::PathGeometry,
                 collection: true
+      attribute :rule_above_color, Idml::Elements::TypedValue
+      attribute :rule_below_color, Idml::Elements::TypedValue
+      attribute :paragraph_shading_color, Idml::Elements::TypedValue
+      attribute :paragraph_border_color, Idml::Elements::TypedValue
+      attribute :paragraph_border_gap_color, Idml::Elements::TypedValue
 
       xml do
         root "Properties"
         map_element "PathBoundingBox", to: :path_bounding_box
         map_element "PathGeometry", to: :path_geometry
+        map_element "RuleAboveColor", to: :rule_above_color
+        map_element "RuleBelowColor", to: :rule_below_color
+        map_element "ParagraphShadingColor", to: :paragraph_shading_color
+        map_element "ParagraphBorderColor", to: :paragraph_border_color
+        map_element "ParagraphBorderGapColor", to: :paragraph_border_gap_color
       end
 
       def first_geometry

data/lib/idml/elements/typed_value.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Idml
+  module Elements
+    # Typed value child element — IDML's `(object_type, xsd:string) |
+    # (string_type, xsd:string)` wrapper used inside Properties for
+    # values like RuleAboveColor and ParagraphShadingColor: a `type`
+    # attribute plus the value as text content.
+    class TypedValue < Lutaml::Model::Serializable
+      attribute :type, :string
+      attribute :value, :string
+
+      xml do
+        root "TypedValue"
+        map_attribute "type", to: :type
+        map_content to: :value
+      end
+    end
+  end
+end

data/lib/idml/elements.rb

@@ -147,6 +147,7 @@ module Idml
     autoload :TOCStyle, "idml/elements/toc_style"
     autoload :TOCStyleEntry, "idml/elements/toc_style_entry"
     autoload :Table, "idml/elements/table"
+    autoload :TypedValue, "idml/elements/typed_value"
     autoload :TableCell, "idml/elements/table_cell"
     autoload :TableRow, "idml/elements/table_row"
     autoload :TableStyle, "idml/elements/table_style"

data/lib/idml/render/paragraph_rules.rb

@@ -82,6 +82,131 @@ module Idml
       end
       private_class_method :emit_rule
 
+      # Emits the paragraph's shading: a fill rect behind the
+      # paragraph block (top_y..bottom_y within the column). The
+      # ParagraphShading* offsets expand the rect outward; tint
+      # scales the color. Color comes from Properties >
+      # ParagraphShadingColor (black when absent, per InDesign's
+      # default shading color).
+      def self.emit_shading(canvas, paragraph, context, top_y, bottom_y,
+                            frame_left, frame_right)
+        return unless paragraph.paragraph_shading_on
+        return unless top_y > bottom_y
+
+        tint_value = decoration_tint(paragraph.paragraph_shading_tint)
+        return unless tint_value
+
+        color = resolve_color(paragraph.paragraph_shading_color,
+                              tint_value, context)
+        return unless color
+
+        left, right, top, bottom = decoration_rect(
+          paragraph, top_y, bottom_y, frame_left, frame_right,
+          left_offset: paragraph.paragraph_shading_left_offset,
+          right_offset: paragraph.paragraph_shading_right_offset,
+          top_offset: paragraph.paragraph_shading_top_offset,
+          bottom_offset: paragraph.paragraph_shading_bottom_offset
+        )
+        canvas.fill_color(color)
+        canvas.rectangle(left, bottom, right - left, top - bottom)
+        canvas.fill
+      end
+
+      # Emits the paragraph's border: per-side strokes around the
+      # paragraph block, each side with its own line weight, drawn
+      # at the block rect expanded by the border offsets.
+      def self.emit_border(canvas, paragraph, context, top_y, bottom_y,
+                           frame_left, frame_right)
+        return unless paragraph.paragraph_border_on
+        return unless top_y > bottom_y
+
+        tint_value = decoration_tint(paragraph.paragraph_border_tint)
+        return unless tint_value
+
+        color = resolve_color(paragraph.paragraph_border_color,
+                              tint_value, context)
+        return unless color
+
+        left, right, top, bottom = decoration_rect(
+          paragraph, top_y, bottom_y, frame_left, frame_right,
+          left_offset: paragraph.paragraph_border_left_offset,
+          right_offset: paragraph.paragraph_border_right_offset,
+          top_offset: paragraph.paragraph_border_top_offset,
+          bottom_offset: paragraph.paragraph_border_bottom_offset
+        )
+        apply_rule_color(canvas, paragraph.paragraph_border_color,
+                         tint_value, context)
+        stroke_border_sides(canvas, paragraph, left, right, top, bottom)
+      end
+
+      # Tint value for a decoration, or nil when zero/absent.
+      def self.decoration_tint(tint)
+        value = (tint || DEFAULT_TINT).to_f
+        value.positive? ? value : nil
+      end
+      private_class_method :decoration_tint
+
+      # The decoration rect [left, right, top, bottom]: the column
+      # (or text) extents expanded outward by the given offsets.
+      def self.decoration_rect(paragraph, top_y, bottom_y, frame_left,
+                               frame_right, left_offset:, right_offset:,
+                               top_offset:, bottom_offset:)
+        left, right = decoration_extents(paragraph, frame_left, frame_right)
+        [left - (left_offset || 0).to_f,
+         right + (right_offset || 0).to_f,
+         top_y + (top_offset || 0).to_f,
+         bottom_y - (bottom_offset || 0).to_f]
+      end
+      private_class_method :decoration_rect
+
+      def self.stroke_border_sides(canvas, paragraph, left, right,
+                                   top, bottom)
+        stroke_horizontal(canvas, left, right, top,
+                          paragraph.paragraph_border_top_line_weight)
+        stroke_horizontal(canvas, left, right, bottom,
+                          paragraph.paragraph_border_bottom_line_weight)
+        stroke_vertical(canvas, bottom, top, left,
+                        paragraph.paragraph_border_left_line_weight)
+        stroke_vertical(canvas, bottom, top, right,
+                        paragraph.paragraph_border_right_line_weight)
+      end
+      private_class_method :stroke_border_sides
+
+      def self.stroke_horizontal(canvas, x1, x2, y, weight)
+        thickness = weight.to_f
+        return unless thickness.positive?
+
+        canvas.line_width = thickness
+        canvas.move_to(x1, y)
+        canvas.line_to(x2, y)
+        canvas.stroke
+      end
+      private_class_method :stroke_horizontal
+
+      def self.stroke_vertical(canvas, y1, y2, x, weight)
+        thickness = weight.to_f
+        return unless thickness.positive?
+
+        canvas.line_width = thickness
+        canvas.move_to(x, y1)
+        canvas.line_to(x, y2)
+        canvas.stroke
+      end
+      private_class_method :stroke_vertical
+
+      # Horizontal extents for shading/border: the column width, or
+      # the text width (indented by the paragraph's indents) when
+      # the shading width mode is "TextWidth".
+      def self.decoration_extents(paragraph, frame_left, frame_right)
+        if paragraph.paragraph_shading_width == "TextWidth"
+          [frame_left + (paragraph.left_indent || 0).to_f,
+           frame_right - (paragraph.right_indent || 0).to_f]
+        else
+          [frame_left, frame_right]
+        end
+      end
+      private_class_method :decoration_extents
+
       # Returns `[x1, x2]` for the rule. Width mode "Text" indents
       # the rule by the paragraph's left/right indent (matches the
       # text bounds); "Column" (default) spans the full column.

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

@@ -25,6 +25,7 @@ module Idml
       # FontMetrics is available (no shaper → no wrap → rough output).
       class TextFrameRenderer
         DEFAULT_SIZE = 12.0
+        RUBY_SIZE_FACTOR = 0.5
 
         def self.render(canvas, context)
           frame = context.item
@@ -445,6 +446,12 @@ module Idml
 
           emit_paragraph_top_rule(canvas, paragraph, context, cursor_y,
                                   frame_left, frame_right, first_paragraph)
+          block_top, block_bottom = paragraph_block_extent(
+            paragraph, font, wrap_width, cursor_y, bottom_limit
+          )
+          ParagraphRules.emit_shading(canvas, paragraph, context,
+                                      block_top, block_bottom,
+                                      frame_left, frame_right)
           drop_cap = emit_drop_cap(canvas, paragraph, context, frame_left,
                                    cursor_y, first_paragraph)
 
@@ -463,10 +470,28 @@ module Idml
                                                 cursor_y, frame_left,
                                                 frame_right, para_attrs,
                                                 remaining_runs)
+          ParagraphRules.emit_border(canvas, paragraph, context,
+                                     block_top, block_bottom,
+                                     frame_left, frame_right)
           [remaining_runs, cursor_y, char_cursor]
         end
         private_class_method :render_runs_for_paragraph
 
+        # The paragraph's block extent: top at the current cursor,
+        # bottom at the pre-measured height clamped to the frame's
+        # bottom limit. Shading and border both use this one rect so
+        # they agree even when the paragraph splits across frames
+        # (the split case shades only the rendered part).
+        def self.paragraph_block_extent(paragraph, font, wrap_width,
+                                        cursor_y, bottom_limit)
+          height = TextEngine::Measurement.paragraph_height(
+            paragraph, font, wrap_width
+          )
+          block_bottom = [cursor_y - height, bottom_limit].max
+          [cursor_y, block_bottom]
+        end
+        private_class_method :paragraph_block_extent
+
         def self.iterate_paragraph_runs(canvas, paragraph, runs, context,
                                         layout_frame, font, wrap_width,
                                         cursor_y, bottom_limit, char_cursor,
@@ -714,15 +739,26 @@ module Idml
             left_indent: left_indent,
           )
 
-          positioned.each do |line|
+          emit_run_lines(canvas, positioned, run, context, size, font,
+                         bottom_limit, char_cursor)
+          [positioned, next_y]
+        end
+        private_class_method :layout_run
+
+        # Emits the run's positioned lines (clipped at the bottom
+        # limit), recording positions and annotating the first line
+        # with the run's ruby when present.
+        def self.emit_run_lines(canvas, positioned, run, context, size,
+                                font, bottom_limit, char_cursor)
+          positioned.each_with_index do |line, index|
             break if line.y < bottom_limit
 
             emit_line(canvas, line, run, context, size)
             record_position(context, line, size, char_cursor)
+            emit_ruby(canvas, run, line, size, font, context) if index.zero?
           end
-          [positioned, next_y]
         end
-        private_class_method :layout_run
+        private_class_method :emit_run_lines
 
         # Emits one positioned line: applies character-level styling
         # (fill color + tint, capitalization, position, tracking,
@@ -755,6 +791,36 @@ module Idml
         end
         private_class_method :emit_line
 
+        # Emits the run's ruby (phonetic annotation) above the first
+        # line of the annotated run, centered over the line's width.
+        # RubyFontSize defaults to half the base size; RubyPosition
+        # values containing "Below" place it under the base text.
+        # Approximation: IDML attaches ruby to a character range;
+        # we annotate the whole first line.
+        def self.emit_ruby(canvas, run, line, base_size, font, context)
+          ruby_text = run.ruby_string
+          return if ruby_text.nil? || ruby_text.empty?
+
+          ruby_size = run.ruby_font_size || (base_size * RUBY_SIZE_FACTOR)
+          glyphs = TextEngine::Shaper.shape(text: ruby_text, font: font,
+                                            size: ruby_size)
+          ruby_width = glyphs.sum(&:width)
+          x = line.x + ((line.width - ruby_width) / 2)
+          y = ruby_y(run, line, base_size, ruby_size)
+          canvas.text(ruby_text, at: [x, y],
+                                 font: font_for_run(run, context), size: ruby_size)
+        end
+        private_class_method :emit_ruby
+
+        def self.ruby_y(run, line, base_size, ruby_size)
+          if run.ruby_position.to_s.include?("Below")
+            line.y - (base_size * 0.25) - ruby_size
+          else
+            line.y + (base_size * 0.45) + ruby_size
+          end
+        end
+        private_class_method :ruby_y
+
         def self.leading_for(paragraph, size)
           TextEngine::VerticalLayout.leading_for(paragraph.auto_leading, size)
         end

data/lib/idml/render/style_resolver.rb

@@ -43,6 +43,11 @@ module Idml
         :baseline_shift,
         :footnote_number,
         :footnote_paragraphs,
+        # Ruby (phonetic annotation) — from the CSR's Ruby*
+        # attributes. Present only on runs with a RubyString.
+        :ruby_string,
+        :ruby_font_size,
+        :ruby_position,
         keyword_init: true,
       )
 
@@ -82,6 +87,28 @@ module Idml
         :rule_below_left_indent,
         :rule_below_right_indent,
         :rule_below_width,
+        # ParagraphShading — fill rect behind the paragraph block.
+        # Color comes from Properties > ParagraphShadingColor.
+        :paragraph_shading_on,
+        :paragraph_shading_color,
+        :paragraph_shading_tint,
+        :paragraph_shading_width,
+        :paragraph_shading_left_offset,
+        :paragraph_shading_right_offset,
+        :paragraph_shading_top_offset,
+        :paragraph_shading_bottom_offset,
+        # ParagraphBorder — per-side strokes around the paragraph.
+        :paragraph_border_on,
+        :paragraph_border_color,
+        :paragraph_border_tint,
+        :paragraph_border_top_line_weight,
+        :paragraph_border_left_line_weight,
+        :paragraph_border_right_line_weight,
+        :paragraph_border_bottom_line_weight,
+        :paragraph_border_top_offset,
+        :paragraph_border_left_offset,
+        :paragraph_border_right_offset,
+        :paragraph_border_bottom_offset,
         keyword_init: true,
       )
 
@@ -171,7 +198,8 @@ module Idml
             rule_above: resolve_attr(style_lookup, psr, :rule_above),
             rule_above_line_weight: resolve_attr(style_lookup, psr,
                                                  :rule_above_line_weight),
-            rule_above_color: resolve_attr(style_lookup, psr, :stroke_color),
+            rule_above_color: properties_color(psr, :rule_above_color) ||
+                             resolve_attr(style_lookup, psr, :stroke_color),
             rule_above_tint: resolve_attr(style_lookup, psr,
                                           :rule_above_tint),
             rule_above_offset: resolve_attr(style_lookup, psr,
@@ -185,7 +213,8 @@ module Idml
             rule_below: resolve_attr(style_lookup, psr, :rule_below),
             rule_below_line_weight: resolve_attr(style_lookup, psr,
                                                  :rule_below_line_weight),
-            rule_below_color: resolve_attr(style_lookup, psr, :stroke_color),
+            rule_below_color: properties_color(psr, :rule_below_color) ||
+                             resolve_attr(style_lookup, psr, :stroke_color),
             rule_below_tint: resolve_attr(style_lookup, psr,
                                           :rule_below_tint),
             rule_below_offset: resolve_attr(style_lookup, psr,
@@ -196,12 +225,70 @@ module Idml
                                                   :rule_below_right_indent),
             rule_below_width: resolve_attr(style_lookup, psr,
                                            :rule_below_width),
+            paragraph_shading_on: resolve_attr(style_lookup, psr,
+                                               :paragraph_shading_on),
+            paragraph_shading_color: properties_color(psr,
+                                                      :paragraph_shading_color),
+            paragraph_shading_tint: resolve_attr(style_lookup, psr,
+                                                 :paragraph_shading_tint),
+            paragraph_shading_width: resolve_attr(style_lookup, psr,
+                                                  :paragraph_shading_width),
+            paragraph_shading_left_offset: resolve_attr(
+              style_lookup, psr, :paragraph_shading_left_offset
+            ),
+            paragraph_shading_right_offset: resolve_attr(
+              style_lookup, psr, :paragraph_shading_right_offset
+            ),
+            paragraph_shading_top_offset: resolve_attr(
+              style_lookup, psr, :paragraph_shading_top_offset
+            ),
+            paragraph_shading_bottom_offset: resolve_attr(
+              style_lookup, psr, :paragraph_shading_bottom_offset
+            ),
+            paragraph_border_on: resolve_attr(style_lookup, psr,
+                                              :paragraph_border_on),
+            paragraph_border_color: properties_color(psr,
+                                                     :paragraph_border_color),
+            paragraph_border_tint: resolve_attr(style_lookup, psr,
+                                                :paragraph_border_tint),
+            paragraph_border_top_line_weight: resolve_attr(
+              style_lookup, psr, :paragraph_border_top_line_weight
+            ),
+            paragraph_border_left_line_weight: resolve_attr(
+              style_lookup, psr, :paragraph_border_left_line_weight
+            ),
+            paragraph_border_right_line_weight: resolve_attr(
+              style_lookup, psr, :paragraph_border_right_line_weight
+            ),
+            paragraph_border_bottom_line_weight: resolve_attr(
+              style_lookup, psr, :paragraph_border_bottom_line_weight
+            ),
+            paragraph_border_top_offset: resolve_attr(
+              style_lookup, psr, :paragraph_border_top_offset
+            ),
+            paragraph_border_left_offset: resolve_attr(
+              style_lookup, psr, :paragraph_border_left_offset
+            ),
+            paragraph_border_right_offset: resolve_attr(
+              style_lookup, psr, :paragraph_border_right_offset
+            ),
+            paragraph_border_bottom_offset: resolve_attr(
+              style_lookup, psr, :paragraph_border_bottom_offset
+            ),
           )
           prepend_list_marker(paragraph)
           paragraph
         end
       end
 
+      # Reads a color value element from the PSR's Properties (e.g.
+      # Properties > ParagraphShadingColor). Returns the color name
+      # string, or nil when the element is absent.
+      def self.properties_color(psr, element_attr)
+        psr.properties.first&.public_send(element_attr)&.value
+      end
+      private_class_method :properties_color
+
       def self.csr_runs(psr, condition_filter: nil, style_lookup: nil,
                         footnote_counter: nil, footnote_option: nil)
         counter = footnote_counter || Footnote.counter_for(footnote_option)
@@ -266,6 +353,9 @@ module Idml
                                         :horizontal_scale),
           vertical_scale: resolve_csr(style_lookup, csr, :vertical_scale),
           baseline_shift: resolve_csr(style_lookup, csr, :baseline_shift),
+          ruby_string: resolve_csr(style_lookup, csr, :ruby_string),
+          ruby_font_size: resolve_csr(style_lookup, csr, :ruby_font_size),
+          ruby_position: resolve_csr(style_lookup, csr, :ruby_position),
         )
       end
       private_class_method :text_run

data/lib/idml/text_engine/line_breaker.rb

@@ -7,10 +7,20 @@ module Idml
 
     # Greedy word-wrap line breaker. Accumulates glyphs until
     # exceeding the frame width, then breaks at the last space.
+    # CJK runs get a kinsoku shori post-pass (no line starts or
+    # ends with a forbidden character).
     class LineBreaker
       def self.break(glyphs:, frame_width:)
-        new(frame_width).break(glyphs)
+        lines = new(frame_width).break(glyphs)
+        return lines unless cjk_run?(glyphs)
+
+        CjkLayout.apply_kinsoku(lines)
+      end
+
+      def self.cjk_run?(glyphs)
+        glyphs.any? { |glyph| CjkLayout.cjk?(glyph.codepoint) }
       end
+      private_class_method :cjk_run?
 
       def initialize(frame_width)
         @frame_width = frame_width

data/lib/idml/text_engine/measurement.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Idml
+  module TextEngine
+    # Height measurement for paragraphs — shape + wrap each run and
+    # sum the line count × leading. Used where a paragraph's full
+    # extent must be known before its lines are laid out (paragraph
+    # shading/border rects).
+    module Measurement
+      DEFAULT_POINT_SIZE = 12.0
+
+      # Returns the paragraph's rendered height at `wrap_width`:
+      # every run's wrapped line count × leading, plus paragraph
+      # SpaceBefore / SpaceAfter.
+      def self.paragraph_height(paragraph, font, wrap_width)
+        lines_height = paragraph.runs.sum do |run|
+          size = run.point_size || DEFAULT_POINT_SIZE
+          lines = wrapped_lines(run, font, wrap_width, size)
+          lines.length *
+            TextEngine::VerticalLayout.leading_for(paragraph.auto_leading,
+                                                   size)
+        end
+        lines_height + space_before_after(paragraph)
+      end
+
+      def self.wrapped_lines(run, font, wrap_width, size)
+        glyphs = TextEngine::Shaper.shape(text: run.text, font: font,
+                                          size: size)
+        TextEngine::LineBreaker.break(glyphs: glyphs,
+                                      frame_width: wrap_width)
+      end
+      private_class_method :wrapped_lines
+
+      def self.space_before_after(paragraph)
+        (paragraph.space_before || 0) + (paragraph.space_after || 0)
+      end
+      private_class_method :space_before_after
+    end
+  end
+end

data/lib/idml/text_engine.rb

@@ -6,7 +6,8 @@ module Idml
   # .ttf/.otf files. IDML-agnostic — works on any styled text.
   module TextEngine
     autoload :PdfrbFontMetrics, "#{__dir__}/text_engine/pdfrb_font_metrics"
-    autoload :Shaper,          "#{__dir__}/text_engine/shaper"
+    autoload :Shaper, "#{__dir__}/text_engine/shaper"
+    autoload :Measurement, "#{__dir__}/text_engine/measurement"
     autoload :ShapedGlyph,     "#{__dir__}/text_engine/shaper"
     autoload :LineBreaker,     "#{__dir__}/text_engine/line_breaker"
     autoload :Line,            "#{__dir__}/text_engine/line_breaker"

data/lib/idml/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: idml
 version: !ruby/object:Gem::Version
-  version: 0.8.9
+  version: 0.9.1
 platform: ruby
 authors:
 - Ribose
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-17 00:00:00.000000000 Z
+date: 2026-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -407,6 +407,7 @@ files:
 - lib/idml/elements/transform_attribute_option.rb
 - lib/idml/elements/transparency_setting.rb
 - lib/idml/elements/trap_preset.rb
+- lib/idml/elements/typed_value.rb
 - lib/idml/elements/xml_element.rb
 - lib/idml/elements/xml_export_map.rb
 - lib/idml/elements/xml_import_map.rb
@@ -484,6 +485,7 @@ files:
 - lib/idml/text_engine/cjk_layout.rb
 - lib/idml/text_engine/justifier.rb
 - lib/idml/text_engine/line_breaker.rb
+- lib/idml/text_engine/measurement.rb
 - lib/idml/text_engine/pdfrb_font_metrics.rb
 - lib/idml/text_engine/shaper.rb
 - lib/idml/text_engine/vertical_layout.rb