idml 0.7.1 → 0.7.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f43caa091c83d9d8288f22f3913d21760bf5a5dac986f76b72521bb19f5110e0
-  data.tar.gz: 4e33ef7a0c119936d16c0eecb687d153e04d9dc29d789511633fb6fff7f1a152
+  metadata.gz: 66e6127aeed8e54926e01cacb67c81445565c1e43a558015fd9740e022c12372
+  data.tar.gz: 20b6dcdef5ee316ca394a2b062ed0dac2db9137e08e28f7649944623420e3938
 SHA512:
-  metadata.gz: 16b0f93a7c8993c5f98ad84c6e186ed61ebcaaabcdda63b26c9d1e4bfadd1c3986bef933d2a832d2b3463ab5b23324778a37e92e62cbeb8ce0876dbc26bebcbe
-  data.tar.gz: 9950c7afceda42f377e0d2bef226c4caa346c9d79ac4b3b61dcba99612a321c646eecd6b341be88fd7f8a46c695ecc2449d1bf4d900e4338ed1a4c9f76ea4d45
+  metadata.gz: 94180fd8ac2231198178f40f2051d4e1bd9c56d917cd271808fc87f7de66746739c4ecad65e23f6bbb57be539f061ff5ef9abfda56e71a2bb23ddc403ac3d9a5
+  data.tar.gz: 353fcc512f92ed689fc1e41cabf4fe9310bcb5ce0464be24b0be6a452c1559f860201c7132318bb3fd4be9c510eed63ebb98f056b927b9e781bffcfc2123f632

data/TODO.pdf/103-drop-caps.md

@@ -1,6 +1,17 @@
 # TODO PDF 103: Drop caps (DropCapLines, DropCapCharacters)
 
-## Status: OPEN — gap identified in 2026-08-08 audit
+## Status: PARTIAL — `Render::DropCap` helper computes drop-cap
+geometry (font_size = base × lines, width via font_metrics.measure_text,
+height = leading × lines). TextFrameRenderer.emit_drop_cap emits the
+drop cap as an enlarged glyph at the paragraph's top-left when the
+paragraph declares DropCapLines/DropCapCharacters > 0 and is the
+chain's first paragraph.
+
+Wrap-around text is NOT yet implemented — the drop cap renders as an
+enlarged glyph; subsequent paragraph text flows normally and may
+overlap the drop cap. Real wrap-around (indent lines 1..M to the
+right of the drop cap) requires per-line wrap-width control in
+VerticalLayout, which is a bigger refactor. Tracked as follow-up.
 
 ## Problem
 

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

@@ -1,6 +1,10 @@
 # TODO PDF 108: Multi-frame story flow (use StoryThreader)
 
-## Status: OPEN — gap identified in 2026-08-09 audit
+## Status: DONE — `Render::StoryChainController` threads paragraph/run
+state across linked TextFrames. TextFrameRenderer no longer treats
+chain non-heads as standalone; it picks up leftover state from the
+controller, renders what fits, and stores the new leftover for the
+next frame. Overflow text is no longer silently dropped.
 
 ## Problem
 

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

@@ -1,6 +1,12 @@
 # TODO PDF 110: Conditional text (AppliedConditions)
 
-## Status: OPEN — gap identified in 2026-08-09 audit
+## Status: DONE — `Elements::Condition` models the `<Condition>`
+element from designmap.rnc. `Render::ConditionFilter` indexes
+conditions by Self and answers `visible?(applied_conditions_string)`
+per run. `StyleResolver.extract_paragraphs` takes optional
+`condition_filter:` kwarg and drops PSRs/CSRs whose AppliedConditions
+reference a hidden Condition. Pipeline constructs the filter from
+`designmap.condition` and threads it through RenderContext.
 
 ## Problem
 

data/TODO.pdf/112-text-frame-vertical-justification.md

@@ -0,0 +1,53 @@
+# TODO PDF 112: TextFrame vertical justification (TopAlign / CenterAlign / BottomAlign / JustifyAlign)
+
+## Status: DONE for TopAlign / CenterAlign / BottomAlign. JustifyAlign
+defers to TopAlign (inter-paragraph space distribution not yet
+implemented). Content height is approximated by treating each run
+as one line — wrap may produce more lines, so slack is over-estimated;
+we'd rather under-offset than overflow.
+
+## Problem
+
+`Elements::TextFramePreference` carries `VerticalJustification`
+(attribute VerticalJustification on TextFramePreference_Object in
+Styles.rnc). Possible values: TopAlign, CenterAlign, BottomAlign,
+JustifyAlign.
+
+Today TextFrameRenderer always starts text at the top of the frame
+(`cursor_y = box[:y] + box[:height] - inset_top`). For
+`VerticalJustification="CenterAlign"` documents, the entire text
+block should be vertically centered within the frame's text area;
+for `BottomAlign`, text sits at the bottom.
+
+This is a common layout requirement — callouts, captions, footers,
+and sidebars often use bottom or center vertical justification.
+
+## What needs to happen
+
+1. `TextFrameRenderer#engine_render` reads
+   `frame.text_frame_preference.vertical_justification`.
+2. Compute the total content height (sum of all paragraph heights +
+   space_before/after).
+3. If VerticalJustification is CenterAlign: top-offset =
+   (frame_text_area_height - content_height) / 2.
+4. If BottomAlign: top-offset = (frame_text_area_height - content_height).
+5. Adjust the initial `cursor_y` by top-offset before laying out
+   the first paragraph.
+6. JustifyAlign: distribute extra vertical space between paragraphs
+   (more complex — defer).
+
+## Acceptance criteria
+
+- [ ] TextFrame with VerticalJustification="CenterAlign" centers
+      text vertically in the frame.
+- [ ] TextFrame with VerticalJustification="BottomAlign" aligns
+      text to the bottom.
+- [ ] TextFrame with VerticalJustification="TopAlign" (default)
+      renders as today.
+- [ ] Spec coverage per value.
+
+## Dependencies
+
+- TODO 108 (multi-frame story flow) — content_height calculation
+  needs to consider all paragraphs that will render, which the
+  chain state already tracks.

data/TODO.pdf/113-multi-column-text-frames.md

@@ -0,0 +1,48 @@
+# TODO PDF 113: Multi-column text frames (TextColumnCount, TextColumnGutter)
+
+## Status: OPEN — gap identified in 2026-08-10 audit
+
+## Problem
+
+`Elements::TextFramePreference` declares:
+- `TextColumnCount` — number of text columns in the frame (1-40)
+- `TextColumnGutter` — gap between columns (in points)
+- `TextColumnFixedWidth` — width of each column when uniform
+- `UseFixedColumnWidth` — boolean
+- `UseFlexibleColumnWidth` — boolean
+- `TextColumnMaxWidth` — max column width when flexible
+
+Real-world documents frequently use multi-column layouts
+(magazines, newspapers, technical reports, brochures). Today the
+renderer treats every text frame as a single column, ignoring
+TextColumnCount > 1.
+
+Effect: multi-column stories render as one wide column that over-
+laps adjacent content. The PDF is unreadable for multi-column docs.
+
+## What needs to happen
+
+1. `TextFrameRenderer` reads `text_frame_preference.text_column_count`.
+2. When > 1: split the frame's text area into N columns separated
+   by `text_column_gutter`.
+3. Render text column-by-column: column 1 fills top-to-bottom,
+   overflow continues at top of column 2, etc.
+4. StoryThreader chain state threads across columns WITHIN a frame
+   before crossing to the next frame.
+5. Optional: support TextColumnFixedWidth vs flexible-width
+   distribution.
+
+Architecture: this combines TODO 108 (chain flow) with column
+awareness. Each column acts like a mini-frame in the chain.
+
+## Acceptance criteria
+
+- [ ] TextFrame with TextColumnCount=2 renders two side-by-side columns.
+- [ ] Text overflows from column 1 → column 2 → next frame.
+- [ ] TextColumnGutter honored as the gap between columns.
+- [ ] Single-column frames render as today.
+
+## Dependencies
+
+- TODO 108 (multi-frame story flow) — column-to-column flow uses
+  the same chain state mechanism.

data/TODO.pdf/114-text-wrap-around-shapes.md

@@ -0,0 +1,50 @@
+# TODO PDF 114: Text wrap around shapes (TextWrapPreference)
+
+## Status: OPEN — gap identified in 2026-08-10 audit
+
+## Problem
+
+IDML page items (Rectangle, Polygon, GraphicLine, Group, Image, EPS)
+can declare a `<TextWrapPreference>` child that controls how text
+in neighboring TextFrames wraps around the item. Settings include:
+
+- WrapMode: None / Jump / Next / Bounding Box / Shape / Drop Cap
+- Contour: the wrap boundary (could differ from the visual shape)
+- Inverse: text wraps INSIDE the contour (rare)
+- OffsetTop/Left/Bottom/Right: additional margin around the contour
+
+Real documents wrap text around images and callout boxes constantly.
+Without text wrap support, overlapping items produce unreadable
+output — text from one frame runs over a graphic in another.
+
+Today TextFrameRenderer knows nothing about TextWrapPreference on
+other page items. It renders into the frame's full geometric
+rectangle regardless of overlapping wrap contours.
+
+## What needs to happen
+
+1. `Render::TextWrapResolver` reads TextWrapPreference from all
+   page items in the spread and indexes their contours by Self.
+2. Per TextFrame: compute the intersection of the frame's text area
+   with all wrap contours in the spread.
+3. TextFrameRenderer queries the resolver per text line; each line's
+   wrap width is reduced by the overlap on the left and right.
+4. Lines that fall entirely inside a wrap region are skipped.
+
+This is a substantial feature — wrap computation is non-trivial
+(geometry intersection, contour following). Most documents use a
+simple Bounding Box mode (rectangle subtract), which is tractable.
+
+## Acceptance criteria
+
+- [ ] TextWrapMode="BoundingBox" with an image inside the frame's
+      bounds reduces wrap width on affected lines.
+- [ ] TextWrapMode="None" (default) renders as today.
+- [ ] OffsetTop/Left/Bottom/Right honored (expands the contour by
+      the offsets).
+
+## Dependencies
+
+- TODO 108 (multi-frame story flow) — wrap-aware wrap width needs
+  to combine with chain-threaded line layout.
+- TODO 113 (multi-column) — wrap interacts with column boundaries.

data/TODO.pdf/115-bullet-numbered-lists.md

@@ -0,0 +1,46 @@
+# TODO PDF 115: Bullet and numbered list rendering
+
+## Status: OPEN — gap identified in 2026-08-10 audit
+
+## Problem
+
+`Elements::ParagraphStyleRange` carries a large set of bullets and
+numbering attributes (BulletsAndNumberingListType, NumberingExpression,
+BulletsTextAfter, NumberingLevel, NumberingContinue, NumberingStartAt,
+BulletsAlignment, NumberingAlignment, BulletCharacterType,
+BulletCharacterValue, RestartPolicy, LowerLevel, UpperLevel).
+
+The renderer ignores all of these. Lists appear in the PDF as plain
+paragraphs without bullet markers or numbering.
+
+Real documents (technical specs, tutorials, procedures, contracts)
+use lists extensively.
+
+## What needs to happen
+
+1. Read BulletsAndNumberingListType from PSR:
+   - "BulletList" → emit a bullet glyph at the paragraph's start
+   - "NumberedList" → emit a number/letter at the paragraph's start
+2. Apply BulletsAlignment (left/center/right) within a hanging-indent
+   gutter.
+3. Auto-increment numbering per NumberingLevel +
+   NumberingContinue + NumberingStartAt rules.
+4. Honor RestartPolicy for sub-list restart behavior.
+5. BulletCharacterValue picks the glyph (Unicode codepoint).
+
+Architecture: list markers prepend the paragraph's first run; the
+renderer needs an in-memory counter per numbering chain (similar
+to StoryChainController).
+
+## Acceptance criteria
+
+- [ ] PSR with BulletsAndNumberingListType="BulletList" renders a
+      bullet glyph before the paragraph's first character.
+- [ ] PSR with BulletsAndNumberingListType="NumberedList" renders
+      a sequential number, auto-incremented per chain.
+- [ ] BulletsTextAfter (e.g., ". ", ") ") honored as the marker's
+      suffix.
+
+## Dependencies
+
+- None — independent feature work on PSR.

data/lib/idml/elements/condition.rb

@@ -0,0 +1,31 @@
+# frozen_string: true
+
+module Idml
+  module Elements
+    # `<Condition>` — a single condition declared in `designmap.xml`.
+    # Authors tag text runs with one or more conditions (the CSR's
+    # `AppliedConditions` attribute is a list of condition Self IDs).
+    # The condition's `Visible` flag controls whether tagged text
+    # appears in the rendered output.
+    #
+    # Schema: `Condition_Object` in
+    # `reference-docs/schemas/package/designmap.rnc`.
+    class Condition < Lutaml::Model::Serializable
+      attribute :self_attr, :string
+      attribute :name, :string
+      attribute :indicator_method, :string
+      attribute :underline_indicator_appearance, :string
+      attribute :visible, :boolean, default: true
+
+      xml do
+        root "Condition"
+        map_attribute "Self", to: :self_attr
+        map_attribute "Name", to: :name
+        map_attribute "IndicatorMethod", to: :indicator_method
+        map_attribute "UnderlineIndicatorAppearance",
+                      to: :underline_indicator_appearance
+        map_attribute "Visible", to: :visible
+      end
+    end
+  end
+end

data/lib/idml/elements.rb

@@ -17,6 +17,7 @@ module Idml
     autoload :ButtonPreference, "idml/elements/pref_button_preference"
     autoload :Bookmark, "idml/elements/bookmark"
     autoload :Cell, "idml/elements/cell"
+    autoload :Condition, "idml/elements/condition"
     autoload :CellStyle, "idml/elements/cell_style"
     autoload :CellStyleGroup, "idml/elements/cell_style_group"
     autoload :ChapterNumberPreference,

data/lib/idml/parts/designmap.rb

@@ -48,6 +48,7 @@ module Idml
 
       attribute :layer, Idml::Elements::Layer, collection: true
       attribute :bookmark, Idml::Elements::Bookmark, collection: true
+      attribute :condition, Idml::Elements::Condition, collection: true
       attribute :hyperlink, Idml::Elements::Hyperlink, collection: true
       attribute :hyperlink_page_destination,
                 Idml::Elements::HyperlinkPageDestination, collection: true
@@ -92,6 +93,7 @@ module Idml
         map_attribute "ActiveProcess", to: :active_process
         map_element "Layer", to: :layer
         map_element "Bookmark", to: :bookmark
+        map_element "Condition", to: :condition
         map_element "Hyperlink", to: :hyperlink
         map_element "HyperlinkPageDestination",
                     to: :hyperlink_page_destination

data/lib/idml/render/condition_filter.rb

@@ -0,0 +1,57 @@
+# frozen_string: true
+
+module Idml
+  module Render
+    # Resolves whether a styled run should render based on its
+    # AppliedConditions and the visibility flags declared on the
+    # corresponding `<Condition>` elements in `designmap.xml`.
+    #
+    # A run is visible when either:
+    # - It has no AppliedConditions (the common case), OR
+    # - Every condition it references is itself Visible.
+    #
+    # A run is hidden when ANY referenced condition is hidden. This
+    # matches InDesign's "hide any text the user has toggled off"
+    # semantics.
+    #
+    # Construction: `ConditionFilter.from_designmap(designmap)`
+    # reads the condition collection and indexes by Self. Use
+    # `filter.visible?(applied_conditions_string)` per run; pass nil
+    # or empty string for untagged runs.
+    class ConditionFilter
+      def self.from_designmap(designmap)
+        conditions = designmap ? designmap.condition : []
+        new(conditions)
+      end
+
+      def initialize(conditions)
+        @visibility_by_self = conditions.to_h do |cond|
+          [cond.self_attr, condition_visible?(cond)]
+        end
+      end
+
+      # `applied_conditions` is the raw PSR/CSR string. IDML encodes
+      # it as a space-separated list of condition Self IDs. Returns
+      # true when the run should render.
+      def visible?(applied_conditions)
+        return true if applied_conditions.nil?
+        return true if applied_conditions.strip.empty?
+
+        applied_conditions.split.uniq.all? do |cond_self|
+          condition_visible?(cond_self)
+        end
+      end
+
+      private
+
+      # A condition is visible when explicitly Visible="true" OR when
+      # the Visibility flag is unset (default true). Only an explicit
+      # Visible="false" hides it.
+      def condition_visible?(cond_or_self)
+        return @visibility_by_self.fetch(cond_or_self, true) if cond_or_self.is_a?(String)
+
+        cond_or_self.visible.nil? || cond_or_self.visible
+      end
+    end
+  end
+end

data/lib/idml/render/drop_cap.rb

@@ -0,0 +1,83 @@
+# frozen_string: true
+
+module Idml
+  module Render
+    # Computes drop-cap geometry for a paragraph. IDML's DropCapLines
+    # (M) and DropCapCharacters (N) declare that the first N
+    # characters of the paragraph should render at M-lines-tall and
+    # the next M text lines should wrap to the right of the drop cap.
+    #
+    # The helper returns a `DropCapLayout` struct with the drop cap
+    # text, font size, width (for wrap offset), and total height.
+    # Returns nil when the paragraph doesn't declare drop caps.
+    module DropCap
+      DropCapLayout = Struct.new(
+        :text, :width, :height, :font_size, :wrap_offset, :lines,
+        keyword_init: true
+      )
+
+      # Returns a DropCapLayout for the paragraph, or nil when drop
+      # caps aren't declared. `font_metrics` measures the drop-cap
+      # text's natural width. `base_size` is the paragraph's normal
+      # font size (drop cap is enlarged relative to it).
+      def self.layout(paragraph, font_metrics:, base_size:, leading:)
+        return nil unless active?(paragraph)
+        return nil unless font_metrics
+
+        chars = paragraph.drop_cap_characters.to_i
+        lines = paragraph.drop_cap_lines.to_i
+        return nil if chars <= 0 || lines <= 0
+
+        build_layout(paragraph, font_metrics, base_size, leading, chars, lines)
+      end
+
+      # True when the paragraph declares an active drop cap
+      # (both DropCapLines and DropCapCharacters are positive integers).
+      def self.active?(paragraph)
+        return false unless paragraph
+        return false unless paragraph.drop_cap_lines.to_i.positive?
+
+        paragraph.drop_cap_characters.to_i.positive?
+      end
+
+      # Pulls the first N characters from the paragraph's first run.
+      # If the first run is shorter than N, takes from subsequent runs
+      # until N chars are accumulated (rare — drop caps typically use
+      # 1-2 chars).
+      def self.extract_drop_cap_text(paragraph, n)
+        runs = paragraph.runs
+        return nil if runs.empty?
+
+        collected = +""
+        runs.each do |run|
+          needed = n - collected.length
+          break if needed <= 0
+
+          collected << run.text[0, needed]
+          break if collected.length >= n
+        end
+        collected
+      end
+
+      def self.build_layout(paragraph, font_metrics, base_size, leading,
+                            chars, lines)
+        text = extract_drop_cap_text(paragraph, chars)
+        return nil if text.nil? || text.empty?
+
+        font_size = base_size * lines
+        width = font_metrics.measure_text(text, font_size).to_f
+        return nil unless width&.positive?
+
+        DropCapLayout.new(
+          text: text,
+          width: width,
+          height: leading * lines,
+          font_size: font_size,
+          wrap_offset: width,
+          lines: lines,
+        )
+      end
+      private_class_method :build_layout
+    end
+  end
+end

data/lib/idml/render/pipeline.rb

@@ -38,6 +38,7 @@ module Idml
         structure = StructureTracker.new(enabled: @tagged)
         position_tracker = PositionTracker.new
         layer_filter = LayerFilter.from_designmap(@package.designmap)
+        condition_filter = ConditionFilter.from_designmap(@package.designmap)
         font_ref_resolver = FontReferenceResolver.build(@package)
         font_setup = FontSetup.new(package: @package,
                                    font_search_paths: @font_search_paths)
@@ -50,7 +51,8 @@ module Idml
           page_index = render_spread(writer, spread, layer_filter,
                                      font_ref_resolver, font_resource,
                                      font_metrics, font_map, structure,
-                                     position_tracker, page_index)
+                                     position_tracker, condition_filter,
+                                     page_index)
         end
 
         structure.flush(writer)
@@ -90,14 +92,14 @@ module Idml
 
       def render_spread(writer, spread, layer_filter, font_ref_resolver,
                         font_resource, font_metrics, font_map, structure,
-                        position_tracker, page_offset)
+                        position_tracker, condition_filter, page_offset)
         pages = spread.spread.flat_map(&:page)
         image_refs = ImageCollector.new(writer: writer,
                                         base_dir: File.dirname(@package.path),
                                         page_height: DEFAULT_HEIGHT).collect(spread)
         renderer = build_renderer(layer_filter, font_ref_resolver,
                                   font_resource, font_metrics, font_map,
-                                  structure, position_tracker)
+                                  structure, position_tracker, condition_filter)
         current = page_offset
 
         pages.each do |page|
@@ -126,7 +128,8 @@ module Idml
       end
 
       def build_renderer(layer_filter, font_ref_resolver, font_resource,
-                         font_metrics, font_map, structure, position_tracker)
+                         font_metrics, font_map, structure, position_tracker,
+                         condition_filter)
         SpreadRenderer.new(
           font_metrics: font_metrics,
           font_ps_name: font_resource,
@@ -136,6 +139,7 @@ module Idml
           font_ref_resolver: font_ref_resolver,
           structure: structure,
           position_tracker: position_tracker,
+          condition_filter: condition_filter,
         )
       end
 

data/lib/idml/render/render_context.rb

@@ -20,6 +20,8 @@ module Idml
       :structure,
       :page_index,
       :position_tracker,
+      :chain_controller,
+      :condition_filter,
       keyword_init: true,
     )
   end

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

@@ -30,7 +30,6 @@ module Idml
         def self.render(canvas, context)
           frame = context.item
           return unless frame.parent_story
-          return unless chain_head?(frame)
 
           story = context.package&.story_by_id(frame.parent_story)
           return unless story
@@ -38,12 +37,53 @@ module Idml
           box = frame_box(frame, context.page_height)
           render_inline_tables(canvas, story, box, context)
 
-          paragraphs = StyleResolver.extract_paragraphs(story)
-          return if paragraphs.empty?
+          state = initial_chain_state(frame, story, context)
+          return unless state
 
-          render_text(canvas, paragraphs, context, box)
+          render_text(canvas, state, context, box)
+          store_chain_state(frame, state, context)
         end
 
+        # Returns the StoryChainController::State to render this frame
+        # with. For chain heads (no predecessor), this is a fresh
+        # state built from extract_paragraphs. For chain non-heads,
+        # this is the leftover state from the previous frame in the
+        # chain (nil when there's nothing left to render).
+        def self.initial_chain_state(frame, story, context)
+          controller = context.chain_controller
+          return fresh_state(story, context) if chain_head?(frame)
+          return nil unless controller
+
+          controller.state_for(frame.parent_story)
+        end
+        private_class_method :initial_chain_state
+
+        # Records the post-render state for the chain so the next
+        # frame in the chain picks up where this one left off. Only
+        # meaningful when a chain_controller is wired.
+        def self.store_chain_state(frame, state, context)
+          controller = context.chain_controller
+          return unless controller
+
+          controller.store_state(frame.parent_story, state)
+        end
+        private_class_method :store_chain_state
+
+        def self.fresh_state(story, context)
+          paragraphs = StyleResolver.extract_paragraphs(
+            story, condition_filter: context.condition_filter
+          )
+          return nil if paragraphs.empty?
+
+          StoryChainController::State.new(
+            paragraphs: paragraphs,
+            current_paragraph: nil,
+            runs_remaining: [],
+            char_cursor: 0,
+          )
+        end
+        private_class_method :fresh_state
+
         # Discovers Tables inlined in the story (Story > PSR > CSR >
         # Table — the real IDML structure) and renders each within
         # the frame's bounds. Real IDML Tables have no own geometry,
@@ -70,12 +110,12 @@ module Idml
         end
         private_class_method :tables_in_story
 
-        def self.render_text(canvas, paragraphs, context, box)
+        def self.render_text(canvas, state, context, box)
           font = context.font_metrics
           if font
-            engine_render(canvas, paragraphs, context, box, font)
+            engine_render(canvas, state, context, box, font)
           else
-            simple_render(canvas, paragraphs, context, box)
+            simple_render(canvas, state, context, box)
           end
         end
         private_class_method :render_text
@@ -109,56 +149,251 @@ module Idml
         end
         private_class_method :layout_frame
 
-        # Walks paragraphs and emits one `canvas.text` per line via
-        # the Shaper → LineBreaker → Justifier → VerticalLayout
-        # pipeline. Cursor y descends monotonically across
-        # paragraphs so text flows top-to-bottom (the previous
-        # implementation reset every run to the frame top).
-        def self.engine_render(canvas, paragraphs, context, box, font)
+        # Walks the chain state's paragraphs/runs and emits one
+        # `canvas.text` per line via the Shaper → LineBreaker →
+        # Justifier → VerticalLayout pipeline. Cursor y descends
+        # monotonically across paragraphs. When a paragraph partially
+        # fits, its remaining runs go back into the state for the
+        # next frame in the chain.
+        def self.engine_render(canvas, state, context, box, font)
           layout_frame = layout_frame(context.item, box)
-          cursor_y = box[:y] + box[:height] - (layout_frame.inset_top || 0)
+          top_y = box[:y] + box[:height] - (layout_frame.inset_top || 0)
           bottom_limit = TextEngine::VerticalLayout.bottom_limit(layout_frame)
-          char_cursor = 0
+          cursor_y = vertical_justify_top(top_y, bottom_limit, state, context)
+          char_cursor = state.char_cursor
 
-          paragraphs.each do |paragraph|
-            break if cursor_y < bottom_limit
-
-            cursor_y, char_cursor = render_paragraph(
-              canvas, paragraph, context, layout_frame, font,
+          if state.current_paragraph
+            cursor_y, char_cursor = resume_paragraph(
+              canvas, state, context, layout_frame, font,
               cursor_y, bottom_limit, char_cursor
             )
+            return if state.current_paragraph
           end
+
+          consume_paragraphs(canvas, state, context, layout_frame, font,
+                             cursor_y, bottom_limit, char_cursor)
         end
         private_class_method :engine_render
 
-        def self.render_paragraph(canvas, paragraph, context, layout_frame,
-                                  font, cursor_y, bottom_limit, char_cursor)
+        # Computes the starting cursor_y for vertical justification.
+        # IDML's TextFramePreference.VerticalJustification can be:
+        # - TopAlign (default): start at frame top, no offset
+        # - CenterAlign: center the content block vertically
+        # - BottomAlign: align content to the frame bottom
+        # - JustifyAlign: distribute extra space between paragraphs
+        #   (deferred — falls back to TopAlign behavior)
+        #
+        # Content height is estimated by walking paragraphs and
+        # summing leading × lines + space_before/after. Without
+        # shaping/wrapping we can't know exact line count, so we
+        # approximate by treating each run as one line.
+        def self.vertical_justify_top(top_y, bottom_limit, state, context)
+          justification = text_frame_vertical_justification(context)
+          return top_y unless %w[CenterAlign BottomAlign].include?(justification)
+
+          content_height = estimate_content_height(state)
+          available = top_y - bottom_limit
+          slack = [available - content_height, 0].max
+          return top_y if slack.zero?
+
+          case justification
+          when "CenterAlign" then top_y - (slack / 2)
+          when "BottomAlign" then top_y - slack
+          else top_y
+          end
+        end
+        private_class_method :vertical_justify_top
+
+        def self.text_frame_vertical_justification(context)
+          pref = context.item&.text_frame_preference&.first
+          pref&.vertical_justification
+        end
+        private_class_method :text_frame_vertical_justification
+
+        # Estimates total renderable content height for vertical
+        # justification. Walks paragraphs and runs, summing leading
+        # per run plus paragraph space_before/after. Approximation:
+        # treats each run as one line (wrap may produce more lines,
+        # which would over-estimate slack; acceptable for
+        # justification since we'd rather under-offset than overflow).
+        def self.estimate_content_height(state)
+          paragraphs = paragraphs_for_estimate(state)
+          return 0 if paragraphs.empty?
+
+          paragraphs.sum do |paragraph|
+            paragraph_height(paragraph)
+          end
+        end
+        private_class_method :estimate_content_height
+
+        def self.paragraphs_for_estimate(state)
+          result = []
+          result << state.current_paragraph if state.current_paragraph
+          result + state.paragraphs
+        end
+        private_class_method :paragraphs_for_estimate
+
+        def self.paragraph_height(paragraph)
+          size = paragraph.runs.first&.point_size || DEFAULT_SIZE
+          leading = leading_for(paragraph, size)
+          line_count = [paragraph.runs.length, 1].max
+          (leading * line_count) + space_before_after(paragraph)
+        end
+        private_class_method :paragraph_height
+
+        def self.space_before_after(paragraph)
+          (paragraph.space_before || 0) + (paragraph.space_after || 0)
+        end
+        private_class_method :space_before_after
+
+        def self.resume_paragraph(canvas, state, context, layout_frame, font,
+                                  cursor_y, bottom_limit, char_cursor)
+          paragraph = state.current_paragraph
+          remaining_runs, cursor_y, char_cursor = render_runs_for_paragraph(
+            canvas, paragraph, state.runs_remaining, context,
+            layout_frame, font, cursor_y, bottom_limit, char_cursor,
+            first_paragraph: true
+          )
+          if remaining_runs.any?
+            state.runs_remaining = remaining_runs
+          else
+            state.current_paragraph = nil
+            state.runs_remaining = []
+          end
+          [cursor_y, char_cursor]
+        end
+        private_class_method :resume_paragraph
+
+        def self.consume_paragraphs(canvas, state, context, layout_frame, font,
+                                    cursor_y, bottom_limit, char_cursor)
+          pending = 0
+          state.paragraphs.each do |paragraph|
+            break if cursor_y < bottom_limit
+
+            remaining_runs, cursor_y, char_cursor = render_runs_for_paragraph(
+              canvas, paragraph, paragraph.runs, context,
+              layout_frame, font, cursor_y, bottom_limit, char_cursor,
+              first_paragraph: pending.zero?
+            )
+            if remaining_runs.any?
+              state.current_paragraph = paragraph
+              state.runs_remaining = remaining_runs
+              break
+            end
+            pending += 1
+          end
+
+          state.paragraphs = state.paragraphs[pending..]
+          state.char_cursor = char_cursor
+        end
+        private_class_method :consume_paragraphs
+
+        # Renders a paragraph's runs (a subset when resuming mid-para).
+        # Returns [remaining_runs, cursor_y, char_cursor] where
+        # remaining_runs is the runs that didn't fit (empty when all
+        # done). Emits RuleAbove before the first run and RuleBelow
+        # after the last successfully-rendered run.
+        def self.render_runs_for_paragraph(canvas, paragraph, runs, context,
+                                           layout_frame, font, cursor_y,
+                                           bottom_limit, char_cursor,
+                                           first_paragraph:)
           wrap_width = TextEngine::VerticalLayout.wrap_width(
             layout_frame, paragraph.right_indent || 0
           )
           para_attrs = paragraph_attrs(paragraph)
           frame_left, frame_right = paragraph_frame_extents(layout_frame)
 
-          # RuleAbove sits at the paragraph's top edge (before
-          # space_before is subtracted), so emit it first using the
-          # incoming cursor_y as the anchor.
+          emit_paragraph_top_rule(canvas, paragraph, context, cursor_y,
+                                  frame_left, frame_right, first_paragraph)
+          emit_drop_cap(canvas, paragraph, context, frame_left, cursor_y,
+                        first_paragraph)
+
+          rendered_count = 0
+          runs.each do |run|
+            break if cursor_y < bottom_limit
+
+            space_before = paragraph_space_before(para_attrs, first_paragraph,
+                                                  rendered_count)
+            positioned, next_y = layout_run(
+              canvas, run, paragraph, context, layout_frame, font,
+              wrap_width, cursor_y, space_before,
+              para_attrs[:first_line_indent], para_attrs[:left_indent],
+              char_cursor
+            )
+            char_cursor += positioned.length
+            cursor_y = next_y
+            rendered_count += 1
+          end
+
+          remaining_runs = runs[rendered_count..]
+          cursor_y = emit_paragraph_bottom_rule(canvas, paragraph, context,
+                                                cursor_y, frame_left,
+                                                frame_right, para_attrs,
+                                                remaining_runs)
+          [remaining_runs, cursor_y, char_cursor]
+        end
+        private_class_method :render_runs_for_paragraph
+
+        # Renders the drop cap for a paragraph (when declared and the
+        # first paragraph of the chain). Wrap-around text is not yet
+        # implemented — the drop cap renders as an enlarged glyph at
+        # the paragraph's top-left; subsequent text may overlap it.
+        # Marked as a follow-up in TODO 103.
+        def self.emit_drop_cap(canvas, paragraph, context, frame_left,
+                               cursor_y, first_paragraph)
+          return nil unless first_paragraph
+          return nil unless DropCap.active?(paragraph)
+
+          base_size = paragraph.runs.first&.point_size || DEFAULT_SIZE
+          leading = leading_for(paragraph, base_size)
+          drop_cap = DropCap.layout(paragraph,
+                                    font_metrics: context.font_metrics,
+                                    base_size: base_size, leading: leading)
+          return nil unless drop_cap
+
+          drop_at_y = cursor_y - drop_cap.font_size + (base_size * 0.25)
+          canvas.text(
+            drop_cap.text,
+            at: [frame_left, drop_at_y],
+            font: font_for_run(paragraph.runs.first, context),
+            size: drop_cap.font_size,
+          )
+        end
+        private_class_method :emit_drop_cap
+
+        def self.emit_paragraph_top_rule(canvas, paragraph, context, cursor_y,
+                                         frame_left, frame_right,
+                                         first_paragraph)
+          return unless first_paragraph
+
           ParagraphRules.emit_rule_above(canvas, paragraph, context,
                                          cursor_y, frame_left, frame_right)
+        end
+        private_class_method :emit_paragraph_top_rule
 
-          cursor_y, char_cursor = render_runs(
-            canvas, paragraph, context, layout_frame, font,
-            wrap_width, cursor_y, bottom_limit, char_cursor, para_attrs
-          )
-          after_y = cursor_y - para_attrs[:space_after]
+        def self.paragraph_space_before(para_attrs, first_paragraph,
+                                        rendered_count)
+          return 0 unless first_paragraph && rendered_count.zero?
+
+          para_attrs[:space_before]
+        end
+        private_class_method :paragraph_space_before
 
-          # RuleBelow sits at the paragraph's bottom edge (after the
-          # last line + space_after), so emit it last using after_y
-          # as the anchor.
+        # Emits RuleBelow after a paragraph's last run. Returns the
+        # updated cursor_y (subtracting space_after when the paragraph
+        # completed).
+        def self.emit_paragraph_bottom_rule(canvas, paragraph, context,
+                                            cursor_y, frame_left,
+                                            frame_right, para_attrs,
+                                            remaining_runs)
+          return cursor_y unless remaining_runs.empty?
+
+          after_y = cursor_y - para_attrs[:space_after]
           ParagraphRules.emit_rule_below(canvas, paragraph, context,
                                          after_y, frame_left, frame_right)
-          [after_y, char_cursor]
+          after_y
         end
-        private_class_method :render_paragraph
+        private_class_method :emit_paragraph_bottom_rule
 
         def self.paragraph_frame_extents(layout_frame)
           inset_left = layout_frame.inset_left || 0
@@ -178,27 +413,6 @@ module Idml
         end
         private_class_method :paragraph_attrs
 
-        def self.render_runs(canvas, paragraph, context, layout_frame, font,
-                             wrap_width, cursor_y, bottom_limit, char_cursor,
-                             para_attrs)
-          space_before = para_attrs[:space_before]
-          paragraph.runs.each do |run|
-            break if cursor_y < bottom_limit
-
-            positioned, next_y = layout_run(
-              canvas, run, paragraph, context, layout_frame, font,
-              wrap_width, cursor_y, space_before,
-              para_attrs[:first_line_indent], para_attrs[:left_indent],
-              char_cursor
-            )
-            char_cursor += positioned.length
-            cursor_y = next_y
-            space_before = 0
-          end
-          [cursor_y, char_cursor]
-        end
-        private_class_method :render_runs
-
         # Shapes one run's text, wraps to the inset/indent-adjusted
         # width, justifies per paragraph alignment, and asks
         # VerticalLayout to position the lines. Emits each line via
@@ -321,8 +535,11 @@ module Idml
 
         # Fallback when no metrics are available: emit all runs as
         # one `text_rich` block, letting pdfrb measure advance widths.
-        def self.simple_render(canvas, paragraphs, context, box)
-          runs = paragraphs.flat_map(&:runs)
+        # Chain threading is best-effort here — the simple path
+        # doesn't wrap, so the first frame's render typically emits
+        # all content and clears the chain state.
+        def self.simple_render(canvas, state, context, box)
+          runs = collect_runs(state)
           return if runs.empty?
 
           runs_for = build_rich_runs(runs, context)
@@ -331,9 +548,22 @@ module Idml
             runs_for,
             at: [box[:x], box[:y] + box[:height] - first_size],
           )
+          state.paragraphs = []
+          state.current_paragraph = nil
+          state.runs_remaining = []
         end
         private_class_method :simple_render
 
+        def self.collect_runs(state)
+          runs = state.runs_remaining || []
+          if state.current_paragraph
+            runs + state.current_paragraph.runs
+          else
+            runs + state.paragraphs.flat_map(&:runs)
+          end
+        end
+        private_class_method :collect_runs
+
         def self.build_rich_runs(runs, context)
           runs.map do |run|
             {

data/lib/idml/render/spread_renderer.rb

@@ -7,7 +7,8 @@ module Idml
       def initialize(font_metrics: nil, font_ps_name: Render::DEFAULT_FONT,
                      package: nil, layer_filter: LayerFilter::EXCLUDE_NONE,
                      font_ref_resolver: nil, structure: nil,
-                     position_tracker: nil, font_map: {})
+                     position_tracker: nil, font_map: {},
+                     condition_filter: nil)
         @font_metrics = font_metrics
         @font_ps_name = font_ps_name
         @package = package
@@ -16,6 +17,7 @@ module Idml
         @structure = structure
         @position_tracker = position_tracker
         @font_map = font_map
+        @condition_filter = condition_filter
       end
 
       def render(canvas, spread, page_width:, page_height:, image_refs: [],
@@ -33,6 +35,8 @@ module Idml
           structure: @structure,
           page_index: page_index,
           position_tracker: @position_tracker,
+          chain_controller: StoryChainController.new,
+          condition_filter: @condition_filter,
         }
 
         canvas.save_graphics_state do

data/lib/idml/render/story_chain_controller.rb

@@ -0,0 +1,66 @@
+# frozen_string: true
+
+module Idml
+  module Render
+    # Threads story-rendering state across linked TextFrames in a
+    # chain. A story overflows from frame 1 → frame 2 → frame 3 etc.
+    # via PreviousTextFrame/NextTextFrame links; without chain
+    # awareness, the renderer would silently truncate overflow text.
+    #
+    # State is per story_id (the ParentStory attribute). State is
+    # populated when a chain head renders and consumed when chain
+    # non-head frames render.
+    #
+    # Threading granularity: paragraphs and runs. If a run partially
+    # fits in a frame, the next frame picks up where the previous
+    # left off (the partially-rendered lines stay in the previous
+    # frame; remaining lines come from re-wrapping the run).
+    class StoryChainController
+      # `paragraphs` : Array<Paragraph> not yet started
+      # `current_paragraph` : Paragraph in progress (nil if none)
+      # `runs_remaining` : Array<StyledRun> in current_paragraph not yet rendered
+      # `char_cursor` : global character cursor (for hyperlink tracking)
+      State = Struct.new(
+        :paragraphs,
+        :current_paragraph,
+        :runs_remaining,
+        :char_cursor,
+        keyword_init: true,
+      )
+
+      def initialize
+        @states = {}
+      end
+
+      # Returns the chain state for a story, or nil if the story has
+      # no leftover content. Chain heads (no predecessor) get no
+      # state — they render from scratch.
+      def state_for(story_id)
+        @states[story_id]
+      end
+
+      # Records the chain state for a story after a frame's render.
+      # Removes the state entirely when no content remains.
+      def store_state(story_id, state)
+        if state.nil? || empty_state?(state)
+          @states.delete(story_id)
+        else
+          @states[story_id] = state
+        end
+      end
+
+      # True when a story has pending content from a previous frame.
+      def has_pending?(story_id)
+        @states.key?(story_id)
+      end
+
+      private
+
+      def empty_state?(state)
+        state.paragraphs.empty? &&
+          state.current_paragraph.nil? &&
+          state.runs_remaining&.empty?
+      end
+    end
+  end
+end

data/lib/idml/render/style_resolver.rb

@@ -54,6 +54,8 @@ module Idml
         :left_indent,
         :right_indent,
         :auto_leading,
+        :drop_cap_lines,
+        :drop_cap_characters,
         # RuleAbove / RuleBelow — paragraph rules (horizontal lines
         # above/below the paragraph block). Driven by PSR attributes.
         :rule_above,
@@ -104,11 +106,13 @@ module Idml
       # its runs and carries the paragraph-level attributes from the
       # owning PSR. Empty paragraphs (no runs after filtering) are
       # skipped.
-      def self.extract_paragraphs(story)
+      def self.extract_paragraphs(story, condition_filter: nil)
         return [] unless story&.inner
 
         story.inner.paragraph_style_range.filter_map do |psr|
-          runs = csr_runs(psr)
+          next unless condition_visible?(psr, condition_filter)
+
+          runs = csr_runs(psr, condition_filter: condition_filter)
           next if runs.empty?
 
           Paragraph.new(
@@ -120,6 +124,8 @@ module Idml
             left_indent: psr.left_indent,
             right_indent: psr.right_indent,
             auto_leading: psr.auto_leading,
+            drop_cap_lines: psr.drop_cap_lines,
+            drop_cap_characters: psr.drop_cap_characters,
             rule_above: psr.rule_above,
             rule_above_line_weight: psr.rule_above_line_weight,
             rule_above_color: psr.stroke_color,
@@ -140,8 +146,10 @@ module Idml
         end
       end
 
-      def self.csr_runs(psr)
+      def self.csr_runs(psr, condition_filter: nil)
         psr.character_style_range.filter_map do |csr|
+          next unless condition_visible?(csr, condition_filter)
+
           text = csr.text_content
           next if text.nil? || text.empty?
 
@@ -170,6 +178,16 @@ module Idml
       end
       private_class_method :csr_runs
 
+      # Drops the PSR/CSR when any of its AppliedConditions
+      # references a hidden Condition. Returns true when no filter
+      # is supplied (caller doesn't care about conditions).
+      def self.condition_visible?(psr_or_csr, condition_filter)
+        return true unless condition_filter
+
+        condition_filter.visible?(psr_or_csr.applied_conditions)
+      end
+      private_class_method :condition_visible?
+
       def self.alignment_for(csr)
         ALIGNMENT_MAP[csr.justification] || :left
       end

data/lib/idml/render.rb

@@ -15,7 +15,10 @@ module Idml
     autoload :StrokeStyle,         "#{__dir__}/render/stroke_style"
     autoload :CharacterStyle,      "#{__dir__}/render/character_style"
     autoload :ParagraphRules,      "#{__dir__}/render/paragraph_rules"
+    autoload :DropCap,             "#{__dir__}/render/drop_cap"
+    autoload :StoryChainController, "#{__dir__}/render/story_chain_controller"
     autoload :LayerFilter,         "#{__dir__}/render/layer_filter"
+    autoload :ConditionFilter,     "#{__dir__}/render/condition_filter"
     autoload :Placement,           "#{__dir__}/render/placement"
     autoload :ImageCollector,      "#{__dir__}/render/image_collector"
     autoload :StructureTracker,    "#{__dir__}/render/structure_tracker"

data/lib/idml/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: idml
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.7.3
 platform: ruby
 authors:
 - Ribose
@@ -168,6 +168,10 @@ files:
 - TODO.pdf/11-font-embedding.md
 - TODO.pdf/110-conditional-text.md
 - TODO.pdf/111-footnote-support.md
+- TODO.pdf/112-text-frame-vertical-justification.md
+- TODO.pdf/113-multi-column-text-frames.md
+- TODO.pdf/114-text-wrap-around-shapes.md
+- TODO.pdf/115-bullet-numbered-lists.md
 - TODO.pdf/12-idml-to-pdf-pipeline.md
 - TODO.pdf/13-cjk-text-layout.md
 - TODO.pdf/14-page-item-element-models.md
@@ -276,6 +280,7 @@ files:
 - lib/idml/elements/character_style_group.rb
 - lib/idml/elements/character_style_range.rb
 - lib/idml/elements/color.rb
+- lib/idml/elements/condition.rb
 - lib/idml/elements/content.rb
 - lib/idml/elements/content_transparency_setting.rb
 - lib/idml/elements/contour_option.rb
@@ -428,6 +433,8 @@ files:
 - lib/idml/render/character_style.rb
 - lib/idml/render/color_helper.rb
 - lib/idml/render/color_resolver.rb
+- lib/idml/render/condition_filter.rb
+- lib/idml/render/drop_cap.rb
 - lib/idml/render/font_reference_resolver.rb
 - lib/idml/render/font_setup.rb
 - lib/idml/render/gradient_resolver.rb
@@ -454,6 +461,7 @@ files:
 - lib/idml/render/renderers/table_renderer.rb
 - lib/idml/render/renderers/text_frame_renderer.rb
 - lib/idml/render/spread_renderer.rb
+- lib/idml/render/story_chain_controller.rb
 - lib/idml/render/story_threader.rb
 - lib/idml/render/stroke_style.rb
 - lib/idml/render/structure_mapper.rb