idml 0.10.10 → 0.10.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69238283188d95396073ce5caacf5662573ccaa6d913e1f76d056b24284449d7
-  data.tar.gz: 20639926a31480df14b3225e04a3eb04f3042bfb105aa9377a63bcb1a0cc5850
+  metadata.gz: 49122b9c9f5974361567afb8fc2e063602e370141f0d5990f8de156275c312c4
+  data.tar.gz: c4f21424d6cd5d2f9345801aeb53be0b78d26f3d0c423b8ad20b179dff4ef38f
 SHA512:
-  metadata.gz: 474d4266f64894e0fde05e60e2791402854e20b0a4820950e165f8552fb6be7aa644eb7a5303f8f2fa0e86e6dd4df1673d6b53f6ae9a2fac304f36c4fa5cc5e0
-  data.tar.gz: 48ba09b818f5079b981cbed968a49779a69fc38c61e6500c973036f404f6ce1796d7238fea2a0532355b3d5a61130d1d741ac59b77fa823fb4b8e3a4fe0b8f5b
+  metadata.gz: 6c06eb1149c2fed295382a4ce65504d12c821d884ffa6cd145f9ac96e0837c82b1dbfdd16abd082e84366dd6c0bfd6edc8670e187d71785f1de0e7a415cc9892
+  data.tar.gz: 12352d559b36427ec1be4ce71e31cfc149e24ec52a1fe70b65c3ecc720575c1a4f7a9aab8b96e67329747f33bc2005494c6f0c2034508b642edf37ba917a45ca

data/TODO.pdf/149-architecture-round-two.md

@@ -0,0 +1,53 @@
+# TODO PDF 149: Architecture review round two — policy modules + test seam
+
+## Status: COMPLETE — implemented 2026-08-29
+
+## Problem
+
+Follow-up architecture review (hot-spot: the renderer) after
+TODO 148's wing split:
+
+1. The keep-options family (paragraph deferral: KeepAllLines /
+   KeepFirstLines / KeepLastLines windows, KeepWithNext,
+   StartParagraph breaks) was ten private predicates buried in
+   the engine — only testable through full end-to-end renders.
+2. Frame-positioning policy (FirstBaselineOffset modes, vertical
+   justification, content-height estimation) was interleaved with
+   run emission, and `first_paragraph_leading(state)` /
+   `first_paragraph_leading_for(paragraph)` were near-duplicate
+   leading helpers maintained apart.
+3. The render specs' real interface — the PDF content stream —
+   was parsed by copy-pasted regexes (99 scan() sites, five
+   private helper reimplementations); two spec bugs this week
+   came from exactly this duplication.
+
+## Solution
+
+- **`Renderers::KeepPolicy`** (~118 lines, module_function): the
+  deferral predicates extracted as a standalone pure module. The
+  engine calls one entry point,
+  `KeepPolicy.paragraph_deferred?(...)`. New direct unit spec
+  (`keep_policy_spec.rb`, 14 examples) drives the window
+  arithmetic with real `StyleResolver::Paragraph` structs — no
+  canvas, writer, or fonts.
+- **`Renderers::FrameMetrics`** (~160 lines, module_function):
+  baseline modes, vertical-justify offsets, and content-height
+  estimation in one home. The duplicate leading helpers are
+  consolidated onto `FrameMetrics.leading_for(paragraph)`, which
+  KeepPolicy also reuses.
+- **`PdfStream`** (spec_helper): one named parser for the content
+  stream (`text_positions`, `text_ys`, `bt_count`, `stroke_count`,
+  `rect_count`); the five private spec helpers and all inline
+  scan() idioms replaced.
+
+TextFrameRenderer: 1235 → 960 lines (flow + emission only). Suite
+3222 → 3256 examples. Zero behavior change.
+
+## Files
+
+- `lib/idml/render/renderers/keep_policy.rb` (new)
+- `lib/idml/render/renderers/frame_metrics.rb` (new)
+- `lib/idml/render/renderers/text_frame_renderer.rb`
+- `lib/idml/render.rb`
+- `spec/spec_helper.rb` + 10 render specs
+- `spec/idml/render/renderers/keep_policy_spec.rb` (new)

data/TODO.pdf/150-architecture-round-three.md

@@ -0,0 +1,41 @@
+# TODO PDF 150: Architecture review round three — seam repairs
+
+## Status: COMPLETE — implemented 2026-08-30
+
+## Problem
+
+Round-three review findings (after TODOs 148-149):
+
+1. **Page-dimensions seam leak (bug)**: `ImageCollector` and
+   `HyperlinkEmitter` received a hardcoded `DEFAULT_HEIGHT = 792`
+   while pages rendered at per-page dimensions — both use the
+   height for the IDML→PDF y-flip, so images and link rectangles
+   misplaced on any non-letter page.
+2. **Dead interface kept alive by its tests**:
+   `TextWrapResolver#overlap_width` (+ `line_overlap`) had zero
+   lib callers since TODO 138 — only its own spec — and encoded
+   sum-semantics for multiple contours where the real interface
+   (`wrap_adjustment`) uses max. The spec suite asserted behavior
+   the renderer no longer had.
+3. **Thirteen copies of the synthetic-package triplet**: every
+   engine-path spec repeated `Dir.mktmpdir → Package.write →
+   Package.new`, with drifting names and inconsistent part sets.
+
+## Solution
+
+- Pipeline threads per-page `dims[:height]` into both consumers;
+  the constants stay only as `page_dimensions_for` fallbacks.
+- `overlap_width` / `line_overlap` deleted; all 15 spec call
+  sites migrated to `wrap_adjustment` (the "sums contours" spec
+  now documents max-combination honestly). The polygon variant
+  `WrapContour.overlap_width` stays — it is load-bearing.
+- `build_package(parts, name)` helper in spec_helper; thirteen
+  triplet copies replaced; three local helpers that shadowed the
+  global renamed (`anchored_fixture`, `decorated_fixture`,
+  `footnote_fixture`, `endnote_fixture`, `footnote_package`).
+
+## Files
+
+- `lib/idml/render/pipeline.rb`
+- `lib/idml/render/text_wrap_resolver.rb`
+- `spec/spec_helper.rb` + 13 spec files

data/lib/idml/render/pipeline.rb

@@ -96,9 +96,6 @@ module Idml
                         position_tracker, condition_filter, style_lookup,
                         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, condition_filter,
@@ -108,21 +105,26 @@ module Idml
         pages.each do |page|
           current += 1
           dims = page_dimensions_for(page)
+          image_refs = ImageCollector.new(
+            writer: writer,
+            base_dir: File.dirname(@package.path),
+            page_height: dims[:height],
+          ).collect(spread)
           canvas = writer.add_page(width: dims[:width], height: dims[:height])
           renderer.render(canvas, spread, page_width: dims[:width],
                                           page_height: dims[:height],
                                           image_refs: image_refs,
                                           page_index: current)
-          emit_hyperlinks(writer, spread, current, layer_filter,
-                          position_tracker)
+          emit_hyperlinks(writer, spread, current, dims[:height],
+                          layer_filter, position_tracker)
         end
         current
       end
 
-      def emit_hyperlinks(writer, spread, page_index, layer_filter,
-                          position_tracker)
+      def emit_hyperlinks(writer, spread, page_index, page_height,
+                          layer_filter, position_tracker)
         HyperlinkEmitter.new(writer: writer, package: @package,
-                             page_height: DEFAULT_HEIGHT,
+                             page_height: page_height,
                              layer_filter: layer_filter,
                              position_tracker: position_tracker)
           .emit_for(spread, page_index)

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

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    module Renderers
+      # Frame positioning policy for the text engine: where the
+      # first baseline sits under each FirstBaselineOffset mode,
+      # where the content block starts under vertical
+      # justification, and how tall the pending content is
+      # estimated to be. Pure functions of the TextFrame's
+      # preference, the chain state, and font metrics — no canvas,
+      # no emission (MECE: this module owns frame-positioning
+      # policy; TextFrameRenderer owns flow and emission;
+      # KeepPolicy owns paragraph deferral).
+      module FrameMetrics
+        FIRST_BASELINE_MODES = %w[
+          AscentOffset FixedHeight CapHeight XHeight EmboxHeight
+        ].freeze
+
+        # pdfrb 0.7.1 never fills the cap_height metric, so
+        # CapHeight / XHeight fall back to standard font
+        # proportions (cap ≈ 0.72 em, x ≈ 0.52 em — Arial and
+        # Helvetica both sit within 1% of these).
+        CAP_HEIGHT_RATIO = 0.72
+        X_HEIGHT_RATIO = 0.52
+
+        module_function
+
+        # Top y for the content block under the frame's vertical
+        # justification: TopAlign keeps the frame top;
+        # CenterAlign / BottomAlign offset by the slack between the
+        # estimated content height and the available space
+        # (JustifyAlign falls back to TopAlign behavior).
+        def vertical_justify_top(top_y, bottom_limit, state, context)
+          justification = text_frame_vertical_justification(context)
+          return top_y unless %w[CenterAlign BottomAlign].include?(justification)
+
+          available = top_y - bottom_limit
+          slack = [available - estimate_content_height(state), 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
+
+        # FirstBaselineOffset: how far below the frame's top inset
+        # the first line's baseline sits, relative to the layout's
+        # leading-based default. AscentOffset shifts by (ascent −
+        # leading), FixedHeight by (MinimumFirstBaselineOffset −
+        # leading), CapHeight by the cap-height proportion, XHeight
+        # by the x-height proportion, EmboxHeight by the em box
+        # (the first paragraph's point size).
+        def first_baseline_offset(context, state, font)
+          pref = context.item&.text_frame_preference&.first
+          mode = pref&.first_baseline_offset
+          return 0.0 unless FIRST_BASELINE_MODES.include?(mode)
+
+          baseline_target(pref, mode, state, font) -
+            first_paragraph_leading(state)
+        end
+
+        # Distance from the top inset to the first baseline under
+        # the given mode.
+        def baseline_target(pref, mode, state, font)
+          leading = first_paragraph_leading(state)
+          case mode
+          when "AscentOffset"
+            ratio_scaled(font.ascent, font) * leading
+          when "CapHeight"
+            cap_ratio(font) * leading
+          when "XHeight"
+            X_HEIGHT_RATIO * leading
+          when "EmboxHeight"
+            first_paragraph_size(state)
+          else
+            pref.minimum_first_baseline_offset || leading
+          end
+        end
+
+        def cap_ratio(font)
+          cap = font.cap_height
+          return CAP_HEIGHT_RATIO unless cap
+
+          ratio_scaled(cap, font)
+        end
+
+        def ratio_scaled(metric, font)
+          upem = font.units_per_em
+          return 1.0 if upem.zero?
+
+          metric / upem
+        end
+
+        def first_paragraph_size(state)
+          paragraph = state.current_paragraph || state.paragraphs.first
+          first_run = paragraph&.runs&.first
+          first_run&.point_size || TextFrameRenderer::DEFAULT_SIZE
+        end
+
+        # Leading of a paragraph computed from its first run's
+        # point size (the default size when it has no runs yet).
+        def leading_for(paragraph)
+          size = paragraph.runs.first&.point_size ||
+            TextFrameRenderer::DEFAULT_SIZE
+          TextEngine::VerticalLayout.leading_for(paragraph.auto_leading,
+                                                 size)
+        end
+
+        def first_paragraph_leading(state)
+          paragraph = state.current_paragraph || state.paragraphs.first
+          unless paragraph
+            return TextFrameRenderer::DEFAULT_SIZE *
+                TextEngine::VerticalLayout::DEFAULT_LEADING_FACTOR
+          end
+
+          leading_for(paragraph)
+        end
+
+        def text_frame_vertical_justification(context)
+          pref = context.item&.text_frame_preference&.first
+          pref&.vertical_justification
+        end
+
+        # 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 estimate_content_height(state)
+          paragraphs_for_estimate(state).sum { |p| paragraph_height(p) }
+        end
+
+        def paragraphs_for_estimate(state)
+          result = []
+          result << state.current_paragraph if state.current_paragraph
+          result + state.paragraphs
+        end
+
+        def paragraph_height(paragraph)
+          size = paragraph.runs.first&.point_size ||
+            TextFrameRenderer::DEFAULT_SIZE
+          leading = TextEngine::VerticalLayout.leading_for(
+            paragraph.auto_leading, size
+          )
+          line_count = [paragraph.runs.length, 1].max
+          (leading * line_count) + space_before_after(paragraph)
+        end
+
+        def space_before_after(paragraph)
+          (paragraph.space_before || 0) + (paragraph.space_after || 0)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    module Renderers
+      # Paragraph deferral policy (keep options + forced breaks):
+      # decides whether a paragraph moves wholly to the next
+      # frame/column instead of being split. Honors StartParagraph
+      # forced breaks, KeepAllLinesTogether, the KeepFirstLines /
+      # KeepLastLines partial windows (measured-line-count
+      # approximation), and KeepWithNext. Pure predicates over the
+      # paragraph chain state and frame geometry — no canvas, no
+      # emission (MECE: TextFrameRenderer owns flow and emission;
+      # FrameMetrics owns frame positioning).
+      module KeepPolicy
+        BREAK_MODES = %w[
+          NextPage NextColumn NextFrame NextOddPage NextEvenPage
+        ].freeze
+
+        module_function
+
+        # True when the paragraph should move wholly to the next
+        # frame: a StartParagraph forced break, or a keep rule that
+        # the remaining space violates (never for the frame's
+        # first paragraph, so progress is always made).
+        def paragraph_deferred?(paragraph, next_paragraph,
+                                layout_frame, font, cursor_y,
+                                bottom_limit, placed_any)
+          return true if paragraph_break?(paragraph) && placed_any
+          return false unless placed_any
+          return true if keep_with_next_break?(paragraph, next_paragraph,
+                                               layout_frame, font,
+                                               cursor_y, bottom_limit)
+
+          keep_all_lines_break?(paragraph, layout_frame, font,
+                                cursor_y, bottom_limit) ||
+            keep_windows_break?(paragraph, layout_frame, font,
+                                cursor_y, bottom_limit)
+        end
+
+        # KeepAllLinesTogether: defer when the paragraph cannot
+        # fully fit the remaining space.
+        def keep_all_lines_break?(paragraph, layout_frame, font,
+                                  cursor_y, bottom_limit)
+          return false unless paragraph.keep_all_lines_together
+
+          height = paragraph_block_height(paragraph, layout_frame, font)
+          (cursor_y - height) < bottom_limit
+        end
+
+        # Partial keep windows, approximated by measured line
+        # counts: KeepFirstLines defers when fewer than N lines
+        # fit; KeepLastLines defers when the overflow tail for the
+        # next frame would strand fewer than N lines.
+        def keep_windows_break?(paragraph, layout_frame, font,
+                                cursor_y, bottom_limit)
+          return false unless paragraph.keep_first_lines ||
+            paragraph.keep_last_lines
+
+          height = paragraph_block_height(paragraph, layout_frame, font)
+          return false if (cursor_y - height) >= bottom_limit
+
+          leading = FrameMetrics.leading_for(paragraph)
+          lines_fit = [((cursor_y - bottom_limit) / leading).floor, 0].max
+          first_window_break?(paragraph, lines_fit) ||
+            last_window_break?(paragraph, lines_fit, height, leading)
+        end
+
+        def first_window_break?(paragraph, lines_fit)
+          paragraph.keep_first_lines &&
+            lines_fit < paragraph.keep_first_lines
+        end
+
+        def last_window_break?(paragraph, lines_fit, height, leading)
+          return false unless paragraph.keep_last_lines
+
+          total_lines = [(height / leading).ceil, 1].max
+          lines_fit.positive? &&
+            (total_lines - lines_fit) < paragraph.keep_last_lines
+        end
+
+        # KeepWithNext: this paragraph defers when the next
+        # paragraph is forced to the next frame, or when the next
+        # paragraph's first line would not fit after this one.
+        def keep_with_next_break?(paragraph, next_paragraph,
+                                  layout_frame, font, cursor_y,
+                                  bottom_limit)
+          return false unless keepable_pair?(paragraph, next_paragraph)
+          return true if paragraph_break?(next_paragraph)
+
+          height = paragraph_block_height(paragraph, layout_frame, font)
+          (cursor_y - height - FrameMetrics.leading_for(next_paragraph)) <
+            bottom_limit
+        end
+
+        def keepable_pair?(paragraph, next_paragraph)
+          !paragraph.keep_with_next.nil? && !next_paragraph.nil?
+        end
+
+        # True when the paragraph requests a forced break to the
+        # next frame/column (StartParagraph). All break flavors act
+        # at frame/column granularity.
+        def paragraph_break?(paragraph)
+          BREAK_MODES.include?(paragraph.start_paragraph)
+        end
+
+        def paragraph_block_height(paragraph, layout_frame, font)
+          wrap_width = TextEngine::VerticalLayout.wrap_width(
+            layout_frame, paragraph.right_indent || 0
+          )
+          TextEngine::Measurement.paragraph_height(
+            paragraph, font, wrap_width
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -284,8 +284,10 @@ module Idml
             (layout_frame.inset_top || 0)
           bottom_limit = TextEngine::VerticalLayout.bottom_limit(layout_frame)
           footnotes = []
-          cursor_y = vertical_justify_top(top_y, bottom_limit, state, context)
-          cursor_y -= first_baseline_offset(context, state, font)
+          cursor_y = FrameMetrics.vertical_justify_top(top_y, bottom_limit,
+                                                       state, context)
+          cursor_y -= FrameMetrics.first_baseline_offset(context, state,
+                                                         font)
           char_cursor = state.char_cursor
 
           if state.current_paragraph
@@ -326,7 +328,9 @@ module Idml
           top_y = col_frame.y + col_frame.height - (col_frame.inset_top || 0)
           bottom_limit = TextEngine::VerticalLayout.bottom_limit(col_frame)
           footnotes = []
-          cursor_y = top_y - first_baseline_offset(context, state, font)
+          cursor_y = top_y - FrameMetrics.first_baseline_offset(
+            context, state, font
+          )
           char_cursor = state.char_cursor
 
           if state.current_paragraph
@@ -389,160 +393,6 @@ module Idml
         private_class_method :build_column_frames
 
         # 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
-
-        # FirstBaselineOffset: how far below the frame's top inset
-        # the first line's baseline sits. The layout's default is
-        # leading-based; AscentOffset shifts by (ascent − leading)
-        # and FixedHeight by (MinimumFirstBaselineOffset − leading).
-        # CapHeight uses the font's cap-height metric (leading
-        # fallback when the font reports none); XHeight approximates
-        # as 70% of cap height; EmboxHeight uses the em box (the
-        # first paragraph's point size). Returns the extra shift to
-        # subtract from the cursor.
-        FIRST_BASELINE_MODES = %w[
-          AscentOffset FixedHeight CapHeight XHeight EmboxHeight
-        ].freeze
-
-        def self.first_baseline_offset(context, state, font)
-          pref = context.item&.text_frame_preference&.first
-          mode = pref&.first_baseline_offset
-          return 0.0 unless FIRST_BASELINE_MODES.include?(mode)
-
-          baseline_target(pref, mode, state, font) -
-            first_paragraph_leading(state)
-        end
-        private_class_method :first_baseline_offset
-
-        # Distance from the top inset to the first baseline under
-        # the given mode.
-        # pdfrb 0.7.1 never fills the cap_height metric, so
-        # CapHeight / XHeight fall back to standard font
-        # proportions (cap ≈ 0.72 em, x ≈ 0.52 em — Arial and
-        # Helvetica both sit within 1% of these).
-        CAP_HEIGHT_RATIO = 0.72
-        X_HEIGHT_RATIO = 0.52
-
-        def self.baseline_target(pref, mode, state, font)
-          leading = first_paragraph_leading(state)
-          case mode
-          when "AscentOffset"
-            ratio_scaled(font.ascent, font) * leading
-          when "CapHeight"
-            cap_ratio(font) * leading
-          when "XHeight"
-            X_HEIGHT_RATIO * leading
-          when "EmboxHeight"
-            first_paragraph_size(state)
-          else
-            pref.minimum_first_baseline_offset || leading
-          end
-        end
-        private_class_method :baseline_target
-
-        def self.cap_ratio(font)
-          cap = font.cap_height
-          return CAP_HEIGHT_RATIO unless cap
-
-          ratio_scaled(cap, font)
-        end
-        private_class_method :cap_ratio
-
-        def self.ratio_scaled(metric, font)
-          upem = font.units_per_em
-          return 1.0 if upem.zero?
-
-          metric / upem
-        end
-        private_class_method :ratio_scaled
-
-        def self.first_paragraph_size(state)
-          paragraph = state.current_paragraph || state.paragraphs.first
-          first_run = paragraph&.runs&.first
-          first_run&.point_size || DEFAULT_SIZE
-        end
-        private_class_method :first_paragraph_size
-
-        def self.first_paragraph_leading(state)
-          paragraph = state.current_paragraph || state.paragraphs.first
-          unless paragraph
-            return DEFAULT_SIZE *
-                TextEngine::VerticalLayout::DEFAULT_LEADING_FACTOR
-          end
-
-          size = paragraph.runs.first&.point_size || DEFAULT_SIZE
-          TextEngine::VerticalLayout.leading_for(paragraph.auto_leading,
-                                                 size)
-        end
-        private_class_method :first_paragraph_leading
-
-        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,
@@ -571,9 +421,9 @@ module Idml
             break if cursor_y < bottom_limit
 
             next_paragraph = state.paragraphs[index + 1]
-            break if paragraph_deferred?(paragraph, next_paragraph,
-                                         layout_frame, font, cursor_y,
-                                         bottom_limit, pending.positive?)
+            break if KeepPolicy.paragraph_deferred?(paragraph, next_paragraph,
+                                                    layout_frame, font, cursor_y,
+                                                    bottom_limit, pending.positive?)
 
             remaining_runs, cursor_y, char_cursor = render_runs_for_paragraph(
               canvas, paragraph, paragraph.runs, context,
@@ -967,130 +817,6 @@ module Idml
         end
         private_class_method :mojikumi_aki_overrides
 
-        # True when the paragraph should move wholly to the next
-        # frame: a StartParagraph forced break, or KeepAllLines-
-        # Together with insufficient remaining space (never for the
-        # frame's first paragraph, so progress is always made).
-        def self.paragraph_deferred?(paragraph, next_paragraph,
-                                     layout_frame, font, cursor_y,
-                                     bottom_limit, placed_any)
-          return true if paragraph_break?(paragraph) && placed_any
-          return false unless placed_any
-          return true if keep_with_next_break?(paragraph, next_paragraph,
-                                               layout_frame, font,
-                                               cursor_y, bottom_limit)
-
-          keep_all_lines_break?(paragraph, layout_frame, font,
-                                cursor_y, bottom_limit) ||
-            keep_windows_break?(paragraph, layout_frame, font,
-                                cursor_y, bottom_limit)
-        end
-        private_class_method :paragraph_deferred?
-
-        # KeepAllLinesTogether: defer when the paragraph cannot
-        # fully fit the remaining space.
-        def self.keep_all_lines_break?(paragraph, layout_frame, font,
-                                       cursor_y, bottom_limit)
-          return false unless paragraph.keep_all_lines_together
-
-          wrap_width = TextEngine::VerticalLayout.wrap_width(
-            layout_frame, paragraph.right_indent || 0
-          )
-          height = TextEngine::Measurement.paragraph_height(
-            paragraph, font, wrap_width
-          )
-          (cursor_y - height) < bottom_limit
-        end
-        private_class_method :keep_all_lines_break?
-
-        # Partial keep windows, approximated by measured line
-        # counts: KeepFirstLines defers when fewer than N lines
-        # fit; KeepLastLines defers when the overflow tail for the
-        # next frame would strand fewer than N lines.
-        def self.keep_windows_break?(paragraph, layout_frame, font,
-                                     cursor_y, bottom_limit)
-          return false unless paragraph.keep_first_lines ||
-            paragraph.keep_last_lines
-
-          wrap_width = TextEngine::VerticalLayout.wrap_width(
-            layout_frame, paragraph.right_indent || 0
-          )
-          height = TextEngine::Measurement.paragraph_height(
-            paragraph, font, wrap_width
-          )
-          return false if (cursor_y - height) >= bottom_limit
-
-          leading = first_paragraph_leading_for(paragraph)
-          lines_fit = [((cursor_y - bottom_limit) / leading).floor, 0].max
-          first_window_break?(paragraph, lines_fit) ||
-            last_window_break?(paragraph, lines_fit, height, leading)
-        end
-        private_class_method :keep_windows_break?
-
-        def self.first_window_break?(paragraph, lines_fit)
-          paragraph.keep_first_lines &&
-            lines_fit < paragraph.keep_first_lines
-        end
-        private_class_method :first_window_break?
-
-        def self.last_window_break?(paragraph, lines_fit, height, leading)
-          return false unless paragraph.keep_last_lines
-
-          total_lines = [(height / leading).ceil, 1].max
-          lines_fit.positive? &&
-            (total_lines - lines_fit) < paragraph.keep_last_lines
-        end
-        private_class_method :last_window_break?
-
-        def self.first_paragraph_leading_for(paragraph)
-          size = paragraph.runs.first&.point_size || DEFAULT_SIZE
-          TextEngine::VerticalLayout.leading_for(paragraph.auto_leading,
-                                                 size)
-        end
-        private_class_method :first_paragraph_leading_for
-
-        # KeepWithNext: this paragraph defers when the next
-        # paragraph is forced to the next frame, or when the next
-        # paragraph's first line would not fit after this one.
-        def self.keep_with_next_break?(paragraph, next_paragraph,
-                                       layout_frame, font, cursor_y,
-                                       bottom_limit)
-          return false unless keepable_pair?(paragraph, next_paragraph)
-          return true if paragraph_break?(next_paragraph)
-
-          wrap_width = TextEngine::VerticalLayout.wrap_width(
-            layout_frame, paragraph.right_indent || 0
-          )
-          height = TextEngine::Measurement.paragraph_height(
-            paragraph, font, wrap_width
-          )
-          (cursor_y - height - follower_leading(next_paragraph)) <
-            bottom_limit
-        end
-        private_class_method :keep_with_next_break?
-
-        def self.keepable_pair?(paragraph, next_paragraph)
-          !paragraph.keep_with_next.nil? && !next_paragraph.nil?
-        end
-        private_class_method :keepable_pair?
-
-        def self.follower_leading(next_paragraph)
-          size = next_paragraph.runs.first&.point_size || DEFAULT_SIZE
-          TextEngine::VerticalLayout.leading_for(
-            next_paragraph.auto_leading, size
-          )
-        end
-        private_class_method :follower_leading
-
-        # True when the paragraph requests a forced break to the
-        # next frame/column (StartParagraph). All break flavors act
-        # at frame/column granularity.
-        def self.paragraph_break?(paragraph)
-          %w[NextPage NextColumn NextFrame NextOddPage NextEvenPage]
-            .include?(paragraph.start_paragraph)
-        end
-        private_class_method :paragraph_break?
-
         # Justifies the run's lines; only the final line of the
         # paragraph's final run stays ragged under full
         # justification.

data/lib/idml/render/text_wrap_resolver.rb

@@ -159,28 +159,6 @@ module Idml
       end
       private :interval_side_adjustment
 
-      # Returns the total horizontal overlap of all contours with a
-      # text line at the given y range within the given x range.
-      # Sum, not max — multiple overlapping contours compound.
-      # Returns 0.0 when there's no overlap. Inverse contours
-      # reduce by the frame width minus their own width (text may
-      # only flow inside).
-      def overlap_width(line_y, line_height, frame_x, frame_right)
-        @contours.sum do |contour|
-          width = if contour.is_a?(WrapContour::Shape)
-                    WrapContour.overlap_width(contour, line_y,
-                                              line_height, frame_x,
-                                              frame_right)
-                  else
-                    line_overlap(contour, line_y, line_height,
-                                 frame_x, frame_right)[:width]
-                  end
-          next width unless contour.inverse
-
-          (frame_right - frame_x) - width
-        end
-      end
-
       # The wrap shape for an item: a bounding-box rectangle
       # (BoundingBoxTextWrap — the legacy "BoundingBox" spelling is
       # also accepted from early synthetic fixtures) or a flattened
@@ -250,13 +228,6 @@ module Idml
       end
       private_class_method :contour_mode?
 
-      def line_overlap(contour, line_y, line_height, frame_x, frame_right)
-        return { width: 0.0 } unless y_overlap?(contour, line_y, line_height)
-        return { width: 0.0 } unless x_overlap?(contour, frame_x, frame_right)
-
-        { width: x_overlap_width(contour, frame_x, frame_right) }
-      end
-
       def y_overlap?(contour, line_y, line_height)
         line_top = line_y + line_height
         line_bottom = line_y

data/lib/idml/render.rb

@@ -100,3 +100,11 @@ Idml::Render::Renderers.autoload(
   :SimpleText,
   "#{__dir__}/render/renderers/simple_text",
 )
+Idml::Render::Renderers.autoload(
+  :FrameMetrics,
+  "#{__dir__}/render/renderers/frame_metrics",
+)
+Idml::Render::Renderers.autoload(
+  :KeepPolicy,
+  "#{__dir__}/render/renderers/keep_policy",
+)

data/lib/idml/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: idml
 version: !ruby/object:Gem::Version
-  version: 0.10.10
+  version: 0.10.12
 platform: ruby
 authors:
 - Ribose
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-29 00:00:00.000000000 Z
+date: 2026-08-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -212,7 +212,9 @@ files:
 - TODO.pdf/146-next-column-wrap.md
 - TODO.pdf/147-side-aware-shapes.md
 - TODO.pdf/148-architecture-improvements.md
+- TODO.pdf/149-architecture-round-two.md
 - TODO.pdf/15-wire-spread-children.md
+- TODO.pdf/150-architecture-round-three.md
 - TODO.pdf/16-typed-model-pipeline.md
 - TODO.pdf/17-shape-rendering.md
 - TODO.pdf/18-text-rendering.md
@@ -502,8 +504,10 @@ files:
 - lib/idml/render/position_tracker.rb
 - lib/idml/render/render_context.rb
 - lib/idml/render/renderers.rb
+- lib/idml/render/renderers/frame_metrics.rb
 - lib/idml/render/renderers/graphic_line_renderer.rb
 - lib/idml/render/renderers/group_renderer.rb
+- lib/idml/render/renderers/keep_policy.rb
 - lib/idml/render/renderers/oval_renderer.rb
 - lib/idml/render/renderers/path_renderer.rb
 - lib/idml/render/renderers/polygon_renderer.rb