@xprite/pixelate 0.0.0-stage → 0.1.1

package/dist/palette.js

@@ -0,0 +1,280 @@
+import { UINT8_MAX } from "./base.js";
+import { assertPixelBuffer, clampByte } from "./base.js";
+import { optimizePalette, paletteCoordinates } from "./quantization.js";
+const RGB_HISTOGRAM_BINS = 32 * 32 * 32;
+const HISTOGRAM_BINS = RGB_HISTOGRAM_BINS * 16 + 1;
+const MAX_EXACT_COLORS = 16_384;
+const REDUCTION_CACHE_SIZE = 65_536;
+function colorKey(data, offset, opaqueVisible = false) {
+    if (data[offset + 3] === 0)
+        return 0;
+    return ((data[offset] << 24) |
+        (data[offset + 1] << 16) |
+        (data[offset + 2] << 8) |
+        (opaqueVisible ? UINT8_MAX : data[offset + 3]) |
+        0);
+}
+function colorFromKey(key) {
+    return [
+        (key >>> 24) & UINT8_MAX,
+        (key >>> 16) & UINT8_MAX,
+        (key >>> 8) & UINT8_MAX,
+        key & UINT8_MAX,
+    ];
+}
+function paletteLimit(value) {
+    if (value === undefined)
+        return 256;
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new RangeError("maxColors must be a positive integer");
+    }
+    return Math.min(256, value);
+}
+function histogramIndex(r, g, b, a) {
+    if (!a)
+        return HISTOGRAM_BINS - 1;
+    return (r >>> 3) | ((g >>> 3) << 5) | ((b >>> 3) << 10) | ((a >>> 4) << 15);
+}
+/** The visible-alpha palette uses the same RGB bins without the constant alpha-plane offset. */
+function opaqueHistogramPalette(image, maxColors) {
+    const counts = new Uint32Array(RGB_HISTOGRAM_BINS);
+    const sumR = new Float64Array(RGB_HISTOGRAM_BINS);
+    const sumG = new Float64Array(RGB_HISTOGRAM_BINS);
+    const sumB = new Float64Array(RGB_HISTOGRAM_BINS);
+    const touched = [];
+    const { data } = image;
+    let total = 0;
+    for (let offset = 0; offset < data.length; offset += 4) {
+        if (!data[offset + 3])
+            continue;
+        total++;
+        const r = data[offset];
+        const g = data[offset + 1];
+        const b = data[offset + 2];
+        const index = (r >>> 3) | ((g >>> 3) << 5) | ((b >>> 3) << 10);
+        if (counts[index] === 0)
+            touched.push(index);
+        counts[index] += 1;
+        sumR[index] += r;
+        sumG[index] += g;
+        sumB[index] += b;
+    }
+    touched.sort((left, right) => counts[right] - counts[left] || left - right);
+    const entries = [];
+    for (let i = 0; i < touched.length; i++) {
+        const index = touched[i];
+        const count = counts[index];
+        entries.push({
+            color: [
+                clampByte(sumR[index] / count),
+                clampByte(sumG[index] / count),
+                clampByte(sumB[index] / count),
+                UINT8_MAX,
+            ],
+            count,
+            coverage: count / total,
+        });
+    }
+    return optimizePalette(entries, maxColors);
+}
+function histogramPalette(image, maxColors, ignoreTransparent, opaqueVisible) {
+    if (opaqueVisible && ignoreTransparent)
+        return opaqueHistogramPalette(image, maxColors);
+    const counts = new Uint32Array(HISTOGRAM_BINS);
+    const sumR = new Float64Array(HISTOGRAM_BINS);
+    const sumG = new Float64Array(HISTOGRAM_BINS);
+    const sumB = new Float64Array(HISTOGRAM_BINS);
+    const sumA = new Float64Array(HISTOGRAM_BINS);
+    const touched = [];
+    const { data } = image;
+    let total = 0;
+    for (let offset = 0; offset < data.length; offset += 4) {
+        const a = opaqueVisible && data[offset + 3] ? UINT8_MAX : data[offset + 3];
+        if (ignoreTransparent && !a)
+            continue;
+        total++;
+        const r = a ? data[offset] : 0;
+        const g = a ? data[offset + 1] : 0;
+        const b = a ? data[offset + 2] : 0;
+        const index = histogramIndex(r, g, b, a);
+        if (counts[index] === 0)
+            touched.push(index);
+        counts[index] += 1;
+        sumR[index] += r;
+        sumG[index] += g;
+        sumB[index] += b;
+        sumA[index] += a;
+    }
+    touched.sort((left, right) => counts[right] - counts[left] || left - right);
+    const entries = [];
+    for (let i = 0; i < touched.length; i += 1) {
+        const index = touched[i];
+        const count = counts[index];
+        entries.push({
+            color: [
+                clampByte(sumR[index] / count),
+                clampByte(sumG[index] / count),
+                clampByte(sumB[index] / count),
+                clampByte(sumA[index] / count),
+            ],
+            count,
+            coverage: count / total,
+        });
+    }
+    return optimizePalette(entries, maxColors);
+}
+/**
+ * Extract a deterministic, bounded palette. Exact colors are retained for
+ * ordinary sprites; a fixed 32x32x32x16 histogram is used for noisy images so
+ * memory stays bounded instead of growing with every photograph pixel.
+ */
+export function extractPalette(image, options = {}) {
+    return extractPaletteWithAlpha(image, options, false);
+}
+function extractPaletteWithAlpha(image, options, opaqueVisible) {
+    assertPixelBuffer(image);
+    const maxColors = paletteLimit(options.maxColors);
+    const exact = new Map();
+    const data = image.data;
+    let overflowed = false;
+    let total = 0;
+    for (let offset = 0; offset < data.length; offset += 4) {
+        if (options.ignoreTransparent && !data[offset + 3])
+            continue;
+        total++;
+        const key = colorKey(data, offset, opaqueVisible);
+        const previous = exact.get(key);
+        if (previous !== undefined) {
+            exact.set(key, previous + 1);
+        }
+        else if (exact.size < MAX_EXACT_COLORS) {
+            exact.set(key, 1);
+        }
+        else {
+            overflowed = true;
+            break;
+        }
+    }
+    if (overflowed)
+        return histogramPalette(image, maxColors, options.ignoreTransparent ?? false, opaqueVisible);
+    const entries = [...exact.entries()]
+        .sort(([keyA, countA], [keyB, countB]) => countB - countA || (keyA >>> 0) - (keyB >>> 0))
+        .map(([key, count]) => ({
+        color: colorFromKey(key),
+        count,
+        coverage: count / total,
+    }));
+    return optimizePalette(entries, maxColors);
+}
+/** Count distinct RGBA values with a bounded result for large images. */
+export function countDistinctColors(image, limit = MAX_EXACT_COLORS) {
+    assertPixelBuffer(image);
+    if (!Number.isSafeInteger(limit) || limit < 1)
+        throw new RangeError("limit must be a positive integer");
+    const colors = new Set();
+    for (let offset = 0; offset < image.data.length; offset += 4) {
+        colors.add(colorKey(image.data, offset));
+        if (colors.size > limit)
+            return limit + 1;
+    }
+    return colors.size;
+}
+function validatePalette(palette) {
+    if (!Array.isArray(palette) || palette.length < 1 || palette.length > 256) {
+        throw new RangeError("palette must contain between 1 and 256 colors");
+    }
+    return palette.map((color, index) => {
+        if (!Array.isArray(color) ||
+            color.length !== 4 ||
+            color.some((channel) => !Number.isFinite(channel))) {
+            throw new TypeError(`palette[${index}] must be an RGBA tuple`);
+        }
+        return [
+            clampByte(color[0]),
+            clampByte(color[1]),
+            clampByte(color[2]),
+            clampByte(color[3]),
+        ];
+    });
+}
+function paletteMatcher(palette, preserveAlpha = false) {
+    const colors = validatePalette(palette);
+    const transparent = colors.some((color) => color[3] === 0);
+    const cache = new Map();
+    const coordinates = colors.map((color) => paletteCoordinates(preserveAlpha && color[3] ? [color[0], color[1], color[2], UINT8_MAX] : color));
+    const nearest = (r, g, b, a) => {
+        const opacity = preserveAlpha && a ? UINT8_MAX : a;
+        const cacheKey = opacity ? (r << 24) | (g << 16) | (b << 8) | opacity : 0;
+        const cached = cache.get(cacheKey);
+        if (cached !== undefined)
+            return cached;
+        const sample = paletteCoordinates([r, g, b, opacity]);
+        let best = 0, bestDistance = Number.POSITIVE_INFINITY;
+        for (let i = 0; i < coordinates.length; i++) {
+            if (preserveAlpha && a && !colors[i][3])
+                continue;
+            const color = coordinates[i];
+            const dl = sample[0] - color[0], da = sample[1] - color[1], db = sample[2] - color[2], opacityDifference = sample[3] - color[3];
+            const distance = dl * dl + da * da + db * db + opacityDifference * opacityDifference;
+            if (distance < bestDistance) {
+                bestDistance = distance;
+                best = i;
+            }
+        }
+        if (cache.size < REDUCTION_CACHE_SIZE)
+            cache.set(cacheKey, best);
+        return best;
+    };
+    return { colors, transparent, nearest };
+}
+/** Perceptual matching with exact RGBA cache keys; colors within a coarse bin may differ. */
+export function reduceToPalette(image, palette, options = {}) {
+    assertPixelBuffer(image);
+    const { colors, transparent, nearest } = paletteMatcher(palette, options.preserveAlpha);
+    const output = new Uint8ClampedArray(image.data.length);
+    const source = image.data;
+    for (let offset = 0; offset < source.length; offset += 4) {
+        if ((transparent || options.preserveAlpha) && source[offset + 3] === 0)
+            continue;
+        const index = nearest(source[offset], source[offset + 1], source[offset + 2], source[offset + 3]);
+        const color = colors[index];
+        output[offset] = color[0];
+        output[offset + 1] = color[1];
+        output[offset + 2] = color[2];
+        output[offset + 3] = options.preserveAlpha ? source[offset + 3] : color[3];
+    }
+    return { width: image.width, height: image.height, data: output };
+}
+/** Palette generation counts visible RGB independently of coverage. */
+export function extractPixelationPalette(image, options = {}) {
+    const entries = extractPaletteWithAlpha(image, { ...options, ignoreTransparent: true }, true);
+    return entries.length
+        ? entries
+        : [{ color: [0, 0, 0, 0], count: image.width * image.height, coverage: 1 }];
+}
+/** Compact mapped-RGB groups for the bounded Structure/TwoStage palettes. */
+export function reduceToPixelationLabels(image, palette) {
+    assertPixelBuffer(image);
+    const { colors, nearest } = paletteMatcher(palette, true);
+    const keys = [0];
+    const groups = new Map([[0, 0]]);
+    const paletteGroups = colors.map((color) => {
+        const key = (color[0] << 16) | (color[1] << 8) | color[2];
+        let group = groups.get(key);
+        if (group === undefined) {
+            group = keys.length;
+            groups.set(key, group);
+            keys.push(key);
+        }
+        return group;
+    });
+    const data = new Uint8Array(image.width * image.height);
+    const source = image.data;
+    for (let offset = 0; offset < source.length; offset += 4) {
+        if (source[offset + 3] === 0)
+            continue;
+        data[offset / 4] =
+            paletteGroups[nearest(source[offset], source[offset + 1], source[offset + 2], source[offset + 3])];
+    }
+    return { data, keys };
+}

package/dist/pixelate.d.ts

@@ -0,0 +1,15 @@
+import type { PixelBuffer } from "./base.ts";
+import type { PixelateOptions } from "./types.ts";
+/**
+ * Pixelate an RGBA buffer without touching the source. Nearest mode follows
+ * nearest-neighbor `floor(dst * src / dst)` mapping. Box mode averages the
+ * source area covered by each destination pixel. Local dominant and structural
+ * sampling preserve contrasting regions; grid recovery restores one RGBA pixel
+ * per detected cell. Limiting colours keeps each pixel's own alpha.
+ */
+export declare function pixelateImage(image: PixelBuffer, options?: PixelateOptions): PixelBuffer;
+/**
+ * Async pixelate for product Auto path (import-worker). Same output as pixelateImage;
+ * Auto detect overlaps WASM AC+RL with proposers via Promise join (no COOP/COEP).
+ */
+export declare function pixelateImageAsync(image: PixelBuffer, options?: PixelateOptions): Promise<PixelBuffer>;

package/dist/pixelate.js

@@ -0,0 +1,214 @@
+import { assertDimension, assertPixelBuffer } from "./base.js";
+import { protectPixelationContours } from "./contours.js";
+import { smoothPixelation } from "./denoise.js";
+import { blockPartition } from "./grid.js";
+import { prepareGridSampling } from "./grid-sampling.js";
+import { runPixeloe } from "./line-guided/pixeloe-entry.js";
+import { resizeMostFrequent } from "./most-frequent.js";
+import { applyOutlinePrepass, DEFAULT_LINE_GUIDE, runsStockPixeloe, } from "./outline-prepass.js";
+import { snapPalette } from "./palette-snap.js";
+import { detectWithAlgorithm, detectWithAlgorithmAsync, recoverWithGrid, } from "./pixelation-algorithm-registry.js";
+import { resizeBox, resizeNearest } from "./resize.js";
+import { samplePixelation } from "./sampling.js";
+import { OutlinePrepass, PixelationMethod, PixelationMode, PixelationAlgorithm, } from "./types.js";
+const WORKING_SCALE = 4;
+const MAX_WORKING_PIXELS = 1_048_576;
+const MAX_OUTLINE_STRENGTH = 100;
+function prepareSource(image, target, outlineStrength) {
+    const scale = Math.min(WORKING_SCALE, Math.sqrt(MAX_WORKING_PIXELS / (target.width * target.height)));
+    const width = Math.min(image.width, Math.max(1, Math.ceil(target.width * scale)));
+    const height = Math.min(image.height, Math.max(1, Math.ceil(target.height * scale)));
+    const working = image.width === width && image.height === height
+        ? image
+        : resizeBox(image, width, height, "premultiplied");
+    return protectPixelationContours(working, outlineStrength);
+}
+function uniformBlocks(image, target) {
+    return {
+        ...blockPartition(image, target.width, target.height),
+        confidence: 1,
+        reliable: true,
+        algorithm: PixelationAlgorithm.UniformGrid,
+    };
+}
+function sampleImage(image, options, method) {
+    // Grid recovery runs when asked for, or when only an algorithm was named and it finds a reliable grid.
+    const wantsGrid = options.mode === PixelationMode.RecoverGrid ||
+        (options.mode === undefined && options.algorithm !== undefined);
+    const grid = options.grid ??
+        (wantsGrid
+            ? detectWithAlgorithm(image, options.algorithm ?? PixelationAlgorithm.Auto)
+            : undefined);
+    const mode = options.mode ??
+        (grid && (!("reliable" in grid) || grid.reliable)
+            ? PixelationMode.RecoverGrid
+            : PixelationMode.Convert);
+    if (mode !== PixelationMode.Convert && mode !== PixelationMode.RecoverGrid)
+        throw new RangeError("Unknown pixelation mode.");
+    const prepass = options.prepass ?? OutlinePrepass.None;
+    const guide = prepass === OutlinePrepass.PixeloeLines ? (options.lineGuide ?? DEFAULT_LINE_GUIDE) : undefined;
+    if (mode === PixelationMode.RecoverGrid) {
+        const found = grid ?? detectWithAlgorithm(image, options.algorithm ?? PixelationAlgorithm.Auto);
+        if ("reliable" in found && !found.reliable)
+            throw new Error("No consistent pixel grid was detected. Turn off Automatic grid and choose cell sizes.");
+        const cell = (found.cellWidth + found.cellHeight) / 2;
+        const analysis = found;
+        const upright = prepareGridSampling(image, analysis);
+        const gridForRecover = { ...analysis, rotation: undefined, sampling: undefined };
+        // Custom size's even blocks with PixelOE + Contrast: stock PixelOE to that size.
+        if (runsStockPixeloe({ ...options, mode }, found))
+            return runPixeloe(upright, { width: found.width, height: found.height }, guide);
+        return recoverWithGrid(applyOutlinePrepass(upright, cell, prepass, options.lineGuide), gridForRecover, options.colorPicker);
+    }
+    const target = resolveTargetSize(image, options);
+    // PixelOE + Contrast without a recovered grid is stock PixelOE: the reference result.
+    if (runsStockPixeloe({ ...options, mode }, undefined))
+        return runPixeloe(image, target, guide);
+    // Otherwise an independent pre-pass; whatever sampler or colour picker follows works on its result.
+    image = applyOutlinePrepass(image, (image.width / target.width + image.height / target.height) / 2, prepass, options.lineGuide);
+    const strength = options.outlineStrength ?? 0;
+    if (!Number.isFinite(strength) || strength < 0 || strength > MAX_OUTLINE_STRENGTH)
+        throw new RangeError("Outline protection must be between 0 and 100.");
+    if (options.blockPicker)
+        return recoverWithGrid(image, uniformBlocks(image, target), options.colorPicker);
+    const alphaMode = options.alphaMode ?? "straight";
+    if (alphaMode !== "straight" && alphaMode !== "premultiplied")
+        throw new RangeError("alphaMode must be 'straight' or 'premultiplied'");
+    const prepared = strength || method === PixelationMethod.Dominant || method === PixelationMethod.Structure
+        ? prepareSource(image, target, strength)
+        : image;
+    if (method === PixelationMethod.Nearest)
+        return resizeNearest(prepared, target.width, target.height);
+    if (method === PixelationMethod.Box)
+        return resizeBox(prepared, target.width, target.height, alphaMode);
+    if (method === PixelationMethod.MostFrequent)
+        return resizeMostFrequent(prepared, target.width, target.height);
+    return samplePixelation(prepared, target.width, target.height, method);
+}
+function sizeFromBlock(blockSize, image) {
+    if (typeof blockSize === "number") {
+        assertDimension(blockSize, "blockSize");
+        return {
+            width: Math.max(1, Math.ceil(image.width / blockSize)),
+            height: Math.max(1, Math.ceil(image.height / blockSize)),
+        };
+    }
+    if (!blockSize || typeof blockSize !== "object")
+        throw new TypeError("blockSize must be a positive number or size");
+    assertDimension(blockSize.width, "blockSize.width");
+    assertDimension(blockSize.height, "blockSize.height");
+    return {
+        width: Math.max(1, Math.ceil(image.width / blockSize.width)),
+        height: Math.max(1, Math.ceil(image.height / blockSize.height)),
+    };
+}
+function resolveTargetSize(image, options) {
+    const hasTargetFields = options.targetWidth !== undefined || options.targetHeight !== undefined;
+    const hasTargetObject = options.targetSize !== undefined;
+    if (hasTargetFields && hasTargetObject)
+        throw new RangeError("Use a target size object or targetWidth/targetHeight, not both");
+    if ((options.targetWidth !== undefined || options.targetHeight !== undefined) &&
+        options.blockSize !== undefined) {
+        throw new RangeError("Use target dimensions or blockSize, not both");
+    }
+    if (options.targetSize && options.blockSize !== undefined) {
+        throw new RangeError("Use target dimensions or blockSize, not both");
+    }
+    if (options.blockSize !== undefined)
+        return sizeFromBlock(options.blockSize, image);
+    const targetObject = options.targetSize;
+    const targetWidth = targetObject?.width ?? options.targetWidth;
+    const targetHeight = targetObject?.height ?? options.targetHeight;
+    if (targetWidth === undefined && targetHeight === undefined)
+        return { width: image.width, height: image.height };
+    if (targetWidth !== undefined)
+        assertDimension(targetWidth, "targetWidth");
+    if (targetHeight !== undefined)
+        assertDimension(targetHeight, "targetHeight");
+    if (targetWidth === undefined) {
+        return {
+            width: Math.max(1, Math.round((image.width * targetHeight) / image.height)),
+            height: targetHeight,
+        };
+    }
+    if (targetHeight === undefined) {
+        return {
+            width: targetWidth,
+            height: Math.max(1, Math.round((image.height * targetWidth) / image.width)),
+        };
+    }
+    return { width: targetWidth, height: targetHeight };
+}
+function validateMethod(value) {
+    const method = value ?? PixelationMethod.Nearest;
+    if (!Object.values(PixelationMethod).includes(method))
+        throw new RangeError("Unknown pixelation method.");
+    return method;
+}
+/**
+ * Pixelate an RGBA buffer without touching the source. Nearest mode follows
+ * nearest-neighbor `floor(dst * src / dst)` mapping. Box mode averages the
+ * source area covered by each destination pixel. Local dominant and structural
+ * sampling preserve contrasting regions; grid recovery restores one RGBA pixel
+ * per detected cell. Limiting colours keeps each pixel's own alpha.
+ */
+export function pixelateImage(image, options = {}) {
+    assertPixelBuffer(image);
+    const method = validateMethod(options.method);
+    const sampled = sampleImage(image, options, method);
+    const smoothed = options.removeNoise ? smoothPixelation(sampled) : sampled;
+    // Limit colors: Lab k-means that keeps rare colours, or snapping to a loaded palette.
+    let result = options.paletteSnap ? snapPalette(smoothed, options.paletteSnap) : smoothed;
+    if (options.preserveDimensions &&
+        (result.width !== image.width || result.height !== image.height)) {
+        result = resizeNearest(result, image.width, image.height);
+    }
+    return result;
+}
+async function sampleImageAsync(image, options, method) {
+    const wantsGrid = options.mode === PixelationMode.RecoverGrid ||
+        (options.mode === undefined && options.algorithm !== undefined);
+    const grid = options.grid ??
+        (wantsGrid
+            ? await detectWithAlgorithmAsync(image, options.algorithm ?? PixelationAlgorithm.Auto)
+            : undefined);
+    const mode = options.mode ??
+        (grid && (!("reliable" in grid) || grid.reliable)
+            ? PixelationMode.RecoverGrid
+            : PixelationMode.Convert);
+    if (mode !== PixelationMode.Convert && mode !== PixelationMode.RecoverGrid)
+        throw new RangeError("Unknown pixelation mode.");
+    const prepass = options.prepass ?? OutlinePrepass.None;
+    const guide = prepass === OutlinePrepass.PixeloeLines ? (options.lineGuide ?? DEFAULT_LINE_GUIDE) : undefined;
+    if (mode === PixelationMode.RecoverGrid) {
+        const found = grid ??
+            (await detectWithAlgorithmAsync(image, options.algorithm ?? PixelationAlgorithm.Auto));
+        if ("reliable" in found && !found.reliable)
+            throw new Error("No consistent pixel grid was detected. Turn off Automatic grid and choose cell sizes.");
+        const cell = (found.cellWidth + found.cellHeight) / 2;
+        const analysis = found;
+        const upright = prepareGridSampling(image, analysis);
+        const gridForRecover = { ...analysis, rotation: undefined, sampling: undefined };
+        if (runsStockPixeloe({ ...options, mode }, found))
+            return runPixeloe(upright, { width: found.width, height: found.height }, guide);
+        return recoverWithGrid(applyOutlinePrepass(upright, cell, prepass, options.lineGuide), gridForRecover, options.colorPicker);
+    }
+    // Convert path is sync — reuse sampleImage body for non-recover.
+    return sampleImage(image, { ...options, grid: undefined, mode: PixelationMode.Convert }, method);
+}
+/**
+ * Async pixelate for product Auto path (import-worker). Same output as pixelateImage;
+ * Auto detect overlaps WASM AC+RL with proposers via Promise join (no COOP/COEP).
+ */
+export async function pixelateImageAsync(image, options = {}) {
+    assertPixelBuffer(image);
+    const method = validateMethod(options.method);
+    const sampled = await sampleImageAsync(image, options, method);
+    const smoothed = options.removeNoise ? smoothPixelation(sampled) : sampled;
+    let result = options.paletteSnap ? snapPalette(smoothed, options.paletteSnap) : smoothed;
+    if (options.preserveDimensions &&
+        (result.width !== image.width || result.height !== image.height)) {
+        result = resizeNearest(result, image.width, image.height);
+    }
+    return result;
+}

package/dist/pixelation-algorithm-registry.d.ts

@@ -0,0 +1,34 @@
+import type { PixelBuffer } from "./base.ts";
+import { CellColorPicker, PixelationAlgorithm, type PixelGridAnalysis, type PixelGridGeometry, type PixelationSize } from "./types.ts";
+export interface PixelationAlgorithmEntry {
+    /** i18n key of the label shown in the import dialog and preferences. */
+    readonly label: string;
+    /**
+     * Whether "Find pixels by" offers this entry; the plain resize is only Auto's fallback, and the
+     * single proposers are Fixed grid's sources (see getGridSources).
+     */
+    readonly listed: boolean;
+    /**
+     * Sync detect for most algorithms. Auto also exposes detectAsync for product overlap
+     * (browser nested Worker join without COOP/COEP).
+     */
+    detect(image: PixelBuffer, size?: PixelationSize): PixelGridAnalysis;
+    /** Optional async detect (Auto): awaitable WASM||proposers overlap. */
+    detectAsync?(image: PixelBuffer, size?: PixelationSize): Promise<PixelGridAnalysis>;
+    /** One output pixel per grid cell. */
+    run(image: PixelBuffer, grid: PixelGridGeometry, picker: CellColorPicker): PixelBuffer;
+}
+export declare function getAlgorithmEntry(algorithm: PixelationAlgorithm): PixelationAlgorithmEntry;
+export declare function getAllAlgorithms(): readonly PixelationAlgorithm[];
+/** Entries the import dialog offers, in registry order. */
+export declare function getListedAlgorithms(): readonly PixelationAlgorithm[];
+export declare function getGridSources(): readonly PixelationAlgorithm[];
+/** The "Find pixels by" entry an algorithm belongs to: a grid source is a kind of Fixed grid. */
+export declare function pixelationMethodOf(algorithm: PixelationAlgorithm): PixelationAlgorithm;
+export declare function detectWithAlgorithm(image: PixelBuffer, algorithm?: PixelationAlgorithm, size?: PixelationSize): PixelGridAnalysis;
+/**
+ * Async detect for product Auto path: uses detectAsync when present (WASM||proposers
+ * overlap via nested Worker Promise join). Other algorithms resolve sync detect.
+ */
+export declare function detectWithAlgorithmAsync(image: PixelBuffer, algorithm?: PixelationAlgorithm, size?: PixelationSize): Promise<PixelGridAnalysis>;
+export declare function recoverWithGrid(image: PixelBuffer, grid: PixelGridGeometry, picker?: CellColorPicker): PixelBuffer;