libpng 1.6.58.1-x86_64-darwin

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 16e5dd6d318b51cc13b34d8f5ca8489d3a757edb438a24393e44c482419ceddb
+  data.tar.gz: e11408d58731ad57c1b2b42762cd85310980d57f9792d91a5b351226fb3b62a1
+SHA512:
+  metadata.gz: 3ddce550352b62eddc513be6f63513152097f3ae29a38aca3b33f34fa97d7df0fb3827468686241f0527a64354a0e947e7530fe8d60cd219ad63d645bd2ac5c6
+  data.tar.gz: b12921336b664c0c0fa0ecab722e5a1a7d649498f5688a30238cebf8efa8e1f4f2ac0e2ce25d94fcc345732c6a443ae7057d0e9e20ef871b132ac49e85b11d1b

data/.github/workflows/build.yml

@@ -0,0 +1,190 @@
+name: build
+
+on:
+  push:
+    branches: [ main ]
+    paths-ignore:
+      - '*.adoc'
+  pull_request:
+  workflow_dispatch:
+
+concurrency:
+  group: '${{ github.workflow }}-${{ github.job }}-${{ github.head_ref || github.ref_name }}'
+  cancel-in-progress: true
+
+jobs:
+  prepare:
+    uses: metanorma/ci/.github/workflows/prepare-rake.yml@main
+
+  test:
+    name: Test on Ruby ${{ matrix.ruby.version }} ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+
+    needs: prepare
+    if: needs.prepare.outputs.push-for-tag != 'true'
+
+    continue-on-error: ${{ matrix.ruby.experimental }}
+    strategy:
+      fail-fast: false
+      max-parallel: 5
+      matrix: ${{ fromJson(needs.prepare.outputs.matrix) }}
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - uses: ruby/setup-ruby@master
+      with:
+        bundler-cache: true
+        ruby-version: ${{ matrix.ruby.version }}
+        rubygems: ${{ matrix.ruby.rubygems }}
+
+    # libpng's CMake needs cmake >= 3.10 and a working zlib. Both are
+    # pre-installed on GitHub Actions runners; this is just a sanity check.
+    - name: Install build tools
+      if: startsWith(matrix.os, 'ubuntu')
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y cmake ninja-build zlib1g-dev
+
+    - name: Install build tools (macOS)
+      if: startsWith(matrix.os, 'macos')
+      run: |
+        brew install cmake ninja
+
+    - name: Install build tools (Windows)
+      if: startsWith(matrix.os, 'windows')
+      uses: step-security/msvc-dev-cmd@v1
+
+    - run: bundle exec rake
+
+  build:
+    name: build ${{ matrix.os }}, ${{ matrix.ruby-version }}, ${{ matrix.platform }}
+    runs-on: ${{ matrix.os }}
+    needs: prepare
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            platform: any
+            ruby-version: ${{ needs.prepare.outputs.default-ruby-version }}
+          - os: ubuntu-latest
+            platform: x86_64-linux
+            ruby-version: ${{ needs.prepare.outputs.default-ruby-version }}
+          - os: ubuntu-24.04-arm
+            platform: aarch64-linux
+            ruby-version: ${{ needs.prepare.outputs.default-ruby-version }}
+          - os: windows-latest
+            platform: x64-mingw32
+            ruby-version: ${{ needs.prepare.outputs.default-ruby-version }}
+          - os: windows-latest
+            platform: x64-mingw-ucrt
+            ruby-version: ${{ needs.prepare.outputs.default-ruby-version }}
+          - os: windows-11-arm
+            platform: aarch64-mingw-ucrt
+            ruby-version: '3.4'
+          - os: macos-15-intel
+            platform: x86_64-darwin
+            ruby-version: ${{ needs.prepare.outputs.default-ruby-version }}
+          - os: macos-latest
+            platform: arm64-darwin
+            ruby-version: ${{ needs.prepare.outputs.default-ruby-version }}
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Setup Ruby
+      uses: ruby/setup-ruby@master
+      with:
+        ruby-version: ${{ matrix.ruby-version }}
+        bundler-cache: true
+
+    - name: Install build tools (Linux)
+      if: startsWith(matrix.os, 'ubuntu')
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y cmake ninja-build zlib1g-dev
+
+    - name: Install build tools (macOS)
+      if: startsWith(matrix.os, 'macos')
+      run: |
+        brew install cmake ninja
+
+    - name: Install build tools (Windows)
+      if: startsWith(matrix.os, 'windows')
+      uses: step-security/msvc-dev-cmd@v1
+      with:
+        arch: ${{ matrix.platform == 'aarch64-mingw-ucrt' && 'arm64' || 'x64' }}
+
+    - run: bundle exec rake gem:native:${{ matrix.platform }}
+
+    - uses: actions/upload-artifact@v4
+      with:
+        name: pkg-${{ matrix.platform }}
+        path: pkg/*.gem
+
+    - name: Install gem
+      run: gem install -b pkg/libpng-*.gem
+
+    - name: Test conversion
+      shell: bash
+      run: |
+        ruby -rlibpng -e 'png = Libpng.encode(2, 2, "\xff" * 16, pixel_format: "RGBA"); File.binwrite("test.png", png); puts Libpng.decode(png, pixel_format: "RGBA").inspect'
+
+  build_musl:
+    name: build ${{ matrix.platform }} (Alpine)
+    runs-on: ${{ matrix.os }}
+    needs: prepare
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            platform: x86_64-linux-musl
+          - os: ubuntu-24.04-arm
+            platform: aarch64-linux-musl
+
+    steps:
+    - uses: actions/checkout@v4
+
+    # Run the entire build inside an Alpine container via `docker run` rather
+    # than the workflow `container:` field. The latter only works on x64
+    # runners (Actions' JS runtime has no arm64-musl build), but arm64 Ubuntu
+    # runners can run arm64 Alpine images natively via Docker.
+    - name: Build in Alpine container
+      shell: bash
+      env:
+        PLATFORM: ${{ matrix.platform }}
+        RUBY_VERSION: ${{ needs.prepare.outputs.default-ruby-version }}
+      run: |
+        cat > /tmp/alpine-build.sh <<'BUILD_EOF'
+        #!/bin/sh
+        set -e
+        apk add --no-cache build-base cmake ninja git file zlib-dev
+        # The mounted /work volume is owned by the host runner user; git in
+        # the container (running as root) refuses to operate on it without
+        # this. Without it, `git ls-files` in the gemspec returns empty and
+        # the built gem is missing lib/libpng.rb.
+        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')
+        BUILD_EOF
+        chmod +x /tmp/alpine-build.sh
+        docker run --rm \
+          -v "$PWD:/work" \
+          -v /tmp/alpine-build.sh:/alpine-build.sh \
+          -w /work \
+          -e PLATFORM \
+          ruby:${RUBY_VERSION}-alpine \
+          /alpine-build.sh
+
+    - uses: actions/upload-artifact@v4
+      with:
+        name: pkg-${{ matrix.platform }}
+        path: pkg/*.gem

data/.github/workflows/release.yml

@@ -0,0 +1,281 @@
+name: release
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+    inputs:
+      bump-type:
+        description: 'What to bump before tagging'
+        type: choice
+        options:
+          - current
+          - iteration
+          - libpng
+        default: iteration
+      libpng-version:
+        description: 'New libpng version (required when bump-type=libpng, e.g. 1.6.49)'
+        type: string
+        required: false
+
+# contents: write is needed for workflow_dispatch to push the bump commit + tag.
+# id-token: write is required for RubyGems.org Trusted Publishing (OIDC).
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  bump:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    outputs:
+      sha: ${{ steps.sha.outputs.sha }}
+      new-version: ${{ steps.bump.outputs.new-version }}
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@master
+        with:
+          ruby-version: '3.3'
+
+      - name: Bump version.rb
+        id: bump
+        shell: bash
+        env:
+          BUMP_TYPE: ${{ inputs.bump-type }}
+          LIBPNG_VERSION_INPUT: ${{ inputs.libpng-version }}
+        run: |
+          set -euo pipefail
+
+          if [[ "$BUMP_TYPE" == "current" ]]; then
+            NEW_VERSION=$(ruby -Ilib -rlibpng/version -e 'puts Libpng::VERSION')
+            echo "new-version=${NEW_VERSION}" >> "$GITHUB_OUTPUT"
+            echo "sha=${{ github.sha }}" >> "$GITHUB_OUTPUT"
+            echo "Releasing current VERSION (${NEW_VERSION}) -- no bump."
+            exit 0
+          fi
+
+          ruby <<'RUBY'
+            bump_type = ENV.fetch("BUMP_TYPE")
+            path = "lib/libpng/version.rb"
+            content = File.read(path)
+
+            case bump_type
+            when "iteration"
+              m = %r{LIBPNG_RUBY_ITERATION = (\d+)}.match(content) or
+                raise "Could not find LIBPNG_RUBY_ITERATION in #{path}"
+              content.sub!(%r{LIBPNG_RUBY_ITERATION = \d+},
+                           "LIBPNG_RUBY_ITERATION = #{m[1].to_i + 1}") or
+                raise "Failed to substitute iteration"
+            when "libpng"
+              new_v = ENV.fetch("LIBPNG_VERSION_INPUT", "")
+              raise "libpng-version input is required when bump-type=libpng" if new_v.empty?
+              raise "Invalid version format: #{new_v} (expected X.Y.Z)" unless new_v.match?(/\A\d+\.\d+\.\d+\z/)
+              content.sub!(%r{LIBPNG_VERSION = "[^"]+"},
+                           "LIBPNG_VERSION = \"#{new_v}\"") or
+                raise "Failed to substitute libpng version"
+              content.sub!(%r{LIBPNG_RUBY_ITERATION = \d+},
+                           "LIBPNG_RUBY_ITERATION = 0") or
+                raise "Failed to reset iteration"
+            else
+              raise "Unknown bump-type: #{bump_type}"
+            end
+
+            File.write(path, content)
+            load File.expand_path(path)
+            File.open(ENV.fetch("GITHUB_OUTPUT"), "a") do |f|
+              f.puts "new-version=#{Libpng::VERSION}"
+            end
+            warn "Bumped to #{Libpng::VERSION}"
+          RUBY
+
+          NEW_VERSION=$(ruby -Ilib -rlibpng/version -e 'puts Libpng::VERSION')
+          echo "new-version=${NEW_VERSION}" >> "$GITHUB_OUTPUT"
+
+          git config user.name  "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add lib/libpng/version.rb
+          git commit -m "Release v${NEW_VERSION}"
+          echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
+      - name: Show what's being released
+        run: |
+          echo "Releasing version: ${{ steps.bump.outputs.new-version }}"
+          git --no-pager log --oneline -1 "${{ steps.bump.outputs.sha }}"
+
+      - name: Push bump commit + tag
+        env:
+          NEW_VERSION: ${{ steps.bump.outputs.new-version }}
+          SHA: ${{ steps.bump.outputs.sha }}
+        run: |
+          if [[ -n "${SHA}" && "${SHA}" != "${{ github.sha }}" ]]; then
+            git push origin "HEAD:${{ github.event.repository.default_branch }}"
+          fi
+          git tag "v${NEW_VERSION}" "${SHA}"
+          git push origin "v${NEW_VERSION}"
+
+  build:
+    needs: bump
+    if: always() && !cancelled() && !failure() && (needs.bump.result == 'success' || needs.bump.result == 'skipped')
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            platform: any
+            ruby-version: '3.3'
+          - os: ubuntu-latest
+            platform: x86_64-linux
+            ruby-version: '3.3'
+          - os: ubuntu-24.04-arm
+            platform: aarch64-linux
+            ruby-version: '3.3'
+          - os: windows-latest
+            platform: x64-mingw32
+            ruby-version: '3.3'
+          - os: windows-latest
+            platform: x64-mingw-ucrt
+            ruby-version: '3.3'
+          - os: windows-11-arm
+            platform: aarch64-mingw-ucrt
+            ruby-version: '3.4'
+          - os: macos-15-intel
+            platform: x86_64-darwin
+            ruby-version: '3.3'
+          - os: macos-latest
+            platform: arm64-darwin
+            ruby-version: '3.3'
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.bump.outputs.sha || github.ref }}
+
+      - uses: ruby/setup-ruby@master
+        with:
+          ruby-version: ${{ matrix.ruby-version }}
+          bundler-cache: true
+
+      - name: Install build tools (Linux)
+        if: startsWith(matrix.os, 'ubuntu')
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake ninja-build zlib1g-dev
+
+      - name: Install build tools (macOS)
+        if: startsWith(matrix.os, 'macos')
+        run: |
+          brew install cmake ninja
+
+      - name: Install build tools (Windows)
+        if: startsWith(matrix.os, 'windows')
+        uses: step-security/msvc-dev-cmd@v1
+        with:
+          arch: ${{ matrix.platform == 'aarch64-mingw-ucrt' && 'arm64' || 'x64' }}
+
+      - run: bundle exec rake gem:native:${{ matrix.platform }}
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pkg-${{ matrix.platform }}
+          path: pkg/*.gem
+
+      - name: Install gem
+        run: gem install -b pkg/libpng-*.gem
+
+      - name: Test conversion
+        shell: bash
+        run: |
+          ruby -rlibpng -e 'png = Libpng.encode(2, 2, "\xff" * 16, pixel_format: "RGBA"); puts Libpng.decode(png, pixel_format: "RGBA").inspect'
+
+  build_musl:
+    needs: bump
+    if: always() && !cancelled() && !failure() && (needs.bump.result == 'success' || needs.bump.result == 'skipped')
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - os: ubuntu-latest
+            platform: x86_64-linux-musl
+          - os: ubuntu-24.04-arm
+            platform: aarch64-linux-musl
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.bump.outputs.sha || github.ref }}
+
+      - name: Build in Alpine container
+        shell: bash
+        env:
+          PLATFORM: ${{ matrix.platform }}
+        run: |
+          cat > /tmp/alpine-build.sh <<'BUILD_EOF'
+          #!/bin/sh
+          set -e
+          apk add --no-cache build-base cmake ninja git file zlib-dev
+          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')
+          BUILD_EOF
+          chmod +x /tmp/alpine-build.sh
+          docker run --rm \
+            -v "$PWD:/work" \
+            -v /tmp/alpine-build.sh:/alpine-build.sh \
+            -w /work \
+            -e PLATFORM \
+            ruby:3.3-alpine \
+            /alpine-build.sh
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pkg-${{ matrix.platform }}
+          path: pkg/*.gem
+
+  publish:
+    needs: [ bump, build, build_musl ]
+    if: always() && !cancelled() && !failure()
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.bump.outputs.sha || github.ref }}
+
+      - uses: ruby/setup-ruby@master
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: pkg-*
+          path: pkg
+          merge-multiple: true
+
+      - name: Configure RubyGems credentials (Trusted Publishing / OIDC)
+        uses: rubygems/configure-rubygems-credentials@main
+
+      - name: Publish to rubygems.org
+        shell: bash
+        run: |
+          set +e
+          for gem in pkg/*.gem; do
+            output=$(gem push -V "$gem" 2>&1)
+            rc=$?
+            if [ $rc -eq 0 ]; then
+              echo "$output"
+              continue
+            fi
+            # RubyGems rejects re-pushing the same version with 422, even for
+            # identical content. Tolerate that so we can publish newly-added
+            # platform variants at a version whose source gem already exists.
+            if echo "$output" | grep -qE "already (exists|pushed)|Conflict|Repushing"; then
+              echo "Skip $(basename "$gem") (already published)"
+              continue
+            fi
+            echo "$output" >&2
+            exit 1
+          done

data/.gitignore

@@ -0,0 +1,17 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+/ports/
+/lib/libpng/*.so
+/lib/libpng/*.so.*
+/lib/libpng/*.dylib
+/lib/libpng/*.dll
+/.idea/
+/.vscode/
+*.gem

data/.rspec

@@ -0,0 +1,3 @@
+RSpec
+--format documentation
+--color

data/.rubocop.yml

@@ -0,0 +1,39 @@
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 2.7
+  SuggestExtensions: false
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+# The wrapper is by nature a single file with FFI declarations + several
+# methods that walk libpng's chunked API; splitting would obscure the
+# 1-to-1 mapping with the C API.
+Metrics/AbcSize:
+  Max: 60
+Metrics/ClassLength:
+  Max: 200
+Metrics/CyclomaticComplexity:
+  Max: 20
+Metrics/MethodLength:
+  Max: 50
+Metrics/ModuleLength:
+  Max: 250
+Metrics/PerceivedComplexity:
+  Max: 20
+Metrics/ParameterLists:
+  Max: 7
+
+Metrics/BlockLength:
+  Exclude:
+    - spec/**/*.rb
+    - Rakefile
+    - libpng.gemspec
+
+Style/SpecialGlobalVars:
+  Exclude:
+    - ext/extconf.rb
+Style/FrozenStringLiteralComment:
+  Exclude:
+    - ext/extconf.rb
+    - lib/libpng/recipe.rb

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,108 @@
+= 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
+
+The gem downloads a pre-compiled binary for your platform automatically.
+No C compiler, libpng development headers, or system packages are needed
+at install time.
+
+== 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
+
+=== 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)
+
+`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).
+
+== 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:
+
+  r = Ractor.new do
+    Libpng.encode(2, 2, "\xFF" * 16, pixel_format: "RGBA")
+  end
+  r.take  # => PNG binary
+
+== Versioning
+
+This gem follows a `{LIBPNG_VERSION}.{ITERATION}` scheme:
+
+- `LIBPNG_VERSION` is the upstream libpng release the gem is built
+  against (currently 1.6.48).
+- `ITERATION` is a counter that bumps on Ruby-side changes (recipe bug
+  fixes, CI tweaks, doc updates). It resets to 0 each time
+  `LIBPNG_VERSION` bumps.
+
+For example, `1.6.48.0` is the first release against libpng 1.6.48,
+`1.6.48.1` is a Ruby-side fix, and `1.6.49.0` would be a release against
+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.
+2. `lib/libpng/recipe.rb` -- a MiniPortileCMake recipe that downloads
+   the libpng source tarball and runs CMake to produce the shared
+   library. This is invoked by `ext/extconf.rb` when the gem is installed
+   from source.
+3. `Rakefile` defines `gem:native:<platform>` tasks that pre-compile
+   the gem for each target platform. The pre-compiled gems bundle the
+   `.so`/`.dylib`/`.dll` and disable `extconf.rb`, so installation
+   requires no C compiler.
+
+== 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].