idml 0.6.2 → 0.7.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 46b15814f26a45f5df5c3170df66846ff831727ce3dcf4b7ebe1b1c0377d8c0e
-  data.tar.gz: d4041eacffab33e437330116d3b1268577b6ad8afbc0f2ee4cc1e015c07ec3a4
+  metadata.gz: f43caa091c83d9d8288f22f3913d21760bf5a5dac986f76b72521bb19f5110e0
+  data.tar.gz: 4e33ef7a0c119936d16c0eecb687d153e04d9dc29d789511633fb6fff7f1a152
 SHA512:
-  metadata.gz: 45e7dcb9c7bad255b0bc4fbe2e97e741c7a1b1ff52a6bf899ffdffdf838f310780c1e90832b54f9cbd5a0044b7b908f9c3791fd8274b4272fe1f40506b0ce793
-  data.tar.gz: b928db59ed416b59431bb638e1d86630488247dff7a3aaa6361954029920d3cb053095fdba28d7d7a00ec386e1b7f6153c89a7478135ad44523a3cb000cba840
+  metadata.gz: 16b0f93a7c8993c5f98ad84c6e186ed61ebcaaabcdda63b26c9d1e4bfadd1c3986bef933d2a832d2b3463ab5b23324778a37e92e62cbeb8ce0876dbc26bebcbe
+  data.tar.gz: 9950c7afceda42f377e0d2bef226c4caa346c9d79ac4b3b61dcba99612a321c646eecd6b341be88fd7f8a46c695ecc2449d1bf4d900e4338ed1a4c9f76ea4d45

data/Gemfile

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

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

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

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

@@ -1,6 +1,15 @@
 # TODO PDF 101: Paragraph borders and rules (RuleAbove, RuleBelow, ParagraphBorder)
 
-## Status: OPEN — gap identified in 2026-08-08 audit
+## 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
 

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

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

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

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

data/TODO.pdf/108-multi-frame-story-flow.md

@@ -0,0 +1,50 @@
+# TODO PDF 108: Multi-frame story flow (use StoryThreader)
+
+## Status: OPEN — gap identified in 2026-08-09 audit
+
+## Problem
+
+`Render::StoryThreader` exists with specs (`spec/idml/render_layer_threader_spec.rb`).
+It builds text-frame chains from PreviousTextFrame/NextTextFrame
+links. The intent: a story flows across linked frames, with each
+frame getting the lines that fit and overflow going to the next.
+
+But `TextFrameRenderer` doesn't use it. The renderer treats each
+frame independently:
+- `chain_head?` filter skips non-head frames (correct — they'd
+  double-render)
+- Each chain-head frame renders its entire story from the top
+- Overflow that doesn't fit is silently dropped
+
+For real documents with multi-page stories (books, magazines,
+newspapers), this loses text. The PDF shows only what fits in the
+first frame.
+
+## What needs to happen
+
+1. TextFrameRenderer accepts the chain (list of frames) instead
+   of one frame at a time.
+2. For each chain:
+   - Lay out story text starting at frame 1's top
+   - When text overflows frame 1's bottom, continue at frame 2's top
+   - Repeat until either text ends or chain ends
+3. The PageItemRenderer dispatch needs to know about chains, not
+   just per-item rendering.
+
+Architecture: the chain context needs to live in RenderContext
+(or a new RenderChainContext). Each frame's render call passes the
+current y cursor + remaining paragraphs/runs/lines, and the next
+frame's render call picks up where the previous left off.
+
+## Acceptance criteria
+
+- [ ] Story that overflows frame 1 continues in frame 2.
+- [ ] Hyperlink rects resolve correctly across frames.
+- [ ] Spec: 2 linked TextFrames, story of 50 lines, each frame fits
+      20 lines → frame 1 shows lines 1-20, frame 2 shows 21-40,
+      frame 3 (if present) shows 41-50.
+
+## Dependencies
+
+- None — independent feature work, but changes the renderer's
+  per-frame abstraction significantly.

data/TODO.pdf/109-dry-color-tint.md

@@ -0,0 +1,42 @@
+# TODO PDF 109: DRY color tint application (ColorHelper vs CharacterStyle vs ParagraphRules)
+
+## Status: DONE — `ColorHelper.apply_tint(color, tint)` is the single
+canonical tint helper. CharacterStyle and ParagraphRules both delegate
+to it. 7 new specs cover nil tint, tint >= 1.0, RGB/CMYK scaling,
+tint 0.0, unknown models, nil input.
+
+## Problem
+
+Color tint (scaling a color's components toward zero) is implemented
+in three places with slightly different shapes:
+
+1. `Render::CharacterStyle.apply_tint(color, tint)` — used for
+   text fill color.
+2. `Render::ParagraphRules.scale_color(color, tint_value)` — used
+   for paragraph rule colors.
+3. (Implicit) `Render::ColorResolver` resolves tints on its own
+   when reading ColorValue, before returning the color hash.
+
+The first two are essentially the same logic with different method
+names. The third means a `ColorResolver.resolve` result might or
+might not have tint already applied — callers can't tell.
+
+## What needs to happen
+
+1. Pick one canonical tint helper. Either:
+   - Move to `ColorHelper.apply_tint(color, tint)`, or
+   - Create `Render::ColorTint.apply(color, tint)`.
+2. CharacterStyle and ParagraphRules call the canonical helper.
+3. ColorResolver documents whether it applies tint or returns raw
+   colors (today it appears to apply tint internally).
+
+## Acceptance criteria
+
+- [ ] Single tint helper in one place.
+- [ ] CharacterStyle and ParagraphRules both delegate to it.
+- [ ] ColorResolver's tint behavior is documented.
+- [ ] Spec coverage for tint 0.0, 0.5, 1.0 on RGB and CMYK colors.
+
+## Dependencies
+
+- None — pure refactor.

data/TODO.pdf/110-conditional-text.md

@@ -0,0 +1,37 @@
+# TODO PDF 110: Conditional text (AppliedConditions)
+
+## Status: OPEN — gap identified in 2026-08-09 audit
+
+## Problem
+
+PSR and CSR both carry an `AppliedConditions` attribute (a list of
+condition Self IDs). In InDesign, conditions let authors mark text
+as conditional (e.g., "show only in instructor edition", "draft
+review comments"). Each `<Condition>` in Resources/Styles.xml
+declares whether it's visible, its highlight color, etc.
+
+Today the renderer ignores `AppliedConditions` — all conditional
+text renders regardless of condition visibility. For documents that
+use conditions heavily (textbooks, legal, regulatory), this means
+the PDF always shows every variant instead of the chosen subset.
+
+## What needs to happen
+
+1. Verify `Elements::Condition` exists in the model (Resources/Styles.rnc).
+2. Add `Render::ConditionFilter` that reads visible conditions from
+   Resources/Styles.xml.
+3. StyleResolver filters PSRs/CSRs whose AppliedConditions reference
+   a hidden condition.
+4. Spec: PSR with condition A (hidden) doesn't render; condition B
+   (visible) renders.
+
+## Acceptance criteria
+
+- [ ] Condition model from RNC.
+- [ ] ConditionFilter.from_styles(graphic_or_styles).
+- [ ] StyleResolver.extract_paragraphs takes optional ConditionFilter.
+- [ ] Hidden-condition runs filtered out.
+
+## Dependencies
+
+- None — pure feature work on existing models.

data/TODO.pdf/111-footnote-support.md

@@ -0,0 +1,40 @@
+# TODO PDF 111: Footnote support
+
+## Status: OPEN — gap identified in 2026-08-09 audit
+
+## Problem
+
+IDML has full footnote support:
+- `<Footnote>` elements in Stories (inline footnote markers + text)
+- `<FootnoteOption>` on PSR (numbering rules, layout)
+- `TextFramePreference.FootnotesEnableOverrides`,
+  `FootnotesSpanAcrossColumns`, `FootnotesMinimumSpacing`,
+  `FootnotesSpaceBetween` — frame-level footnote layout
+- `<TextFrameFootnoteOptionsObject>` — per-frame footnote config
+
+The renderer doesn't model footnote content or lay it out.
+Documents with footnotes (academic, legal, technical) currently
+lose footnote text in the PDF.
+
+## What needs to happen
+
+1. Model `<Footnote>` element (story-embedded footnote text +
+   reference marker).
+2. Story parsing extracts footnotes alongside main text.
+3. Footnote text renders at the bottom of the page that contains
+   the reference marker.
+4. Footnote numbering rules from FootnoteOption honored.
+5. Continuous footnotes flow across pages.
+
+This is a large feature — defer until needed by a real fixture.
+
+## Acceptance criteria
+
+- [ ] Footnote text rendered at bottom of containing page.
+- [ ] Footnote marker in body text links to footnote text.
+- [ ] Numbering restarts per document section per FootnoteOption.
+
+## Dependencies
+
+- TODO 108 (multi-frame story flow) — footnotes need to know which
+  page a reference appears on.

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

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

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

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

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

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

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

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

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

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

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

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

data/idml.gemspec

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

data/lib/idml/elements/table.rb

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

data/lib/idml/render/character_style.rb

@@ -0,0 +1,148 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # Applies character-level styling from a `StyleResolver::StyledRun`
+    # around a text-emitting block. Centralizes the IDML → PDF mapping
+    # for run-level visual properties (text color, underline rule,
+    # strike-through rule, capitalization, super/subscript position).
+    #
+    # Used by `TextFrameRenderer` so character-level effects live in
+    # one place (DRY). The block typically calls `canvas.text` (or
+    # `canvas.text_rich`); this helper sets the surrounding graphics
+    # state and emits the rule lines after the block returns.
+    module CharacterStyle
+      UNDERLINE_THICKNESS_FACTOR = 0.05
+      UNDERLINE_DROP_FACTOR = 0.10
+      STRIKE_THICKNESS_FACTOR = 0.05
+      STRIKE_RISE_FACTOR = 0.25
+
+      # Yields with the run's fill color applied, then draws underline
+      # and/or strike-through rules above/below the text baseline.
+      # `x`, `y`, `width`, `size` describe the line's geometry so the
+      # rules can be positioned correctly. The block's emitted text
+      # gets the run's character-level adjustments baked in via
+      # `text_kwargs` (caller passes the canvas.text kwargs in, and
+      # CharacterStyle adds tracking/scale on top).
+      def self.apply(canvas, run, context, x:, y:, width:, size:)
+        apply_fill_color(canvas, run, context)
+        yield
+        draw_underline(canvas, run, x, y, width, size)
+        draw_strike_through(canvas, run, x, y, width, size)
+      end
+
+      # Returns the canvas.text kwargs augmented with the run's
+      # Tracking (PDF char_spacing). IDML Tracking is in points;
+      # pdfrb's char_spacing is also in text-space units, so the
+      # mapping is 1:1.
+      def self.text_kwargs(run, base_kwargs)
+        return base_kwargs unless run.tracking
+
+        base_kwargs.merge(char_spacing: run.tracking.to_f)
+      end
+
+      # Yields within a transformed coordinate space when the run
+      # declares glyph scaling. IDML HorizontalScale/VerticalScale
+      # are percentages (100 = no scaling). When both are 100 / nil,
+      # yields without transformation (no graphics-state push).
+      def self.with_glyph_scaling(canvas, run, &)
+        sx = scale_factor(run.horizontal_scale)
+        sy = scale_factor(run.vertical_scale)
+        return yield if scaling_identity?(sx, sy)
+
+        canvas.scale(sx, sy, &)
+      end
+
+      def self.scaling_identity?(sx, sy)
+        (sx - 1.0).abs < FLOAT_EPSILON && (sy - 1.0).abs < FLOAT_EPSILON
+      end
+
+      FLOAT_EPSILON = 1e-9
+      private_constant :FLOAT_EPSILON
+
+      # Returns the run's baseline shift (in PDF units). Positive
+      # values shift up; negative shift down. Used to offset the
+      # text's `at: y` for CSR's BaselineShift.
+      def self.baseline_offset(run)
+        run.baseline_shift&.nonzero? ? run.baseline_shift.to_f : 0.0
+      end
+
+      # Transforms the text per the CSR's Capitalization attribute.
+      # AllCaps/SmallCaps → uppercase (true small-caps would require
+      # an OpenType feature; deferred). Other values pass through.
+      def self.transform_text(text, capitalization)
+        return text unless %w[AllCaps SmallCaps].include?(capitalization)
+
+        text.upcase
+      end
+
+      # Returns `[font_size, baseline_offset]` for the CSR's Position
+      # attribute. Superscript/subscript shrink the font and shift
+      # the baseline. Normal / nil returns the size unchanged.
+      def self.position_scale(position, font_size)
+        case position
+        when "Superscript" then [font_size * 0.583, font_size * 0.333]
+        when "Subscript" then [font_size * 0.583, -font_size * 0.0833]
+        else [font_size, 0.0]
+        end
+      end
+
+      def self.apply_fill_color(canvas, run, context)
+        return unless run.fill_color
+        return if run.fill_color == "Color/None"
+
+        color = context.color_resolver&.resolve(run.fill_color)
+        return unless color
+
+        tinted = ColorHelper.apply_tint(color, run.fill_tint)
+        canvas.fill_color(ColorHelper.to_canvas(tinted))
+      end
+      private_class_method :apply_fill_color
+
+      def self.scale_factor(declared)
+        return 1.0 unless declared
+        return 1.0 if declared <= 0
+
+        declared.to_f / 100.0
+      end
+      private_class_method :scale_factor
+
+      def self.draw_underline(canvas, run, x, y, width, size)
+        return unless run.underline
+
+        thickness = rule_thickness(run.underline_weight, size,
+                                   UNDERLINE_THICKNESS_FACTOR)
+        drop = rule_offset(run.underline_offset, size,
+                           UNDERLINE_DROP_FACTOR)
+        canvas.rectangle(x, y - drop, width, thickness)
+        canvas.fill
+      end
+      private_class_method :draw_underline
+
+      def self.draw_strike_through(canvas, run, x, y, width, size)
+        return unless run.strike_thru
+
+        thickness = rule_thickness(run.strike_through_weight, size,
+                                   STRIKE_THICKNESS_FACTOR)
+        rise = rule_offset(run.strike_through_offset, size,
+                           STRIKE_RISE_FACTOR)
+        canvas.rectangle(x, y + rise - thickness, width, thickness)
+        canvas.fill
+      end
+      private_class_method :draw_strike_through
+
+      def self.rule_thickness(declared, size, factor)
+        declared&.positive? ? declared : (size * factor)
+      end
+      private_class_method :rule_thickness
+
+      def self.rule_offset(declared, size, factor)
+        return size * factor unless declared
+        return size * factor if declared.zero?
+
+        declared
+      end
+      private_class_method :rule_offset
+    end
+  end
+end

data/lib/idml/render/color_helper.rb

@@ -1,9 +1,10 @@
-# frozen_string_literal: true
+# frozen_string: true
 
 module Idml
   module Render
-    # Converts IDML color hashes to pdfrb Canvas color arrays.
-    # Centralizes the mapping so all renderers use a consistent format.
+    # Converts IDML color hashes to pdfrb Canvas color arrays and
+    # applies tint scaling. Centralizes the mapping so all renderers
+    # use a consistent format.
     module ColorHelper
       module_function
 
@@ -18,6 +19,29 @@ module Idml
         when :cmyk then [:cmyk, color[:c], color[:m], color[:y], color[:k]]
         end
       end
+
+      # Scales a color's components by `tint` (1.0 = full strength,
+      # 0.5 = halved). Tint is the IDML mechanism for lightening a
+      # color without defining a new one. Returns the original color
+      # unchanged when tint is nil or >= 1.0. Single canonical
+      # implementation — CharacterStyle, ParagraphRules, and any
+      # future caller should all delegate here.
+      def apply_tint(color, tint)
+        return color unless color
+        return color unless tint
+        return color if tint >= 1.0
+
+        case color[:model]
+        when :rgb
+          { model: :rgb, r: color[:r] * tint, g: color[:g] * tint,
+            b: color[:b] * tint }
+        when :cmyk
+          { model: :cmyk, c: color[:c] * tint, m: color[:m] * tint,
+            y: color[:y] * tint, k: color[:k] * tint }
+        else
+          color
+        end
+      end
     end
   end
 end