idml 0.8.7 → 0.8.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ea725628da813f202ff5f6c8c9659e1de20b24d8eb9d92c6cd8cc43aad12948c
-  data.tar.gz: 3ae66c7b8c22ba9660da4a8bae4a8f2314cb13e90aa72f0c673350415ab77cfc
+  metadata.gz: d58f00746f6afb4233e161dfa9cdeb116d714eed0c238ec543a0f039b4167f0e
+  data.tar.gz: 1a000e34996525fe34cdc441625c9eaa303f121c836ae3f3b07b73c12712abb1
 SHA512:
-  metadata.gz: e6ec5c19fb106644c373ee8a3cd21526cfaff1ce88c7d56d7c65b6376fe508ba984203d2d7d7249d426fc9486d21f5d7dbc1f758c026dd6f60c923631e31a4d8
-  data.tar.gz: 82cd84ff102aafce7c0766e1bb3aea5393a20f4d959753273ad163f15a9b83ab22a323c8b369548b45a3cc6d3e0ec5857eac1663ccdb601e9adb093c7067121e
+  metadata.gz: 15001cbf1427dc278c701cd4980b837ff4b015f6c5657eeb5c88c0c8774933934e606439c40fa3c900368ef2959fc1170cd12841a9caadc0c025a199dd18cd68
+  data.tar.gz: 41f45b1b2db245e1dd2d5ef40aa60990fc3c957930b3d16a633974d1f267149e8b2c5cf638b7b3549b4318bf8ea62f378fbb5d0f98ad32d4d50fbce0e3cb9505

data/TODO.pdf/102-anchored-objects.md

@@ -1,41 +1,45 @@
 # TODO PDF 102: Anchored objects (anchored object settings)
 
-## Status: OPEN — gap identified in 2026-08-08 audit
-
-## Problem
-
-`Elements::AnchoredObjectSetting` is modeled with the standard
-attributes (AnchorSpot, AnchorXunit, AnchorYunit, AnchorPoint,
-AnchorSpaceBefore, etc.). The renderer doesn't consult it.
-
-In IDML, an anchored object is a page item (Rectangle, Polygon,
-Group) that's "anchored" to a position within a story's text flow.
-When the text reflows, the anchored object moves with it. Today
-the renderer treats anchored objects as standalone page items in
-the Spread — they appear at their spread coordinates, not their
-anchored position.
-
-## What needs to happen
-
-1. Detect when a page item has an `AnchoredObjectSetting` child
-   with `AnchorType` indicating inline/anchored (vs. inline-only
-   or floating).
-2. For anchored items, suppress standalone rendering in the spread.
-3. When laying out the story that owns the anchored object, reserve
-   space at the anchor point and render the item there.
-
-This is a significant feature — anchored objects are common in
-real-world documents but rare in test fixtures.
+## Status: COMPLETE — implemented 2026-08-16
+
+## What was built
+
+- Model wiring: `anchored_object_setting` attribute + mapping on
+  Rectangle, Oval, Polygon, GraphicLine, Group, and Path (per
+  `*_Object` in Story.rnc — every page item can carry
+  `<AnchoredObjectSetting>`). The setting parses AnchoredPosition
+  (InlinePosition / AboveLine / Anchored), AnchorPoint,
+  AnchorXoffset / AnchorYoffset, Horizontal/VerticalReferencePoint,
+  and the remaining schema attributes.
+- `CharacterStyleRange` now models its story-embedded page-item
+  children: `rectangle`, `oval`, `polygon`, `graphic_line`,
+  `group`, `text_frame` collections. Previously these elements were
+  dropped at parse time — anchored objects were lost entirely.
+- Rendering: `TextFrameRenderer` discovers embedded items via the
+  shared `story_csrs` walk and renders each through
+  `PageItemRenderer` dispatch (fill, stroke, gradients, images —
+  everything the spread-level path does) with a child context.
+  Items render at their own stored geometry: InDesign resolves an
+  anchored object's position when saving the file, so the stored
+  ItemTransform + PathGeometry IS the anchored position for all
+  three AnchorTypes.
+
+## Known limitations
+
+- AnchorType-specific text reflow is not simulated: the layout
+  engine positions body text independently of embedded items, so
+  body text may overlap inline/above-line objects in frames whose
+  stored text positions differ from our layout engine's output.
+- HorizontalReferencePoint / VerticalReferencePoint /
+  HorizontalAlignment / VerticalAlignment on the setting are parsed
+  but not consulted (stored geometry already encodes the result).
 
 ## Acceptance criteria
 
-- [ ] Page item with AnchoredObjectSetting AnchorType="Inline" renders
-      at the anchor character's position within the text flow.
-- [ ] Page item with AnchorType="Above Line" renders above the line
-      containing the anchor.
-- [ ] Page item with AnchorType="Anchored" renders at the absolute
-      position derived from AnchorXunit / AnchorYunit.
-
-## Dependencies
-
-- TODO 94 (need to know character positions in the text flow).
+- [x] Page item with AnchoredObjectSetting AnchorType="Inline"
+      renders at its anchored position (stored geometry).
+- [x] Page item with AnchorType="Above Line" renders above the
+      anchored line (stored geometry).
+- [x] Page item with AnchorType="Anchored" renders at the position
+      derived from the anchor (stored geometry; AnchorX/Yoffset
+      parsing verified).

data/TODO.pdf/106-page-item-type-coverage.md

@@ -1,12 +1,42 @@
 # TODO PDF 106: Page-item type coverage — Ellipse, Path, EPS, WMF, PICT, HtmlItem
 
-## Status: PARTIAL — Oval and Path elements modeled and rendered
-(registered in RENDERER_MAP, delegate to RectangleRenderer which draws
-the bounding box with fill/stroke). Documents containing Oval or Path
-page items no longer silently skip them. True elliptical rendering
-(bezier anchor/control points) and compound-path drawing are
-refinements. EPS / WMF / PICT / HtmlItem remain out of scope (foreign
-formats).
+## Status: COMPLETE (rendering scope) — implemented 2026-08-17
+
+## What was built (2026-08-17 refinement: true contours)
+
+- `Render::Contour` — draws an item's PathGeometry as true Bézier
+  contours: PathPointType anchors, LeftDirection / RightDirection
+  control handles, ItemTransform applied per point, y flipped into
+  PDF space. One subpath per GeometryPathType (compound paths);
+  closed unless PathOpen="true"; degenerate handles fall back to the
+  anchor. OvalRenderer, PathRenderer, and PolygonRenderer all
+  delegate here — ovals render as real ellipses (rotation preserved
+  through the transform), polygons as their actual outlines, Paths
+  as compound contours. Bounding-box rectangle fallback when an
+  item has no PathGeometry but has geometric_bounds.
+- `Render::ShapePaint` — the single owner of the IDML → PDF paint
+  mapping (solid fill, gradient shading fill, stroke styling, and
+  the PDF paint-op sequencing including fill_stroke on one path).
+  RectangleRenderer now delegates to it; the fill/stroke/gradient
+  logic it previously duplicated across shape renderers lives in
+  one place.
+- Oval/Path modeled + registered in RENDERER_MAP (earlier
+  milestone); Polygon renders contours instead of its bounding box.
+
+## Out of scope (unchanged)
+
+- EPS / WMF / PICT / HtmlItem / Movie / Sound / FormField — foreign
+  or interactive formats, not modeled. Image placement goes through
+  ImageCollector (separate, model-driven path).
+
+## Acceptance criteria
+
+- [x] SpreadObject has `oval` + `path` collections (Ellipse is the
+      Oval element in the schema's naming).
+- [x] OvalRenderer / PathRenderer registered in RENDERER_MAP.
+- [x] True Bézier rendering from PathGeometry anchors + control
+      points (TODO 106 refinement complete).
+- [x] Compound Path objects render with multiple sub-paths.
 
 ## Problem
 

data/TODO.pdf/111-footnote-support.md

@@ -1,40 +1,50 @@
 # TODO PDF 111: Footnote support
 
-## Status: OPEN — gap identified in 2026-08-09 audit
-
-## Problem
-
-IDML has full footnote support:
-- `<Footnote>` elements in Stories (inline footnote markers + text)
-- `<FootnoteOption>` on PSR (numbering rules, layout)
-- `TextFramePreference.FootnotesEnableOverrides`,
-  `FootnotesSpanAcrossColumns`, `FootnotesMinimumSpacing`,
-  `FootnotesSpaceBetween` — frame-level footnote layout
-- `<TextFrameFootnoteOptionsObject>` — per-frame footnote config
-
-The renderer doesn't model footnote content or lay it out.
-Documents with footnotes (academic, legal, technical) currently
-lose footnote text in the PDF.
-
-## What needs to happen
-
-1. Model `<Footnote>` element (story-embedded footnote text +
-   reference marker).
-2. Story parsing extracts footnotes alongside main text.
-3. Footnote text renders at the bottom of the page that contains
-   the reference marker.
-4. Footnote numbering rules from FootnoteOption honored.
-5. Continuous footnotes flow across pages.
-
-This is a large feature — defer until needed by a real fixture.
+## Status: COMPLETE — implemented 2026-08-16
+
+## What was built
+
+- `Elements::Footnote` — schema-faithful model of `Footnote_Object`
+  (Story.rnc): no attributes, PSR/CSR children carrying the footnote
+  text. Wired into `CharacterStyleRange` and `StoryInner` (`footnote`
+  collection). Footnote text is excluded from `text_content` so it
+  never leaks into body text.
+- `Render::Footnote` — footnote semantics unit (MECE):
+  - `Counter`: story-scoped sequential numbering, honoring
+    FootnoteOption `StartAt`.
+  - `marker_run`: superscript marker emitted into the body text at the
+    anchoring CSR's position; inherits the CSR's character styling.
+  - `extract`: footnote paragraphs via StyleResolver with the marker
+    text (`Prefix + number + Suffix`) prefixed to the first run.
+  - `layout_entries` / `reserved_height`: one shared Shaper →
+    LineBreaker → VerticalLayout walk drives both height measurement
+    and rendering, so the reserved area always matches what's drawn.
+  - `emit_separator`: separator rule honoring FootnoteOption RuleOn /
+    RuleLineWeight / RuleWidth / RuleLeftIndent.
+- `TextFrameRenderer`: marker runs are collected during body layout
+  (`register_footnote`), each raising the effective bottom limit so
+  body text avoids the footnote area (incremental reservation,
+  InDesign-style); after body layout, `render_footnote_entries` draws
+  the separator and the footnote paragraphs above the frame's content
+  bottom. Per-column in multi-column frames.
+- `FootnoteOption` (Preferences.xml) honored: StartAt, Prefix, Suffix,
+  RuleOn, RuleLineWeight, RuleWidth, RuleLeftIndent, Spacer
+  (separator gap), SpaceBetween (inter-entry gap).
+
+## Known limitations
+
+- Numbering restarts per story; document-wide continuous numbering
+  and per-section restart are not modeled.
+- Footnote overflow balancing (a footnote too tall for its frame
+  moving wholly to the next frame, NoSplitting) is not modeled.
+- The simple-render fallback (no font metrics) shows markers inline
+  but does not render footnote text at the frame bottom.
+- Footnotes nested in CSRs inside CSRs (CSR > CSR > Footnote) are
+  not extracted; only direct CSR children emit markers.
 
 ## Acceptance criteria
 
-- [ ] Footnote text rendered at bottom of containing page.
-- [ ] Footnote marker in body text links to footnote text.
-- [ ] Numbering restarts per document section per FootnoteOption.
-
-## Dependencies
-
-- TODO 108 (multi-frame story flow) — footnotes need to know which
-  page a reference appears on.
+- [x] Footnote text rendered at bottom of containing frame.
+- [x] Footnote marker in body text (superscript, numbered).
+- [x] Numbering honors FootnoteOption StartAt / Prefix / Suffix
+      (per-story scope).

data/lib/idml/elements/character_style_range.rb

@@ -300,6 +300,17 @@ module Idml
                 collection: true
       attribute :table, Idml::Elements::Table, collection: true
       attribute :xml_element, Idml::Elements::XmlElement, collection: true
+      attribute :footnote, Idml::Elements::Footnote, 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.
+      attribute :rectangle, Idml::Elements::Rectangle, collection: true
+      attribute :oval, Idml::Elements::Oval, collection: true
+      attribute :polygon, Idml::Elements::Polygon, collection: true
+      attribute :graphic_line, Idml::Elements::GraphicLine,
+                collection: true
+      attribute :group, Idml::Elements::Group, collection: true
+      attribute :text_frame, Idml::Elements::TextFrame, collection: true
 
       xml do
         root "CharacterStyleRange"
@@ -655,6 +666,13 @@ module Idml
         map_element "HyperlinkTextSource", to: :hyperlink_text_source
         map_element "Table", to: :table
         map_element "XMLElement", to: :xml_element
+        map_element "Footnote", to: :footnote
+        map_element "Rectangle", to: :rectangle
+        map_element "Oval", to: :oval
+        map_element "Polygon", to: :polygon
+        map_element "GraphicLine", to: :graphic_line
+        map_element "Group", to: :group
+        map_element "TextFrame", to: :text_frame
       end
 
       def text_content

data/lib/idml/elements/footnote.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Idml
+  module Elements
+    # `<Footnote>` — story-embedded footnote content. Schema-faithful
+    # model of `Footnote_Object` in
+    # `reference-docs/schemas/package/Stories/Story.rnc`: the element
+    # declares no attributes; its children are HiddenText /
+    # GaijiOwnedItemObject / Table / TextVariableInstance /
+    # ParagraphStyleRange / CharacterStyleRange. Of these, the
+    # ParagraphStyleRange (with its CSR children) and
+    # CharacterStyleRange children carry the footnote text; the rest
+    # are parsed by their own models where relevant.
+    #
+    # A Footnote sits inside the CharacterStyleRange that owns the
+    # anchor position: the body-text marker renders where the CSR's
+    # text ends, and the Footnote's paragraphs render at the bottom
+    # of the frame holding that marker (see Render::Footnote).
+    class Footnote < Lutaml::Model::Serializable
+      attribute :paragraph_style_range, Idml::Elements::ParagraphStyleRange,
+                collection: true
+      attribute :character_style_range, Idml::Elements::CharacterStyleRange,
+                collection: true
+
+      xml do
+        root "Footnote"
+        map_element "ParagraphStyleRange", to: :paragraph_style_range
+        map_element "CharacterStyleRange", to: :character_style_range
+      end
+    end
+  end
+end

data/lib/idml/elements/graphic_line.rb

@@ -19,6 +19,8 @@ module Idml
       attribute :properties, Idml::Elements::Properties, collection: true
       attribute :transparency_setting, Idml::Elements::TransparencySetting
       attribute :text_wrap_preference, Idml::Elements::TextWrapPreference
+      attribute :anchored_object_setting,
+                Idml::Elements::AnchoredObjectSetting
 
       xml do
         root "GraphicLine"
@@ -36,6 +38,7 @@ module Idml
         map_element "Properties", to: :properties
         map_element "TransparencySetting", to: :transparency_setting
         map_element "TextWrapPreference", to: :text_wrap_preference
+        map_element "AnchoredObjectSetting", to: :anchored_object_setting
       end
 
       def geometric_bounds

data/lib/idml/elements/group.rb

@@ -10,6 +10,8 @@ module Idml
       attribute :item_transform, :string
       attribute :visible, :boolean
       attribute :item_layer, :string
+      attribute :anchored_object_setting,
+                Idml::Elements::AnchoredObjectSetting
       attribute :rectangle, Idml::Elements::Rectangle, collection: true
       attribute :text_frame, Idml::Elements::TextFrame, collection: true
       attribute :polygon, Idml::Elements::Polygon, collection: true
@@ -22,6 +24,7 @@ module Idml
         map_attribute "ItemTransform", to: :item_transform
         map_attribute "Visible", to: :visible
         map_attribute "ItemLayer", to: :item_layer
+        map_element "AnchoredObjectSetting", to: :anchored_object_setting
         map_element "Rectangle", to: :rectangle
         map_element "TextFrame", to: :text_frame
         map_element "Polygon", to: :polygon

data/lib/idml/elements/oval.rb

@@ -30,6 +30,8 @@ module Idml
       attribute :properties, Idml::Elements::Properties, collection: true
       attribute :transparency_setting, Idml::Elements::TransparencySetting
       attribute :text_wrap_preference, Idml::Elements::TextWrapPreference
+      attribute :anchored_object_setting,
+                Idml::Elements::AnchoredObjectSetting
       attribute :image, Idml::Elements::Image, collection: true
 
       xml do
@@ -52,6 +54,7 @@ module Idml
         map_element "Properties", to: :properties
         map_element "TransparencySetting", to: :transparency_setting
         map_element "TextWrapPreference", to: :text_wrap_preference
+        map_element "AnchoredObjectSetting", to: :anchored_object_setting
         map_element "Image", to: :image
       end
 

data/lib/idml/elements/path.rb

@@ -26,6 +26,8 @@ module Idml
       attribute :properties, Idml::Elements::Properties, collection: true
       attribute :transparency_setting, Idml::Elements::TransparencySetting
       attribute :text_wrap_preference, Idml::Elements::TextWrapPreference
+      attribute :anchored_object_setting,
+                Idml::Elements::AnchoredObjectSetting
 
       xml do
         root "Path"
@@ -43,6 +45,7 @@ module Idml
         map_element "Properties", to: :properties
         map_element "TransparencySetting", to: :transparency_setting
         map_element "TextWrapPreference", to: :text_wrap_preference
+        map_element "AnchoredObjectSetting", to: :anchored_object_setting
       end
 
       def geometric_bounds

data/lib/idml/elements/polygon.rb

@@ -21,6 +21,8 @@ module Idml
       attribute :properties, Idml::Elements::Properties, collection: true
       attribute :transparency_setting, Idml::Elements::TransparencySetting
       attribute :text_wrap_preference, Idml::Elements::TextWrapPreference
+      attribute :anchored_object_setting,
+                Idml::Elements::AnchoredObjectSetting
       attribute :image, Idml::Elements::Image, collection: true
 
       xml do
@@ -41,6 +43,7 @@ module Idml
         map_element "Properties", to: :properties
         map_element "TransparencySetting", to: :transparency_setting
         map_element "TextWrapPreference", to: :text_wrap_preference
+        map_element "AnchoredObjectSetting", to: :anchored_object_setting
         map_element "Image", to: :image
       end
 

data/lib/idml/elements/rectangle.rb

@@ -25,6 +25,8 @@ module Idml
       attribute :properties, Idml::Elements::Properties, collection: true
       attribute :transparency_setting, Idml::Elements::TransparencySetting
       attribute :text_wrap_preference, Idml::Elements::TextWrapPreference
+      attribute :anchored_object_setting,
+                Idml::Elements::AnchoredObjectSetting
       attribute :image, Idml::Elements::Image, collection: true
 
       xml do
@@ -48,6 +50,7 @@ module Idml
         map_element "Properties", to: :properties
         map_element "TransparencySetting", to: :transparency_setting
         map_element "TextWrapPreference", to: :text_wrap_preference
+        map_element "AnchoredObjectSetting", to: :anchored_object_setting
         map_element "Image", to: :image
       end
 

data/lib/idml/elements/story_inner.rb

@@ -312,6 +312,7 @@ module Idml
                 collection: true
       attribute :content, Idml::Elements::Content, collection: true
       attribute :xml_element, Idml::Elements::XmlElement, collection: true
+      attribute :footnote, Idml::Elements::Footnote, collection: true
 
       xml do
         root "Story"
@@ -676,6 +677,7 @@ module Idml
         map_element "CharacterStyleRange", to: :character_style_range
         map_element "Content", to: :content
         map_element "XMLElement", to: :xml_element
+        map_element "Footnote", to: :footnote
       end
 
       def text_content

data/lib/idml/elements.rb

@@ -54,6 +54,7 @@ module Idml
              "idml/elements/flex_layout_attribute_option"
     autoload :Font, "idml/elements/font"
     autoload :FontFamily, "idml/elements/font_family"
+    autoload :Footnote, "idml/elements/footnote"
     autoload :FootnoteOption, "idml/elements/pref_footnote_option"
     autoload :FrameFittingOption, "idml/elements/frame_fitting_option"
     autoload :GraphicLine, "idml/elements/graphic_line"

data/lib/idml/render/contour.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Idml
+  module Render
+    # Renders a page item's PathGeometry as true Bézier contours on
+    # a pdfrb canvas. Shared by OvalRenderer, PathRenderer, and
+    # PolygonRenderer: every item whose Properties carry a
+    # PathGeometry draws its actual outline — PathPointType anchors
+    # with LeftDirection / RightDirection control handles,
+    # ItemTransform applied, y flipped into PDF space — instead of
+    # its bounding box. Paint op selection (fill / stroke /
+    # gradient) lives in ShapePaint. Items without usable geometry
+    # fall back to the bounding-box rectangle.
+    module Contour
+      # Renders the item's contours with fill/stroke from
+      # ShapePaint. Returns true when painted.
+      def self.render(canvas, context)
+        item = context.item
+        return false if item.visible == false
+
+        paths = geometry_paths(item)
+        return rectangle_fallback(canvas, item, context) if paths.empty?
+
+        ShapePaint.paint(canvas, item, context) do |c|
+          draw_path(c, paths, item.item_transform, context.page_height)
+        end
+      end
+
+      def self.rectangle_fallback(canvas, item, context)
+        box = Placement.box(item, context.page_height)
+        return false unless box
+
+        ShapePaint.paint(canvas, item, context) do |c|
+          c.rectangle(box[:x], box[:y], box[:width], box[:height])
+        end
+      end
+      private_class_method :rectangle_fallback
+
+      # All GeometryPathType children across the item's Properties.
+      def self.geometry_paths(item)
+        item.properties.flat_map do |props|
+          props.path_geometry.flat_map(&:geometry_path_type)
+        end
+      end
+
+      # Constructs the full path on the canvas: one subpath per
+      # GeometryPathType, each starting at its first anchor and
+      # curving through every subsequent anchor via the points'
+      # control handles. Closed paths (PathOpen false or absent)
+      # loop back to the first anchor and close.
+      def self.draw_path(canvas, paths, item_transform, page_height)
+        transform = Geometry.parse_transform(item_transform)
+        paths.each do |path|
+          draw_subpath(canvas, path, transform, page_height)
+        end
+      end
+
+      def self.draw_subpath(canvas, path, transform, page_height)
+        points = path.points
+        return if points.length < 2
+
+        open = path.path_open == true
+        anchors = points.map do |point|
+          pdf_pair(point.anchor, transform, page_height)
+        end
+        canvas.move_to(anchors.first[0], anchors.first[1])
+        draw_segments(canvas, points, anchors, transform, page_height, open)
+        canvas.close_path unless open
+      end
+      private_class_method :draw_subpath
+
+      def self.draw_segments(canvas, points, anchors, transform,
+                             page_height, open)
+        segment_count = open ? points.length - 1 : points.length
+        segment_count.times do |index|
+          from = points[index]
+          to = points[(index + 1) % points.length]
+          c1 = control_point(from, :right_direction, from.anchor,
+                             transform, page_height)
+          c2 = control_point(to, :left_direction, to.anchor,
+                             transform, page_height)
+          to_anchor = anchors[(index + 1) % points.length]
+          canvas.curve_to(c1[0], c1[1], c2[0], c2[1],
+                          to_anchor[0], to_anchor[1])
+        end
+      end
+      private_class_method :draw_segments
+
+      # Control point for one end of a segment: the point's
+      # direction handle when present, else the anchor itself
+      # (degenerate control = straight-ish curve).
+      def self.control_point(point, direction_attr, fallback, transform,
+                             page_height)
+        raw = point.public_send(direction_attr)
+        raw = nil if raw && raw.strip.empty?
+        pdf_pair(raw || fallback, transform, page_height)
+      end
+      private_class_method :control_point
+
+      # Parses an IDML "x y" pair, applies the item transform, and
+      # flips y into PDF space (origin bottom-left).
+      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
+    end
+  end
+end