libpng 1.6.58.4 → 1.6.58.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3764dc7e75c29be74bf732ba3d3ac4a66b17c4d20f5e1404f7d1d4fb4a7bff5d
-  data.tar.gz: 81d239f7c17eef66172e93543c949d1cee3a5d5bd281f997c3e26153e7beafe5
+  metadata.gz: fda67e6ac3b6280ed407565fc08a8166668093554afd534e33cf041d47900ecd
+  data.tar.gz: 060045bc45e2dc049d5957063a2dd045283b01f821666247b6a789638d35b277
 SHA512:
-  metadata.gz: 4d7d3caf69638aaf251a34631346007aed404d662a5d238dadf628b0f202ff2db51a751c6de310e76358c974c9b8d12207cb9f89f0f7c8b6d45fd47ae8d0a5be
-  data.tar.gz: aedc2495d938619919ba47c65fb1f54f3b38af2cddcf39d38fef0eb9464031d5dcdc3922f3e6230d2bf05c612e271c28e0878ef263b3200c5a15c14336453c97
+  metadata.gz: 253211e3494d116f6cf13e78b5688cf171b0c4f85817b2f818fb3d69cffaa4e025687c7e086885b27ea57c2083555097a99732f188464f786676224987e4a08c
+  data.tar.gz: adc29322d89eb94d2f978f57e82be6f59d2a9691c233cefc09552d0c021e11f3f438fe1a8aebb6da2df56db5acbc9b7e8c0a1ff9697815489505f80b2ddc592b

data/.github/workflows/build.yml

@@ -143,12 +143,6 @@ 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
@@ -174,27 +168,12 @@ jobs:
         git config --global --add safe.directory /work
         bundle install --jobs 4
         bundle exec rake "gem:native:${PLATFORM}"
-        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
+        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 \
@@ -208,4 +187,90 @@ jobs:
     - uses: actions/upload-artifact@v4
       with:
         name: pkg-${{ matrix.platform }}
+        path: pkg/*.gem
+
+  # OHOS (OpenHarmony / Huawei HarmonyOS PC) requires the official OHOS
+  # NDK to cross-compile. The NDK's clang and binary-sign-tool are x86_64
+  # ELF binaries; on this arm64 runner they run transparently via
+  # binfmt_misc + qemu-user-static. Verification (dockerharmony) runs
+  # natively because the arm64 rootfs matches the host architecture.
+  build_ohos:
+    name: build aarch64-linux-ohos (NDK)
+    runs-on: ubuntu-24.04-arm
+    needs: prepare
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install host-side tools
+      # These are used for: NDK setup (curl/jq/unzip), artifact prep
+      # (file), and dockerharmony verification (docker is preinstalled).
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y curl jq unzip file
+
+    - name: Register binfmt for amd64 docker emulation
+      # The OHOS NDK is x86_64-only. We run the entire build inside an
+      # amd64 docker container on this arm64 host -- docker's binfmt_misc
+      # registration handles the emulation transparently inside the
+      # container, with no library juggling on the host side.
+      run: docker run --privileged --rm tonistiigi/binfmt --install amd64
+
+    - name: Cache OHOS NDK
+      id: cache-ndk
+      uses: actions/cache@v4
+      with:
+        path: ext/ohos/ndk
+        key: ohos-ndk-${{ hashFiles('ext/ohos/setup-ndk.sh') }}
+
+    - name: Setup OHOS NDK (host-side; only curl/jq/unzip needed)
+      if: steps.cache-ndk.outputs.cache-hit != 'true'
+      run: sh ext/ohos/setup-ndk.sh --prefix ext/ohos/ndk
+
+    - name: Build OHOS gem in amd64 container
+      # The entire build (libpng + static zlib + signing) runs inside an
+      # amd64 docker container so the NDK's x86_64 clang + binary-sign-tool
+      # run natively (no qemu at the process level; docker's binfmt handles
+      # the container emulation as a whole).
+      run: |
+        docker run --rm --platform linux/amd64 \
+          -v "$PWD:/work" -w /work \
+          -e target_platform=aarch64-linux-ohos \
+          ruby:3.3 \
+          sh -c '
+            set -e
+            apt-get update
+            apt-get install -y --no-install-recommends cmake ninja-build zlib1g-dev
+            bundle install --jobs 4
+            bundle exec rake gem:native:aarch64-linux-ohos
+            # Confirm the .so was produced and is arm64 ELF (sanity).
+            file lib/libpng/libpng16.so
+          '
+
+    - name: Prepare dockerharmony artifacts (host-side)
+      # verify-prepare.sh cross-compiles smoke-test.c using the NDK clang.
+      # We run it inside the same amd64 container for the same reason.
+      run: |
+        docker run --rm --platform linux/amd64 \
+          -v "$PWD:/work" -w /work \
+          -e NDK_ROOT=/work/ext/ohos/ndk \
+          ruby:3.3 \
+          sh -c '
+            set -e
+            apt-get update
+            apt-get install -y --no-install-recommends file
+            sh ext/ohos/verify-prepare.sh
+          '
+
+    - name: Verify in dockerharmony (real OHOS userland, arm64-native)
+      run: |
+        docker pull ghcr.io/hqzing/dockerharmony:latest
+        docker run --rm \
+          -v "$PWD/ohos-verify:/work" \
+          -w /work \
+          ghcr.io/hqzing/dockerharmony:latest \
+          sh -c 'LD_LIBRARY_PATH=. ./smoke-test'
+
+    - uses: actions/upload-artifact@v4
+      with:
+        name: pkg-aarch64-linux-ohos
         path: pkg/*.gem

data/.github/workflows/release.yml

@@ -201,10 +201,6 @@ 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:
@@ -222,22 +218,8 @@ jobs:
           git config --global --add safe.directory /work
           bundle install --jobs 4
           bundle exec rake "gem:native:${PLATFORM}"
-          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
+          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 \
@@ -253,8 +235,79 @@ jobs:
           name: pkg-${{ matrix.platform }}
           path: pkg/*.gem
 
+  # OHOS NDK cross-compile. See build.yml's build_ohos job for full notes.
+  build_ohos:
+    needs: bump
+    if: always() && !cancelled() && !failure() && (needs.bump.result == 'success' || needs.bump.result == 'skipped')
+    runs-on: ubuntu-24.04-arm
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ needs.bump.outputs.sha || github.ref }}
+
+      - name: Install host-side tools
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y curl jq unzip file
+
+      - name: Register binfmt for amd64 docker emulation
+        run: docker run --privileged --rm tonistiigi/binfmt --install amd64
+
+      - name: Cache OHOS NDK
+        id: cache-ndk
+        uses: actions/cache@v4
+        with:
+          path: ext/ohos/ndk
+          key: ohos-ndk-${{ hashFiles('ext/ohos/setup-ndk.sh') }}
+
+      - name: Setup OHOS NDK
+        if: steps.cache-ndk.outputs.cache-hit != 'true'
+        run: sh ext/ohos/setup-ndk.sh --prefix ext/ohos/ndk
+
+      - name: Build OHOS gem in amd64 container
+        run: |
+          docker run --rm --platform linux/amd64 \
+            -v "$PWD:/work" -w /work \
+            -e target_platform=aarch64-linux-ohos \
+            ruby:3.3 \
+            sh -c '
+              set -e
+              apt-get update
+              apt-get install -y --no-install-recommends cmake ninja-build zlib1g-dev
+              bundle install --jobs 4
+              bundle exec rake gem:native:aarch64-linux-ohos
+              file lib/libpng/libpng16.so
+            '
+
+      - name: Prepare dockerharmony artifacts
+        run: |
+          docker run --rm --platform linux/amd64 \
+            -v "$PWD:/work" -w /work \
+            -e NDK_ROOT=/work/ext/ohos/ndk \
+            ruby:3.3 \
+            sh -c '
+              set -e
+              apt-get update
+              apt-get install -y --no-install-recommends file
+              sh ext/ohos/verify-prepare.sh
+            '
+
+      - name: Verify in dockerharmony (real OHOS userland)
+        run: |
+          docker pull ghcr.io/hqzing/dockerharmony:latest
+          docker run --rm \
+            -v "$PWD/ohos-verify:/work" \
+            -w /work \
+            ghcr.io/hqzing/dockerharmony:latest \
+            sh -c 'LD_LIBRARY_PATH=. ./smoke-test'
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: pkg-aarch64-linux-ohos
+          path: pkg/*.gem
+
   publish:
-    needs: [ bump, build, build_musl ]
+    needs: [ bump, build, build_musl, build_ohos ]
     if: always() && !cancelled() && !failure()
     runs-on: ubuntu-latest
     steps:

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,92 @@ 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.6] - 2026-07-26
+
+### Changed
+- **OHOS (`aarch64-linux-ohos`) is now cross-compiled with the official OHOS
+  NDK** (Huawei's `ohos.toolchain.cmake` + LLVM-19 clang), replacing the
+  1.6.58.4/.5 approach of shipping Alpine-built musl bytes labeled as OHOS.
+
+  The build runs on `ubuntu-24.04-arm`. The OHOS NDK clang is an x86_64
+  binary and runs transparently via `binfmt_misc` + `qemu-user-static`.
+  zlib is built statically with the same toolchain and linked into
+  `libpng16.so` (avoids the OHOS non-standard zlib SONAME
+  `libshared_libz.z.so`). The freshly built `.so` is code-signed with
+  `binary-sign-tool sign -selfSign 1` (mandatory for runtime loading on
+  production OHOS devices).
+
+  Verification: the signed `.so` is loaded by a smoke-test binary inside
+  real OHOS userland (the `dockerharmony` container running natively on
+  the same arm64 host -- no qemu). Build fails if the smoke test fails.
+
+### Added
+- `lib/libpng/ohos.rb`, `lib/libpng/ohos/{ndk,zlib_builder,code_signer,recipe}.rb`
+  -- OHOS cross-compile support. Lazy-loaded only when building for OHOS.
+  - `Libpng::OHOS::NDK` -- pure-data class for NDK path discovery.
+  - `Libpng::OHOS::ZlibBuilder < MiniPortileCMake` -- static zlib build.
+  - `Libpng::OHOS::CodeSigner` -- wraps `binary-sign-tool`.
+  - `Libpng::OHOS::Recipe < Libpng::Recipe` -- orchestrates the OHOS build.
+- `lib/libpng/recipe.rb`: `Recipe.for_target(platform)` factory -- OCP seam
+  that returns `OHOS::Recipe` for `*-ohos` targets, base `Recipe` otherwise.
+- `ext/ohos/setup-ndk.sh` -- downloads OHOS SDK + LLVM-19 via daily_build API
+  (adapted from ohos-node's `build.sh`).
+- `ext/ohos/smoke-test.c` -- minimal libpng round-trip test for dockerharmony.
+- `ext/ohos/verify-prepare.sh` -- cross-compiles smoke-test with NDK clang,
+  bundles signed `.so` + SONAME symlinks (fixes PR #12's symlink bug).
+- 49 new specs under `spec/ohos/` + `spec/recipe_factory_spec.rb`.
+
+### Caveats
+- The 1.6.58.4/.5 OHOS gems shipped Alpine-built bytes without NDK
+  verification. This version is the first with proper OHOS NDK
+  cross-compilation + signing.
+- Code signing uses `-selfSign 1` (self-signed). Sufficient for OHOS
+  userland load. Production deployment on Huawei-managed hardware may
+  require re-signing with an enrolled cert.
+
+### Superseded
+- PR #11 (closed) -- hand-written `toolchain.cmake` + system CMake. Replaced
+  by NDK's bundled `ohos.toolchain.cmake`.
+- PR #12 (closed) -- dockerharmony verification of Alpine bytes. The
+  verification step is reused here; the Alpine-built `.so` is replaced
+  with the NDK-built, signed one.
+
+## [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,20 +20,33 @@ 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/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 |
+| `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). Has `.for_target(platform)` factory -- OCP seam that returns `OHOS::Recipe` for `*-ohos`, base `Recipe` otherwise |
+| `lib/libpng/ohos.rb` | `Libpng::OHOS` namespace + autoloads. Lazy-loaded only when `Recipe.for_target` is called with an OHOS target |
+| `lib/libpng/ohos/ndk.rb` | `OHOS::NDK` -- pure-data class for NDK path discovery (toolchain/sysroot/clang/sign-tool). Idempotent `#download` via `setup-ndk.sh` |
+| `lib/libpng/ohos/zlib_builder.rb` | `OHOS::ZlibBuilder < MiniPortileCMake` -- builds `libz.a` statically with the OHOS toolchain |
+| `lib/libpng/ohos/code_signer.rb` | `OHOS::CodeSigner` -- wraps `binary-sign-tool sign -selfSign 1`. Pure-data `#sign_command` is testable without invoking the tool |
+| `lib/libpng/ohos/recipe.rb` | `OHOS::Recipe < Libpng::Recipe` -- orchestrates NDK setup, zlib build, libpng cross-compile with `ohos.toolchain.cmake`, and post-install signing |
+| `ext/extconf.rb` | Gem extension entry. Calls `Libpng::Recipe.for_target(ENV['target_platform']).new`, then emits a dummy Makefile |
+| `ext/ohos/setup-ndk.sh` | Downloads OHOS SDK + LLVM-19 via OpenHarmony daily_build API (adapted from ohos-node/build.sh). Idempotent |
+| `ext/ohos/smoke-test.c` | Minimal libpng round-trip test, cross-compiled with NDK clang and run inside dockerharmony |
+| `ext/ohos/verify-prepare.sh` | Cross-compiles smoke-test, bundles signed `.so` + SONAME symlinks for dockerharmony |
 
 ### 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.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 +71,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
@@ -69,6 +82,25 @@ 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`.
 
+### OHOS (`aarch64-linux-ohos`) build notes
+
+OHOS uses a dedicated `build_ohos` CI job (see `.github/workflows/build.yml`)
+that runs on `ubuntu-24.04-arm`. The NDK's clang and `binary-sign-tool` are
+x86_64 ELF and run via `binfmt_misc` + `qemu-user-static`. The job:
+
+1. Downloads OHOS SDK + LLVM-19 via `ext/ohos/setup-ndk.sh` (~1.5 GB, cached
+   across runs by `actions/cache@v4`).
+2. Runs `rake gem:native:aarch64-linux-ohos`, which delegates to
+   `Libpng::OHOS::Recipe` (sets up NDK, builds static zlib, cross-compiles
+   libpng with `ohos.toolchain.cmake`, signs the `.so`).
+3. Cross-compiles `ext/ohos/smoke-test.c` with NDK clang via
+   `verify-prepare.sh`, then runs it inside the `dockerharmony` container
+   (real OHOS userland) — build fails if smoke-test doesn't output `OK`.
+
+Local dev: `target_platform=aarch64-linux-ohos bundle exec rake compile`
+will only succeed on an arm64 host with `qemu-user-static` registered,
+because the NDK clang is x86_64 ELF. CI handles this automatically.
+
 ## Release process
 
 Releases are tag-triggered via `.github/workflows/release.yml`. Trigger with:
@@ -96,12 +128,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

@@ -44,7 +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`)
+| `aarch64-linux-ohos` | ARM64 OpenHarmony / Huawei HarmonyOS PC | `ubuntu-24.04-arm` + OHOS NDK (cross-compiled, signed, **verified in dockerharmony**)
 | `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)
@@ -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/TODO.ohos/01-architecture.md

@@ -0,0 +1,105 @@
+# 01 - Architecture
+
+## Goal
+
+Cross-compile `libpng16.so` for `aarch64-linux-ohos` using the official OHOS
+NDK (Huawei-blessed toolchain), code-sign it, and empirically verify it in
+real OHOS userland (dockerharmony). Replace the 1.6.58.4/.5/.6 approach of
+"Alpine-built bytes labeled as OHOS".
+
+## Why this design (vs PR #11 / PR #12)
+
+| Approach | Status | Why rejected |
+|---|---|---|
+| Alpine bytes labeled OHOS (1.6.58.4/.5) | shipped | unverified assumption; user flagged musl symbol visibility, TLS, pthread layout risks |
+| PR #11: hand-written `toolchain.cmake` + system CMake | closed | 5 CI iterations failed (sysroot path, missing zlib in sysroot, try_compile couldn't find crt objects) — root cause: NOT using NDK's bundled `ohos.toolchain.cmake` |
+| PR #12: Alpine bytes + dockerharmony verification | closed | still ships Alpine bytes labeled OHOS; user wants proper NDK bytes |
+| **PR #13 (this plan)** | current | NDK-bundled `ohos.toolchain.cmake` + static zlib + `binary-sign-tool` + dockerharmony verify |
+
+## Key insights from references
+
+- **OHOS CMake doc** (`openharmony-6.0-app-dev-docs/napi/build-with-ndk-cmake.md`):
+  - NDK ships own CMake at `${SDK_PATH}/native/build-tools/cmake/bin/cmake`
+  - Toolchain file at `${SDK_PATH}/native/build/cmake/ohos.toolchain.cmake`
+  - Invoke: `cmake -DOHOS_ARCH=arm64-v8a -DOHOS_PLATFORM=OHOS -DCMAKE_TOOLCHAIN_FILE=...`
+  - Toolchain handles sysroot + `--target=arm-linux-ohos` + try_compile compatibility
+
+- **ohos-node** (`~/src/external/ohos-node/build.sh`):
+  - NDK download via `https://dcp.openharmony.cn/api/daily_build/build/list/component`
+  - Two components needed: `ohos-sdk-public` (SDK + `binary-sign-tool`) + `LLVM-19` (clang + sysroot)
+  - `binary-sign-tool sign -selfSign 1` is mandatory post-build
+  - Output runs on OHOS via dockerharmony (real OHOS rootfs)
+
+- **dockerharmony** (`~/src/external/dockerharmony/`):
+  - OHOS rootfs (musl + toybox + mksh) in Docker, runs aarch64-linux-musl binaries natively on arm64 hosts
+  - OHOS ships zlib as `libshared_libz.z.so` (NOT `libz.so`) — patchelf needed if linking dynamically
+
+- **NDK architecture reality** (verified):
+  - `LLVM-19` tarball contains `llvm-linux-x86_64.tar.gz` (x86_64-build clang) + `ohos-sysroot.tar.gz` (architecture-independent sysroot files)
+  - There is **no arm64 build of the NDK clang** in the daily_build output
+  - `ohos.toolchain.cmake` is a CMake script (architecture-independent)
+  - `binary-sign-tool` is in the x86_64-build ohos-sdk
+
+## CI topology (corrected: native arm64 + transparent qemu for NDK binaries)
+
+Single job on `ubuntu-24.04-arm` (native arm64 runner):
+
+1. Install `qemu-user-static` + `binfmt-support` — registers binfmt_misc so
+   x86_64 ELF binaries run transparently via `qemu-x86_64`.
+2. Run `ext/ohos/setup-ndk.sh` → NDK + LLVM-19 in `ext/ohos/ndk/`
+3. `bundle exec rake gem:native:aarch64-linux-ohos` →
+   - `OHOS::Recipe#cook` runs:
+     - Downloads libpng source (MiniPortile)
+     - Builds static zlib via `OHOS::ZlibBuilder` (NDK clang under binfmt)
+     - CMake-configures libpng with `ohos.toolchain.cmake` + static zlib (NDK cmake/clang under binfmt)
+     - Builds + installs `libpng16.so`
+     - Signs `.so` via `OHOS::CodeSigner` (`binary-sign-tool` under binfmt)
+4. Run `ext/ohos/verify-prepare.sh` → `ohos-verify/` artifacts (cross-compile smoke-test with NDK clang)
+5. Run dockerharmony natively: `docker run --rm -v ...:/work ghcr.io/hqzing/dockerharmony:latest sh -c 'LD_LIBRARY_PATH=. ./smoke-test'`
+
+### Why this is the right topology
+
+| Aspect | x86_64 runner (original plan) | arm64 runner + qemu (revised) |
+|---|---|---|
+| NDK clang / binary-sign-tool | native speed | ~5x slower (qemu emulation) |
+| dockerharmony verification | ~5x slower (qemu binfmt for arm64) | **native speed** |
+| CI complexity | needs binfmt setup, multi-arch docker pull | standard docker pull |
+| Total CI time | dominated by slow dockerharmony emulation | dominated by slow NDK compile (smaller) |
+
+Compilation is ~1 min native → ~5 min under qemu (acceptable).
+dockerharmony smoke-test is ~50ms native → ~250ms under qemu — small absolute number,
+but the binfmt setup for arm64 emulation on x86_64 is finicky and has been flaky
+in CI historically. Native arm64 docker is rock-solid.
+
+**Net**: arm64 + qemu is simpler AND faster overall.
+
+## MECE file layout
+
+```
+ext/ohos/
+├── setup-ndk.sh           # Downloads SDK + LLVM-19 (idempotent, shell)
+├── smoke-test.c           # Round-trip test (kept from PR #12)
+├── verify-prepare.sh      # Cross-compiles smoke-test, bundles for dockerharmony
+└── (no toolchain.cmake — we use NDK's bundled ohos.toolchain.cmake)
+
+lib/libpng/
+├── recipe.rb              # Add Recipe.for_target factory (OCP seam)
+├── ohos.rb                # Module Libpng::OHOS + autoloads
+└── ohos/
+    ├── ndk.rb             # OHOS::NDK: pure-data path discovery + download
+    ├── zlib_builder.rb    # OHOS::ZlibBuilder < MiniPortileCMake (static zlib)
+    ├── code_signer.rb     # OHOS::CodeSigner: wraps binary-sign-tool
+    └── recipe.rb          # OHOS::Recipe < Libpng::Recipe
+
+lib/libpng.rb              # Add autoload :OHOS, 'libpng/ohos'
+ext/extconf.rb             # Use Recipe.for_target(...) factory
+```
+
+## OCP compliance
+
+Adding a new cross-compile platform = adding `lib/libpng/<platform>/` with a
+`<Platform>::Recipe < Libpng::Recipe` subclass and registering it in
+`Recipe.for_target`. No modification of `Libpng::Recipe` needed.
+
+The existing `Libpng::Recipe` is unchanged (except adding the factory class
+method). All OHOS logic is in `lib/libpng/ohos/`.