libpng 1.6.58.2 → 1.6.58.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd40beeea8a0333bc4f83c461da33eec3bb0ffdcf9982dc289efab87da554d17
-  data.tar.gz: d9d837770569d6fdc083d2d074138679c70b43eeac8f666f906fb44f053ec2ef
+  metadata.gz: b8e15eabb884474f99879a934d6472eba94e686b19dd734f87a6ab80b7f815d2
+  data.tar.gz: 511877de0b69d9813a7eec8ea2d5e25ab932a32a9edf89139ac8a5e635adf426
 SHA512:
-  metadata.gz: 621b7892d277ccdb0ab0535c38ee69c11b9e4b866e05ec7ef7248fd1df9bc4aa6f5a81a5b560eb67a6491ce00c76f853c3e7d3014273890d2dc9a11b76beb1a6
-  data.tar.gz: ec661e92e1f7c8b3ddeae8c2b43dc5ff9795ae2ee5aa34b344887134c605e54513b41209e19df74bc04d3bc4e63ed2524202b153841a724a98b48944515276e6
+  metadata.gz: 1bdb8b75f3ca27c415793d03ba234b18e63a155266e1f187012866eceda8c3e40b5409375a3045a1686ea6c3bed527c8d8be710aeb2a68483f362273c5bf467e
+  data.tar.gz: ae9cf74ed74fc27bf55ddc92a4a50b2cd347a0319e3d8eb6821e2456a7dd762e062061b7a208708ef358161251b7ae488f80a46aa783effe85b164280f49f036

data/.rubocop.yml

@@ -22,7 +22,7 @@ Metrics/ModuleLength:
 Metrics/PerceivedComplexity:
   Max: 20
 Metrics/ParameterLists:
-  Max: 7
+  Max: 9
 
 Metrics/BlockLength:
   Exclude:

data/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+All notable changes to the `libpng` Ruby gem are documented here.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+This gem follows a `{LIBPNG_VERSION}.{LIBPNG_RUBY_ITERATION}` version
+scheme. `LIBPNG_VERSION` is the upstream libpng release; `ITERATION`
+bumps for Ruby-side changes and resets to 0 when LIBPNG_VERSION bumps.
+
+## [1.6.58.3] - 2026-07-26
+
+### Added
+- `Libpng.encode_standard` -- standard libpng write API
+  (`png_create_write_struct` -> `png_set_IHDR` -> `png_set_rows` ->
+  `png_write_png(PNG_TRANSFORM_IDENTITY)`). Mirrors libemf2svg's
+  `rgb2png` byte layout and emits only IHDR/IDAT/IEND directly (no
+  post-hoc chunk stripping).
+- `interlace:` option on `encode_standard` -- `:none` (default) or
+  `:adam7`.
+- `bit_depth:` option on `encode_standard` -- 8 (default) or 16 for
+  RGB/RGBA/GRAY.
+- `pixel_format: :palette` with `palette:` option on `encode_standard` --
+  emits PNG_COLOR_TYPE_PALETTE via `png_set_PLTE` (and `png_set_tRNS`
+  when any palette entry has alpha).
+- `Libpng::DecodedImage#bit_depth`, `#color_type`, `#interlace` -- IHDR
+  metadata fields populated by walking the source PNG after decode.
+- `Libpng::ChunkWalker` -- public class for walking PNG chunks:
+  `#each_chunk`, `#strip_ancillary`, `#ihdr_fields`.
+- `Libpng::BytesPerPixel` -- pure-data helper module mapping formats
+  and color types to bytes-per-pixel (8- and 16-bit aware).
+- Architecture refactor: split the monolithic `lib/libpng.rb` (466
+  lines) into MECE per-concern files using Ruby `autoload`. New files:
+  `lib/libpng/error.rb`, `decoded_image.rb`, `chunk_walker.rb`,
+  `bytes_per_pixel.rb`, `simplified_encoder.rb`,
+  `simplified_decoder.rb`, `standard_encoder.rb`. Public API
+  unchanged.
+- Specs: malformed-input suite, encode_standard Ractor suite,
+  benchmark suite, options suite for interlace/bit_depth/palette,
+  metadata suite for DecodedImage + ChunkWalker.
+
+### Changed
+- `mini_portile2` dependency bumped from `~> 2.6` to `~> 2.8`.
+- Removed all `require_relative` from library code in favor of
+  `autoload` (per project code-quality rules).
+- `ext/extconf.rb` now triggers `Libpng::Recipe` autoload via
+  `require 'libpng'` instead of reaching into `lib/libpng/recipe.rb`
+  directly.
+
+### Fixed
+- Filter option documentation: clarified that `:default`, `:adaptive`,
+  and `:all` produce byte-identical output but exercise different
+  libpng code paths. `:none` forces no filtering.
+- Removed redundant `.dup.freeze` on `LIBPNG_VER_STRING_C` (the source
+  string is already a frozen literal).
+
+## [1.6.58.2] - 2026-07-26
+
+### Added
+- `Libpng.encode_standard` initial release -- standard libpng write
+  API with memory-stream output via `png_set_write_fn` FFI callback
+  (no Tempfile), filter control, compression level control, and error
+  handling via `png_set_error_fn` callback.
+- Specs: 32 specs covering encode_standard round-trips, filter
+  variants, compression levels, chunk-layout assertions, parity check
+  against simplified `encode`.
+
+## [1.6.58.1] - 2026-07-25
+
+### Added
+- Full platform coverage: `aarch64-linux-musl`, `aarch64-linux` (native
+  on `ubuntu-24.04-arm`), `aarch64-mingw-ucrt` (native on
+  `windows-11-arm`), `x86_64-linux-musl` (Alpine via `docker run`).
+- `step-security/msvc-dev-cmd@v1` replaces deleted `ilammy/msvc-dev-tools`
+  action.
+- Release workflow tolerates already-published gems (skip-on-conflict).
+- Specs: Ractor safety suite for `encode` and `decode` (Ruby 3.x and 4.0).
+
+### Fixed
+- `ext/extconf.rb` now emits a dummy Makefile so RubyGems is satisfied
+  when installing the source (`ruby` platform) gem.
+- Recipe globs `{bin,lib}/libpng16*.dll` on Windows (CMake's
+  GNUInstallDirs puts the .dll in `bin/`, not `lib/`).
+- Alpine build runs inside `docker run` (not the `container:` field)
+  so it works on arm64 Ubuntu runners.
+- `git config --global --add safe.directory /work` in Alpine container
+  so `git ls-files` works for the gemspec.
+
+## [1.6.58.0] - 2026-07-25
+
+### Added
+- Initial pre-compiled libpng gem. Bundles libpng 1.6.58 shared
+  libraries for x86_64 Linux, x86_64 macOS, arm64 macOS, x64 Windows
+  (MSVCRT and UCRT).
+- `Libpng.encode` / `Libpng.decode` -- simplified API binding via FFI.
+- `strip_colorspace:` option on `encode` to drop sRGB/gAMA chunks the
+  simplified API emits by default.
+- `convert_to_8bit:` option on `encode` for 16-bit input.
+- MiniPortile-based recipe for building libpng from source when
+  installing the platform-agnostic `ruby` gem.

data/CLAUDE.md

@@ -0,0 +1,109 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+`libpng` is a Ruby gem that wraps the official libpng shared library via FFI. The native `libpng16.{so,dylib,dll}` is **pre-compiled per target platform and shipped inside the gem** — `gem install libpng` must not require a C compiler on the host.
+
+10 platform gems are published per release (see README for the full matrix).
+
+## Architecture
+
+The library is split into MECE per-concern files under `lib/libpng/`,
+loaded via `autoload` from `lib/libpng.rb`. **Never use `require_relative`
+(or `require` with a path) for internal library code** — add an
+`autoload` entry to `lib/libpng.rb` instead.
+
+| File | Responsibility |
+|---|---|
+| `lib/libpng.rb` | Module + FFI setup + constants + public dispatch (`encode`/`decode`/`encode_standard`) + autoloads |
+| `lib/libpng/version.rb` | `LIBPNG_VERSION`, `LIBPNG_RUBY_ITERATION`, `VERSION` |
+| `lib/libpng/error.rb` | `Libpng::Error` |
+| `lib/libpng/decoded_image.rb` | `Libpng::DecodedImage` (Struct returned by `decode`) |
+| `lib/libpng/chunk_walker.rb` | `Libpng::ChunkWalker` (walk/strip/extract metadata from PNG bytes) |
+| `lib/libpng/bytes_per_pixel.rb` | `Libpng::BytesPerPixel` (pure-data lookup) |
+| `lib/libpng/simplified_encoder.rb` | `Libpng::SimplifiedEncoder` (libpng simplified write API) |
+| `lib/libpng/simplified_decoder.rb` | `Libpng::SimplifiedDecoder` (libpng simplified read API + IHDR metadata) |
+| `lib/libpng/standard_encoder.rb` | `Libpng::StandardEncoder` (libpng standard write API with filter/compression/interlace/bit_depth/palette options) |
+| `lib/libpng/recipe.rb` | `Libpng::Recipe < MiniPortileCMake` (builds libpng from source for the source gem) |
+| `ext/extconf.rb` | Gem extension entry. Triggers `Libpng::Recipe` autoload via `require 'libpng'`, then emits a dummy Makefile |
+
+### Public API
+
+```ruby
+Libpng.encode(width, height, pixels, pixel_format:, convert_to_8bit:, strip_colorspace:)
+Libpng.encode_standard(width, height, pixels, pixel_format:, filter:, compression_level:, interlace:, bit_depth:, palette:)
+Libpng.decode(png, pixel_format:)
+```
+
+Each is a thin dispatcher that constructs a dedicated encoder/decoder instance and calls `#call`. The instance is discarded after the call (per-call state, Ractor-safe).
+
+### FFI binding
+
+`Libpng` extends `FFI::Library` and attaches:
+- 4 simplified-API functions (`png_image_*`)
+- 10 standard-API functions (`png_create_write_struct`, `png_set_IHDR`, `png_set_PLTE`, `png_set_tRNS`, `png_set_filter`, `png_set_compression_level`, `png_set_write_fn`, `png_write_png`, `png_set_rows`, `png_destroy_write_struct`, `png_create_info_struct`)
+
+FFI calls inside encoder classes use the qualified form: `Libpng.png_set_IHDR(...)`. The function table is set up once at module load and is shareable across Ractors.
+
+### Ractor safety
+
+Every encoder/decoder allocates its own `png_image` (simplified API) or `png_struct` (standard API) per call. No shared mutable state on the Ruby side. The Ractor specs in `spec/ractor_spec.rb` and `spec/ractor_standard_spec.rb` verify this across Ruby 3.3, 3.4, and 4.0.
+
+Ruby 4.0 removed `Ractor#take`; use the helper `ractor_result(r)` which prefers `#value` (4.0+) and falls back to `#take` (3.x).
+
+## Common commands
+
+```sh
+bundle install
+bundle exec rake compile         # build libpng via MiniPortile (needs cmake + zlib)
+bundle exec rake spec            # all specs (~81 examples)
+bundle exec rspec spec/libpng_spec.rb:17   # single spec by line
+bundle exec rake rubocop
+bundle exec rake                 # default: spec + rubocop
+
+bundle exec rake gem:native:arm64-darwin    # build a pre-compiled gem
+bundle exec rake gem:native:any             # source gem (compiles on install)
+```
+
+Platform gem tasks: `x64-mingw32`, `x64-mingw-ucrt`, `aarch64-mingw-ucrt`, `x86_64-linux`, `x86_64-linux-musl`, `aarch64-linux`, `aarch64-linux-musl`, `x86_64-darwin`, `arm64-darwin`.
+
+## Release process
+
+Releases are tag-triggered via `.github/workflows/release.yml`. Trigger with:
+
+```sh
+gh workflow run release.yml --repo claricle/libpng-ruby --ref main -f bump-type=iteration
+# or: -f bump-type=libpng -f libpng-version=1.6.59
+# or: -f bump-type=current  # release current VERSION as-is
+```
+
+The workflow bumps `lib/libpng/version.rb`, pushes a `v*` tag, builds all 10 platform gems, and publishes to RubyGems via OIDC Trusted Publishing.
+
+**Never** push tags or merge to main directly — always go through PRs.
+
+## Code quality rules (project-wide)
+
+- **Never** `require_relative` for internal library code — use `autoload`.
+- **Never** `send` to call private methods. Redesign the API boundary instead.
+- **Never** `instance_variable_set`/`get` across objects.
+- **Never** `respond_to?` for type checks — use `is_a?` or design the type hierarchy so the check isn't needed.
+- **DRY / MECE / OCP**: each concern lives in exactly one file. New pixel format = add to `FORMAT_BY_NAME` + `COLOR_TYPE_BY_FORMAT` + `BytesPerPixel` (and `FORMAT_TO_COLOR_TYPE` if standard-API).
+
+## Specs
+
+- `spec/libpng_spec.rb` — `encode`/`decode` simplified API
+- `spec/libpng_standard_spec.rb` — `encode_standard` core
+- `spec/standard_encoder_options_spec.rb` — `interlace:`/`bit_depth:`/`palette:` options
+- `spec/decoded_image_metadata_spec.rb` — IHDR metadata + `ChunkWalker`
+- `spec/malformed_input_spec.rb` — corrupt PNG input handling
+- `spec/ractor_spec.rb` — Ractor safety for simplified API
+- `spec/ractor_standard_spec.rb` — Ractor safety for standard API
+- `spec/benchmark_spec.rb` — encode/decode timing comparison
+
+## See also
+
+- `TODO.roadmap/` — prioritized backlog with status (done/planned/wontdo) per item
+- `CHANGELOG.md` — release history
+- `REPORT-complex-api-needs.md` — historical report that drove `encode_standard`

data/README.adoc

@@ -60,10 +60,13 @@ for the current set):
 
   # Decode a PNG into raw pixels.
   decoded = Libpng.decode(File.binread("out.png"), pixel_format: "RGBA")
-  decoded.width   # => Integer
-  decoded.height  # => Integer
-  decoded.format  # => "RGBA"
-  decoded.pixels  # => binary String of RGBA bytes
+  decoded.width       # => Integer
+  decoded.height      # => Integer
+  decoded.format      # => "RGBA"
+  decoded.pixels      # => binary String of RGBA bytes
+  decoded.bit_depth   # => 8 (from IHDR)
+  decoded.color_type  # => 6 (PNG_COLOR_TYPE_RGB_ALPHA, from IHDR)
+  decoded.interlace   # => 0 (PNG_INTERLACE_NONE, from IHDR)
 
 === Supported pixel formats
 
@@ -94,33 +97,47 @@ output. Set to `false` to keep the ancillary color chunks.
 For parity with libpng's classic write path -- the same code path used
 by `libemf2svg`'s `rgb2png` -- use `encode_standard` instead of
 `encode`. It calls `png_create_write_struct` + `png_set_IHDR` +
-`png_set_rows` + `png_write_png(PNG_TRANSFORM_IDENTITY)` directly, with
-filter and zlib-compression control exposed:
+`png_set_rows` + `png_write_png(PNG_TRANSFORM_IDENTITY)` directly.
 
   Libpng.encode_standard(width, height, pixels,
                          pixel_format: "RGBA",
                          filter: :default,
-                         compression_level: 6)
+                         compression_level: 6,
+                         interlace: :none,
+                         bit_depth: 8,
+                         palette: nil)
 
-`pixel_format`:: `GRAY`, `GA`, `RGB`, or `RGBA` only. The byte-order
-variants (`BGR`, `ARGB`, `BGRA`, `ABGR`) are simplified-API only --
-the standard API always emits host-order.
+`pixel_format`:: `:gray`, `:ga`, `:rgb`, `:rgba`, or `:palette`. The
+byte-order variants (`BGR`, `ARGB`, `BGRA`, `ABGR`) are simplified-API
+only -- the standard API always emits host-order.
 
-`filter`:: One of `:default` (adaptive -- libpng picks the best filter
-per row, the libemf2svg default), `:adaptive` (same), `:none`, `:sub`,
-`:up`, `:avg`, `:paeth`, or `:all`.
+`filter`:: `:default` (adaptive -- libpng picks the best filter per
+row, the libemf2svg default), `:adaptive` (same output, exercises a
+different libpng code path), `:none`, `:sub`, `:up`, `:avg`, `:paeth`,
+`:all`.
 
 `compression_level`:: zlib level 0-9. Default 6 (Z_DEFAULT_COMPRESSION,
 matching libemf2svg).
 
+`interlace`:: `:none` (default) or `:adam7`.
+
+`bit_depth`:: 8 (default) or 16. Only valid for `:gray`, `:rgb`,
+`:rgba`. 16-bit callers must provide 2 bytes per channel
+(host-order little-endian). Always 8 for `:palette`.
+
+`palette`:: Array of `[r, g, b]` or `[r, g, b, a]` (1..256 entries).
+Required when `pixel_format: :palette`. If any entry has alpha, a `tRNS`
+chunk is emitted.
+
 Output is written directly into a Ruby String via `png_set_write_fn` --
 no `Tempfile`, no disk I/O. The FFI write callback is held on a local
-Array so it survives the libpng calls.
+`Array` so it survives the libpng calls.
 
 Differences from `encode`:
 - Emits only `IHDR` / `IDAT` / `IEND` (no post-hoc chunk stripping
   needed).
-- Standard API only -- no `convert_to_8bit` option.
+- Supports palette, 16-bit, and interlaced output -- simplified API
+  doesn't.
 - Errors are raised via a `png_set_error_fn` callback (set on
   `png_create_write_struct`). libpng expects error callbacks to
   longjmp; we rb_raise instead, which unwinds the Ruby stack. The

data/TODO.roadmap/01-claude-md-update.md

@@ -0,0 +1,27 @@
+# 01 - CLAUDE.md update
+
+- **Priority**: P0
+- **Status**: Done
+
+## Context
+
+The agent-facing `CLAUDE.md` was out of sync after `encode_standard`,
+the platform matrix expansion, and the architecture refactor. Future
+Claude instances would land in a codebase that no longer matched the
+documented structure.
+
+## Approach
+
+Re-created `CLAUDE.md` with:
+- File-responsibility table for the new autoloaded structure
+- Public API surface (encode / encode_standard / decode) with options
+- FFI binding inventory (simplified + standard APIs)
+- Ractor safety section including the Ruby 4.0 `#value` migration
+- Code quality rules (no `require_relative`, no `send`, no `iv_get`,
+  no `respond_to?` -- the project-wide rules)
+- Spec inventory
+- Cross-links to `TODO.roadmap/`, `CHANGELOG.md`, `REPORT-complex-api-needs.md`
+
+## Delivered
+
+PR #7 (this branch).

data/TODO.roadmap/02-encode-standard-ractor-spec.md

@@ -0,0 +1,24 @@
+# 02 - encode_standard Ractor spec
+
+- **Priority**: P0
+- **Status**: Done
+
+## Context
+
+PR #6 added `encode_standard` and claimed Ractor safety (every call
+allocates its own `png_struct`), but only `encode` and `decode` had
+Ractor specs. Unverified claims are worse than no claims.
+
+## Approach
+
+New spec file `spec/ractor_standard_spec.rb` with two cases:
+1. Encode inside a Ractor, round-trip the bytes in the main Ractor.
+2. 8 concurrent Ractors running `encode_standard(filter: :sub)` and
+   verifying decode round-trip.
+
+Uses the `ractor_result(ractor)` helper (prefers `#value` on Ruby 4.0+,
+falls back to `#take` on Ruby 3.x).
+
+## Delivered
+
+PR #7 (this branch).

data/TODO.roadmap/03-mini-portile2-bump.md

@@ -0,0 +1,26 @@
+# 03 - Bump mini_portile2 dependency
+
+- **Priority**: P0
+- **Status**: Done
+
+## Context
+
+The gemspec constrained `mini_portile2` to `~> 2.6`. Current upstream
+is 2.8.9. The constraint prevented the source gem from picking up
+mini_portile2 bug fixes and CMake improvements.
+
+## Approach
+
+Bumped `libpng.gemspec`:
+
+```ruby
+spec.add_dependency 'mini_portile2', '~> 2.8'
+```
+
+Allowed versions 2.8.x. Did not jump to `>= 2.8` (unbounded) because
+mini_portile2 has had breaking changes between major versions in the
+past; staying on `~> 2.8` is the conservative choice.
+
+## Delivered
+
+PR #7 (this branch).

data/TODO.roadmap/04-changelog.md

@@ -0,0 +1,34 @@
+# 04 - CHANGELOG.md
+
+- **Priority**: P1
+- **Status**: Done
+
+## Context
+
+Release notes lived in PR descriptions and git tags -- invisible to
+users tracking what changed between versions. The README's
+`Versioning` section described the scheme but not what each release
+actually delivered.
+
+## Approach
+
+New `CHANGELOG.md` following the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+format. Retroactively populated with entries for every released
+version:
+
+- 1.6.58.0 -- initial release
+- 1.6.58.1 -- parsanol platform parity (musl, Windows ARM64, native arm64 runners)
+- 1.6.58.2 -- encode_standard initial release
+- 1.6.58.3 -- architecture refactor, encode_standard options
+  (interlace/bit_depth/palette), read-side metadata, autoload+OOP
+
+Each entry categorizes changes as Added / Changed / Fixed per Keep a
+Changelog conventions.
+
+The RubyGems `changelog_uri` metadata in `libpng.gemspec` already
+points at `README.adoc#versioning`. Future: should it point at
+`CHANGELOG.md` instead?
+
+## Delivered
+
+PR #7 (this branch).

data/TODO.roadmap/05-benchmarks.md

@@ -0,0 +1,41 @@
+# 05 - Benchmarks for encode paths
+
+- **Priority**: P1
+- **Status**: Done
+
+## Context
+
+`encode_standard` was claimed to be ~3x faster than the original
+Tempfile-based approach (per `REPORT-complex-api-needs.md`), but no
+benchmark existed to verify or catch regressions.
+
+## Approach
+
+New spec file `spec/benchmark_spec.rb`. Three image sizes (16x16,
+128x128, 512x512). For each:
+
+- `Libpng.encode` (simplified, strip_colorspace on)
+- `Libpng.encode_standard` (memory write)
+- `Libpng.decode` (simplified, RGBA)
+
+Measures median of 50 iterations using `Benchmark.realtime`. Prints
+comparable numbers via `warn` so they show in CI logs but don't affect
+test pass/fail.
+
+Sanity assertions (not timing-based):
+- Both PNGs start with `\x89PNG`
+- Standard PNG decodes to the same pixels
+
+Benchmarks are smoke tests, not performance gates. Specific timings
+vary by machine and CI runner load; gating on absolute numbers would
+be flaky.
+
+## Delivered
+
+PR #7 (this branch).
+
+## Future work
+
+- Add a `rake benchmark` task that runs only `spec/benchmark_spec.rb`
+- Track benchmark results across releases (maybe via GitHub Actions
+  artifacts) to spot performance regressions over time

data/TODO.roadmap/06-malformed-input-tests.md

@@ -0,0 +1,47 @@
+# 06 - Malformed input tests for decode
+
+- **Priority**: P1
+- **Status**: Done
+
+## Context
+
+The original spec covered "non-PNG input" and "truncated input" but
+not:
+- Empty / nil input
+- Corrupt IHDR CRC
+- Corrupt IDAT CRC
+- Zero-dimension IHDR
+- Impossibly large dimensions
+- PNG missing IEND
+- PNG truncated mid-IDAT
+
+libpng's simplified read API is well-behaved on bad input (captures
+errors into the `png_image` message buffer instead of aborting), but
+the wrapper should still raise `Libpng::Error` rather than propagate
+`NoMethodError` or segfault.
+
+## Approach
+
+New spec file `spec/malformed_input_spec.rb`. Each case constructs a
+broken PNG and asserts that `Libpng.decode` raises `Libpng::Error`
+(or, for borderline cases, doesn't crash).
+
+Helper methods on the spec:
+- `with_chunk(png, type, replacement_data)` -- splice replacement data
+  into a specific chunk
+- `corrupt_crc(png, type)` -- XOR the first CRC byte of a chunk
+
+## What we learned
+
+- `nil` input previously raised `NoMethodError: undefined method
+  'bytesize' for nil`. Fixed by adding a nil guard in
+  `Libpng::SimplifiedDecoder#initialize`.
+- Zero-dimension IHDR detection works (libpng rejects).
+- Corrupt IHDR CRC is detected by libpng and raises cleanly.
+- Corrupt IDAT CRC: libpng's simplified API may either error or
+  accept (zlib is sometimes able to decode despite the bad CRC). The
+  spec tolerates both outcomes.
+
+## Delivered
+
+PR #7 (this branch).

data/TODO.roadmap/07-interlace-option.md

@@ -0,0 +1,40 @@
+# 07 - interlace: option on encode_standard
+
+- **Priority**: P1
+- **Status**: Done
+
+## Context
+
+`encode_standard` hardcoded `INTERLACE_NONE`. Some use cases (progressive
+image loading for web) require Adam7 interlacing.
+
+## Approach
+
+New option on `Libpng::StandardEncoder`:
+
+```ruby
+interlace: :none | :adam7
+```
+
+Constants already defined in `lib/libpng.rb` (`INTERLACE_NONE`,
+`INTERLACE_ADAM7`). Added `INTERLACE_BY_NAME` lookup table for
+symbol-to-constant mapping.
+
+Validation: rejects unknown symbols with a clear error.
+
+Specs in `spec/standard_encoder_options_spec.rb`:
+- Default is `:none` (verify via IHDR walk)
+- `:adam7` produces IHDR with `interlace=INTERLACE_ADAM7`
+- Adam7 output is larger than :none for small images (per-pass
+  overhead exceeds compression savings)
+- Round-trips through `Libpng.decode` to the original pixels
+
+## Delivered
+
+PR #7 (this branch).
+
+## Why not also add to encode (simplified API)?
+
+libpng's simplified API doesn't expose interlace control -- it always
+emits non-interlaced PNGs. Adding it there would require a separate
+write path, which is what `encode_standard` already is.

data/TODO.roadmap/08-palette-support.md

@@ -0,0 +1,54 @@
+# 08 - Palette support
+
+- **Priority**: P2
+- **Status**: Done
+
+## Context
+
+Report item #6: `encode_standard` only supported direct-color formats
+(GRAY, GA, RGB, RGBA). Indexed-color images (1-bpp MONOPATTERN brushes
+in EMF, indexed-color sprites, simple icons) compress much better as
+`PNG_COLOR_TYPE_PALETTE` than as RGBA.
+
+## Approach
+
+New `pixel_format: :palette` mode on `Libpng::StandardEncoder`:
+
+```ruby
+Libpng.encode_standard(width, height, indices,
+                       pixel_format: :palette,
+                       palette: [[r, g, b], ...])  # or [r, g, b, a]
+```
+
+The encoder:
+1. Validates the palette (1..256 entries; each `[r,g,b]` or `[r,g,b,a]`
+   with 0..255 values).
+2. Always uses `bit_depth=8` for palette format (1/2/4-bit packed
+   indices are possible but require row stride juggling that's not
+   worth the complexity for v1).
+3. Calls `png_set_PLTE` with the RGB bytes.
+4. If any palette entry has alpha, calls `png_set_tRNS` with the alpha
+   values.
+
+New FFI bindings attached:
+- `png_set_PLTE` -- `[:pointer, :pointer, :pointer, :int], :void`
+- `png_set_tRNS` -- `[:pointer, :pointer, :pointer, :int, :pointer], :void`
+
+The tRNS 5th arg is `png_color_16p trans_color` -- pass NULL (nil).
+
+Specs verify:
+- Palette PNG round-trips via RGBA decode (each index expands to its
+  palette color)
+- Alpha entries are accepted
+- Missing palette, oversized palette, malformed entries all raise
+
+## Delivered
+
+PR #7 (this branch).
+
+## Future work
+
+- 1/2/4-bit packed palette indices for smaller files. Requires row
+  stride changes and is niche.
+- Palette extraction on decode (currently `decode` always expands
+  palette to RGBA/RGB).

data/TODO.roadmap/09-16-bit-encode.md

@@ -0,0 +1,53 @@
+# 09 - 16-bit encode support
+
+- **Priority**: P2
+- **Status**: Done
+
+## Context
+
+`encode_standard` hardcoded `bit_depth=8`. Some scientific imaging and
+photography workflows require 16-bit per channel for higher dynamic
+range.
+
+## Approach
+
+New option on `Libpng::StandardEncoder`:
+
+```ruby
+bit_depth: 8 | 16
+```
+
+The encoder:
+1. Validates `bit_depth` is 8 or 16 (or 8 only for `:ga` / `:palette`).
+2. Passes the bit_depth to `png_set_IHDR`.
+3. Computes `stride = width * channels * (bit_depth == 16 ? 2 : 1)`
+   via `Libpng::BytesPerPixel.for_color_type(color_type, bit_depth:)`.
+
+Caller is responsible for providing 2 bytes per channel
+(host-order little-endian on x86/arm -- the typical convention).
+
+## New helper
+
+`Libpng::BytesPerPixel.for_color_type(color_type, bit_depth: 8)` --
+maps a `PNG_COLOR_TYPE_*` plus bit depth to bytes per pixel. Uses the
+`CHANNELS_BY_COLOR_TYPE` table and `CHANNEL_BYTES_8_BIT` /
+`CHANNEL_BYTES_16_BIT` constants.
+
+## Specs
+
+- bit_depth: 8 (default) -- verify IHDR
+- bit_depth: 16 -- verify IHDR has bit_depth=16
+- bit_depth: 16 with palette format -- reject (palette is always 8)
+- bit_depth: 12 -- reject (only 8 and 16 supported)
+
+## Delivered
+
+PR #7 (this branch).
+
+## Future work
+
+- `convert_to_16bit:` on `encode` (simplified API) -- currently only
+  `convert_to_8bit:` exists.
+- 16-bit decode: `decode` currently always produces 8-bit output even
+  when the source PNG is 16-bit. This is libpng's simplified API
+  behavior.