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

package/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Changelog
 
-## 0.2.0-beta.0 (unreleased)
+## 0.3.0-beta.0 (2026-10-28)
+
+- `fast` mode starts each codec's quality search from a prediction (ridge regression on cheap image features,
+  fitted on a 317-image corpus in `bench/predictor/`). Benchmark: −8.0% bytes and −18% time vs the fixed start;
+  quality still verified for every output. Not enabled for `balanced`, where it traded size for speed.
+- Demo: settings apply to all loaded images immediately; compare and candidates sections expanded by default.
+
+## 0.2.0-beta.0 (2026-10-27)
 
 - `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).
@@ -9,7 +16,7 @@
 - `optiq-image/react`: `useOptiq(file, options)` hook.
 - `optimizeFiles()` batch API for Node (worker_threads pool).
 
-## 0.1.0-beta.0 (unreleased)
+## 0.1.0-beta.0 (2026-10-27)
 
 Audit fixes (see docs/audit.md):
 

package/README.md

@@ -197,7 +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 `fast` (no AVIF, ≤ 5 encodes) | 13.25 → 5.49 MB | 58.5% | 24/24 | 434 ms | 173 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 |
@@ -209,7 +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 |
+| Optiq `fast` | 13.25 → 5.49 MB | 58.5% | 24/24 | 349 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/classify.d.ts

@@ -14,6 +14,12 @@ export interface ImageFeatures {
     smoothStepShare: number;
     /** Pixels with alpha < 255. */
     transparentShare: number;
+    /** Texture features used by the quality predictor (see src/predictor.ts). */
+    lumaStd: number;
+    chromaRms: number;
+    meanGrad: number;
+    edgeShare16: number;
+    hfEnergy: number;
 }
 /**
  * Deterministic feature extraction on a grid of up to 24x24 patches of 16x16 contiguous pixels.

package/dist/classify.js

@@ -13,6 +13,9 @@ export function extractFeatures(img) {
     const ny = Math.min(MAX_PATCHES_PER_AXIS, Math.max(1, Math.floor(H / ph)));
     const counts = new Map();
     let sampled = 0, pairs = 0, flat = 0, hard = 0, smooth = 0, transparent = 0;
+    // Texture statistics (float BT.601 luma/chroma; must match bench/predictor/features.mjs used for fitting).
+    let sumY = 0, sumY2 = 0, sumC2 = 0, grad = 0, gradN = 0, edges16 = 0, lap = 0, lapN = 0;
+    const Yf = (o) => 0.299 * data[o] + 0.587 * data[o + 1] + 0.114 * data[o + 2];
     const luma = (o) => (data[o] * 77 + data[o + 1] * 150 + data[o + 2] * 29) >> 8;
     const word = (o) => ((data[o] << 24) | (data[o + 1] << 16) | (data[o + 2] << 8) | data[o + 3]) >>> 0;
     const pair = (a, b) => {
@@ -44,6 +47,24 @@ export function extractFeatures(img) {
                         pair(o, o + 4);
                     if (y + 1 < y0 + ph)
                         pair(o, o + W * 4);
+                    const yy = Yf(o);
+                    const cb = -0.168736 * data[o] - 0.331264 * data[o + 1] + 0.5 * data[o + 2];
+                    const cr = 0.5 * data[o] - 0.418688 * data[o + 1] - 0.081312 * data[o + 2];
+                    sumY += yy;
+                    sumY2 += yy * yy;
+                    sumC2 += cb * cb + cr * cr;
+                    if (x + 1 < x0 + pw) {
+                        const d = Math.abs(yy - Yf(o + 4));
+                        grad += d;
+                        gradN++;
+                        if (d > 16)
+                            edges16++;
+                    }
+                    if (x > x0 && x + 1 < x0 + pw && y > y0 && y + 1 < y0 + ph) {
+                        const l = 4 * yy - Yf(o - 4) - Yf(o + 4) - Yf(o - W * 4) - Yf(o + W * 4);
+                        lap += l * l;
+                        lapN++;
+                    }
                 }
             }
         }
@@ -60,6 +81,11 @@ export function extractFeatures(img) {
         hardEdgeShare: pairs ? hard / pairs : 0,
         smoothStepShare: pairs ? smooth / pairs : 0,
         transparentShare: transparent / sampled,
+        lumaStd: Math.sqrt(Math.max(0, sumY2 / sampled - (sumY / sampled) ** 2)) / 255,
+        chromaRms: Math.sqrt(sumC2 / (2 * sampled)) / 128,
+        meanGrad: gradN ? grad / gradN / 255 : 0,
+        edgeShare16: gradN ? edges16 / gradN : 0,
+        hfEnergy: Math.sqrt(lap / Math.max(1, lapN)) / 255,
     };
 }
 /**

package/dist/engine.js

@@ -9,6 +9,7 @@ import { OptiqError, throwIfAborted } from "./errors.js";
 import { OUTPUT_FORMATS, resolveOptions } from "./options.js";
 import { applyOrientation, hasTransparentPixels, pixelsEqual, targetSize, tileMosaic } from "./pixels.js";
 import { effectiveMinQuality, losslessPlans, planCandidates } from "./plan.js";
+import { predictStart } from "./predictor.js";
 import { displayDimensions, probe } from "./probe.js";
 import { ssim } from "./quality.js";
 const MIME = {
@@ -307,7 +308,7 @@ export async function optimize(input, options, ctx) {
         check();
     }
     emit("analyzing", 0.12);
-    const { category } = await timed("classify", () => classify(reference));
+    const { category, features } = await timed("classify", () => classify(reference));
     minQuality = effectiveMinQuality(category, opts);
     const planInput = {
         category,
@@ -423,6 +424,13 @@ export async function optimize(input, options, ctx) {
         let hi = hi0; // search upper bound
         let passQ;
         let q = plan.start;
+        // The predictor was fitted for the balanced thresholds and settings (shared by `fast`).
+        const predicted = opts.searchStart !== "fixed" && (opts.mode === "balanced" || opts.mode === "fast") && plan.format !== "png"
+            ? predictStart(plan.format, category, features, opts.searchStart)
+            : undefined;
+        if (predicted)
+            q = Math.max(lo0, Math.min(hi0, predicted.start));
+        let steppedDown = false;
         while (share > 0 && lo <= hi) {
             const c = await tryEvaluate(plan, { ...plan.settings, quality: q }, useProxy);
             if (!c)
@@ -443,8 +451,19 @@ export async function optimize(input, options, ctx) {
                 break;
             if (passQ === undefined && q >= hi0)
                 break;
-            // Next probe: bisect the open interval; if nothing passed yet, move up towards the top of the range.
-            q = passQ === undefined ? Math.min(hi, Math.ceil((lo + hi0) / 2)) : Math.floor((lo + hi) / 2);
+            if (predicted && passQ !== undefined && lo === lo0 && !steppedDown) {
+                // The predicted start passed and nothing has failed yet: probe one typical-error step lower before bisecting.
+                // (Upward moves keep the original bisection towards the top of the range: growing upward jumps overshot
+                // and exhausted the budget in the first comparison run — kodim19 +81% bytes.)
+                {
+                    steppedDown = true;
+                    q = Math.max(lo0, passQ - predicted.step);
+                }
+            }
+            else {
+                // Next probe: bisect the open interval; if nothing passed yet, move up towards the top of the range.
+                q = passQ === undefined ? Math.min(hi, Math.ceil((lo + hi0) / 2)) : Math.floor((lo + hi) / 2);
+            }
             if (passQ === undefined && share === 0)
                 break;
         }

package/dist/options.d.ts

@@ -19,6 +19,7 @@ export interface ResolvedOptions {
     /** Quality search tolerance (codec quality units). */
     qualityTolerance: number;
     avifSpeed: number;
+    searchStart: "fixed" | "category" | "model";
 }
 export declare const OUTPUT_FORMATS: readonly OutputFormat[];
 export declare const MODE_DEFAULTS: Record<CompressionMode, {

package/dist/options.js

@@ -67,5 +67,8 @@ export function resolveOptions(o = {}) {
         onUnmetConstraints: o.onUnmetConstraints ?? "best-effort",
         qualityTolerance: d.qualityTolerance,
         avifSpeed: d.avifSpeed,
+        // Measured (bench/predictor/compare.mjs): the feature-based start is a clean win only in `fast` (fewer encodes,
+        // smaller files on both the held-out split and the independent corpus); in `balanced` it traded size for speed.
+        searchStart: o.searchStart ?? (mode === "fast" ? "model" : "fixed"),
     };
 }

package/dist/predictor-model.d.ts

@@ -0,0 +1,7 @@
+export declare const PREDICTOR_MODEL: Record<string, {
+    c: number;
+    w: number[];
+    sigma: number;
+    median: number;
+    n: number;
+}>;

package/dist/predictor-model.js

@@ -0,0 +1,112 @@
+// Generated by bench/predictor/fit.mjs from bench/predictor/labels.jsonl (train split). Do not edit by hand.
+// Ridge regression: quality ≈ c + Σ w_i · feature_i, features in this order: logHf, logGrad, lumaStd, chromaRms, flat, smooth, hardEdge, edge16, logColors, transparent.
+export const PREDICTOR_MODEL = {
+    "avif:photo": {
+        "c": 61.909,
+        "w": [
+            4.8476,
+            4.4747,
+            6.8754,
+            -32.094,
+            2.6394,
+            -0.4836,
+            -131.98,
+            -50.1434,
+            3.8811,
+            0
+        ],
+        "sigma": 6.13,
+        "median": 55,
+        "n": 139
+    },
+    "avif:graphic": {
+        "c": 72.4676,
+        "w": [
+            -0.2699,
+            0.4591,
+            -15.8289,
+            -9.0301,
+            -42.8535,
+            -16.7837,
+            -129.1587,
+            16.6855,
+            1.0012,
+            -1.8608
+        ],
+        "sigma": 7.5,
+        "median": 29,
+        "n": 87
+    },
+    "webp:photo": {
+        "c": 99.1048,
+        "w": [
+            6.3456,
+            4.9984,
+            13.8173,
+            -28.2776,
+            -20.9312,
+            -7.2995,
+            -252.7529,
+            -59.7518,
+            3.1287,
+            0
+        ],
+        "sigma": 8.38,
+        "median": 76,
+        "n": 138
+    },
+    "webp:graphic": {
+        "c": 105.9106,
+        "w": [
+            0.2885,
+            0.5672,
+            -26.2165,
+            15.9697,
+            -50.1994,
+            -10.1447,
+            9.9325,
+            -60.0364,
+            -1.6271,
+            0.1538
+        ],
+        "sigma": 7.47,
+        "median": 40,
+        "n": 87
+    },
+    "jpeg:photo": {
+        "c": 88.448,
+        "w": [
+            7.4945,
+            2.0242,
+            -2.5954,
+            -23.0289,
+            -6.7996,
+            -3.7135,
+            -62.2263,
+            -19.1349,
+            1.589,
+            0
+        ],
+        "sigma": 5.48,
+        "median": 69,
+        "n": 139
+    },
+    "jpeg:graphic": {
+        "c": 118.758,
+        "w": [
+            -0.1487,
+            2.945,
+            -26.4641,
+            -11.9989,
+            -45.233,
+            -7.9,
+            49.1273,
+            27.3451,
+            -2.4267,
+            0
+        ],
+        "sigma": 9.77,
+        "median": 52,
+        "n": 68
+    }
+};

package/dist/predictor.d.ts

@@ -0,0 +1,16 @@
+import type { ImageFeatures } from "./classify.js";
+import type { ImageCategory, OutputFormat } from "./types.js";
+/**
+ * Where the per-codec quality search starts.
+ * - `fixed`: one start per mode (original behaviour);
+ * - `category`: median quality needed per codec, separately for photos and graphics (fitted on bench/predictor);
+ * - `model`: ridge regression on cheap image features (same fit).
+ * The search always verifies its result, so a bad start costs encodes, never quality.
+ */
+export type SearchStart = "fixed" | "category" | "model";
+export interface PredictedStart {
+    start: number;
+    /** Step for the first probe after the start (≈ typical prediction error). */
+    step: number;
+}
+export declare function predictStart(format: Exclude<OutputFormat, "png">, category: ImageCategory, features: ImageFeatures, how: Exclude<SearchStart, "fixed">): PredictedStart | undefined;

package/dist/predictor.js

@@ -0,0 +1,24 @@
+import { PREDICTOR_MODEL } from "./predictor-model.js";
+const GRAPHIC = new Set(["screenshot", "text-graphic", "illustration", "transparent-illustration"]);
+const FEATURE_FNS = [
+    (f) => Math.log(f.hfEnergy + 1e-4),
+    (f) => Math.log(f.meanGrad + 1e-4),
+    (f) => f.lumaStd,
+    (f) => f.chromaRms,
+    (f) => f.flatShare,
+    (f) => f.smoothStepShare,
+    (f) => f.hardEdgeShare,
+    (f) => f.edgeShare16,
+    (f) => Math.log(f.uniqueColors),
+    (f) => f.transparentShare,
+];
+export function predictStart(format, category, features, how) {
+    const m = PREDICTOR_MODEL[`${format}:${GRAPHIC.has(category) ? "graphic" : "photo"}`];
+    if (!m)
+        return undefined;
+    if (how === "category")
+        return { start: m.median, step: Math.max(3, Math.round(m.sigma)) };
+    const q = m.c + m.w.reduce((s, w, i) => s + w * FEATURE_FNS[i](features), 0);
+    // Start half a typical error above the prediction: a first encode that passes is cheaper to refine downwards.
+    return { start: Math.round(q + m.sigma / 2), step: Math.max(3, Math.round(m.sigma)) };
+}

package/dist/types.d.ts

@@ -48,6 +48,11 @@ export interface OptiqOptions {
     maxInputBytes?: number;
     /** Reject inputs whose header declares more pixels than this (decompression-bomb guard). Default 50 MP. */
     maxInputPixels?: number;
+    /**
+     * Where each codec's quality search starts. Only affects speed, never the quality guarantee.
+     * @internal Benchmarking switch; the default is chosen from measurements (see docs/audit.md).
+     */
+    searchStart?: "fixed" | "category" | "model";
     /** What to do when no candidate meets all constraints. Default `best-effort` (result lists `unmetConstraints`). */
     onUnmetConstraints?: "best-effort" | "throw";
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "optiq-image",
-  "version": "0.2.0-beta.0",
+  "version": "0.3.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)",
@@ -35,7 +35,7 @@
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "bin": {
-    "optiq-image": "./dist/cli.js"
+    "optiq-image": "dist/cli.js"
   },
   "exports": {
     ".": {