idml 0.9.8 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29f97721ebdd63304b8c879eaa45764906dfa40b85363688aa9d860ccdd6f62c
-  data.tar.gz: 439a3e3454be081957617ce5107ae735a47d56c4dc206104d3e483c5a20db669
+  metadata.gz: 13770ed8937eeed41a40bd223bb8caadc833da870858d691caa0e1806058c286
+  data.tar.gz: dec0fe8f24c1aaa8258ecf18506560b1e0793bd7d4ebe56bf361dc1a69ff736a
 SHA512:
-  metadata.gz: 0c669bcf817d1e2b8ab74c116e3a0e472b8ca5529fdfeba4f0adb85d7f1ddb78da5d422c63907cbe68f4a7c381ce5862d17b674063070bce64e9664584159b97
-  data.tar.gz: b427dc2a77703a71074fc541eb8eea36485dc78607dea9faa8f13d3ca69c70e013a749374ef8abca81057bdf5e7563f6717bea30e45ad967a5836ead3e325d6a
+  metadata.gz: '0394efac9722c854cd4e8c2771d0ec494aaa8d3b50ca6ea471bbe8f5f44daf62a1f1bd4d12031ee9d59b0d7b6c5f65f5378db661d5a110d056734958369a870e'
+  data.tar.gz: 07d3a9492ea5a41819f4fe0353176671307ad7263feedeb909bd08f8284eb79b84df0fef0057db1d089a3a02ff7d255459ea2e232e5c929d3d1ffccc70685e81

data/TODO.pdf/127-keep-with-next.md

@@ -0,0 +1,20 @@
+# TODO PDF 127: KeepWithNext
+
+## Status: COMPLETE — implemented 2026-08-20
+
+## What was done
+
+- `StyleResolver::Paragraph` carries `keep_with_next` from the PSR.
+- A paragraph with KeepWithNext defers to the next frame when the
+  FOLLOWING paragraph is forced there (StartParagraph break) or
+  when the follower's first line would not fit after this
+  paragraph (pre-measured via TextEngine::Measurement plus the
+  follower's leading). Combined with TODO 123's KeepAllLinesTogether,
+  both keep flavors share one deferral predicate in
+  `consume_paragraphs`.
+
+## Known limitations
+
+- The numeric strength of KeepWithNext (1–5, lines to keep) is
+  treated as boolean.
+- Not applied in vertical writing mode.

data/TODO.pdf/128-first-baseline-offset.md

@@ -0,0 +1,21 @@
+# TODO PDF 128: Text frame FirstBaselineOffset
+
+## Status: COMPLETE — implemented 2026-08-23
+
+## What was done
+
+`TextFrameRenderer` honors
+`TextFramePreference.FirstBaselineOffset` when positioning the
+first line's baseline: AscentOffset places it ascent-below the top
+inset (typically higher than the default leading-based position);
+FixedHeight uses MinimumFirstBaselineOffset. LeadingOffset /
+CapHeight / XHeight / EmboxHeight approximate as the existing
+leading-based default (cap/x-height metrics are not exposed by
+PdfrbFontMetrics). Applied in both the single-column and
+multi-column paths.
+
+## Known limitations
+
+- CapHeight / XHeight offsets fall back to leading (font metrics
+  expose ascent only).
+- Not applied in vertical writing mode.

data/TODO.pdf/129-justification-glyph-scaling.md

@@ -0,0 +1,18 @@
+# TODO PDF 129: Justification glyph scaling
+
+## Status: COMPLETE — implemented 2026-08-23
+
+## What was done
+
+`Justifier` distributes any residual slack remaining after the
+word-spacing and letter-spacing caps as uniform glyph scaling,
+capped at `MaximumGlyphScaling` (PSR → Paragraph → SpacingLimits).
+InDesign's default cap (100%) disables scaling — only documents
+that relax the cap get stretched glyphs, matching TODO 119's
+layered distribution: words first, then letters, then glyphs.
+
+## Known limitations
+
+- MinimumGlyphScaling (compression of overlong lines) is not
+  applied — the breaker never produces overlong justified lines
+  except forced unbreakable runs.

data/TODO.pdf/61-known-limitations.md

@@ -1,35 +1,54 @@
 # TODO PDF 61: Known limitations and future work
 
-## Status: DOCUMENTED
+## Status: DOCUMENTED — refreshed 2026-08-20
 
-## Known limitations
-
-1. **Font embedding**: pdfrb 0.3.0 registers fonts by name but does
-   not embed FontFile2 binary data in the PDF. Text renders correctly
-   on systems with the font installed but may not render on other
-   systems. Requires pdfrb font subsetting support (TODO 52).
+Previously listed limitations (font embedding, tagged PDF, per-run
+styling, dead code) were resolved by TODOs 52/53/55/67/76 long ago;
+this list reflects the current state.
 
-2. **Image fixture tests**: The fixture IDML references an external
-   JPEG at a macOS-specific path. Tests that check image embedding
-   are skipped on CI. A self-contained fixture with an embedded image
-   would fix this.
-
-3. **Text engine integration**: TextFrameRenderer uses the text engine
-   for line breaking when FontMetrics is available (Helvetica as .ttf).
-   On macOS, Helvetica is a .ttc collection, so the fallback simple
-   renderer is used (no line breaking). Per-run styling (different
-   fonts/sizes in one frame) is simplified to use the first run's style.
+## Known limitations
 
-4. **Dead code**: Old modules (PdfWriter, FontEmbedder, Color, Path,
-   Text) are marked DEPRECATED but cannot be deleted per the project's
-   "never delete source files" policy. They are not used by any active
-   code path.
+### Text layout
+- **Hyphenation** is not implemented (Hyphenation* attributes are
+  parsed but unused); a hyphenation dictionary would be required.
+- **Justification**: word/letter spacing caps apply (TODO 119) and
+  MaximumGlyphScaling stretches as the last resort (TODO 129);
+  MinimumGlyphScaling compression and ToBinding / RTL binding
+  alignment are not applied.
+- **Keep options**: whole-paragraph KeepAllLinesTogether (TODO
+  123) and KeepWithNext (TODO 127) are honored; partial keep
+  windows (KeepFirstLines / KeepLastLines) are not.
+- **First baseline**: AscentOffset and FixedHeight are honored
+  (TODO 128); CapHeight / XHeight approximate as leading.
+- **StartParagraph** breaks act at frame/column granularity — no
+  odd/even page parity.
+- **Text wrap** (TODO 114): BoundingBox mode only; Shape contour
+  following and Inverse mode are not implemented.
+
+### CJK
+- **Mojikumi**: CJK/Latin auto script spacing is applied (TODO
+  125); full class-based punctuation compression tables are not.
+- **Vertical mode**: Latin rotation is per glyph (not run-grouped);
+  ruby placement is beside-column; keep options do not apply.
+
+### Structural features
+- **Endnotes** (TODO 117): reference markers render; endnote TEXT
+  rendering is gated on a real fixture (the EndnoteTextRange
+  reference chain is opaque without one).
+- **Footnotes** number per story; overflow balancing (NoSplitting)
+  is not modeled; the simple-render fallback shows markers without
+  footnote text.
+- **Anchored objects** render at stored geometry; AnchorType
+  text-reflow is not simulated.
+- **Tables** do not span frames (no repeated header rows); diagonal
+  cell strokes are modeled but not drawn.
+- **Inline anchored objects / footnotes inside table cells** are
+  not handled.
 
 ## Future enhancements
 
-- Font subsetting (TODO 52) — requires pdfrb enhancement
-- Tagged PDF / PDF/UA (TODO 53) — requires pdfrb StructTreeRoot
-- Dead code removal (TODO 51) — when policy allows
-- Self-contained test fixture with embedded image
-- Per-run text styling with cursor tracking
+- Hyphenation dictionary integration
+- Shape-mode text wrap contours
+- Frame-spanning tables with header repeats
+- Class-based mojikumi tables
 - Performance benchmark for 100+ page documents

data/lib/idml/render/footnote.rb

@@ -131,6 +131,7 @@ module Idml
           limits = TextEngine::Justifier::SpacingLimits.new(
             max_word_spacing: paragraph.maximum_word_spacing,
             max_letter_spacing: paragraph.maximum_letter_spacing,
+            max_glyph_scaling: paragraph.maximum_glyph_scaling,
           )
           lines.each_with_index do |line, index|
             TextEngine::Justifier.justify(

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

@@ -433,6 +433,7 @@ module Idml
           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)
           char_cursor = state.char_cursor
 
           if state.current_paragraph
@@ -473,7 +474,7 @@ 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
+          cursor_y = top_y - first_baseline_offset(context, state, font)
           char_cursor = state.char_cursor
 
           if state.current_paragraph
@@ -564,6 +565,53 @@ module Idml
         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 / XHeight / EmboxHeight approximate as leading.
+        # Returns the extra shift to subtract from the cursor.
+        def self.first_baseline_offset(context, state, font)
+          pref = context.item&.text_frame_preference&.first
+          mode = pref&.first_baseline_offset
+          return 0.0 unless %w[AscentOffset FixedHeight].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.
+        def self.baseline_target(pref, mode, state, font)
+          if mode == "AscentOffset"
+            ascent_scaled(font) * first_paragraph_leading(state)
+          else
+            pref.minimum_first_baseline_offset ||
+              first_paragraph_leading(state)
+          end
+        end
+        private_class_method :baseline_target
+
+        def self.ascent_scaled(font)
+          upem = font.units_per_em.zero? ? 1 : font.units_per_em
+          font.ascent / upem
+        end
+        private_class_method :ascent_scaled
+
+        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
@@ -629,11 +677,13 @@ module Idml
                                     cursor_y, bottom_limit, char_cursor,
                                     footnotes)
           pending = 0
-          state.paragraphs.each do |paragraph|
+          state.paragraphs.each_with_index do |paragraph, index|
             break if cursor_y < bottom_limit
-            break if paragraph_deferred?(paragraph, layout_frame, font,
-                                         cursor_y, bottom_limit,
-                                         pending.positive?)
+
+            next_paragraph = state.paragraphs[index + 1]
+            break if 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,
@@ -969,11 +1019,25 @@ module Idml
         # 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, layout_frame, font,
-                                     cursor_y, bottom_limit, placed_any)
+        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 paragraph.keep_all_lines_together
           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)
+        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
@@ -983,7 +1047,40 @@ module Idml
           )
           (cursor_y - height) < bottom_limit
         end
-        private_class_method :paragraph_deferred?
+        private_class_method :keep_all_lines_break?
+
+        # 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
@@ -1002,6 +1099,7 @@ module Idml
           limits = TextEngine::Justifier::SpacingLimits.new(
             max_word_spacing: paragraph.maximum_word_spacing,
             max_letter_spacing: paragraph.maximum_letter_spacing,
+            max_glyph_scaling: paragraph.maximum_glyph_scaling,
           )
           lines.each_with_index do |line, index|
             TextEngine::Justifier.justify(

data/lib/idml/render/style_resolver.rb

@@ -68,12 +68,16 @@ module Idml
         # Justification distribution caps (percent; from PSR).
         :maximum_word_spacing,
         :maximum_letter_spacing,
+        :maximum_glyph_scaling,
         # Forced paragraph break (StartParagraph: NextPage /
         # NextColumn / NextFrame / NextOddPage / NextEvenPage).
         :start_paragraph,
         # Widow/orphan control: KeepAllLinesTogether pushes the whole
-        # paragraph to the next frame when it cannot fully fit.
+        # paragraph to the next frame when it cannot fully fit;
+        # KeepWithNext binds this paragraph to the next paragraph's
+        # first line.
         :keep_all_lines_together,
+        :keep_with_next,
         :bullets_and_numbering_list_type,
         :bullet_character_value,
         :bullets_text_after,
@@ -202,11 +206,16 @@ module Idml
             maximum_letter_spacing: resolve_attr(
               style_lookup, psr, :maximum_letter_spacing
             ),
+            maximum_glyph_scaling: resolve_attr(
+              style_lookup, psr, :maximum_glyph_scaling
+            ),
             start_paragraph: resolve_attr(style_lookup, psr,
                                           :start_paragraph),
             keep_all_lines_together: resolve_attr(
               style_lookup, psr, :keep_all_lines_together
             ),
+            keep_with_next: resolve_attr(style_lookup, psr,
+                                         :keep_with_next),
             drop_cap_lines: resolve_attr(style_lookup, psr, :drop_cap_lines),
             drop_cap_characters: resolve_attr(style_lookup, psr,
                                               :drop_cap_characters),

data/lib/idml/text_engine/justifier.rb

@@ -10,11 +10,13 @@ module Idml
       # Justification distribution caps, in percent (100 = natural).
       # InDesign defaults: word spacing max 133%, letter spacing 0%.
       SpacingLimits = Struct.new(
-        :max_word_spacing, :max_letter_spacing, keyword_init: true
+        :max_word_spacing, :max_letter_spacing, :max_glyph_scaling,
+        keyword_init: true
       )
 
       DEFAULT_MAX_WORD_SPACING = 133.0
       DEFAULT_MAX_LETTER_SPACING = 0.0
+      DEFAULT_MAX_GLYPH_SCALING = 100.0
 
       def self.justify(line:, frame_width:, alignment: :left,
                        last_line: false, limits: nil)
@@ -63,7 +65,12 @@ module Idml
           glyph.width += extra
         end
         residual = slack - word_share
-        distribute_letter_spacing(line, residual) if residual.positive?
+        return unless residual.positive?
+
+        before = line.glyphs.sum(&:width)
+        distribute_letter_spacing(line, residual)
+        residual -= (line.glyphs.sum(&:width) - before)
+        distribute_glyph_scaling(line, residual) if residual.positive?
       end
 
       # Total room the word spaces may grow within the max-word-
@@ -91,6 +98,23 @@ module Idml
         line.glyphs.each { |glyph| glyph.width += add }
       end
       private :distribute_letter_spacing
+
+      # Last resort: uniform glyph scaling for any remaining slack,
+      # capped at max_glyph_scaling percent. InDesign's default cap
+      # (100%) disables it; only documents that relax the cap get
+      # stretched glyphs.
+      def distribute_glyph_scaling(line, residual)
+        max_pct = @limits&.max_glyph_scaling || DEFAULT_MAX_GLYPH_SCALING
+        grow = (max_pct - 100) / 100.0
+        return unless grow.positive?
+
+        total = line.glyphs.sum(&:width)
+        return unless total.positive?
+
+        factor = [residual / total, grow].min
+        line.glyphs.each { |glyph| glyph.width *= (1 + factor) }
+      end
+      private :distribute_glyph_scaling
     end
   end
 end

data/lib/idml/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: idml
 version: !ruby/object:Gem::Version
-  version: 0.9.8
+  version: 0.10.0
 platform: ruby
 authors:
 - Ribose
@@ -185,6 +185,9 @@ files:
 - TODO.pdf/124-tatechuyoko-vertical.md
 - TODO.pdf/125-script-spacing.md
 - TODO.pdf/126-part-cache.md
+- TODO.pdf/127-keep-with-next.md
+- TODO.pdf/128-first-baseline-offset.md
+- TODO.pdf/129-justification-glyph-scaling.md
 - TODO.pdf/13-cjk-text-layout.md
 - TODO.pdf/14-page-item-element-models.md
 - TODO.pdf/15-wire-spread-children.md