smart-downscaler 0.2.1 → 0.3.1

package/README.md

@@ -4,9 +4,39 @@ A sophisticated Rust library for intelligent image downscaling with focus on pix
 
 **Available as both a native Rust library and a WebAssembly module for browser/Node.js usage.**
 
+## What's New in v0.2
+
+### 🎨 Oklab Color Space
+
+Version 0.2 introduces **Oklab color space** for all color operations, solving the common problem of desaturated, muddy colors:
+
+| Before (RGB Median Cut) | After (Oklab Median Cut) |
+|-------------------------|--------------------------|
+| Colors appear tanned/darkened | True color preservation |
+| Saturated colors become muddy | Vibrant colors maintained |
+| RGB averaging loses chroma | Perceptually uniform blending |
+
+### Palette Strategies
+
+Choose the best strategy for your use case:
+
+```javascript
+const config = new WasmDownscaleConfig();
+config.palette_strategy = 'saturation'; // For vibrant pixel art
+```
+
+| Strategy | Best For | Description |
+|----------|----------|-------------|
+| `oklab` | General use | Default, best overall quality |
+| `saturation` | Vibrant art | Preserves highly saturated colors |
+| `medoid` | Exact colors | Only uses colors from source image |
+| `kmeans` | Small palettes | K-Means++ clustering |
+| `legacy` | Comparison | Original RGB (not recommended) |
+
 ## Features
 
-- **Global Palette Extraction**: Median Cut + K-Means++ refinement in Lab color space for perceptually optimal palettes
+- **Oklab Color Space**: Modern perceptual color space with superior hue linearity
+- **Global Palette Extraction**: Median Cut + K-Means++ refinement
 - **Multiple Segmentation Methods**:
   - SLIC superpixels for fast, balanced regions
   - VTracer-style hierarchical clustering for content-aware boundaries
@@ -14,7 +44,6 @@ A sophisticated Rust library for intelligent image downscaling with focus on pix
 - **Edge-Aware Processing**: Sobel/Scharr edge detection to preserve boundaries
 - **Neighbor-Coherent Assignment**: Spatial coherence through neighbor and region voting
 - **Two-Pass Refinement**: Iterative optimization for smooth results
-- **Graph-Cut Optimization**: Optional MRF energy minimization for advanced refinement
 - **WebAssembly Support**: Run in browsers with full performance
 
 ## Installation
@@ -25,7 +54,7 @@ Add to your `Cargo.toml`:
 
 ```toml
 [dependencies]
-smart-downscaler = "0.1"
+smart-downscaler = "0.2"
 ```
 
 ### WebAssembly (npm)
@@ -49,11 +78,24 @@ Or use directly in browser:
 
 ```rust
 use smart_downscaler::prelude::*;
+use smart_downscaler::palette::PaletteStrategy;
 
 fn main() {
     let img = image::open("input.png").unwrap().to_rgb8();
+    
+    // Simple usage
     let result = downscale(&img, 64, 64, 16);
     result.save("output.png").unwrap();
+    
+    // Advanced: preserve vibrant colors
+    let config = DownscaleConfig {
+        palette_size: 24,
+        palette_strategy: PaletteStrategy::SaturationWeighted,
+        ..Default::default()
+    };
+    
+    let pixels: Vec<Rgb> = img.pixels().map(|&p| p.into()).collect();
+    let result = smart_downscale(&pixels, img.width() as usize, img.height() as usize, 64, 64, &config);
 }
 ```
 
@@ -62,111 +104,128 @@ fn main() {
 ```javascript
 import init, { WasmDownscaleConfig, downscale_rgba } from 'smart-downscaler';
 
-// Initialize WASM
 await init();
 
-// Get image data from canvas
 const ctx = canvas.getContext('2d');
 const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
 
-// Configure
-const config = new WasmDownscaleConfig();
+// Use vibrant preset for saturated colors
+const config = WasmDownscaleConfig.vibrant();
 config.palette_size = 16;
-config.neighbor_weight = 0.3;
-config.segmentation_method = 'hierarchy_fast';
 
-// Downscale
+// Or configure manually
+const config2 = new WasmDownscaleConfig();
+config2.palette_size = 16;
+config2.palette_strategy = 'saturation';
+config2.neighbor_weight = 0.3;
+
 const result = downscale_rgba(
   imageData.data,
   canvas.width,
   canvas.height,
-  64, 64,  // target size
+  64, 64,
   config
 );
 
-// Use result
 const outputData = new ImageData(result.data, result.width, result.height);
 outputCtx.putImageData(outputData, 0, 0);
-
-// Access palette
-console.log(`Used ${result.palette_size} colors`);
 ```
 
-### Using the JavaScript Wrapper
-
-For an even simpler API, use the included JavaScript wrapper:
+### Configuration Presets
 
 ```javascript
-import { init, downscale, extractPalette, getPresetPalette } from './smart-downscaler.js';
-
-await init();
+// Speed optimized
+const fast = WasmDownscaleConfig.fast();
 
-// Simple downscale
-const result = downscale(canvas, 64, 64, {
-  paletteSize: 16,
-  segmentation: 'hierarchy_fast'
-});
+// Best quality
+const quality = WasmDownscaleConfig.quality();
 
-// With preset palette (Game Boy, NES, PICO-8, CGA)
-const gbPalette = getPresetPalette('gameboy');
-const gbResult = downscaleWithPalette(canvas, 64, 64, gbPalette);
+// Preserve vibrant colors
+const vibrant = WasmDownscaleConfig.vibrant();
 
-// Extract palette only
-const palette = extractPalette(canvas, 16);
+// Use only exact source colors
+const exact = WasmDownscaleConfig.exact_colors();
 ```
 
-## Building WebAssembly
+## Why Oklab?
 
-Requirements: [wasm-pack](https://rustwasm.github.io/wasm-pack/)
+Traditional RGB-based palette extraction has fundamental problems:
 
-```bash
-# Install wasm-pack
-cargo install wasm-pack
+### The Problem: RGB Averaging Desaturates Colors
+
+```
+Red [255, 0, 0] + Cyan [0, 255, 255] 
+  RGB Average → Gray [127, 127, 127] ❌
+```
+
+When you average colors in RGB space, saturated colors get pulled toward gray. This is why downscaled images often look "washed out" or "tanned."
 
-# Build all targets
-./build-wasm.sh
+### The Solution: Oklab Color Space
 
-# Or manually:
-wasm-pack build --target web --features wasm --no-default-features --out-dir pkg/web
+Oklab is a **perceptually uniform** color space where:
+- Euclidean distance = perceived color difference
+- Averaging preserves hue and saturation
+- Interpolations look natural
+
+```
+Red (Oklab) + Cyan (Oklab)
+  Oklab Average → Preserves colorfulness ✓
 ```
 
-## WASM API Reference
+### Visual Comparison
 
-### Functions
+| Issue | RGB Median Cut | Oklab Median Cut |
+|-------|----------------|------------------|
+| Saturated colors | Become muddy | Stay vibrant |
+| Gradients | Shift in hue | Stay consistent |
+| Dark colors | Get darker | Accurate lightness |
+| Overall look | Desaturated | True to source |
 
-| Function | Description |
-|----------|-------------|
-| `downscale(data, w, h, tw, th, config?)` | Downscale RGBA image data |
-| `downscale_rgba(data, w, h, tw, th, config?)` | Same, for Uint8ClampedArray |
-| `downscale_simple(data, w, h, tw, th, colors)` | Simple API with color count |
-| `downscale_with_palette(data, w, h, tw, th, palette, config?)` | Use custom palette |
-| `extract_palette_from_image(data, w, h, colors, iters)` | Extract palette only |
-| `quantize_to_palette(data, w, h, palette)` | Quantize without resizing |
+## API Reference
 
 ### WasmDownscaleConfig
 
 ```javascript
 const config = new WasmDownscaleConfig();
-config.palette_size = 16;           // Output colors
-config.kmeans_iterations = 5;       // Palette refinement
-config.neighbor_weight = 0.3;       // Spatial coherence [0-1]
-config.region_weight = 0.2;         // Region coherence [0-1]
-config.two_pass_refinement = true;  // Enable refinement
-config.refinement_iterations = 3;   // Refinement passes
-config.edge_weight = 0.5;           // Edge detection weight
-config.segmentation_method = 'hierarchy_fast'; // 'none'|'slic'|'hierarchy'|'hierarchy_fast'
-
-// Presets
-const fast = WasmDownscaleConfig.fast();
-const quality = WasmDownscaleConfig.quality();
+
+// Palette settings
+config.palette_size = 16;           // Number of output colors
+config.palette_strategy = 'oklab';  // 'oklab', 'saturation', 'medoid', 'kmeans', 'legacy'
+config.kmeans_iterations = 5;       // Refinement iterations
+
+// Spatial coherence
+config.neighbor_weight = 0.3;       // [0-1] Prefer neighbor colors
+config.region_weight = 0.2;         // [0-1] Prefer region colors
+
+// Refinement
+config.two_pass_refinement = true;
+config.refinement_iterations = 3;
+
+// Edge detection
+config.edge_weight = 0.5;
+
+// Segmentation
+config.segmentation_method = 'hierarchy_fast'; // 'none', 'slic', 'hierarchy', 'hierarchy_fast'
 ```
 
+### Available Functions
+
+| Function | Description |
+|----------|-------------|
+| `downscale(data, w, h, tw, th, config?)` | Main downscale function |
+| `downscale_rgba(data, w, h, tw, th, config?)` | For Uint8ClampedArray input |
+| `downscale_simple(data, w, h, tw, th, colors)` | Simple API |
+| `downscale_with_palette(...)` | Use custom palette |
+| `extract_palette_from_image(data, w, h, colors, iters, strategy?)` | Extract palette only |
+| `quantize_to_palette(data, w, h, palette)` | Quantize without resizing |
+| `get_palette_strategies()` | List available strategies |
+
 ### WasmDownscaleResult
 
 ```javascript
 result.width          // Output width
-result.height         // Output height
-result.data           // Uint8ClampedArray (RGBA for ImageData)
+result.height         // Output height  
+result.data           // Uint8ClampedArray (RGBA)
 result.rgb_data()     // Uint8Array (RGB only)
 result.palette        // Uint8Array (RGB, 3 bytes per color)
 result.indices        // Uint8Array (palette index per pixel)
@@ -179,143 +238,129 @@ result.palette_size   // Number of colors
 # Basic usage
 smart-downscaler input.png output.png -w 64 -h 64
 
-# With custom palette size
-smart-downscaler input.png output.png -w 128 -h 128 -p 32
+# With saturation preservation
+smart-downscaler input.png output.png -w 64 -h 64 --palette-strategy saturation
 
-# Using scale factor
-smart-downscaler input.png output.png -s 0.125 -p 16
+# Using exact source colors only
+smart-downscaler input.png output.png -w 64 -h 64 --palette-strategy medoid -p 24
 
-# With SLIC segmentation
-smart-downscaler input.png output.png -w 64 -h 64 --segmentation slic
+# Full options
+smart-downscaler input.png output.png \
+  -w 128 -h 128 \
+  -p 32 \
+  --palette-strategy saturation \
+  --segmentation hierarchy-fast \
+  --neighbor-weight 0.4
 ```
 
 ## Algorithm Details
 
-### 1. Global Palette Extraction
+### 1. Palette Extraction (Oklab Median Cut)
 
-The traditional per-tile k-means approach causes color drift across the image. We instead:
+1. Convert all pixels to Oklab color space
+2. Build weighted color histogram
+3. Apply Median Cut to partition Oklab space
+4. For each bucket, compute centroid in Oklab
+5. Convert centroids back to RGB
+6. Refine with K-Means++ in Oklab space
 
-1. Build a weighted color histogram from all source pixels
-2. Apply Median Cut to partition the color space, finding initial centroids with good distribution
-3. Refine centroids using K-Means++ in CIE Lab space for perceptual accuracy
+### 2. Saturation-Weighted Strategy
 
-### 2. Region Pre-Segmentation
+When using `saturation` strategy:
+```
+effective_weight = pixel_count × (1 + chroma × 2)
+```
 
-Before downscaling, we identify coherent regions to preserve:
+This boosts the influence of highly saturated colors during Median Cut partitioning.
 
-**SLIC Superpixels:**
-- Iteratively clusters pixels by color and spatial proximity
-- Produces compact, regular regions
-- Fast and predictable
+### 3. Medoid Strategy
 
-**Hierarchical Clustering (VTracer-style):**
-- Bottom-up merging of similar adjacent pixels
-- Content-aware boundaries that follow natural edges
-- Configurable merge threshold and minimum region size
+Instead of computing centroids (averages), selects the actual image color closest to the centroid. Guarantees output palette contains only exact source colors.
 
-**Fast Hierarchical (Union-Find):**
-- O(α(n)) per operation using union by rank + path compression
-- Best for large images where full hierarchical is too slow
+### 4. Region Pre-Segmentation
 
-### 3. Edge-Aware Tile Computation
+Before downscaling, identifies coherent regions:
+- **SLIC**: Fast, regular superpixels
+- **Hierarchy**: Content-aware boundaries
+- **Hierarchy Fast**: O(α(n)) union-find
 
-Each output tile's color is computed as a weighted average of source pixels:
+### 5. Edge-Aware Tile Computation
 
 ```
-weight(pixel) = 1 / (1 + edge_strength * edge_weight)
+weight(pixel) = 1 / (1 + edge_strength × edge_weight)
 ```
 
-This reduces the influence of transitional edge pixels, avoiding muddy colors from averaging across boundaries.
-
-### 4. Neighbor-Coherent Assignment
+Reduces influence of transitional edge pixels.
 
-When assigning each tile to a palette color, we consider:
+### 6. Neighbor-Coherent Assignment
 
-- **Color distance** to the tile's weighted average (primary factor)
-- **Neighbor votes**: already-assigned neighbors bias toward their colors
-- **Region membership**: tiles in the same source region prefer consistent colors
-
-The scoring function:
 ```
-score(color) = distance(color, tile_avg) * (1 - neighbor_bias - region_bias)
+score(color) = oklab_distance(color, tile_avg) × (1 - neighbor_bias - region_bias)
 ```
 
-### 5. Two-Pass Refinement
-
-After initial assignment, we iteratively refine:
-
-1. For each pixel, gather all 8 neighbors
-2. Re-evaluate the best palette color considering neighbor votes
-3. Update if a better assignment is found
-4. Repeat until convergence or max iterations
-
-This smooths isolated outliers while preserving intentional edges.
-
-### 6. Graph-Cut Optimization (Optional)
-
-For highest quality, we offer MRF energy minimization:
-
-- **Data term**: color distance between tile and palette color
-- **Smoothness term**: penalty for different labels between neighbors
-- **Alpha-expansion**: iteratively try changing each pixel to each label
-
-## Comparison with Existing Tools
-
-| Feature | Smart Downscaler | Per-Tile K-Means | Simple Resize |
-|---------|------------------|------------------|---------------|
-| Global color consistency | ✓ | ✗ | ✗ |
-| Edge preservation | ✓ | Partial | ✗ |
-| Region awareness | ✓ | ✗ | ✗ |
-| Spatial coherence | ✓ | ✗ | ✗ |
-| Two-pass refinement | ✓ | ✗ | ✗ |
-| Custom palette support | ✓ | ✓ | ✗ |
-| Perceptual color space | ✓ (Lab) | Often RGB | N/A |
-
 ## Performance
 
-Typical performance on a modern CPU (single-threaded):
+Typical performance (single-threaded):
 
 | Image Size | Target Size | Palette | Time |
 |------------|-------------|---------|------|
 | 256×256 | 32×32 | 16 | ~50ms |
 | 512×512 | 64×64 | 32 | ~200ms |
 | 1024×1024 | 128×128 | 32 | ~800ms |
-| 2048×2048 | 256×256 | 64 | ~3s |
 
-Enable the `parallel` feature for multi-threaded processing on large images.
+Enable `parallel` feature for multi-threaded processing.
 
 ## Configuration Reference
 
-### DownscaleConfig
+### DownscaleConfig (Rust)
 
 | Field | Type | Default | Description |
 |-------|------|---------|-------------|
-| `palette_size` | usize | 16 | Number of colors in output palette |
-| `kmeans_iterations` | usize | 5 | K-Means refinement iterations |
-| `neighbor_weight` | f32 | 0.3 | Weight for neighbor coherence [0-1] |
-| `region_weight` | f32 | 0.2 | Weight for region coherence [0-1] |
-| `two_pass_refinement` | bool | true | Enable iterative refinement |
-| `refinement_iterations` | usize | 3 | Max refinement iterations |
-| `segmentation` | SegmentationMethod | Hierarchy | Pre-segmentation method |
-| `edge_weight` | f32 | 0.5 | Edge influence in tile averaging |
+| `palette_size` | usize | 16 | Output colors |
+| `palette_strategy` | PaletteStrategy | OklabMedianCut | Extraction method |
+| `kmeans_iterations` | usize | 5 | Refinement iterations |
+| `neighbor_weight` | f32 | 0.3 | Neighbor coherence |
+| `region_weight` | f32 | 0.2 | Region coherence |
+| `two_pass_refinement` | bool | true | Enable refinement |
+| `refinement_iterations` | usize | 3 | Max iterations |
+| `segmentation` | SegmentationMethod | Hierarchy | Pre-segmentation |
+| `edge_weight` | f32 | 0.5 | Edge influence |
+
+### PaletteStrategy
+
+| Value | Description |
+|-------|-------------|
+| `OklabMedianCut` | Default, best general quality |
+| `SaturationWeighted` | Preserves vibrant colors |
+| `Medoid` | Exact source colors only |
+| `KMeansPlusPlus` | K-Means++ clustering |
+| `LegacyRgb` | Original RGB (not recommended) |
+
+## Troubleshooting
+
+### Colors still look desaturated
+
+Try increasing palette size or using `saturation` strategy:
+```javascript
+config.palette_size = 24;  // Up from 16
+config.palette_strategy = 'saturation';
+```
 
-### HierarchyConfig
+### Want exact source colors
 
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `merge_threshold` | f32 | 15.0 | Max color distance for merging |
-| `min_region_size` | usize | 4 | Minimum pixels per region |
-| `max_regions` | usize | 0 | Max regions (0 = unlimited) |
-| `spatial_weight` | f32 | 0.1 | Spatial proximity influence |
+Use medoid strategy with no K-Means refinement:
+```javascript
+config.palette_strategy = 'medoid';
+config.kmeans_iterations = 0;
+```
 
-### SlicConfig
+### Output looks noisy
 
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `num_superpixels` | usize | 100 | Approximate superpixel count |
-| `compactness` | f32 | 10.0 | Shape regularity (higher = more compact) |
-| `max_iterations` | usize | 10 | SLIC iterations |
-| `convergence_threshold` | f32 | 1.0 | Early termination threshold |
+Increase neighbor weight for smoother results:
+```javascript
+config.neighbor_weight = 0.5;  // Up from 0.3
+config.two_pass_refinement = true;
+```
 
 ## License
 
@@ -323,8 +368,7 @@ MIT
 
 ## Credits
 
-Inspired by:
-- VTracer's hierarchical clustering approach
+- Oklab color space by Björn Ottosson
 - SLIC superpixel algorithm
 - K-Means++ initialization
-- CIE Lab perceptual color space
+- VTracer hierarchical clustering approach

package/package.json

@@ -5,11 +5,11 @@
     "Pixagram"
   ],
   "description": "Intelligent pixel art downscaler with region-aware color quantization",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/pixagram-blockchain/smart-downscaler"
+    "url": "https://github.com/pixagram/smart-downscaler"
   },
   "files": [
     "smart_downscaler_bg.wasm",
@@ -30,4 +30,4 @@
     "quantization",
     "wasm"
   ]
-}
+}

package/smart_downscaler.d.ts

@@ -1,6 +1,40 @@
 /* tslint:disable */
 /* eslint-disable */
 
+export class ColorAnalysisResult {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  /**
+   * Get color at index
+   */
+  get_color(index: number): ColorEntry | undefined;
+  /**
+   * Get all colors as a flat array: [r, g, b, count(4 bytes), percentage(4 bytes), ...] 
+   * Each color is 11 bytes
+   */
+  get_colors_flat(): Uint8Array;
+  /**
+   * Get colors as JSON-compatible array
+   */
+  to_json(): any;
+  readonly success: boolean;
+  readonly color_count: number;
+  readonly total_pixels: number;
+}
+
+export class ColorEntry {
+  private constructor();
+  free(): void;
+  [Symbol.dispose](): void;
+  readonly r: number;
+  readonly g: number;
+  readonly b: number;
+  readonly count: number;
+  readonly percentage: number;
+  readonly hex: string;
+}
+
 export class WasmDownscaleConfig {
   free(): void;
   [Symbol.dispose](): void;
@@ -16,6 +50,14 @@ export class WasmDownscaleConfig {
    * Create configuration optimized for quality
    */
   static quality(): WasmDownscaleConfig;
+  /**
+   * Create configuration optimized for vibrant colors
+   */
+  static vibrant(): WasmDownscaleConfig;
+  /**
+   * Create configuration that uses only exact image colors (medoid)
+   */
+  static exact_colors(): WasmDownscaleConfig;
   /**
    * Number of colors in the output palette (default: 16)
    */
@@ -64,6 +106,10 @@ export class WasmDownscaleConfig {
    * Get the segmentation method
    */
   segmentation_method: string;
+  /**
+   * Get the palette extraction strategy
+   */
+  palette_strategy: string;
 }
 
 export class WasmDownscaleResult {
@@ -105,15 +151,23 @@ export class WasmDownscaleResult {
 }
 
 /**
- * Highly optimized color analysis using a custom linear-probing hash table.
- * 
- * OPTIMIZATIONS:
- * 1. Casts u8 slice to u32 slice (Zero Copy, 4x read speed)
- * 2. Uses Power-of-Two capacity for bitwise masking (vs modulo)
- * 3. FxHash-style integer mixer
- * 4. Linear probing with localized memory access
+ * Analyze colors in an image
+ *
+ * # Arguments
+ * * `image_data` - RGBA pixel data
+ * * `max_colors` - Maximum number of unique colors to track (stops if exceeded)
+ * * `sort_method` - Sorting method: "frequency", "morton", or "hilbert"
+ *
+ * # Returns
+ * ColorAnalysisResult with array of colors (r, g, b, count, percentage, hex)
+ * If unique colors exceed max_colors, returns early with success=false
  */
-export function analyze_colors(image_data: Uint8Array, max_colors: number, sort_method: string): any;
+export function analyze_colors(image_data: Uint8Array, max_colors: number, sort_method: string): ColorAnalysisResult;
+
+/**
+ * Compute perceptual color distance between two RGB colors
+ */
+export function color_distance(r1: number, g1: number, b1: number, r2: number, g2: number, b2: number): number;
 
 /**
  * Main downscaling function for WebAssembly
@@ -149,7 +203,22 @@ export function downscale_with_palette(image_data: Uint8Array, width: number, he
 /**
  * Extract a color palette from an image without downscaling
  */
-export function extract_palette_from_image(image_data: Uint8Array, _width: number, _height: number, num_colors: number, kmeans_iterations: number): Uint8Array;
+export function extract_palette_from_image(image_data: Uint8Array, _width: number, _height: number, num_colors: number, kmeans_iterations: number, strategy?: string | null): Uint8Array;
+
+/**
+ * Get chroma (saturation) of an RGB color
+ */
+export function get_chroma(r: number, g: number, b: number): number;
+
+/**
+ * Get lightness of an RGB color in Oklab space
+ */
+export function get_lightness(r: number, g: number, b: number): number;
+
+/**
+ * Get available palette strategies
+ */
+export function get_palette_strategies(): Array<any>;
 
 /**
  * Initialize panic hook for better error messages in browser console
@@ -161,11 +230,21 @@ export function init(): void;
  */
 export function log(message: string): void;
 
+/**
+ * Convert Oklab to RGB (utility function for JS)
+ */
+export function oklab_to_rgb(l: number, a: number, b: number): Uint8Array;
+
 /**
  * Quantize an image to a specific palette without resizing
  */
 export function quantize_to_palette(image_data: Uint8Array, width: number, height: number, palette_data: Uint8Array): WasmDownscaleResult;
 
+/**
+ * Convert RGB to Oklab (utility function for JS)
+ */
+export function rgb_to_oklab(r: number, g: number, b: number): Float32Array;
+
 /**
  * Get library version
  */

package/smart_downscaler_bg.js

@@ -3,6 +3,12 @@ export function __wbg_set_wasm(val) {
     wasm = val;
 }
 
+function addToExternrefTable0(obj) {
+    const idx = wasm.__externref_table_alloc();
+    wasm.__wbindgen_externrefs.set(idx, obj);
+    return idx;
+}
+
 function _assertClass(instance, klass) {
     if (!(instance instanceof klass)) {
         throw new Error(`expected instance of ${klass.name}`);
@@ -27,15 +33,17 @@ function getUint8ArrayMemory0() {
     return cachedUint8ArrayMemory0;
 }
 
-function isLikeNone(x) {
-    return x === undefined || x === null;
+function handleError(f, args) {
+    try {
+        return f.apply(this, args);
+    } catch (e) {
+        const idx = addToExternrefTable0(e);
+        wasm.__wbindgen_exn_store(idx);
+    }
 }
 
-function passArray8ToWasm0(arg, malloc) {
-    const ptr = malloc(arg.length * 1, 1) >>> 0;
-    getUint8ArrayMemory0().set(arg, ptr / 1);
-    WASM_VECTOR_LEN = arg.length;
-    return ptr;
+function isLikeNone(x) {
+    return x === undefined || x === null;
 }
 
 function passStringToWasm0(arg, malloc, realloc) {
@@ -110,6 +118,14 @@ if (!('encodeInto' in cachedTextEncoder)) {
 
 let WASM_VECTOR_LEN = 0;
 
+const ColorAnalysisResultFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_coloranalysisresult_free(ptr >>> 0, 1));
+
+const ColorEntryFinalization = (typeof FinalizationRegistry === 'undefined')
+    ? { register: () => {}, unregister: () => {} }
+    : new FinalizationRegistry(ptr => wasm.__wbg_colorentry_free(ptr >>> 0, 1));
+
 const WasmDownscaleConfigFinalization = (typeof FinalizationRegistry === 'undefined')
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_wasmdownscaleconfig_free(ptr >>> 0, 1));
@@ -118,6 +134,154 @@ const WasmDownscaleResultFinalization = (typeof FinalizationRegistry === 'undefi
     ? { register: () => {}, unregister: () => {} }
     : new FinalizationRegistry(ptr => wasm.__wbg_wasmdownscaleresult_free(ptr >>> 0, 1));
 
+/**
+ * Result of color analysis
+ */
+export class ColorAnalysisResult {
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(ColorAnalysisResult.prototype);
+        obj.__wbg_ptr = ptr;
+        ColorAnalysisResultFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        ColorAnalysisResultFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_coloranalysisresult_free(ptr, 0);
+    }
+    /**
+     * @returns {boolean}
+     */
+    get success() {
+        const ret = wasm.coloranalysisresult_success(this.__wbg_ptr);
+        return ret !== 0;
+    }
+    /**
+     * @returns {number}
+     */
+    get color_count() {
+        const ret = wasm.coloranalysisresult_color_count(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * @returns {number}
+     */
+    get total_pixels() {
+        const ret = wasm.coloranalysisresult_total_pixels(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * Get color at index
+     * @param {number} index
+     * @returns {ColorEntry | undefined}
+     */
+    get_color(index) {
+        const ret = wasm.coloranalysisresult_get_color(this.__wbg_ptr, index);
+        return ret === 0 ? undefined : ColorEntry.__wrap(ret);
+    }
+    /**
+     * Get all colors as a flat array: [r, g, b, count(4 bytes), percentage(4 bytes), ...]
+     * Each color is 11 bytes
+     * @returns {Uint8Array}
+     */
+    get_colors_flat() {
+        const ret = wasm.coloranalysisresult_get_colors_flat(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * Get colors as JSON-compatible array
+     * @returns {any}
+     */
+    to_json() {
+        const ret = wasm.coloranalysisresult_to_json(this.__wbg_ptr);
+        if (ret[2]) {
+            throw takeFromExternrefTable0(ret[1]);
+        }
+        return takeFromExternrefTable0(ret[0]);
+    }
+}
+if (Symbol.dispose) ColorAnalysisResult.prototype[Symbol.dispose] = ColorAnalysisResult.prototype.free;
+
+/**
+ * A single color entry with statistics
+ */
+export class ColorEntry {
+    static __wrap(ptr) {
+        ptr = ptr >>> 0;
+        const obj = Object.create(ColorEntry.prototype);
+        obj.__wbg_ptr = ptr;
+        ColorEntryFinalization.register(obj, obj.__wbg_ptr, obj);
+        return obj;
+    }
+    __destroy_into_raw() {
+        const ptr = this.__wbg_ptr;
+        this.__wbg_ptr = 0;
+        ColorEntryFinalization.unregister(this);
+        return ptr;
+    }
+    free() {
+        const ptr = this.__destroy_into_raw();
+        wasm.__wbg_colorentry_free(ptr, 0);
+    }
+    /**
+     * @returns {number}
+     */
+    get r() {
+        const ret = wasm.colorentry_r(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {number}
+     */
+    get g() {
+        const ret = wasm.colorentry_g(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {number}
+     */
+    get b() {
+        const ret = wasm.colorentry_b(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {number}
+     */
+    get count() {
+        const ret = wasm.colorentry_count(this.__wbg_ptr);
+        return ret >>> 0;
+    }
+    /**
+     * @returns {number}
+     */
+    get percentage() {
+        const ret = wasm.colorentry_percentage(this.__wbg_ptr);
+        return ret;
+    }
+    /**
+     * @returns {string}
+     */
+    get hex() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.colorentry_hex(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
+}
+if (Symbol.dispose) ColorEntry.prototype[Symbol.dispose] = ColorEntry.prototype.free;
+
 /**
  * Configuration options for the downscaler (JavaScript-compatible)
  */
@@ -338,6 +502,31 @@ export class WasmDownscaleConfig {
             wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
         }
     }
+    /**
+     * Set the palette extraction strategy
+     * @param {string} strategy
+     */
+    set palette_strategy(strategy) {
+        const ptr0 = passStringToWasm0(strategy, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+        const len0 = WASM_VECTOR_LEN;
+        wasm.wasmdownscaleconfig_set_palette_strategy(this.__wbg_ptr, ptr0, len0);
+    }
+    /**
+     * Get the palette extraction strategy
+     * @returns {string}
+     */
+    get palette_strategy() {
+        let deferred1_0;
+        let deferred1_1;
+        try {
+            const ret = wasm.wasmdownscaleconfig_palette_strategy(this.__wbg_ptr);
+            deferred1_0 = ret[0];
+            deferred1_1 = ret[1];
+            return getStringFromWasm0(ret[0], ret[1]);
+        } finally {
+            wasm.__wbindgen_free(deferred1_0, deferred1_1, 1);
+        }
+    }
     /**
      * Create configuration optimized for speed
      * @returns {WasmDownscaleConfig}
@@ -354,6 +543,22 @@ export class WasmDownscaleConfig {
         const ret = wasm.wasmdownscaleconfig_quality();
         return WasmDownscaleConfig.__wrap(ret);
     }
+    /**
+     * Create configuration optimized for vibrant colors
+     * @returns {WasmDownscaleConfig}
+     */
+    static vibrant() {
+        const ret = wasm.wasmdownscaleconfig_vibrant();
+        return WasmDownscaleConfig.__wrap(ret);
+    }
+    /**
+     * Create configuration that uses only exact image colors (medoid)
+     * @returns {WasmDownscaleConfig}
+     */
+    static exact_colors() {
+        const ret = wasm.wasmdownscaleconfig_exact_colors();
+        return WasmDownscaleConfig.__wrap(ret);
+    }
 }
 if (Symbol.dispose) WasmDownscaleConfig.prototype[Symbol.dispose] = WasmDownscaleConfig.prototype.free;
 
@@ -447,28 +652,44 @@ export class WasmDownscaleResult {
 if (Symbol.dispose) WasmDownscaleResult.prototype[Symbol.dispose] = WasmDownscaleResult.prototype.free;
 
 /**
- * Highly optimized color analysis using a custom linear-probing hash table.
+ * Analyze colors in an image
+ *
+ * # Arguments
+ * * `image_data` - RGBA pixel data
+ * * `max_colors` - Maximum number of unique colors to track (stops if exceeded)
+ * * `sort_method` - Sorting method: "frequency", "morton", or "hilbert"
  *
- * OPTIMIZATIONS:
- * 1. Casts u8 slice to u32 slice (Zero Copy, 4x read speed)
- * 2. Uses Power-of-Two capacity for bitwise masking (vs modulo)
- * 3. FxHash-style integer mixer
- * 4. Linear probing with localized memory access
+ * # Returns
+ * ColorAnalysisResult with array of colors (r, g, b, count, percentage, hex)
+ * If unique colors exceed max_colors, returns early with success=false
  * @param {Uint8Array} image_data
  * @param {number} max_colors
  * @param {string} sort_method
- * @returns {any}
+ * @returns {ColorAnalysisResult}
  */
 export function analyze_colors(image_data, max_colors, sort_method) {
-    const ptr0 = passArray8ToWasm0(image_data, wasm.__wbindgen_malloc);
+    const ptr0 = passStringToWasm0(sort_method, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
     const len0 = WASM_VECTOR_LEN;
-    const ptr1 = passStringToWasm0(sort_method, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
-    const len1 = WASM_VECTOR_LEN;
-    const ret = wasm.analyze_colors(ptr0, len0, max_colors, ptr1, len1);
+    const ret = wasm.analyze_colors(image_data, max_colors, ptr0, len0);
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
-    return takeFromExternrefTable0(ret[0]);
+    return ColorAnalysisResult.__wrap(ret[0]);
+}
+
+/**
+ * Compute perceptual color distance between two RGB colors
+ * @param {number} r1
+ * @param {number} g1
+ * @param {number} b1
+ * @param {number} r2
+ * @param {number} g2
+ * @param {number} b2
+ * @returns {number}
+ */
+export function color_distance(r1, g1, b1, r2, g2, b2) {
+    const ret = wasm.color_distance(r1, g1, b1, r2, g2, b2);
+    return ret;
 }
 
 /**
@@ -577,16 +798,52 @@ export function downscale_with_palette(image_data, width, height, target_width,
  * @param {number} _height
  * @param {number} num_colors
  * @param {number} kmeans_iterations
+ * @param {string | null} [strategy]
  * @returns {Uint8Array}
  */
-export function extract_palette_from_image(image_data, _width, _height, num_colors, kmeans_iterations) {
-    const ret = wasm.extract_palette_from_image(image_data, _width, _height, num_colors, kmeans_iterations);
+export function extract_palette_from_image(image_data, _width, _height, num_colors, kmeans_iterations, strategy) {
+    var ptr0 = isLikeNone(strategy) ? 0 : passStringToWasm0(strategy, wasm.__wbindgen_malloc, wasm.__wbindgen_realloc);
+    var len0 = WASM_VECTOR_LEN;
+    const ret = wasm.extract_palette_from_image(image_data, _width, _height, num_colors, kmeans_iterations, ptr0, len0);
     if (ret[2]) {
         throw takeFromExternrefTable0(ret[1]);
     }
     return takeFromExternrefTable0(ret[0]);
 }
 
+/**
+ * Get chroma (saturation) of an RGB color
+ * @param {number} r
+ * @param {number} g
+ * @param {number} b
+ * @returns {number}
+ */
+export function get_chroma(r, g, b) {
+    const ret = wasm.get_chroma(r, g, b);
+    return ret;
+}
+
+/**
+ * Get lightness of an RGB color in Oklab space
+ * @param {number} r
+ * @param {number} g
+ * @param {number} b
+ * @returns {number}
+ */
+export function get_lightness(r, g, b) {
+    const ret = wasm.get_lightness(r, g, b);
+    return ret;
+}
+
+/**
+ * Get available palette strategies
+ * @returns {Array<any>}
+ */
+export function get_palette_strategies() {
+    const ret = wasm.get_palette_strategies();
+    return ret;
+}
+
 /**
  * Initialize panic hook for better error messages in browser console
  */
@@ -604,6 +861,18 @@ export function log(message) {
     wasm.log(ptr0, len0);
 }
 
+/**
+ * Convert Oklab to RGB (utility function for JS)
+ * @param {number} l
+ * @param {number} a
+ * @param {number} b
+ * @returns {Uint8Array}
+ */
+export function oklab_to_rgb(l, a, b) {
+    const ret = wasm.oklab_to_rgb(l, a, b);
+    return ret;
+}
+
 /**
  * Quantize an image to a specific palette without resizing
  * @param {Uint8Array} image_data
@@ -620,6 +889,18 @@ export function quantize_to_palette(image_data, width, height, palette_data) {
     return WasmDownscaleResult.__wrap(ret[0]);
 }
 
+/**
+ * Convert RGB to Oklab (utility function for JS)
+ * @param {number} r
+ * @param {number} g
+ * @param {number} b
+ * @returns {Float32Array}
+ */
+export function rgb_to_oklab(r, g, b) {
+    const ret = wasm.rgb_to_oklab(r, g, b);
+    return ret;
+}
+
 /**
  * Get library version
  * @returns {string}
@@ -675,6 +956,11 @@ export function __wbg_new_from_slice_f9c22b9153b26992(arg0, arg1) {
     return ret;
 };
 
+export function __wbg_new_with_length_95ba657dfb7d3dfb(arg0) {
+    const ret = new Float32Array(arg0 >>> 0);
+    return ret;
+};
+
 export function __wbg_new_with_length_aa5eaf41d35235e5(arg0) {
     const ret = new Uint8Array(arg0 >>> 0);
     return ret;
@@ -684,11 +970,21 @@ export function __wbg_prototypesetcall_dfe9b766cdc1f1fd(arg0, arg1, arg2) {
     Uint8Array.prototype.set.call(getArrayU8FromWasm0(arg0, arg1), arg2);
 };
 
-export function __wbg_set_3f1d0b984ed272ed(arg0, arg1, arg2) {
-    arg0[arg1] = arg2;
+export function __wbg_push_7d9be8f38fc13975(arg0, arg1) {
+    const ret = arg0.push(arg1);
+    return ret;
+};
+
+export function __wbg_set_781438a03c0c3c81() { return handleError(function (arg0, arg1, arg2) {
+    const ret = Reflect.set(arg0, arg1, arg2);
+    return ret;
+}, arguments) };
+
+export function __wbg_set_index_04c4b93e64d08a52(arg0, arg1, arg2) {
+    arg0[arg1 >>> 0] = arg2;
 };
 
-export function __wbg_set_7df433eea03a5c14(arg0, arg1, arg2) {
+export function __wbg_set_index_165b46b0114d368c(arg0, arg1, arg2) {
     arg0[arg1 >>> 0] = arg2;
 };