@wasmedia/wimagemagick 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,230 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-10-03
+
+First release published to npm, as `@wasmedia/wimagemagick`.
+
+### Added
+- npm package: `@wasmedia/wimagemagick`, published by the CI pipeline when a
+  `vX.Y.Z` tag is pushed, from the same build the tests ran on and with an npm
+  provenance statement. The package (and the Pages playground) now ship
+  `dist/licenses/`: the licence of ImageMagick and of every library linked
+  into the `.wasm`, several of which are LGPL and linked statically.
+- Samsung SRW and Kodak KDC files are recognised on their own, like ARW and
+  DCR. Without a format hint both used to fail with
+  `missing required "ImageLength"`. Pentax PEF is now the only common raw that
+  still needs the hint (or a `.pef` filename).
+- `detectRawFormat()` also names Fujifilm RAF, Panasonic RW2, Olympus ORF
+  (`IIRO`), Canon CRW, Minolta MRW and older Leica/Panasonic RAW files. These
+  already decoded without a hint, because ImageMagick recognises them itself,
+  but `detectRawFormat()` returned `undefined` for them, so it could not be
+  used to ask whether a file is a raw.
+- Sony ARW and Kodak DCR files are recognised on their own by `identify()`,
+  `WMagickImage.fromBuffer()`, `fromBlob()` and `detectRawFormat()`, like NEF
+  and CR2 already were. Without a format hint they used to fail with
+  `missing required "ImageLength"` or `CompressNotSupported`. Checked against
+  ARWs from three Sony bodies (2010–2016) and a Kodak DCS Pro SLR/n.
+- A `process` message for the Web Worker: decode once, run a list of
+  `WMagickImage` operations in order, encode once, and get back the bytes plus
+  the image's size and format before and after. The convert/resize/identify
+  messages each did one fixed thing. The protocol is exported as
+  `createWorkerHandler()` and is now covered by tests.
+- `WMagickImage.fit(maxWidth, maxHeight)`: shrink to fit a box, keeping the
+  aspect ratio and never enlarging, like `-resize WxH>`.
+- `identify()`, `WMagickImage.fromBuffer()` and `fromBlob()` recognise Canon
+  CR2/CR3, Nikon NEF, DNG, Hasselblad 3FR and Phase One IIQ files on their own
+  and read them with LibRaw — no format hint needed. Without one these files
+  used to come back as the embedded preview (NEF, 3FR, IIQ: a 160x120 to
+  640x480 thumbnail with exit code 0), the undemosaiced mosaic (DNG), or an
+  error (CR2, CR3). The detection is exported as `detectRawFormat()`. An
+  explicit format still wins, and other raw formats still need one.
+- Two more kinds of DNG decode: floating-point Deflate DNGs, the layout HDR
+  merges produce, and lossy JPEG DNGs, Lightroom's "lossy compressed" option.
+  LibRaw is now built with zlib and libjpeg; previously the first failed with
+  "Corrupted data" and the second was rejected as an unsupported format.
+- RAW camera files can now actually be decoded through the public API. LibRaw
+  was linked all along, but ImageMagick registers the raw coders as
+  "explicit format" coders and never picks them from a file's magic bytes —
+  a DNG, CR2, NEF or ARW is a TIFF at that level, so the TIFF coder claimed
+  every raw and returned the undemosaiced sensor mosaic instead of a
+  photograph, with no error. The format can now be named:
+  `identify(module, bytes, { format: 'CR2' })`,
+  `WMagickImage.fromBuffer(bytes, 'DNG')`,
+  `Image.fromBlob(file, 'DNG')`, or an explicit `dng:` prefix in a command.
+  A filename that already ends in a raw extension (`shot.cr2`) worked before
+  and still does.
+- Format coverage tests (`tests/integration/formats.test.ts`, 30 cases). Every
+  decode case reads a file produced outside this build — `sips`, `cwebp`,
+  `avifenc`, `cjxl`, and a Bayer-mosaic DNG generated by
+  `tests/fixtures/make-bayer-dng.py` and verified with LibRaw's own
+  `raw-identify`/`dcraw_emu` — and every encode case checks the bytes against
+  the container's signature before ImageMagick reads them back. Removing a
+  delegate now fails a named test instead of quietly shrinking the format set.
+- The native build fails loudly when a delegate goes missing.
+  `native/settings/common.sh` passes an explicit `--with-<delegate>` flag for
+  everything the build promises and lists the set in `REQUIRED_DELEGATES`;
+  `build-imagemagick.sh` checks the generated `magick-baseconfig.h` after
+  configure and stops the build if one is absent. configure discovers
+  delegates through pkg-config and otherwise carries on without them.
+- Test suite (`npm test`): unit tests for the pure helpers plus
+  integration tests that drive the real WASM build through the CLI interface,
+  `WMagickImage`, the MEMFS helpers, the MagickWand bindings and the loader.
+  `npm run typecheck` type-checks `src/` and `tests/` together, since vitest
+  does not.
+- `npm run playground` (`scripts/playground.mjs`) — local static server that
+  serves `examples/browser/index.html` with `dist/` mounted alongside, so the
+  WASM playground works without a separate web server.
+- `LICENSE`, `CHANGELOG.md`, `CONTRIBUTING.md`.
+- README badges (pipeline status, latest release, license, ImageMagick
+  version, WebAssembly+SIMD).
+- Playground UI improvements:
+  - JXL and JP2 added to the output format dropdown.
+  - Output panel now shows input → output size delta with percent change
+    (green if smaller, red if larger).
+  - Resize controls gain an aspect-ratio lock and `Fit 2048 / 1024 / 512 /
+    Clear` presets driven by the loaded image's intrinsic dimensions.
+  - View toggle between side-by-side preview and a draggable compare
+    slider that overlays output on top of input.
+  - CLI mode gains a persistent localStorage history (50 commands, ↑/↓
+    navigation) and an `Examples ▾` dropdown with six canned commands.
+  - File picker accepts RAW (CR2/CR3/NEF/ARW/RAF/ORF/DNG/RW2/PEF), JXL,
+    and JP2 extensions.
+
+### Changed
+- The package is renamed from `wimagemagick` to `@wasmedia/wimagemagick`,
+  matching the other wasmedia packages. Imports change accordingly
+  (`@wasmedia/wimagemagick`, `@wasmedia/wimagemagick/worker`).
+- The browser playground decodes and encodes in the library's Web Worker
+  instead of on the page. A large file no longer freezes the page while
+  ImageMagick works: loading a 24 MP TIFF used to block it for about two
+  seconds, and now the longest stall is under 20 ms.
+- Documentation now matches the build. The delegate list claimed harfbuzz,
+  which has never been in the prebuilt dependency bundle, and listed openjph
+  as "JPEG XL (via JPEG Pleno)" — openjph is High-Throughput JPEG 2000, and
+  ImageMagick has no HTJ2K coder at the pinned commit, so it was never used.
+  `docs/building.md` now carries the delegate list the build actually reports,
+  says which libraries are deliberately absent and why, and documents two
+  behaviours that had been catching people out: a missing encoder (HEIC, EXR,
+  any raw format) is a warning rather than an error, so ImageMagick writes the
+  input's format under the requested name and returns 0; and `label:`,
+  `caption:` and `-annotate` need the caller to supply a font, because
+  fontconfig is absent and no fonts ship inside the WASM filesystem.
+- `libopenjph` is no longer linked. Nothing referenced it, so the binary is
+  unchanged; the link list now reflects that JPEG 2000 comes from openjpeg and
+  JPEG XL from libjxl.
+- The browser playground reads RAW files properly. It advertised CR2/NEF/ARW/DNG
+  in the file picker but read every drop as a plain buffer, so a raw came back
+  as the TIFF-container mosaic; it now derives the format from the file
+  extension.
+- CI runs the tests for real: the `test` job no longer carries
+  `allow_failure: true` (it had been failing on every pipeline with "No test
+  files found") and now type-checks before running the suite.
+- CI validates merge requests. Jobs without `rules:` defaulted to
+  `only: [branches, tags]`, so a merge request pipeline ran nothing but
+  `build-image` and an MR could merge green without the WASM or TypeScript ever
+  being compiled. Every job now runs on both merge request and branch
+  pipelines, and a `workflow:` block keeps a branch with an open MR from
+  building twice.
+- CI pipeline runs on GitLab SaaS instance (shared) runners:
+  `default: tags: [saas-linux-small-amd64]`, with `build-image` and
+  `build-wasm` overriding to `saas-linux-medium-amd64` for the extra RAM
+  needed by Docker-in-Docker and WASM linking. No self-hosted runner is
+  required to build the project.
+- `build-image` now sets `DOCKER_HOST`, `DOCKER_TLS_VERIFY`, and
+  `DOCKER_CERT_PATH` so the docker client connects to the `dind` service
+  over TLS on port 2376 (matching `DOCKER_TLS_CERTDIR`).
+- Build pipeline consolidated to a single output: single-threaded + SIMD.
+  Previously the build attempted to produce both a single-threaded and a
+  threaded variant; the threaded path was unbuildable against the prebuilt
+  delegate bundle (libheif/libde265/libaom and OpenEXR objects lack the
+  atomics feature flag, blocking `wasm-ld --shared-memory`).
+- `dist/` layout is now flat (`dist/wimagemagick.{js,wasm}`); the per-variant
+  subdirectories (`dist/single/`, `dist/threaded/`) are gone.
+- `native/settings/single.sh` renamed to `native/settings/build.sh`. The
+  `threaded.sh` settings file has been removed.
+- TypeScript wrapper no longer branches on threading: `WImageMagickOptions`
+  drops `preferThreaded`, `WImageMagickInstance` drops `isThreaded`, and the
+  `detectThreadingSupport()` helper is gone.
+
+### Fixed
+- In the playground, Auto-orient, Strip and Convert with "Same as input" work
+  on camera raws and HEIC. They used to fail with
+  `NoEncodeDelegateForThisImageFormat`, since ImageMagick cannot write those
+  formats; the result is now saved as PNG, and the output line says so.
+- The playground's input panel previews camera raws (and HEIC, JXL, TIFF or
+  JP2 in browsers that cannot display them) instead of showing a broken image.
+  When the browser cannot decode a file itself, the preview is rendered from
+  ImageMagick's decode — oriented, and capped at 2048 px — and the compare
+  slider uses it too. A file that cannot be read at all shows "No preview".
+- A truncated or damaged RAW file now fails like any other bad image — exit
+  code 1 and an ImageMagick error from the DNG coder — instead of throwing a bare
+  pointer out of `callMain`. The prebuilt LibRaw had its exception handlers
+  compiled out, so every such file leaked about a megabyte and a few dozen of
+  them crashed the module for good (`memory access out of bounds`). LibRaw is
+  now built from source with exception catching; a thousand damaged raws in a
+  row leave the module healthy.
+- A command's `stdout` now arrives with that command. The CLI entry point
+  (`native/bindings/api-exports.c`) flushes libc's streams before returning:
+  the runtime is deliberately kept alive between commands (`EXIT_RUNTIME=0`),
+  so nothing flushed at exit and a command's output sat in the buffer until
+  some later command pushed it out. Output is line-buffered, so `-format`
+  strings still need their trailing `\n`. Requires a WASM rebuild.
+- `execute()` now resolves the filename behind an explicit format prefix.
+  `dng:capture` and `info:report.txt` were treated as pseudo-formats and left
+  pointing outside the command's working directory, so the first failed with
+  "No such file or directory" and the second silently wrote its report where
+  nothing could read it back — including the `info:report.txt` example in
+  `docs/api.md`. Pseudo-formats whose argument is content (`xc:`, `gradient:`,
+  `label:`, `plasma:`, `null:` and friends) are still passed through untouched.
+- `execute()` and `identify()` return the command's output again. Emscripten
+  captures `print`/`printErr` while the module is being constructed, so the
+  previous approach of reassigning them per command left `stdout` and
+  `stderr` permanently empty; the loader now installs the hooks up front.
+- `identify()` returns a real description (`"<width> <height> <format>"`, or
+  ImageMagick's verbose report). It used to invoke a non-existent `identify`
+  sub-command — this build exposes ImageMagick's image command directly — and
+  returned an empty string for every image.
+- `execute()` resolves filenames that start with a digit or with `x`
+  (`2024-photo.jpg`, `xray.png`), which it previously mistook for geometry and
+  pseudo-format arguments and failed to find, and it no longer rewrites
+  pseudo-format arguments such as `gradient:red-blue`, `null:` or `info:` into
+  working-directory paths. Output names now need an extension to be recognised.
+- `parseCommand()` keeps an explicitly empty quoted argument (`-set comment ""`)
+  instead of dropping it and shifting the rest of argv.
+
+### Removed
+- OpenEXR support (`--with-openexr=no`). The prebuilt EXR objects trip
+  Emscripten cross-compile feature detection; HEIC/AVIF/JXL/JP2 cover the
+  high-dynamic-range and modern-format use cases.
+- Threaded build infrastructure: `native/settings/threaded.sh`,
+  `native/scripts/build-deps-threaded.sh`, the `BUILD_VARIANT` and
+  `WASM_THREAD_FLAGS` CMake plumbing, the `build:native:threaded` /
+  `build:native:single` npm scripts, and the dual-variant CI jobs.
+
+## [0.1.0] - Initial development (not tagged or published)
+
+### Added
+- Native WASM build pipeline (`native/`): Dockerised Emscripten toolchain,
+  ImageMagick v7 cross-compile against prebuilt delegate static libraries.
+- Verified format support: JPEG, PNG, WebP, TIFF, GIF, BMP, AVIF, JXL, JP2,
+  HEIC (decode), RAW (via LibRaw).
+- TypeScript wrapper (`src/`): `initWImageMagick()` loader, `WMagickImage`
+  high-level chainable image class, MagickWand C-API bindings via `cwrap`,
+  CLI-style `execute()`, MEMFS file helpers, Web Worker entry point.
+- GitLab CI pipeline (`.gitlab-ci.yml`): registry-cached Docker image,
+  WASM build, TypeScript build, test stage, GitLab Pages deploy of the
+  browser playground.
+- Browser playground (`examples/browser/index.html`): drag-and-drop, format
+  conversion, resize, quality, strip metadata, auto-orient, CLI mode.
+- Convenience C wrappers exported from the WASM module:
+  `wimagemagick_identify`, `wimagemagick_convert`, `wimagemagick_resize`.
+
+[Unreleased]: https://gitlab.com/wasmedia/wimagemagick/-/compare/v0.2.0...HEAD
+[0.2.0]: https://gitlab.com/wasmedia/wimagemagick/-/tags/v0.2.0

package/LICENSE

@@ -0,0 +1,199 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recognize an "include"
+      as a comment marker.
+
+   Copyright 2026 Roger Howard
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,75 @@
+# wimagemagick
+
+[![pipeline status](https://gitlab.com/wasmedia/wimagemagick/badges/main/pipeline.svg)](https://gitlab.com/wasmedia/wimagemagick/-/commits/main)
+[![latest release](https://gitlab.com/wasmedia/wimagemagick/-/badges/release.svg)](https://gitlab.com/wasmedia/wimagemagick/-/releases)
+[![license: Apache 2.0](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![ImageMagick](https://img.shields.io/badge/ImageMagick-v7-orange.svg)](https://imagemagick.org/)
+[![WebAssembly](https://img.shields.io/badge/WebAssembly-SIMD-654ff0.svg)](https://webassembly.org/)
+
+A feature-complete ImageMagick build with all modern dependencies, compiled for WASM so it can be easily run in a modern browser.
+
+## Install
+
+```bash
+npm install @wasmedia/wimagemagick
+```
+
+```typescript
+import { initWImageMagick } from '@wasmedia/wimagemagick';
+
+const wim = await initWImageMagick();
+const img = wim.Image.fromBuffer(bytes);
+const jpeg = img.fit(1600, 1600).quality(85).toBuffer('JPEG');
+img.dispose();
+```
+
+The package ships the `.wasm` (about 13 MB, 5 MB gzipped) next to its JS, and
+loads it relative to the module, so a bundler that copies assets referenced by
+`new URL(..., import.meta.url)` needs no configuration. [docs/api.md](docs/api.md)
+has the full API, including the Web Worker entry
+(`@wasmedia/wimagemagick/worker`). The WASM statically links ImageMagick and
+several LGPL libraries; their licences are in `dist/licenses/`.
+
+Try it without installing at [magick.wasmedia.org](https://magick.wasmedia.org/).
+
+## Format & Feature Scope
+
+- **Excluded:** Ghostscript-based features (PDF rendering), FFmpeg-based features (video)
+- **Included:** As many image formats as practical, specifically:
+  - Common raster, read and write: JPEG, PNG, WebP, TIFF, GIF, BMP, AVIF, JXL, JP2/J2K
+  - HEIC/HEIF (via libheif) — decode only; encoding would need x265
+  - RAW camera formats (via LibRaw) — decode only; the common ones are
+    detected from their headers, see [Reading RAW files](docs/api.md#reading-raw-files)
+  - Other formats as practical to cross-compile
+
+`docs/building.md` has the verified format matrix and the list of delegates
+that are deliberately absent.
+
+## Technical Requirements
+
+- **ImageMagick version:** Always target the current stable release (currently v7)
+- **API surface:** Both CLI-style interface (pass command strings) and C API (MagickWand/MagickCore)
+- **JS wrapper:** High-level JS wrapper on top of the C bindings, plus CLI-style command execution
+- **Toolchain:** Open to any practical WASM toolchain (Emscripten is the likely choice)
+- **Output:** Both a single `.wasm` + JS glue bundle and an npm-distributable package
+- **Bundle size:** Large binaries are acceptable if necessary to support the full format set
+- **File I/O:** Support both Emscripten virtual filesystem (MEMFS) and direct `ArrayBuffer`/`Blob` passing
+- **Web Workers:** Should support running off the main thread
+- **Distribution:** Open source, published to npm as `@wasmedia/wimagemagick`
+- **Browser support:** Chrome and Safari at minimum
+- **Build:** Single-threaded + SIMD — works on any site without special headers
+
+## Prior Art
+
+| Project | Status | IM Version | Delegates | Threading/SIMD | API Style |
+|---------|--------|------------|-----------|----------------|-----------|
+| [@imagemagick/magick-wasm](https://github.com/dlemstra/magick-wasm) | Active, ~853 stars | v7 (current) | Rich (HEIF, WebP, RAW, JXL, EXR) | None | OOP TypeScript only |
+| [WASM-ImageMagick](https://github.com/KnicKnic/WASM-ImageMagick) | Abandoned (2023) | v7 (~2019 era) | Minimal (JPEG, PNG, TIFF, GIF) | None | CLI strings only |
+| [magickwand.js](https://github.com/mmomtchev/magickwand.js) | Active, ~91 stars | v7 (current) | Rich (HEIF, WebP, EXR) | Partial async workers | Full Magick++ OOP |
+
+**Gaps wimagemagick fills:**
+- No project offers both CLI-style and programmatic API
+- AVIF support is absent from all
+
+**Build-on opportunity:** dlemstra's [Magick.Native](https://github.com/dlemstra/Magick.Native) already cross-compiles ImageMagick v7 + rich delegates to WASM via Emscripten. It could serve as a foundation for the native build, with wimagemagick adding threading/SIMD builds, CLI interface, and the JS wrapper layer on top.
+

package/dist/api.d.ts

@@ -0,0 +1,68 @@
+/**
+ * MagickWand C API bindings via Emscripten cwrap.
+ *
+ * Provides typed wrappers around all exported MagickWand functions.
+ * For direct, low-level access to ImageMagick's C API from JavaScript.
+ */
+import type { WasmModule } from "./types.js";
+export interface MagickBindings {
+    MagickWandGenesis(): void;
+    MagickWandTerminus(): void;
+    NewMagickWand(): number;
+    DestroyMagickWand(wand: number): number;
+    CloneMagickWand(wand: number): number;
+    MagickReadImage(wand: number, filename: string): number;
+    MagickWriteImage(wand: number, filename: string): number;
+    MagickReadImageBlob(wand: number, blob: number, length: number): number;
+    MagickGetImageBlob(wand: number, lengthPtr: number): number;
+    MagickRelinquishMemory(ptr: number): number;
+    MagickGetImageWidth(wand: number): number;
+    MagickGetImageHeight(wand: number): number;
+    MagickGetImageFormat(wand: number): string;
+    MagickSetImageFormat(wand: number, format: string): number;
+    MagickResizeImage(wand: number, width: number, height: number, filter: number): number;
+    MagickAdaptiveResizeImage(wand: number, width: number, height: number): number;
+    MagickThumbnailImage(wand: number, width: number, height: number): number;
+    MagickCropImage(wand: number, width: number, height: number, x: number, y: number): number;
+    MagickExtentImage(wand: number, width: number, height: number, x: number, y: number): number;
+    MagickRotateImage(wand: number, background: number, degrees: number): number;
+    MagickFlipImage(wand: number): number;
+    MagickFlopImage(wand: number): number;
+    MagickTransposeImage(wand: number): number;
+    MagickTransverseImage(wand: number): number;
+    MagickBlurImage(wand: number, radius: number, sigma: number): number;
+    MagickGaussianBlurImage(wand: number, radius: number, sigma: number): number;
+    MagickSharpenImage(wand: number, radius: number, sigma: number): number;
+    MagickUnsharpMaskImage(wand: number, radius: number, sigma: number, gain: number, threshold: number): number;
+    MagickCompositeImage(wand: number, sourceWand: number, compose: number, clipToSelf: number, x: number, y: number): number;
+    MagickSetImageCompressionQuality(wand: number, quality: number): number;
+    MagickGetImageCompressionQuality(wand: number): number;
+    MagickStripImage(wand: number): number;
+    MagickAutoOrientImage(wand: number): number;
+    MagickAutoLevelImage(wand: number): number;
+    MagickNormalizeImage(wand: number): number;
+    MagickDeskewImage(wand: number, threshold: number): number;
+    MagickSetImageAlphaChannel(wand: number, alphaType: number): number;
+    MagickGetException(wand: number, severityPtr: number): string;
+    MagickClearException(wand: number): number;
+    MagickSetResourceLimit(type: number, limit: number): number;
+    MagickGetResourceLimit(type: number): number;
+    MagickSetSize(wand: number, width: number, height: number): number;
+    MagickSetDepth(wand: number, depth: number): number;
+    MagickGetNumberImages(wand: number): number;
+    MagickSetIteratorIndex(wand: number, index: number): number;
+    MagickResetIterator(wand: number): void;
+    MagickGetImageDepth(wand: number): number;
+    MagickSetImageDepth(wand: number, depth: number): number;
+    MagickGetImageColorspace(wand: number): number;
+    MagickSetImageColorspace(wand: number, colorspace: number): number;
+    MagickProfileImage(wand: number, name: string, profile: number, length: number): number;
+    MagickGetImageProfile(wand: number, name: string, lengthPtr: number): number;
+    MagickRemoveImageProfile(wand: number, name: string, lengthPtr: number): number;
+    wimagemagick_identify(blob: number, length: number, widthPtr: number, heightPtr: number, formatPtr: number, formatBufSize: number): number;
+    wimagemagick_convert(blob: number, length: number, format: string, quality: number, outLengthPtr: number): number;
+    wimagemagick_resize(blob: number, length: number, width: number, height: number, format: string, quality: number, outLengthPtr: number): number;
+}
+/** Create typed bindings for all exported MagickWand C functions. */
+export declare function createBindings(module: WasmModule): MagickBindings;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}