libpng 1.6.58.4 → 1.6.58.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3764dc7e75c29be74bf732ba3d3ac4a66b17c4d20f5e1404f7d1d4fb4a7bff5d
-  data.tar.gz: 81d239f7c17eef66172e93543c949d1cee3a5d5bd281f997c3e26153e7beafe5
+  metadata.gz: e9edc7cf7190ff782780b914a63bc3a26cd3c1dd71199c26ec144e3e3f72619f
+  data.tar.gz: bed30533f0f5b33e4064213aa6bacecb8e815ca56234a8991ae8af70627cb40f
 SHA512:
-  metadata.gz: 4d7d3caf69638aaf251a34631346007aed404d662a5d238dadf628b0f202ff2db51a751c6de310e76358c974c9b8d12207cb9f89f0f7c8b6d45fd47ae8d0a5be
-  data.tar.gz: aedc2495d938619919ba47c65fb1f54f3b38af2cddcf39d38fef0eb9464031d5dcdc3922f3e6230d2bf05c612e271c28e0878ef263b3200c5a15c14336453c97
+  metadata.gz: e94cbd6af3fbc2accb177d8f3adc9565582d1853e9f998ff314934b6b5f2816f058164b40a32ee7661b55ea5c58e920c03d600d30e49e7f1d51d5f71e280f3f7
+  data.tar.gz: 88fca2579a17b68e184b381483687e43eef88d5a104ac74deb12056bd376e494db7e3b795312fad2042219979a0c9119b2daef8cd4dd2e47c6cf49925a2f5274

data/.rubocop.yml

@@ -22,7 +22,7 @@ Metrics/ModuleLength:
 Metrics/PerceivedComplexity:
   Max: 20
 Metrics/ParameterLists:
-  Max: 9
+  Max: 10
 
 Metrics/BlockLength:
   Exclude:
@@ -37,3 +37,11 @@ Style/FrozenStringLiteralComment:
   Exclude:
     - ext/extconf.rb
     - lib/libpng/recipe.rb
+
+# libpng's C function names use mixed case + digits (e.g.
+# png_set_strip_16, png_set_expand_gray_1_2_4_to_8). We attach them
+# via FFI with their canonical names so docs and headers cross-
+# reference cleanly.
+Naming/VariableNumber:
+  Exclude:
+    - lib/libpng/binding.rb

data/CHANGELOG.md

@@ -7,6 +7,42 @@ 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.5] - 2026-07-26
+
+### Added
+- **Write-side metadata on `encode_standard`**. Six new keyword options:
+  - `text:` -- `Hash<String,String>` of tEXt/iTXt entries. Non-ASCII
+    values automatically use iTXt (UTF-8) instead of tEXt (Latin-1).
+  - `gamma:` -- `Float` file gamma (e.g. `0.45455` for sRGB).
+  - `srgb_intent:` -- `Integer 0..3` rendering intent.
+  - `chromaticities:` -- `Hash` with the 8 cHRM primaries.
+  - `icc_profile:` -- `Hash` with `:name` and `:data` for an ICC
+    color profile (libpng compresses internally).
+  - `phys:` -- `Hash` with `:pixels_per_unit_x/y` and `:unit`
+    (`0` unknown, `1` meters).
+- **`pHYs` chunk read support**. `Libpng::ChunkWalker#phys_chunk`
+  returns a Hash with `:pixels_per_unit_x/y`, `:unit`, and (when
+  `unit==1`) computed `:dpi_x/y`. `DecodedImage#phys` is populated
+  by both decode paths.
+- **`Libpng.decode_standard`** -- standard libpng read API
+  (`png_create_read_struct` -> `png_read_info` -> transforms ->
+  `png_read_image`). Counterpart to `encode_standard`; gives
+  callers explicit control over which transforms apply
+  (palette-to-RGB, gray-to-RGB, alpha add/strip, 16-to-8 demotion,
+  interlace handling). Returns the same `DecodedImage` shape as
+  `decode`, so metadata access is uniform across both decode paths.
+- New classes/modules: `Libpng::StandardDecoder`,
+  `Libpng::MetadataWriter`, `Libpng::TextWriter`, `Libpng::TextEntry`.
+- 27 new specs across `spec/write_metadata_spec.rb` (round-trips for
+  every metadata type + validation errors) and
+  `spec/standard_decoder_spec.rb` (transform coverage + Ractor safety).
+
+### Fixed
+- Internal: refactored `StandardEncoder` to delegate metadata writing
+  to `MetadataWriter`. Class length back under rubocop limits.
+- Corrected `FILLER_BEFORE`/`FILLER_AFTER` constant values (the code
+  had them swapped -- libpng uses `BEFORE=0, AFTER=1`).
+
 ## [1.6.58.4] - 2026-07-26
 
 ### Added

data/CLAUDE.md

@@ -20,12 +20,15 @@ loaded via `autoload` from `lib/libpng.rb`. **Never use `require_relative`
 | `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: `#each_chunk`, `#ihdr_fields`, `#text_chunks` for tEXt/zTXt/iTXt, `#color_chunks` for gAMA/cHRM/sRGB/iCCP, `#strip_ancillary`) |
+| `lib/libpng/decoded_image.rb` | `Libpng::DecodedImage` (Struct returned by `decode` / `decode_standard`) |
+| `lib/libpng/chunk_walker.rb` | `Libpng::ChunkWalker` (walk/strip/extract metadata: `#each_chunk`, `#ihdr_fields`, `#text_chunks` for tEXt/zTXt/iTXt, `#color_chunks` for gAMA/cHRM/sRGB/iCCP, `#phys_chunk` for pHYs, `#strip_ancillary`) |
 | `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/simplified_decoder.rb` | `Libpng::SimplifiedDecoder` (libpng simplified read API + metadata via ChunkWalker) |
+| `lib/libpng/standard_encoder.rb` | `Libpng::StandardEncoder` (libpng standard write API; filter/compression/interlace/bit_depth/palette + metadata via MetadataWriter) |
+| `lib/libpng/standard_decoder.rb` | `Libpng::StandardDecoder` (libpng standard read API; explicit transform control) |
+| `lib/libpng/metadata_writer.rb` | `Libpng::MetadataWriter` (validates + writes text/gAMA/sRGB/cHRM/iCCP/pHYs onto a png_ptr/info_ptr pair) |
+| `lib/libpng/text_writer.rb` | `Libpng::TextWriter` + `Libpng::TextEntry` (builds png_text struct array, calls `png_set_text`) |
 | `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 |
 
@@ -33,7 +36,9 @@ loaded via `autoload` from `lib/libpng.rb`. **Never use `require_relative`
 
 ```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.encode_standard(width, height, pixels, pixel_format:, filter:, compression_level:, interlace:, bit_depth:, palette:, **metadata)
+Libpng.decode(png, pixel_format:)
+Libpng.decode_standard(png, pixel_format:, bit_depth:)
 Libpng.decode(png, pixel_format:)
 ```
 
@@ -58,7 +63,7 @@ Ruby 4.0 removed `Ractor#take`; use the helper `ractor_result(r)` which prefers
 ```sh
 bundle install
 bundle exec rake compile         # build libpng via MiniPortile (needs cmake + zlib)
-bundle exec rake spec            # all specs (~105 examples)
+bundle exec rake spec            # all specs (~132 examples)
 bundle exec rspec spec/libpng_spec.rb:17   # single spec by line
 bundle exec rake rubocop
 bundle exec rake                 # default: spec + rubocop
@@ -96,12 +101,14 @@ The workflow bumps `lib/libpng/version.rb`, pushes a `v*` tag, builds all 11 pla
 - `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/write_metadata_spec.rb` — text/gAMA/sRGB/cHRM/pHYs write round-trips + validation
 - `spec/decoded_image_metadata_spec.rb` — IHDR metadata + `ChunkWalker`
-- `spec/text_chunk_spec.rb` — tEXt/zTXt/iTXt parsing
-- `spec/color_metadata_spec.rb` — gAMA/cHRM/sRGB/iCCP parsing
+- `spec/text_chunk_spec.rb` — tEXt/zTXt/iTXt parsing (read side)
+- `spec/color_metadata_spec.rb` — gAMA/cHRM/sRGB/iCCP parsing (read side)
+- `spec/standard_decoder_spec.rb` — `decode_standard` transforms + Ractor safety
 - `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/ractor_standard_spec.rb` — Ractor safety for standard write API
 - `spec/benchmark_spec.rb` — encode/decode timing comparison
 
 ## See also

data/README.adoc

@@ -71,6 +71,7 @@ for the current set):
   decoded.interlace   # => 0 (PNG_INTERLACE_NONE, from IHDR)
   decoded.text        # => {"Title" => "Sunset", "Author" => "Jane"} (tEXt/zTXt/iTXt)
   decoded.color       # => {:gamma => 0.45455, :srgb_intent => 0, ...} (gAMA/cHRM/sRGB/iCCP)
+  decoded.phys        # => {:pixels_per_unit_x => 3779, :unit => 1, :dpi_x => 95.99, ...} (pHYs)
 
 === Supported pixel formats
 
@@ -109,7 +110,14 @@ by `libemf2svg`'s `rgb2png` -- use `encode_standard` instead of
                          compression_level: 6,
                          interlace: :none,
                          bit_depth: 8,
-                         palette: nil)
+                         palette: nil,
+                         # Metadata writers (each optional):
+                         text: { "Title" => "Sunset", "Author" => "Jane" },
+                         gamma: 0.45455,
+                         srgb_intent: 0,
+                         chromaticities: { white_point_x: 0.3127, ... },
+                         icc_profile: { name: "sRGB IEC61966-2.1", data: bytes },
+                         phys: { pixels_per_unit_x: 3779, pixels_per_unit_y: 3779, unit: 1 })
 
 `pixel_format`:: `:gray`, `:ga`, `:rgb`, `:rgba`, or `:palette`. The
 byte-order variants (`BGR`, `ARGB`, `BGRA`, `ABGR`) are simplified-API
@@ -148,12 +156,29 @@ Differences from `encode`:
   `ensure` block calls `png_destroy_write_struct` to release the C
   state.
 
+=== Standard API (decode_standard)
+
+`Libpng.decode_standard` is the read-side counterpart to
+`encode_standard`. It calls `png_create_read_struct` +
+`png_set_read_fn` (memory reader) + `png_read_info` + transforms +
+`png_read_image`, giving the caller explicit control over which
+transforms apply (palette-to-RGB, gray-to-RGB, alpha add/strip,
+16-to-8 demotion, interlace handling).
+
+  decoded = Libpng.decode_standard(png_bytes, pixel_format: "RGBA", bit_depth: 8)
+
+Returns the same `Libpng::DecodedImage` shape as `decode`, so metadata
+fields (`text`, `color`, `phys`) work uniformly across both decode
+paths. Use `decode` for the common case (auto-transforms); use
+`decode_standard` when you need to know exactly which transforms
+applied (e.g. for parity with `libemf2svg`'s `png2rgb`).
+
 == Ractor safety
 
-`Libpng.encode` and `Libpng.decode` are Ractor-safe. Every call
-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.
+`Libpng.encode`, `Libpng.encode_standard`, `Libpng.decode`, and
+`Libpng.decode_standard` are all Ractor-safe. Every call allocates and
+frees its own libpng state; no shared mutable state exists on the Ruby
+side. Calls from multiple Ractors run concurrently without locking.
 
 Example (Ruby 3.x uses `Ractor#take`; Ruby 4.0+ uses `Ractor#value`):
 

data/lib/libpng/binding.rb

@@ -28,7 +28,9 @@ module Libpng
     # __dir__ is lib/libpng/; the shared library ships at lib/libpng/.
     ffi_lib File.expand_path(lib_filename, __dir__)
 
+    # ----------------------------------------------------------------
     # libpng simplified API (png_image / png_image_*).
+    # ----------------------------------------------------------------
     attach_function :png_image_begin_read_from_memory,
                     %i[pointer pointer size_t], :int
     attach_function :png_image_finish_read,
@@ -37,7 +39,9 @@ module Libpng
                     %i[pointer pointer pointer int pointer int pointer], :int
     attach_function :png_image_free, [:pointer], :void
 
-    # libpng standard (non-simplified) write API.
+    # ----------------------------------------------------------------
+    # libpng standard write API.
+    # ----------------------------------------------------------------
     attach_function :png_create_write_struct,
                     %i[string pointer pointer pointer], :pointer
     attach_function :png_create_info_struct, [:pointer], :pointer
@@ -53,5 +57,77 @@ module Libpng
     attach_function :png_set_write_fn,
                     %i[pointer pointer pointer pointer], :void
     attach_function :png_write_png, %i[pointer pointer int pointer], :void
+
+    # ----------------------------------------------------------------
+    # Metadata writers (called between png_set_IHDR and png_write_png).
+    # ----------------------------------------------------------------
+    # png_text is a struct; we pass an array pointer + count.
+    attach_function :png_set_text,
+                    %i[pointer pointer pointer int], :void
+    # file_gamma is a double.
+    attach_function :png_set_gAMA,
+                    %i[pointer pointer double], :void
+    attach_function :png_set_sRGB,
+                    %i[pointer pointer int], :void
+    # 8 chromaticity doubles (white_x, white_y, r_x, r_y, g_x, g_y, b_x, b_y).
+    attach_function :png_set_cHRM,
+                    %i[pointer pointer double double double double
+                       double double double double], :void
+    # png_set_iCCP(png_ptr, info_ptr, name, compression_type, profile, length)
+    attach_function :png_set_iCCP,
+                    %i[pointer pointer string int pointer uint], :void
+    # png_set_pHYs(png_ptr, info_ptr, res_x, res_y, unit_type)
+    attach_function :png_set_pHYs,
+                    %i[pointer pointer uint32 uint32 int], :void
+
+    # ----------------------------------------------------------------
+    # libpng standard read API.
+    # ----------------------------------------------------------------
+    attach_function :png_create_read_struct,
+                    %i[string pointer pointer pointer], :pointer
+    attach_function :png_destroy_read_struct, %i[pointer pointer pointer], :void
+    attach_function :png_set_read_fn,
+                    %i[pointer pointer pointer pointer], :void
+    attach_function :png_read_info, %i[pointer pointer], :void
+    attach_function :png_read_update_info, %i[pointer pointer], :void
+    attach_function :png_read_image, %i[pointer pointer], :void
+    attach_function :png_read_end, %i[pointer pointer], :void
+    # Returns the byte count per row AFTER any transforms are applied.
+    attach_function :png_get_rowbytes, %i[pointer pointer], :size_t
+    # Returns the post-transform color type / bit depth / channels.
+    attach_function :png_get_color_type, %i[pointer pointer], :uint8
+    attach_function :png_get_bit_depth, %i[pointer pointer], :uint8
+    attach_function :png_get_channels, %i[pointer pointer], :uint8
+    # Returns post-transform width / height (transforms rarely change these).
+    attach_function :png_get_image_width, %i[pointer pointer], :uint32
+    attach_function :png_get_image_height, %i[pointer pointer], :uint32
+    attach_function :png_get_interlace_type, %i[pointer pointer], :uint8
+    # png_get_IHDR signature differs from png_set_IHDR: widths are passed
+    # by reference (pointer to uint32) so libpng can write them back.
+    attach_function :png_get_IHDR,
+                    %i[pointer pointer pointer pointer pointer pointer
+                       pointer pointer pointer], :uint32
+
+    # ----------------------------------------------------------------
+    # Read-side transforms (call between png_read_info and png_read_image).
+    # Each takes only (png_ptr); they toggle internal state.
+    # ----------------------------------------------------------------
+    attach_function :png_set_expand, [:pointer], :void
+    attach_function :png_set_palette_to_rgb, [:pointer], :void
+    attach_function :png_set_tRNS_to_alpha, [:pointer], :void
+    attach_function :png_set_strip_alpha, [:pointer], :void
+    attach_function :png_set_strip_16, [:pointer], :void
+    attach_function :png_set_expand_gray_1_2_4_to_8, [:pointer], :void
+    attach_function :png_set_gray_to_rgb, [:pointer], :void
+    attach_function :png_set_rgb_to_gray, %i[pointer int double double], :void
+    attach_function :png_set_filler, %i[pointer uint int], :void
+    attach_function :png_set_add_alpha, %i[pointer uint int], :void
+    attach_function :png_set_packing, [:pointer], :void
+    attach_function :png_set_swap, [:pointer], :void
+    attach_function :png_set_interlace_handling, [:pointer], :int
+    attach_function :png_set_gamma, %i[pointer double double], :void
+
+    # PNG_INFO_* bit flags returned by png_get_valid.
+    attach_function :png_get_valid, %i[pointer pointer uint], :uint
   end
 end

data/lib/libpng/chunk_walker.rb

@@ -159,6 +159,23 @@ module Libpng
       result
     end
 
+    # Parse the pHYs chunk (physical pixel dimensions). Returns nil if
+    # no pHYs chunk is present. Otherwise a Hash with:
+    #
+    #   :pixels_per_unit_x -> Integer (uint32 from chunk)
+    #   :pixels_per_unit_y -> Integer (uint32 from chunk)
+    #   :unit               -> Integer 0 (unknown) or 1 (meters)
+    #   :dpi_x              -> Float, only when unit == 1; otherwise nil
+    #   :dpi_y              -> Float, only when unit == 1; otherwise nil
+    #
+    # DPI conversion: 1 inch = 0.0254 m, so dpi = pixels_per_meter * 0.0254.
+    def phys_chunk
+      each_chunk do |type, data, _|
+        return parse_phys(data) if type == 'pHYs'
+      end
+      nil
+    end
+
     private
 
     def verify_signature
@@ -267,5 +284,23 @@ module Libpng
     rescue Zlib::Error
       # Skip malformed iCCP rather than failing the whole decode.
     end
+
+    def parse_phys(data)
+      return if data.length < 9
+
+      ppux, ppuy, unit = data.unpack('NNC')
+      result = {
+        pixels_per_unit_x: ppux,
+        pixels_per_unit_y: ppuy,
+        unit: unit
+      }
+      # DPI = pixels-per-meter * (1 inch / 0.0254 m).
+      # Only meaningful when unit == PHYS_TYPE_METER.
+      if unit == Libpng::PHYS_TYPE_METER
+        result[:dpi_x] = (ppux * Libpng::INCH_PER_METER).round(2)
+        result[:dpi_y] = (ppuy * Libpng::INCH_PER_METER).round(2)
+      end
+      result
+    end
   end
 end

data/lib/libpng/decoded_image.rb

@@ -15,8 +15,11 @@ module Libpng
   #                 value. Empty Hash when no text chunks present.
   # +color+         Hash<Symbol,*> of gAMA/cHRM/sRGB/iCCP fields. Empty
   #                 Hash when no color metadata present.
+  # +phys+          Hash<Symbol,*> from pHYs chunk, or nil when absent.
+  #                 Keys: :pixels_per_unit_x, :pixels_per_unit_y, :unit,
+  #                 and (when unit==1) :dpi_x, :dpi_y.
   DecodedImage = Struct.new(:width, :height, :format, :pixels,
                             :bit_depth, :color_type, :interlace,
-                            :text, :color,
+                            :text, :color, :phys,
                             keyword_init: true)
 end

data/lib/libpng/metadata_writer.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Libpng
+  # Validates and writes PNG metadata chunks (text, gamma, sRGB,
+  # chromaticities, ICC profile, pHYs) onto a (png_ptr, info_ptr)
+  # pair. Extracted from StandardEncoder so the encoder stays focused
+  # on pixel + IHDR/PLTE concerns; this module owns the metadata story.
+  #
+  # The same module is reusable by any future encoder that wants to
+  # emit metadata -- it doesn't depend on StandardEncoder's state.
+  module MetadataWriter
+    REQUIRED_CHRM_KEYS = %i[
+      white_point_x white_point_y
+      red_x red_y
+      green_x green_y
+      blue_x blue_y
+    ].freeze
+
+    module_function
+
+    # Validate the metadata portion of an options Hash. Raises
+    # Libpng::Error on any invalid value. Keys with nil values are
+    # treated as absent.
+    def validate!(options)
+      validate_text!(options[:text]) if options[:text]
+      validate_gamma!(options[:gamma]) if options[:gamma]
+      validate_srgb_intent!(options[:srgb_intent]) if options[:srgb_intent]
+      validate_chromaticities!(options[:chromaticities]) if options[:chromaticities]
+      validate_icc_profile!(options[:icc_profile]) if options[:icc_profile]
+      validate_phys!(options[:phys]) if options[:phys]
+    end
+
+    # Apply metadata writers in spec-defined order: text first
+    # (tEXt/zTXt/iTXt come after PLTE but before oFFs/pHYs in the
+    # canonical chunk ordering), then color-space chunks (sRGB, gAMA,
+    # cHRM, iCCP), then pHYs. libpng sorts these into the right file
+    # order on write, so call order here just needs to be consistent.
+    def apply(png_ptr, info_ptr, options)
+      apply_text(png_ptr, info_ptr, options[:text]) if options[:text]
+      apply_srgb(png_ptr, info_ptr, options[:srgb_intent]) if options[:srgb_intent]
+      apply_gamma(png_ptr, info_ptr, options[:gamma]) if options[:gamma]
+      apply_chromaticities(png_ptr, info_ptr, options[:chromaticities]) if options[:chromaticities]
+      apply_icc_profile(png_ptr, info_ptr, options[:icc_profile]) if options[:icc_profile]
+      apply_phys(png_ptr, info_ptr, options[:phys]) if options[:phys]
+    end
+
+    def validate_text!(text)
+      raise Error, 'text must be a Hash' unless text.is_a?(Hash)
+
+      text.each do |key, value|
+        unless key.is_a?(String) && key.length.between?(1, 79)
+          raise Error, "text key #{key.inspect} must be a 1..79 char ASCII String"
+        end
+        raise Error, "text[#{key.inspect}] must be a String, got #{value.class}" unless value.is_a?(String)
+      end
+    end
+
+    def validate_gamma!(gamma)
+      return if gamma.is_a?(Float) && gamma.positive? && gamma <= 1.0
+
+      raise Error, 'gamma must be a Float 0 < g <= 1'
+    end
+
+    def validate_srgb_intent!(intent)
+      return if intent.is_a?(Integer) && (0..3).cover?(intent)
+
+      raise Error, 'srgb_intent must be an Integer 0..3'
+    end
+
+    def validate_chromaticities!(chrm)
+      missing = REQUIRED_CHRM_KEYS.reject { |k| chrm.is_a?(Hash) && chrm.key?(k) }
+      return if missing.empty?
+
+      raise Error, "chromaticities missing keys: #{missing.inspect}"
+    end
+
+    def validate_icc_profile!(profile)
+      unless profile.is_a?(Hash) && profile[:name].is_a?(String) && profile[:data].is_a?(String)
+        raise Error, 'icc_profile must be a Hash with :name (String) and :data (binary String)'
+      end
+      return if profile[:name].length.between?(1, 79)
+
+      raise Error, 'icc_profile[:name] must be 1..79 chars'
+    end
+
+    def validate_phys!(phys)
+      unless phys.is_a?(Hash) && phys.key?(:pixels_per_unit_x) && phys.key?(:pixels_per_unit_y) && phys.key?(:unit)
+        raise Error, 'phys must be a Hash with :pixels_per_unit_x, :pixels_per_unit_y, :unit'
+      end
+      unless phys[:unit].is_a?(Integer) && [0, 1].include?(phys[:unit])
+        raise Error, 'phys[:unit] must be 0 (unknown) or 1 (meters)'
+      end
+
+      [phys[:pixels_per_unit_x], phys[:pixels_per_unit_y]].each do |v|
+        unless v.is_a?(Integer) && v.between?(0, 0xFFFFFFFF)
+          raise Error, 'phys pixels_per_unit_* must be Integer 0..2^32-1'
+        end
+      end
+    end
+
+    def apply_text(png_ptr, info_ptr, text)
+      entries = text.map { |k, v| Libpng::TextEntry.new(key: k, value: v) }
+      Libpng::TextWriter.call(png_ptr, info_ptr, entries)
+    end
+
+    def apply_srgb(png_ptr, info_ptr, intent)
+      Libpng::Binding.png_set_sRGB(png_ptr, info_ptr, intent)
+    end
+
+    def apply_gamma(png_ptr, info_ptr, gamma)
+      Libpng::Binding.png_set_gAMA(png_ptr, info_ptr, gamma)
+    end
+
+    def apply_chromaticities(png_ptr, info_ptr, chrm)
+      Libpng::Binding.png_set_cHRM(
+        png_ptr, info_ptr,
+        chrm[:white_point_x], chrm[:white_point_y],
+        chrm[:red_x], chrm[:red_y],
+        chrm[:green_x], chrm[:green_y],
+        chrm[:blue_x], chrm[:blue_y]
+      )
+    end
+
+    def apply_icc_profile(png_ptr, info_ptr, profile)
+      data = profile[:data]
+      FFI::MemoryPointer.new(:uint8, data.bytesize) do |buf|
+        buf.write_bytes(data)
+        Libpng::Binding.png_set_iCCP(png_ptr, info_ptr, profile[:name], 0, buf, data.bytesize)
+      end
+    end
+
+    def apply_phys(png_ptr, info_ptr, phys)
+      Libpng::Binding.png_set_pHYs(png_ptr, info_ptr,
+                                   phys[:pixels_per_unit_x],
+                                   phys[:pixels_per_unit_y],
+                                   phys[:unit])
+    end
+  end
+end

data/lib/libpng/simplified_decoder.rb

@@ -74,7 +74,8 @@ module Libpng
         color_type: ihdr[:color_type],
         interlace: ihdr[:interlace],
         text: safe_text(walker),
-        color: safe_color(walker)
+        color: safe_color(walker),
+        phys: safe_phys(walker)
       }
     end
 
@@ -96,6 +97,12 @@ module Libpng
       {}
     end
 
+    def safe_phys(walker)
+      walker.phys_chunk
+    rescue ChunkWalker::FormatError
+      nil
+    end
+
     def read_message(img)
       s = img.get_bytes(PNG_IMAGE_OFF_MESSAGE, PNG_IMAGE_MESSAGE_BYTES)
       s = s.split("\x00").first || ''

data/lib/libpng/standard_decoder.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module Libpng
+  # Decodes a PNG byte buffer into raw pixels via libpng's standard
+  # read API (png_create_read_struct -> png_set_read_fn -> png_read_info
+  # -> optional transforms -> png_read_image). This is the read-side
+  # counterpart to StandardEncoder; together they expose libpng's full
+  # low-level read/write surface, complementing the simplified API.
+  #
+  # Why use this instead of Libpng.decode (the simplified path)?
+  # - Explicit control over which transforms apply (the simplified
+  #   API auto-applies a fixed set).
+  # - Useful when the caller wants to inspect the source pixel format
+  #   before deciding how to expand it (e.g. skip palette expansion
+  #   for performance on already-RGBA images).
+  #
+  # Options:
+  #   pixel_format:     The desired output format. One of:
+  #                     :gray, :ga, :rgb, :rgba (default).
+  #                     Determines which expansion / stripping
+  #                     transforms get applied.
+  #   bit_depth:        8 (default) or 16. 16-bit output preserves
+  #                     the source's full range when the source is
+  #                     also 16-bit; otherwise the source is
+  #                     promoted (8 -> 16 by zero-extension) or
+  #                     demoted (16 -> 8 by png_set_strip_16).
+  #
+  # Output:
+  #   Returns a Libpng::DecodedImage. The :text, :color, :phys
+  #   metadata fields are populated via ChunkWalker (same as the
+  #   simplified path) so callers get the same metadata story
+  #   regardless of which decode path they use.
+  #
+  # One instance per decode call. Ractor-safe.
+  class StandardDecoder
+    # Read-state accumulator. The libpng read callback reads PNG bytes
+    # out of this; the offset advances with each call. Wrapping the
+    # state in a small struct keeps the FFI::Function closure capture
+    # explicit (and the closure itself becomes trivially shareable
+    # because the struct's instance vars are not mutated outside the
+    # callback).
+    ReadState = Struct.new(:bytes, :offset, keyword_init: true)
+
+    # PNG file signature: 8 bytes.
+    SIGNATURE_BYTES = [137, 80, 78, 71, 13, 10, 26, 10].freeze
+
+    def initialize(png, pixel_format: 'RGBA', bit_depth: 8)
+      raise Error, 'input PNG buffer is nil' if png.nil?
+      raise Error, 'input PNG buffer must be a String' unless png.is_a?(String)
+      raise Error, 'input is too short to be a PNG' if png.bytesize < 8
+      raise Error, 'input is not a PNG (bad signature)' unless png.bytes.first(8) == SIGNATURE_BYTES
+
+      @png = png
+      @pixel_format_sym = coerce_pixel_format(pixel_format)
+      @target_bit_depth = bit_depth
+      raise Error, 'bit_depth must be 8 or 16' unless [8, 16].include?(@target_bit_depth)
+    end
+
+    # Returns a Libpng::DecodedImage.
+    def call
+      output = String.new.force_encoding('ASCII-8BIT')
+      state = ReadState.new(bytes: @png, offset: 0)
+      read_fn = make_read_fn(state)
+      error_fn = make_error_fn
+
+      png_ptr = FFI::Pointer.new(0)
+      info_ptr = FFI::Pointer.new(0)
+      begin
+        png_ptr = Libpng::Binding.png_create_read_struct(LIBPNG_VER_STRING_C, nil, error_fn, nil)
+        raise Error, 'png_create_read_struct returned NULL' if png_ptr.null?
+
+        info_ptr = Libpng::Binding.png_create_info_struct(png_ptr)
+        raise Error, 'png_create_info_struct returned NULL' if info_ptr.null?
+
+        # Read callback + flush (NULL); we read from memory, not a file.
+        Libpng::Binding.png_set_read_fn(png_ptr, nil, read_fn, nil)
+
+        Libpng::Binding.png_read_info(png_ptr, info_ptr)
+        width = Libpng::Binding.png_get_image_width(png_ptr, info_ptr)
+        height = Libpng::Binding.png_get_image_height(png_ptr, info_ptr)
+        src_bit_depth = Libpng::Binding.png_get_bit_depth(png_ptr, info_ptr)
+        src_color_type = Libpng::Binding.png_get_color_type(png_ptr, info_ptr)
+
+        apply_transforms(png_ptr, info_ptr, src_bit_depth, src_color_type)
+        # png_set_interlace_handling returns the pass count (1 for
+        # non-interlaced, 7 for Adam7). png_read_image handles the
+        # multi-pass accumulation automatically once this is set.
+        Libpng::Binding.png_set_interlace_handling(png_ptr)
+        Libpng::Binding.png_read_update_info(png_ptr, info_ptr)
+
+        row_bytes = Libpng::Binding.png_get_rowbytes(png_ptr, info_ptr)
+        out_size = row_bytes * height
+
+        FFI::MemoryPointer.new(:uint8, out_size) do |out_buf|
+          FFI::MemoryPointer.new(:pointer, height) do |rows|
+            height.times do |y|
+              rows.put_pointer(y * FFI.type_size(:pointer), out_buf + (y * row_bytes))
+            end
+            Libpng::Binding.png_read_image(png_ptr, rows)
+          end
+          output << out_buf.read_bytes(out_size)
+        end
+
+        Libpng::Binding.png_read_end(png_ptr, info_ptr)
+
+        metadata = walker_metadata
+        DecodedImage.new(
+          width: width,
+          height: height,
+          format: @pixel_format_sym.upcase.to_s,
+          pixels: output,
+          bit_depth: metadata[:bit_depth],
+          color_type: metadata[:color_type],
+          interlace: metadata[:interlace],
+          text: metadata[:text],
+          color: metadata[:color],
+          phys: metadata[:phys]
+        )
+      ensure
+        destroy(png_ptr, info_ptr)
+      end
+    end
+
+    private
+
+    def coerce_pixel_format(value)
+      sym = value.to_s.downcase.to_sym
+      raise Error, "unknown pixel_format #{value.inspect}" unless FORMAT_TO_COLOR_TYPE.key?(sym)
+      raise Error, 'pixel_format :palette is write-only' if sym == :palette
+
+      sym
+    end
+
+    # Apply libpng transforms based on the requested output format and
+    # the source's actual color type / bit depth. The ordering matters
+    # -- libpng documents the canonical sequence in libpng-manual.txt
+    # section "Reading PNG files step-by-step".
+    def apply_transforms(png_ptr, info_ptr, src_bit_depth, src_color_type)
+      # 1. Expand everything to 8-bit first (sub-8 gray + palette).
+      if src_bit_depth < 8
+        Libpng::Binding.png_set_expand(png_ptr)
+      elsif src_bit_depth == 16 && @target_bit_depth == 8
+        Libpng::Binding.png_set_strip_16(png_ptr)
+      end
+
+      target_color_type = FORMAT_TO_COLOR_TYPE[@pixel_format_sym]
+      src_has_alpha = src_color_type.anybits?(COLOR_MASK_ALPHA)
+      src_has_color = src_color_type.anybits?(COLOR_MASK_COLOR)
+      target_has_alpha = target_color_type.anybits?(COLOR_MASK_ALPHA)
+      target_has_color = target_color_type.anybits?(COLOR_MASK_COLOR)
+
+      # 2. Palette -> RGB (always; we don't expose palette output).
+      Libpng::Binding.png_set_palette_to_rgb(png_ptr) if src_color_type == COLOR_TYPE_PALETTE
+
+      # 3. tRNS -> explicit alpha (only meaningful when caller wants alpha).
+      if target_has_alpha && png_get_valid(png_ptr, info_ptr, PNG_INFO_TRNS).positive?
+        Libpng::Binding.png_set_tRNS_to_alpha(png_ptr)
+      end
+
+      # 4. Gray <-> RGB conversion.
+      if !src_has_color && target_has_color
+        Libpng::Binding.png_set_gray_to_rgb(png_ptr)
+      elsif src_has_color && !target_has_color
+        Libpng::Binding.png_set_rgb_to_gray(png_ptr, RGB_TO_GRAY_DEFAULT, -1.0, -1.0)
+      end
+
+      # 5. Add / strip alpha to match target.
+      if target_has_alpha && !src_has_alpha
+        # Add a fully-opaque alpha channel after the RGB bytes.
+        Libpng::Binding.png_set_add_alpha(png_ptr, 0xFF, FILLER_AFTER)
+      elsif !target_has_alpha && src_has_alpha
+        Libpng::Binding.png_set_strip_alpha(png_ptr)
+      end
+    end
+
+    def png_get_valid(png_ptr, info_ptr, flag)
+      Libpng::Binding.png_get_valid(png_ptr, info_ptr, flag)
+    end
+
+    def make_read_fn(state)
+      # Closure captures `state`. Reads up to `len` bytes into `dst`,
+      # starting from the current offset and advancing it.
+      FFI::Function.new(:void, %i[pointer pointer size_t]) do |_png_ptr, dst, len|
+        avail = state.bytes.bytesize - state.offset
+        n = [len, avail].min
+        if n.positive?
+          dst.write_bytes(state.bytes.byteslice(state.offset, n), 0, n)
+          state.offset += n
+        end
+        # If the caller asked for more than we have, libpng treats it as
+        # an error (premature EOF) and longjmps out via the error handler.
+      end
+    end
+
+    # libpng's standard error path uses setjmp/longjmp. We install an
+    # error_fn that raises a Ruby exception instead -- the raise itself
+    # unwinds the C stack via FFI's safety mechanisms (rb_protect-style).
+    def make_error_fn
+      FFI::Function.new(:void, %i[pointer string]) do |_png_ptr, msg|
+        raise Error, "libpng: #{msg}"
+      end
+    end
+
+    def walker_metadata
+      walker = ChunkWalker.new(@png)
+      ihdr = walker.ihdr_fields
+      {
+        bit_depth: ihdr[:bit_depth],
+        color_type: ihdr[:color_type],
+        interlace: ihdr[:interlace],
+        text: walker.text_chunks,
+        color: walker.color_chunks,
+        phys: walker.phys_chunk
+      }
+    rescue ChunkWalker::FormatError
+      {
+        bit_depth: nil, color_type: nil, interlace: nil,
+        text: {}, color: {}, phys: nil
+      }
+    end
+
+    def destroy(png_ptr, info_ptr)
+      return if png_ptr.null?
+
+      FFI::MemoryPointer.new(:pointer) do |pp|
+        pp.write_pointer(png_ptr)
+        FFI::MemoryPointer.new(:pointer) do |ip|
+          ip.write_pointer(info_ptr)
+          Libpng::Binding.png_destroy_read_struct(pp, ip, nil)
+        end
+      end
+    end
+  end
+end

data/lib/libpng/standard_encoder.rb

@@ -19,15 +19,32 @@ module Libpng
   #   palette:          Array of [r, g, b] or [r, g, b, a] for
   #                     pixel_format: :palette. 1..256 entries.
   #
+  # Metadata options (forwarded to MetadataWriter; written between
+  # IHDR/PLTE and png_write_png):
+  #   text:             Hash<String,String> of tEXt keyword -> value.
+  #                     Values with non-ASCII bytes use iTXt (UTF-8).
+  #   gamma:            Float file gamma (e.g. 0.45455 for sRGB).
+  #   srgb_intent:      Integer 0..3 (perceptual, relative-colorimetric,
+  #                     saturation, absolute-colorimetric).
+  #   chromaticities:   Hash with :white_point_x/y, :red_x/y,
+  #                     :green_x/y, :blue_x/y (each a Float 0..1).
+  #   icc_profile:      Hash with :name (String) and :data (binary
+  #                     String). libpng compresses via zlib internally.
+  #   phys:             Hash with :pixels_per_unit_x, :pixels_per_unit_y,
+  #                     and :unit (0 = unknown, 1 = meters).
+  #
   # One instance per encode call. Ractor-safe.
   class StandardEncoder
+    METADATA_KEYS = %i[text gamma srgb_intent chromaticities icc_profile phys].freeze
+
     def initialize(width, height, pixels,
                    pixel_format: 'RGBA',
                    filter: :default,
                    compression_level: 6,
                    interlace: :none,
                    bit_depth: 8,
-                   palette: nil)
+                   palette: nil,
+                   **metadata)
       @width = width
       @height = height
       @pixels = pixels
@@ -37,6 +54,7 @@ module Libpng
       @interlace_sym = interlace.to_sym
       @bit_depth = bit_depth
       @palette = palette
+      @metadata = metadata
       validate!
     end
 
@@ -61,6 +79,9 @@ module Libpng
                                      COMPRESSION_TYPE_DEFAULT, FILTER_TYPE_DEFAULT)
         apply_filter(png_ptr)
         apply_palette(png_ptr, info_ptr) if palette_format?
+        # Metadata writers run AFTER IHDR/PLTE and BEFORE png_write_png
+        # (which is what calls png_write_info -> emits all queued chunks).
+        MetadataWriter.apply(png_ptr, info_ptr, @metadata)
 
         FFI::MemoryPointer.new(:uint8, @pixels.bytesize) do |px|
           px.write_bytes(@pixels)
@@ -117,6 +138,7 @@ module Libpng
 
       validate_bit_depth!
       validate_palette! if palette_format?
+      MetadataWriter.validate!(@metadata)
       return unless @pixels.bytesize < expected_size
 
       raise Error,

data/lib/libpng/text_writer.rb

@@ -0,0 +1,105 @@
+# frozen_string_literal: true
+
+module Libpng
+  # One user-supplied text entry, normalized. The encoder decides
+  # whether to emit it as tEXt (Latin-1 ASCII) or iTXt (UTF-8 with
+  # potentially multibyte characters) based on whether the value
+  # contains non-ASCII bytes.
+  TextEntry = Struct.new(:key, :value, keyword_init: true) do
+    def compression
+      value.ascii_only? ? TEXT_COMPRESSION_NONE : TEXT_COMPRESSION_ITXT_KEY
+    end
+  end
+
+  # Writes an Array of TextEntry as a png_text array via png_set_text.
+  # All FFI allocations live inside the block; strings must outlive
+  # the png_set_text call, which copies their bytes into libpng's
+  # internal storage.
+  #
+  # The png_text struct layout is computed dynamically via
+  # FFI.type_size so the code is portable across 32-bit and 64-bit
+  # builds (though the gem currently only ships 64-bit binaries).
+  module TextWriter
+    module_function
+
+    def call(png_ptr, info_ptr, entries)
+      return if entries.empty?
+
+      struct_size = text_struct_size
+      FFI::MemoryPointer.new(:uint8, struct_size * entries.length) do |array|
+        entries.each_with_index do |entry, i|
+          populate_entry(array + (i * struct_size), entry)
+        end
+        Libpng::Binding.png_set_text(png_ptr, info_ptr, array, entries.length)
+      end
+    end
+
+    # png_text struct layout (computed once):
+    #   int   compression   (offset 0)
+    #   char* key           (after alignment)
+    #   char* text
+    #   size_t text_length
+    #   size_t itxt_length
+    #   char* lang
+    #   char* lang_key
+    def text_struct_size
+      int_size = FFI.type_size(:int)
+      ptr_size = FFI.type_size(:pointer)
+      sz_size = FFI.type_size(:size_t)
+      natural = ptr_size # both pointer and size_t align to pointer width
+      offset = align_up(int_size, natural)
+      2.times { offset += ptr_size } # key, text
+      2.times { offset += sz_size }  # text_length, itxt_length
+      2.times { offset += ptr_size } # lang, lang_key
+      align_up(offset, natural) # round up to natural struct alignment
+    end
+
+    def populate_entry(slot, entry)
+      int_size = FFI.type_size(:int)
+      ptr_size = FFI.type_size(:pointer)
+      sz_size = FFI.type_size(:size_t)
+      natural = ptr_size
+
+      slot.put_int(0, entry.compression)
+
+      # Allocate persistent C strings for key, text. These must
+      # outlive png_set_text; once that returns libpng has copied
+      # the bytes internally.
+      key_bytes = "#{entry.key.b}\x00"
+      val_bytes = "#{entry.value.b}\x00"
+      key_ptr = FFI::MemoryPointer.new(:uint8, key_bytes.bytesize, false)
+      key_ptr.write_bytes(key_bytes)
+      val_ptr = FFI::MemoryPointer.new(:uint8, val_bytes.bytesize, false)
+      val_ptr.write_bytes(val_bytes)
+
+      offset = align_up(int_size, natural)
+      slot.put_pointer(offset, key_ptr)
+      offset += ptr_size
+      slot.put_pointer(offset, val_ptr)
+      offset += ptr_size
+      put_size(slot, offset, entry.value.bytesize)
+      offset += sz_size
+      itxt_len = entry.value.ascii_only? ? 0 : entry.value.bytesize
+      put_size(slot, offset, itxt_len)
+      offset += sz_size
+      slot.put_pointer(offset, nil)
+      offset += ptr_size
+      slot.put_pointer(offset, nil)
+    end
+
+    # Write a size_t value to a slot at the given offset. FFI doesn't
+    # expose put_size_t directly; choose the right writer based on the
+    # platform's size_t width (8 bytes on 64-bit, 4 on 32-bit).
+    def put_size(slot, offset, value)
+      if FFI.type_size(:size_t) == 8
+        slot.put_uint64(offset, value)
+      else
+        slot.put_uint32(offset, value)
+      end
+    end
+
+    def align_up(value, alignment)
+      ((value + alignment - 1) / alignment) * alignment
+    end
+  end
+end

data/lib/libpng/version.rb

@@ -11,6 +11,6 @@ module Libpng
   # new libpng release. The iteration resets to 0 each time
   # LIBPNG_VERSION bumps.
   LIBPNG_VERSION = '1.6.58'
-  LIBPNG_RUBY_ITERATION = 4
+  LIBPNG_RUBY_ITERATION = 5
   VERSION = "#{LIBPNG_VERSION}.#{LIBPNG_RUBY_ITERATION}"
 end

data/lib/libpng.rb

@@ -31,6 +31,10 @@ module Libpng
   autoload :SimplifiedEncoder, 'libpng/simplified_encoder'
   autoload :SimplifiedDecoder, 'libpng/simplified_decoder'
   autoload :StandardEncoder, 'libpng/standard_encoder'
+  autoload :StandardDecoder, 'libpng/standard_decoder'
+  autoload :TextWriter, 'libpng/text_writer'
+  autoload :TextEntry, 'libpng/text_writer'
+  autoload :MetadataWriter, 'libpng/metadata_writer'
 
   # FFI bindings. Autoloaded so that requiring `libpng` is cheap and
   # does not dlopen libpng16.{so,dylib,dll} -- ext/extconf.rb needs to
@@ -134,6 +138,76 @@ module Libpng
     all: FILTER_ALL
   }.freeze
 
+  # ------------------------------------------------------------------
+  # PNG_TEXT_COMP_* (compression field of png_text struct).
+  # Used by the write path to choose tEXt / zTXt / iTXt output.
+  # libpng's own constants are PNG_TEXT_COMPRESSION_{NONE,zTXt,iTXt}_KEY;
+  # we use SCREAMING_SNAKE_CASE per Ruby convention.
+  # ------------------------------------------------------------------
+  TEXT_COMPRESSION_NONE      = -1 # tEXt
+  TEXT_COMPRESSION_ZTXT_KEY  = 0  # zTXt (zlib)
+  TEXT_COMPRESSION_ITXT_KEY  = 1  # iTXt (no compression by default)
+  TEXT_COMPRESSION_LAST      = 2  # marker; not used as a real value
+
+  TEXT_COMPRESSION_BY_NAME = {
+    text: TEXT_COMPRESSION_NONE,
+    ztxt: TEXT_COMPRESSION_ZTXT_KEY,
+    itxt: TEXT_COMPRESSION_ITXT_KEY
+  }.freeze
+
+  # ------------------------------------------------------------------
+  # sRGB rendering intents (png.h).
+  # ------------------------------------------------------------------
+  SRGB_INTENT_PERCEPTUAL            = 0
+  SRGB_INTENT_RELATIVE_COLORIMETRIC = 1
+  SRGB_INTENT_SATURATION            = 2
+  SRGB_INTENT_ABSOLUTE              = 3
+
+  # ------------------------------------------------------------------
+  # pHYs unit types (png.h).
+  # ------------------------------------------------------------------
+  PHYS_TYPE_UNKNOWN = 0
+  PHYS_TYPE_METER   = 1
+
+  # Meters-per-inch (1 inch = 0.0254 m). Used to convert pHYs pixels-per-meter
+  # to DPI: dpi = ppm * 0.0254.
+  INCH_PER_METER = 0.0254
+
+  # ------------------------------------------------------------------
+  # PNG_INFO_* bit flags (png.h). Returned by png_get_valid to test
+  # which chunks are present in an info_ptr. Renamed to SCREAMING_SNAKE
+  # to match Ruby convention; libpng uses mixed case (PNG_INFO_tRNS,
+  # PNG_INFO_bKGD, etc.) which doesn't pass Ruby style checks.
+  # ------------------------------------------------------------------
+  PNG_INFO_IHDR = 0x0001
+  PNG_INFO_PLTE = 0x0002
+  PNG_INFO_TRNS = 0x0004
+  PNG_INFO_BKGD = 0x0008
+  PNG_INFO_HIST = 0x0010
+  PNG_INFO_PHYS = 0x0020
+  PNG_INFO_OFFS = 0x0040
+  PNG_INFO_TIME = 0x0080
+  PNG_INFO_PCAL = 0x0100
+  PNG_INFO_SRGB = 0x0200
+  PNG_INFO_ICCP = 0x0400
+  PNG_INFO_SBIT = 0x0800
+  PNG_INFO_SPLT = 0x1000
+  PNG_INFO_IDAT = 0x2000
+  PNG_INFO_ACTL = 0x4000
+  PNG_INFO_EXIF = 0x8000
+  PNG_INFO_GAMA = 0x10000
+  PNG_INFO_CHRM = 0x20000
+
+  # png_set_rgb_to_gray error_action values.
+  RGB_TO_GRAY_DEFAULT    = 1 # silent
+  RGB_TO_GRAY_WARN       = 2 # warn on error
+  RGB_TO_GRAY_ERR        = 3 # raise error
+
+  # png_set_filler / png_set_add_alpha filler_position values.
+  # Matches png.h: PNG_FILLER_BEFORE = 0, PNG_FILLER_AFTER = 1.
+  FILLER_BEFORE = 0
+  FILLER_AFTER = 1
+
   # PNG_LIBPNG_VER_STRING. The C string passed as `user_png_ver` to
   # png_create_write_struct. libpng checks this against its compiled-in
   # version; mismatches return NULL. Must match the libpng16 binary we
@@ -174,15 +248,28 @@ module Libpng
     end
 
     # Encode raw pixels via the standard write API. Accepts filter,
-    # compression_level, interlace, bit_depth, and palette options.
-    # Emits only IHDR/IDAT/IEND directly (no chunk stripping needed).
+    # compression_level, interlace, bit_depth, and palette options,
+    # plus text/gamma/srgb_intent/chromaticities/icc_profile/phys
+    # metadata writers. Emits only the chunks libpng's standard path
+    # produces (no post-hoc stripping needed).
     def encode_standard(width, height, pixels, **opts)
       StandardEncoder.new(width, height, pixels, **opts).call
     end
 
-    # Decode a PNG buffer into raw pixels plus IHDR metadata.
+    # Decode a PNG buffer via libpng's simplified read API. Returns a
+    # DecodedImage with width/height/format/pixels plus IHDR fields
+    # and text/color/phys metadata (parsed via ChunkWalker).
     def decode(png, **opts)
       SimplifiedDecoder.new(png, **opts).call
     end
+
+    # Decode a PNG buffer via libpng's standard read API
+    # (png_create_read_struct -> png_read_info -> optional transforms
+    # -> png_read_image). Use this instead of `decode` when you need
+    # explicit control over which transforms apply. Returns a
+    # DecodedImage with the same metadata fields as `decode`.
+    def decode_standard(png, **opts)
+      StandardDecoder.new(png, **opts).call
+    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: libpng
 version: !ruby/object:Gem::Version
-  version: 1.6.58.4
+  version: 1.6.58.5
 platform: ruby
 authors:
 - Ribose Inc.
@@ -68,10 +68,13 @@ files:
 - lib/libpng/chunk_walker.rb
 - lib/libpng/decoded_image.rb
 - lib/libpng/error.rb
+- lib/libpng/metadata_writer.rb
 - lib/libpng/recipe.rb
 - lib/libpng/simplified_decoder.rb
 - lib/libpng/simplified_encoder.rb
+- lib/libpng/standard_decoder.rb
 - lib/libpng/standard_encoder.rb
+- lib/libpng/text_writer.rb
 - lib/libpng/version.rb
 - libpng.gemspec
 homepage: https://github.com/claricle/libpng-ruby