idml 0.8.8 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad2709aae7d11f8a91843141700ab7882b9b7a196480d7b6077fe4f0b6473d16
-  data.tar.gz: b6fd8d8df9996dabd3fd4ffbfc9fb788930cb3ca04bb6f014ae8b3c9fce5b6af
+  metadata.gz: ff487a296f9cbd5b926b963c7acb7d4864d43060ffed5b1ec7438a75bac1446a
+  data.tar.gz: f4926fe3add1833a954628aace986839f101722deafde891783c54afdd509a58
 SHA512:
-  metadata.gz: 20154b884fb1688985cdca3c7a3866e7c55be9059768d4a00eae4058bdd237f3606c964318d224bdd198853bc61a0a9167012b5dc6cc558f4a31537146a45a27
-  data.tar.gz: 7075c7451518b208e6ce17da854fb9954048ed40825287dc87bf4b4543467a0677a277fdf49f124703c353dfc4faf1b770de936d69acf1b0958998887a1cb101
+  metadata.gz: 043ed38d8ebdcf1af8506e83d8548b6590d923f0b4b1ef01687dca5c7528bc5d9a16c79c67e06dc626abe70334afd72882aefac2f15f8253c71d56bc40224274
+  data.tar.gz: 0fefb80560e396290585e3677ca395abd1096511b78321c7ff05ff3add4b5bf0242a4c21ea3321244b7da5290651e369b376696400dc19429ecc547b1c534842

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/106-page-item-type-coverage.md

@@ -1,12 +1,42 @@
 # TODO PDF 106: Page-item type coverage — Ellipse, Path, EPS, WMF, PICT, HtmlItem
 
-## Status: PARTIAL — Oval and Path elements modeled and rendered
-(registered in RENDERER_MAP, delegate to RectangleRenderer which draws
-the bounding box with fill/stroke). Documents containing Oval or Path
-page items no longer silently skip them. True elliptical rendering
-(bezier anchor/control points) and compound-path drawing are
-refinements. EPS / WMF / PICT / HtmlItem remain out of scope (foreign
-formats).
+## Status: COMPLETE (rendering scope) — implemented 2026-08-17
+
+## What was built (2026-08-17 refinement: true contours)
+
+- `Render::Contour` — draws an item's PathGeometry as true Bézier
+  contours: PathPointType anchors, LeftDirection / RightDirection
+  control handles, ItemTransform applied per point, y flipped into
+  PDF space. One subpath per GeometryPathType (compound paths);
+  closed unless PathOpen="true"; degenerate handles fall back to the
+  anchor. OvalRenderer, PathRenderer, and PolygonRenderer all
+  delegate here — ovals render as real ellipses (rotation preserved
+  through the transform), polygons as their actual outlines, Paths
+  as compound contours. Bounding-box rectangle fallback when an
+  item has no PathGeometry but has geometric_bounds.
+- `Render::ShapePaint` — the single owner of the IDML → PDF paint
+  mapping (solid fill, gradient shading fill, stroke styling, and
+  the PDF paint-op sequencing including fill_stroke on one path).
+  RectangleRenderer now delegates to it; the fill/stroke/gradient
+  logic it previously duplicated across shape renderers lives in
+  one place.
+- Oval/Path modeled + registered in RENDERER_MAP (earlier
+  milestone); Polygon renders contours instead of its bounding box.
+
+## Out of scope (unchanged)
+
+- EPS / WMF / PICT / HtmlItem / Movie / Sound / FormField — foreign
+  or interactive formats, not modeled. Image placement goes through
+  ImageCollector (separate, model-driven path).
+
+## Acceptance criteria
+
+- [x] SpreadObject has `oval` + `path` collections (Ellipse is the
+      Oval element in the schema's naming).
+- [x] OvalRenderer / PathRenderer registered in RENDERER_MAP.
+- [x] True Bézier rendering from PathGeometry anchors + control
+      points (TODO 106 refinement complete).
+- [x] Compound Path objects render with multiple sub-paths.
 
 ## Problem
 

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/contour.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # Renders a page item's PathGeometry as true Bézier contours on
+    # a pdfrb canvas. Shared by OvalRenderer, PathRenderer, and
+    # PolygonRenderer: every item whose Properties carry a
+    # PathGeometry draws its actual outline — PathPointType anchors
+    # with LeftDirection / RightDirection control handles,
+    # ItemTransform applied, y flipped into PDF space — instead of
+    # its bounding box. Paint op selection (fill / stroke /
+    # gradient) lives in ShapePaint. Items without usable geometry
+    # fall back to the bounding-box rectangle.
+    module Contour
+      # Renders the item's contours with fill/stroke from
+      # ShapePaint. Returns true when painted.
+      def self.render(canvas, context)
+        item = context.item
+        return false if item.visible == false
+
+        paths = geometry_paths(item)
+        return rectangle_fallback(canvas, item, context) if paths.empty?
+
+        ShapePaint.paint(canvas, item, context) do |c|
+          draw_path(c, paths, item.item_transform, context.page_height)
+        end
+      end
+
+      def self.rectangle_fallback(canvas, item, context)
+        box = Placement.box(item, context.page_height)
+        return false unless box
+
+        ShapePaint.paint(canvas, item, context) do |c|
+          c.rectangle(box[:x], box[:y], box[:width], box[:height])
+        end
+      end
+      private_class_method :rectangle_fallback
+
+      # All GeometryPathType children across the item's Properties.
+      def self.geometry_paths(item)
+        item.properties.flat_map do |props|
+          props.path_geometry.flat_map(&:geometry_path_type)
+        end
+      end
+
+      # Constructs the full path on the canvas: one subpath per
+      # GeometryPathType, each starting at its first anchor and
+      # curving through every subsequent anchor via the points'
+      # control handles. Closed paths (PathOpen false or absent)
+      # loop back to the first anchor and close.
+      def self.draw_path(canvas, paths, item_transform, page_height)
+        transform = Geometry.parse_transform(item_transform)
+        paths.each do |path|
+          draw_subpath(canvas, path, transform, page_height)
+        end
+      end
+
+      def self.draw_subpath(canvas, path, transform, page_height)
+        points = path.points
+        return if points.length < 2
+
+        open = path.path_open == true
+        anchors = points.map do |point|
+          pdf_pair(point.anchor, transform, page_height)
+        end
+        canvas.move_to(anchors.first[0], anchors.first[1])
+        draw_segments(canvas, points, anchors, transform, page_height, open)
+        canvas.close_path unless open
+      end
+      private_class_method :draw_subpath
+
+      def self.draw_segments(canvas, points, anchors, transform,
+                             page_height, open)
+        segment_count = open ? points.length - 1 : points.length
+        segment_count.times do |index|
+          from = points[index]
+          to = points[(index + 1) % points.length]
+          c1 = control_point(from, :right_direction, from.anchor,
+                             transform, page_height)
+          c2 = control_point(to, :left_direction, to.anchor,
+                             transform, page_height)
+          to_anchor = anchors[(index + 1) % points.length]
+          canvas.curve_to(c1[0], c1[1], c2[0], c2[1],
+                          to_anchor[0], to_anchor[1])
+        end
+      end
+      private_class_method :draw_segments
+
+      # Control point for one end of a segment: the point's
+      # direction handle when present, else the anchor itself
+      # (degenerate control = straight-ish curve).
+      def self.control_point(point, direction_attr, fallback, transform,
+                             page_height)
+        raw = point.public_send(direction_attr)
+        raw = nil if raw && raw.strip.empty?
+        pdf_pair(raw || fallback, transform, page_height)
+      end
+      private_class_method :control_point
+
+      # Parses an IDML "x y" pair, applies the item transform, and
+      # flips y into PDF space (origin bottom-left).
+      def self.pdf_pair(raw, transform, page_height)
+        x, y = raw.to_s.split(/\s+/).map(&:to_f)
+        tx, ty = Geometry.apply_transform(transform, x, y)
+        [tx, page_height - ty]
+      end
+      private_class_method :pdf_pair
+    end
+  end
+end

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/oval_renderer.rb

@@ -3,14 +3,13 @@
 module Idml
   module Render
     module Renderers
-      # Renders an IDML Oval on a Pdfrb::Content::Canvas. Delegates to
-      # RectangleRenderer which draws the bounding box with fill/stroke.
-      # Approximation: a true ellipse would generate bezier anchor and
-      # control points from the PathGeometry; the bounding box renders
-      # the correct extent and colors. See TODO 106 for refinement.
+      # Renders an IDML Oval on a Pdfrb::Content::Canvas as a true
+      # Bézier ellipse from its PathGeometry (which preserves any
+      # rotation in the ItemTransform). Falls back to the
+      # bounding-box rectangle when the item carries no geometry.
       class OvalRenderer
         def self.render(canvas, context)
-          RectangleRenderer.render(canvas, context)
+          Contour.render(canvas, context)
         end
       end
     end

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

@@ -4,14 +4,13 @@ module Idml
   module Render
     module Renderers
       # Renders an IDML Path (standalone compound path) on a
-      # Pdfrb::Content::Canvas. Delegates to RectangleRenderer which
-      # draws the bounding box with fill/stroke. Approximation: a true
-      # compound path would draw each sub-path from the EntirePath
-      # list or PathPoint children; the bounding box renders the
-      # correct extent and colors. See TODO 106 for refinement.
+      # Pdfrb::Content::Canvas as its actual Bézier contours — one
+      # subpath per GeometryPathType, closed or open per PathOpen.
+      # Falls back to the bounding-box rectangle when the item
+      # carries no geometry.
       class PathRenderer
         def self.render(canvas, context)
-          RectangleRenderer.render(canvas, context)
+          Contour.render(canvas, context)
         end
       end
     end

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

@@ -3,46 +3,15 @@
 module Idml
   module Render
     module Renderers
+      # Renders an IDML Polygon on a Pdfrb::Content::Canvas as its
+      # actual Bézier contours from PathGeometry (control handles
+      # default to the anchors, so plain polygons render straight
+      # edges). Falls back to the bounding-box rectangle when the
+      # item carries no geometry.
       class PolygonRenderer
         def self.render(canvas, context)
-          poly = context.item
-          return if poly.visible == false
-
-          box = Placement.box(poly, context.page_height)
-          return unless box
-
-          Blending.wrap(canvas, poly.transparency_setting) do
-            render_fill(canvas, poly, context, box)
-            render_stroke(canvas, poly, context, box)
-          end
-        end
-
-        def self.render_fill(canvas, poly, context, box)
-          return unless poly.fill_color && poly.fill_color != "Color/None"
-
-          color = context.color_resolver&.resolve(poly.fill_color)
-          return unless color
-
-          canvas.fill_color(ColorHelper.to_canvas(color))
-          canvas.rectangle(box[:x], box[:y], box[:width], box[:height])
-          canvas.fill
-        end
-        private_class_method :render_fill
-
-        def self.render_stroke(canvas, poly, context, box)
-          return unless StrokeStyle.strokeable?(poly)
-
-          color = context.color_resolver&.resolve(poly.stroke_color)
-          return unless color
-
-          StrokeStyle.apply(canvas, poly) do
-            canvas.stroke_color(ColorHelper.to_canvas(color))
-            canvas.line_width = poly.stroke_weight
-            canvas.rectangle(box[:x], box[:y], box[:width], box[:height])
-            canvas.stroke
-          end
+          Contour.render(canvas, context)
         end
-        private_class_method :render_stroke
       end
     end
   end

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

@@ -3,7 +3,9 @@
 module Idml
   module Render
     module Renderers
-      # Renders an IDML Rectangle on a Pdfrb::Content::Canvas.
+      # Renders an IDML Rectangle on a Pdfrb::Content::Canvas: an
+      # axis-aligned rectangle from the item's placement box, with
+      # fill / stroke / gradient painting delegated to ShapePaint.
       class RectangleRenderer
         def self.render(canvas, context)
           rect = context.item
@@ -12,101 +14,10 @@ module Idml
           box = Placement.box(rect, context.page_height)
           return unless box
 
-          Blending.wrap(canvas, rect.transparency_setting) do
-            render_fill(canvas, rect, context, box)
-            render_stroke(canvas, rect, context, box)
+          ShapePaint.paint(canvas, rect, context) do |c|
+            c.rectangle(box[:x], box[:y], box[:width], box[:height])
           end
         end
-
-        def self.render_fill(canvas, rect, context, box)
-          return unless rect.fill_color
-          return if rect.fill_color == "Color/None"
-
-          if GradientResolver.gradient?(rect.fill_color)
-            render_gradient_fill(canvas, rect, context, box)
-            return
-          end
-
-          color = context.color_resolver&.resolve(rect.fill_color)
-          return unless color
-
-          canvas.fill_color(ColorHelper.to_canvas(color))
-          canvas.rectangle(box[:x], box[:y], box[:width], box[:height])
-          canvas.fill
-        end
-        private_class_method :render_fill
-
-        def self.render_gradient_fill(canvas, rect, context, box)
-          gradient = gradient_for(rect, context)
-          return unless gradient
-          return unless gradient.gradient_stop.length >= 2
-
-          stops = gradient_stops(gradient, context)
-          return unless stops.length >= 2
-
-          shading = if gradient.type == "Radial"
-                      radial_shading(canvas, box, stops)
-                    else
-                      axial_shading(canvas, box, stops)
-                    end
-          canvas.rectangle(box[:x], box[:y], box[:width], box[:height])
-          canvas.fill_shading(shading)
-        end
-        private_class_method :render_gradient_fill
-
-        def self.axial_shading(canvas, box, stops)
-          canvas.document.shadings.add_axial(
-            from: [box[:x], box[:y] + box[:height]],
-            to: [box[:x] + box[:width], box[:y]],
-            stops: stops,
-          )
-        end
-        private_class_method :axial_shading
-
-        def self.radial_shading(canvas, box, stops)
-          cx = box[:x] + (box[:width] / 2.0)
-          cy = box[:y] + (box[:height] / 2.0)
-          radius = [box[:width], box[:height]].max / 2.0
-          canvas.document.shadings.add_radial(
-            from: [cx, cy, 0.0],
-            to: [cx, cy, radius],
-            stops: stops,
-          )
-        end
-        private_class_method :radial_shading
-
-        def self.gradient_for(rect, context)
-          graphic = context.package&.graphic
-          return nil unless graphic
-
-          graphic.gradient.find { |g| g.self_attr == rect.fill_color }
-        end
-        private_class_method :gradient_for
-
-        def self.gradient_stops(gradient, context)
-          gradient.gradient_stop.filter_map do |stop|
-            color = context.color_resolver&.resolve(stop.stop_color)
-            next unless color
-
-            [stop.location || 0.0, ColorHelper.to_canvas(color)]
-          end
-        end
-        private_class_method :gradient_stops
-
-        def self.render_stroke(canvas, rect, context, box)
-          return unless StrokeStyle.strokeable?(rect)
-
-          color = context.color_resolver&.resolve(rect.stroke_color)
-          return unless color
-
-          StrokeStyle.apply(canvas, rect) do
-            canvas.stroke_color(ColorHelper.to_canvas(color))
-            canvas.line_width = rect.stroke_weight
-            canvas.rectangle(box[:x], box[:y], box[:width], box[:height])
-            canvas.stroke
-          end
-        end
-        private_class_method :render_stroke
       end
     end
   end

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

@@ -445,6 +445,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 +469,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,

data/lib/idml/render/shape_paint.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # Paints a page item's fill and stroke on a pdfrb canvas,
+    # delegating path construction to the caller's block. The
+    # single owner of the IDML → PDF paint mapping — solid fill,
+    # gradient shading fill, stroke styling — shared by every
+    # shape renderer. Callers choose the geometry (axis-aligned
+    # rectangle, Bézier contour); this module chooses the paint
+    # and the PDF paint op sequencing (fill, stroke, or
+    # fill-and-stroke on one path).
+    module ShapePaint
+      # Paints the item. The block receives the canvas and must
+      # construct the current path (move_to/line_to/curve_to/...).
+      # The block may be called more than once (a path is consumed
+      # by each paint op, so fill-then-stroke rebuilds it).
+      # Returns nil when there is nothing to paint; truthy
+      # otherwise.
+      def self.paint(canvas, item, context, &build_path)
+        fill = fill_style(item, context)
+        stroke = stroke_style(item, context)
+        return unless fill || stroke
+
+        Blending.wrap(canvas, item.transparency_setting) do
+          paint_styles(canvas, item, context, fill, stroke, &build_path)
+        end
+      end
+
+      # Returns the fill plan: { kind: :solid, color: } for a
+      # resolved color, { kind: :gradient, gradient:, stops: } for
+      # a fill referencing a Gradient, nil when nothing fillable.
+      def self.fill_style(item, context)
+        return nil unless item.fill_color
+        return nil if item.fill_color == "Color/None"
+
+        if GradientResolver.gradient?(item.fill_color)
+          gradient_fill_style(item, context)
+        else
+          solid_fill_style(item, context)
+        end
+      end
+      private_class_method :fill_style
+
+      def self.gradient_fill_style(item, context)
+        gradient = gradient_for(item, context)
+        return nil unless gradient
+
+        stops = gradient_stops(gradient, context)
+        return nil unless stops.length >= 2
+
+        { kind: :gradient, gradient: gradient, stops: stops }
+      end
+      private_class_method :gradient_fill_style
+
+      def self.solid_fill_style(item, context)
+        color = context.color_resolver&.resolve(item.fill_color)
+        return nil unless color
+
+        { kind: :solid, color: ColorHelper.to_canvas(color) }
+      end
+      private_class_method :solid_fill_style
+
+      def self.stroke_style(item, context)
+        return nil unless StrokeStyle.strokeable?(item)
+
+        color = context.color_resolver&.resolve(item.stroke_color)
+        return nil unless color
+
+        { color: ColorHelper.to_canvas(color) }
+      end
+      private_class_method :stroke_style
+
+      def self.paint_styles(canvas, item, context, fill, stroke, &)
+        if fill && stroke
+          paint_fill_and_stroke(canvas, item, context, fill, stroke,
+                                &)
+        elsif fill
+          paint_fill(canvas, item, context, fill, &)
+        else
+          paint_stroke(canvas, item, stroke, &)
+        end
+      end
+      private_class_method :paint_styles
+
+      def self.paint_fill(canvas, item, context, fill, &)
+        yield(canvas)
+        if fill[:kind] == :gradient
+          canvas.fill_shading(shading_for(canvas, item, context, fill))
+        else
+          canvas.fill_color(fill[:color])
+          canvas.fill
+        end
+      end
+      private_class_method :paint_fill
+
+      def self.paint_stroke(canvas, item, stroke, &)
+        StrokeStyle.apply(canvas, item) do
+          canvas.stroke_color(stroke[:color])
+          canvas.line_width = item.stroke_weight
+          yield(canvas)
+          canvas.stroke
+        end
+      end
+      private_class_method :paint_stroke
+
+      # Fill and stroke on one path where possible (fill_stroke);
+      # a gradient fill consumes the path, so the stroke rebuilds
+      # it afterward.
+      def self.paint_fill_and_stroke(canvas, item, context, fill, stroke,
+                                     &)
+        if fill[:kind] == :gradient
+          paint_fill(canvas, item, context, fill, &)
+          paint_stroke(canvas, item, stroke, &)
+        else
+          yield(canvas)
+          canvas.fill_color(fill[:color])
+          StrokeStyle.apply(canvas, item) do
+            canvas.stroke_color(stroke[:color])
+            canvas.line_width = item.stroke_weight
+            canvas.fill_stroke
+          end
+        end
+      end
+      private_class_method :paint_fill_and_stroke
+
+      def self.shading_for(canvas, item, context, fill)
+        box = Placement.box(item, context.page_height)
+        stops = fill[:stops]
+        if fill[:gradient].type == "Radial"
+          canvas.document.shadings.add_radial(
+            from: radial_center(box, 0.0),
+            to: radial_center(box, [box[:width], box[:height]].max / 2.0),
+            stops: stops,
+          )
+        else
+          canvas.document.shadings.add_axial(
+            from: [box[:x], box[:y] + box[:height]],
+            to: [box[:x] + box[:width], box[:y]],
+            stops: stops,
+          )
+        end
+      end
+      private_class_method :shading_for
+
+      def self.radial_center(box, radius)
+        cx = box[:x] + (box[:width] / 2.0)
+        cy = box[:y] + (box[:height] / 2.0)
+        [cx, cy, radius]
+      end
+      private_class_method :radial_center
+
+      def self.gradient_for(item, context)
+        graphic = context.package&.graphic
+        return nil unless graphic
+
+        graphic.gradient.find { |g| g.self_attr == item.fill_color }
+      end
+      private_class_method :gradient_for
+
+      def self.gradient_stops(gradient, context)
+        gradient.gradient_stop.filter_map do |stop|
+          color = context.color_resolver&.resolve(stop.stop_color)
+          next unless color
+
+          [stop.location || 0.0, ColorHelper.to_canvas(color)]
+        end
+      end
+      private_class_method :gradient_stops
+    end
+  end
+end

data/lib/idml/render/style_resolver.rb

@@ -82,6 +82,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 +193,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 +208,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 +220,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)

data/lib/idml/render.rb

@@ -23,6 +23,8 @@ module Idml
     autoload :ConditionFilter,     "#{__dir__}/render/condition_filter"
     autoload :TextWrapResolver,    "#{__dir__}/render/text_wrap_resolver"
     autoload :Footnote,            "#{__dir__}/render/footnote"
+    autoload :ShapePaint,          "#{__dir__}/render/shape_paint"
+    autoload :Contour,             "#{__dir__}/render/contour"
     autoload :Placement,           "#{__dir__}/render/placement"
     autoload :ImageCollector,      "#{__dir__}/render/image_collector"
     autoload :StructureTracker,    "#{__dir__}/render/structure_tracker"

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.8"
+  VERSION = "0.9.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: idml
 version: !ruby/object:Gem::Version
-  version: 0.8.8
+  version: 0.9.0
 platform: ruby
 authors:
 - Ribose
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-16 00:00:00.000000000 Z
+date: 2026-08-17 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
@@ -439,6 +440,7 @@ files:
 - lib/idml/render/color_helper.rb
 - lib/idml/render/color_resolver.rb
 - lib/idml/render/condition_filter.rb
+- lib/idml/render/contour.rb
 - lib/idml/render/drop_cap.rb
 - lib/idml/render/font_reference_resolver.rb
 - lib/idml/render/font_setup.rb
@@ -469,6 +471,7 @@ files:
 - lib/idml/render/renderers/rectangle_renderer.rb
 - lib/idml/render/renderers/table_renderer.rb
 - lib/idml/render/renderers/text_frame_renderer.rb
+- lib/idml/render/shape_paint.rb
 - lib/idml/render/spread_renderer.rb
 - lib/idml/render/story_chain_controller.rb
 - lib/idml/render/story_threader.rb
@@ -482,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