idml 0.1.0

data/TODO.complete/23-lutaml-only-no-rexml.md

@@ -0,0 +1,60 @@
+# TODO 23: Delete REXML; route all XML through lutaml-model
+
+## Goal
+
+The gem uses ONLY `lutaml-model` for XML. No REXML, no Nokogiri, no
+direct adapter access. Every query goes through typed
+`Lutaml::Model::Serializable` subclasses.
+
+## Acceptance criteria
+
+- [ ] `lib/idml/document.rb` no longer requires or references REXML.
+      `find_by_self` returns the part name where the Self was found
+      (string-based search — no XML parsing).
+      `story_text` and `each_story` use the typed `Story#text_content`
+      and `Story#self_id`.
+      `xml_structure` returns the typed `BackingStory` instance.
+      `tagged_elements` walks the typed XMLElement collection.
+- [ ] `lib/idml/composition/insert_idml.rb` no longer requires or
+      references REXML. `BackingStoryMerger` parses via the typed
+      `BackingStory` model, manipulates the typed tree, serializes back.
+- [ ] New typed models:
+      - `lib/idml/elements/content.rb` — `<Content>` (text).
+      - `lib/idml/elements/xml_element.rb` — recursive `<XMLElement>`
+        (Self, MarkupTag, XMLContent, child XMLElement, child Content).
+- [ ] `Story` and `BackingStory` declare `Content` and `XMLElement`
+      as typed children.
+- [ ] `Story#text_content` returns the concatenated Content text.
+- [ ] `Story#self_id` exposes the inner `<Story Self="...">` attribute
+      via typed mapping.
+- [ ] `idml.gemspec` and `Gemfile` drop the `rexml` direct dependency.
+- [ ] All existing specs continue to pass (with API adjustments for
+      `find_by_self` returning a String).
+
+## Files
+
+- `lib/idml/elements.rb` (autoloads)
+- `lib/idml/elements/content.rb`
+- `lib/idml/elements/xml_element.rb`
+- `lib/idml/parts/story.rb` — add typed children
+- `lib/idml/parts/backing_story.rb` — add typed children
+- `lib/idml/document.rb` — refactor off REXML
+- `lib/idml/composition/insert_idml.rb` — refactor off REXML
+- `idml.gemspec`, `Gemfile`
+- `spec/idml/document_spec.rb` — adjust find_by_self expectations
+
+## Design notes
+
+- The long-term goal remains: expand typed coverage so every element
+  is typed. This TODO types just what Document and InsertIdml need:
+  Content (text) and XMLElement (recursive tree).
+- `find_by_self` over elements we haven't typed returns nil. Document
+  this as a known limitation; the long-tail typing work (TODOs 04–07
+  expansion) shrinks the gap over time.
+- `BackingStoryMerger` becomes: parse dest + source into typed
+  `BackingStory`, append source's `xml_element` collection to dest's,
+  serialize via `BackingStory.to_xml`.
+
+## Dependencies
+
+- None (reversible refactor).

data/TODO.complete/24-anti-pattern-forbid-rexml.md

@@ -0,0 +1,29 @@
+# TODO 24: Anti-pattern hard-bans REXML
+
+## Goal
+
+Encode the "no REXML" rule in the anti-pattern spec. The check fires
+on any `require "rexml/..."` or `REXML::` reference in `lib/`.
+
+## Acceptance criteria
+
+- [ ] `spec/anti_patterns_spec.rb` extends the FORBIDDEN_REQUIRES list
+      to include `rexml`.
+- [ ] The "no Nokogiri" check is generalized to a "no forbidden XML
+      libraries" check that covers both `nokogiri` and `rexml`.
+- [ ] `rexml` removed from the external-require allowlist.
+
+## Files
+
+- `spec/anti_patterns_spec.rb`
+
+## Design notes
+
+- The forbidden check looks for `require "rexml/..."` (any sub-path)
+      and `REXML::` constant references.
+- Document the rule's rationale in the spec comment: lutaml-model is
+  the only XML authority; everything else must be typed.
+
+## Dependencies
+
+- TODO 23 (REXML removed so the spec passes).

data/TODO.complete/25-claude-md-lutaml-only.md

@@ -0,0 +1,29 @@
+# TODO 25: CLAUDE.md — "lutaml-model only" rule
+
+## Goal
+
+Broaden the "No Nokogiri" rule in CLAUDE.md to "lutaml-model only"
+(no Nokogiri, no REXML, no direct adapter access). Document the
+architectural intent.
+
+## Acceptance criteria
+
+- [ ] `CLAUDE.md` Conventions section replaces the "No Nokogiri" bullet
+      with a broader "lutaml-model only" rule covering Nokogiri, REXML,
+      and direct adapter access.
+- [ ] The rule references the anti-pattern enforcement (TODO 24).
+- [ ] The rule documents the alternative: define a typed model class
+      for any XML element you need to query.
+
+## Files
+
+- `CLAUDE.md`
+
+## Design notes
+
+- One bullet, one paragraph of rationale. The full reasoning lives in
+  `TODO.complete/23-lutaml-only-no-rexml.md`.
+
+## Dependencies
+
+- TODOs 23, 24 (rule enforced when documented).

data/TODO.complete/26-rnc-faithful-models.md

@@ -0,0 +1,66 @@
+# TODO 26: RNC-faithful typed models
+
+## Goal
+
+Every typed element class declares the full attribute set defined for
+that element in the RNG Compact schemas at
+`reference-docs/schemas/package/`. No more guessing from fixture
+content; the RNC is the single source of truth.
+
+## Why
+
+The user (rightly) called out that the current StoryInner /
+ParagraphStyleRange / CharacterStyleRange / Content / XmlElement
+classes model only the attributes I needed for the Document queries
+(Self, MarkupTag, text). The RNC declares dozens more per element —
+layout, styling, hyphenation, kerning, etc. Faithful modeling means
+users can manipulate every attribute the IDML spec exposes.
+
+## Acceptance criteria
+
+For each typed element class listed below, the attribute set must
+match the corresponding RNC definition exactly. A spec asserts the
+match.
+
+- [ ] `Idml::Elements::StoryInner` ← `Story_Object` in
+      `Stories/Story.rnc` (60+ attributes).
+- [ ] `Idml::Elements::ParagraphStyleRange` ←
+      `ParagraphStyleRange_Object` (large attribute set).
+- [ ] `Idml::Elements::CharacterStyleRange` ←
+      `CharacterStyleRange_Object`.
+- [ ] `Idml::Elements::Content` ← `Content_Object`.
+- [ ] `Idml::Elements::XmlElement` ← `XMLElement_Object`.
+- [ ] Each part class (`Spread`, `MasterSpread`, `Story`,
+      `BackingStory`, `Fonts`, `Graphic`, `Style`, `StyleMapping`,
+      `Preferences`, `Tags`, `Mapping`, `Designmap`) declares the full
+      attribute set from its root element's RNC definition.
+- [ ] Round-trip per part continues to pass on every fixture (the
+      attribute expansion shouldn't break parsing).
+
+## Files
+
+- `lib/idml/elements/*.rb`
+- `lib/idml/parts/*.rb`
+- `spec/idml/elements/*_spec.rb` (new) — attribute-set assertions
+  against the RNC.
+- `spec/idml/parts/*_spec.rb` (existing) — update attribute-set
+  expectations to match RNC.
+
+## Design notes
+
+- The RNC for each element lists `attribute Name { type }?` lines.
+  Translate each to `attribute :ruby_name, :lutaml_type` plus a
+  `map_attribute "Name", to: :ruby_name` in the xml block.
+- Ruby names: snake_case of the XML name (`HyphenateCapitalizedWords`
+  → `:hyphenate_capitalized_words`). For Ruby-reserved names (`Self`,
+  `Class`), append `_attr` (`Self` → `:self_attr`).
+- Don't edit the RNC. The schema is the source of truth; the Ruby
+  class mirrors it.
+- The current Document queries only need a few attributes per element,
+  but the classes should expose all of them. Future queries don't have
+  to expand the model; they just use the methods that are already
+  there.
+
+## Dependencies
+
+- TODO 23 (lutaml-model only).

data/TODO.complete/27-geometry-scale-rotate.md

@@ -0,0 +1,28 @@
+# TODO 27: Geometry scale + rotate
+
+## Goal
+
+Extend `Idml::Geometry` beyond translate to cover scale and rotate.
+Completes the coordinate-transform toolkit composition ops need.
+
+## Acceptance criteria
+
+- [ ] `Geometry.scale(point, by:)` returns a new Point scaled by a factor.
+- [ ] `Geometry.rotate(point, angle_degrees:, around:)` returns a new Point
+      rotated by `angle_degrees` around the `around` Point.
+- [ ] Specs cover identity (no-op), single-axis scale, 90°/180°/270°
+      rotations, and a non-trivial rotation around an arbitrary origin.
+
+## Files
+
+- `lib/idml/geometry.rb`
+- `spec/idml/geometry_spec.rb`
+
+## Design notes
+
+- IDML coordinate system: origin bottom-left of spread, y up.
+- Standard math; no XML involved.
+
+## Dependencies
+
+- None.

data/TODO.complete/28-designmap-migration.md

@@ -0,0 +1,33 @@
+# TODO 28: Designmap migration to DocumentObject
+
+## Goal
+
+Replace the hand-written attribute list on `Idml::Parts::Designmap`
+with a typed `DocumentObject` inner element — the same wrapper
+pattern used by `Story` (which wraps `StoryInner`).
+
+## Acceptance criteria
+
+- [ ] `Designmap` declares a single `inner` attribute of type
+      `Idml::Elements::DocumentObject`.
+- [ ] `Designmap.dom_version`, `Designmap.self_attr`, `Designmap.name`
+      continue to work via delegation.
+- [ ] All existing designmap specs pass unchanged.
+- [ ] Round-trip suite continues to pass on every fixture.
+
+## Files
+
+- `lib/idml/parts/designmap.rb`
+- `lib/idml/elements/document_object.rb` (regenerate if needed)
+- `spec/idml/parts/designmap_spec.rb` (existing — verify still passes)
+
+## Design notes
+
+- The current Designmap has 33 hand-written attributes that match
+  `Document_Object`'s direct attributes. Migrating them into the
+  typed `DocumentObject` element keeps the wrapper pattern consistent
+  with Story → StoryInner, Spread → SpreadObject, etc.
+
+## Dependencies
+
+- None.

data/TODO.complete/29-add-page-from-idml.md

@@ -0,0 +1,35 @@
+# TODO 29: AddPageFromIdml composition op
+
+## Goal
+
+Implement `Composition::AddPageFromIdml` — copy a page from a source
+package into a destination package. Follows the same pattern as
+`InsertIdml` (structural merge) and uses `Prefix` to avoid Self
+collisions.
+
+## Acceptance criteria
+
+- [ ] `AddPageFromIdml.new(dest_pkg).call(source:, page_number:, at:, only:)`
+      returns a new Package with the source's specified page appended.
+- [ ] Prefixes both packages to avoid Self collisions.
+- [ ] Adds the source page's spread to dest's spreads list (in designmap).
+- [ ] Adds the source page's stories to dest's package.
+- [ ] Spec: adding a page from a multi-page fixture to a single-page
+      fixture results in a package with one more page.
+
+## Files
+
+- `lib/idml/composition/add_page_from_idml.rb`
+- `spec/idml/composition/add_page_from_idml_spec.rb`
+
+## Design notes
+
+- Page-level extraction from a Spread requires identifying which
+  `<Page>` child of the spread corresponds to the requested page
+  number, plus the page items between this Page boundary and the next.
+- This is a simplified structural implementation — full geometric
+  reflow is deferred.
+
+## Dependencies
+
+- TODOs 11, 14 (Geometry for transforms if needed).

data/TODO.complete/30-import-xml.md

@@ -0,0 +1,37 @@
+# TODO 30: ImportXml composition op
+
+## Goal
+
+Implement `Composition::ImportXml` — replace text content in a
+package's stories based on an XML structure tree. Mirrors
+SimpleIDML's `IDMLPackage.import_xml`.
+
+## Acceptance criteria
+
+- [ ] `ImportXml.new(pkg).call(xml_string:, at:)` returns a new
+      Package with text content updated per the XML.
+- [ ] Honors SimpleIDML's flags:
+  `simpleidml-setcontent="false"`,
+  `simpleidml-ignorecontent="true"`,
+  `simpleidml-setcontent="delete"`,
+  `simpleidml-setcontent="clear"`,
+  `simpleidml-setcontent="remove-previous-br"`,
+  `simpleidml-forcecontent="true"`.
+- [ ] Spec: importing a known XML fragment into the fixture replaces
+      a specific story's text with the new content.
+
+## Files
+
+- `lib/idml/composition/import_xml.rb`
+- `spec/idml/composition/import_xml_spec.rb`
+
+## Design notes
+
+- Walks the source XML tree (lutaml-model), finds matching XMLElement
+  by Self in the package's stories, replaces Content text.
+- Image references via `href` attribute swap image links — defer if
+  complex.
+
+## Dependencies
+
+- TODO 12 (Document for navigation).

data/TODO.complete/31-export-xml.md

@@ -0,0 +1,32 @@
+# TODO 31: ExportXml composition op
+
+## Goal
+
+Implement `Composition::ExportXml` — produce a flat XML string
+representing the package's logical XML structure tree + text content.
+Mirrors SimpleIDML's `IDMLPackage.export_xml`.
+
+## Acceptance criteria
+
+- [ ] `ExportXml.new(pkg).call(at: nil)` returns a String of XML.
+- [ ] Output is rooted at the package's BackingStory structure.
+- [ ] Each XMLElement has its text content populated from its linked
+      Story.
+- [ ] Spec: exporting the fixture yields XML containing every tagged
+      element with its text.
+
+## Files
+
+- `lib/idml/composition/export_xml.rb`
+- `spec/idml/composition/export_xml_spec.rb`
+
+## Design notes
+
+- Walks BackingStory's XmlElement tree.
+- For each XMLElement with an XMLContent attribute, fetches the
+  linked Story and inlines its text.
+- Output is well-formed XML via lutaml-model serialization.
+
+## Dependencies
+
+- TODO 12 (Document for navigation).

data/TODO.complete/33-element-spec-coverage.md

@@ -0,0 +1,30 @@
+# TODO 33: Per-element spec coverage
+
+## Goal
+
+Add a parameterized spec that exercises every typed element class —
+guarantees the codegen output parses a minimal valid XML fragment.
+
+## Acceptance criteria
+
+- [ ] `spec/idml/elements_spec.rb` enumerates every class in
+      `Idml::Elements` (via `Idml::Elements.constants`).
+- [ ] For each class: instantiate via `<Foo Self="x"/>` (or similar
+      minimal valid XML for that element's root name).
+- [ ] Asserts the returned object's class.
+- [ ] For classes with a `Self` attribute on the root: asserts the
+      attribute round-trips.
+
+## Files
+
+- `spec/idml/elements_spec.rb`
+
+## Design notes
+
+- Catches codegen bugs that produce syntactically valid but
+  semantically broken Ruby (wrong root name, missing namespace).
+- Cheap to run; high coverage value.
+
+## Dependencies
+
+- TODOs 23-26 (the codegen output this spec verifies).

data/TODO.pdf/01-font-metrics.md

@@ -0,0 +1,43 @@
+# TODO PDF 01: Font metrics reader
+
+## Goal
+
+Read OpenType/TrueType font files and expose per-glyph advance widths
+and kerning pairs. This is the foundation of the text engine — without
+font metrics, we can't measure text or position glyphs.
+
+## Acceptance criteria
+
+- [ ] `Idml::TextEngine::FontMetrics.open(path)` loads a .ttf or .otf
+      file and parses the `head`, `hhea`, `hmtx`, `cmap`, and `kern`
+      (or `GPOS`) tables.
+- [ ] `#glyph_width(codepoint)` returns the advance width for a
+      Unicode codepoint, scaled to the font's `unitsPerEm`.
+- [ ] `#kerning_pair(left_cp, right_cp)` returns the kerning value
+      for a glyph pair (0 if none).
+- [ ] `#ascent`, `#descent`, `#line_gap`, `#units_per_em` expose
+      vertical metrics.
+- [ ] Uses `ttfunk` (Prawn's font reader) as the parsing backend —
+      battle-tested, pure Ruby, MIT license.
+- [ ] Spec: load a known font (e.g., DejaVuSans.ttf), verify glyph
+      widths for 'A', 'a', ' ', and verify ascent/descent.
+
+## Files
+
+- `lib/idml/text_engine.rb` — module + autoloads.
+- `lib/idml/text_engine/font_metrics.rb`
+- `spec/idml/text_engine/font_metrics_spec.rb`
+
+## Design notes
+
+- `ttfunk` parses the binary font format. We wrap it in a typed
+  `FontMetrics` class that exposes a clean API (no TTFunk types leak).
+- Cache glyph widths after first lookup (most documents reuse the
+  same glyphs heavily).
+- The IDML `Fonts.xml` lists font family + style names. We need a
+  resolver that maps `Name="Minion Pro"` + `FontStyleName="Regular"`
+  to a .ttf/.otf file on disk. This is TODO 02.
+
+## Dependencies
+
+- `ttfunk` gem (add to gemspec).

data/TODO.pdf/02-font-resolver.md

@@ -0,0 +1,42 @@
+# TODO PDF 02: Font resolver
+
+## Goal
+
+Map IDML font references (family + style) to .ttf/.otf file paths on
+disk. IDML's `Fonts.xml` lists every font used; the resolver finds
+the actual font program.
+
+## Acceptance criteria
+
+- [ ] `Idml::TextEngine::FontResolver.new(font_search_paths:)`
+      accepts a list of directories to search.
+- [ ] `#resolve(family_name:, style_name:)` returns a
+      `FontMetrics` instance (from TODO 01) or nil if not found.
+- [ ] Searches common locations: system font dirs, user font dirs,
+      InDesign Document fonts folder (inside the IDML package's
+      parent), and any user-configured paths.
+- [ ] Handles style aliases: "Regular" = "Normal" = "Book";
+      "Bold" = "Semibold" when no exact match.
+- [ ] Caches resolved fonts by (family, style) key.
+- [ ] Spec: resolve a system font (e.g., "Arial" / "Regular" on
+      macOS or "DejaVu Sans" / "Book" on Linux).
+
+## Files
+
+- `lib/idml/text_engine/font_resolver.rb`
+- `spec/idml/text_engine/font_resolver_spec.rb`
+
+## Design notes
+
+- Font resolution is inherently platform-dependent. macOS uses
+  `~/Library/Fonts/`, `/Library/Fonts/`, `/System/Library/Fonts/`.
+  Linux uses `/usr/share/fonts/`, `~/.local/share/fonts/`.
+  Windows uses `C:\Windows\Fonts\`.
+- The IDML package itself may carry a "Document fonts" folder
+  (via InDesign's Package feature). Check there first.
+- For tests, bundle a small open-source font (e.g., DejaVu Sans
+  subset or Source Sans Pro) under `spec/fixtures/fonts/`.
+
+## Dependencies
+
+- TODO 01 (FontMetrics).

data/TODO.pdf/03-text-shaper.md

@@ -0,0 +1,40 @@
+# TODO PDF 03: Text shaper
+
+## Goal
+
+Convert a text string + font + size into a sequence of positioned
+glyphs with widths and kerning applied. The shaper is the bridge
+between raw text and layout.
+
+## Acceptance criteria
+
+- [ ] `Idml::TextEngine::Shaper.shape(text:, font_metrics:, size:)`
+      returns an Array of `ShapedGlyph` structs (codepoint, advance
+      width at the given size, kerning adjustment vs previous glyph).
+- [ ] `ShapedGlyph` struct: `codepoint`, `glyph_id`, `width`
+      (scaled to point size), `x_offset`, `y_offset`.
+- [ ] Handles basic kerning via `font_metrics.kerning_pair`.
+- [ ] `ShapedLine.measure(glyphs)` returns total width.
+- [ ] Spec: shape "Hello" in a known font, verify total width
+      matches sum of glyph widths ± kerning.
+
+## Files
+
+- `lib/idml/text_engine/shaper.rb`
+- `lib/idml/text_engine/shaped_glyph.rb`
+- `spec/idml/text_engine/shaper_spec.rb`
+
+## Design notes
+
+- No OpenType feature substitution (GSUB) in the first version.
+  Ligatures (fi, fl, ff) and contextual alternates are deferred —
+  they require parsing the GSUB table, which is a significant
+  undertaking. The text engine renders individual codepoints;
+  ligatures appear as separate characters.
+- Tracking (letter spacing) is applied as a constant offset per
+  glyph. Word spacing is applied at space characters.
+- Ruby's String#each_codepoint handles Unicode correctly.
+
+## Dependencies
+
+- TODO 01 (FontMetrics).

data/TODO.pdf/04-line-breaker-justifier.md

@@ -0,0 +1,51 @@
+# TODO PDF 04: Line breaker + justifier
+
+## Goal
+
+Break shaped text into lines that fit within a frame width, then
+justify each line per its paragraph alignment.
+
+## Acceptance criteria
+
+- [ ] `Idml::TextEngine::LineBreaker.break(glyphs:, frame_width:)`
+      returns an Array of `Line` objects, each holding a sub-range
+      of glyphs and the line's natural width.
+- [ ] Greedy algorithm: accumulate words until exceeding frame
+      width, then break. Word boundary = space glyph.
+- [ ] Hyphenation: optional, via `hyphenate: true` kwarg. Uses
+      simple suffix rules in the first version (TeX patterns
+      deferred).
+- [ ] `Idml::TextEngine::Justifier.justify(line:, frame_width:,`
+      `alignment:)` adjusts glyph x-positions per alignment:
+      - `:left` — no adjustment.
+      - `:center` — center the line in the frame.
+      - `:right` — right-align.
+      - `:justified` — distribute extra space between words.
+- [ ] Justified mode distributes space per the paragraph's
+      MinimumWordSpacing / DesiredWordSpacing / MaximumWordSpacing
+      (already typed on ParagraphStyleRange).
+- [ ] Spec: break a 100-word paragraph at 300pt width, verify no
+      line exceeds 300pt. Verify center/right/justified produce
+      correct x-offsets.
+
+## Files
+
+- `lib/idml/text_engine/line_breaker.rb`
+- `lib/idml/text_engine/justifier.rb`
+- `lib/idml/text_engine/line.rb`
+- `spec/idml/text_engine/line_breaker_spec.rb`
+- `spec/idml/text_engine/justifier_spec.rb`
+
+## Design notes
+
+- Greedy breaking is not as good as Knuth-Plass (InDesign's
+  Paragraph Composer), but it handles 90% of cases correctly.
+  Bad breaks (orphan/widow lines, rivers) are visible but the text
+  is readable.
+- The Justifier distributes "slack" (frame_width - line_width)
+  across word spaces for justified text. Each space grows by
+  slack / number_of_spaces, clamped to min/max word spacing.
+
+## Dependencies
+
+- TODO 03 (Shaper).

data/TODO.pdf/05-vertical-layout.md

@@ -0,0 +1,42 @@
+# TODO PDF 05: Vertical layout
+
+## Goal
+
+Position lines vertically within a text frame: leading, paragraph
+spacing, drop caps, inset margins.
+
+## Acceptance criteria
+
+- [ ] `Idml::TextEngine::VerticalLayout.layout(lines:, frame:,`
+      `paragraph_attrs:)` returns positioned glyphs with final
+      (x, y) coordinates.
+- [ ] Leading: each line advances by `font_size * auto_leading`
+      (default 1.2) or the explicit Leading attribute.
+- [ ] Paragraph spacing: SpaceBefore added before the first line
+      of each paragraph; SpaceAfter after the last.
+- [ ] First-line indent: FirstLineIndent offset on the first line
+      of each paragraph.
+- [ ] Left/right indent: LeftIndent / RightIndent shrink the
+      effective frame width.
+- [ ] Frame insets: InsetSpacing (top, bottom, left, right) from
+      the TextFrame's TextFramePreference.
+- [ ] Spec: layout a 3-paragraph text block, verify Y positions
+      respect leading + spacing.
+
+## Files
+
+- `lib/idml/text_engine/vertical_layout.rb`
+- `spec/idml/text_engine/vertical_layout_spec.rb`
+
+## Design notes
+
+- IDML's coordinate system: origin bottom-left, y increases
+  upward. The vertical layout works top-down (first line at top
+  of frame) and emits y coordinates in IDML convention.
+- Drop caps (DropCapLines, DropCapCharacters) are a stretch goal
+  — they require enlarging the first N characters' font size and
+  wrapping text around them.
+
+## Dependencies
+
+- TODOs 03, 04 (Shaper, LineBreaker).

data/TODO.pdf/06-pdf-color-operators.md

@@ -0,0 +1,25 @@
+# TODO PDF 06: PDF color operators
+
+## Goal
+
+Map IDML color definitions (from Graphic.xml) to PDF color space
+operators for content streams.
+
+## Acceptance criteria
+
+- [ ] `Idml::Render::Color` converts IDML Color objects (RGB, CMYK,
+      LAB) to PDF operator strings.
+- [ ] RGB: `r g b rg` (fill), `r g b RG` (stroke). Values 0.0–1.0.
+- [ ] CMYK: `c m y k k` (fill), `c m y k K` (stroke).
+- [ ] Tint: scaled color value (IDML TintValue applies).
+- [ ] Named colors resolved from Graphic.xml's Color collection.
+- [ ] Spec: convert a known RGB color to operator string.
+
+## Files
+
+- `lib/idml/render/color.rb`
+- `spec/idml/render/color_spec.rb`
+
+## Dependencies
+
+- Typed Graphic/Color element classes (done).

data/TODO.pdf/07-pdf-path-operators.md

@@ -0,0 +1,29 @@
+# TODO PDF 07: PDF path operators
+
+## Goal
+
+Map IDML geometric page items (Rectangle, Polygon, GraphicLine, etc.)
+to PDF path construction and painting operators.
+
+## Acceptance criteria
+
+- [ ] `Idml::Render::Path` converts IDML ItemTransform + Path points
+      to PDF path operators.
+- [ ] Rectangle → `x y w h re`.
+- [ ] Polygon/Path → `x y m ... x y l ... h` (moveto, lineto, close).
+- [ ] Fill → `f` (nonzero winding).
+- [ ] Stroke → `S`.
+- [ ] Fill + Stroke → `B`.
+- [ ] ItemTransform (transformation matrix) → `a b c d e f cm`
+      (current transformation matrix).
+- [ ] Spec: render a known rectangle to operator string.
+
+## Files
+
+- `lib/idml/render/path.rb`
+- `spec/idml/render/path_spec.rb`
+
+## Dependencies
+
+- Typed Spread/SpreadObject element classes (done).
+- TODO 06 (Color for fill/stroke).