libpng 1.6.58.2 → 1.6.58.3

data/TODO.roadmap/10-libpng-1.6.59-bump.md

@@ -0,0 +1,59 @@
+# 10 - Libpng 1.6.59 bump when released
+
+- **Priority**: Future
+- **Status**: Planned (waiting on upstream)
+
+## Context
+
+The gem currently bundles libpng 1.6.58. Upstream `libpng16` branch is
+at `1.6.59.git` (unreleased as of 2026-07-26). 1.6.59 will include:
+
+- Memory safety fix: prevent double-free of `png_struct` members on
+  allocation failure (`cae47455`).
+- Windows/MinGW import-library symlink fix (`78ae423b`) -- doesn't
+  affect us since we ship the .dll directly.
+- CMake policy bump to 4.4 (`7ed557b4`).
+- Various CI/license maintenance.
+
+## Trigger
+
+Tag `v1.6.59` on https://github.com/pnggroup/libpng.
+
+## Approach
+
+The release workflow already has a `bump-type=libpng` mode:
+
+```sh
+gh workflow run release.yml --repo claricle/libpng-ruby \
+  --ref main \
+  -f bump-type=libpng \
+  -f libpng-version=1.6.59
+```
+
+This bumps `LIBPNG_VERSION = "1.6.59"` in `lib/libpng/version.rb`,
+resets `LIBPNG_RUBY_ITERATION` to 0, and triggers a 1.6.59.0 release.
+
+Manual steps before triggering:
+1. Update `LIBPNG_URL` and `LIBPNG_SHA256` in `lib/libpng/recipe.rb`
+   once the tarball is on sourceforge. Verify with:
+   `curl -sL <URL> | shasum -a 256`
+2. Smoke-test locally: `bundle exec rake compile` (downloads new
+   source, builds, copies the .so/.dylib/.dll into `lib/libpng/`).
+3. Run the full spec suite to catch any API regressions.
+
+## Risks
+
+- API surface: 1.6.59 is unlikely to add new public functions
+  (the diff between 1.6.58 and 1.6.59.git shows only bug fixes and
+  build improvements in `png.h`).
+- Binary layout: `png_image` struct size and field offsets are
+  unchanged.
+- Version string: `LIBPNG_VER_STRING_C` in `lib/libpng.rb` would need
+  to update to match the new binary, since `png_create_write_struct`
+  checks `user_png_ver` against the compiled-in version.
+
+## Won't do
+
+Don't ship a `1.6.59.git`-suffixed version. The `.git` suffix in our
+`{LIBPNG_VERSION}.{ITERATION}` scheme would be confusing for users.
+Wait for the actual 1.6.59 release.

data/TODO.roadmap/11-read-side-metadata.md

@@ -0,0 +1,59 @@
+# 11 - Read-side metadata getters
+
+- **Priority**: P2
+- **Status**: Done
+
+## Context
+
+`Libpng::DecodedImage` returned only `width`, `height`, `format`, and
+`pixels`. Callers wanting bit_depth, color_type, or interlace method
+had to walk the PNG themselves.
+
+## Approach
+
+Two pieces:
+
+1. **Expanded Struct**: `Libpng::DecodedImage` now has `bit_depth`,
+   `color_type`, `interlace` keyword fields (in addition to the
+   existing four).
+
+2. **`Libpng::ChunkWalker`**: new public class for walking PNG chunk
+   layout. Methods:
+   - `#each_chunk` -- yields `[type, data, offset]`
+   - `#strip_ancillary` -- returns a new binary String with only
+     IHDR/IDAT/IEND (used by SimplifiedEncoder when `strip_colorspace:
+     true`)
+   - `#ihdr_data` -- raw IHDR bytes
+   - `#ihdr_fields` -- parsed Hash: `:width, :height, :bit_depth,
+     :color_type, :compression, :filter, :interlace`
+
+3. **`Libpng::SimplifiedDecoder`** uses `ChunkWalker#ihdr_fields` after
+   the libpng decode to populate the new Struct fields. Best-effort:
+   if the walker raises (e.g. corrupt PNG), the metadata stays nil and
+   the libpng-side error propagates.
+
+## Refactor side-effect
+
+The chunk-stripping logic in `Libpng::SimplifiedEncoder` was rewritten
+to use `ChunkWalker#strip_ancillary` instead of inline code. DRY win:
+one place that understands PNG chunk layout.
+
+## Specs
+
+`spec/decoded_image_metadata_spec.rb` verifies:
+- IHDR metadata is populated for RGBA/RGB/GRAY decode
+- Adam7 interlace is reflected after `encode_standard(interlace:
+  :adam7)` -> decode
+- `ChunkWalker` parses IHDR fields correctly
+- `ChunkWalker` raises `FormatError` on non-PNG input
+
+## Delivered
+
+PR #7 (this branch).
+
+## Future work
+
+- Expose text chunks (tEXt/zTXt/iTXt) -- see [TODO 19](19-text-chunk-read.md)
+- Expose color metadata (gAMA/cHRM/sRGB/iCCP) -- see [TODO 20](20-color-metadata-read.md)
+- Ancillary chunk preservation on decode (currently we expand to
+  pixels and drop everything else)

data/TODO.roadmap/12-full-api-surface.md

@@ -0,0 +1,61 @@
+# 12 - Full libpng API surface binding
+
+- **Priority**: Skip
+- **Status**: Won't do
+
+## Context
+
+We expose 13 of libpng's 172 exported functions (~8%). The audit
+(see PR #6 discussion) identified gaps in:
+
+- Standard read API (10 functions)
+- Write-side chunk setters (15+: PLTE, tRNS, gAMA, cHRM, sRGB, iCCP,
+  bKGD, pHYs, oFFs, tIME, sCAL, sPLT, hIST, text, unknown chunks)
+- Info getters (~20)
+- Read transformations (~20)
+- Advanced compression controls
+- Progressive/streaming decode
+- File I/O variants
+- Filter heuristics
+- Interlacing helpers
+- CRC error handling
+- Memory/struct internals
+
+## Why we won't do this
+
+1. **Scope creep**: The gem's purpose is encode/decode with libemf2svg
+   parity, not a complete libpng binding.
+2. **Maintenance cost**: Each function needs docs, tests, and version
+   compatibility checks across libpng releases.
+3. **Ractor safety risk**: Many libpng functions are stateful
+   (`png_set_*` mutates `png_struct`). Exposing them naively could
+   introduce Ractor-safety violations.
+4. **Alternatives exist**: Users needing low-level libpng access can
+   `attach_function` against the bundled `libpng16.so` directly
+   (it contains all 172 functions).
+5. **YAGNI**: No user has requested specific functions beyond what
+   `encode_standard` provides.
+
+## When this position might change
+
+- A specific user need that can't be met by extending the existing
+  options-based API.
+- A major libpng release that introduces a high-demand feature
+  (unlikely in the 1.6.x series).
+- A formal request from emfsvg or another downstream consumer.
+
+## Recommended path forward (if needed)
+
+Instead of exposing `png_set_gAMA` etc. as individual Ruby methods,
+add higher-level options to `encode_standard`:
+
+```ruby
+Libpng.encode_standard(width, height, pixels,
+                       pixel_format: "RGBA",
+                       gamma: 0.45455,         # emits gAMA
+                       chromaticities: {...},  # emits cHRM
+                       srgb: 0,                # emits sRGB
+                       icc_profile: File.read("profile.icc"))  # emits iCCP
+```
+
+This keeps the API Ruby-idiomatic and limits the testing surface.

data/TODO.roadmap/13-c-extension-setjmp.md

@@ -0,0 +1,77 @@
+# 13 - C extension wrapper for setjmp
+
+- **Priority**: Skip
+- **Status**: Won't do
+
+## Context
+
+`encode_standard` uses `png_set_error_fn` to register an FFI callback
+that calls `rb_raise` instead of libpng's default `abort()`. libpng
+expects error callbacks to `longjmp` back to a `setjmp` point set up
+by the caller. Calling `rb_raise` from the FFI callback unwinds the
+Ruby stack via Ruby's own `longjmp`-based exception machinery.
+
+This works for input-validation errors (most cases) but has a subtle
+caveat: libpng's internal state between the callback invocation and
+the `setjmp` target is not cleaned up. Our `ensure` block calls
+`png_destroy_write_struct` to release the C state, which is sufficient
+in practice.
+
+## Why we won't do this
+
+A C extension could properly wrap the standard API with `setjmp`:
+```c
+if (setjmp(png_jmpbuf(png_ptr))) {
+    /* longjmp target -- copy error message, return error code */
+}
+```
+
+This would give clean error handling without Ruby stack unwinding
+concerns.
+
+But:
+
+1. **Adds a build dependency**: A C extension means the gem requires a
+   C compiler at install time on every platform. We currently ship
+   pre-compiled binary gems for 9 platforms specifically to avoid
+   this. Adding a C extension would require shipping pre-compiled
+   extensions for each platform too -- a significant build/release
+   burden.
+
+2. **Current approach works**: The rb_raise-from-callback pattern has
+   not caused any user-visible issues in testing or production use.
+
+3. **Documented in README**: The caveat is called out in the
+   `encode_standard` documentation. Users who need bulletproof error
+   handling for adversarial input can validate before calling.
+
+4. **Simplified API already handles it cleanly**: The `png_image_*`
+   API uses an internal `setjmp` and captures errors into the message
+   buffer. For decode paths (where adversarial input is most likely),
+   `Libpng.decode` is the right choice.
+
+## When this position might change
+
+- A real-world crash report attributed to the rb_raise-from-callback
+  pattern.
+- A user needing to call `encode_standard` in a tight loop with
+  potentially-corrupt pixel buffers (where the half-freed png_struct
+  could accumulate state).
+
+## Alternative under consideration
+
+If we ever do add a C extension, it would be a tiny `.c` file (maybe
+50 lines) exposing a single function:
+
+```c
+int libpng_encode_to_memory_safe(
+    uint32_t width, uint32_t height, int bit_depth, int color_type,
+    int interlace, int filter, int compression_level,
+    const void *pixels, int stride,
+    const void *palette, int palette_entries,
+    void **out, size_t *out_len,
+    char *err_msg, size_t err_msg_len);
+```
+
+This would be the only C function in the gem. FFI would bind it
+directly. All libpng state would be confined inside the C function.

data/TODO.roadmap/14-progressive-decode.md

@@ -0,0 +1,47 @@
+# 14 - Progressive/streaming decode
+
+- **Priority**: Skip
+- **Status**: Won't do
+
+## Context
+
+libpng supports progressive (streaming) decode via
+`png_set_progressive_read_fn` + `png_process_data`. This lets callers
+feed bytes incrementally as they arrive (e.g. over a network socket)
+rather than buffering the entire PNG first.
+
+## Why we won't do this
+
+1. **No use case yet**: The gem's consumers (emfsvg, image processing
+   tools) work with complete PNGs in memory.
+
+2. **API complexity**: Progressive decode requires a stateful reader
+   object (`Libpng::ProgressiveReader`?) with `#feed(bytes)` and
+   `#finish` methods, plus callback hooks for row completion. This is
+   a significantly different API surface from the current
+   `Libpng.decode(png_bytes)`.
+
+3. **Ruby I/O is usually buffered anyway**: Ruby's `IO.read`,
+   `Net::HTTP.get`, etc. all return complete strings. Streaming is the
+   exception, not the rule.
+
+4. **Memory savings are minimal**: A typical PNG is 100KB-5MB.
+   Buffering the whole thing in a String is fine for almost all use
+   cases.
+
+## When this position might change
+
+- A user building a streaming image service (e.g. progressive JPEG-like
+  loading for web).
+- A request from a framework like Rack that wants to decode PNG
+  uploads as they arrive.
+
+## Alternative if needed
+
+Use a tempfile + standard `Libpng.decode`:
+```ruby
+File.open(upload_path, 'wb') { |f| f.write(chunk) until done }
+decoded = Libpng.decode(File.binread(upload_path))
+```
+
+Not streaming, but avoids holding the entire upload in Ruby memory.

data/TODO.roadmap/15-file-io-variants.md

@@ -0,0 +1,57 @@
+# 15 - File I/O variants
+
+- **Priority**: Skip
+- **Status**: Won't do
+
+## Context
+
+libpng exposes file-based I/O via `png_init_io(FILE*)`, plus the
+simplified API has `png_image_begin_read_from_file` /
+`png_image_write_to_file`. We currently only use the memory-based
+variants (`_from_memory`, `_to_memory`, `png_set_write_fn` with
+in-memory callback).
+
+## Why we won't do this
+
+1. **`FILE*` lifetime is awkward across FFI**: A Ruby `File` object
+   wraps a `FILE*`. Passing it to libpng via FFI requires either:
+   - Reaching into Ruby's internal struct layout (fragile, version-
+     dependent)
+   - Opening a separate `FILE*` via `fopen(3)` and managing its
+     lifetime manually (error-prone)
+
+2. **Memory-stream output is the right default**: It avoids disk I/O
+   entirely, lets callers decide where to persist (or not), and works
+   identically across all 10 platforms.
+
+3. **Ruby already has good file I/O**:
+   ```ruby
+   png = Libpng.encode(width, height, pixels, pixel_format: "RGBA")
+   File.binwrite("out.png", png)
+   ```
+   is idiomatic Ruby. Adding `Libpng.encode_to_file` would be a
+   duplicate API for marginal benefit.
+
+4. **Simplified API file variants are POSIX-only**:
+   `png_image_begin_read_from_file` takes a `const char *filename`,
+   which doesn't handle Windows wide-char paths cleanly. The memory
+   variants sidestep this entirely.
+
+## When this position might change
+
+- A user with truly huge images (multi-GB) where holding the encoded
+  PNG in memory before writing to disk is wasteful.
+- A performance benchmark showing `File.binwrite` is a real bottleneck
+  (unlikely -- disk I/O is fast and `File.binwrite` uses `write(2)`
+  directly).
+
+## Alternative under consideration
+
+If streaming-to-file becomes important, the right design is:
+```ruby
+Libpng.encode_standard(width, height, pixels, output: io_object)
+```
+where `io_object` is anything responding to `#<<` (String, File,
+StringIO, etc.). The internal FFI write callback would call
+`io_object << data.read_bytes(len)`. This is more flexible than a
+file-only variant and requires no new libpng functions.

data/TODO.roadmap/16-architecture-refactor.md

@@ -0,0 +1,97 @@
+# 16 - Architecture refactor: autoload + OOP
+
+- **Priority**: P0
+- **Status**: Done
+
+## Context
+
+`lib/libpng.rb` was a 466-line monolith mixing:
+- Module definition
+- FFI library setup
+- 13 `attach_function` calls
+- ~40 constants (FORMAT_*, COLOR_TYPE_*, FILTER_*, INTERLACE_*, etc.)
+- `png_image` struct layout constants
+- `encode`, `decode`, `encode_standard` methods (each 50-100 lines)
+- 5 private helper methods
+
+Plus the file used `require_relative 'libpng/version'`, violating the
+project-wide rule against `require_relative` for internal library code.
+
+## Approach
+
+Split into MECE per-concern files under `lib/libpng/`, loaded via
+`autoload` from `lib/libpng.rb`:
+
+| File | Responsibility |
+|---|---|
+| `error.rb` | `Libpng::Error` |
+| `decoded_image.rb` | `Libpng::DecodedImage` Struct |
+| `chunk_walker.rb` | `Libpng::ChunkWalker` (PNG chunk walking utility class) |
+| `bytes_per_pixel.rb` | `Libpng::BytesPerPixel` (pure-data lookup) |
+| `simplified_encoder.rb` | `Libpng::SimplifiedEncoder` (encode via simplified API) |
+| `simplified_decoder.rb` | `Libpng::SimplifiedDecoder` (decode + metadata extraction) |
+| `standard_encoder.rb` | `Libpng::StandardEncoder` (encode_standard with all options) |
+
+Each encoder/decoder is a class instantiated per call:
+```ruby
+class Libpng::SimplifiedEncoder
+  def initialize(width, height, pixels, **opts)
+    # validate + store
+  end
+
+  def call
+    # do the work, return result
+  end
+end
+```
+
+The public API stays as module methods for backward compat:
+```ruby
+def self.encode(width, height, pixels, **opts)
+  SimplifiedEncoder.new(width, height, pixels, **opts).call
+end
+```
+
+## Why per-call instances
+
+- **OCP**: New encode options (e.g. `gamma:`) extend the encoder class
+  without touching `Libpng.encode`.
+- **Testability**: Each encoder is independently testable.
+- **MECE**: Validation lives in the encoder, FFI calls live in the
+  encoder, dispatch lives in the module. Three concerns, three places.
+- **Ractor-safe by construction**: Instances are local to one call,
+  never shared.
+
+The per-call allocation cost (~1 object) is negligible compared to the
+libpng C call.
+
+## Why autoload instead of eager
+
+- Faster `require 'libpng'` for users who only need one API
+- Project rule: never `require_relative` for internal library code
+- Lazy loading of rarely-used classes (e.g. `Recipe` is only needed
+  during source-gem install)
+
+## What changed in ext/extconf.rb
+
+Before:
+```ruby
+$LOAD_PATH << File.expand_path('../lib', __dir__)
+require 'libpng/recipe'  # violation: require with path
+```
+
+After:
+```ruby
+$LOAD_PATH << File.expand_path('../lib', __dir__)
+require 'libpng'  # triggers autoload setup
+recipe = Libpng::Recipe.new  # accesses Recipe constant, triggers autoload
+```
+
+## Specs
+
+All existing specs still pass without modification (the public API is
+unchanged). 81 examples, 0 failures.
+
+## Delivered
+
+PR #7 (this branch).

data/TODO.roadmap/17-ruby-version-policy.md

@@ -0,0 +1,46 @@
+# 17 - Ruby version support policy
+
+- **Priority**: Future
+- **Status**: Planned
+
+## Context
+
+The gemspec declares `required_ruby_version = '>= 2.7.0'`. Ruby 2.7
+reached EOL in March 2023. Ruby 3.0 reached EOL in March 2024. Ruby
+3.1 is in security maintenance. Ruby 3.2, 3.3, 3.4 are current.
+
+Ractors require Ruby 3.0+. Our Ractor specs guard with
+`return unless defined?(Ractor)` so they no-op on 2.7, but the
+`return` at file top-level might warn on some Ruby versions.
+
+## Proposal
+
+Bump `required_ruby_version` to `>= 3.1.0` in a future minor release.
+
+Rationale:
+- Drops EOL versions (2.7, 3.0) -- no security backports
+- Keeps 3.1 (security maintenance) and all current versions (3.2, 3.3, 3.4)
+- Aligns with `mini_portile2 ~> 2.8` which also requires 3.1+
+- Removes the `return unless defined?(Ractor)` guard from spec files
+  (the gem can assume Ractor exists)
+
+## Risks
+
+- Some users may still be on 2.7 (legacy deployments). They'd be
+  stuck on the last 2.7-compatible release.
+- RubyInstaller ARM64 builds start at 3.4.1, so Windows ARM64 users
+  are unaffected.
+
+## Approach
+
+1. Wait one release cycle after announcing the deprecation.
+2. Bump `required_ruby_version` in `libpng.gemspec`.
+3. Update the README Ruby version badge.
+4. Remove the Ractor guard in `spec/ractor_spec.rb` and
+   `spec/ractor_standard_spec.rb`.
+
+## Trigger
+
+Either:
+- ruby-setup-ruby drops 2.7 and 3.0 from its version matrix, OR
+- A security feature in libpng requires Ruby 3.1+ APIs.

data/TODO.roadmap/18-dependabot.md

@@ -0,0 +1,52 @@
+# 18 - Dependabot for automated dependency bumps
+
+- **Priority**: Future
+- **Status**: Planned
+
+## Context
+
+The gem has runtime dependencies on `ffi` and `mini_portile2`, and dev
+dependencies on `rake`, `rspec`, and `rubocop`. These are bumped
+manually when someone notices a new version. Dependabot would automate
+this and open PRs when new versions are released.
+
+## Proposal
+
+Add `.github/dependabot.yml`:
+
+```yaml
+version: 2
+updates:
+  - package-ecosystem: "bundler"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+    groups:
+      dev-deps:
+        dependency-type: "development"
+      runtime-deps:
+        dependency-type: "production"
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+```
+
+Two groups:
+- **dev-deps**: rake, rspec, rubocop -- batch into one PR per week
+- **runtime-deps**: ffi, mini_portile2 -- separate PRs (more careful
+  review since these affect end users)
+
+Plus GitHub Actions version bumps (checkout, upload-artifact, etc.).
+
+## Risks
+
+- Slightly noisier PR queue.
+- Some bumps may break CI (e.g. rubocop new cops). Auto-merge is not
+  appropriate; each PR needs human review.
+
+## Trigger
+
+When the project stabilizes after the current refactor wave.

data/TODO.roadmap/19-text-chunk-read.md

@@ -0,0 +1,104 @@
+# 19 - Text chunk (tEXt/zTXt/iTXt) read support
+
+- **Priority**: P2
+- **Status**: Planned
+
+## Context
+
+PNG images often carry metadata in text chunks:
+- `tEXt`: Latin-1 key/value pairs
+- `zTXt`: zlib-compressed Latin-1
+- `iTXt`: UTF-8 with optional compression, optional language tag
+
+Common keys: `Title`, `Author`, `Description`, `Copyright`,
+`Software`, `Creation Time`.
+
+Our `ChunkWalker` already iterates all chunks. We just need to parse
+the text chunk format and expose it on `DecodedImage`.
+
+## Proposal
+
+Extend `Libpng::ChunkWalker` with text-chunk parsing, and extend
+`DecodedImage` to carry a `text` field.
+
+```ruby
+decoded = Libpng.decode(File.binread("photo.png"), pixel_format: "RGB")
+decoded.text           # => { "Title" => "Sunset", "Author" => "Jane", ... }
+decoded.text["Title"]  # => "Sunset"
+```
+
+Text values are UTF-8 strings (converted from Latin-1 for tEXt/zTXt;
+already UTF-8 for iTXt). Keys are ASCII.
+
+## Implementation
+
+Add to `chunk_walker.rb`:
+
+```ruby
+def text_chunks
+  result = {}
+  each_chunk do |type, data, _|
+    case type
+    when 'tEXt' then parse_text(data, result)
+    when 'zTXt' then parse_ztxt(data, result)
+    when 'iTXt' then parse_itxt(data, result)
+    end
+  end
+  result
+end
+
+private
+
+def parse_text(data, result)
+  null_idx = data.index("\x00")
+  return if null_idx.nil?
+  key = data[0, null_idx]
+  val = data[(null_idx + 1)..]
+  result[key] = val.force_encoding('ISO-8859-1').encode('UTF-8')
+end
+
+def parse_ztxt(data, result)
+  null_idx = data.index("\x00")
+  return if null_idx.nil?
+  key = data[0, null_idx]
+  # data[null_idx+1] is compression method (0 = zlib)
+  compressed = data[(null_idx + 2)..]
+  val = Zlib.inflate(compressed)
+  result[key] = val.force_encoding('ISO-8859-1').encode('UTF-8')
+end
+
+def parse_itxt(data, result)
+  # iTXt is more complex: keyword\0 compression_flag compression_method
+  # language_tag\0 translated_keyword\0 text
+  # ... parse accordingly
+end
+```
+
+Then in `simplified_decoder.rb`:
+
+```ruby
+metadata = extract_metadata
+text = ChunkWalker.new(@png).text_chunks rescue {}
+return DecodedImage.new(..., text: text)
+```
+
+And in `decoded_image.rb`:
+
+```ruby
+DecodedImage = Struct.new(:width, :height, :format, :pixels,
+                          :bit_depth, :color_type, :interlace, :text,
+                          keyword_init: true)
+```
+
+## Specs
+
+- Round-trip: encode a PNG with tEXt chunks (via libpng's standard API,
+  once we expose `png_set_text`), decode, verify text matches.
+- zTXt decompression works.
+- iTXt UTF-8 round-trip.
+- Malformed text chunk doesn't break decode (best-effort).
+
+## Out of scope
+
+- Writing text chunks (`png_set_text`) -- separate TODO if needed.
+- International text chunk ordering / precedence rules.