idml 0.1.0

data/Gemfile.lock

@@ -0,0 +1,253 @@
+PATH
+  remote: .
+  specs:
+    idml (0.1.0)
+      bigdecimal
+      fontisan
+      lutaml-model (~> 0.8.18)
+      pdfrb
+      rubyzip
+      thor
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    ast (2.4.3)
+    base64 (0.3.0)
+    bigdecimal (4.1.2)
+    bindata (2.5.1)
+    brotli (0.8.0)
+    canon (0.2.12)
+      diff-lcs
+      json
+      moxml (~> 0.1.22)
+      nokogiri
+      paint
+      rainbow
+      table_tennis
+      thor
+      unicode-name
+    concurrent-ruby (1.3.8)
+    csv (3.3.6)
+    diff-lcs (1.6.2)
+    ffi (1.17.4-aarch64-linux-gnu)
+    ffi (1.17.4-aarch64-linux-musl)
+    ffi (1.17.4-arm-linux-gnu)
+    ffi (1.17.4-arm-linux-musl)
+    ffi (1.17.4-arm64-darwin)
+    ffi (1.17.4-x64-mingw-ucrt)
+    ffi (1.17.4-x86_64-darwin)
+    ffi (1.17.4-x86_64-linux-gnu)
+    ffi (1.17.4-x86_64-linux-musl)
+    fontisan (0.4.45)
+      base64
+      bindata (~> 2.5)
+      brotli (~> 0.5)
+      logger
+      lutaml-model (~> 0.8)
+      nokogiri (~> 1.16)
+      thor (~> 1.3)
+    json (2.21.2)
+    language_server-protocol (3.17.0.6)
+    lint_roller (1.1.0)
+    liquid (5.13.0)
+      bigdecimal
+      strscan (>= 3.1.1)
+    logger (1.7.0)
+    lutaml-model (0.8.19)
+      base64
+      bigdecimal
+      canon
+      concurrent-ruby
+      liquid (>= 4.0, < 6.0)
+      moxml (~> 0.1.25)
+      ostruct
+      rubyzip (~> 2.3)
+      thor
+    memo_wise (1.13.0)
+    moxml (0.1.26)
+    nokogiri (1.19.4-aarch64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.4-aarch64-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.4-arm-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.4-arm-linux-musl)
+      racc (~> 1.4)
+    nokogiri (1.19.4-arm64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.4-x64-mingw-ucrt)
+      racc (~> 1.4)
+    nokogiri (1.19.4-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.19.4-x86_64-linux-gnu)
+      racc (~> 1.4)
+    nokogiri (1.19.4-x86_64-linux-musl)
+      racc (~> 1.4)
+    ostruct (0.6.3)
+    paint (2.3.0)
+    parallel (2.1.0)
+    parser (3.3.12.0)
+      ast (~> 2.4.1)
+      racc
+    pdfrb (0.3.0)
+      thor
+    prism (1.9.0)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.4.2)
+    regexp_parser (2.12.0)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.88.2)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      parallel (>= 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.50.0)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    rubocop-rake (0.7.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.72.1)
+    rubocop-rspec (3.10.2)
+      lint_roller (~> 1.1)
+      regexp_parser (>= 2.0)
+      rubocop (~> 1.86, >= 1.86.2)
+    ruby-progressbar (1.13.0)
+    rubyzip (2.4.1)
+    simplecov (1.0.3)
+    strscan (3.1.8)
+    table_tennis (1.0.0)
+      csv (~> 3.3)
+      ffi (~> 1.17)
+      memo_wise (~> 1.13)
+      paint (~> 2.3)
+      unicode-display_width (~> 3.2)
+    thor (1.5.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    unicode-name (1.14.0)
+      unicode-types (~> 1.11)
+    unicode-types (1.11.0)
+    yard (0.9.45)
+
+PLATFORMS
+  aarch64-linux-gnu
+  aarch64-linux-musl
+  arm-linux-gnu
+  arm-linux-musl
+  arm64-darwin
+  x64-mingw-ucrt
+  x86_64-darwin
+  x86_64-linux-gnu
+  x86_64-linux-musl
+
+DEPENDENCIES
+  idml!
+  lutaml-model (~> 0.8.0)
+  pdfrb
+  rake
+  rspec
+  rubocop
+  rubocop-performance
+  rubocop-rake
+  rubocop-rspec
+  simplecov
+  thor
+  yard
+
+CHECKSUMS
+  ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
+  base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  bigdecimal (4.1.2) sha256=53d217666027eab4280346fba98e7d5b66baaae1b9c3c1c0ffe89d48188a3fbd
+  bindata (2.5.1) sha256=53186a1ec2da943d4cb413583d680644eb810aacbf8902497aac8f191fad9e58
+  brotli (0.8.0) sha256=0c5a42046b3b603fb109656881147fd76064c034b7d19c1b4fcc32a093a4d55d
+  canon (0.2.12) sha256=9b87514fbf6c0f9f28d1e2746ea5837b08e24e50c30751dba27a89f86e8709af
+  concurrent-ruby (1.3.8) sha256=b2f1be836e968ccc78ccfce277ea79c72a88633f22306782c16ff23fb415d1e1
+  csv (3.3.6) sha256=aba61e7e507a66f03d45cb1f3c4b6359861c3504038b422962875dce099e4456
+  diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
+  ffi (1.17.4-aarch64-linux-gnu) sha256=b208f06f91ffd8f5e1193da3cae3d2ccfc27fc36fba577baf698d26d91c080df
+  ffi (1.17.4-aarch64-linux-musl) sha256=9286b7a615f2676245283aef0a0a3b475ae3aae2bb5448baace630bb77b91f39
+  ffi (1.17.4-arm-linux-gnu) sha256=d6dbddf7cb77bf955411af5f187a65b8cd378cb003c15c05697f5feee1cb1564
+  ffi (1.17.4-arm-linux-musl) sha256=9d4838ded0465bef6e2426935f6bcc93134b6616785a84ffd2a3d82bc3cf6f95
+  ffi (1.17.4-arm64-darwin) sha256=19071aaf1419251b0a46852abf960e77330a3b334d13a4ab51d58b31a937001b
+  ffi (1.17.4-x64-mingw-ucrt) sha256=f6ff9618cfccc494138bddade27aa06c74c6c7bc367a1ea1103d80c2fcb9ed35
+  ffi (1.17.4-x86_64-darwin) sha256=aa70390523cf3235096cf64962b709b4cfbd5c082a2cb2ae714eb0fe2ccda496
+  ffi (1.17.4-x86_64-linux-gnu) sha256=9d3db14c2eae074b382fa9c083fe95aec6e0a1451da249eab096c34002bc752d
+  ffi (1.17.4-x86_64-linux-musl) sha256=3fdf9888483de005f8ef8d1cf2d3b20d86626af206cbf780f6a6a12439a9c49e
+  fontisan (0.4.45) sha256=2337ca0205f806647b24b8cac57aa34f3769473026ae6f52dc36bde0feed6c62
+  idml (0.1.0)
+  json (2.21.2) sha256=1f1d3b7cf2b3ba1a69beca0bb6db13d5438b80bff3cd54cdaaa620b9b07c1c6a
+  language_server-protocol (3.17.0.6) sha256=5ef2c0c138f8267e1bc631d3328347d354f96724b0af22f2c79516120443b7f0
+  lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87
+  liquid (5.13.0) sha256=09d594fd96b98e19a8fd5c32aadcc6950df429b69f48c2f774c0db0ce272bf19
+  logger (1.7.0) sha256=196edec7cc44b66cfb40f9755ce11b392f21f7967696af15d274dde7edff0203
+  lutaml-model (0.8.19) sha256=470a54930b463074c4112fe0abf6708c3a3fd42c460fdb8cad527978b3ddc7ae
+  memo_wise (1.13.0) sha256=30220c38c4cef410849bc73553c58664dc2c91c6379e4a1df22aea02358b716b
+  moxml (0.1.26) sha256=f29c2a76377f014920fbb9bec8d66acc3f162fa8a4f6a855010c3d2ac1ceeb70
+  nokogiri (1.19.4-aarch64-linux-gnu) sha256=1269fb644a6de405057a53dd5c762b1209b43ca7424f839454d3dbc677c31a8f
+  nokogiri (1.19.4-aarch64-linux-musl) sha256=35c65b9ce72b3bb03207bdbe7067915019dc18c1b9b59139684bd6690fdd01af
+  nokogiri (1.19.4-arm-linux-gnu) sha256=a301313e38bb065d68239e79734bcd6f56fb6efaacebde29e9abf2a4735340ca
+  nokogiri (1.19.4-arm-linux-musl) sha256=588923c101bcfa78869734d247d25b598674323e7f22474fc468f6e5647311eb
+  nokogiri (1.19.4-arm64-darwin) sha256=a46db9853286e6597b36ebc6953817d15acf3a299583eb3f89fdc6f91dd63527
+  nokogiri (1.19.4-x64-mingw-ucrt) sha256=051da97b8eccfdb5444fed40246a35e10d7298b9efe759b4cd25455ea04c587e
+  nokogiri (1.19.4-x86_64-darwin) sha256=7fd17057d3e1f00e9954a74b3cd76595d3d4a5ef233b7ed9599047c204f70551
+  nokogiri (1.19.4-x86_64-linux-gnu) sha256=379fae440b28915e3f19d752ce2dcf8465ed2b2fbefd2a7ca0dd497bc981a06a
+  nokogiri (1.19.4-x86_64-linux-musl) sha256=17dfb7c1fa194ae02fbf7c51a7afc8d278045ab3fdacfd86f91d02d7b274470b
+  ostruct (0.6.3) sha256=95a2ed4a4bd1d190784e666b47b2d3f078e4a9efda2fccf18f84ddc6538ed912
+  paint (2.3.0) sha256=327d623e4038619d5bd99ae5db07973859cd78400c7f0329eea283cef8e83be5
+  parallel (2.1.0) sha256=b35258865c2e31134c5ecb708beaaf6772adf9d5efae28e93e99260877b09356
+  parser (3.3.12.0) sha256=21a6d7f755d5a24dfbdc6e6b772e4e879a52e7631a88bc5a3a134606052c9828
+  pdfrb (0.3.0) sha256=2a83db0730d5c36ea00c4114a635ae045bcc823bac6575332ed56a765d771bcc
+  prism (1.9.0) sha256=7b530c6a9f92c24300014919c9dcbc055bf4cdf51ec30aed099b06cd6674ef85
+  racc (1.8.1) sha256=4a7f6929691dbec8b5209a0b373bc2614882b55fc5d2e447a21aaa691303d62f
+  rainbow (3.1.1) sha256=039491aa3a89f42efa1d6dec2fc4e62ede96eb6acd95e52f1ad581182b79bc6a
+  rake (13.4.2) sha256=cb825b2bd5f1f8e91ca37bddb4b9aaf345551b4731da62949be002fa89283701
+  regexp_parser (2.12.0) sha256=35a916a1d63190ab5c9009457136ae5f3c0c7512d60291d0d1378ba18ce08ebb
+  rspec (3.13.2) sha256=206284a08ad798e61f86d7ca3e376718d52c0bc944626b2349266f239f820587
+  rspec-core (3.13.6) sha256=a8823c6411667b60a8bca135364351dda34cd55e44ff94c4be4633b37d828b2d
+  rspec-expectations (3.13.5) sha256=33a4d3a1d95060aea4c94e9f237030a8f9eae5615e9bd85718fe3a09e4b58836
+  rspec-mocks (3.13.8) sha256=086ad3d3d17533f4237643de0b5c42f04b66348c28bf6b9c2d3f4a3b01af1d47
+  rspec-support (3.13.7) sha256=0640e5570872aafefd79867901deeeeb40b0c9875a36b983d85f54fb7381c47c
+  rubocop (1.88.2) sha256=8def251c90cd955feb4daa3edc0ab56893250c4ce90ef81e6c80c03f9a939bbf
+  rubocop-ast (1.50.0) sha256=b9ca88300da0803ee222ad20cdb30494c0a784eed06fdc35d254b06d662788db
+  rubocop-performance (1.26.1) sha256=cd19b936ff196df85829d264b522fd4f98b6c89ad271fa52744a8c11b8f71834
+  rubocop-rake (0.7.1) sha256=3797f2b6810c3e9df7376c26d5f44f3475eda59eb1adc38e6f62ecf027cbae4d
+  rubocop-rspec (3.10.2) sha256=0b3e2ecc592cd10ecbf0095bb58d1e357905276e069643523cc19eb7495f65e2
+  ruby-progressbar (1.13.0) sha256=80fc9c47a9b640d6834e0dc7b3c94c9df37f08cb072b7761e4a71e22cff29b33
+  rubyzip (2.4.1) sha256=8577c88edc1fde8935eb91064c5cb1aef9ad5494b940cf19c775ee833e075615
+  simplecov (1.0.3) sha256=38ef0514f16ae7562f0d0f4df02610071115103d301b6de7dacbcc000082e39b
+  strscan (3.1.8) sha256=aae2db611a225559f21ffbb71765c9a4e60fd262534a9ea84f4f11c7f32f679e
+  table_tennis (1.0.0) sha256=955f76ca4debd42ee88682af8d4554a74d533c89de4f1581bc37855b15faa956
+  thor (1.5.0) sha256=e3a9e55fe857e44859ce104a84675ab6e8cd59c650a49106a05f55f136425e73
+  unicode-display_width (3.2.0) sha256=0cdd96b5681a5949cdbc2c55e7b420facae74c4aaf9a9815eee1087cb1853c42
+  unicode-emoji (4.2.0) sha256=519e69150f75652e40bf736106cfbc8f0f73aa3fb6a65afe62fefa7f80b0f80f
+  unicode-name (1.14.0) sha256=b350dcdeb503748c8ad05c472e8078570fbf3231a73be53431c15db10bbedbdd
+  unicode-types (1.11.0) sha256=81d1201273260fa89b85471e7eebb93a51bb4e5f078a525508dcae7835d176f9
+  yard (0.9.45) sha256=52e211493f7cb8a3ebf7e104a25a1e73937a3103092545d34cb88fafebb3dc51
+
+BUNDLED WITH
+  4.0.16

data/README.adoc

@@ -0,0 +1,4 @@
+= Ruby parser for Adobe IDML
+
+IDML is the InDesign Markup Language from Adobe used by InDesign.
+

data/Rakefile

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+begin
+  require "yard"
+  YARD::Rake::YardocTask.new do |t|
+    t.files = ["lib/**/*.rb"]
+    t.options = ["--no-private"]
+  end
+rescue LoadError
+  # yard is optional; `rake yard` is unavailable if not installed
+end
+
+task default: %i[spec rubocop]

data/TODO.complete/01-bootstrap.md

@@ -0,0 +1,52 @@
+# TODO 01: Bootstrap gem skeleton
+
+## Goal
+
+Stand up a runnable gem: `bundle exec rake` is green on an empty suite, CI
+workflows fire on PRs, anti-pattern spec is in force.
+
+## Acceptance criteria
+
+- [ ] `idml.gemspec` exists, declares `idml` 0.1.0, Ruby `>= 3.3.0`,
+      BSD-2-Clause, deps `lutaml-model ~> 0.8.18` and `bigdecimal` (no `mml`).
+- [ ] `Gemfile`, `Gemfile.lock` (after `bundle install`).
+- [ ] `Rakefile` with `bundle exec rake` running spec + rubocop.
+- [ ] `.rspec` with `--format documentation --color --require spec_helper`.
+- [ ] `.rubocop.yml` inherits from `riboseinc/oss-guides` + `.rubocop_todo.yml`
+      (empty), enables `rubocop-rspec`, `rubocop-performance`, `rubocop-rake`.
+- [ ] `lib/idml.rb` eager-requires `lutaml/model`, autoloads `VERSION`.
+- [ ] `lib/idml/version.rb` defines `VERSION = "0.1.0"`.
+- [ ] `spec/spec_helper.rb` boots simplecov + loads `lib/idml`.
+- [ ] `spec/anti_patterns_spec.rb` ports sts-ruby's checks: `method_missing`,
+      `respond_to_missing?`, `Object.const_get`, `.send(`,
+      `instance_variable_set/get`, `respond_to?` type-checks, hand-rolled
+      serializers (`to_h`/`from_h`/`to_xml`/`from_xml` etc.), `require_relative`
+      in lib/, internal `require` calls.
+- [ ] `.github/workflows/rake.yml` and `release.yml` use metanorma/ci
+      reusable workflows.
+- [ ] `CODE_OF_CONDUCT.md`.
+- [ ] `bundle exec rake` exits 0 on an empty spec suite.
+
+## Files
+
+- `idml.gemspec`
+- `Gemfile`, `Gemfile.lock`
+- `Rakefile`
+- `.rspec`
+- `.rubocop.yml`, `.rubocop_todo.yml`
+- `lib/idml.rb`, `lib/idml/version.rb`
+- `spec/spec_helper.rb`, `spec/anti_patterns_spec.rb`
+- `.github/workflows/rake.yml`, `.github/workflows/release.yml`
+- `CODE_OF_CONDUCT.md`
+
+## Design notes
+
+- Use `Dir.chdir(File.expand_path(__dir__)) { \`git ls-files -z\`.split("\x0") }`
+  in gemspec to keep `spec.files` accurate (matches sts-ruby pattern).
+- The anti-pattern spec is the project's load-bearing quality gate. It must
+  pass on every commit, including this initial one.
+- Set `TargetRubyVersion: 3.3` in `.rubocop.yml` (matches gemspec minimum).
+
+## Dependencies
+
+- None.

data/TODO.complete/02-package-layer.md

@@ -0,0 +1,48 @@
+# TODO 02: Package layer (ZIP container)
+
+## Goal
+
+`Idml::Package` reads an `.idml` ZIP, exposes its parts by name, and writes
+a new ZIP. Parts layer is not yet typed — parts round-trip as raw XML strings.
+
+## Acceptance criteria
+
+- [ ] `Idml::Package.open(path)` returns a `Package` instance; the underlying
+      `Zip::File` is held internally and closed on GC.
+- [ ] `package.part_names` returns an Array of every entry name (excluding
+      directory entries), sorted.
+- [ ] `package.read_part(name)` returns the raw XML string for that entry.
+- [ ] `package.has_part?(name)` predicate.
+- [ ] `package.each_part(&block)` yields `(name, xml)` pairs; returns
+      Enumerator if no block.
+- [ ] `Idml::Package.write(parts:, to:)` writes a new ZIP at `to:` with:
+      - `mimetype` first, stored (not deflated) — required by IDML UCF spec.
+      - All other parts deflated.
+- [ ] Round-trip: extract every part of `spec/fixtures/sample-with-image.idml`,
+      rezip, assert the new ZIP contains the same entries with byte-equivalent
+      content. (Note: ZIP metadata like timestamps may differ — compare entries
+      only, not the ZIP container bytes.)
+- [ ] `Idml::Errors::PackageNotFound`, `InvalidPackageError`, `PartNotFound`
+      raised at the right boundaries. No bare `RuntimeError`.
+
+## Files
+
+- `lib/idml/errors.rb` — error class hierarchy rooted at `Idml::Error`.
+- `lib/idml/package.rb` — `Package` class.
+- `spec/idml/package_spec.rb` — full coverage.
+
+## Design notes
+
+- Use `rubyzip` (`Zip::File`) — already widely used in the Ruby ecosystem.
+- Add `rubyzip` to gemspec runtime deps.
+- `mimetype` is special: must be first entry, compression method `stored`
+  (zero). IDML readers refuse files that get this wrong.
+- `Package` is read-only by design. Mutation goes through Composition (TODO
+  10), which produces a new `Package`. Avoids working-copy state.
+- `Package` does NOT parse XML. It just hands bytes to the caller. Typing
+  happens at the Parts layer (TODO 03+).
+- Autoload `Package` from `lib/idml.rb`; autoload `Errors` similarly.
+
+## Dependencies
+
+- TODO 01 (bootstrap).

data/TODO.complete/03-parts-registry-and-designmap.md

@@ -0,0 +1,64 @@
+# TODO 03: Parts registry + Designmap model
+
+## Goal
+
+Stand up the part-class registry and ship the first typed part: `Designmap`.
+This TODO establishes the pattern all subsequent part TODOs follow.
+
+## Acceptance criteria
+
+- [ ] `lib/idml/part.rb` defines the `Idml::Part` mixin module with one class
+      method: `part_file(pattern)` — registers the class against a `Regexp`
+      matching its filename inside the package.
+- [ ] `lib/idml/parts.rb` defines `Idml::Parts` with:
+      - autoloads for every part class (this TODO adds only `Designmap`;
+        subsequent TODOs append).
+      - `Parts.class_for(file_name)` returns the registered class or raises
+        `Parts::UnknownPartError`.
+      - `Parts.register(pattern, klass)` — used by the `Part.part_file` macro.
+      - `Parts.all` — returns every registered class, for tooling.
+      - Registry is eager-populated on first lookup (autoload triggering).
+- [ ] `lib/idml/parts/designmap.rb` defines `Idml::Parts::Designmap
+      < Lutaml::Model::Serializable`. Calls `part_file "designmap.xml"`.
+      Attribute list derived from `reference-docs/schemas/package/designmap.rnc`
+      (root element `Document`).
+- [ ] `Package.part(name)` returns a typed model instance when a registered
+      class exists for `name`; falls back to `read_part(name)` (raw XML)
+      otherwise.
+- [ ] Spec: `Designmap.attributes.keys` matches the RNG-derived expected set.
+- [ ] Spec: `Designmap.from_xml(fixture_designmap)` returns an instance with
+      `dom_version: "21.5"`.
+- [ ] Spec: round-trip — `Designmap.to_xml(Designmap.from_xml(xml))` produces
+      XML-equivalent output (canonicalized comparison via Nokogiri).
+- [ ] Spec: `Package.part("designmap.xml")` returns a `Designmap` instance.
+
+## Files
+
+- `lib/idml/part.rb`
+- `lib/idml/parts.rb`
+- `lib/idml/parts/designmap.rb`
+- `lib/idml/parts.rb` — updated with `Designmap` autoload.
+- `lib/idml.rb` — autoload `Part`, `Parts`.
+- `spec/idml/part_spec.rb`
+- `spec/idml/parts/designmap_spec.rb`
+- `spec/idml/parts_spec.rb` — registry behavior.
+
+## Design notes
+
+- The pattern set by this TODO: one file per part class, one entry in the
+  `Parts` autoload list, the part class self-registers via `part_file`.
+- `Designmap` is the simplest part (single root `<Document>` with attributes
+  and several child element collections). Good first model.
+- Use `ordered` in the `xml do` block — IDML child order is semantically
+  meaningful throughout the spec.
+- The IDML namespace on the root (`xmlns:idPkg="..."`) is per-schema; preserve
+  it via `namespace` directive in lutaml-model.
+- For attributes whose Ruby name differs from XML name (e.g. `Self` →
+  `:self_attr`), use `map_attribute "Self", to: :self_attr`. Avoid shadowing
+  Ruby's `self` keyword.
+- For the registry: use a hash of `Regexp => Class`. `class_for` does
+  linear find — the registry is small (~12 entries), no perf concern.
+
+## Dependencies
+
+- TODO 01, TODO 02.

data/TODO.complete/04-spread-and-master-spread.md

@@ -0,0 +1,57 @@
+# TODO 04: Spread + MasterSpread models
+
+## Goal
+
+Model the two spread-flavored parts. These are the largest and most
+structurally diverse parts (Spread.rnc is 4,430 lines).
+
+## Acceptance criteria
+
+- [ ] `Idml::Parts::Spread` parses `<idPkg:Spread>` (root) with all attributes
+      and child element collections from the RNG.
+- [ ] `Idml::Parts::MasterSpread` parses `<idPkg:MasterSpread>` similarly.
+      Subclass or sibling — decide based on RNG divergence (likely sibling;
+      they have different attribute sets).
+- [ ] Element classes nested under `Idml::Spread::*`:
+      `Rectangle`, `Polygon`, `GraphicLine`, `TextFrame`, `Group`, `Page`,
+      `Image`, `EPS`, `PDF`, `Movie`, `Sound`, `Media`, `HTMLItem`, `EPS`,
+      `Page`, plus their child elements (`Properties`, `Path`, `TextFrame`,
+      etc.).
+- [ ] `Package.spreads` returns an Array of `Spread` instances (one per
+      `Spreads/Spread_*.xml`). `Package.master_spreads` similar.
+- [ ] `Package.part("Spreads/Spread_ud1.xml")` returns a `Spread` instance.
+- [ ] Round-trip spec: parse → serialize → XML-equivalent, per the fixture's
+      two spreads.
+- [ ] Attribute-set spec: each element class declares the RNG-listed attribute
+      set.
+
+## Files
+
+- `lib/idml/parts/spread.rb` — root + nested element classes.
+- `lib/idml/parts/master_spread.rb`
+- `lib/idml/parts.rb` — autoload spread/master_spread.
+- `lib/idml/package.rb` — convenience accessors `spreads`, `master_spreads`.
+- `spec/idml/parts/spread_spec.rb`
+- `spec/idml/parts/master_spread_spec.rb`
+
+## Design notes
+
+- Spread is the most attribute-dense element in IDML. The RNG defines
+  hundreds of attributes (most optional). Use a systematic approach:
+  - Group attributes by category (geometry, styling, transitions, etc.) in
+    the model file. Visual grouping only — the XML output is order-independent
+    for attributes.
+  - Mark optional attributes with the `:` default pattern (`attribute :foo,
+    :string, default: nil` or omit default if lutaml-model handles optional).
+- Child element order matters (z-order in spread). Use `ordered` on root.
+- For elements that may appear many times in any order (Page items: Rectangle,
+  TextFrame, Polygon, etc.), `map_element` each one with `collection: true`.
+- MasterSpread is structurally similar but not identical. Read its RNG
+  carefully and don't subclass unless the attribute sets truly nest.
+- `Self` attributes are unique IDs; model as `:string`. Cross-references via
+  `ParentStory`, `FillColor`, etc. are also strings (we don't resolve them at
+  the model layer; resolution is a Document-layer concern, TODO 10+).
+
+## Dependencies
+
+- TODO 03 (registry pattern).

data/TODO.complete/05-story-and-backing-story.md

@@ -0,0 +1,56 @@
+# TODO 05: Story + BackingStory models
+
+## Goal
+
+Model the two story-flavored parts. Stories carry text flow content;
+BackingStory is the root of the logical XML tree.
+
+## Acceptance criteria
+
+- [ ] `Idml::Parts::Story` parses `<idPkg:Story>` with all RNG-declared
+      attributes and child elements.
+- [ ] `Idml::Parts::BackingStory` parses `<XmlStory>` (BackingStory.xml's
+      root element). Sibling class, not subclass.
+- [ ] Element classes nested under `Idml::Story::*`:
+      `ParagraphStyleRange` (`ParagraphStyleRange`), `CharacterStyleRange`
+      (`CharacterStyleRange`), `Content` (`Content`), `XMLElement`
+      (`XMLElement`), `SpecialCharacter`, `DiscretionaryHyphen`, `Footnote`,
+      `Gaiji`, `HiddenText`, `VariableInstance`, `Table`, `Cell`, `Attributes`
+      (XMLElement attrs).
+- [ ] `Package.stories` returns Array of `Story` instances.
+- [ ] `Package.backing_story` returns the single `BackingStory` instance.
+- [ ] Convenience: `story.text` returns the concatenated plain-text content
+      of all `Content` runs.
+- [ ] Round-trip spec per fixture story (4 of them) and the BackingStory.
+
+## Files
+
+- `lib/idml/parts/story.rb`
+- `lib/idml/parts/backing_story.rb`
+- `lib/idml/parts.rb` — autoload both.
+- `lib/idml/package.rb` — `stories`, `backing_story` accessors.
+- `spec/idml/parts/story_spec.rb`
+- `spec/idml/parts/backing_story_spec.rb`
+
+## Design notes
+
+- Stories are where IDML gets hairy: deeply nested runs with mixed content
+  (text + child elements). Use `ordered` everywhere.
+- `ParagraphStyleRange` (`<ParagraphStyleRange>`) wraps block-level text;
+  `CharacterStyleRange` (`<CharacterStyleRange>`) wraps inline runs. Both can
+  contain `Content` (text), `XMLElement` (XML structure tag), and special
+  characters (`<SpecialCharacter>`).
+- `Content` element is mixed-content: has text content AND an attribute
+  `XMLElement` reference. Use `map_content` + `map_attribute`.
+- `story.text` is a derived convenience; the model itself preserves structure.
+  Implement as an iteration over the content tree.
+- XMLElement is the bridge to the logical XML structure (tags applied in
+  InDesign's Structure panel). Preserve its `MarkupTag` attribute — that's
+  the connection to Tags.xml.
+- `BackingStory` is the root of the XML structure tree. Its `XMLElement`
+  children mirror the InDesign document's logical structure. Distinct enough
+  from `Story` to warrant a sibling class.
+
+## Dependencies
+
+- TODO 03.

data/TODO.complete/06-resources.md

@@ -0,0 +1,53 @@
+# TODO 06: Resources models (Fonts, Graphic, Style, StyleMapping, Preferences)
+
+## Goal
+
+Model the five Resources parts.
+
+## Acceptance criteria
+
+- [ ] `Idml::Parts::Fonts` parses `<idPkg:Fonts>` root with `FontFamily` and
+      `Font` collections.
+- [ ] `Idml::Parts::Graphic` parses `<idPkg:Graphic>` root with `Color`,
+      `ColorGroup`, `FlattenerCustomSettings`, `Tracking`, `Tint`, `MixedInk`,
+      `MixedInkGroup`, `Gradient`, `StrokeStyle` collections per RNG.
+- [ ] `Idml::Parts::Style` parses `<idPkg:Style>` root with `RootCharacterStyleGroup`,
+      `RootParagraphStyleGroup`, `RootCellStyleGroup`, `RootTableStyleGroup`,
+      `RootObjectStyleGroup`, plus their style children.
+- [ ] `Idml::Parts::StyleMapping` parses `<idPkg:StyleMapping>` with
+      `ImportXmlElementToStyleMap`, `ImportXmlElementToInlineStoryMap`,
+      `ExportXmlTagToStyleMap` collections.
+- [ ] `Idml::Parts::Preferences` parses `<idPkg:Preferences>` with its many
+      child collections (`AdobePageMatch`, `Application`, `DocumentPreference`,
+      `DisplayPerformancePreference`, etc. — list per RNG).
+- [ ] `Package.fonts`, `Package.graphic`, `Package.style`,
+      `Package.style_mapping`, `Package.preferences` accessors.
+- [ ] Round-trip spec for each part using fixture data.
+
+## Files
+
+- `lib/idml/parts/fonts.rb`
+- `lib/idml/parts/graphic.rb`
+- `lib/idml/parts/style.rb`
+- `lib/idml/parts/style_mapping.rb`
+- `lib/idml/parts/preferences.rb`
+- `lib/idml/parts.rb` — autoload all five.
+- `lib/idml/package.rb` — accessors.
+- `spec/idml/parts/{fonts,graphic,style,style_mapping,preferences}_spec.rb`
+
+## Design notes
+
+- These parts are large but structurally regular: root + collections of
+  similar children. Pattern is repeatable across the five.
+- Preferences is the biggest (1,827 RNG lines). Don't try to model every
+  nested preference; model the top-level child collections and let inner
+  content round-trip via nested element classes.
+- Styles have nested groups (style groups contain styles). Build out the
+  nested class tree.
+- For long-tail elements (rare style options, obscure preferences), use
+  typed mapping where the RNG gives a clear type, `:string` for opaque
+  enums. Mark attribute-set assertions to match what we model.
+
+## Dependencies
+
+- TODO 03.

data/TODO.complete/07-xml-structure.md

@@ -0,0 +1,32 @@
+# TODO 07: XML structure models (Tags, Mapping)
+
+## Goal
+
+Model the two small XML/ parts.
+
+## Acceptance criteria
+
+- [ ] `Idml::Parts::Tags` parses `<idPkg:Tags>` root with `XMLTag` collection.
+- [ ] `Idml::Parts::Mapping` parses `<idPkg:Mapping>` root with `XMLImportMap`
+      collection.
+- [ ] `Package.tags`, `Package.mapping` accessors.
+- [ ] Round-trip spec per fixture.
+
+## Files
+
+- `lib/idml/parts/tags.rb`
+- `lib/idml/parts/mapping.rb`
+- `lib/idml/parts.rb` — autoload both.
+- `lib/idml/package.rb` — accessors.
+- `spec/idml/parts/{tags,mapping}_spec.rb`
+
+## Design notes
+
+- These are the smallest parts. Good for closing out the part layer with a
+  quick win after the large TODO 04–06 work.
+- `XMLTag` has `Self`, `Name`, `TagColor` attributes — straightforward.
+- `XMLImportMap` has `MarkupTag`, `MappedStyle` — also straightforward.
+
+## Dependencies
+
+- TODO 03.