Kivoza HEIC decoder source kit
==============================

This directory is a self-contained public rebuild kit for the browser decoder
used by the Kivoza HEIC converter. Download every file linked from
`/licenses/` into this one directory, keep the filenames unchanged, and follow
the steps below. The rebuild uses only the two local source archives; it does
not clone a repository, read a Kivoza project checkout, or depend on a
temporary directory outside this kit.

Source inputs
-------------

libheif v1.23.4 (official release source):
  Source URL: https://github.com/strukturag/libheif/releases/download/v1.23.4/libheif-1.23.4.tar.gz
  Source commit: 4e14f5942c1732ace9611b9522cc991501445463
  Local archive: libheif-v1.23.4-source.tar.gz
  SHA-256: d0c02b4b0e978f34a1974b6f3eea7975a537bf7a9195ffeea38e7242ff316fdd
  License: ../libheif-COPYING.txt (GNU LGPL v3)

libde265 v1.0.15 (official release source):
  Source URL: https://github.com/strukturag/libde265/releases/download/v1.0.15/libde265-1.0.15.tar.gz
  Local archive: libde265-v1.0.15-source.tar.gz
  SHA-256: 00251986c29d34d3af7117ed05874950c875dd9292d016be29d3b3762666511d
  License: ../libde265-COPYING.txt (GNU LGPL v3)

The template archive is retained as provenance for the original packaging
work, but it is not required by this kit:

  Local archive: libheif-emscripten-template-dd5a19b.tar.gz
  SHA-256: 645155062d329afff7d2f4ebcc3ea52c23179f3f0ca7e4a7abdd48ef3264b759
  Template commit: dd5a19b878149437a5a427f6e1afa8bac624a714
  Note: the template retains its upstream libheif submodule pointer. The
  official libheif archive above contains the build-emscripten.sh script used
  by this public kit, so no submodule checkout is needed.

Verify the downloaded archives before building:

  sha256sum libheif-v1.23.4-source.tar.gz
  sha256sum libde265-v1.0.15-source.tar.gz
  sha256sum libheif-emscripten-template-dd5a19b.tar.gz

The output must match the three values above. The complete upstream license
texts are one directory above this README.

Raw decoder rebuild
-------------------

The exact Emscripten image is:

  emscripten/emsdk@sha256:96617f27fe16421588241def73908fd348a7f9d260440ed0d00b36dcf7a063cc

Obtain that image before using the script. Then run:

  chmod +x rebuild-libheif-v1.23.4.sh
  ./rebuild-libheif-v1.23.4.sh

The script passes `--network none` to the compiler container and supplies the
local libde265 archive to the upstream build script. Its compiler container
has these explicit limits: 2 GiB memory, 2.5 GiB memory plus swap, 2 CPUs, and
512 PIDs, and it runs as the invoking user's UID/GID so a later rebuild can
clean the output directory. It applies the two visible Kivoza source changes
documented in MODIFICATIONS.txt, replaces the generated CommonJS/AMD footer with
`export default libheif;`, and fixes the remaining build flags to match the
released browser decoder.

The raw files are written to:

  .build/libheif-v1.23.4/libheif-1.23.4/buildjs/libheif.js
  .build/libheif-v1.23.4/libheif-1.23.4/buildjs/libheif.wasm

ESM bundle rebuild
------------------

The bundle uses the exact image and dependency versions below:

  Docker image: node@sha256:f32b81066cde10a75dbac96646099533316d94bac4150c55da1636e1f0ffdc46
  npm dependency: @esbuild/linux-x64 0.28.2

The lockfile records the npm tarball URL and integrity value. From this
directory, install the locked binary in a bounded container. This first
container needs network access only to fetch the public npm tarball:

  docker run --rm --network host --memory=2g --memory-swap=2560m --cpus=2 --pids-limit=512 \
    --user "$(id -u):$(id -g)" \
    -v "$PWD:/kit" -w /kit \
    node@sha256:f32b81066cde10a75dbac96646099533316d94bac4150c55da1636e1f0ffdc46 \
    sh -lc 'npm ci --ignore-scripts'

Then run the bundle step with networking disabled:

  docker run --rm --network none --memory=2g --memory-swap=2560m --cpus=2 --pids-limit=512 \
    --user "$(id -u):$(id -g)" \
    -v "$PWD:/kit" -w /kit \
    node@sha256:f32b81066cde10a75dbac96646099533316d94bac4150c55da1636e1f0ffdc46 \
    sh -lc 'node build-libheif-bundle.mjs'

The ESM bundle is written to `.build/libheif-bundle.mjs`. Run
`node verify-kit.mjs` in the same bounded Node container to check the archive
hashes, raw output signatures, and bundle output. Remove `node_modules/` and
`.build/` after copying the outputs if you want a clean source directory.

The public kit's generated bundle is the artifact consumed by the converter.
For comparison, the release fingerprint record lists these current runtime
files and hashes:

  libheif.js: 166958 bytes,
    b88334e8fdbd06a4e6e5f44f15747c800d81da1d50d03cdddc2022e56bd0ddcc
  libheif.wasm: 1502231 bytes,
    eb5a08e7f7211adee08c28e93217aa22b311721cdca4c5442ecb652f54278718
  libheif-bundle.mjs: 2089414 bytes,
    149a5f6bb243d88c4549df1eb0df93af15372e4680fe94dd121de069d0331eed

Rebuild output can differ when the pinned image, source archives, or locked
esbuild package changes. Record any difference instead of treating it as an
unverified match.

Files and licensing
-------------------

  rebuild-libheif-v1.23.4.sh  raw Emscripten rebuild
  build-libheif-bundle.mjs    ESM bundling command
  libheif-bundle-entry.mjs    local raw-input wrapper
  package.json                locked bundle tool declaration
  package-lock.json           locked npm dependency and integrity
  verify-kit.mjs              output and archive verification
  MODIFICATIONS.txt           exact changes applied around upstream scripts

The complete license texts are available at:

  ../libheif-COPYING.txt
  ../libde265-COPYING.txt

The GNU Lesser General Public License v3 is also available from:
  https://www.gnu.org/licenses/lgpl-3.0.html

These files describe the decoder dependency and its browser build. They do
not change the upstream license terms. Kivoza's application terms are on the
site's Terms page.