libpng 1.6.58.1 → 1.6.58.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91ec3180573925adf91a3fb1463a008d05a113f633ca4a4dcd00546008585699
-  data.tar.gz: 34cc29c477d3bd9939067304ef3fc21357b773df42022bf16c6ef52323f25c5b
+  metadata.gz: b8e15eabb884474f99879a934d6472eba94e686b19dd734f87a6ab80b7f815d2
+  data.tar.gz: 511877de0b69d9813a7eec8ea2d5e25ab932a32a9edf89139ac8a5e635adf426
 SHA512:
-  metadata.gz: 4489b62efba7933a588fabafd4d0cb65122a77d0a363a476a80db1e726affcffbe70a02ac7783b916b867d59ad9a0f6ebd1319d12421a3ab65e74d92822e143c
-  data.tar.gz: 34042f2512c7234881c36bbcb140b283f267288d7b0575a71131773a681419f5542b9419de40355a5190050f9415b0081af3396e7115153fb6026575b58d5415
+  metadata.gz: 1bdb8b75f3ca27c415793d03ba234b18e63a155266e1f187012866eceda8c3e40b5409375a3045a1686ea6c3bed527c8d8be710aeb2a68483f362273c5bf467e
+  data.tar.gz: ae9cf74ed74fc27bf55ddc92a4a50b2cd347a0319e3d8eb6821e2456a7dd762e062061b7a208708ef358161251b7ae488f80a46aa783effe85b164280f49f036

data/.rubocop.yml

@@ -10,19 +10,19 @@ Gemspec/DevelopmentDependencies:
 # methods that walk libpng's chunked API; splitting would obscure the
 # 1-to-1 mapping with the C API.
 Metrics/AbcSize:
-  Max: 60
+  Max: 70
 Metrics/ClassLength:
   Max: 200
 Metrics/CyclomaticComplexity:
   Max: 20
 Metrics/MethodLength:
-  Max: 50
+  Max: 70
 Metrics/ModuleLength:
-  Max: 250
+  Max: 350
 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

@@ -22,9 +22,33 @@ Or install manually:
 
   gem install libpng
 
-The gem downloads a pre-compiled binary for your platform automatically.
-No C compiler, libpng development headers, or system packages are needed
-at install time.
+RubyGems automatically selects the pre-compiled gem that matches your
+platform. No C compiler, libpng development headers, or system packages
+are required at install time when a binary gem is available. The
+platform-agnostic `ruby` gem is the fallback: it downloads the libpng
+source tarball at install time and compiles it via CMake (requires
+`cmake`, `ninja`, and zlib headers).
+
+== Supported platforms
+
+The following pre-compiled platform gems are published for each release
+(see the link:https://rubygems.org/gems/libpng/versions[RubyGems versions page]
+for the current set):
+
+[cols="1,1,3", options="header"]
+|===
+| Gem platform | Target | Build host
+| `ruby` (source) | Any platform (compiles on install) | n/a
+| `x86_64-linux` | x86_64 Linux (glibc) | `ubuntu-latest`
+| `x86_64-linux-musl` | x86_64 Linux (musl, e.g. Alpine) | `ruby:<ver>-alpine` on x86_64
+| `aarch64-linux` | ARM64 Linux (glibc) | `ubuntu-24.04-arm` (native)
+| `aarch64-linux-musl` | ARM64 Linux (musl) | `ruby:<ver>-alpine` on arm64
+| `x64-mingw32` | x64 Windows, RubyInstaller < 3.0 (MSVCRT) | `windows-latest`
+| `x64-mingw-ucrt` | x64 Windows, RubyInstaller >= 3.0 (UCRT) | `windows-latest`
+| `aarch64-mingw-ucrt` | ARM64 Windows (Ruby >= 3.4) | `windows-11-arm` (native)
+| `x86_64-darwin` | Intel macOS | `macos-15-intel`
+| `arm64-darwin` | Apple Silicon macOS | `macos-latest`
+|===
 
 == Usage
 
@@ -36,10 +60,13 @@ at install time.
 
   # 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
 
@@ -52,12 +79,71 @@ at install time.
 
   Libpng.encode(width, height, pixels,
                 pixel_format: "RGBA",
-                convert_to_8bit: false)
+                convert_to_8bit: false,
+                strip_colorspace: true)
 
-`convert_to_8bit: true` causes libpng to convert 16-bit input to 8-bit
+`convert_to_8bit: true`:: causes libpng to convert 16-bit input to 8-bit
 on write (input is still passed as a packed byte buffer; use this if you
 have packed 16-bit-per-channel data).
 
+`strip_colorspace: true`:: (default) walks the PNG chunk list after
+encode and keeps only `IHDR`, `IDAT`, and `IEND`, dropping the sRGB/gAMA
+chunks libpng's simplified API emits by default. This matches the
+"classic" libpng write path (e.g. libemf2svg) and produces byte-identical
+output. Set to `false` to keep the ancillary color chunks.
+
+=== Standard API (encode_standard)
+
+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.
+
+  Libpng.encode_standard(width, height, pixels,
+                         pixel_format: "RGBA",
+                         filter: :default,
+                         compression_level: 6,
+                         interlace: :none,
+                         bit_depth: 8,
+                         palette: nil)
+
+`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`:: `: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.
+
+Differences from `encode`:
+- Emits only `IHDR` / `IDAT` / `IEND` (no post-hoc chunk stripping
+  needed).
+- 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
+  `ensure` block calls `png_destroy_write_struct` to release the C
+  state.
+
 == Ractor safety
 
 `Libpng.encode` and `Libpng.decode` are Ractor-safe. Every call
@@ -65,25 +151,26 @@ allocates and frees its own libpng `png_image`; no shared mutable state
 exists on the Ruby side. Calls from multiple Ractors run concurrently
 without locking.
 
-Example:
+Example (Ruby 3.x uses `Ractor#take`; Ruby 4.0+ uses `Ractor#value`):
 
   r = Ractor.new do
     Libpng.encode(2, 2, "\xFF" * 16, pixel_format: "RGBA")
   end
-  r.take  # => PNG binary
+  r.take   # Ruby 3.x
+  r.value  # Ruby 4.0+ (Ractor#take was removed in 4.0)
 
 == Versioning
 
 This gem follows a `{LIBPNG_VERSION}.{ITERATION}` scheme:
 
 - `LIBPNG_VERSION` is the upstream libpng release the gem is built
-  against (currently 1.6.48).
+  against (currently `1.6.58`).
 - `ITERATION` is a counter that bumps on Ruby-side changes (recipe bug
   fixes, CI tweaks, doc updates). It resets to 0 each time
   `LIBPNG_VERSION` bumps.
 
-For example, `1.6.48.0` is the first release against libpng 1.6.48,
-`1.6.48.1` is a Ruby-side fix, and `1.6.49.0` would be a release against
+For example, `1.6.58.0` is the first release against libpng 1.6.58,
+`1.6.58.1` is a Ruby-side fix, and `1.6.59.0` would be a release against
 the next upstream libpng.
 
 == How it works
@@ -91,15 +178,54 @@ the next upstream libpng.
 The gem has three layers:
 
 1. `lib/libpng.rb` -- Ruby FFI wrapper. Loads `libpng16.{so,dylib,dll}`
-   from the gem's `lib/libpng/` directory at runtime.
-2. `lib/libpng/recipe.rb` -- a MiniPortileCMake recipe that downloads
-   the libpng source tarball and runs CMake to produce the shared
-   library. This is invoked by `ext/extconf.rb` when the gem is installed
-   from source.
-3. `Rakefile` defines `gem:native:<platform>` tasks that pre-compile
-   the gem for each target platform. The pre-compiled gems bundle the
-   `.so`/`.dylib`/`.dll` and disable `extconf.rb`, so installation
-   requires no C compiler.
+   from the gem's `lib/libpng/` directory at runtime and exposes
+   `Libpng.encode` / `Libpng.decode` against libpng's "simplified"
+   high-level C API (`png_image_*`). The wrapper manually lays out the
+   `png_image` struct via explicit byte offsets into an
+   `FFI::MemoryPointer` rather than `FFI::Struct`, because `FFI::Struct`
+   carries class-level state that is not shareable across non-main
+   Ractors.
+
+2. `lib/libpng/recipe.rb` -- a `MiniPortileCMake` recipe that downloads
+   the libpng source tarball pinned by `LIBPNG_URL` / `LIBPNG_SHA256`,
+   runs CMake with `PNG_SHARED=ON PNG_STATIC=OFF PNG_TESTS=OFF`, and
+   copies the resulting shared lib into `lib/libpng/`. Invoked only when
+   installing the **source** (`ruby` platform) gem.
+
+3. `ext/extconf.rb` -- gem extension entry point. Calls `Recipe#cook_if_not`,
+   which is a no-op once the per-platform checkpoint file
+   (`ports/.../<name>-<ver>-<platform>.installed`) exists. After cooking,
+   emits a dummy `Makefile` via `mkmf` so RubyGems is satisfied (no Ruby
+   C extension is compiled). The pre-compiled platform gems unset
+   `spec.extensions`, so this never runs for them.
+
+=== Pre-compiled platform gems
+
+`Rakefile` defines `gem:native:<platform>` tasks for each target. Each
+task clones the gemspec, sets `spec.platform`, adds
+`lib/libpng/*.{dll,so,dylib}` to `spec.files`, removes the
+`mini_portile2` dependency (no longer needed at install time), and
+unsets `spec.extensions` -- the resulting gem installs with no compiler.
+
+The release workflow (`.github/workflows/release.yml`) builds all 10
+platforms in parallel on the appropriate native runner:
+
+- x86_64 Linux glibc -- `ubuntu-latest`
+- ARM64 Linux glibc -- `ubuntu-24.04-arm` (native)
+- x86_64 Linux musl -- `ruby:<ver>-alpine` via `docker run` on `ubuntu-latest`
+- ARM64 Linux musl -- `ruby:<ver>-alpine` via `docker run` on `ubuntu-24.04-arm`
+- x64 Windows (both MSVCRT and UCRT) -- `windows-latest` with `step-security/msvc-dev-cmd`
+- ARM64 Windows -- `windows-11-arm` (native) with `arch: arm64`
+- Intel macOS -- `macos-15-intel`
+- Apple Silicon macOS -- `macos-latest`
+
+Linux glibc and macOS builds run natively on the matching runner. Linux
+musl builds run inside `ruby:<ver>-alpine` containers via `docker run`
+rather than the workflow `container:` field, because Actions' JS runtime
+has no arm64-musl build and therefore cannot run Alpine containers on
+arm64 runners. Windows builds use the Visual Studio toolchain via
+`step-security/msvc-dev-cmd` (a maintained drop-in for the deleted
+`ilammy/msvc-dev-tools`).
 
 == License
 

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).