libpng 1.6.58.2 → 1.6.58.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd40beeea8a0333bc4f83c461da33eec3bb0ffdcf9982dc289efab87da554d17
-  data.tar.gz: d9d837770569d6fdc083d2d074138679c70b43eeac8f666f906fb44f053ec2ef
+  metadata.gz: 3764dc7e75c29be74bf732ba3d3ac4a66b17c4d20f5e1404f7d1d4fb4a7bff5d
+  data.tar.gz: 81d239f7c17eef66172e93543c949d1cee3a5d5bd281f997c3e26153e7beafe5
 SHA512:
-  metadata.gz: 621b7892d277ccdb0ab0535c38ee69c11b9e4b866e05ec7ef7248fd1df9bc4aa6f5a81a5b560eb67a6491ce00c76f853c3e7d3014273890d2dc9a11b76beb1a6
-  data.tar.gz: ec661e92e1f7c8b3ddeae8c2b43dc5ff9795ae2ee5aa34b344887134c605e54513b41209e19df74bc04d3bc4e63ed2524202b153841a724a98b48944515276e6
+  metadata.gz: 4d7d3caf69638aaf251a34631346007aed404d662a5d238dadf628b0f202ff2db51a751c6de310e76358c974c9b8d12207cb9f89f0f7c8b6d45fd47ae8d0a5be
+  data.tar.gz: aedc2495d938619919ba47c65fb1f54f3b38af2cddcf39d38fef0eb9464031d5dcdc3922f3e6230d2bf05c612e271c28e0878ef263b3200c5a15c14336453c97

data/.github/workflows/build.yml

@@ -143,6 +143,12 @@ jobs:
             platform: x86_64-linux-musl
           - os: ubuntu-24.04-arm
             platform: aarch64-linux-musl
+          # OHOS (OpenHarmony / Huawei HarmonyOS PC) is musl-based arm64.
+          # Built inside the same Alpine container as aarch64-linux-musl;
+          # the resulting binary is byte-compatible. Only the gem's
+          # platform label differs so RubyGems on OHOS selects it.
+          - os: ubuntu-24.04-arm
+            platform: aarch64-linux-ohos
 
     steps:
     - uses: actions/checkout@v4
@@ -168,12 +174,27 @@ jobs:
         git config --global --add safe.directory /work
         bundle install --jobs 4
         bundle exec rake "gem:native:${PLATFORM}"
-        gem install -b pkg/libpng-*.gem
-        # Smoke test from /tmp so bundler's source-tree LOAD_PATH doesn't
-        # shadow the installed gem. Activate via `gem` so RubyGems resolves
-        # the platform-specific binary gem (Alpine Ruby's platform string
-        # is *-linux-musl, which must match the gem's platform suffix).
-        (cd /tmp && ruby -e 'gem "libpng"; require "libpng"; png = Libpng.encode(2, 2, "\xff" * 16, pixel_format: "RGBA"); File.binwrite("test.png", png); puts Libpng.decode(png, pixel_format: "RGBA").inspect')
+        case "${PLATFORM}" in
+          *-ohos)
+            # OHOS gem is labeled aarch64-linux-ohos so RubyGems on OHOS
+            # selects it, but Alpine Ruby reports *-linux-musl -- a
+            # platform mismatch. The .so inside is musl-compatible, so
+            # unpack the gem and load it via -Ilib directly to verify
+            # the binary works without going through RubyGems install.
+            mkdir -p /tmp/ohos-smoke
+            gem unpack pkg/libpng-*.gem --target /tmp/ohos-smoke
+            (cd /tmp/ohos-smoke/libpng-* && \
+              ruby -Ilib -e 'require "libpng"; png = Libpng.encode(2, 2, "\xff" * 16, pixel_format: "RGBA"); puts Libpng.decode(png, pixel_format: "RGBA").inspect')
+            ;;
+          *)
+            gem install -b pkg/libpng-*.gem
+            # Smoke test from /tmp so bundler's source-tree LOAD_PATH doesn't
+            # shadow the installed gem. Activate via `gem` so RubyGems resolves
+            # the platform-specific binary gem (Alpine Ruby's platform string
+            # is *-linux-musl, which must match the gem's platform suffix).
+            (cd /tmp && ruby -e 'gem "libpng"; require "libpng"; png = Libpng.encode(2, 2, "\xff" * 16, pixel_format: "RGBA"); File.binwrite("test.png", png); puts Libpng.decode(png, pixel_format: "RGBA").inspect')
+            ;;
+        esac
         BUILD_EOF
         chmod +x /tmp/alpine-build.sh
         docker run --rm \

data/.github/workflows/release.yml

@@ -201,6 +201,10 @@ jobs:
             platform: x86_64-linux-musl
           - os: ubuntu-24.04-arm
             platform: aarch64-linux-musl
+          # OHOS: same Alpine-built musl arm64 binary as aarch64-linux-musl,
+          # packaged under a distinct platform label.
+          - os: ubuntu-24.04-arm
+            platform: aarch64-linux-ohos
     steps:
       - uses: actions/checkout@v4
         with:
@@ -218,8 +222,22 @@ jobs:
           git config --global --add safe.directory /work
           bundle install --jobs 4
           bundle exec rake "gem:native:${PLATFORM}"
-          gem install -b pkg/libpng-*.gem
-          (cd /tmp && ruby -e 'gem "libpng"; require "libpng"; png = Libpng.encode(2, 2, "\xff" * 16, pixel_format: "RGBA"); puts Libpng.decode(png, pixel_format: "RGBA").inspect')
+          case "${PLATFORM}" in
+            *-ohos)
+              # OHOS gem is labeled aarch64-linux-ohos so RubyGems on OHOS
+              # selects it, but Alpine Ruby reports *-linux-musl. The .so
+              # inside is musl-compatible -- unpack and load via -Ilib to
+              # verify the binary without going through RubyGems install.
+              mkdir -p /tmp/ohos-smoke
+              gem unpack pkg/libpng-*.gem --target /tmp/ohos-smoke
+              (cd /tmp/ohos-smoke/libpng-* && \
+                ruby -Ilib -e 'require "libpng"; png = Libpng.encode(2, 2, "\xff" * 16, pixel_format: "RGBA"); puts Libpng.decode(png, pixel_format: "RGBA").inspect')
+              ;;
+            *)
+              gem install -b pkg/libpng-*.gem
+              (cd /tmp && ruby -e 'gem "libpng"; require "libpng"; png = Libpng.encode(2, 2, "\xff" * 16, pixel_format: "RGBA"); puts Libpng.decode(png, pixel_format: "RGBA").inspect')
+              ;;
+          esac
           BUILD_EOF
           chmod +x /tmp/alpine-build.sh
           docker run --rm \

data/.gitignore

@@ -12,6 +12,8 @@
 /lib/libpng/*.so.*
 /lib/libpng/*.dylib
 /lib/libpng/*.dll
+/Makefile
+/lib/libpng/Makefile
 /.idea/
 /.vscode/
 *.gem

data/.rspec

@@ -1,3 +1,3 @@
-RSpec
 --format documentation
 --color
+--require spec_helper

data/.rubocop.yml

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

data/CHANGELOG.md

@@ -0,0 +1,127 @@
+# 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.4] - 2026-07-26
+
+### Added
+- `Libpng::ChunkWalker#text_chunks` -- parses `tEXt`, `zTXt`, and `iTXt`
+  chunks into a flat Hash of keyword -> UTF-8 String. zTXt values are
+  zlib-inflated; tEXt/zTXt values are transcoded from Latin-1 to UTF-8;
+  iTXt values stay UTF-8 (with optional compression). Malformed chunks
+  are silently skipped so a single broken entry doesn't poison the rest
+  of the decode.
+- `Libpng::ChunkWalker#color_chunks` -- parses `gAMA`, `cHRM`, `sRGB`,
+  and `iCCP` chunks into a Hash with Symbol keys (`:gamma`,
+  `:white_point_x/y`, `:red_x/y`, `:green_x/y`, `:blue_x/y`,
+  `:srgb_intent`, `:icc_profile_name`, `:icc_profile`). iCCP profiles
+  are zlib-decompressed into raw binary bytes for downstream ICC
+  libraries.
+- `Libpng::DecodedImage#text` and `#color` -- new keyword Struct fields,
+  populated by `Libpng.decode` via the new ChunkWalker accessors. Both
+  default to an empty Hash when the source PNG has no relevant chunks.
+- New platform: `aarch64-linux-ohos` (OpenHarmony / Huawei HarmonyOS PC).
+  OHOS is musl-based arm64 -- the resulting shared library is
+  byte-compatible with `aarch64-linux-musl`; only the gem's platform
+  label differs so RubyGems on OHOS selects the right variant. Built in
+  the same Alpine container as the musl gem.
+- Specs: 24 new specs across `spec/text_chunk_spec.rb` and
+  `spec/color_metadata_spec.rb` covering all 7 chunk types, malformed
+  input handling, Ractor moving, and end-to-end metadata exposure on
+  `DecodedImage`.
+
+## [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,110 @@
+# 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.
+
+11 platform gems are published per release (10 native + the source `ruby` gem). Native targets: `x86_64-linux`, `x86_64-linux-musl`, `aarch64-linux`, `aarch64-linux-musl`, `aarch64-linux-ohos`, `x64-mingw32`, `x64-mingw-ucrt`, `aarch64-mingw-ucrt`, `x86_64-darwin`, `arm64-darwin`.
+
+## 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: `#each_chunk`, `#ihdr_fields`, `#text_chunks` for tEXt/zTXt/iTXt, `#color_chunks` for gAMA/cHRM/sRGB/iCCP, `#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/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 (~105 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`, `aarch64-linux-ohos`, `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 11 platform gems (10 native + the source `ruby` gem), 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/text_chunk_spec.rb` — tEXt/zTXt/iTXt parsing
+- `spec/color_metadata_spec.rb` — gAMA/cHRM/sRGB/iCCP parsing
+- `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
+
+- `CHANGELOG.md` — release history
+- `REPORT-complex-api-needs.md` — historical report that drove `encode_standard`

data/README.adoc

@@ -31,8 +31,9 @@ source tarball at install time and compiles it via CMake (requires
 
 == 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]
+The following 11 pre-compiled platform gems are published for each
+release -- 10 native targets plus the platform-agnostic source (`ruby`)
+gem (see the link:https://rubygems.org/gems/libpng/versions[RubyGems versions page]
 for the current set):
 
 [cols="1,1,3", options="header"]
@@ -43,6 +44,7 @@ for the current set):
 | `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
+| `aarch64-linux-ohos` | ARM64 OpenHarmony / Huawei HarmonyOS PC | `ruby:<ver>-alpine` on arm64 (byte-compatible with `aarch64-linux-musl`)
 | `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)
@@ -60,10 +62,15 @@ for the current set):
 
   # Decode a PNG into raw pixels.
   decoded = Libpng.decode(File.binread("out.png"), pixel_format: "RGBA")
-  decoded.width   # => Integer
-  decoded.height  # => Integer
-  decoded.format  # => "RGBA"
-  decoded.pixels  # => binary String of RGBA bytes
+  decoded.width       # => Integer
+  decoded.height      # => Integer
+  decoded.format      # => "RGBA"
+  decoded.pixels      # => binary String of RGBA bytes
+  decoded.bit_depth   # => 8 (from IHDR)
+  decoded.color_type  # => 6 (PNG_COLOR_TYPE_RGB_ALPHA, from IHDR)
+  decoded.interlace   # => 0 (PNG_INTERLACE_NONE, from IHDR)
+  decoded.text        # => {"Title" => "Sunset", "Author" => "Jane"} (tEXt/zTXt/iTXt)
+  decoded.color       # => {:gamma => 0.45455, :srgb_intent => 0, ...} (gAMA/cHRM/sRGB/iCCP)
 
 === Supported pixel formats
 
@@ -94,33 +101,47 @@ output. Set to `false` to keep the ancillary color chunks.
 For parity with libpng's classic write path -- the same code path used
 by `libemf2svg`'s `rgb2png` -- use `encode_standard` instead of
 `encode`. It calls `png_create_write_struct` + `png_set_IHDR` +
-`png_set_rows` + `png_write_png(PNG_TRANSFORM_IDENTITY)` directly, with
-filter and zlib-compression control exposed:
+`png_set_rows` + `png_write_png(PNG_TRANSFORM_IDENTITY)` directly.
 
   Libpng.encode_standard(width, height, pixels,
                          pixel_format: "RGBA",
                          filter: :default,
-                         compression_level: 6)
+                         compression_level: 6,
+                         interlace: :none,
+                         bit_depth: 8,
+                         palette: nil)
 
-`pixel_format`:: `GRAY`, `GA`, `RGB`, or `RGBA` only. The byte-order
-variants (`BGR`, `ARGB`, `BGRA`, `ABGR`) are simplified-API only --
-the standard API always emits host-order.
+`pixel_format`:: `:gray`, `:ga`, `:rgb`, `:rgba`, or `:palette`. The
+byte-order variants (`BGR`, `ARGB`, `BGRA`, `ABGR`) are simplified-API
+only -- the standard API always emits host-order.
 
-`filter`:: One of `:default` (adaptive -- libpng picks the best filter
-per row, the libemf2svg default), `:adaptive` (same), `:none`, `:sub`,
-`:up`, `:avg`, `:paeth`, or `:all`.
+`filter`:: `:default` (adaptive -- libpng picks the best filter per
+row, the libemf2svg default), `:adaptive` (same output, exercises a
+different libpng code path), `:none`, `:sub`, `:up`, `:avg`, `:paeth`,
+`:all`.
 
 `compression_level`:: zlib level 0-9. Default 6 (Z_DEFAULT_COMPRESSION,
 matching libemf2svg).
 
+`interlace`:: `:none` (default) or `:adam7`.
+
+`bit_depth`:: 8 (default) or 16. Only valid for `:gray`, `:rgb`,
+`:rgba`. 16-bit callers must provide 2 bytes per channel
+(host-order little-endian). Always 8 for `:palette`.
+
+`palette`:: Array of `[r, g, b]` or `[r, g, b, a]` (1..256 entries).
+Required when `pixel_format: :palette`. If any entry has alpha, a `tRNS`
+chunk is emitted.
+
 Output is written directly into a Ruby String via `png_set_write_fn` --
 no `Tempfile`, no disk I/O. The FFI write callback is held on a local
-Array so it survives the libpng calls.
+`Array` so it survives the libpng calls.
 
 Differences from `encode`:
 - Emits only `IHDR` / `IDAT` / `IEND` (no post-hoc chunk stripping
   needed).
-- Standard API only -- no `convert_to_8bit` option.
+- Supports palette, 16-bit, and interlaced output -- simplified API
+  doesn't.
 - Errors are raised via a `png_set_error_fn` callback (set on
   `png_create_write_struct`). libpng expects error callbacks to
   longjmp; we rb_raise instead, which unwinds the Ruby stack. The

data/Rakefile

@@ -39,6 +39,7 @@ platforms = %w[
   x86_64-linux-musl
   aarch64-linux
   aarch64-linux-musl
+  aarch64-linux-ohos
   x86_64-darwin
   arm64-darwin
 ]

data/ext/extconf.rb

@@ -1,7 +1,14 @@
-$: << File.expand_path(File.join(File.dirname(__FILE__), '../lib'))
+# frozen_string_literal: true
+
+# extconf.rb is invoked by RubyGems when installing the source ('ruby'
+# platform) gem. It needs to find lib/libpng.rb on the load path so it
+# can trigger Libpng::Recipe autoload. We don't `require_relative`
+# because that pins to a specific path; instead we extend $LOAD_PATH
+# and let the normal autoload machinery do the work.
+$LOAD_PATH << File.expand_path(File.join(File.dirname(__FILE__), '../lib'))
 
-require 'libpng/recipe'
 require 'mkmf'
+require 'libpng' # triggers autoload setup; Libpng::Recipe loads lazily
 
 recipe = Libpng::Recipe.new
 recipe.cook_if_not

data/lib/libpng/binding.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require 'ffi'
+
+module Libpng
+  # FFI bindings to the bundled `libpng16.{so,dylib,dll}`. Lives in its
+  # own autoloaded module so that requiring `libpng` (the top-level
+  # entry point used by `ext/extconf.rb` during the source-gem build)
+  # does NOT eagerly dlopen the shared library -- it may not exist yet
+  # at that point.
+  #
+  # The first time an encoder or decoder references `Libpng::Binding`,
+  # this file loads, ffi_lib fires, and the FFI functions attach. From
+  # then on, calls go directly through the attached C functions.
+  module Binding
+    extend FFI::Library
+
+    ffi_lib_flags :now, :global
+
+    lib_filename = if FFI::Platform.windows?
+                     'libpng16.dll'
+                   elsif FFI::Platform.mac?
+                     'libpng16.dylib'
+                   else
+                     'libpng16.so'
+                   end
+
+    # __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,
+                    %i[pointer pointer pointer int pointer], :int
+    attach_function :png_image_write_to_memory,
+                    %i[pointer pointer pointer int pointer int pointer], :int
+    attach_function :png_image_free, [:pointer], :void
+
+    # libpng standard (non-simplified) write API.
+    attach_function :png_create_write_struct,
+                    %i[string pointer pointer pointer], :pointer
+    attach_function :png_create_info_struct, [:pointer], :pointer
+    attach_function :png_destroy_write_struct, %i[pointer pointer], :void
+    attach_function :png_set_IHDR,
+                    %i[pointer pointer uint32 uint32 int int int int int], :void
+    attach_function :png_set_rows, %i[pointer pointer pointer], :void
+    attach_function :png_set_PLTE, %i[pointer pointer pointer int], :void
+    attach_function :png_set_tRNS,
+                    %i[pointer pointer pointer int pointer], :void
+    attach_function :png_set_filter, %i[pointer int int], :void
+    attach_function :png_set_compression_level, %i[pointer int], :void
+    attach_function :png_set_write_fn,
+                    %i[pointer pointer pointer pointer], :void
+    attach_function :png_write_png, %i[pointer pointer int pointer], :void
+  end
+end

data/lib/libpng/bytes_per_pixel.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Libpng
+  # Maps pixel formats to bytes-per-pixel. Used by both the simplified
+  # and standard encoders / decoders to compute row stride.
+  #
+  # Pure data class -- no I/O, no allocations beyond the lookup itself.
+  module BytesPerPixel
+    # Per-channel byte count for the supported bit depths. Linear (16-bit)
+    # formats aren't currently exposed via the simplified API path; the
+    # standard encoder uses this table when bit_depth: 16 is requested.
+    CHANNEL_BYTES_8_BIT  = 1
+    CHANNEL_BYTES_16_BIT = 2
+
+    # Channels per PNG_COLOR_TYPE_* (png.h).
+    CHANNELS_BY_COLOR_TYPE = {
+      Libpng::COLOR_TYPE_GRAY => 1,
+      Libpng::COLOR_TYPE_GRAY_ALPHA => 2,
+      Libpng::COLOR_TYPE_RGB => 3,
+      Libpng::COLOR_TYPE_RGB_ALPHA => 4,
+      Libpng::COLOR_TYPE_PALETTE => 1
+    }.freeze
+
+    def self.for_format(format_value)
+      case format_value
+      when Libpng::FORMAT_GRAY then 1
+      when Libpng::FORMAT_GA, Libpng::FORMAT_AG then 2
+      when Libpng::FORMAT_RGB, Libpng::FORMAT_BGR then 3
+      when Libpng::FORMAT_RGBA, Libpng::FORMAT_ARGB,
+        Libpng::FORMAT_BGRA, Libpng::FORMAT_ABGR then 4
+      else
+        raise Libpng::Error, "no bytes-per-pixel mapping for format 0x#{format_value.to_s(16)}"
+      end
+    end
+
+    def self.for_color_type(color_type, bit_depth: 8)
+      channels = CHANNELS_BY_COLOR_TYPE[color_type] ||
+                 raise(Libpng::Error, "unknown color_type #{color_type}")
+      channel_bytes = bit_depth == 16 ? CHANNEL_BYTES_16_BIT : CHANNEL_BYTES_8_BIT
+      channels * channel_bytes
+    end
+  end
+end