idml 0.1.0

data/TODO.pdf/23-fontmetrics-ps-name-fix.md

@@ -0,0 +1,43 @@
+# TODO PDF 23: FontMetrics PostScript name fix
+
+## Goal
+
+Fix the `FontMetrics#postscript_name` method to prefer platform 3
+(Windows, UTF-16BE) name records over platform 1 (Macintosh, MacRoman).
+Currently the first matching name_id record is returned regardless of
+platform, producing garbled names like "A r i a l M T".
+
+## Why
+
+The garbled PS name flows into the embedded font's `/BaseFont` entry,
+producing invalid PDF font references. Font embedding tests must
+tolerate the garbled name instead of asserting the correct value.
+
+## Acceptance criteria
+
+- [ ] `FontMetrics#parse_name_entry` iterates all records and prefers:
+      1. platform_id=3 (Windows), encoding_id=1 (UCS-2)
+      2. platform_id=3, any encoding
+      3. platform_id=1 (Macintosh)
+      4. platform_id=0 (Unicode)
+- [ ] `Arial.ttf` produces `postscript_name == "ArialMT"`.
+- [ ] `Helvetica.ttf` (if available) produces correct PS name.
+- [ ] Spec: assert exact PS name for a known font.
+
+## Files
+
+- `lib/idml/text_engine/font_metrics.rb` (fix `parse_name_entry`)
+- `spec/idml/text_engine/font_metrics_spec.rb`
+
+## Design notes
+
+- The name table has multiple records per name_id, one per
+  platform/encoding/language combination. Windows (platform 3)
+  records are the most reliable for PS names.
+- Platform 1 (Macintosh) records use MacRoman encoding — the existing
+  `decode_name_string` already handles this, but the selection logic
+  doesn't prefer platform 3.
+
+## Dependencies
+
+- None.

data/TODO.pdf/24-antipattern-coverage.md

@@ -0,0 +1,35 @@
+# TODO PDF 24: Anti-pattern coverage for render modules
+
+## Goal
+
+Ensure all new render and text-engine modules pass the anti-pattern
+spec. Add any missing modules to the spec's file enumeration.
+
+## Why
+
+The anti-pattern spec (`spec/anti_patterns_spec.rb`) checks every `lib/`
+file for forbidden patterns (Nokogiri, REXML, method_missing, send,
+instance_variable_set, require_relative, etc.). New modules added in
+TODOs 09–23 must be covered.
+
+## Acceptance criteria
+
+- [ ] `bundle exec rspec spec/anti_patterns_spec.rb` passes with 0
+      violations across all `lib/idml/render/` and `lib/idml/text_engine/`
+      files.
+- [ ] No `require_relative` in any new file.
+- [ ] No `double()` in any new spec file.
+- [ ] All new modules use `autoload` (defined in parent namespace file).
+
+## Files
+
+- `spec/anti_patterns_spec.rb` (verify coverage)
+
+## Design notes
+
+- The spec auto-discovers all `.rb` files under `lib/`, so new files
+  are automatically checked. But verify no new violations are introduced.
+
+## Dependencies
+
+- All TODOs that add new lib/ files.

data/TODO.pdf/25-cli-render.md

@@ -0,0 +1,38 @@
+# TODO PDF 25: CLI render subcommand
+
+## Goal
+
+Add a `render` subcommand to the `idml` CLI that converts an IDML
+file to PDF.
+
+## Why
+
+Users need a command-line interface to convert IDML to PDF without
+writing Ruby code. The rendering pipeline exists but is only accessible
+programmatically.
+
+## Acceptance criteria
+
+- [ ] `idml render input.idml output.pdf` produces a valid PDF.
+- [ ] `--font-path` option adds custom font search directories.
+- [ ] `--verbose` option prints progress (spreads processed, images
+      embedded, fonts resolved).
+- [ ] Exit code 0 on success, 1 on error (with message to stderr).
+- [ ] Spec: invoke the CLI via `Thor` and verify output file exists.
+
+## Files
+
+- `lib/idml/cli.rb` (add `render` command)
+- `lib/idml/cli/` (if commands are split into subcommand files)
+- `spec/idml/cli_spec.rb`
+
+## Design notes
+
+- The CLI uses `Thor` (already a dependency).
+- The render command calls `Idml::Render.render(package:, to:, font_search_paths:)`.
+- Error handling: catch `Errors::PackageNotFound`, `Errors::InvalidPackage`
+  and print user-friendly messages.
+
+## Dependencies
+
+- TODO 12 (Pipeline).

data/TODO.pdf/26-renderer-registry.md

@@ -0,0 +1,45 @@
+# TODO PDF 26: Page-item renderer registry (OCP)
+
+## Goal
+
+Replace the `case/when` dispatch in `SpreadRenderer` with a registration-
+based renderer registry. Each page-item type gets its own renderer class
+that self-registers. Adding a new type = creating a new class, not
+editing a switch statement.
+
+## Why
+
+The current `SpreadRenderer#render_page_item` uses `case item when
+Idml::Elements::Rectangle ...`. This violates OCP — every new page-item
+type requires modifying SpreadRenderer. A registry decouples dispatch
+from the SpreadRenderer, making the system open for extension.
+
+## Acceptance criteria
+
+- [ ] `Idml::Render::PageItemRenderer` module with `register(type,
+      renderer)` and `for(item)` class methods.
+- [ ] `Idml::Render::RenderContext` struct carrying shared state
+      (package, font_resolver, color_resolver, page dimensions).
+- [ ] `RectangleRenderer`, `TextFrameRenderer`, `PolygonRenderer`,
+      `GraphicLineRenderer` classes — each returns a string of PDF
+      operators.
+- [ ] Each renderer registers itself: `PageItemRenderer.register(
+      Idml::Elements::Rectangle, RectangleRenderer)`.
+- [ ] `SpreadRenderer` delegates to `PageItemRenderer.for(item)`.
+- [ ] No `case/when` or `is_a?` dispatch in SpreadRenderer.
+- [ ] Specs for each renderer and the registry.
+
+## Files
+
+- `lib/idml/render/page_item_renderer.rb`
+- `lib/idml/render/render_context.rb`
+- `lib/idml/render/renderers/rectangle_renderer.rb`
+- `lib/idml/render/renderers/text_frame_renderer.rb`
+- `lib/idml/render/renderers/polygon_renderer.rb`
+- `lib/idml/render/renderers/graphic_line_renderer.rb`
+- `lib/idml/render/spread_renderer.rb` (simplify to delegate)
+- `lib/idml/render.rb` (add autoloads)
+
+## Dependencies
+
+- TODOs 14–18 (existing element models and rendering).

data/TODO.pdf/27-text-engine-integration.md

@@ -0,0 +1,41 @@
+# TODO PDF 27: Text engine integration
+
+## Goal
+
+Wire the text engine (Shaper → LineBreaker → Justifier → VerticalLayout)
+into TextFrame rendering. Currently text is dumped as a single run at a
+hardcoded position. The text engine should lay out text within the
+frame's geometry, respecting insets and applying word-wrap.
+
+## Why
+
+The text engine was built in TODOs 01–05 but never used. Text rendering
+produces a single `Tj` with the first 200 characters at position (72,
+page_height-72). Real layout requires shaping glyphs, breaking lines at
+the frame width, and positioning each line at the correct baseline.
+
+## Acceptance criteria
+
+- [ ] TextFrameRenderer extracts text content from the linked Story.
+- [ ] Text is shaped via `TextEngine::Shaper` using the resolved font.
+- [ ] Lines broken via `TextEngine::LineBreaker` at frame width minus
+      insets.
+- [ ] Lines justified via `TextEngine::Justifier`.
+- [ ] Glyphs positioned via `TextEngine::VerticalLayout`.
+- [ ] PDF text operators emitted for each positioned glyph run.
+- [ ] Falls back to simple text dump when no font metrics available.
+- [ ] Spec: render a TextFrame with known text, verify multiple `Tj`
+      operators (one per line) in the PDF.
+
+## Files
+
+- `lib/idml/render/renderers/text_frame_renderer.rb`
+- `lib/idml/render/style_resolver.rb` (extract font/size from CSR)
+- `spec/idml/render/text_frame_renderer_spec.rb`
+
+## Dependencies
+
+- TODO 26 (renderer registry).
+- TODO 28 (path geometry for frame bounds).
+- TODO 29 (character style extraction).
+- TODOs 01–05 (text engine).

data/TODO.pdf/28-path-geometry-models.md

@@ -0,0 +1,47 @@
+# TODO PDF 28: Path geometry models
+
+## Goal
+
+Create typed element models for IDML's path geometry hierarchy:
+`PathGeometry`, `GeometryPathType`, `PathPointArray`, `PathPointType`.
+Wire them as children of Rectangle, TextFrame, Polygon, GraphicLine via
+a `Properties` wrapper.
+
+## Why
+
+Page-item geometry (position, size, shape) is stored in
+`Properties/PathGeometry/GeometryPathType/PathPointArray/PathPointType`.
+Without modeling this, the renderer cannot determine where to place
+shapes or text frames. Currently the renderer uses hardcoded positions.
+
+## Acceptance criteria
+
+- [ ] `Idml::Elements::PathPointType` — Anchor, LeftDirection,
+      RightDirection attributes (space-separated "x y" doubles).
+- [ ] `Idml::Elements::PathPointArray` — collection of PathPointType.
+- [ ] `Idml::Elements::GeometryPathType` — PathOpen attribute +
+      PathPointArray child.
+- [ ] `Idml::Elements::PathGeometry` — collection of GeometryPathType.
+- [ ] `Idml::Elements::Properties` — wrapper containing PathGeometry,
+      PathBoundingBox, Label.
+- [ ] Rectangle, TextFrame, Polygon, GraphicLine have `properties`
+      attribute.
+- [ ] Convenience method `geometric_bounds` on each page item: derives
+      `[y1, x1, y2, x2]` from PathPointType anchors.
+- [ ] Spec: parse fixture Rectangle, verify geometric_bounds matches
+      the PathPointArray anchors.
+
+## Files
+
+- `lib/idml/elements/path_point_type.rb`
+- `lib/idml/elements/path_point_array.rb`
+- `lib/idml/elements/geometry_path_type.rb`
+- `lib/idml/elements/path_geometry.rb`
+- `lib/idml/elements/properties.rb`
+- `lib/idml/elements/rectangle.rb` (add properties)
+- `lib/idml/elements/text_frame.rb` (add properties)
+- `lib/idml/elements.rb` (autoloads)
+
+## Dependencies
+
+- TODO 14 (page-item element models).

data/TODO.pdf/29-character-style-extraction.md

@@ -0,0 +1,36 @@
+# TODO PDF 29: Character style extraction
+
+## Goal
+
+Extract font family, size, color, and style attributes from
+CharacterStyleRange elements in Stories. Pass these as styled text runs
+to the text engine for per-run rendering.
+
+## Why
+
+Currently the renderer uses `story.text_content` which flattens all
+styled runs into a single string. Real documents have mixed fonts,
+sizes, and colors within a single text frame. Each CharacterStyleRange
+carries `AppliedFont`, `PointSize`, `FillColor`, `FontStyle` etc.
+
+## Acceptance criteria
+
+- [ ] `Idml::Render::StyleResolver` extracts styled runs from a Story.
+- [ ] Each run carries: text, font_family, font_style, point_size,
+      fill_color, fill_tint.
+- [ ] Style attributes cascade from ParagraphStyleRange →
+      CharacterStyleRange (CSR overrides PSR).
+- [ ] Style attributes resolved from Resources/Styles.xml when CSR
+      references an `AppliedCharacterStyle`.
+- [ ] Spec: extract runs from the fixture's Story, verify font size
+      and family are populated.
+
+## Files
+
+- `lib/idml/render/style_resolver.rb`
+- `spec/idml/render/style_resolver_spec.rb`
+
+## Dependencies
+
+- TODO 14 (CharacterStyleRange model exists).
+- TODO 22 (ColorResolver).

data/TODO.pdf/30-shape-geometry-rendering.md

@@ -0,0 +1,40 @@
+# TODO PDF 30: Shape geometry rendering
+
+## Goal
+
+Render Rectangle, Polygon, and GraphicLine shapes using their actual
+PathGeometry — not hardcoded 100×100 rectangles. Apply ItemTransform
+and fill/stroke colors.
+
+## Why
+
+Currently `render_rectangle` emits a fixed `0 0 100 100 re` regardless
+of the actual shape bounds. Real shapes have arbitrary positions and
+sizes derived from PathPointArray anchors.
+
+## Acceptance criteria
+
+- [ ] Rectangle: derive bounds from PathPointType anchors, emit `re`
+      operator with correct x/y/width/height.
+- [ ] Polygon: emit `m`/`l` path operators from PathPointArray.
+- [ ] GraphicLine: emit open path with stroke.
+- [ ] ItemTransform applied via `cm` operator.
+- [ ] FillColor resolved via ColorResolver, emitted as `rg`/`k`.
+- [ ] StrokeColor + StrokeWeight emitted as `RG`/`K` + `w` + `S`.
+- [ ] Coordinate Y-flip applied (IDML top-left → PDF bottom-left origin).
+- [ ] Spec: render a Rectangle with known PathGeometry, verify PDF
+      contains `re` with correct coordinates.
+
+## Files
+
+- `lib/idml/render/renderers/rectangle_renderer.rb`
+- `lib/idml/render/renderers/polygon_renderer.rb`
+- `lib/idml/render/renderers/graphic_line_renderer.rb`
+- `lib/idml/render/coordinate_transform.rb`
+- `spec/idml/render/shape_geometry_spec.rb`
+
+## Dependencies
+
+- TODO 26 (renderer registry).
+- TODO 28 (path geometry models).
+- TODO 22 (ColorResolver).

data/TODO.pdf/31-stroke-rendering.md

@@ -0,0 +1,35 @@
+# TODO PDF 31: Stroke rendering
+
+## Goal
+
+Render stroke attributes on page items: stroke color, weight, end cap,
+join style, and dash patterns.
+
+## Why
+
+Currently only fill is rendered. Many IDML page items have visible
+strokes (borders, lines, arrows). StrokeWeight, EndCap, EndJoin, and
+StrokeType (solid/dashed/dotted) need to be emitted as PDF operators.
+
+## Acceptance criteria
+
+- [ ] StrokeColor resolved via ColorResolver, emitted as `RG`/`K`.
+- [ ] StrokeWeight emitted as `w` operator.
+- [ ] EndCap (Butt/Round/Square) emitted as `J` operator.
+- [ ] EndJoin (Miter/Round/Bevel) emitted as `j` operator.
+- [ ] MiterLimit emitted as `M` operator.
+- [ ] DashedStrokeStyle: dash array + dash offset emitted as `d`.
+- [ ] DottedStrokeStyle: dot pattern as dash array.
+- [ ] Spec: render a Rectangle with stroke, verify `w`, `RG`, `S`
+      operators in PDF.
+
+## Files
+
+- `lib/idml/render/stroke_renderer.rb`
+- `lib/idml/render/renderers/rectangle_renderer.rb` (integrate)
+- `spec/idml/render/stroke_renderer_spec.rb`
+
+## Dependencies
+
+- TODO 30 (shape geometry rendering).
+- TODO 22 (ColorResolver).

data/TODO.pdf/32-master-spread-rendering.md

@@ -0,0 +1,36 @@
+# TODO PDF 32: Master spread rendering
+
+## Goal
+
+Render master spread page items as background on each page. Master
+spreads contain repeating elements (headers, footers, page numbers,
+backgrounds) that appear on every page referencing the master.
+
+## Why
+
+Currently master spread items are ignored. Documents with master
+content (page numbers, running headers) lose this content in the PDF
+output. The Spread's `ShowMasterItems` attribute and Page's
+`AppliedMaster` attribute control master item visibility.
+
+## Acceptance criteria
+
+- [ ] Pipeline resolves each Page's `AppliedMaster` to a
+      `Parts::MasterSpread`.
+- [ ] Master spread page items rendered before spread's own items
+      (background layer).
+- [ ] `ShowMasterItems="false"` on Spread suppresses master items.
+- [ ] Master items positioned relative to the page (MasterPageTransform
+      applied).
+- [ ] Spec: render a fixture with master items, verify background
+      content appears in the PDF.
+
+## Files
+
+- `lib/idml/render/pipeline.rb` (resolve master spreads)
+- `lib/idml/render/spread_renderer.rb` (render master items first)
+- `spec/idml/render/master_spread_spec.rb`
+
+## Dependencies
+
+- TODOs 14–16 (element models + typed pipeline).

data/TODO.pdf/33-font-resolution-from-idml.md

@@ -0,0 +1,38 @@
+# TODO PDF 33: Font resolution from IDML
+
+## Goal
+
+Resolve fonts referenced in IDML documents using Resources/Fonts.xml.
+The FontFamily and Font entries map family/style names to PostScript
+names, which the FontResolver uses to find the actual font file.
+
+## Why
+
+Currently the Pipeline always uses "Helvetica" as the default font.
+Real IDML documents reference specific fonts (Minion Pro, Myriad Pro,
+etc.) via CharacterStyleRange#AppliedFont. The Fonts.xml part carries
+the PostScriptName needed to locate the font file on disk.
+
+## Acceptance criteria
+
+- [ ] `Parts::Fonts` typed model parses FontFamily → Font entries.
+- [ ] `FontFamily#name` and `Font#postscript_name` accessible.
+- [ ] Pipeline reads `package.fonts` and passes font info to the
+      FontResolver.
+- [ ] FontResolver can search by PostScriptName (not just family name).
+- [ ] CharacterStyleRange#applied_font mapped to a font file.
+- [ ] Spec: load fixture Fonts.xml, verify "Minion Pro" family has
+      PostScriptName "MinionPro-Regular".
+
+## Files
+
+- `lib/idml/parts/fonts.rb` (verify typed model)
+- `lib/idml/elements/font_family.rb` (verify)
+- `lib/idml/elements/font.rb` (verify)
+- `lib/idml/text_engine/font_resolver.rb` (add PS name search)
+- `spec/idml/text_engine/font_resolver_spec.rb`
+
+## Dependencies
+
+- TODO 01 (FontMetrics).
+- TODO 02 (FontResolver).

data/TODO.pdf/34-story-threading.md

@@ -0,0 +1,32 @@
+# TODO PDF 34: Story threading
+
+## Goal
+
+Follow the PreviousTextFrame/NextTextFrame chain to thread stories
+across multiple text frames. A single story can flow through several
+frames; the renderer must lay out text sequentially across the chain.
+
+## Why
+
+Currently each TextFrame is rendered independently using its full story
+text. In reality, a story's text overflows from one frame to the next.
+Frame A gets the first N lines, frame B gets the remainder.
+
+## Acceptance criteria
+
+- [ ] Pipeline identifies text frame chains (head frame = PreviousTextFrame=="n").
+- [ ] Story text distributed across the chain: frame A gets lines that
+      fit, overflow goes to frame B.
+- [ ] Each frame renders only its portion of the story.
+- [ ] Handles circular references gracefully (no infinite loop).
+- [ ] Spec: two linked TextFrames, verify text splits across them.
+
+## Files
+
+- `lib/idml/render/story_threader.rb`
+- `lib/idml/render/pipeline.rb` (identify chains)
+- `spec/idml/render/story_threader_spec.rb`
+
+## Dependencies
+
+- TODO 27 (text engine integration).

data/TODO.pdf/35-pdf-metadata.md

@@ -0,0 +1,34 @@
+# TODO PDF 35: PDF metadata
+
+## Goal
+
+Embed document metadata (Title, Author, Subject, Keywords, Creator,
+Producer, CreationDate) in the PDF Info dictionary, sourced from the
+IDML Preferences part.
+
+## Why
+
+PDF metadata is used by search engines, document management systems,
+and accessibility tools. Currently the produced PDF has no metadata
+beyond the bare structure.
+
+## Acceptance criteria
+
+- [ ] `PdfWriter#add_info(hash)` writes an Info object referenced by
+      the trailer.
+- [ ] Pipeline extracts metadata from Preferences (document title,
+      author) and designmap (DOMVersion).
+- [ ] Producer set to "idml gem v{VERSION}".
+- [ ] CreationDate set to current time (PDF date format).
+- [ ] Spec: render a PDF, verify `/Title`, `/Producer`, `/CreationDate`
+      in the Info dictionary.
+
+## Files
+
+- `lib/idml/render/pdf_writer.rb` (add_info method)
+- `lib/idml/render/pipeline.rb` (extract + pass metadata)
+- `spec/idml/render/pdf_metadata_spec.rb`
+
+## Dependencies
+
+- TODO 12 (Pipeline).

data/TODO.pdf/36-performance-caching.md

@@ -0,0 +1,33 @@
+# TODO PDF 36: Performance caching
+
+## Goal
+
+Cache expensive operations: FontMetrics file parsing, FontResolver
+search results, and ColorResolver lookups. Currently every
+`FontMetrics.open` re-reads and re-parses the font binary.
+
+## Why
+
+The Pipeline opens the same font file multiple times (once for text
+metrics, once for embedding). FontResolver scans all .ttf/.otf files
+on every resolve. These are O(n) operations repeated per spread/item.
+
+## Acceptance criteria
+
+- [ ] `FontMetrics.open` caches by file path (class-level Hash).
+- [ ] `FontResolver#resolve` caches by [family, style] key (already
+      per-instance; add class-level for cross-instance reuse).
+- [ ] `ColorResolver#resolve` caches by color name (already per-instance).
+- [ ] `Package#part` caches typed part instances (already per-instance).
+- [ ] Benchmark: rendering a 10-spread package shows < 2x slowdown vs
+      single-spread.
+- [ ] Spec: verify FontMetrics.open returns same instance for same path.
+
+## Files
+
+- `lib/idml/text_engine/font_metrics.rb` (class cache)
+- `lib/idml/text_engine/font_resolver.rb` (class cache)
+
+## Dependencies
+
+- None.

data/TODO.pdf/37-round-trip-specs.md

@@ -0,0 +1,33 @@
+# TODO PDF 37: Round-trip specs for element models
+
+## Goal
+
+Add round-trip specs for every page-item element model: `from_xml(xml)`
+→ `to_xml` should produce XML equivalent to the input. This catches
+attribute mapping errors and child-element ordering issues.
+
+## Why
+
+The element models were added in TODO 14 with structural specs (parse
+fixture, verify attributes) but no round-trip specs. Round-trip is the
+project's core quality gate — it proves the model faithfully represents
+the XML.
+
+## Acceptance criteria
+
+- [ ] Round-trip spec for: Page, Rectangle, TextFrame, Image, Link,
+      Polygon, Group, GraphicLine.
+- [ ] Each spec: read fixture part XML → from_xml → to_xml → compare
+      with original (ignoring whitespace, attribute order).
+- [ ] Spread-level round-trip: Spread_ud1.xml preserves all modeled
+      child elements.
+- [ ] Any round-trip failure identifies the specific attribute/element
+      that diverged.
+
+## Files
+
+- `spec/idml/elements/round_trip_spec.rb`
+
+## Dependencies
+
+- TODO 14 (element models).

data/TODO.pdf/38-pdf-output-validation.md

@@ -0,0 +1,34 @@
+# TODO PDF 38: PDF output validation
+
+## Goal
+
+Validate that the PDF files produced by the Pipeline are structurally
+correct: parseable cross-reference table, valid object streams,
+balanced save/restore state, required dictionary entries.
+
+## Why
+
+The current specs check for substrings in the PDF (`/Type /Page`,
+`/Filter /DCTDecode`) but don't verify the PDF is actually parseable.
+A malformed xref table or missing `endobj` would silently produce an
+invalid file that some viewers reject.
+
+## Acceptance criteria
+
+- [ ] Spec that opens the output PDF and walks the xref table.
+- [ ] Verify every `n` entry points to a valid `N 0 obj` header.
+- [ ] Verify every object has matching `endobj`.
+- [ ] Verify trailer `/Root` points to a valid Catalog.
+- [ ] Verify Catalog `/Pages` points to a valid Pages tree.
+- [ ] Verify each Page has `/MediaBox`, `/Contents`, `/Resources`.
+- [ ] Verify content stream length matches `/Length` entry.
+- [ ] Spec: run on the fixture output PDF, all checks pass.
+
+## Files
+
+- `spec/idml/render/pdf_validation_spec.rb`
+- `lib/idml/render/pdf_validator.rb` (optional — pure validation logic)
+
+## Dependencies
+
+- TODO 12 (Pipeline).

data/TODO.pdf/39-geometry-coordinate-helpers.md

@@ -0,0 +1,26 @@
+# TODO PDF 39: Geometry module coordinate helpers
+
+## Goal
+
+Centralize all coordinate-system conversions (IDML ↔ PDF) in the
+`Idml::Geometry` module. Every renderer derives placement from these
+helpers instead of inline math.
+
+## Status: DONE
+
+## What was implemented
+
+- `Geometry.parse_transform(str)` — parses "a b c d e f" into a Transform.
+- `Geometry.apply_transform(transform, x, y)` — applies affine matrix to a point.
+- `Geometry.combine_transforms(outer, inner)` — multiplies two transforms.
+- `Geometry.transform_bounds(bounds, transform)` — transforms [y1,x1,y2,x2].
+- `Geometry.bounds_to_pdf_rect(bounds, page_height)` — converts to PDF
+  `{x:, y:, width:, height:}` with Y-axis flip.
+- `Color.fill_op(color_hash)` / `Color.stroke_op(color_hash)` — dispatch
+  RGB/CMYK from a resolved color hash.
+- `Path.stroke_width(weight)` — PDF `w` operator.
+- RectangleRenderer: applies ItemTransform + Y-flip, renders fill and stroke.
+- PolygonRenderer: uses bounds + fill + stroke (bounding-box approximation).
+- TextFrameRenderer: uses frame geometric_bounds for text engine layout.
+- StyleResolver: extracts styled runs from Story (font_style, point_size,
+  fill_color per CharacterStyleRange).

data/TODO.pdf/40-font-ps-name-resolution.md

@@ -0,0 +1,30 @@
+# TODO PDF 40: Font PS name resolution from Fonts.xml
+
+## Goal
+
+Connect the IDML document's Fonts.xml (FontFamily/Font entries with
+PostScriptName) to the FontResolver so text rendering uses the correct
+font, not the hardcoded "Helvetica" default.
+
+## Status: PARTIALLY DONE
+
+## What was done
+
+- Verified `Parts::Fonts` typed model parses FontFamily → Font entries.
+- `FontFamily` and `Font` element models exist and expose PostScriptName.
+- The FontResolver can find fonts by family name + style.
+
+## What remains
+
+- Map CharacterStyleRange#applied_font → FontFamily/Font → PostScriptName
+  → FontResolver search.
+- Add PostScriptName-based search to FontResolver (current search is
+  family-name based).
+- Pipeline: pass document font references to the font resolver.
+- When a document font can't be found on disk, log a warning and fall
+  back to the default font.
+
+## Dependencies
+
+- TODO 29 (StyleResolver for applied_font extraction).
+- TODO 33 (font resolution from IDML).