optiq-image 0.0.0-stage → 0.2.0-beta.0

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## 0.2.0-beta.0 (unreleased)
+
+- `mode: "fast"`: SSIM ≥ 0.975 like `balanced`, no AVIF, no oxipng, ≤ 5 encodes. Benchmark: −54.9% total
+  (balanced −61.2%), median 405 ms in Chromium (balanced 1.3 s), median peak RSS 184 MB (balanced 304 MB).
+- `optiq-image` CLI (`npx optiq-image <files|folders>`): dry run by default, `--out`, `--in-place`, parallel workers.
+- `optiq-image/vite`: Vite plugin that optimises build output in place (same names and formats).
+- `optiq-image/react`: `useOptiq(file, options)` hook.
+- `optimizeFiles()` batch API for Node (worker_threads pool).
+
+## 0.1.0-beta.0 (unreleased)
+
+Audit fixes (see docs/audit.md):
+
+- A perceptual mode could return the original although `lossless` mode found a smaller pixel-exact file (P3 photo
+  PNG: 794 KB returned, 472 KB available). Quality ranges now reach JPEG 98 / WebP 99 / AVIF 95, and lossless
+  candidates are added when no re-encode meets the threshold for a losslessly stored input.
+- SSIM is now bounded by the alpha plane's own SSIM for images with transparency.
+- Warning when the output is larger than the input because the original was not an allowed result.
+- SSIM 20–54% faster with numerically identical results.
+- Verified with Vite 7 and Vite 8.
+
+First public beta.
+
+- `compressImage` / `createCompressor`: Web Worker pool, `AbortSignal` cancellation (terminates the worker),
+  progress events, typed `OptiqError` codes, canvas fallback when WASM cannot load.
+- Modes: `lossless` (pixel-exact, verified), `visually-lossless` (SSIM ≥ 0.99), `balanced` (SSIM ≥ 0.975).
+- Codecs (via jSquash): MozJPEG, libwebp, libavif, oxipng, Rust `png` and `resize`; own static-GIF decoder.
+- Format sniffing from content; EXIF orientation, ICC, EXIF/XMP preservation; animation never silently flattened.
+- Tile-mosaic quality search for images above 4 MP.
+- `optiq-image/upload`: presigned PUT/POST upload with progress and original-file fallback.
+- `optiq-image/node`: Node.js codec initialisation for tests, benchmarks and server-side use.
+
+Tested in Chromium, Firefox and WebKit. Known limitations: no AVIF metadata writer; HEIC unsupported.

package/LICENSE

@@ -0,0 +1,201 @@
+                                 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 reasonable and customary use in 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 Additional Liability. 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 additional liability.
+
+   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 recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Optiq contributors
+
+   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/NOTICE

@@ -0,0 +1,30 @@
+Optiq
+Copyright 2026 Optiq contributors
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).
+
+Optiq does not bundle codec binaries itself. It depends on the following packages, which an application
+bundle that uses Optiq will include. Their licences permit commercial redistribution provided the notices
+are reproduced; the full texts ship inside each package (LICENSE and codec/LICENSE.codec.md).
+
+  @jsquash/jpeg, @jsquash/webp, @jsquash/avif, @jsquash/png, @jsquash/oxipng, @jsquash/resize
+    Apache-2.0, Copyright 2023 jamsinclair; derived from Squoosh, Copyright 2020 Google Inc.
+
+  MozJPEG / libjpeg-turbo (in @jsquash/jpeg)
+    IJG License, Modified (3-clause) BSD License, zlib License
+    "This software is based in part on the work of the Independent JPEG Group."
+
+  libwebp (in @jsquash/webp)
+    BSD-3-Clause, Copyright (c) 2010, Google Inc.
+
+  libavif and libaom (in @jsquash/avif)
+    libavif: BSD-2-Clause, Copyright 2019 Joe Drago and contributors
+    libaom: BSD-2-Clause, Copyright (c) 2016, Alliance for Open Media, plus the AOMedia Patent License 1.0
+    (@jsquash/avif does not ship these texts; see https://github.com/AOMediaCodec/libavif and
+    https://aomedia.googlesource.com/aom/+/refs/heads/main/LICENSE and PATENTS)
+
+  png crate (in @jsquash/png)                   MIT OR Apache-2.0, The image-rs Developers
+  oxipng (in @jsquash/oxipng)                   MIT, Copyright (c) 2016 Joshua Holmer
+  resize crate (in @jsquash/resize)             MIT, Copyright (c) 2015 PistonDevelopers
+  hqx (in @jsquash/resize)                      Apache-2.0
+  magic-kernel (in @jsquash/resize)             MIT, Copyright (c) 2024 Serhii Tatarintsev

package/README.md

@@ -1,3 +1,260 @@
-# Temporary Holding Version
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Baukaalm/optiq/main/brand/logo-white.svg" />
+    <img src="https://raw.githubusercontent.com/Baukaalm/optiq/main/brand/logo-black.svg" width="96" height="96" alt="Optiq" />
+  </picture>
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">Optiq</h1>
+
+**[Try the demo](https://baukaalm.github.io/optiq/try)** · **[Documentation](https://baukaalm.github.io/optiq/)** · [Benchmarks](https://baukaalm.github.io/optiq/benchmarks)
+
+Browser-side image optimisation for uploads. For every image Optiq encodes a bounded set of candidates
+(MozJPEG, libwebp, libavif, oxipng — compiled to WebAssembly), **measures** each one, and returns the smallest
+output that satisfies your constraint:
+
+- `lossless` — decoded pixels (including alpha) are verified identical to the input;
+- `visually-lossless` — pixels may differ; SSIM ≥ 0.99 against the input (configurable);
+- `balanced` (default) — SSIM ≥ 0.975, smaller search budget, faster AVIF preset.
+
+Work runs in a Web Worker; the main thread only posts a `Blob` and receives an `ArrayBuffer`. Results carry the
+chosen codec/settings, every candidate tried, the measured quality, warnings, fallbacks and unmet constraints.
+
+> Benchmarks: see [Benchmark results](#benchmark-results) and `bench/results/RESULTS.md`. Optiq is not
+> uniformly better than the alternatives; the trade-offs (size vs. time vs. memory) are listed there per category.
+
+## Install
+
+```sh
+pnpm add optiq-image      # or npm / yarn
+```
+
+Requirements: an ES2022 browser with module Workers and WebAssembly (Chrome/Edge 80+, Firefox 114+, Safari 15+).
+AVIF *output* is only useful where your audience can decode AVIF (Chrome 85+, Firefox 93+, Safari 16.4+); remove it
+with `autoFormats: ["jpeg", "png", "webp"]` otherwise.
+
+### Bundler setup (Vite 7 and 8)
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  worker: { format: "es" }, // codecs are loaded with dynamic import() inside the worker
+  optimizeDeps: {           // dev only: pre-bundling breaks `new URL("x.wasm", import.meta.url)`
+    exclude: ["optiq-image", "@jsquash/jpeg", "@jsquash/png", "@jsquash/webp", "@jsquash/avif", "@jsquash/oxipng", "@jsquash/resize"],
+  },
+});
+```
+
+webpack 5 and Parcel 2 understand `new Worker(new URL("./worker.js", import.meta.url), { type: "module" })` and
+`new URL("*.wasm", import.meta.url)` natively. For anything else pass `workerFactory` to `createCompressor`.
+Each codec is a separate chunk, fetched on first use (AVIF ≈ 3.5 MB, others 35–350 KB).
+
+## Usage
+
+```ts
+import { compressImage, isOptiqError } from "optiq-image";
+
+const controller = new AbortController();
+try {
+  const result = await compressImage(file, {
+    mode: "balanced",
+    maxWidthOrHeight: 2560,
+    signal: controller.signal,
+    onProgress: (e) => console.log(e.stage, Math.round(e.progress * 100), e.bestBytes),
+  });
+  result.blob;            // Blob with the right MIME type (image/avif, image/webp, ...)
+  result.fileName;        // "IMG_0042.webp" — extension matches the encoded bytes
+  result.sizeReductionRatio, result.qualityMetric, result.codec, result.warnings;
+  if (!result.constraintsMet) console.warn(result.unmetConstraints);
+} catch (e) {
+  if (isOptiqError(e)) console.warn(e.code, e.message); // e.g. UNSUPPORTED_FORMAT, ABORTED
+  // the original `file` is untouched — upload it instead
+}
+```
+
+React:
+
+```tsx
+function useCompressed(file?: File) {
+  const [state, set] = useState<{ result?: CompressionResult; error?: unknown; progress: number }>({ progress: 0 });
+  useEffect(() => {
+    if (!file) return;
+    const ac = new AbortController();
+    compressImage(file, { signal: ac.signal, onProgress: (e) => set((s) => ({ ...s, progress: e.progress })) })
+      .then((result) => set({ result, progress: 1 }), (error) => !ac.signal.aborted && set({ error, progress: 0 }));
+    return () => ac.abort(); // terminates the worker job
+  }, [file]);
+  return state;
+}
+```
+
+For explicit control over workers use `createCompressor({ maxWorkers, workerFactory, codecFallback, allowMainThread, recycleAfterPixels })`.
+
+### Options
+
+| Option | Default | Meaning |
+|---|---|---|
+| `mode` | `"balanced"` | `lossless`, `visually-lossless`, `balanced`, `fast` (no AVIF, ≤ 5 encodes; ~3× faster) |
+| `minQuality` | 0.99 / 0.975 | SSIM threshold (ignored in lossless). Gradients use a stricter value half-way to 1 |
+| `maxOutputBytes` | – | Upper bound. If impossible without violating quality, the result lists it in `unmetConstraints` |
+| `maxWidthOrHeight` | – | Downscale longest side. In `lossless` mode only with `allowLossyResize: true` |
+| `targetFormat` | `"auto"` | `auto`, `original`, `jpeg`, `png`, `webp`, `avif` |
+| `autoFormats` | all four | Formats `auto` may choose |
+| `allowFormatConversion` | `true` | `false` keeps the input format |
+| `maxCandidates` | 10 / 16 / 4 | Encode budget (balanced / visually-lossless / lossless) |
+| `searchStrategy` | `"binary"` | `fixed` = one encode per format at a preset quality |
+| `preserveMetadata` | `true` | Keep EXIF/XMP/ICC. `false` strips EXIF (incl. GPS) and XMP; non-sRGB ICC is kept anyway |
+| `preserveAnimation` | `true` | Animated inputs are only optimised at container level. `false` permits flattening to frame 1 |
+| `minSavingsRatio` | `0.02` | Keep the original unless re-encoding saves at least this |
+| `maxInputBytes` / `maxInputPixels` | 100 MiB / 50 MP | Checked before reading / before decoding |
+| `onUnmetConstraints` | `"best-effort"` | `throw` → `CONSTRAINTS_UNSATISFIABLE` |
+
+Progress stages: `reading → probing → decoding → (resizing) → analyzing → encoding … → finalizing → done`.
+
+Error codes: `INVALID_INPUT`, `UNSUPPORTED_FORMAT`, `MALFORMED_INPUT`, `INPUT_TOO_LARGE`, `INVALID_OPTIONS`,
+`INCOMPATIBLE_OPTIONS` (e.g. JPEG requested for a transparent image), `CONSTRAINTS_UNSATISFIABLE`,
+`CODEC_UNAVAILABLE`, `UNSUPPORTED_ENVIRONMENT`, `WORKER_ERROR`, `ABORTED` (`name === "AbortError"`).
+
+## React, CLI, Vite plugin
+
+```tsx
+import { useOptiq } from "optiq-image/react";
+const { status, result, progress, cancel } = useOptiq(file, { mode: "fast" });
+```
+
+[View example](https://github.com/Baukaalm/optiq/blob/main/docs/examples/PhotoUploadForm.tsx) (upload form with progress, cancel and S3) · [React hook docs](https://baukaalm.github.io/optiq/guide/react)
+
+```sh
+npx optiq-image ./photos --out ./photos-optimized      # static images, in parallel worker threads
+```
+
+```ts
+import { optiq } from "optiq-image/vite";               // optimises build output in place
+export default defineConfig({ plugins: [optiq()] });
+```
+
+## Uploading to S3
+
+```ts
+import { compressAndUpload } from "optiq-image/upload";
+const out = await compressAndUpload(file, { requestPresignedUpload: (req) => fetch("/api/presign", …).then((r) => r.json()) });
+```
+
+Compression is optional and never blocks the upload: if it fails or does not help, the original is uploaded.
+Presigned URLs must come from your backend — see [docs/guide/s3.md](https://github.com/Baukaalm/optiq/blob/main/docs/guide/s3.md) for the contract and a backend sketch.
+
+## Supported formats
+
+| | Input | Output |
+|---|---|---|
+| JPEG | 8-bit RGB/gray (CMYK, 12-bit: kept as is) | MozJPEG, progressive |
+| PNG | all incl. 16-bit, APNG (container-level only) | oxipng (lossless) |
+| WebP | lossy, lossless, animated (container-level only) | lossy / lossless |
+| AVIF | still (animated / rotated: kept as is) | libavif |
+| GIF | static (converted), animated (kept as is) | – |
+| HEIC/HEIF | detected → `UNSUPPORTED_FORMAT` | – |
+| SVG | detected → returned unchanged, never rasterised | – |
+
+Formats are detected from file content. Extensions and MIME types are ignored (a `.jpg` that is a PNG is a PNG).
+
+## Guarantees and limitations
+
+- **Lossless** means decoded RGBA equality, verified per candidate, for the decoder Optiq uses. JPEG
+  decoders are not bit-exact across implementations, so “lossless” for a JPEG input is only ever a byte-level
+  container rewrite (metadata removal), never a re-encode.
+- **Transparency** is never dropped: JPEG is excluded when any pixel has alpha < 255.
+- **Orientation**: EXIF orientation is applied to the pixels of re-encoded outputs (tag reset to 1) and preserved in
+  container-level outputs.
+- **Colour**: ICC profiles are carried into JPEG/PNG/WebP outputs. AVIF output is tagged sRGB and is not used for
+  images with a non-sRGB profile. sRGB profiles are dropped only with `preserveMetadata: false` (or for AVIF output,
+  where the `nclx` sRGB tag is equivalent). No colour conversion is performed.
+- **Metadata**: kept by default. AVIF output is skipped when EXIF/XMP must be preserved (no AVIF metadata writer).
+  With `preserveMetadata: false`, EXIF (including GPS), XMP, comments and trailing data are removed.
+- **Animation** is never silently flattened.
+- **SSIM is a proxy for perception**, not perception: it under-weights banding in smooth gradients and chroma
+  bleeding. Validate thresholds on your own content.
+- **Memory**: large images need several hundred MB inside the worker (see benchmarks). WASM memory is returned by
+  terminating the worker, which happens automatically after jobs above 8 MP.
+- **Speed**: searching costs multiple encodes. Use `balanced`, lower `maxCandidates`, `searchStrategy: "fixed"`, or
+  drop AVIF from `autoFormats` when latency matters more than bytes.
+
+## Licensing
+
+Optiq: Apache-2.0. Bundled codecs (via jSquash, Apache-2.0 wrappers): MozJPEG (IJG + BSD-3 + zlib),
+libwebp (BSD-3), libavif (BSD-2) with libaom (BSD-2 + AOMedia patent licence), Rust `png`, `oxipng`, `resize`
+(MIT/Apache-2.0). All permit commercial redistribution with notices. No GPL code is included
+(libimagequant was rejected for that reason).
+
+## Benchmark results
+
+24 images (`bench/corpus/manifest.json`): 10 Kodak photos (8 JPEG q92, 2 PNG), 3 phone-style 12 MP JPEGs,
+2 screenshots, 2 text graphics, 4 transparent illustrations, 3 gradients. Apple M4 Pro (14 cores, 24 GB), macOS arm64, Node 24.15 and
+headless Chromium 156. Every output is decoded with the same decoders and scored with the same SSIM against the
+input. Full tables, per-image rows and the optimisation log: [`bench/results/RESULTS.md`](https://github.com/Baukaalm/optiq/blob/main/bench/results/RESULTS.md).
+
+**Perceptual, all 24 images (Node; same encoders as the browser)**
+
+| Tool | Total output | Reduction | Meets SSIM ≥ 0.975 | Median time | Median peak RSS |
+|---|---|---|---|---|---|
+| Optiq `balanced` | 13.25 → 5.15 MB | 61.1% | 24/24 | 1.8 s | 301 MB |
+| Optiq `fast` (no AVIF, ≤ 5 encodes) | 13.25 → 5.97 MB | 54.9% | 24/24 | 521 ms | 184 MB |
+| Optiq `balanced`, `preserveMetadata: false` | 13.25 → 4.73 MB | 64.3% | 24/24 | 1.5 s | 297 MB |
+| Optiq `visually-lossless` | 13.25 → 6.38 MB | 51.8% | 24/24 (≥ 0.99: 24/24) | 2.3 s | 325 MB |
+| libvips WebP q80 | 13.25 → 6.50 MB | 51.0% | 17/24 | 59 ms | 105 MB |
+| libvips MozJPEG q80 (opaque only) | 12.82 → 6.87 MB | 46.4% | 11/20 | 54 ms | 106 MB |
+| libvips AVIF q50 | 13.25 → 3.41 MB | 74.3% | 11/24 (photos: 0/10) | 590 ms | 151 MB |
+
+**Browser (Chromium), against browser-image-compression 2.0.2 and canvas**
+
+| Tool | Total output | Reduction | Meets SSIM ≥ 0.975 | Median time |
+|---|---|---|---|---|
+| Optiq `balanced` | 13.25 → 5.15 MB | 61.1% | 24/24 | 1.4 s |
+| Optiq `fast` | 13.25 → 5.97 MB | 54.9% | 24/24 | 405 ms |
+| browser-image-compression `initialQuality: 0.8` | 13.25 → 10.21 MB | 22.9% | 19/24 | 78 ms |
+| browser-image-compression `fileType: webp, 0.8` | 13.25 → 6.52 MB | 50.8% | 18/24 | 37 ms |
+| browser-image-compression `maxSizeMB: 1` | 13.25 → 7.14 MB | 46.1% | 21/24 (3 large photos were downscaled, not scored) | 128 ms |
+| canvas WebP 0.8 | 13.25 → 6.52 MB | 50.8% | 18/24 | 36 ms |
+
+What the numbers say:
+
+- **Per image, no baseline dominated Optiq `balanced`** (smaller *and* higher SSIM) on any image.
+  `balanced` dominated MozJPEG q80 on 11/20, WebP q80 on 10/24, browser-image-compression WebP 0.8 on 10/24 and
+  AVIF q50 on 2/24; everything else is a trade-off.
+- **AVIF q50 is much smaller on photos, but at SSIM 0.93–0.97**, below the 0.975 constraint on all 10 Kodak photos.
+  Optiq spends bytes to stay above the threshold; whether that threshold is right for you is a product decision.
+- **Category matters.** Screenshots/text: −90.6% / −91.8% vs. −62.8% / −46.6% for WebP q80 (lossless WebP and
+  screen-content AVIF win there). Large 12 MP phone photos: −41.5% with metadata kept (AVIF excluded because EXIF
+  must be preserved), −47.7% with `preserveMetadata: false`, vs. −30.7% for WebP q80.
+- **Optiq is slow and memory-hungry by comparison.** It runs several encodes plus decodes and SSIM per
+  image: 1–4 s typical, 3–4 s for 12 MP photos (8–12 s when AVIF is allowed), 16.6 s for a 5 MP screenshot in
+  `balanced` and 38 s in `visually-lossless`; median peak RSS ≈ 300 MB, up to 1.1 GB. Single canvas/libvips encodes
+  take 5–800 ms. Work runs in a worker, so the UI stays responsive (max main-thread gap 11 ms during a 12 MP job).
+
+**Lossless** (`sc-lossless`, Node): pixel-exact on 24/24 and never larger than the input (total −20.4%).
+PNG photos −27% (oxipng), screenshots −76% and text −91% (about the same as libvips lossless WebP effort 6),
+transparent illustrations −42% and gradients −66%, where libvips PNG max compression reached −60% / −76% but its
+outputs were not pixel-exact against the reference. JPEG inputs: only metadata can be removed losslessly (0% with
+the default `preserveMetadata: true`; no jpegtran in this build).
+
+## Development
+
+Toolchain: Node ≥ 20 (tested with 24.15), pnpm 11, Playwright Chromium (`pnpm exec playwright install chromium chromium-headless-shell`).
+No Rust toolchain is required: all WASM comes prebuilt from pinned jSquash packages.
+
+```sh
+pnpm install
+pnpm typecheck
+pnpm test             # unit + integration tests in Node (real WASM codecs)
+pnpm test:browser     # builds, bundles a consumer page with Vite, runs it in Chromium (incl. CSP/no-WASM fallback)
+pnpm test:demo        # demo end-to-end (light/dark/mobile): compress → presign → PUT to mock S3
+pnpm pack:check       # pack the tarball, install it in a fresh Vite app, typecheck, build, run (does not publish)
+pnpm demo             # React + HeroUI demo with a mock presigned-S3 backend
+pnpm docs:dev         # VitePress documentation site
+pnpm bench:corpus     # download/render the benchmark corpus (24 images)
+pnpm bench:node       # Optiq vs libvips (sharp), with peak RSS per run
+pnpm bench:browser    # Optiq vs browser-image-compression and canvas, in Chromium
+pnpm bench:report     # writes bench/results/RESULTS.md
+```
+
+Documentation site (guides, API reference generated from the TSDoc comments, benchmarks, architecture):
+`pnpm docs:dev`, or read the Markdown in [`docs/`](https://github.com/Baukaalm/optiq/blob/main/docs/). Design notes: [docs/architecture.md](https://github.com/Baukaalm/optiq/blob/main/docs/architecture.md).

package/dist/batch-worker.d.ts

@@ -0,0 +1,6 @@
+import type { OptiqOptions } from "./types.js";
+export interface BatchRequest {
+    id: number;
+    path: string;
+    options: OptiqOptions;
+}

package/dist/batch-worker.js

@@ -0,0 +1,17 @@
+// worker_threads entry for batch optimisation in Node (CLI, Vite plugin). One image at a time per thread:
+// the WASM codecs are single-threaded, so parallelism comes from running several of these.
+import { readFile } from "node:fs/promises";
+import { parentPort } from "node:worker_threads";
+import { serializeError } from "./errors.js";
+import { optimizeInNode } from "./node.js";
+parentPort.on("message", async (req) => {
+    try {
+        const input = new Uint8Array(await readFile(req.path));
+        const out = await optimizeInNode(input, req.options);
+        const bytes = out.bytes ? out.bytes.slice().buffer : undefined;
+        parentPort.postMessage({ id: req.id, ok: true, bytes, report: out.report }, bytes ? [bytes] : []);
+    }
+    catch (e) {
+        parentPort.postMessage({ id: req.id, ok: false, error: serializeError(e) });
+    }
+});

package/dist/batch.d.ts

@@ -0,0 +1,16 @@
+import type { EngineReport } from "./engine.js";
+import { type OptiqError } from "./errors.js";
+import type { OptiqOptions } from "./types.js";
+export interface BatchItemResult {
+    path: string;
+    /** Output bytes; undefined when the input was already optimal (report.usedOriginal). */
+    bytes?: Uint8Array;
+    report?: EngineReport;
+    error?: OptiqError;
+}
+export interface BatchOptions {
+    /** Worker threads. Default: available cores − 1 (at least 1). Each holds a few copies of one decoded image. */
+    concurrency?: number;
+    onResult?: (r: BatchItemResult, done: number, total: number) => void;
+}
+export declare function optimizeFiles(paths: string[], options: OptiqOptions, batch?: BatchOptions): Promise<BatchItemResult[]>;

package/dist/batch.js

@@ -0,0 +1,51 @@
+/**
+ * Batch optimisation of files in Node using a pool of worker threads (used by the CLI and the Vite plugin).
+ */
+import { availableParallelism } from "node:os";
+import { Worker } from "node:worker_threads";
+import { deserializeError } from "./errors.js";
+export async function optimizeFiles(paths, options, batch = {}) {
+    const n = Math.max(1, Math.min(paths.length, batch.concurrency ?? Math.max(1, availableParallelism() - 1)));
+    const results = new Array(paths.length);
+    if (!paths.length)
+        return results;
+    let next = 0;
+    let done = 0;
+    await new Promise((resolve, reject) => {
+        const workers = [];
+        const finish = () => {
+            for (const w of workers)
+                void w.terminate();
+            resolve();
+        };
+        const feed = (w) => {
+            if (next >= paths.length)
+                return;
+            const id = next++;
+            w.postMessage({ id, path: paths[id], options });
+        };
+        for (let i = 0; i < n; i++) {
+            const w = new Worker(new URL("./batch-worker.js", import.meta.url));
+            workers.push(w);
+            w.on("message", (m) => {
+                const r = m.ok
+                    ? { path: paths[m.id], bytes: m.bytes ? new Uint8Array(m.bytes) : undefined, report: m.report }
+                    : { path: paths[m.id], error: deserializeError(m.error) };
+                results[m.id] = r;
+                done++;
+                batch.onResult?.(r, done, paths.length);
+                if (done === paths.length)
+                    finish();
+                else
+                    feed(w);
+            });
+            w.on("error", (e) => {
+                for (const x of workers)
+                    void x.terminate();
+                reject(e);
+            });
+            feed(w);
+        }
+    });
+    return results;
+}

package/dist/classify.d.ts

@@ -0,0 +1,31 @@
+import type { RawImage } from "./pixels.js";
+import type { ImageCategory } from "./types.js";
+export interface ImageFeatures {
+    sampledPixels: number;
+    /** Distinct RGBA values among sampled pixels (capped at 4096). */
+    uniqueColors: number;
+    /** Share of sampled pixels having the single most common colour (background). */
+    dominantColorShare: number;
+    /** Horizontally/vertically adjacent pairs with identical RGBA. */
+    flatShare: number;
+    /** Adjacent pairs with luma step > 64 (hard edges: text, UI lines). */
+    hardEdgeShare: number;
+    /** Adjacent non-identical pairs with luma step <= 3 (smooth ramps). */
+    smoothStepShare: number;
+    /** Pixels with alpha < 255. */
+    transparentShare: number;
+}
+/**
+ * Deterministic feature extraction on a grid of up to 24x24 patches of 16x16 contiguous pixels.
+ * Adjacency is only evaluated inside patches, so it reflects the full-resolution content without scanning every pixel.
+ */
+export declare function extractFeatures(img: RawImage): ImageFeatures;
+/**
+ * Heuristic rules with hand-set thresholds, checked against the test fixtures and the benchmark corpus (see docs/architecture.md);
+ * the category only steers which codecs/settings are tried first, never the quality decision.
+ */
+export declare function classifyFeatures(f: ImageFeatures): ImageCategory;
+export declare function classify(img: RawImage): {
+    category: ImageCategory;
+    features: ImageFeatures;
+};