HEIF decoder source and rebuilding

Draw on a Map uses libheif-js 1.23.2, libheif, and libde265 1.0.15 under
LGPL-3.0. Copyright holders include Kiril Vatev, Dirk Farin, struktur AG,
Joachim Bauch, and the contributors identified in the source archives.
COPYING.txt contains the LGPL-3.0 and GPL-3.0 license texts.
LIBDE265-COPYING.txt contains the libde265 license texts.
EMSCRIPTEN-LICENSE.txt contains the Emscripten runtime license.
MUSL-COPYRIGHT.txt, LIBCXX-LICENSE.txt, LIBCXXABI-LICENSE.txt, and
COMPILER-RT-LICENSE.txt contain the standard runtime component notices.
These files come from the Emscripten 3.1.61 source tree.

You may modify the libraries and reverse engineer the worker to debug those
modifications. The application files and rebuild.mjs have the MIT license in
APPLICATION-LICENSE.txt. These permissions apply independently of the website
terms. You can rebuild and replace this worker without the rest of the
application source. The map and worker communicate through messages.

All paths below are relative to https://drawonamap.com/licenses/heif/.
The source downloads are free and do not require an account.

Rebuild the worker

You can download source.zip and extract it instead of downloading each file.
Each published worker also links to an immutable /_astro/heif-source.*.zip
archive for that worker. Use that archive when rebuilding an older release.

1. Download package.json, rebuild.mjs, APPLICATION-LICENSE.txt, COPYING.txt,
   LIBDE265-COPYING.txt, and EMSCRIPTEN-LICENSE.txt into an empty directory.
2. Create an application directory. Download these files into it:
   application/heif-fallback-worker.ts
   application/heif-color-profile.ts
3. Install Node.js 24. From the download directory, run:

   npm install --ignore-scripts
   npm run build

This produces heif-fallback-worker.js. The application source is copied from
the same checkout as each website build. The build uses esbuild 0.28.2.
It does not need credentials or application server code.

To use a modified library, replace
node_modules/libheif-js/libheif-wasm/libheif-bundle.mjs with your compatible
build, then run npm run build again. The library must retain the exported
HEIF decoding and color-profile APIs used by the two application files.

Replace the worker in your browser

Open browser developer tools and enable local response overrides. Drop a
HEIF image onto the map to request /_astro/heif-fallback-worker-<hash>.js.
Override that response with your rebuilt heif-fallback-worker.js, reload
the page, and drop the image again. The hash changes between releases; use
the URL from the Network panel. Keep the response JavaScript content type.
The application does not check a signature or checksum on this worker.
The normal application limits on image import still apply.

Build the native libraries

sources.json records the exact source revisions, download origins, archive
SHA-256 checksums, and the reviewed npm bundle checksum. Download all four
archives listed there from sources/. They contain:

- libheif at ac1cb05c39008f01525c991ff8b88f84ddf70fd2;
- libde265 1.0.15, including its configure script;
- libheif-emscripten v1.23.2, including the release workflow;
- libheif-js at 6ca00b818c0ff51cb2a5c75b9ce97d708083335a.

The published decoder uses Emscripten 3.1.61 and its standard runtime.
Use Ubuntu 22.04 with CMake, make, autoconf, automake, libtool, pkg-config,
Python, Node.js, TypeScript 5, and Emscripten 3.1.61 on PATH. Set EMSDK to
the Emscripten SDK directory and source its emsdk_env.sh.

Extract libheif and libheif-js. In an empty native-build directory, put the
libde265-1.0.15.tar.gz archive, then run:

   USE_WASM=1 USE_TYPESCRIPT=1 USE_UNSAFE_EVAL=0 \
     /path/to/libheif/build-emscripten.sh /path/to/libheif

The script builds libde265 from the local archive. Its defaults enable
libde265 1.0.15 and disable AOM, OpenJPEG, WebCodecs, and the uncompressed
codec. The original release workflow is in the libheif-emscripten archive.
The source archives include library headers, bindings, post.js, CMake files,
and the build scripts. No library source changes were made by Draw on a Map.

Create libheif-wasm/ in a temporary packaging directory. Copy the generated
libheif.js, libheif.wasm, and libheif.d.ts into it. Copy libheif/COPYING into
libheif-wasm/LICENSE. In that directory, create the native archive:

   tar -czf native.tar.gz libheif-wasm

In the extracted libheif-js source directory, run:

   npm install --ignore-scripts
   node scripts/install.js /absolute/path/to/native.tar.gz

Use the resulting libheif-wasm/libheif-bundle.mjs as the replacement library
in the worker rebuild procedure above. The helper applies its upstream
ES2019 transform and embeds the WebAssembly binary in the JavaScript module.

Archive retention

These source archives must remain available while their matching decoder
binaries remain available. A dependency upgrade must update sources.json,
the archived sources, the rebuild package version, and these instructions.