@pixagram/renderart 0.4.1 → 0.4.5

package/README.md

@@ -4,15 +4,9 @@ High-performance pixel art rendering engines with GPU (WebGL2) and CPU (WASM) su
 
 ## Features
 
-- **CRT Effect** (2-32x) - Classic CRT display simulation with barrel distortion, scanlines, and shadow mask
-- **HEX Upscaling** (2-32x) - Transform pixel art into hexagonal grid representations
-- **XBRZ Scaling** (2-6x) - Edge-preserving pixel art scaling algorithm
-
-All engines support:
-- ⚡ **GPU acceleration** via WebGL2 (CRT, HEX)
-- 🦀 **CPU fallback** via Rust/WASM (all engines)
-- 🎨 **Customizable presets** and fine-grained options
-- 🔄 **Auto-initialization** - WASM loads automatically on first use
+- **CRT Effect** - Classic CRT display simulation
+- **HEX Upscaling** - Hexagonal grid transformation  
+- **XBRZ Scaling** - Edge-preserving pixel art scaling
 
 ## Installation
 
@@ -20,57 +14,33 @@ All engines support:
 npm install @pixagram/renderart
 ```
 
-## ⚠️ Building from Source (Required)
-
-The package includes placeholder WASM. You **must** build the actual WASM module:
-
-```bash
-# Prerequisites: Rust + wasm-pack
-# Install wasm-pack: https://rustwasm.github.io/wasm-pack/installer/
-
-cd node_modules/@pixagram/renderart
-npm run build:wasm
-```
-
-Or build everything:
-```bash
-npm run build
-```
-
 ## Quick Start
 
+### GPU Only (Simplest)
+
 ```typescript
 import { RenderArt } from '@pixagram/renderart';
 
-// Create renderer (auto-initializes WASM)
-const renderer = await RenderArt.create();
-
-// Get your image data
-const imageData = ctx.getImageData(0, 0, canvas.width, canvas.height);
-
-// Apply CRT effect
-const crtResult = await renderer.crt.render(imageData, { scale: 3 });
-
-// Apply HEX effect
-const hexResult = await renderer.hex.render(imageData, { scale: 16 });
-
-// Apply XBRZ scaling
-const xbrzResult = await renderer.xbrz.render(imageData, { scale: 4 });
-
-// Use the result
-ctx.putImageData(new ImageData(crtResult.data, crtResult.width, crtResult.height), 0, 0);
+const renderer = RenderArt.createGpuOnly();
+const result = renderer.crt.renderSync(imageData, { scale: 3 });
 ```
 
-### GPU-Only Mode (Sync, No WASM)
+### With WASM/CPU Support
 
 ```typescript
-import { RenderArt } from '@pixagram/renderart';
+// 1. Import WASM module
+import init, * as wasm from '@pixagram/renderart/wasm';
 
-// Create GPU-only renderer (no WASM loading)
-const renderer = RenderArt.createGpuOnly();
+// 2. Import renderart
+import { initWasm, RenderArt } from '@pixagram/renderart';
 
-// Synchronous rendering
-const result = renderer.crt.renderSync(imageData, { scale: 3 });
+// 3. Initialize WASM
+await init();
+initWasm(wasm);
+
+// 4. Use renderers
+const renderer = RenderArt.create();
+const result = renderer.crt.render(imageData, { scale: 3 });
 ```
 
 ### Direct Renderer Usage
@@ -78,144 +48,68 @@ const result = renderer.crt.renderSync(imageData, { scale: 3 });
 ```typescript
 import { CrtGpuRenderer } from '@pixagram/renderart';
 
-// Use GPU renderer directly (no WASM needed)
 const crt = CrtGpuRenderer.create();
 const result = crt.render(imageData, { scale: 3 });
 crt.dispose();
 ```
 
-## Webpack Configuration
-
-For webpack 5, add to your webpack.config.js:
-
-```javascript
-module.exports = {
-  experiments: {
-    asyncWebAssembly: true,
-  },
-  module: {
-    rules: [
-      {
-        test: /\.wasm$/,
-        type: 'webassembly/async',
-      },
-    ],
-  },
-};
-```
-
-## API Reference
-
-### RenderArt (Unified API)
-
-```typescript
-// With CPU fallback (auto-loads WASM)
-const renderer = await RenderArt.create();
-
-// GPU-only mode
-const renderer = RenderArt.createGpuOnly();
-
-// Access capabilities
-console.log(renderer.capabilities);
-// { gpu: true, cpu: true, maxTextureSize: 16384, recommendedBackend: 'gpu' }
-
-// Cleanup
-renderer.dispose();
-```
+## API
 
-### CRT Engine
+### CRT Options
 
 ```typescript
-// Async with auto backend selection
-const result = await renderer.crt.render(imageData, {
-  scale: 3,              // 2-32 (default: 3)
+{
+  scale: 3,              // 2-32
   warpX: 0.015,          // Horizontal curvature
-  warpY: 0.02,           // Vertical curvature
-  scanHardness: -4.0,    // Scanline sharpness
-  scanOpacity: 0.5,      // Scanline intensity
-  maskOpacity: 0.3,      // Shadow mask intensity
+  warpY: 0.02,           // Vertical curvature  
+  scanHardness: -4.0,
+  scanOpacity: 0.5,
+  maskOpacity: 0.3,
   enableWarp: true,
   enableScanlines: true,
   enableMask: true,
-  backend: 'auto',       // 'gpu', 'cpu', or 'auto'
-});
-
-// With preset
-const result = await renderer.crt.render(imageData, 'authentic');
-// Presets: 'default', 'authentic', 'subtle', 'flat'
-
-// Sync GPU-only
-const result = renderer.crt.renderSync(imageData, { scale: 3 });
+}
 ```
 
-### HEX Engine
+### HEX Options
 
 ```typescript
-const result = await renderer.hex.render(imageData, {
-  scale: 16,                    // 2-32 (default: 16)
-  orientation: 'flat-top',      // 'flat-top' or 'pointy-top'
-  drawBorders: true,
+{
+  scale: 16,                    // 2-32
+  orientation: 'flat-top',      // or 'pointy-top'
+  drawBorders: false,
   borderColor: '#282828',
   borderThickness: 1,
-  backgroundColor: 'transparent',
-});
-
-// Presets: 'default', 'bordered', 'pointy'
-const result = await renderer.hex.render(imageData, 'bordered');
-
-// Get output dimensions
-const dims = renderer.hex.getDimensions(64, 64, { scale: 16 });
+}
 ```
 
-### XBRZ Engine (CPU Only)
+### XBRZ Options (CPU only)
 
 ```typescript
-const result = await renderer.xbrz.render(imageData, {
-  scale: 4,                          // 2-6 (default: 2)
+{
+  scale: 4,                     // 2-6
   luminanceWeight: 1.0,
   equalColorTolerance: 30,
-  dominantDirectionThreshold: 4.4,
-  steepDirectionThreshold: 2.2,
-});
-
-// Presets: 'default', 'sharp', 'smooth'
-const result = await renderer.xbrz.render(imageData, 'sharp');
+}
 ```
 
-## Backend Support
-
-| Engine | GPU (WebGL2) | CPU (WASM) |
-|--------|--------------|------------|
-| CRT    | ✅ Primary   | ✅ Fallback |
-| HEX    | ✅ Primary   | ✅ Fallback |
-| XBRZ   | ❌ N/A       | ✅ Only     |
-
-## Browser Support
+## Webpack Configuration
 
-- Chrome 79+
-- Firefox 75+
-- Safari 15+
-- Edge 79+
+```javascript
+module.exports = {
+  experiments: {
+    asyncWebAssembly: true,
+  },
+};
+```
 
-## Development
+## Building from Source
 
 ```bash
-# Clone and install
-git clone https://github.com/pixagram/renderart.git
-cd renderart
-npm install
-
-# Build WASM (requires Rust + wasm-pack)
-npm run build:wasm
-
-# Build TypeScript
-npm run build:ts
-
-# Full build
-npm run build
-
-# Run tests
-npm test
+# Prerequisites: Rust + wasm-pack
+npm run build:wasm  # Build WASM
+npm run build:ts    # Build TypeScript
+npm run build       # Build all
 ```
 
 ## License

package/dist/index.d.mts

@@ -190,68 +190,51 @@ declare const HEX_PRESETS: Record<string, Partial<HexOptions>>;
 /**
  * WASM Module Loader
  *
- * Handles loading and initialization of the Rust WASM module.
- * Auto-initializes on first use.
+ * Simple manual initialization pattern.
+ * User must call initWasm() with the WASM module before using CPU renderers.
  */
 
 /**
- * Initialize WASM module (auto-called on first use)
- * Can be called manually to pre-load WASM.
+ * Initialize WASM module.
  *
- * @param wasmUrl - Optional URL to the .wasm file.
+ * @example
+ * ```typescript
+ * import init, * as wasmModule from '@pixagram/renderart/dist/renderart_wasm_bg.js';
+ * import { initWasm } from '@pixagram/renderart';
+ *
+ * await init();
+ * initWasm(wasmModule);
+ * ```
  */
-declare function initWasm(wasmUrl?: string): Promise<void>;
+declare function initWasm(wasmModule: any): void;
 /** Check if WASM is loaded */
 declare function isWasmLoaded(): boolean;
-/** Check if WASM loading failed */
-declare function hasWasmError(): boolean;
-/** Get WASM loading error if any */
-declare function getWasmError(): Error | null;
-/** CRT CPU Renderer using WASM (auto-initializes) */
+/** CRT CPU Renderer using WASM */
 declare class CrtCpuRenderer {
-    private initialized;
-    /** Create and initialize renderer */
-    static create(): Promise<CrtCpuRenderer>;
-    /** Initialize (loads WASM if needed) */
-    init(): Promise<void>;
+    /** Create renderer (WASM must be initialized first) */
+    static create(): CrtCpuRenderer;
     /** Check if renderer is ready */
     isReady(): boolean;
     /** Render CRT effect */
     render(input: ImageInput | ImageData, options?: CrtOptions): ImageOutput;
-    /** Dispose resources */
     dispose(): void;
 }
-/** HEX CPU Renderer using WASM (auto-initializes) */
+/** HEX CPU Renderer using WASM */
 declare class HexCpuRenderer {
-    private initialized;
-    /** Create and initialize renderer */
-    static create(): Promise<HexCpuRenderer>;
-    /** Initialize (loads WASM if needed) */
-    init(): Promise<void>;
-    /** Check if renderer is ready */
+    static create(): HexCpuRenderer;
     isReady(): boolean;
-    /** Render hexagonal effect */
     render(input: ImageInput | ImageData, options?: HexOptions): ImageOutput;
-    /** Get output dimensions */
     getDimensions(srcWidth: number, srcHeight: number, scale: number, orientation?: HexOrientation): {
         width: number;
         height: number;
     };
-    /** Dispose resources */
     dispose(): void;
 }
-/** XBRZ CPU Renderer using WASM (auto-initializes) */
+/** XBRZ CPU Renderer using WASM */
 declare class XbrzCpuRenderer {
-    private initialized;
-    /** Create and initialize renderer */
-    static create(): Promise<XbrzCpuRenderer>;
-    /** Initialize (loads WASM if needed) */
-    init(): Promise<void>;
-    /** Check if renderer is ready */
+    static create(): XbrzCpuRenderer;
     isReady(): boolean;
-    /** Render xBRZ scaling */
     render(input: ImageInput | ImageData, options?: XbrzOptions): ImageOutput;
-    /** Dispose resources */
     dispose(): void;
 }
 /** XBRZ presets */
@@ -260,7 +243,7 @@ declare const XBRZ_PRESETS: Record<string, Partial<XbrzOptions>>;
 /**
  * RenderArt - Unified Pixel Art Rendering Engine
  *
- * GPU renderers work standalone. CPU renderers auto-initialize WASM.
+ * GPU renderers work standalone. CPU renderers require WASM initialization.
  */
 
 /** CRT rendering engine */
@@ -271,10 +254,9 @@ declare class CrtEngine {
     constructor(gpuAvailable: boolean);
     private ensureGpu;
     private ensureCpu;
-    /** Render with automatic backend selection */
-    render(input: ImageInput | ImageData, options?: CrtOptions): Promise<ImageOutput>;
-    render(input: ImageInput | ImageData, preset: CrtPreset, overrides?: Partial<CrtOptions>): Promise<ImageOutput>;
-    /** Render synchronously (GPU only) */
+    /** Render with options or preset */
+    render(input: ImageInput | ImageData, optionsOrPreset?: CrtOptions | CrtPreset): ImageOutput;
+    /** Synchronous GPU-only render */
     renderSync(input: ImageInput | ImageData, options?: CrtOptions): ImageOutput;
     dispose(): void;
 }
@@ -286,8 +268,7 @@ declare class HexEngine {
     constructor(gpuAvailable: boolean);
     private ensureGpu;
     private ensureCpu;
-    render(input: ImageInput | ImageData, options?: HexOptions): Promise<ImageOutput>;
-    render(input: ImageInput | ImageData, preset: HexPreset, overrides?: Partial<HexOptions>): Promise<ImageOutput>;
+    render(input: ImageInput | ImageData, optionsOrPreset?: HexOptions | HexPreset): ImageOutput;
     renderSync(input: ImageInput | ImageData, options?: HexOptions): ImageOutput;
     getDimensions(srcWidth: number, srcHeight: number, options?: HexOptions): {
         width: number;
@@ -295,33 +276,30 @@ declare class HexEngine {
     };
     dispose(): void;
 }
-/** XBRZ rendering engine (CPU only) */
+/** XBRZ rendering engine (CPU/WASM only) */
 declare class XbrzEngine {
     private cpuRenderer;
     private ensureCpu;
-    render(input: ImageInput | ImageData, options?: XbrzOptions): Promise<ImageOutput>;
-    render(input: ImageInput | ImageData, preset: XbrzPreset, overrides?: Partial<XbrzOptions>): Promise<ImageOutput>;
-    getDimensions(srcWidth: number, srcHeight: number, scale?: number): {
-        width: number;
-        height: number;
-    };
+    render(input: ImageInput | ImageData, optionsOrPreset?: XbrzOptions | XbrzPreset): ImageOutput;
     dispose(): void;
 }
-/** RenderArt - Unified Pixel Art Rendering Engine */
+/** Main RenderArt instance */
 declare class RenderArt {
     readonly crt: CrtEngine;
     readonly hex: HexEngine;
     readonly xbrz: XbrzEngine;
-    private _capabilities;
+    readonly capabilities: RendererCapabilities;
     private constructor();
-    /** Create RenderArt instance */
+    /**
+     * Create RenderArt instance.
+     * For CPU/WASM support, call initWasm() first.
+     */
     static create(): RenderArt;
-    /** Create GPU-only instance */
+    /**
+     * Create GPU-only RenderArt instance (no WASM needed).
+     */
     static createGpuOnly(): RenderArt;
-    /** Pre-initialize WASM for faster first CPU render */
-    preloadWasm(wasmUrl?: string): Promise<void>;
-    get capabilities(): RendererCapabilities;
     dispose(): void;
 }
 
-export { type Backend, CRT_PRESETS, CrtCpuRenderer, CrtEngine, CrtGpuRenderer, type CrtOptions, type CrtPreset, HEX_PRESETS, HexCpuRenderer, HexEngine, HexGpuRenderer, type HexOptions, type HexOrientation, type HexPreset, type ImageInput, type ImageOutput, type PixelData, RenderArt, type RenderStats, type Renderer, type RendererCapabilities, XBRZ_PRESETS, XbrzCpuRenderer, XbrzEngine, type XbrzOptions, type XbrzPreset, getWasmError, hasWasmError, hexGetDimensions, initWasm, isWasmLoaded };
+export { type Backend, CRT_PRESETS, CrtCpuRenderer, CrtEngine, CrtGpuRenderer, type CrtOptions, type CrtPreset, HEX_PRESETS, HexCpuRenderer, HexEngine, HexGpuRenderer, type HexOptions, type HexOrientation, type HexPreset, type ImageInput, type ImageOutput, type PixelData, RenderArt, type RenderStats, type Renderer, type RendererCapabilities, XBRZ_PRESETS, XbrzCpuRenderer, XbrzEngine, type XbrzOptions, type XbrzPreset, hexGetDimensions, initWasm, isWasmLoaded };

package/dist/index.d.ts

@@ -190,68 +190,51 @@ declare const HEX_PRESETS: Record<string, Partial<HexOptions>>;
 /**
  * WASM Module Loader
  *
- * Handles loading and initialization of the Rust WASM module.
- * Auto-initializes on first use.
+ * Simple manual initialization pattern.
+ * User must call initWasm() with the WASM module before using CPU renderers.
  */
 
 /**
- * Initialize WASM module (auto-called on first use)
- * Can be called manually to pre-load WASM.
+ * Initialize WASM module.
  *
- * @param wasmUrl - Optional URL to the .wasm file.
+ * @example
+ * ```typescript
+ * import init, * as wasmModule from '@pixagram/renderart/dist/renderart_wasm_bg.js';
+ * import { initWasm } from '@pixagram/renderart';
+ *
+ * await init();
+ * initWasm(wasmModule);
+ * ```
  */
-declare function initWasm(wasmUrl?: string): Promise<void>;
+declare function initWasm(wasmModule: any): void;
 /** Check if WASM is loaded */
 declare function isWasmLoaded(): boolean;
-/** Check if WASM loading failed */
-declare function hasWasmError(): boolean;
-/** Get WASM loading error if any */
-declare function getWasmError(): Error | null;
-/** CRT CPU Renderer using WASM (auto-initializes) */
+/** CRT CPU Renderer using WASM */
 declare class CrtCpuRenderer {
-    private initialized;
-    /** Create and initialize renderer */
-    static create(): Promise<CrtCpuRenderer>;
-    /** Initialize (loads WASM if needed) */
-    init(): Promise<void>;
+    /** Create renderer (WASM must be initialized first) */
+    static create(): CrtCpuRenderer;
     /** Check if renderer is ready */
     isReady(): boolean;
     /** Render CRT effect */
     render(input: ImageInput | ImageData, options?: CrtOptions): ImageOutput;
-    /** Dispose resources */
     dispose(): void;
 }
-/** HEX CPU Renderer using WASM (auto-initializes) */
+/** HEX CPU Renderer using WASM */
 declare class HexCpuRenderer {
-    private initialized;
-    /** Create and initialize renderer */
-    static create(): Promise<HexCpuRenderer>;
-    /** Initialize (loads WASM if needed) */
-    init(): Promise<void>;
-    /** Check if renderer is ready */
+    static create(): HexCpuRenderer;
     isReady(): boolean;
-    /** Render hexagonal effect */
     render(input: ImageInput | ImageData, options?: HexOptions): ImageOutput;
-    /** Get output dimensions */
     getDimensions(srcWidth: number, srcHeight: number, scale: number, orientation?: HexOrientation): {
         width: number;
         height: number;
     };
-    /** Dispose resources */
     dispose(): void;
 }
-/** XBRZ CPU Renderer using WASM (auto-initializes) */
+/** XBRZ CPU Renderer using WASM */
 declare class XbrzCpuRenderer {
-    private initialized;
-    /** Create and initialize renderer */
-    static create(): Promise<XbrzCpuRenderer>;
-    /** Initialize (loads WASM if needed) */
-    init(): Promise<void>;
-    /** Check if renderer is ready */
+    static create(): XbrzCpuRenderer;
     isReady(): boolean;
-    /** Render xBRZ scaling */
     render(input: ImageInput | ImageData, options?: XbrzOptions): ImageOutput;
-    /** Dispose resources */
     dispose(): void;
 }
 /** XBRZ presets */
@@ -260,7 +243,7 @@ declare const XBRZ_PRESETS: Record<string, Partial<XbrzOptions>>;
 /**
  * RenderArt - Unified Pixel Art Rendering Engine
  *
- * GPU renderers work standalone. CPU renderers auto-initialize WASM.
+ * GPU renderers work standalone. CPU renderers require WASM initialization.
  */
 
 /** CRT rendering engine */
@@ -271,10 +254,9 @@ declare class CrtEngine {
     constructor(gpuAvailable: boolean);
     private ensureGpu;
     private ensureCpu;
-    /** Render with automatic backend selection */
-    render(input: ImageInput | ImageData, options?: CrtOptions): Promise<ImageOutput>;
-    render(input: ImageInput | ImageData, preset: CrtPreset, overrides?: Partial<CrtOptions>): Promise<ImageOutput>;
-    /** Render synchronously (GPU only) */
+    /** Render with options or preset */
+    render(input: ImageInput | ImageData, optionsOrPreset?: CrtOptions | CrtPreset): ImageOutput;
+    /** Synchronous GPU-only render */
     renderSync(input: ImageInput | ImageData, options?: CrtOptions): ImageOutput;
     dispose(): void;
 }
@@ -286,8 +268,7 @@ declare class HexEngine {
     constructor(gpuAvailable: boolean);
     private ensureGpu;
     private ensureCpu;
-    render(input: ImageInput | ImageData, options?: HexOptions): Promise<ImageOutput>;
-    render(input: ImageInput | ImageData, preset: HexPreset, overrides?: Partial<HexOptions>): Promise<ImageOutput>;
+    render(input: ImageInput | ImageData, optionsOrPreset?: HexOptions | HexPreset): ImageOutput;
     renderSync(input: ImageInput | ImageData, options?: HexOptions): ImageOutput;
     getDimensions(srcWidth: number, srcHeight: number, options?: HexOptions): {
         width: number;
@@ -295,33 +276,30 @@ declare class HexEngine {
     };
     dispose(): void;
 }
-/** XBRZ rendering engine (CPU only) */
+/** XBRZ rendering engine (CPU/WASM only) */
 declare class XbrzEngine {
     private cpuRenderer;
     private ensureCpu;
-    render(input: ImageInput | ImageData, options?: XbrzOptions): Promise<ImageOutput>;
-    render(input: ImageInput | ImageData, preset: XbrzPreset, overrides?: Partial<XbrzOptions>): Promise<ImageOutput>;
-    getDimensions(srcWidth: number, srcHeight: number, scale?: number): {
-        width: number;
-        height: number;
-    };
+    render(input: ImageInput | ImageData, optionsOrPreset?: XbrzOptions | XbrzPreset): ImageOutput;
     dispose(): void;
 }
-/** RenderArt - Unified Pixel Art Rendering Engine */
+/** Main RenderArt instance */
 declare class RenderArt {
     readonly crt: CrtEngine;
     readonly hex: HexEngine;
     readonly xbrz: XbrzEngine;
-    private _capabilities;
+    readonly capabilities: RendererCapabilities;
     private constructor();
-    /** Create RenderArt instance */
+    /**
+     * Create RenderArt instance.
+     * For CPU/WASM support, call initWasm() first.
+     */
     static create(): RenderArt;
-    /** Create GPU-only instance */
+    /**
+     * Create GPU-only RenderArt instance (no WASM needed).
+     */
     static createGpuOnly(): RenderArt;
-    /** Pre-initialize WASM for faster first CPU render */
-    preloadWasm(wasmUrl?: string): Promise<void>;
-    get capabilities(): RendererCapabilities;
     dispose(): void;
 }
 
-export { type Backend, CRT_PRESETS, CrtCpuRenderer, CrtEngine, CrtGpuRenderer, type CrtOptions, type CrtPreset, HEX_PRESETS, HexCpuRenderer, HexEngine, HexGpuRenderer, type HexOptions, type HexOrientation, type HexPreset, type ImageInput, type ImageOutput, type PixelData, RenderArt, type RenderStats, type Renderer, type RendererCapabilities, XBRZ_PRESETS, XbrzCpuRenderer, XbrzEngine, type XbrzOptions, type XbrzPreset, getWasmError, hasWasmError, hexGetDimensions, initWasm, isWasmLoaded };
+export { type Backend, CRT_PRESETS, CrtCpuRenderer, CrtEngine, CrtGpuRenderer, type CrtOptions, type CrtPreset, HEX_PRESETS, HexCpuRenderer, HexEngine, HexGpuRenderer, type HexOptions, type HexOrientation, type HexPreset, type ImageInput, type ImageOutput, type PixelData, RenderArt, type RenderStats, type Renderer, type RendererCapabilities, XBRZ_PRESETS, XbrzCpuRenderer, XbrzEngine, type XbrzOptions, type XbrzPreset, hexGetDimensions, initWasm, isWasmLoaded };