idml 0.10.9 → 0.10.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3ebdf83496770ecda7b37cc6f6cdc2388874785ccad23ac57aa396f76aef03b
-  data.tar.gz: d7304a209e09d4de3ee6d9f7556d18053f838ee3fef9a4f787f06693aa42ee32
+  metadata.gz: ea3cefcb949b7fd6399d850354df7fe37e6f822e766994522b9df4ceaa13cfd7
+  data.tar.gz: 531db1a6a0d5ccb32cd7f3fddd751b99d140a5504a3ab7645913167e34fdeb7e
 SHA512:
-  metadata.gz: bd4dc75a85966131506edf7f3e01df91127fbf26525bb02edcf783f0c07580380be0d8bd38562c11a477602731e2efff8de78061580b471f1389f3bb87a07119
-  data.tar.gz: 74286965e709455a356789cc6f7e4c93f75d414a1132301ee8e347a85d114065bd1988921c180a522c646824d79f2049bdfacf7db609e9981b270d3a88b71fbb
+  metadata.gz: 6659beee3fa4e1d325bed4d0ed86a4a1db4c2944010d8a3deffbe3bf029df137187cb3b34fa064b5feecd000abad671fd712fb083caae837796339157bde9e25
+  data.tar.gz: d225c68cea43b34da224e37809cbfa5c0be3abc8775c7f10baee3d1756c69c325a002562070a54a5994ecc7da3883f58bbd407b337b66d9994a99b3532436049

data/TODO.pdf/148-architecture-improvements.md

@@ -0,0 +1,45 @@
+# TODO PDF 148: Codebase architecture improvements
+
+## Status: COMPLETE — implemented 2026-08-29
+
+## Problem
+
+Architecture audit findings:
+
+1. `TextFrameRenderer` was a 1520-line god class owning four
+   unrelated concerns: the horizontal shaping engine, the vertical
+   writing path, the no-metrics fallback, and everything else
+   (chains, endnotes, footnotes, wrap, keep options).
+2. Twelve render specs each declared their own near-identical
+   `*_FONT_CANDIDATES` list (~7 lines each), with two variants
+   drifting apart (some lists lacked the CJK-capable fonts —
+   CJK-dependent specs silently skipped on platforms that had
+   them).
+
+## Solution
+
+- **VerticalEmit** (`renderers/vertical_emit.rb`, ~230 lines): the
+  whole vertical-writing family (vertical_render through
+  ruby_vertical_x), extracted as a class-methods module
+  `extend`ed into TextFrameRenderer — it shares the host's
+  constants, `layout_frame`, and `font_for_run` (MECE: the module
+  owns everything vertical; the host owns the horizontal engine).
+  Zero behavior change; all vertical/ruby specs pass untouched.
+- **SimpleText** (`renderers/simple_text.rb`, ~90 lines): the
+  no-metrics fallback (simple_render, footnote stacking,
+  collect/build rich runs), same extend pattern.
+- **Spec font candidates DRY'd**: `SPEC_FONT_CANDIDATES` +
+  `spec_font_path` in spec_helper; the twelve per-spec constants
+  deleted. Unifying on the CJK-capable superset un-skipped 20
+  previously-skipped examples on CJK-font platforms.
+
+`TextFrameRenderer` is now 1235 lines of cohesive horizontal
+engine + orchestration.
+
+## Files
+
+- `lib/idml/render/renderers/vertical_emit.rb` (new)
+- `lib/idml/render/renderers/simple_text.rb` (new)
+- `lib/idml/render/renderers/text_frame_renderer.rb`
+- `lib/idml/render.rb`
+- `spec/spec_helper.rb` + 12 render specs

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

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    module Renderers
+      # The no-metrics fallback path of TextFrameRenderer: when no
+      # FontMetrics is available (no shaper → no wrap), all runs
+      # emit as one `text_rich` block per frame and footnote text
+      # stacks at the frame bottom. 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.
+      #
+      # A class-methods module extended into TextFrameRenderer —
+      # it shares the host's font resolution (MECE: this module
+      # owns the rough path; the host owns the shaping engine).
+      module SimpleText
+        def simple_render(canvas, state, context, box)
+          runs = collect_runs(state)
+          return if runs.empty?
+
+          runs_for = build_rich_runs(runs, context)
+          first_size = runs.first.point_size ||
+            TextFrameRenderer::DEFAULT_SIZE
+          canvas.text_rich(
+            runs_for,
+            at: [box[:x], box[:y] + box[:height] - first_size],
+          )
+          emit_simple_footnotes(canvas, runs, context, box)
+          state.paragraphs = []
+          state.current_paragraph = nil
+          state.runs_remaining = []
+        end
+
+        # Footnote text for the rough (no-metrics) path: one line
+        # per footnote paragraph, stacked upward from the frame's
+        # bottom edge below a hairline separator. Paragraphs are
+        # already marker-prefixed at extraction.
+        def emit_simple_footnotes(canvas, runs, context, box)
+          paragraphs = runs.flat_map(&:footnote_paragraphs).compact
+          return if paragraphs.empty?
+
+          size = paragraphs.first.runs.first&.point_size ||
+            TextFrameRenderer::DEFAULT_SIZE
+          block_top = box[:y] + (paragraphs.length * size)
+          canvas.line_width = 0.5
+          canvas.stroke_color([:gray, 0.0])
+          canvas.move_to(box[:x], block_top + (size * 0.3))
+          canvas.line_to(box[:x] + (box[:width] * 0.25),
+                         block_top + (size * 0.3))
+          canvas.stroke
+
+          paragraphs.reverse_each.with_index do |paragraph, index|
+            canvas.text_rich(
+              build_rich_runs(paragraph.runs, context),
+              at: [box[:x], box[:y] + ((index + 1) * size)],
+            )
+          end
+        end
+
+        def 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
+
+        def build_rich_runs(runs, context)
+          runs.map do |run|
+            {
+              text: run.text,
+              font: font_for_run(run, context),
+              size: run.point_size || TextFrameRenderer::DEFAULT_SIZE,
+            }
+          end
+        end
+      end
+    end
+  end
+end