optiq-image 0.1.0-beta.0 → 0.2.0-beta.0

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # 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):

package/README.md

@@ -94,7 +94,7 @@ For explicit control over workers use `createCompressor({ maxWorkers, workerFact
 
 | Option | Default | Meaning |
 |---|---|---|
-| `mode` | `"balanced"` | `lossless`, `visually-lossless`, `balanced` |
+| `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` |
@@ -115,6 +115,24 @@ Error codes: `INVALID_INPUT`, `UNSUPPORTED_FORMAT`, `MALFORMED_INPUT`, `INPUT_TO
 `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
@@ -179,6 +197,7 @@ input. Full tables, per-image rows and the optimisation log: [`bench/results/RES
 | 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 |
@@ -190,6 +209,7 @@ input. Full tables, per-image rows and the optimisation log: [`bench/results/RES
 | 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 |

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/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export declare function main(argv?: string[]): Promise<number>;

package/dist/cli.js

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * `optiq-image` command line: optimise image files or folders with the same engine as the browser library.
+ * Default is a dry run that only reports; pass --out or --in-place to write.
+ */
+import { mkdir, readdir, stat, writeFile, rename } from "node:fs/promises";
+import { dirname, extname, join, relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { optimizeFiles } from "./batch.js";
+import { fileNameFor } from "./client.js";
+const HELP = `Usage: optiq-image <files or folders...> [options]
+
+Optimise images with Optiq (the same WASM codecs and quality checks as in the browser).
+Without --out or --in-place nothing is written: you get a report (dry run).
+
+Options
+  --mode <m>            fast | balanced (default) | visually-lossless | lossless
+  --out <dir>           write results to <dir>, mirroring the input folder structure
+  --in-place            overwrite inputs (keeps each file's format, so references stay valid)
+  --keep-format         never change the format (implied by --in-place)
+  --formats <list>      formats auto may choose, e.g. "webp,jpeg" (default: jpeg,png,webp,avif; fast: no avif)
+  --max-size <px>       downscale the longest side (in lossless mode this also allows the resize)
+  --strip-metadata      remove EXIF (incl. GPS) and XMP
+  --min-quality <ssim>  SSIM threshold for perceptual modes (e.g. 0.98)
+  --concurrency <n>     worker threads (default: CPU cores - 1)
+  --json                print a JSON report instead of a table
+  -h, --help            show this help
+
+Examples
+  npx optiq-image ./photos --out ./photos-optimized
+  npx optiq-image public/images --in-place --mode visually-lossless
+  npx optiq-image hero.png --formats webp,avif --out dist/img --json
+`;
+const IMAGE_EXT = new Set([".jpg", ".jpeg", ".png", ".webp", ".avif", ".gif"]);
+async function collect(paths) {
+    const out = [];
+    async function walk(p, root) {
+        const s = await stat(p);
+        if (s.isDirectory()) {
+            for (const e of await readdir(p))
+                if (!e.startsWith("."))
+                    await walk(join(p, e), root);
+        }
+        else if (IMAGE_EXT.has(extname(p).toLowerCase()))
+            out.push({ file: p, root });
+    }
+    for (const p of paths) {
+        const abs = resolve(p);
+        const s = await stat(abs);
+        await walk(abs, s.isDirectory() ? abs : dirname(abs));
+    }
+    return out;
+}
+const kb = (n) => (n < 1024 ? `${n} B` : n < 1048576 ? `${(n / 1024).toFixed(1)} KB` : `${(n / 1048576).toFixed(2)} MB`);
+export async function main(argv = process.argv.slice(2)) {
+    const { values: a, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            mode: { type: "string" },
+            out: { type: "string" },
+            "in-place": { type: "boolean" },
+            "keep-format": { type: "boolean" },
+            formats: { type: "string" },
+            "max-size": { type: "string" },
+            "strip-metadata": { type: "boolean" },
+            "min-quality": { type: "string" },
+            concurrency: { type: "string" },
+            json: { type: "boolean" },
+            help: { type: "boolean", short: "h" },
+        },
+    });
+    if (a.help || !positionals.length) {
+        process.stdout.write(HELP);
+        return a.help ? 0 : 1;
+    }
+    if (a.out && a["in-place"])
+        throw new Error("Use either --out or --in-place, not both");
+    const keepFormat = !!(a["keep-format"] || a["in-place"]);
+    const maxSize = a["max-size"] ? Number(a["max-size"]) : undefined;
+    const options = {
+        mode: a.mode ?? "balanced",
+        allowFormatConversion: !keepFormat,
+        autoFormats: a.formats ? a.formats.split(",").map((s) => s.trim()) : undefined,
+        maxWidthOrHeight: maxSize,
+        allowLossyResize: maxSize !== undefined,
+        preserveMetadata: !a["strip-metadata"],
+        minQuality: a["min-quality"] ? Number(a["min-quality"]) : undefined,
+    };
+    const files = await collect(positionals);
+    if (!files.length) {
+        process.stderr.write("No images found (jpg, jpeg, png, webp, avif, gif)\n");
+        return 1;
+    }
+    const t0 = performance.now();
+    const results = await optimizeFiles(files.map((f) => f.file), options, {
+        concurrency: a.concurrency ? Number(a.concurrency) : undefined,
+        onResult: a.json || !process.stderr.isTTY ? undefined : (r, done, total) => process.stderr.write(`\r${done}/${total} ${relative(process.cwd(), r.path)}`.padEnd(80).slice(0, 100)),
+    });
+    if (!a.json && process.stderr.isTTY)
+        process.stderr.write("\r".padEnd(101) + "\r");
+    const rows = [];
+    let before = 0, after = 0, errors = 0;
+    for (let i = 0; i < results.length; i++) {
+        const r = results[i];
+        const { file, root } = files[i];
+        const rel = relative(root, file);
+        if (r.error || !r.report) {
+            errors++;
+            rows.push({ file: relative(process.cwd(), file), error: `${r.error?.code ?? "ERROR"}: ${r.error?.message}` });
+            continue;
+        }
+        const rep = r.report;
+        before += rep.originalBytes;
+        after += rep.outputBytes;
+        let written;
+        if (r.bytes && (a.out || a["in-place"])) {
+            if (a["in-place"]) {
+                // Write next to the file, then rename: never leaves a half-written image behind.
+                const tmp = `${file}.optiq-tmp`;
+                await writeFile(tmp, r.bytes);
+                await rename(tmp, file);
+                written = file;
+            }
+            else {
+                const target = join(resolve(a.out), dirname(rel), fileNameFor(rel.split(/[\\/]/).pop(), rep.outputFormat));
+                await mkdir(dirname(target), { recursive: true });
+                await writeFile(target, r.bytes);
+                written = target;
+            }
+        }
+        else if (a.out && !r.bytes) {
+            // Already optimal: copy the original so the output folder is complete.
+            const { copyFile } = await import("node:fs/promises");
+            const target = join(resolve(a.out), rel);
+            await mkdir(dirname(target), { recursive: true });
+            await copyFile(file, target);
+            written = target;
+        }
+        rows.push({
+            file: relative(process.cwd(), file),
+            from: rep.originalFormat,
+            to: rep.outputFormat,
+            before: rep.originalBytes,
+            after: rep.outputBytes,
+            saved: rep.sizeReductionRatio,
+            quality: rep.qualityMetricName === "exact" ? "exact" : rep.qualityMetric,
+            usedOriginal: rep.usedOriginal,
+            warnings: rep.warnings,
+            written: written ? relative(process.cwd(), written) : undefined,
+        });
+    }
+    const seconds = (performance.now() - t0) / 1000;
+    if (a.json) {
+        process.stdout.write(JSON.stringify({ options, files: rows, totals: { before, after, saved: before ? 1 - after / before : 0, errors, seconds } }, null, 2) + "\n");
+    }
+    else {
+        for (const r of rows) {
+            if (r.error)
+                process.stdout.write(`✗ ${r.file}  ${r.error}\n`);
+            else
+                process.stdout.write(`${r.usedOriginal ? "=" : "✓"} ${String(r.file).padEnd(40)} ${String(r.from).padEnd(4)}→ ${String(r.to).padEnd(4)} ${kb(r.before).padStart(9)} → ${kb(r.after).padStart(9)}  ${(r.saved * 100).toFixed(1).padStart(5)}%  ${r.quality === "exact" ? "exact" : `SSIM ${r.quality.toFixed(4)}`}\n`);
+        }
+        process.stdout.write(`\n${results.length} files, ${kb(before)} → ${kb(after)} (${before ? ((1 - after / before) * 100).toFixed(1) : 0}% smaller) in ${seconds.toFixed(1)} s${errors ? `, ${errors} failed` : ""}\n`);
+        if (!a.out && !a["in-place"])
+            process.stdout.write("Dry run: nothing written. Use --out <dir> or --in-place.\n");
+    }
+    return errors ? 2 : 0;
+}
+// Run when executed directly (bin), not when imported.
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("/optiq-image") || process.argv[1]?.endsWith("cli.js")) {
+    main().then((code) => process.exit(code), (e) => {
+        process.stderr.write(`optiq-image: ${e instanceof Error ? e.message : String(e)}\n`);
+        process.exit(1);
+    });
+}

package/dist/options.js

@@ -1,12 +1,15 @@
 import { OptiqError } from "./errors.js";
 export const OUTPUT_FORMATS = ["jpeg", "png", "webp", "avif"];
 const TARGETS = ["auto", "original", ...OUTPUT_FORMATS];
-const MODES = ["lossless", "visually-lossless", "balanced"];
+const MODES = ["lossless", "visually-lossless", "balanced", "fast"];
 export const MODE_DEFAULTS = {
     lossless: { minQuality: 1, maxCandidates: 4, qualityTolerance: 0, avifSpeed: 6 },
     "visually-lossless": { minQuality: 0.99, maxCandidates: 16, qualityTolerance: 3, avifSpeed: 6 },
     // AVIF speed 7, not 8: at speed 8 libaom lost its screen-content gains (5 MP dashboard: 45 KB vs 13 KB at q50).
     balanced: { minQuality: 0.975, maxCandidates: 10, qualityTolerance: 5, avifSpeed: 7 },
+    // Same quality bar as balanced; cost is capped instead: AVIF (3.5 MB download, slowest encoder, most memory) is off
+    // by default, oxipng is skipped, and the quality search stops early.
+    fast: { minQuality: 0.975, maxCandidates: 5, qualityTolerance: 8, avifSpeed: 8 },
 };
 function invalid(message) {
     throw new OptiqError("INVALID_OPTIONS", message);
@@ -26,7 +29,7 @@ export function resolveOptions(o = {}) {
     const targetFormat = o.targetFormat ?? "auto";
     if (!TARGETS.includes(targetFormat))
         invalid(`targetFormat must be one of ${TARGETS.join(", ")}; got "${String(targetFormat)}"`);
-    const autoFormats = o.autoFormats ?? [...OUTPUT_FORMATS];
+    const autoFormats = o.autoFormats ?? (mode === "fast" ? OUTPUT_FORMATS.filter((f) => f !== "avif") : [...OUTPUT_FORMATS]);
     if (!autoFormats.length || autoFormats.some((f) => !OUTPUT_FORMATS.includes(f)))
         invalid(`autoFormats must be a non-empty subset of ${OUTPUT_FORMATS.join(", ")}`);
     if (o.minQuality !== undefined && (!Number.isFinite(o.minQuality) || o.minQuality <= 0 || o.minQuality > 1)) {

package/dist/plan.js

@@ -8,12 +8,14 @@ const RANGES = {
 const START = {
     "visually-lossless": { jpeg: 86, webp: 86, avif: 72 },
     balanced: { jpeg: 76, webp: 76, avif: 58 },
+    fast: { jpeg: 78, webp: 78, avif: 58 },
 };
 const isGraphic = (c) => c === "screenshot" || c === "text-graphic" || c === "illustration" || c === "transparent-illustration";
 export function losslessPlans(input, mode) {
     const plans = [];
     const has = (f) => input.allowed.includes(f);
-    if (has("png")) {
+    // oxipng costs ~0.3 s per MP and rarely beats lossless WebP on graphics; `fast` only uses it when PNG is required.
+    if (has("png") && !(mode === "fast" && has("webp"))) {
         if (input.pngContainerEligible)
             plans.push({ kind: "exact", format: "png", settings: { level: 2 }, fromContainer: true });
         else if (input.pixelsExact)

package/dist/react.d.ts

@@ -0,0 +1,26 @@
+import { type CompressCallOptions, type Compressor } from "./client.js";
+import type { CompressionResult, ProgressEvent } from "./types.js";
+export type UseOptiqStatus = "idle" | "compressing" | "done" | "error" | "cancelled";
+export interface UseOptiqOptions extends Omit<CompressCallOptions, "signal" | "onProgress"> {
+    /** Use a specific compressor (worker pool) instead of the shared one. */
+    compressor?: Compressor;
+    /** Set to false to keep the hook idle. Default true. */
+    enabled?: boolean;
+}
+export interface UseOptiqState {
+    status: UseOptiqStatus;
+    result?: CompressionResult;
+    /** The thrown value; usually an OptiqError with a `code`. The original file is always still usable. */
+    error?: unknown;
+    progress?: ProgressEvent;
+    /** Abort the running compression (terminates its worker). */
+    cancel: () => void;
+}
+/**
+ * Compress `file` whenever it (or the options) change. Cancels the previous run automatically, and on unmount.
+ *
+ * ```tsx
+ * const { status, result, progress, cancel } = useOptiq(file, { mode: "balanced" });
+ * ```
+ */
+export declare function useOptiq(file: Blob | null | undefined, options?: UseOptiqOptions): UseOptiqState;

package/dist/react.js

@@ -0,0 +1,35 @@
+/**
+ * `optiq-image/react` — React hook around {@link compressImage}. Requires React 18+ (optional peer dependency).
+ *
+ * @packageDocumentation
+ */
+import { useCallback, useEffect, useRef, useState } from "react";
+import { compressImage } from "./client.js";
+/**
+ * Compress `file` whenever it (or the options) change. Cancels the previous run automatically, and on unmount.
+ *
+ * ```tsx
+ * const { status, result, progress, cancel } = useOptiq(file, { mode: "balanced" });
+ * ```
+ */
+export function useOptiq(file, options = {}) {
+    const { compressor, enabled = true, ...compressOptions } = options;
+    const [state, setState] = useState({ status: "idle" });
+    const controller = useRef(undefined);
+    // Options are compared by value so inline objects do not restart the job on every render.
+    const key = JSON.stringify(compressOptions);
+    useEffect(() => {
+        if (!file || !enabled) {
+            setState({ status: "idle" });
+            return;
+        }
+        const ac = new AbortController();
+        controller.current = ac;
+        setState({ status: "compressing" });
+        const run = compressor ? compressor.compress.bind(compressor) : compressImage;
+        run(file, { ...JSON.parse(key), signal: ac.signal, onProgress: (progress) => !ac.signal.aborted && setState({ status: "compressing", progress }) }).then((result) => !ac.signal.aborted && setState({ status: "done", result }), (error) => setState(ac.signal.aborted ? { status: "cancelled" } : { status: "error", error }));
+        return () => ac.abort();
+    }, [file, enabled, key, compressor]);
+    const cancel = useCallback(() => controller.current?.abort(), []);
+    return { ...state, cancel };
+}

package/dist/types.d.ts

@@ -9,8 +9,9 @@ export type TargetFormat = "auto" | "original" | OutputFormat;
  * - `lossless`: decoded pixels (incl. alpha) of the output are verified to be identical to the input.
  * - `visually-lossless`: decoded pixels may differ; the perceptual difference (SSIM) is kept above a strict threshold.
  * - `balanced`: lower SSIM threshold and smaller search budget; trades some quality for size and speed.
+ * - `fast`: same threshold as `balanced`, but no AVIF, no oxipng and at most 5 encodes; for phones and batches.
  */
-export type CompressionMode = "lossless" | "visually-lossless" | "balanced";
+export type CompressionMode = "lossless" | "visually-lossless" | "balanced" | "fast";
 export type ImageCategory = "photo" | "screenshot" | "text-graphic" | "illustration" | "transparent-illustration" | "gradient";
 export type SearchStrategy = "binary" | "fixed";
 export interface OptiqOptions {

package/dist/vite.d.ts

@@ -0,0 +1,17 @@
+import type { Plugin } from "vite";
+import type { CompressionMode } from "./types.js";
+export interface OptiqViteOptions {
+    /** Default `visually-lossless` (SSIM ≥ 0.99, same format). PNG/GIF are only ever optimised losslessly here. */
+    mode?: CompressionMode;
+    /** Only files whose path (relative to outDir) matches. Default: all jpg/jpeg/png/webp/avif. */
+    include?: RegExp;
+    exclude?: RegExp;
+    /** Keep EXIF/XMP. Default `false` for build output (strips GPS etc. from published images). */
+    preserveMetadata?: boolean;
+    /** Worker threads. Default: CPU cores − 1. */
+    concurrency?: number;
+    /** Print a per-file report. Default `true`. */
+    verbose?: boolean;
+}
+export declare function optiq(options?: OptiqViteOptions): Plugin;
+export default optiq;

package/dist/vite.js

@@ -0,0 +1,69 @@
+/**
+ * `optiq-image/vite` — optimise the images in your Vite build output (bundled assets and `public/` files).
+ *
+ * Runs after the bundle is written. Every image keeps its file name and format, so references in HTML, CSS and JS
+ * stay valid; a file is only replaced when the result is smaller and meets the quality constraint.
+ *
+ * @packageDocumentation
+ */
+import { readdir, stat, writeFile } from "node:fs/promises";
+import { extname, join, relative, resolve } from "node:path";
+import { optimizeFiles } from "./batch.js";
+const EXT = /\.(jpe?g|png|webp|avif)$/i;
+async function walk(dir, out = []) {
+    for (const e of await readdir(dir)) {
+        const p = join(dir, e);
+        if ((await stat(p)).isDirectory())
+            await walk(p, out);
+        else
+            out.push(p);
+    }
+    return out;
+}
+export function optiq(options = {}) {
+    let config;
+    return {
+        name: "optiq-image",
+        apply: "build",
+        enforce: "post",
+        configResolved(c) {
+            config = c;
+        },
+        async closeBundle() {
+            const outDir = resolve(config.root, config.build.outDir);
+            const files = (await walk(outDir)).filter((f) => {
+                const rel = relative(outDir, f);
+                return (options.include ?? EXT).test(rel) && EXT.test(extname(f)) && !(options.exclude && options.exclude.test(rel));
+            });
+            if (!files.length)
+                return;
+            const t0 = performance.now();
+            const results = await optimizeFiles(files, {
+                mode: options.mode ?? "visually-lossless",
+                targetFormat: "original",
+                allowFormatConversion: false,
+                preserveMetadata: options.preserveMetadata ?? false,
+            }, { concurrency: options.concurrency });
+            let before = 0;
+            let after = 0;
+            for (const r of results) {
+                const rel = relative(outDir, r.path);
+                if (r.error || !r.report) {
+                    config.logger.warn(`[optiq] ${rel}: ${r.error?.code ?? "error"} ${r.error?.message ?? ""} (left unchanged)`);
+                    continue;
+                }
+                before += r.report.originalBytes;
+                after += r.report.outputBytes;
+                if (r.bytes)
+                    await writeFile(r.path, r.bytes);
+                if (options.verbose !== false && r.bytes) {
+                    const q = r.report.qualityMetricName === "exact" ? "lossless" : `SSIM ${r.report.qualityMetric?.toFixed(4)}`;
+                    config.logger.info(`[optiq] ${rel}  ${r.report.originalBytes} → ${r.report.outputBytes} B (−${(r.report.sizeReductionRatio * 100).toFixed(1)}%, ${q})`);
+                }
+            }
+            config.logger.info(`[optiq] ${files.length} images: ${(before / 1024).toFixed(1)} KB → ${(after / 1024).toFixed(1)} KB ` +
+                `(−${before ? ((1 - after / before) * 100).toFixed(1) : 0}%) in ${((performance.now() - t0) / 1000).toFixed(1)} s`);
+        },
+    };
+}
+export default optiq;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "optiq-image",
-  "version": "0.1.0-beta.0",
+  "version": "0.2.0-beta.0",
   "description": "Browser-side image optimizer: picks the smallest encoding that satisfies lossless or perceptual (SSIM) quality constraints, in a Web Worker.",
   "license": "Apache-2.0",
   "author": "Bauyrzhan (https://github.com/Baukaalm)",
@@ -28,10 +28,15 @@
   ],
   "type": "module",
   "sideEffects": [
-    "./dist/worker.js"
+    "./dist/worker.js",
+    "./dist/batch-worker.js",
+    "./dist/cli.js"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "optiq-image": "./dist/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -52,6 +57,14 @@
     "./node": {
       "types": "./dist/node.d.ts",
       "import": "./dist/node.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
     }
   },
   "files": [
@@ -87,6 +100,18 @@
     "site:build": "pnpm build && node scripts/build-site.mjs",
     "test:site": "pnpm site:build && node test/browser/site-e2e.mjs"
   },
+  "peerDependencies": {
+    "react": ">=18",
+    "vite": ">=5"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "@jsquash/avif": "2.1.1",
     "@jsquash/jpeg": "1.6.0",
@@ -97,8 +122,13 @@
   },
   "devDependencies": {
     "@types/node": "24.19.2",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
     "browser-image-compression": "2.0.2",
+    "jsdom": "30.1.3",
     "playwright": "1.64.1",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
     "sharp": "0.35.5",
     "ssim.js": "3.5.0",
     "typescript": "5.9.3",