idml 0.10.0 → 0.10.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 13770ed8937eeed41a40bd223bb8caadc833da870858d691caa0e1806058c286
-  data.tar.gz: dec0fe8f24c1aaa8258ecf18506560b1e0793bd7d4ebe56bf361dc1a69ff736a
+  metadata.gz: 40262a683342f0a9308e33ab2cce4a8bcf6b803288d6a0bc3ece3d2b376c6761
+  data.tar.gz: 78cb5495d1d9b72d5e850c6d25c8cd594622d6484476ea61a1ff239df41e9e99
 SHA512:
-  metadata.gz: '0394efac9722c854cd4e8c2771d0ec494aaa8d3b50ca6ea471bbe8f5f44daf62a1f1bd4d12031ee9d59b0d7b6c5f65f5378db661d5a110d056734958369a870e'
-  data.tar.gz: 07d3a9492ea5a41819f4fe0353176671307ad7263feedeb909bd08f8284eb79b84df0fef0057db1d089a3a02ff7d255459ea2e232e5c929d3d1ffccc70685e81
+  metadata.gz: b10228f8870d90e1a66f8fb9b621a26951db4a71e155a3f28165c22a3e9c44b53e7dbc17916ec4b5db0f49987403e4e645e5f0872a79cb0fe591881ff6f9caca
+  data.tar.gz: d4904d3ef2a6d0b1c4dfcd497597042fcedee1b5c3c1643ff892ac867e7b4c3f0881419a906527e5f1705a64292c8c5c5e06ae8af774b8ce725f81c8bcf9ff92

data/README.adoc

@@ -1,4 +1,64 @@
-= Ruby parser for Adobe IDML
+= idml
 
-IDML is the InDesign Markup Language from Adobe used by InDesign.
+A pure-Ruby toolkit for Adobe InDesign IDML files: parse, validate,
+round-trip, compose, and render to PDF.
 
+== What it does
+
+* **Parse & round-trip** — every IDML part is a typed
+  `Lutaml::Model` class generated from Adobe's RelaxNG schemas
+  (`reference-docs/schemas/`): byte-faithful re-serialization with
+  `ZIP_STORED` mimetype ordering preserved.
+* **Validate** — RelaxNG validation against the committed InDesign
+  2026 (DOMVersion 21.5) schemas.
+* **Compose** — `insert_idml`, `add_page_from_idml`, `prefix`,
+  `import_xml`/`export_xml` (ported from SimpleIDML).
+* **Render to PDF** — a full pure-Ruby layout + paint pipeline
+  (pdfrb): multi-frame threaded stories, justification with
+  word/letter/glyph limits, footnotes (bottom-of-frame with
+  separator rules), anchored objects, tables (row/column banding,
+  per-side cell strokes, merged cells), Bézier shape contours,
+  gradients, text wrap (bounding-box, contour, and inverse modes),
+  paragraph shading/borders/rules, drop caps, bullets & numbering,
+  CJK layout (kinsoku shori, ruby, vertical writing with
+  tate-chu-yoko and rotated Latin, script spacing, line-end
+  punctuation compression), tagged PDF, hyperlinks, bookmarks,
+  PDF/A, and font subsetting.
+
+== Install
+
+....
+gem install idml
+....
+
+`.indd` files are a proprietary binary format — export them to
+`.idml` from InDesign first (File → Export), or use InDesign Server
+for headless automation.
+
+== Quick start
+
+....
+require "idml"
+
+# Round-trip a package
+pkg  = Idml::Package.new("doc.idml")
+spec = pkg.spreads.first
+
+# Render to PDF
+Idml.render(package: pkg, to: "doc.pdf")
+....
+
+== Requirements
+
+* Ruby >= 3.3 (tested through 4.0 on macOS/Linux/Windows)
+
+== Reference material
+
+The `reference-docs/` tree carries Adobe's IDML specification, the
+Plug-in SDK's idmltools (behavioral ground truth), and the
+generated RelaxNG schemas — the attribute authority for every
+model class.
+
+== License
+
+BSD-2-Clause.

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

@@ -1,6 +1,8 @@
 # TODO PDF 114: Text wrap around shapes (TextWrapPreference)
 
-## Status: DONE for BoundingBox mode — `Render::TextWrapResolver` computes
+## Status: COMPLETE for BoundingBoxTextWrap + Contour (Contour and
+the schema-spelling enum fix landed 2026-08-23 as TODO 130; Inverse
+mode remains open) — `Render::TextWrapResolver` computes
 wrap contours from page items declaring TextWrapPreference with
 TextWrapMode != "None". SpreadRenderer builds the resolver and passes
 it via RenderContext. TextFrameRenderer's `text_wrap_overlap` queries

data/TODO.pdf/13-cjk-text-layout.md

@@ -24,7 +24,8 @@ kinsoku shori, ruby annotations).
 and vertical ruby (TODO 122), CJK/Latin automatic script spacing
 (TODO 125, a mojikumi subset wired into Shaper). The remaining
 stretch goal is full class-based mojikumi (per-pair punctuation
-compression tables). See `lib/idml/text_engine/cjk_layout.rb` and
+compression tables); line-end punctuation compression landed
+2026-08-23 as TODO 132. See `lib/idml/text_engine/cjk_layout.rb` and
 `lib/idml/text_engine/vertical_text_layout.rb`.
 
 ## Progress 2026-08-17

data/TODO.pdf/130-contour-text-wrap.md

@@ -0,0 +1,38 @@
+# TODO PDF 130: Shape-mode (Contour) text wrap
+
+## Status: COMPLETE — implemented 2026-08-23
+
+## Problem
+
+Two gaps in the text wrap (TODO 114):
+
+1. The TextWrapMode dispatch compared against "BoundingBox" — the
+   schema enum (TextWrapModes_EnumValue in datatype.rnc) spells it
+   "BoundingBoxTextWrap", so REAL documents never matched any mode
+   and text never wrapped.
+2. Contour mode (text following the item's actual shape) was not
+   implemented at all.
+
+## What was done
+
+- Enum fix: BoundingBoxTextWrap accepted (legacy "BoundingBox"
+  spelling kept for the synthetic fixtures); JumpObjectTextWrap /
+  NextColumnTextWrap approximate as the bounding box (the per-run
+  width reduction already pushes text past the object);
+  Contour gets real contour following.
+- `Render::WrapContour`: flattens the item's PathGeometry (Bézier
+  segments sampled at 8 steps, ItemTransform applied, y flipped)
+  into PDF-space polygons — one per subpath, so compound paths
+  with holes work via even-odd ray casting at the text band's
+  midline. The overlap intervals expand by the TextWrapOffset
+  bounds (`Properties > TextWrapOffset`, now modeled on
+  TextWrapPreference via TypedValue) and clip to the frame.
+- `TextWrapResolver` dispatches per mode; overlap_width handles
+  both the box rect and polygon shapes.
+
+## Known limitations
+
+- Band coverage samples the midline (sub-half-line-height notches
+  are missed); offsets expand intervals uniformly rather than
+  offsetting the polygon geometrically; Inverse mode is not
+  implemented (falls back to no wrap).

data/TODO.pdf/131-inverse-wrap.md

@@ -0,0 +1,19 @@
+# TODO PDF 131: Inverse text wrap
+
+## Status: COMPLETE — implemented 2026-08-23
+
+## What was done
+
+`TextWrapPreference Inverse="true"` flips the wrap region: text
+may only flow INSIDE the wrap shape (the avoid-region becomes
+everything outside it within the frame). Works for both the
+bounding-box contour and the Contour-mode polygon shape (TODO
+130); the inversion lives in one place — TextWrapResolver's
+overlap dispatch — and reduces by (frame width − inside width),
+so bands outside the shape block text entirely.
+
+## Known limitations
+
+- Side-aware narrowing is not implemented: the reduction shrinks
+  the wrap width from the right regardless of which side the
+  shape occupies.

data/TODO.pdf/132-line-end-compression.md

@@ -0,0 +1,22 @@
+# TODO PDF 132: Line-end punctuation compression (mojikumi subset 2)
+
+## Status: COMPLETE — implemented 2026-08-23
+
+## What was done
+
+`CjkLayout.apply_line_end_compression`: a CJK line whose final
+glyph is full-width closing punctuation (。、」』）］｝ー etc.) renders
+that glyph at half advance (行末約物半角詰め), tightening the line
+as InDesign's default mojikumi does. Applied in LineBreaker's CJK
+post-pass after kinsoku shori, so horizontal and vertical layout
+both benefit.
+
+Also fixed a latent bug the specs caught: kinsoku's return value
+(new dup'd line array) was discarded when composing the post-pass
+chain — kinsoku adjustments silently vanished once a second
+post-pass followed it.
+
+## Remaining from TODO 13
+
+Per-pair punctuation compression tables (full class-based
+mojikumi).

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

@@ -22,12 +22,14 @@ this list reflects the current state.
   (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.
+- **Text wrap**: BoundingBoxTextWrap, Contour, and Inverse modes
+  render (TODOs 130-131); JumpObject/NextColumn approximate as
+  the box; side-aware narrowing is not implemented.
 
 ### CJK
-- **Mojikumi**: CJK/Latin auto script spacing is applied (TODO
-  125); full class-based punctuation compression tables are not.
+- **Mojikumi**: CJK/Latin auto script spacing (TODO 125) and
+  line-end punctuation compression (TODO 132) are applied; full
+  class-based compression tables are not.
 - **Vertical mode**: Latin rotation is per glyph (not run-grouped);
   ruby placement is beside-column; keep options do not apply.
 

data/lib/idml/elements/properties.rb

@@ -16,6 +16,7 @@ module Idml
       attribute :rule_below_color, Idml::Elements::TypedValue
       attribute :paragraph_shading_color, Idml::Elements::TypedValue
       attribute :paragraph_border_color, Idml::Elements::TypedValue
+      attribute :text_wrap_offset, Idml::Elements::TypedValue
       attribute :paragraph_border_gap_color, Idml::Elements::TypedValue
 
       xml do
@@ -26,6 +27,7 @@ module Idml
         map_element "RuleBelowColor", to: :rule_below_color
         map_element "ParagraphShadingColor", to: :paragraph_shading_color
         map_element "ParagraphBorderColor", to: :paragraph_border_color
+        map_element "TextWrapOffset", to: :text_wrap_offset
         map_element "ParagraphBorderGapColor", to: :paragraph_border_gap_color
       end
 

data/lib/idml/elements/text_wrap_preference.rb

@@ -11,6 +11,7 @@ module Idml
       attribute :apply_to_master_page_only, :boolean
       attribute :text_wrap_side, :string
       attribute :text_wrap_mode, :string
+      attribute :properties, Idml::Elements::Properties, collection: true
 
       xml do
         root "TextWrapPreference"
@@ -18,6 +19,7 @@ module Idml
         map_attribute "ApplyToMasterPageOnly", to: :apply_to_master_page_only
         map_attribute "TextWrapSide", to: :text_wrap_side
         map_attribute "TextWrapMode", to: :text_wrap_mode
+        map_element "Properties", to: :properties
       end
     end
   end

data/lib/idml/render/text_wrap_resolver.rb

@@ -14,7 +14,7 @@ module Idml
     class TextWrapResolver
       # A wrap contour: a PDF-coordinate rectangle the text avoids.
       Contour = Struct.new(
-        :x, :y, :width, :height,
+        :x, :y, :width, :height, :inverse,
         keyword_init: true
       )
 
@@ -40,20 +40,45 @@ module Idml
       # 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.
+      # 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|
-          overlap = line_overlap(contour, line_y, line_height,
-                                 frame_x, frame_right)
-          overlap[:width]
+          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
+      # PathGeometry polygon (Contour mode). JumpObject /
+      # NextColumn modes approximate as the bounding box (the
+      # per-run width reduction already pushes text past the
+      # object).
       def self.contour_for(item, page_height)
         pref = wrap_preference(item)
         return nil unless pref
-        return nil unless bounding_box_mode?(pref)
 
+        if contour_mode?(pref)
+          WrapContour.shape(item, pref, page_height)
+        else
+          box_contour(item, page_height)
+        end
+      end
+      private_class_method :contour_for
+
+      def self.box_contour(item, page_height)
         bounds = item.geometric_bounds
         return nil unless bounds
 
@@ -64,7 +89,7 @@ module Idml
           width: rect[:width], height: rect[:height]
         )
       end
-      private_class_method :contour_for
+      private_class_method :box_contour
 
       # Page item types that can declare TextWrapPreference per the
       # Spread schema. Used to guard the attribute read — querying
@@ -95,10 +120,10 @@ module Idml
       end
       private_class_method :wrappable?
 
-      def self.bounding_box_mode?(pref)
-        pref.text_wrap_mode == "BoundingBox"
+      def self.contour_mode?(pref)
+        pref.text_wrap_mode == "Contour"
       end
-      private_class_method :bounding_box_mode?
+      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)

data/lib/idml/render/wrap_contour.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # Shape-mode text wrap: builds a PDF-space polygon from a page
+    # item's PathGeometry (Bézier segments flattened at a fixed
+    # resolution) and measures the horizontal overlap of a text
+    # line's band with the polygon, expanded by the wrap offsets.
+    # Band coverage uses even-odd ray casting at the band's
+    # midline, so compound paths with holes wrap correctly.
+    module WrapContour
+      FLATTEN_STEPS = 8
+
+      # A wrap shape: flattened polygons (one per subpath) plus the
+      # TextWrapOffset bounds. `inverse` flips the wrap region:
+      # text may only flow INSIDE the shape.
+      Shape = Struct.new(:polygons, :offset, :inverse,
+                         keyword_init: true)
+
+      # Builds the wrap shape for an item's PathGeometry and wrap
+      # preference. Returns nil when the item has no geometry.
+      def self.shape(item, pref, page_height)
+        polygons = polygons_for(item, page_height)
+        return nil if polygons.empty?
+
+        Shape.new(polygons: polygons, offset: wrap_offset(pref),
+                  inverse: pref.inverse)
+      end
+
+      def self.polygons_for(item, page_height)
+        transform = Geometry.parse_transform(item.item_transform)
+        paths = item.properties.flat_map do |props|
+          props.path_geometry.flat_map(&:geometry_path_type)
+        end
+        paths.filter_map do |path|
+          points = flatten_path(path, transform, page_height)
+          points.length >= 3 ? points : nil
+        end
+      end
+      private_class_method :polygons_for
+
+      # Flattens one subpath's Bézier segments into line segments
+      # in PDF space (ItemTransform applied, y flipped).
+      def self.flatten_path(path, transform, page_height)
+        anchors = path.points
+        return [] if anchors.length < 2
+
+        open = path.path_open == true
+        segments = open ? anchors.length - 1 : anchors.length
+        points = [pdf_point(anchors.first, transform, page_height)]
+        segments.times do |index|
+          from = anchors[index]
+          to = anchors[(index + 1) % anchors.length]
+          append_segment(points, from, to, transform, page_height)
+        end
+        points
+      end
+      private_class_method :flatten_path
+
+      def self.append_segment(points, from, to, transform, page_height)
+        c1 = pair_or_nil(from, :right_direction, transform, page_height)
+        c2 = pair_or_nil(to, :left_direction, transform, page_height)
+        start = points.last
+        if c1.nil? && c2.nil?
+          points << pdf_point(to, transform, page_height)
+          return
+        end
+
+        c1 ||= start
+        c2 ||= pdf_point(to, transform, page_height)
+        (1..FLATTEN_STEPS).each do |step|
+          t = step.to_f / FLATTEN_STEPS
+          points << bezier_point(start, c1, c2,
+                                 pdf_point(to, transform, page_height), t)
+        end
+      end
+      private_class_method :append_segment
+
+      def self.bezier_point(p0, p1, p2, p3, t)
+        u = 1 - t
+        w0 = u * u * u
+        w1 = 3 * u * u * t
+        w2 = 3 * u * t * t
+        w3 = t * t * t
+        [
+          (w0 * p0[0]) + (w1 * p1[0]) + (w2 * p2[0]) + (w3 * p3[0]),
+          (w0 * p0[1]) + (w1 * p1[1]) + (w2 * p2[1]) + (w3 * p3[1]),
+        ]
+      end
+      private_class_method :bezier_point
+
+      def self.pair_or_nil(point, direction_attr, transform, page_height)
+        raw = point.public_send(direction_attr)
+        raw = nil if raw && raw.strip.empty?
+        raw && pdf_pair(raw, transform, page_height)
+      end
+      private_class_method :pair_or_nil
+
+      def self.pdf_point(point, transform, page_height)
+        pdf_pair(point.anchor, transform, page_height)
+      end
+      private_class_method :pdf_point
+
+      def self.pdf_pair(raw, transform, page_height)
+        x, y = raw.to_s.split(/\s+/).map(&:to_f)
+        tx, ty = Geometry.apply_transform(transform, x, y)
+        [tx, page_height - ty]
+      end
+      private_class_method :pdf_pair
+
+      # The wrap offsets from Properties > TextWrapOffset
+      # ("top left bottom right"); zero when absent.
+      def self.wrap_offset(pref)
+        raw = pref.properties.first&.text_wrap_offset&.value
+        parts = raw.to_s.split(/\s+/).map(&:to_f)
+        return [0.0, 0.0] if parts.length < 4
+
+        [parts[1], parts[3]] # left, right
+      end
+      private_class_method :wrap_offset
+
+      # Total horizontal overlap of the text line's band with the
+      # shape, expanded by the offsets and clipped to the frame.
+      # The caller (TextWrapResolver) owns inverse flipping.
+      def self.overlap_width(shape, line_y, line_height, frame_x,
+                             frame_right)
+        mid_y = line_y + (line_height / 2.0)
+        width = shape.polygons.sum do |polygon|
+          polygon_overlap(polygon, mid_y, shape.offset)
+        end
+        clip_width(width, frame_x, frame_right)
+      end
+
+      # Even-odd intervals at mid_y expanded by [left, right]
+      # offsets, summed (separate subpaths sum; the common case is
+      # one polygon).
+      def self.polygon_overlap(polygon, mid_y, offset)
+        crossings = edge_crossings(ring(polygon), mid_y).sort
+        return 0.0 if crossings.length < 2
+
+        left, right = offset
+        crossings.each_slice(2).sum do |entry_x, exit_x|
+          (exit_x + right) - (entry_x - left)
+        end
+      end
+      private_class_method :polygon_overlap
+
+      # Closes the polygon ring (each_cons alone misses the
+      # last→first edge).
+      def self.ring(polygon)
+        polygon + [polygon.first]
+      end
+      private_class_method :ring
+
+      def self.edge_crossings(points, mid_y)
+        points.each_cons(2).filter_map do |(x1, y1), (x2, y2)|
+          next unless crosses_midline?(y1, y2, mid_y)
+
+          t = (mid_y - y1) / (y2 - y1)
+          x1 + (t * (x2 - x1))
+        end
+      end
+      private_class_method :edge_crossings
+
+      def self.crosses_midline?(y1, y2, mid_y)
+        (y1 <= mid_y && y2 > mid_y) || (y2 <= mid_y && y1 > mid_y)
+      end
+      private_class_method :crosses_midline?
+
+      def self.clip_width(width, frame_x, frame_right)
+        [width, frame_right - frame_x].min
+      end
+      private_class_method :clip_width
+    end
+  end
+end

data/lib/idml/render.rb

@@ -25,6 +25,7 @@ module Idml
     autoload :Footnote,            "#{__dir__}/render/footnote"
     autoload :ShapePaint,          "#{__dir__}/render/shape_paint"
     autoload :Contour,             "#{__dir__}/render/contour"
+    autoload :WrapContour,         "#{__dir__}/render/wrap_contour"
     autoload :Placement,           "#{__dir__}/render/placement"
     autoload :ImageCollector,      "#{__dir__}/render/image_collector"
     autoload :StructureTracker,    "#{__dir__}/render/structure_tracker"

data/lib/idml/text_engine/cjk_layout.rb

@@ -39,6 +39,41 @@ module Idml
           (0x61..0x7A).cover?(codepoint)
       end
 
+      # Mojikumi subset 2: line-end punctuation compression —
+      # full-width closing punctuation occupying a line's final
+      # position renders at half advance (行末約物半角詰め),
+      # tightening the line as InDesign's default mojikumi does.
+      TRAILING_COMPRESSION_CODEPOINTS = [
+        0x3001, # 、 ideographic comma
+        0x3002, # 。 ideographic full stop
+        0x3009, # 〉
+        0x300B, # 》
+        0x300D, # 」
+        0x300F, # 』
+        0x3011, # 】
+        0x3015, # 〕
+        0xFF09, # ）fullwidth right paren
+        0xFF3D, # ］
+        0xFF5D, # ｝
+        0x30FC, # ー prolonged sound mark
+      ].freeze
+
+      def apply_line_end_compression(lines)
+        lines.each do |line|
+          last = line.glyphs.last
+          next unless last
+          next unless compressible?(last.codepoint)
+
+          last.width /= 2.0
+          line.width = line.glyphs.sum(&:width)
+        end
+        lines
+      end
+
+      def compressible?(codepoint)
+        TRAILING_COMPRESSION_CODEPOINTS.include?(codepoint)
+      end
+
       CJK_RANGES = [
         0x3000..0x303F, # CJK Symbols and Punctuation
         0x3040..0x309F, # Hiragana

data/lib/idml/text_engine/line_breaker.rb

@@ -14,7 +14,8 @@ module Idml
         lines = new(frame_width).break(glyphs)
         return lines unless cjk_run?(glyphs)
 
-        CjkLayout.apply_kinsoku(lines)
+        lines = CjkLayout.apply_kinsoku(lines)
+        CjkLayout.apply_line_end_compression(lines)
       end
 
       def self.cjk_run?(glyphs)

data/lib/idml/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: idml
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.10.2
 platform: ruby
 authors:
 - Ribose
@@ -189,6 +189,9 @@ files:
 - TODO.pdf/128-first-baseline-offset.md
 - TODO.pdf/129-justification-glyph-scaling.md
 - TODO.pdf/13-cjk-text-layout.md
+- TODO.pdf/130-contour-text-wrap.md
+- TODO.pdf/131-inverse-wrap.md
+- TODO.pdf/132-line-end-compression.md
 - TODO.pdf/14-page-item-element-models.md
 - TODO.pdf/15-wire-spread-children.md
 - TODO.pdf/16-typed-model-pipeline.md
@@ -497,6 +500,7 @@ files:
 - lib/idml/render/style_lookup.rb
 - lib/idml/render/style_resolver.rb
 - lib/idml/render/text_wrap_resolver.rb
+- lib/idml/render/wrap_contour.rb
 - lib/idml/text_engine.rb
 - lib/idml/text_engine/cjk_layout.rb
 - lib/idml/text_engine/justifier.rb