libpng 1.6.58.4-aarch64-linux-ohos

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/Gemfile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+gemspec
+
+group :development do
+  gem 'rake', '~> 13.0'
+  gem 'rspec', '~> 3.13'
+  gem 'rubocop', '~> 1.65', require: false
+  gem 'rubocop-performance', require: false
+end

data/LICENSE.txt

@@ -0,0 +1,27 @@
+Copyright (c) 2026 Ribose Inc.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in the
+   documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+
+This gem bundles pre-compiled binaries of libpng, which is itself
+distributed under the libpng license (see the upstream LICENSE file
+in https://github.com/pnggroup/libpng for details).

data/README.adoc

@@ -0,0 +1,238 @@
+= libpng: pre-compiled libpng for Ruby
+
+image:https://img.shields.io/badge/Ruby-%3E%3D%202.7.0-ruby.svg[Ruby]
+image:https://img.shields.io/badge/license-BSD--2--Clause-blue.svg[License]
+
+`libpng` is a Ruby binding for the official PNG reference library
+(https://github.com/pnggroup/libpng[libpng]). The native shared library
+is pre-compiled for each target platform and shipped inside the gem, so
+`gem install libpng` Just Works without a C compiler on the host.
+
+== Installation
+
+Add to your Gemfile:
+
+  gem "libpng"
+
+Then:
+
+  bundle install
+
+Or install manually:
+
+  gem install libpng
+
+RubyGems automatically selects the pre-compiled gem that matches your
+platform. No C compiler, libpng development headers, or system packages
+are required at install time when a binary gem is available. The
+platform-agnostic `ruby` gem is the fallback: it downloads the libpng
+source tarball at install time and compiles it via CMake (requires
+`cmake`, `ninja`, and zlib headers).
+
+== Supported platforms
+
+The following 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"]
+|===
+| Gem platform | Target | Build host
+| `ruby` (source) | Any platform (compiles on install) | n/a
+| `x86_64-linux` | x86_64 Linux (glibc) | `ubuntu-latest`
+| `x86_64-linux-musl` | x86_64 Linux (musl, e.g. Alpine) | `ruby:<ver>-alpine` on x86_64
+| `aarch64-linux` | ARM64 Linux (glibc) | `ubuntu-24.04-arm` (native)
+| `aarch64-linux-musl` | ARM64 Linux (musl) | `ruby:<ver>-alpine` on arm64
+| `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)
+| `x86_64-darwin` | Intel macOS | `macos-15-intel`
+| `arm64-darwin` | Apple Silicon macOS | `macos-latest`
+|===
+
+== Usage
+
+  require "libpng"
+
+  # Encode raw RGBA pixels (row-major, top-down) as a PNG.
+  png = Libpng.encode(width, height, rgba_bytes, pixel_format: "RGBA")
+  File.binwrite("out.png", png)
+
+  # 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.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
+
+- `"GRAY"` / `"GRAYSCALE"` -- 8-bit grayscale (1 byte/pixel)
+- `"GA"` / `"AG"` -- 8-bit grayscale + alpha (2 bytes/pixel)
+- `"RGB"`, `"BGR"` -- 8-bit truecolor (3 bytes/pixel)
+- `"RGBA"`, `"ARGB"`, `"BGRA"`, `"ABGR"` -- 8-bit truecolor + alpha (4 bytes/pixel)
+
+=== Encoding options
+
+  Libpng.encode(width, height, pixels,
+                pixel_format: "RGBA",
+                convert_to_8bit: false,
+                strip_colorspace: true)
+
+`convert_to_8bit: true`:: causes libpng to convert 16-bit input to 8-bit
+on write (input is still passed as a packed byte buffer; use this if you
+have packed 16-bit-per-channel data).
+
+`strip_colorspace: true`:: (default) walks the PNG chunk list after
+encode and keeps only `IHDR`, `IDAT`, and `IEND`, dropping the sRGB/gAMA
+chunks libpng's simplified API emits by default. This matches the
+"classic" libpng write path (e.g. libemf2svg) and produces byte-identical
+output. Set to `false` to keep the ancillary color chunks.
+
+=== Standard API (encode_standard)
+
+For parity with libpng's classic write path -- the same code path used
+by `libemf2svg`'s `rgb2png` -- use `encode_standard` instead of
+`encode`. It calls `png_create_write_struct` + `png_set_IHDR` +
+`png_set_rows` + `png_write_png(PNG_TRANSFORM_IDENTITY)` directly.
+
+  Libpng.encode_standard(width, height, pixels,
+                         pixel_format: "RGBA",
+                         filter: :default,
+                         compression_level: 6,
+                         interlace: :none,
+                         bit_depth: 8,
+                         palette: nil)
+
+`pixel_format`:: `:gray`, `:ga`, `:rgb`, `:rgba`, or `:palette`. The
+byte-order variants (`BGR`, `ARGB`, `BGRA`, `ABGR`) are simplified-API
+only -- the standard API always emits host-order.
+
+`filter`:: `:default` (adaptive -- libpng picks the best filter per
+row, the libemf2svg default), `:adaptive` (same output, exercises a
+different libpng code path), `:none`, `:sub`, `:up`, `:avg`, `:paeth`,
+`:all`.
+
+`compression_level`:: zlib level 0-9. Default 6 (Z_DEFAULT_COMPRESSION,
+matching libemf2svg).
+
+`interlace`:: `:none` (default) or `:adam7`.
+
+`bit_depth`:: 8 (default) or 16. Only valid for `:gray`, `:rgb`,
+`:rgba`. 16-bit callers must provide 2 bytes per channel
+(host-order little-endian). Always 8 for `:palette`.
+
+`palette`:: Array of `[r, g, b]` or `[r, g, b, a]` (1..256 entries).
+Required when `pixel_format: :palette`. If any entry has alpha, a `tRNS`
+chunk is emitted.
+
+Output is written directly into a Ruby String via `png_set_write_fn` --
+no `Tempfile`, no disk I/O. The FFI write callback is held on a local
+`Array` so it survives the libpng calls.
+
+Differences from `encode`:
+- Emits only `IHDR` / `IDAT` / `IEND` (no post-hoc chunk stripping
+  needed).
+- Supports palette, 16-bit, and interlaced output -- simplified API
+  doesn't.
+- Errors are raised via a `png_set_error_fn` callback (set on
+  `png_create_write_struct`). libpng expects error callbacks to
+  longjmp; we rb_raise instead, which unwinds the Ruby stack. The
+  `ensure` block calls `png_destroy_write_struct` to release the C
+  state.
+
+== Ractor safety
+
+`Libpng.encode` and `Libpng.decode` are Ractor-safe. Every call
+allocates and frees its own libpng `png_image`; no shared mutable state
+exists on the Ruby side. Calls from multiple Ractors run concurrently
+without locking.
+
+Example (Ruby 3.x uses `Ractor#take`; Ruby 4.0+ uses `Ractor#value`):
+
+  r = Ractor.new do
+    Libpng.encode(2, 2, "\xFF" * 16, pixel_format: "RGBA")
+  end
+  r.take   # Ruby 3.x
+  r.value  # Ruby 4.0+ (Ractor#take was removed in 4.0)
+
+== Versioning
+
+This gem follows a `{LIBPNG_VERSION}.{ITERATION}` scheme:
+
+- `LIBPNG_VERSION` is the upstream libpng release the gem is built
+  against (currently `1.6.58`).
+- `ITERATION` is a counter that bumps on Ruby-side changes (recipe bug
+  fixes, CI tweaks, doc updates). It resets to 0 each time
+  `LIBPNG_VERSION` bumps.
+
+For example, `1.6.58.0` is the first release against libpng 1.6.58,
+`1.6.58.1` is a Ruby-side fix, and `1.6.59.0` would be a release against
+the next upstream libpng.
+
+== How it works
+
+The gem has three layers:
+
+1. `lib/libpng.rb` -- Ruby FFI wrapper. Loads `libpng16.{so,dylib,dll}`
+   from the gem's `lib/libpng/` directory at runtime and exposes
+   `Libpng.encode` / `Libpng.decode` against libpng's "simplified"
+   high-level C API (`png_image_*`). The wrapper manually lays out the
+   `png_image` struct via explicit byte offsets into an
+   `FFI::MemoryPointer` rather than `FFI::Struct`, because `FFI::Struct`
+   carries class-level state that is not shareable across non-main
+   Ractors.
+
+2. `lib/libpng/recipe.rb` -- a `MiniPortileCMake` recipe that downloads
+   the libpng source tarball pinned by `LIBPNG_URL` / `LIBPNG_SHA256`,
+   runs CMake with `PNG_SHARED=ON PNG_STATIC=OFF PNG_TESTS=OFF`, and
+   copies the resulting shared lib into `lib/libpng/`. Invoked only when
+   installing the **source** (`ruby` platform) gem.
+
+3. `ext/extconf.rb` -- gem extension entry point. Calls `Recipe#cook_if_not`,
+   which is a no-op once the per-platform checkpoint file
+   (`ports/.../<name>-<ver>-<platform>.installed`) exists. After cooking,
+   emits a dummy `Makefile` via `mkmf` so RubyGems is satisfied (no Ruby
+   C extension is compiled). The pre-compiled platform gems unset
+   `spec.extensions`, so this never runs for them.
+
+=== Pre-compiled platform gems
+
+`Rakefile` defines `gem:native:<platform>` tasks for each target. Each
+task clones the gemspec, sets `spec.platform`, adds
+`lib/libpng/*.{dll,so,dylib}` to `spec.files`, removes the
+`mini_portile2` dependency (no longer needed at install time), and
+unsets `spec.extensions` -- the resulting gem installs with no compiler.
+
+The release workflow (`.github/workflows/release.yml`) builds all 10
+platforms in parallel on the appropriate native runner:
+
+- x86_64 Linux glibc -- `ubuntu-latest`
+- ARM64 Linux glibc -- `ubuntu-24.04-arm` (native)
+- x86_64 Linux musl -- `ruby:<ver>-alpine` via `docker run` on `ubuntu-latest`
+- ARM64 Linux musl -- `ruby:<ver>-alpine` via `docker run` on `ubuntu-24.04-arm`
+- x64 Windows (both MSVCRT and UCRT) -- `windows-latest` with `step-security/msvc-dev-cmd`
+- ARM64 Windows -- `windows-11-arm` (native) with `arch: arm64`
+- Intel macOS -- `macos-15-intel`
+- Apple Silicon macOS -- `macos-latest`
+
+Linux glibc and macOS builds run natively on the matching runner. Linux
+musl builds run inside `ruby:<ver>-alpine` containers via `docker run`
+rather than the workflow `container:` field, because Actions' JS runtime
+has no arm64-musl build and therefore cannot run Alpine containers on
+arm64 runners. Windows builds use the Visual Studio toolchain via
+`step-security/msvc-dev-cmd` (a maintained drop-in for the deleted
+`ilammy/msvc-dev-tools`).
+
+== License
+
+BSD-2-Clause; see link:LICENSE.txt[LICENSE.txt]. The gem bundles
+pre-compiled libpng binaries; libpng itself is distributed under the
+https://github.com/pnggroup/libpng/blob/main/LICENSE[libpng license].

data/Rakefile

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]
+
+task :compile do
+  require_relative 'ext/extconf'
+end
+
+task spec: :compile
+
+desc 'Build install-compilation gem'
+task 'gem:native:any' do
+  sh 'rake platform:any gem'
+end
+
+require 'rubygems/package_task'
+
+desc 'Define the gem task to build on any platform (compile on install)'
+task 'platform:any' do
+  spec = Gem::Specification.load('libpng.gemspec').dup
+  task = Gem::PackageTask.new(spec)
+  task.define
+end
+
+platforms = %w[
+  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
+]
+
+platforms.each do |platform|
+  desc "Build pre-compiled gem for the #{platform} platform"
+  task "gem:native:#{platform}" do
+    sh "rake compile platform:#{platform} gem target_platform=#{platform}"
+  end
+
+  desc "Define the gem task to build on the #{platform} platform (binary gem)"
+  task "platform:#{platform}" do
+    spec = Gem::Specification.load('libpng.gemspec').dup
+    spec.platform = Gem::Platform.new(platform)
+    spec.files += Dir.glob('lib/libpng/*.{dll,so,dylib}')
+    spec.extensions = []
+    spec.dependencies.reject! { |d| d.name == 'mini_portile2' }
+
+    task = Gem::PackageTask.new(spec)
+    task.define
+  end
+end
+
+require 'rake/clean'
+
+CLOBBER.include('pkg')
+CLEAN.include('ports',
+              'tmp',
+              'lib/libpng/*.dll',
+              'lib/libpng/*.dylib',
+              'lib/libpng/*.so',
+              'lib/libpng/*.so.*')

data/bin/console

@@ -0,0 +1,5 @@
+#!/bin/sh
+# frozen_string_literal: true
+
+# Console entry point for the libpng gem.
+exec ruby -Ilib -rlibpng -e 'puts "Libpng #{Libpng::VERSION} loaded"; binding.irb' "$@"

data/bin/setup

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'libpng'

data/ext/extconf.rb

@@ -0,0 +1,19 @@
+# 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 'mkmf'
+require 'libpng' # triggers autoload setup; Libpng::Recipe loads lazily
+
+recipe = Libpng::Recipe.new
+recipe.cook_if_not
+
+# RubyGems requires every extconf.rb to leave a Makefile behind, even if
+# no native extension is compiled (libpng is built by Recipe#cook above
+# and loaded via FFI at runtime). dummy_makefile satisfies that contract.
+create_makefile('libpng/dummy')