idml 0.1.0

data/TODO.pdf/08-pdf-text-operators.md

@@ -0,0 +1,29 @@
+# TODO PDF 08: PDF text operators
+
+## Goal
+
+Map positioned glyphs from the text engine to PDF text-showing
+operators in a content stream.
+
+## Acceptance criteria
+
+- [ ] `Idml::Render::Text` takes an Array of positioned glyphs and
+      produces PDF text operators.
+- [ ] `BT` (begin text), `ET` (end text).
+- [ ] `Tf` (set font: `/FontName size Tf`).
+- [ ] `Td` or `Tm` (set text position).
+- [ ] `Tj` (show text string).
+- [ ] `TJ` (show text array with per-glyph kerning adjustments).
+- [ ] Color operators from TODO 06 inside the BT/ET block.
+- [ ] Spec: render "Hello World" at (72, 720) in 12pt → verify
+      the operator sequence.
+
+## Files
+
+- `lib/idml/render/text.rb`
+- `spec/idml/render/text_spec.rb`
+
+## Dependencies
+
+- TODOs 01–05 (text engine).
+- TODO 06 (Color).

data/TODO.pdf/09-image-embedding.md

@@ -0,0 +1,34 @@
+# TODO PDF 09: Image embedding
+
+## Goal
+
+Resolve IDML image links and embed them as PDF XObject images.
+
+## Acceptance criteria
+
+- [ ] `Idml::Render::Image` resolves the `href` attribute on Image
+      page items to a file path.
+- [ ] Supports JPEG and PNG (the two most common IDML image formats).
+- [ ] Creates a PDF image XObject with the correct color space
+      (DeviceRGB for color, DeviceGray for grayscale).
+- [ ] Positions the image using the page item's GeometricBounds
+      and ItemTransform.
+- [ ] Spec: embed a known JPEG into a PDF page.
+
+## Files
+
+- `lib/idml/render/image.rb`
+- `spec/idml/render/image_spec.rb`
+
+## Design notes
+
+- IDML stores image links relative to the IDML file's location.
+  The Package doesn't contain the images themselves (unless it's
+  an InDesign Package, which is a different ZIP structure).
+- For now, accept the image path as-is. If the file doesn't exist,
+  skip the image (don't error).
+
+## Dependencies
+
+- pdfrb XObject support (or raw PDF stream writing).
+- Typed Spread/Image element classes (when added to SpreadObject).

data/TODO.pdf/10-spread-renderer.md

@@ -0,0 +1,33 @@
+# TODO PDF 10: Spread renderer
+
+## Goal
+
+Render an IDML Spread (all its page items) into a single PDF page's
+content stream.
+
+## Acceptance criteria
+
+- [ ] `Idml::Render::SpreadRenderer.new(spread:, font_resolver:,`
+      `color_index:)` renders every page item.
+- [ ] Page items rendered in z-order (back to front, as they appear
+      in the Spread XML).
+- [ ] Rectangle/Polygon → path operators (TODO 07).
+- [ ] TextFrame → text engine (TODOs 01–05) + text operators
+      (TODO 08).
+- [ ] Image → image XObject (TODO 09).
+- [ ] Groups rendered recursively.
+- [ ] Page boundaries (GeometricBounds) set the PDF page's
+      MediaBox.
+- [ ] Spec: render a one-page fixture, verify the output PDF opens
+      and shows the expected content.
+
+## Files
+
+- `lib/idml/render/spread_renderer.rb`
+- `lib/idml/render.rb` — module + autoloads.
+- `spec/idml/render/spread_renderer_spec.rb`
+
+## Dependencies
+
+- TODOs 06–09.
+- Typed Spread element classes (done).

data/TODO.pdf/11-font-embedding.md

@@ -0,0 +1,38 @@
+# TODO PDF 11: Font embedding
+
+## Goal
+
+Embed font subsets in the output PDF so the rendered text is
+portable (not dependent on the viewer having the font installed).
+
+## Acceptance criteria
+
+- [ ] Collect every unique font used across all rendered text.
+- [ ] Subset each font to only the glyphs actually used (reduces
+      file size dramatically).
+- [ ] Embed as PDF Font object (Type0 for OpenType, Type1 for
+      classic PostScript fonts).
+- [ ] Build the font resource dictionary on each PDF page.
+- [ ] Spec: render text, open the output PDF, verify the font is
+      embedded (check /FontFile2 or /FontFile3 entry).
+
+## Files
+
+- `lib/idml/render/font_embedder.rb`
+- `spec/idml/render/font_embedder_spec.rb`
+
+## Design notes
+
+- Font subsetting is non-trivial: parse the font's `glyf` table,
+  extract only referenced glyphs, rebuild the table with new
+  glyph indices. `ttfunk` has some support for this.
+- Alternative: embed the full font (larger but simpler). Start
+  with full embedding, add subsetting later.
+- PDF/UA and PDF/A require embedded fonts. Regular PDF doesn't
+  strictly require it but rendering quality degrades without.
+
+## Dependencies
+
+- TODO 01 (FontMetrics).
+- TODO 08 (text operators — need to know which fonts are used).
+- pdfrb font resource support.

data/TODO.pdf/12-idml-to-pdf-pipeline.md

@@ -0,0 +1,41 @@
+# TODO PDF 12: IDML → PDF pipeline
+
+## Goal
+
+Top-level pipeline: `Idml::Package` → `Pdfrb::Document` → PDF file.
+Ties together the text engine, render layer, and pdfrb.
+
+## Acceptance criteria
+
+- [ ] `Idml::Render.render(package:, to:, font_search_paths:)`
+      produces a PDF at the given path.
+- [ ] For each Spread in the package, creates a PDF Page.
+- [ ] Each Page rendered via SpreadRenderer (TODO 10).
+- [ ] Fonts resolved via FontResolver (TODO 02) and embedded
+      (TODO 11).
+- [ ] Colors resolved from Graphic.xml.
+- [ ] Images resolved from href links (TODO 09).
+- [ ] `Idml::CLI` gains a `render` subcommand:
+      `idml render path.idml -o output.pdf`.
+- [ ] Spec: render the sample-with-image fixture, verify the
+      output PDF has the expected number of pages and is valid.
+
+## Files
+
+- `lib/idml/render.rb` — top-level entry + autoloads.
+- `lib/idml/render/pipeline.rb`
+- `lib/idml/cli.rb` — add `render` subcommand.
+- `spec/idml/render/pipeline_spec.rb`
+
+## Design notes
+
+- The pipeline is the "director" — it doesn't do rendering itself;
+  it orchestrates FontResolver, SpreadRenderer, and pdfrb.
+- Output quality will NOT match InDesign's export. This is an
+  approximation: basic shapes, left/justified text, no OpenType
+  features, no advanced paragraph composition. Documented gap.
+
+## Dependencies
+
+- TODOs 01–11 (everything above).
+- pdfrb gem (Canvas/content stream support).

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

@@ -0,0 +1,40 @@
+# TODO PDF 13: CJK text layout
+
+## Goal
+
+Extend the text engine to handle CJK (Chinese, Japanese, Korean)
+text layout: vertical writing, Tate-Chu-Yoko, Ruby annotations,
+kinsoku shori (line-breaking rules), and CJK-specific punctuation
+handling.
+
+## Acceptance criteria
+
+- [ ] CJK font metrics (square glyphs — equal advance width and
+      height).
+- [ ] Vertical text mode (StoryOrientation = Vertical).
+- [ ] Kinsoku shori (禁止処理): no line start/end with forbidden
+      characters.
+- [ ] Tate-Chu-Yoko (縦中横): horizontal digits in vertical text.
+- [ ] Ruby (ルビ) annotation positioning.
+- [ ] Mojikumi (文字組) spacing classes.
+- [ ] Spec: layout a Japanese paragraph in vertical mode.
+
+## Files
+
+- `lib/idml/text_engine/cjk_layout.rb`
+- `spec/idml/text_engine/cjk_layout_spec.rb`
+
+## Design notes
+
+- CJK text layout is a significant expansion of the text engine.
+  It shares the Shaper and FontMetrics layers but needs its own
+  LineBreaker (kinsoku rules) and VerticalLayout (rotated glyphs).
+- IDML documents the StoryOrientation attribute on StoryPreference.
+  Horizontal = LeftToRightDirection, Vertical = TopToBottom.
+- This TODO is a stretch goal — most IDML → PDF use cases are
+  Latin-script. CJK users should use InDesign Server for
+  pixel-perfect output.
+
+## Dependencies
+
+- TODOs 01–05 (text engine foundation).

data/TODO.pdf/14-page-item-element-models.md

@@ -0,0 +1,61 @@
+# TODO PDF 14: Page-item element models
+
+## Goal
+
+Create typed `Lutaml::Model::Serializable` subclasses for every page-item
+element that appears inside a `<Spread>`. These are the geometric objects
+the renderer must iterate over: Page, Rectangle, TextFrame, Image, Link,
+Polygon, Group, GraphicLine, Ellipse.
+
+## Why
+
+The `SpreadObject` model currently only carries attributes — it has no
+typed references to its child page items. This forces the rendering
+pipeline to fall back to regex on raw XML, violating the project's
+"lutaml-model only" rule and making the pipeline fragile.
+
+## Acceptance criteria
+
+- [ ] `Idml::Elements::Page` — child of Spread; carries GeometricBounds,
+      ItemTransform, AppliedMaster.
+- [ ] `Idml::Elements::Rectangle` — FillColor, FillTint, StrokeColor,
+      StrokeWeight, ItemTransform, GeometricBounds (via Properties),
+      ContentType.
+- [ ] `Idml::Elements::TextFrame` — ParentStory, ItemTransform,
+      ContentType, GeometricBounds, TextFrameOffset.
+- [ ] `Idml::Elements::Image` — ItemTransform, Space, ActualPpi,
+      ImageTypeName.
+- [ ] `Idml::Elements::Link` — LinkResourceURI, LinkResourceFormat.
+- [ ] `Idml::Elements::Polygon` — ItemTransform, FillColor, PathPointArray.
+- [ ] `Idml::Elements::Group` — ItemTransform, child page items.
+- [ ] `Idml::Elements::GraphicLine` — ItemTransform, StrokeColor.
+- [ ] Each class has a round-trip spec: `from_xml` → `to_xml` is equivalent.
+- [ ] Each class is registered in `lib/idml/elements.rb` autoloads.
+
+## Files
+
+- `lib/idml/elements/page.rb`
+- `lib/idml/elements/rectangle.rb`
+- `lib/idml/elements/text_frame.rb`
+- `lib/idml/elements/image.rb`
+- `lib/idml/elements/link.rb`
+- `lib/idml/elements/polygon.rb`
+- `lib/idml/elements/group.rb`
+- `lib/idml/elements/graphic_line.rb`
+- `spec/idml/elements/page_item_spec.rb` (or per-class specs)
+
+## Design notes
+
+- Attribute lists come from `reference-docs/schemas/package/Spreads/Spread.rnc`
+  at the `*_Object` definitions (Rectangle_Object at line 3471, Page_Object
+  at line 4166, etc.). Only render-relevant attributes need to be declared
+  initially — the rest can be added incrementally.
+- The `Image` element contains a `Link` child — `Image` should have
+  `attribute :link, Idml::Elements::Link, collection: true`.
+- `Rectangle` and `TextFrame` can contain child `Image` elements (graphic
+  content placed inside a frame).
+- Reserved Ruby names: `Self` → `self_attr`, `class` → `class_attr`, etc.
+
+## Dependencies
+
+- TODO 14 is the foundation for TODOs 15–18.

data/TODO.pdf/15-wire-spread-children.md

@@ -0,0 +1,46 @@
+# TODO PDF 15: Wire SpreadObject child elements
+
+## Goal
+
+Extend `Idml::Elements::SpreadObject` to expose its child page items as
+typed collections, and `Idml::Parts::Spread` to provide convenient
+accessors for rendering.
+
+## Why
+
+The `SpreadObject` currently maps only attributes. The rendering pipeline
+needs to iterate over `page`, `rectangle`, `text_frame`, `image`, `polygon`
+collections to render each item. Without typed child references, the
+pipeline must parse raw XML.
+
+## Acceptance criteria
+
+- [ ] `SpreadObject` declares `attribute :page, Idml::Elements::Page,
+      collection: true` and similarly for rectangle, text_frame, image,
+      polygon, group, graphic_line.
+- [ ] The XML mapping uses `map_element "Page", to: :page` etc.
+- [ ] The mapping uses `ordered` to preserve child-element z-order
+      (semantically meaningful in IDML — determines visual stacking).
+- [ ] `Parts::Spread#each_page_item` yields each child element in document
+      order, regardless of type.
+- [ ] Round-trip: `Parts::Spread.from_xml(xml).to_xml` is equivalent to
+      the original XML (for the modeled subset).
+- [ ] Spec: load the sample fixture's Spread_ud1.xml and verify
+      `spread.spread.first.page.first.geometric_bounds` is populated.
+
+## Files
+
+- `lib/idml/elements/spread_object.rb` (modify)
+- `lib/idml/parts/spread.rb` (add `each_page_item`)
+- `spec/idml/parts/spread_spec.rb`
+
+## Design notes
+
+- `ordered` is critical: IDML z-order = child-element order. If the
+  mapping isn't ordered, lutaml-model may reorder children on round-trip.
+- The `Properties` child element (Label/KeyValuePair) is metadata, not
+  a page item — it should not appear in `each_page_item`.
+
+## Dependencies
+
+- TODO 14 (page-item element models).

data/TODO.pdf/16-typed-model-pipeline.md

@@ -0,0 +1,48 @@
+# TODO PDF 16: Typed-model rendering pipeline
+
+## Goal
+
+Replace the regex-based image extraction and hardcoded page dimensions
+in the rendering pipeline with typed-model iteration. The Pipeline should
+read typed `Parts::Spread` instances and iterate over `SpreadObject`'s
+child page items.
+
+## Why
+
+The current `Pipeline#collect_images` calls `Render::Image.extract_from_spread`
+with raw XML and regex. This violates the "lutaml-model only" rule and
+is fragile (regex can't handle nested elements, attribute ordering, or
+namespace prefixes robustly).
+
+## Acceptance criteria
+
+- [ ] `Pipeline#call` iterates over `package.spreads` (typed `Parts::Spread`).
+- [ ] Image extraction uses `spread.spread.first` (SpreadObject) →
+      iterate child elements → find `Image` → access `link.first.link_resource_uri`.
+- [ ] No raw XML reading in the Pipeline for modeled parts.
+- [ ] Page dimensions come from the `Page` element's `GeometricBounds`,
+      not a hardcoded constant.
+- [ ] `Render::Image.extract_from_spread` is removed or deprecated;
+      the typed path replaces it.
+- [ ] Spec: Pipeline produces the same PDF structure as before (images
+      embedded, valid PDF header/trailer).
+
+## Files
+
+- `lib/idml/render/pipeline.rb` (rewrite iteration)
+- `lib/idml/render/image.rb` (remove `extract_from_spread` or mark deprecated)
+- `lib/idml/render/spread_renderer.rb` (accept typed SpreadObject)
+- `spec/idml/render/pipeline_spec.rb`
+
+## Design notes
+
+- The `Page` element's `GeometricBounds` is `y1 x1 y2 x2` (top-left,
+  bottom-right in spread coordinates). Page width = x2 - x1,
+  height = y2 - y1.
+- The Page's `ItemTransform` translates page-local coords to spread coords.
+- For images inside Rectangles: iterate Rectangle → check ContentType ==
+  "GraphicType" → find child Image → get Link.
+
+## Dependencies
+
+- TODOs 14, 15 (element models + SpreadObject wiring).

data/TODO.pdf/17-shape-rendering.md

@@ -0,0 +1,46 @@
+# TODO PDF 17: Shape rendering
+
+## Goal
+
+Render IDML page-item shapes (Rectangle, Polygon, GraphicLine, Ellipse)
+as PDF path operators with fill and stroke colors.
+
+## Why
+
+Currently only images are rendered — page-item geometry (colored
+rectangles, borders, backgrounds) is invisible in the output PDF.
+
+## Acceptance criteria
+
+- [ ] `SpreadRenderer` iterates all page items and dispatches to
+      type-specific renderers.
+- [ ] Rectangle: emits `re` (rectangle) operator with fill (`f`) and/or
+      stroke (`S`) based on FillColor/StrokeColor presence.
+- [ ] Polygon: emits `m`/`l` path operators from PathPointArray.
+- [ ] GraphicLine: emits open path with stroke only.
+- [ ] Colors resolved from Resources/Graphic.xml (Color/Swatch names → RGB/CMYK).
+- [ ] ItemTransform applied via `cm` operator.
+- [ ] Spec: render a Rectangle with known fill color, verify PDF
+      contains the `rg` (fill RGB) and `re` operators.
+
+## Files
+
+- `lib/idml/render/shape_renderer.rb` (new)
+- `lib/idml/render/spread_renderer.rb` (dispatch to ShapeRenderer)
+- `lib/idml/render/color_resolver.rb` (new — resolves color names to values)
+- `spec/idml/render/shape_renderer_spec.rb`
+
+## Design notes
+
+- Renderer dispatch should use a registry (OCP): adding a new page-item
+  type = registering a renderer, not editing a switch statement.
+- Color resolution: IDML color names like "Color/Red" reference entries
+  in Resources/Graphic.xml. The resolver looks up the Color element by
+  Self attribute and returns RGB or CMYK values.
+- GeometricBounds for Rectangle: `y1 x1 y2 x2` → PDF rectangle at
+  `(x1, page_height - y2)` with width `x2 - x1`, height `y2 - y1`.
+
+## Dependencies
+
+- TODOs 14–16 (element models + typed pipeline).
+- TODO 22 (color resolution).

data/TODO.pdf/18-text-rendering.md

@@ -0,0 +1,48 @@
+# TODO PDF 18: Text rendering from stories
+
+## Goal
+
+Wire the text engine to actual IDML story content. Extract text from
+Stories, map them to TextFrame positions, and render via the text engine
+pipeline (Shaper → LineBreaker → Justifier → VerticalLayout).
+
+## Why
+
+The text engine exists (TODOs 01–05) but `SpreadRenderer#render_stories`
+returns "". No text appears in the output PDF.
+
+## Acceptance criteria
+
+- [ ] For each TextFrame on a spread, resolve `ParentStory` to a
+      `Parts::Story` via `package.story_by_id(story_id)`.
+- [ ] Extract text content from the Story's ParagraphStyleRange →
+      CharacterStyleRange → Content chain.
+- [ ] Pass styled text runs through the text engine (Shaper → LineBreaker
+      → Justifier → VerticalLayout).
+- [ ] Emit PDF text operators (BT/Tf/Td/Tj/ET) for positioned glyphs.
+- [ ] TextFrame inset margins (TextFrameOffset) respected by the layout.
+- [ ] Spec: render a TextFrame with known text, verify PDF contains
+      the text string in a Tj operator.
+
+## Files
+
+- `lib/idml/render/text_renderer.rb` (new)
+- `lib/idml/render/spread_renderer.rb` (dispatch to TextRenderer)
+- `lib/idml/package.rb` (add `story_by_id`)
+- `spec/idml/render/text_renderer_spec.rb`
+
+## Design notes
+
+- Story text extraction: `CharacterStyleRange#text_content` already
+  exists and recursively joins Content elements.
+- Font/size from CharacterStyleRange: `applied_font`, `point_size`,
+  `fill_color` attributes.
+- The TextFrame's ItemTransform + GeometricBounds gives the frame
+  rectangle; the text engine lays out within it (minus insets).
+- For now, handle single-style runs. Multi-style (mixed fonts/sizes in
+  one line) is a stretch goal.
+
+## Dependencies
+
+- TODOs 14–16 (element models + typed pipeline).
+- TODO 02 (FontResolver).

data/TODO.pdf/19-page-dimensions.md

@@ -0,0 +1,40 @@
+# TODO PDF 19: Page dimensions from IDML
+
+## Goal
+
+Derive PDF page width and height from the IDML document's Page element
+GeometricBounds, rather than using the hardcoded US Letter (612×792)
+constant.
+
+## Why
+
+IDML documents can be any size (A4, business card, poster, etc.).
+Hardcoding 612×792 produces incorrect layouts for non-Letter documents.
+
+## Acceptance criteria
+
+- [ ] `Parts::Spread#page_dimensions` returns `[{ width:, height: }]`
+      for each Page in the spread.
+- [ ] Dimensions derived from `Page#geometric_bounds` (y1 x1 y2 x2 format).
+- [ ] Pipeline passes per-page dimensions to `PdfWriter#add_page`.
+- [ ] Spec: load the sample fixture, verify page dimensions match
+      the fixture's actual page size (612×792 for US Letter).
+
+## Files
+
+- `lib/idml/parts/spread.rb` (add `page_dimensions`)
+- `lib/idml/render/pipeline.rb` (use per-page dimensions)
+- `spec/idml/parts/spread_spec.rb`
+
+## Design notes
+
+- `GeometricBounds="0 0 792 612"` means y1=0, x1=0, y2=792, x2=612.
+  Width = x2 - x1 = 612, Height = y2 - y1 = 792.
+- A spread can contain multiple pages (two-page spread). Each Page
+  element has its own GeometricBounds.
+- The PDF has one page per IDML spread (current behavior). Multi-page
+  spreads render as a single PDF page encompassing all spread pages.
+
+## Dependencies
+
+- TODOs 14–15 (Page element model + SpreadObject wiring).

data/TODO.pdf/20-png-image-support.md

@@ -0,0 +1,43 @@
+# TODO PDF 20: PNG image support
+
+## Goal
+
+Extend image embedding to support PNG files in addition to JPEG.
+PNG images are embedded as PDF XObjects with the FlateDecode filter.
+
+## Why
+
+IDML documents commonly reference PNG images (screenshots, graphics
+with transparency). Currently only JPEG is supported.
+
+## Acceptance criteria
+
+- [ ] `Render::Image.detect_format(data)` returns `:jpeg` or `:png`
+      based on magic bytes.
+- [ ] `Render::Image.png_dimensions(data)` reads IHDR chunk for
+      width/height.
+- [ ] `PdfWriter#add_png_image(data:, width:, height:, colorspace:)`
+      creates an XObject with `/Filter /FlateDecode`.
+- [ ] Pipeline detects format and calls the appropriate writer method.
+- [ ] Spec: embed a known PNG, verify `/Subtype /Image` and
+      `/Filter /FlateDecode` in output.
+
+## Files
+
+- `lib/idml/render/image.rb` (add PNG parsing)
+- `lib/idml/render/pdf_writer.rb` (add `add_png_image`)
+- `lib/idml/render/pipeline.rb` (format detection)
+- `spec/idml/render/image_spec.rb`
+
+## Design notes
+
+- PNG magic bytes: `\x89PNG\r\n\x1a\n` (8 bytes).
+- IHDR chunk: starts at byte offset 8, length=13, width (4 bytes BE),
+  height (4 bytes BE), bit depth, color type.
+- Color type mapping: 0 → DeviceGray, 2 → DeviceRGB, 3 → Indexed,
+  4 → DeviceGray (alpha), 6 → DeviceRGB (alpha).
+- PNG with alpha needs SMask (soft mask) XObject — stretch goal.
+
+## Dependencies
+
+- TODO 09 (image embedding foundation).

data/TODO.pdf/21-coordinate-transform.md

@@ -0,0 +1,41 @@
+# TODO PDF 21: Coordinate transform utility
+
+## Goal
+
+Centralize IDML-to-PDF coordinate system conversion in a dedicated
+`Idml::Geometry::CoordinateTransform` class. Currently the Y-flip logic
+is scattered across `Render::Image.compute_placement` and inline code.
+
+## Why
+
+IDML uses a top-left origin with Y growing downward. PDF uses a
+bottom-left origin with Y growing upward. This conversion is needed
+for every page item (images, shapes, text). Scattering it leads to
+inconsistency and bugs.
+
+## Acceptance criteria
+
+- [ ] `Idml::Geometry::CoordinateTransform` class.
+- [ ] `transform(point)` converts an IDML (x, y) to PDF (x, y).
+- [ ] `transform_bounds(bounds)` converts GeometricBounds to a PDF rectangle.
+- [ ] `combine_transforms(*matrices)` multiplies ItemTransform matrices.
+- [ ] All render modules use this class instead of inline math.
+- [ ] Spec: known transform values produce expected PDF coordinates.
+
+## Files
+
+- `lib/idml/geometry.rb` (add autoload)
+- `lib/idml/geometry/coordinate_transform.rb`
+- `lib/idml/render/image.rb` (refactor to use CoordinateTransform)
+- `spec/idml/geometry/coordinate_transform_spec.rb`
+
+## Design notes
+
+- The transform takes `page_height` as a parameter (for Y-flip).
+- ItemTransform matrices are `a b c d e f` — 2D affine. Matrix
+  multiplication combines parent + child transforms.
+- The Page element's ItemTransform translates page-local to spread coords.
+
+## Dependencies
+
+- None (can be done independently).

data/TODO.pdf/22-color-resolution.md

@@ -0,0 +1,41 @@
+# TODO PDF 22: Color resolution from Resources
+
+## Goal
+
+Resolve IDML color references (e.g., "Color/Red", "Color/c0m100y100k0")
+to concrete RGB or CMYK values using the Resources/Graphic.xml part.
+
+## Why
+
+Page items and text runs reference colors by name. To render fills,
+strokes, and text colors, we need to look up the color definition in
+Resources/Graphic.xml and extract its component values.
+
+## Acceptance criteria
+
+- [ ] `Idml::Render::ColorResolver` class.
+- [ ] Initialized with a `Parts::Graphic` (typed Resources/Graphic.xml).
+- [ ] `resolve(name)` returns `{ model: :rgb, r:, g:, b: }` or
+      `{ model: :cmyk, c:, m:, y:, k: }` or nil if not found.
+- [ ] Handles IDML color name format: `Color/<name>`, `Swatch/<name>`.
+- [ ] Space-separated RGB values (0–255) and CMYK values (0–100) in
+      the Color element's `ColorValue` attribute.
+- [ ] Spec: resolve a known color from the fixture's Graphic.xml.
+
+## Files
+
+- `lib/idml/render/color_resolver.rb`
+- `lib/idml/elements/color.rb` (verify ColorValue attribute exists)
+- `spec/idml/render/color_resolver_spec.rb`
+
+## Design notes
+
+- Resources/Graphic.xml contains `<Color Self="Color/Red" Model="RGB"
+  ColorValue="255 0 0" />` entries.
+- Color names are case-sensitive, prefixed with `Color/` or `Swatch/`.
+- The `[None]` and `[Registration]` colors are special: `[None]` = no
+  fill, `[Registration]` = 100% all channels (registration mark black).
+
+## Dependencies
+
+- TODO 06 (PDF color operators).