idml 0.9.4 → 0.9.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 41d28cdae1d32efe5815542e9f5f702affff8445c1c77b9e62e3c9229f974dca
-  data.tar.gz: d9144aafa235ef8364cd373bc7f62742bc95ed1b6646f159f00e67f72a1706e2
+  metadata.gz: 76ef12540a7d7d1805189664f88fc0c5b400b8d1240fbc495239ddb35f64822c
+  data.tar.gz: 941893920b3e23a32c196de4286a64f10edb0e377bb716a5287ba110bc3052bd
 SHA512:
-  metadata.gz: ca86d99a34bfb4cb1ab62580c3283dda29b21a060435f4dacce15e1069a49bf3009701d34c77700f5308b4c1fcd4e5d11788c89f6802398cb05a872516cae803
-  data.tar.gz: 6b7033ff88e4e5ea4edc4fbdfe7ebdb0024fbcc024107a7f5e5c18e3c7196b6323dcc66ec55485dbc743351c6d15f7bfd3eff922531d2d1ce6d713c9efa99dc7
+  metadata.gz: 95da409c1987bac0a36ab73793c02e349d3060f313f3f4fc2670f22efffd89bd2d5f0bcfba4096dab595cf39a7843134ee0fc4f06f9e4136d477c65f44870586
+  data.tar.gz: a74c7d9a0a1ccd22e57308890a0f6b257e9ec2d3aab7d3d8a407c23b4b52f466cd2c39f86be48d4b89e912e26fcd3a582dbdf27455d8db49a405219ede022357

data/TODO.pdf/117-endnote-support.md

@@ -1,7 +1,7 @@
 # TODO PDF 117: Endnote support
 
-## Status: OPEN (modeling COMPLETE 2026-08-18; rendering OPEN pending
-a real fixture)
+## Status: PARTIAL (modeling + reference markers COMPLETE
+2026-08-18/19; endnote TEXT rendering OPEN pending a real fixture)
 
 ## Problem
 
@@ -20,14 +20,19 @@ story flagged `IsEndnoteStory="true"`. Documents with endnotes
   collections). Round-trip + parse specs.
 - `StoryInner#is_endnote_story` already parsed, so endnote stories
   are identifiable.
+- Reference markers render (2026-08-19): CSR-level `EndnoteRange`
+  elements (verified against CharacterStyleRange_Object in
+  Story.rnc) emit superscript marker runs numbered by a counter
+  SEPARATE from footnotes — endnoted text now shows visible numbered
+  references instead of dropping them. `StoryInner` also parses
+  `StoryPreference` (vertical writing support).
 
 ## Design for rendering (needs a real InDesign fixture to validate)
 
-1. Marker: story-level `Endnote`/`EndnoteRange` pairs delimit the
-   anchor range; marker position requires story text-offset
-   bookkeeping the extraction layer doesn't currently track (unlike
-   footnotes, which sit inside a CSR). A range-aware extraction is
-   the prerequisite.
+1. ~~Marker~~ DONE 2026-08-19: CSR-level EndnoteRange emits a
+   superscript marker run at the CSR's position (same pattern as
+   footnotes). Story-level Endnote/EndnoteRange pairs (no CSR
+   anchor) remain unplaced.
 2. Endnote text: resolve `EndnoteTextRange` → the endnote story
    (IsEndnoteStory) → its paragraphs.
 3. Placement: per EndnoteOption Scope — end of story / end of

data/TODO.pdf/122-vertical-latin-ruby.md

@@ -0,0 +1,29 @@
+# TODO PDF 122: Vertical mode completion — Latin rotation, vertical ruby
+
+## Status: COMPLETE — implemented 2026-08-20
+
+## Problem
+
+The vertical writing path (TODO 13, 2026-08-19) stacked every glyph
+upright: Latin letters and digits rendered sideways-wrong (rotated
+in appearance relative to convention), and ruby annotations were
+not emitted at all in vertical mode.
+
+## What was done
+
+- Latin rotation: non-CJK glyphs in vertical text render rotated
+  90° clockwise (the vertical-writing convention for Latin runs),
+  via a graphics-state transform (q → translate → rotate −90° →
+  text at origin → Q). CJK glyphs stay upright.
+- Vertical ruby: runs carrying RubyString emit the annotation
+  stacked vertically alongside the base glyphs — to the right of
+  the column by default, to the left for RubyPosition values
+  containing "Below" (mirroring the horizontal above/below
+  convention under rotation). RubyFontSize defaults to half the
+  base size.
+
+## Known limitations
+
+- Tate-chu-yoko (horizontal digit groups inside vertical text) and
+  mojikumi spacing classes remain documented stretch goals
+  (TODO 13).

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

@@ -1,11 +1,29 @@
 # TODO PDF 13: CJK text layout
 
-## Status: PARTIAL — horizontal-mode CJK complete (2026-08-17):
-CJK glyph measurement, kinsoku shori, and ruby annotations render.
-Vertical writing mode, tate-chu-yoko, and mojikumi remain OPEN
-stretch goals — they need a vertical (rotated) layout engine and
-real vertical-mode fixtures to build against. See
-`lib/idml/text_engine/cjk_layout.rb`.
+## Status: PARTIAL — vertical writing mode implemented 2026-08-19
+(horizontal-mode CJK was complete 2026-08-17: glyph measurement,
+kinsoku shori, ruby annotations).
+
+## Vertical mode (2026-08-19)
+
+- `StoryInner` now parses `StoryPreference` (StoryOrientation).
+- `TextEngine::VerticalTextLayout` stacks glyphs UPRIGHT in
+  columns flowing right-to-left (CJK ideographs render correctly;
+  Latin glyphs are not rotated — documented approximation), reusing
+  LineBreaker (so kinsoku applies) against the column height.
+- `TextFrameRenderer` takes the vertical path when the story
+  declares Vertical: paragraphs flow as glyph columns, runs start
+  fresh columns, overflow chains to the next frame. Paragraph
+  spacing/rules/decorations and ruby repositioning are not applied
+  in vertical mode.
+- LineBreaker now breaks unspaced CJK runs PER CHARACTER at the
+  frame width (previously they overflowed as one long line) — this
+  also fixes horizontal CJK wrapping.
+
+Remaining stretch goals: tate-chu-yoko, mojikumi, Latin rotation in
+vertical mode, vertical ruby placement. See
+`lib/idml/text_engine/cjk_layout.rb` and
+`lib/idml/text_engine/vertical_text_layout.rb`.
 
 ## Progress 2026-08-17
 

data/lib/idml/elements/character_style_range.rb

@@ -302,6 +302,8 @@ module Idml
       attribute :table, Idml::Elements::Table, collection: true
       attribute :xml_element, Idml::Elements::XmlElement, collection: true
       attribute :footnote, Idml::Elements::Footnote, collection: true
+      attribute :endnote_range, Idml::Elements::EndnoteRange,
+                collection: true
       # Anchored page items embedded in the story flow. Their
       # AnchoredObjectSetting (child of each item) declares how the
       # item anchors to the surrounding text.
@@ -669,6 +671,7 @@ module Idml
         map_element "Table", to: :table
         map_element "XMLElement", to: :xml_element
         map_element "Footnote", to: :footnote
+        map_element "EndnoteRange", to: :endnote_range
         map_element "Rectangle", to: :rectangle
         map_element "Oval", to: :oval
         map_element "Polygon", to: :polygon

data/lib/idml/elements/story_inner.rb

@@ -316,6 +316,7 @@ module Idml
       attribute :endnote, Idml::Elements::Endnote, collection: true
       attribute :endnote_range, Idml::Elements::EndnoteRange,
                 collection: true
+      attribute :story_preference, Idml::Elements::StoryPreference
 
       xml do
         root "Story"
@@ -683,6 +684,7 @@ module Idml
         map_element "Footnote", to: :footnote
         map_element "Endnote", to: :endnote
         map_element "EndnoteRange", to: :endnote_range
+        map_element "StoryPreference", to: :story_preference
       end
 
       def text_content

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

@@ -41,7 +41,8 @@ module Idml
           state = initial_chain_state(frame, story, context)
           return unless state
 
-          render_text(canvas, state, context, box)
+          vertical = vertical_story?(story)
+          render_text(canvas, state, context, box, vertical: vertical)
           store_chain_state(frame, state, context)
         end
 
@@ -146,9 +147,11 @@ module Idml
         end
         private_class_method :context_for_item
 
-        def self.render_text(canvas, state, context, box)
+        def self.render_text(canvas, state, context, box, vertical: false)
           font = context.font_metrics
-          if font
+          if font && vertical
+            vertical_render(canvas, state, context, box, font)
+          elsif font
             engine_render(canvas, state, context, box, font)
           else
             simple_render(canvas, state, context, box)
@@ -156,6 +159,169 @@ module Idml
         end
         private_class_method :render_text
 
+        # True when the story's StoryPreference declares vertical
+        # writing (StoryOrientation="Vertical").
+        def self.vertical_story?(story)
+          story.inner&.story_preference&.story_orientation == "Vertical"
+        end
+        private_class_method :vertical_story?
+
+        # Vertical writing path (StoryOrientation="Vertical", CJK):
+        # paragraphs flow as upright glyph columns advancing
+        # right-to-left; each run starts a fresh column (run-mixing
+        # within a column is not modeled). Runs whose columns would
+        # cross the frame's left inset overflow to the next frame in
+        # the chain. Paragraph spacing, rules, and decorations are
+        # not applied in vertical mode.
+        def self.vertical_render(canvas, state, context, box, font)
+          layout_frame = layout_frame(context.item, box)
+          left_limit = layout_frame.x + (layout_frame.inset_left || 0)
+          resume_vertical_paragraph(state)
+          pending = 0
+
+          state.paragraphs.each do |paragraph|
+            remaining_runs = vertical_paragraph(
+              canvas, paragraph, context, layout_frame, font, left_limit
+            )
+            if remaining_runs.empty?
+              pending += 1
+            else
+              state.current_paragraph = paragraph
+              state.runs_remaining = remaining_runs
+              break
+            end
+          end
+
+          state.paragraphs = state.paragraphs[pending..]
+        end
+        private_class_method :vertical_render
+
+        # Folds a chain-resumed paragraph (runs_remaining) back to
+        # the head of the paragraph list so the vertical path sees a
+        # uniform sequence.
+        def self.resume_vertical_paragraph(state)
+          return unless state.current_paragraph
+
+          state.current_paragraph.runs = state.runs_remaining
+          state.paragraphs.unshift(state.current_paragraph)
+          state.current_paragraph = nil
+          state.runs_remaining = []
+        end
+        private_class_method :resume_vertical_paragraph
+
+        # Renders one paragraph's runs as vertical columns. Returns
+        # the runs that did not fit (empty when all placed).
+        def self.vertical_paragraph(canvas, paragraph, context,
+                                    layout_frame, font, left_limit)
+          paragraph.runs.each_with_index do |run, index|
+            size = run.point_size || DEFAULT_SIZE
+            leading = TextEngine::VerticalLayout.leading_for(
+              paragraph.auto_leading, size
+            )
+            glyphs = TextEngine::Shaper.shape(text: run.text, font: font,
+                                              size: size)
+            positioned, columns = TextEngine::VerticalTextLayout.layout(
+              glyphs: glyphs, frame: layout_frame, leading: leading,
+              size: size
+            )
+            unless vertical_fits?(layout_frame, leading, columns,
+                                  left_limit)
+              return paragraph.runs[index..]
+            end
+
+            positioned.each do |glyph|
+              emit_vertical_glyph(canvas, glyph, run, context, size)
+            end
+            emit_vertical_ruby(canvas, run, positioned, layout_frame,
+                               size, context)
+          end
+          []
+        end
+        private_class_method :vertical_paragraph
+
+        def self.vertical_fits?(layout_frame, leading, columns, left_limit)
+          right = layout_frame.x + layout_frame.width -
+            (layout_frame.inset_right || 0)
+          (right - (columns * leading)) >= left_limit
+        end
+        private_class_method :vertical_fits?
+
+        # Emits one upright glyph at its vertical position with the
+        # run's character styling.
+        # Emits one glyph in vertical mode: CJK upright; Latin
+        # (non-CJK) rotated 90° clockwise per the vertical-writing
+        # convention, via a graphics-state transform.
+        def self.emit_vertical_glyph(canvas, positioned, run, context,
+                                     size)
+          text = [positioned.codepoint].pack("U")
+          if TextEngine::CjkLayout.cjk?(positioned.codepoint)
+            text_kwargs = CharacterStyle.text_kwargs(
+              run,
+              {
+                at: [positioned.x, positioned.y],
+                font: font_for_run(run, context),
+                size: size,
+              },
+            )
+            canvas.text(text, **text_kwargs)
+          else
+            canvas.save_graphics_state do
+              # 90° clockwise: exact matrix (rotate would emit
+              # cos/sin float noise like 6.1e-17).
+              canvas.concat(0, -1, 1, 0, positioned.x, positioned.y)
+              text_kwargs = CharacterStyle.text_kwargs(
+                run,
+                {
+                  at: [0, 0],
+                  font: font_for_run(run, context),
+                  size: size,
+                },
+              )
+              canvas.text(text, **text_kwargs)
+            end
+          end
+        end
+        private_class_method :emit_vertical_glyph
+
+        # Emits the run's ruby alongside its vertical glyphs:
+        # stacked top-to-bottom beside the column — right side by
+        # default, left for Below* RubyPosition values (the
+        # horizontal above/below convention mirrored under
+        # rotation).
+        def self.emit_vertical_ruby(canvas, run, positioned, frame,
+                                    base_size, context)
+          ruby_text = run.ruby_string
+          return if ruby_text.nil? || ruby_text.empty?
+
+          ruby_size = run.ruby_font_size ||
+            (base_size * RUBY_SIZE_FACTOR)
+          x = ruby_vertical_x(positioned.first, run, base_size)
+          y = frame.y + frame.height - (frame.inset_top || 0)
+          ruby_text.each_codepoint do |codepoint|
+            text_kwargs = CharacterStyle.text_kwargs(
+              run,
+              {
+                at: [x, y - ruby_size],
+                font: font_for_run(run, context),
+                size: ruby_size,
+              },
+            )
+            canvas.text([codepoint].pack("U"), **text_kwargs)
+            y -= ruby_size
+          end
+        end
+        private_class_method :emit_vertical_ruby
+
+        def self.ruby_vertical_x(positioned, run, base_size)
+          offset = base_size * 0.9
+          if run.ruby_position.to_s.include?("Below")
+            positioned.x - offset
+          else
+            positioned.x + offset
+          end
+        end
+        private_class_method :ruby_vertical_x
+
         def self.chain_head?(frame)
           frame.previous_text_frame.nil? || frame.previous_text_frame == "n"
         end

data/lib/idml/render/style_resolver.rb

@@ -140,8 +140,9 @@ module Idml
         return [] unless story&.inner
 
         counter = Footnote.counter_for(nil)
+        endnotes = Footnote.counter_for(nil)
         story.inner.paragraph_style_range.flat_map do |psr|
-          csr_runs(psr, footnote_counter: counter)
+          csr_runs(psr, footnote_counter: counter, endnote_counter: endnotes)
         end
       end
 
@@ -170,13 +171,15 @@ module Idml
                                             style_lookup: nil,
                                             footnote_option: nil)
         counter = Footnote.counter_for(footnote_option)
+        endnotes = Footnote.counter_for(nil)
         container.paragraph_style_range.filter_map do |psr|
           next unless condition_visible?(psr, condition_filter)
 
           runs = csr_runs(psr, condition_filter: condition_filter,
                                style_lookup: style_lookup,
                                footnote_counter: counter,
-                               footnote_option: footnote_option)
+                               footnote_option: footnote_option,
+                               endnote_counter: endnotes)
           next if runs.empty?
 
           paragraph = Paragraph.new(
@@ -304,15 +307,18 @@ module Idml
       private_class_method :properties_color
 
       def self.csr_runs(psr, condition_filter: nil, style_lookup: nil,
-                        footnote_counter: nil, footnote_option: nil)
+                        footnote_counter: nil, footnote_option: nil,
+                        endnote_counter: nil)
         counter = footnote_counter || Footnote.counter_for(footnote_option)
+        endnotes = endnote_counter || Footnote.counter_for(nil)
         psr.character_style_range.flat_map do |csr|
           next [] unless condition_visible?(csr, condition_filter)
 
           csr_content_runs(csr, condition_filter: condition_filter,
                                 style_lookup: style_lookup,
                                 footnote_counter: counter,
-                                footnote_option: footnote_option)
+                                footnote_option: footnote_option,
+                                endnote_counter: endnotes)
         end
       end
 
@@ -320,7 +326,8 @@ module Idml
       # plus one superscript marker run per anchored Footnote. A CSR
       # holding only a footnote still emits its marker.
       def self.csr_content_runs(csr, condition_filter:, style_lookup:,
-                                footnote_counter:, footnote_option:)
+                                footnote_counter:, footnote_option:,
+                                endnote_counter:)
         text = csr.text_content
         runs = []
         unless text.nil? || text.empty?
@@ -336,8 +343,21 @@ module Idml
           runs << Footnote.marker_run(number, runs.last, paragraphs,
                                       footnote_option)
         end
+        runs.concat(endnote_marker_runs(csr, endnote_counter, runs.last))
         runs
       end
+
+      # Endnote reference markers (CSR > EndnoteRange): superscript,
+      # numbered by a counter SEPARATE from footnotes. The endnote
+      # text lives in another story (IsEndnoteStory) and is not yet
+      # rendered — see TODO 117.
+      def self.endnote_marker_runs(csr, endnote_counter, base_run)
+        csr.endnote_range.map do |_range|
+          Footnote.marker_run(endnote_counter.next_number, base_run,
+                              nil, nil)
+        end
+      end
+      private_class_method :endnote_marker_runs
       private_class_method :csr_content_runs
 
       def self.text_run(csr, style_lookup:)

data/lib/idml/text_engine/line_breaker.rb

@@ -22,10 +22,22 @@ module Idml
       end
       private_class_method :cjk_run?
 
+      # CJK text wraps per character (no word boundaries): an
+      # overflow whose trailing glyph is CJK breaks before it
+      # instead of emitting an overlong line.
+
       def initialize(frame_width)
         @frame_width = frame_width
       end
 
+      # CJK text wraps per character (no word boundaries): an
+      # overflow whose trailing glyph is CJK breaks before it
+      # instead of emitting an overlong line.
+      def cjk_break?(current)
+        current.length > 1 && CjkLayout.cjk?(current.last.codepoint)
+      end
+      private :cjk_break?
+
       def break(glyphs)
         lines = []
         current = []
@@ -50,6 +62,10 @@ module Idml
             current = current[(last_space_idx + 1)..]
             current_width = current.sum(&:width)
             last_space_idx = -1
+          elsif cjk_break?(current)
+            lines << Line.new(current[0..-2], current_width - glyph.width, 0)
+            current = [glyph]
+            current_width = glyph.width
           else
             lines << Line.new(current, current_width, 0)
             current = []

data/lib/idml/text_engine/vertical_text_layout.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Idml
+  module TextEngine
+    # Vertical (top-to-bottom, right-to-left) glyph layout for CJK
+    # vertical writing (StoryOrientation="Vertical"). Glyphs stay
+    # UPRIGHT — CJK ideographs render correctly stacked; Latin
+    # glyphs are not rotated to the vertical axis (documented
+    # approximation). Line breaking (and therefore kinsoku shori)
+    # is reused from LineBreaker against the column height.
+    module VerticalTextLayout
+      # One glyph placed at its baseline in a vertical column.
+      PositionedGlyph = Struct.new(:codepoint, :x, :y, keyword_init: true)
+
+      # Stacks `glyphs` into columns of at most the frame's text
+      # height; column 0 is the rightmost. Returns
+      # [positioned_glyphs, column_count].
+      def self.layout(glyphs:, frame:, leading:, size:)
+        lines = TextEngine::LineBreaker.break(
+          glyphs: glyphs, frame_width: column_height(frame),
+        )
+        positioned = []
+        lines.each_with_index do |line, column_index|
+          stack_column(positioned, line.glyphs, frame, leading, size,
+                       column_index)
+        end
+        [positioned, lines.length]
+      end
+
+      # The frame's usable vertical extent for one column of text.
+      def self.column_height(frame)
+        frame.height - (frame.inset_top || 0) - (frame.inset_bottom || 0)
+      end
+
+      # Places one column's glyphs at a shared x, baselines walking
+      # down from the frame's text top by each glyph's advance.
+      def self.stack_column(positioned, glyphs, frame, leading, size,
+                            column_index)
+        top_y = frame.y + frame.height - (frame.inset_top || 0)
+        x = column_x(frame, leading, size, column_index)
+        y = top_y
+        glyphs.each do |glyph|
+          y -= advance(glyph)
+          positioned << PositionedGlyph.new(codepoint: glyph.codepoint,
+                                            x: x, y: y)
+        end
+      end
+      private_class_method :stack_column
+
+      # Vertical advance of one glyph — its measured width (the em
+      # for the common square-CJK case).
+      def self.advance(glyph)
+        glyph.width.positive? ? glyph.width : 0.0
+      end
+      private_class_method :advance
+
+      # The column's glyph left edge: columns advance right-to-left
+      # by `leading` from the right inset edge; each glyph (em =
+      # `size`) is centered in its column slot.
+      def self.column_x(frame, leading, size, column_index)
+        right = frame.x + frame.width - (frame.inset_right || 0)
+        slot_left = right - ((column_index + 1) * leading)
+        slot_left + ((leading - size) / 2.0)
+      end
+      private_class_method :column_x
+    end
+  end
+end

data/lib/idml/text_engine.rb

@@ -8,6 +8,8 @@ module Idml
     autoload :PdfrbFontMetrics, "#{__dir__}/text_engine/pdfrb_font_metrics"
     autoload :Shaper, "#{__dir__}/text_engine/shaper"
     autoload :Measurement, "#{__dir__}/text_engine/measurement"
+    autoload :VerticalTextLayout,
+             "#{__dir__}/text_engine/vertical_text_layout"
     autoload :ShapedGlyph,     "#{__dir__}/text_engine/shaper"
     autoload :LineBreaker,     "#{__dir__}/text_engine/line_breaker"
     autoload :Line,            "#{__dir__}/text_engine/line_breaker"

data/lib/idml/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: idml
 version: !ruby/object:Gem::Version
-  version: 0.9.4
+  version: 0.9.6
 platform: ruby
 authors:
 - Ribose
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-19 00:00:00.000000000 Z
+date: 2026-08-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bigdecimal
@@ -180,6 +180,7 @@ files:
 - TODO.pdf/12-idml-to-pdf-pipeline.md
 - TODO.pdf/120-start-paragraph-breaks.md
 - TODO.pdf/121-cell-edge-strokes.md
+- TODO.pdf/122-vertical-latin-ruby.md
 - TODO.pdf/13-cjk-text-layout.md
 - TODO.pdf/14-page-item-element-models.md
 - TODO.pdf/15-wire-spread-children.md
@@ -497,6 +498,7 @@ files:
 - lib/idml/text_engine/pdfrb_font_metrics.rb
 - lib/idml/text_engine/shaper.rb
 - lib/idml/text_engine/vertical_layout.rb
+- lib/idml/text_engine/vertical_text_layout.rb
 - lib/idml/validation.rb
 - lib/idml/validation/result.rb
 - lib/idml/validation/validator.rb