stable-diffusion-cpp-node-api 0.9.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 node-stable-diffusion-cpp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,166 @@
+# node-stable-diffusion-cpp
+
+> **WARNING: This library was vibe coded.** The entire codebase — C++ bindings, JS wrappers, build
+> system, and documentation — was generated by an AI assistant in a single session. It compiles,
+> passes basic smoke tests, and the API surface matches the upstream C library. However, it has
+> **not** been battle-tested in production. Edge cases, memory leaks under unusual error paths, and
+> platform-specific build quirks may exist. Use at your own risk, report issues, and read the source
+> before shipping anything important.
+
+Native Node.js bindings for [stable-diffusion.cpp](https://github.com/leejet/stable-diffusion.cpp) — a pure C/C++ implementation of Stable Diffusion, SDXL, SD3, FLUX, Wan video, and more. Built on N-API for ABI stability across Node.js versions. All heavy operations (model loading, image/video generation, upscaling) run on background threads and return Promises.
+
+## Features
+
+- **Image generation** — txt2img, img2img, inpainting, ControlNet, PhotoMaker, LoRA
+- **Video generation** — Wan2.1/2.2 text-to-video and image-to-video
+- **Upscaling** — ESRGAN-based super resolution
+- **Model conversion** — safetensors/ckpt to GGUF quantized formats
+- **GPU auto-detection** — Metal (macOS), CUDA (Linux/Windows), Vulkan
+- **Async everything** — context creation, generation, upscaling all return Promises
+- **Callbacks** — log, progress, and preview callbacks bridged to the JS event loop
+- **Electron-ready** — N-API v8 targets Node.js 18+ / Electron 22+
+- **TypeScript** — full type declarations included
+
+## Requirements
+
+- Node.js >= 18
+- CMake >= 3.15
+- C++17 compiler (Xcode, GCC 9+, MSVC 2019+)
+- Platform SDK for GPU backend (Xcode for Metal, CUDA Toolkit for NVIDIA, Vulkan SDK)
+
+## Installation
+
+```bash
+git clone --recursive <your-repo-url>
+cd node-stable-diffusion-cpp
+npm install
+```
+
+The `npm install` step compiles the native module. On macOS it automatically enables Metal; on systems with CUDA or Vulkan SDKs installed, those backends are enabled too.
+
+### Manual build
+
+```bash
+npm run build          # Release build
+npm run build:debug    # Debug build
+npm run rebuild        # Clean + rebuild
+npm run clean          # Remove build artifacts
+```
+
+## Quick start
+
+```javascript
+const sd = require('node-stable-diffusion-cpp');
+const fs = require('fs');
+
+// Optional: log what the library is doing
+sd.setLogCallback(({ level, text }) => {
+    if (level >= 1) process.stderr.write(text);
+});
+
+// Optional: track generation progress
+sd.setProgressCallback(({ step, steps, time }) => {
+    process.stderr.write(`\rStep ${step}/${steps} (${time.toFixed(1)}s)`);
+});
+
+(async () => {
+    // Load a model (runs on background thread)
+    // Use modelPath for single-file models (ckpt, safetensors, full gguf).
+    // Use diffusionModelPath only for standalone diffusion-only component files.
+    const ctx = await sd.StableDiffusionContext.create({
+        modelPath: 'path/to/model.gguf',
+    });
+
+    // Generate an image
+    const images = await ctx.generateImage({
+        prompt: 'a photo of an astronaut riding a horse on mars',
+        width: 512,
+        height: 512,
+        sampleParams: {
+            sampleSteps: 20,
+            guidance: { txtCfg: 7.0 },
+        },
+    });
+
+    // Save raw RGB pixels (use stb_image or sharp to encode to PNG)
+    const img = images[0];
+    console.log(`\nGenerated ${img.width}x${img.height} image (${img.data.length} bytes)`);
+    fs.writeFileSync('output.raw', img.data);
+
+    ctx.close();
+})();
+```
+
+## Smoke test
+
+A ready-made script is included:
+
+```bash
+node smoke.js path/to/model.gguf
+```
+
+Edit the constants at the top of `smoke.js` to change prompt, dimensions, steps, etc.
+
+## API overview
+
+| Function / Class | Description |
+|---|---|
+| `StableDiffusionContext.create(opts)` | Load a model, returns `Promise<StableDiffusionContext>` |
+| `ctx.generateImage(opts)` | Text/image to image, returns `Promise<SdImage[]>` |
+| `ctx.generateVideo(opts)` | Text/image to video frames, returns `Promise<SdImage[]>` |
+| `ctx.getDefaultSampleMethod()` | Default sampler for loaded model |
+| `ctx.getDefaultScheduler(method?)` | Default scheduler for sampler |
+| `ctx.close()` | Free native resources |
+| `UpscalerContext.create(opts)` | Load ESRGAN model, returns `Promise<UpscalerContext>` |
+| `upscaler.upscale(image, factor?)` | Upscale an image, returns `Promise<SdImage>` |
+| `convert(opts)` | Convert model format, returns `Promise<boolean>` |
+| `preprocessCanny(image, opts?)` | Canny edge detection (sync, in-place) |
+| `setLogCallback(fn)` | Set/clear log callback |
+| `setProgressCallback(fn)` | Set/clear progress callback |
+| `setPreviewCallback(fn, opts?)` | Set/clear preview callback |
+| `getSystemInfo()` | Backend/hardware info string |
+| `getNumPhysicalCores()` | CPU core count |
+| `version()` / `commit()` | Library version and git commit |
+
+See [docs/API.md](docs/API.md) for the full API reference with all options, types, and examples.
+
+## Supported models
+
+Anything stable-diffusion.cpp supports:
+
+- Stable Diffusion 1.x, 2.x
+- SDXL, SDXL Turbo
+- SD3, SD3.5
+- FLUX.1 (dev, schnell)
+- Wan2.1, Wan2.2 (video)
+- Chroma, Qwen-Image
+- LoRA, ControlNet, PhotoMaker
+- GGUF quantized models (Q4_0, Q5_0, Q8_0, F16, etc.)
+
+## Image data format
+
+All images are plain objects with raw pixel data:
+
+```typescript
+interface SdImage {
+    width: number;    // pixels
+    height: number;   // pixels
+    channel: number;  // 3 for RGB
+    data: Buffer;     // raw RGB bytes, length = width * height * channel
+}
+```
+
+To save as PNG, use a library like [sharp](https://sharp.pixelplumbing.com/):
+
+```javascript
+const sharp = require('sharp');
+await sharp(img.data, { raw: { width: img.width, height: img.height, channels: img.channel } })
+    .png()
+    .toFile('output.png');
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+stable-diffusion.cpp is also MIT licensed. GGML is MIT licensed.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "stable-diffusion-cpp-node-api",
+  "version": "0.9.1",
+  "description": "Node.js N-API bindings for stable-diffusion.cpp — run Stable Diffusion, SDXL, SD3, FLUX, and Wan video models natively",
+  "main": "src/js/index.js",
+  "types": "src/js/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sir-ingvarr/node-stable-diffusion-cpp.git"
+  },
+  "license": "MIT",
+  "scripts": {
+    "preinstall": "test -d .git && git submodule update --init --recursive || true",
+    "build": "cmake-js compile --release",
+    "build:debug": "cmake-js compile --debug",
+    "rebuild": "cmake-js rebuild --release",
+    "clean": "cmake-js clean",
+    "test": "node test/basic.js",
+    "smoke": "node smoke.js"
+  },
+  "keywords": [
+    "stable-diffusion",
+    "sdxl",
+    "sd3",
+    "flux",
+    "wan",
+    "image-generation",
+    "video-generation",
+    "diffusion",
+    "ai",
+    "machine-learning",
+    "ggml",
+    "gguf",
+    "native",
+    "napi",
+    "electron"
+  ],
+  "files": [
+    "src/js/",
+    "LICENSE",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "cmake-js": "^8.0.0",
+    "node-addon-api": "^8.3.1"
+  },
+  "optionalDependencies": {
+    "@stable-diffusion-cpp-node-api/darwin-arm64": "0.9.1",
+    "@stable-diffusion-cpp-node-api/darwin-x64": "0.9.1",
+    "@stable-diffusion-cpp-node-api/linux-x64": "0.9.1",
+    "@stable-diffusion-cpp-node-api/win32-x64": "0.9.1"
+  }
+}

package/src/js/index.d.ts

@@ -0,0 +1,345 @@
+/// <reference types="node" />
+
+// --- Enum string literal types ---
+
+export type SampleMethod =
+    | 'euler'
+    | 'euler_a'
+    | 'heun'
+    | 'dpm2'
+    | 'dpm++2s_a'
+    | 'dpm++2m'
+    | 'dpm++2mv2'
+    | 'ipndm'
+    | 'ipndm_v'
+    | 'lcm'
+    | 'ddim_trailing'
+    | 'tcd'
+    | 'res_multistep'
+    | 'res_2s';
+
+export type Scheduler =
+    | 'discrete'
+    | 'karras'
+    | 'exponential'
+    | 'ays'
+    | 'gits'
+    | 'sgm_uniform'
+    | 'simple'
+    | 'smoothstep'
+    | 'kl_optimal'
+    | 'lcm'
+    | 'bong_tangent';
+
+export type SdType =
+    | 'f32'
+    | 'f16'
+    | 'q4_0'
+    | 'q4_1'
+    | 'q5_0'
+    | 'q5_1'
+    | 'q8_0'
+    | 'q8_1'
+    | 'q2_k'
+    | 'q3_k'
+    | 'q4_k'
+    | 'q5_k'
+    | 'q6_k'
+    | 'q8_k'
+    | 'iq2_xxs'
+    | 'iq2_xs'
+    | 'iq3_xxs'
+    | 'iq1_s'
+    | 'iq4_nl'
+    | 'iq3_s'
+    | 'iq2_s'
+    | 'iq4_xs'
+    | 'i8'
+    | 'i16'
+    | 'i32'
+    | 'i64'
+    | 'f64'
+    | 'iq1_m'
+    | 'bf16'
+    | 'tq1_0'
+    | 'tq2_0'
+    | 'mxfp4';
+
+export type RngType = 'std_default' | 'cuda' | 'cpu';
+
+export type Prediction = 'eps' | 'v' | 'edm_v' | 'flow' | 'flux_flow' | 'flux2_flow';
+
+export type PreviewMode = 'none' | 'proj' | 'tae' | 'vae';
+
+export type LogLevel = 0 | 1 | 2 | 3; // debug, info, warn, error
+
+export type LoraApplyMode = 'auto' | 'immediately' | 'at_runtime';
+
+export type CacheMode = 'disabled' | 'easycache' | 'ucache' | 'dbcache' | 'taylorseer' | 'cachedit';
+
+// --- Data interfaces ---
+
+export interface SdImage {
+    width: number;
+    height: number;
+    channel: number;
+    data: Buffer;
+}
+
+export interface LoraDefinition {
+    path: string;
+    multiplier?: number;
+    isHighNoise?: boolean;
+}
+
+export interface EmbeddingDefinition {
+    name: string;
+    path: string;
+}
+
+export interface SlgParams {
+    layers?: number[];
+    layerStart?: number;
+    layerEnd?: number;
+    scale?: number;
+}
+
+export interface GuidanceParams {
+    txtCfg?: number;
+    imgCfg?: number;
+    distilledGuidance?: number;
+    slg?: SlgParams;
+}
+
+export interface SampleParams {
+    guidance?: GuidanceParams;
+    scheduler?: Scheduler;
+    sampleMethod?: SampleMethod;
+    sampleSteps?: number;
+    eta?: number;
+    shiftedTimestep?: number;
+    flowShift?: number;
+    customSigmas?: number[];
+}
+
+export interface CacheParams {
+    mode?: CacheMode;
+    reuseThreshold?: number;
+    startPercent?: number;
+    endPercent?: number;
+    errorDecayRate?: number;
+    useRelativeThreshold?: boolean;
+    resetErrorOnCompute?: boolean;
+    fnComputeBlocks?: number;
+    bnComputeBlocks?: number;
+    residualDiffThreshold?: number;
+    maxWarmupSteps?: number;
+    maxCachedSteps?: number;
+    maxContinuousCachedSteps?: number;
+    taylorseerNDerivatives?: number;
+    taylorseerSkipInterval?: number;
+    scmPolicyDynamic?: boolean;
+}
+
+export interface TilingParams {
+    enabled?: boolean;
+    tileSizeX?: number;
+    tileSizeY?: number;
+    targetOverlap?: number;
+    relSizeX?: number;
+    relSizeY?: number;
+}
+
+export interface PhotoMakerParams {
+    idImages?: SdImage[];
+    idEmbedPath?: string;
+    styleStrength?: number;
+}
+
+// --- Abort support ---
+
+export interface AbortableOptions {
+    signal?: AbortSignal;
+}
+
+// --- Context creation options ---
+
+export interface ContextOptions extends AbortableOptions {
+    modelPath?: string;
+    clipLPath?: string;
+    clipGPath?: string;
+    clipVisionPath?: string;
+    t5xxlPath?: string;
+    llmPath?: string;
+    llmVisionPath?: string;
+    diffusionModelPath?: string;
+    highNoiseDiffusionModelPath?: string;
+    vaePath?: string;
+    taesdPath?: string;
+    controlNetPath?: string;
+    photoMakerPath?: string;
+    tensorTypeRules?: string;
+    embeddings?: EmbeddingDefinition[];
+    vaeDecodeOnly?: boolean;
+    freeParamsImmediately?: boolean;
+    nThreads?: number;
+    wtype?: SdType;
+    rngType?: RngType;
+    samplerRngType?: RngType;
+    prediction?: Prediction;
+    loraApplyMode?: LoraApplyMode;
+    offloadParamsToCpu?: boolean;
+    enableMmap?: boolean;
+    keepClipOnCpu?: boolean;
+    keepControlNetOnCpu?: boolean;
+    keepVaeOnCpu?: boolean;
+    flashAttn?: boolean;
+    diffusionFlashAttn?: boolean;
+    taePreviewOnly?: boolean;
+    diffusionConvDirect?: boolean;
+    vaeConvDirect?: boolean;
+    circularX?: boolean;
+    circularY?: boolean;
+    forceSdxlVaeConvScale?: boolean;
+    chromaUseDitMask?: boolean;
+    chromaUseT5Mask?: boolean;
+    chromaT5MaskPad?: number;
+    qwenImageZeroCondT?: boolean;
+}
+
+// --- Generation options ---
+
+export interface ImageGenerationOptions extends AbortableOptions {
+    prompt?: string;
+    negativePrompt?: string;
+    clipSkip?: number;
+    initImage?: SdImage;
+    refImages?: SdImage[];
+    autoResizeRefImage?: boolean;
+    increaseRefIndex?: boolean;
+    maskImage?: SdImage;
+    width?: number;
+    height?: number;
+    sampleParams?: SampleParams;
+    strength?: number;
+    seed?: number;
+    batchCount?: number;
+    controlImage?: SdImage;
+    controlStrength?: number;
+    photoMaker?: PhotoMakerParams;
+    vaeTiling?: TilingParams;
+    cache?: CacheParams;
+    loras?: LoraDefinition[];
+}
+
+export interface VideoGenerationOptions extends AbortableOptions {
+    prompt?: string;
+    negativePrompt?: string;
+    clipSkip?: number;
+    initImage?: SdImage;
+    endImage?: SdImage;
+    controlFrames?: SdImage[];
+    width?: number;
+    height?: number;
+    sampleParams?: SampleParams;
+    highNoiseSampleParams?: SampleParams;
+    moeBoundary?: number;
+    strength?: number;
+    seed?: number;
+    videoFrames?: number;
+    vaceStrength?: number;
+    vaeTiling?: TilingParams;
+    cache?: CacheParams;
+    loras?: LoraDefinition[];
+}
+
+export interface UpscalerOptions extends AbortableOptions {
+    esrganPath: string;
+    offloadParamsToCpu?: boolean;
+    direct?: boolean;
+    nThreads?: number;
+    tileSize?: number;
+}
+
+export interface UpscaleOptions extends AbortableOptions {}
+
+export interface ConvertOptions extends AbortableOptions {
+    inputPath: string;
+    outputPath: string;
+    vaePath?: string;
+    outputType?: SdType;
+    tensorTypeRules?: string;
+    convertName?: boolean;
+}
+
+export interface CannyOptions {
+    highThreshold?: number;
+    lowThreshold?: number;
+    weak?: number;
+    strong?: number;
+    inverse?: boolean;
+}
+
+export interface PreviewOptions {
+    mode?: PreviewMode;
+    interval?: number;
+    denoised?: boolean;
+    noisy?: boolean;
+}
+
+// --- Callback data types ---
+
+export interface LogCallbackData {
+    level: LogLevel;
+    text: string;
+}
+
+export interface ProgressCallbackData {
+    step: number;
+    steps: number;
+    time: number;
+}
+
+export interface PreviewCallbackData {
+    step: number;
+    isNoisy: boolean;
+    frames: SdImage[];
+}
+
+// --- Classes ---
+
+export class StableDiffusionContext {
+    private constructor();
+    static create(options: ContextOptions): Promise<StableDiffusionContext>;
+    generateImage(options: ImageGenerationOptions): Promise<SdImage[]>;
+    generateVideo(options: VideoGenerationOptions): Promise<SdImage[]>;
+    getDefaultSampleMethod(): SampleMethod;
+    getDefaultScheduler(sampleMethod?: SampleMethod): Scheduler;
+    close(): void;
+    readonly isClosed: boolean;
+}
+
+export class UpscalerContext {
+    private constructor();
+    static create(options: UpscalerOptions): Promise<UpscalerContext>;
+    upscale(image: SdImage, upscaleFactor?: number, options?: UpscaleOptions): Promise<SdImage>;
+    getUpscaleFactor(): number;
+    close(): void;
+    readonly isClosed: boolean;
+}
+
+// --- Free functions ---
+
+export function abort(): void;
+export function convert(options: ConvertOptions): Promise<boolean>;
+export function preprocessCanny(image: SdImage, options?: CannyOptions): boolean;
+export function setLogCallback(callback: ((data: LogCallbackData) => void) | null): void;
+export function setProgressCallback(callback: ((data: ProgressCallbackData) => void) | null): void;
+export function setPreviewCallback(
+    callback: ((data: PreviewCallbackData) => void) | null,
+    options?: PreviewOptions,
+): void;
+export function getSystemInfo(): string;
+export function getNumPhysicalCores(): number;
+export function version(): string;
+export function commit(): string;

package/src/js/index.js

@@ -0,0 +1,170 @@
+const loadBinding = require('./load-bindings');
+
+const native = loadBinding();
+
+function withAbortSignal(promise, signal) {
+    if (!signal) return promise;
+    if (signal.aborted) {
+        native.abort();
+        return Promise.reject(signal.reason ?? new DOMException('The operation was aborted.', 'AbortError'));
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            native.abort();
+            reject(signal.reason ?? new DOMException('The operation was aborted.', 'AbortError'));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then(
+            (v) => { signal.removeEventListener('abort', onAbort); resolve(v); },
+            (e) => { signal.removeEventListener('abort', onAbort); reject(e); },
+        );
+    });
+}
+
+class StableDiffusionContext {
+    #native;
+
+    /** @internal — use StableDiffusionContext.create() */
+    constructor(nativeCtx) {
+        this.#native = nativeCtx;
+    }
+
+    /**
+     * Create a new StableDiffusion context asynchronously.
+     * Model loading happens on a background thread.
+     * @param {object} options
+     * @returns {Promise<StableDiffusionContext>}
+     */
+    static async create(options) {
+        const { signal, ...opts } = options || {};
+        const ctx = await withAbortSignal(native.StableDiffusionContext.create(opts), signal);
+        return new StableDiffusionContext(ctx);
+    }
+
+    /**
+     * Generate images from a text prompt.
+     * @param {object} options
+     * @returns {Promise<Array<{width: number, height: number, channel: number, data: Buffer}>>}
+     */
+    async generateImage(options) {
+        const { signal, ...opts } = options || {};
+        return withAbortSignal(this.#native.generateImage(opts), signal);
+    }
+
+    /**
+     * Generate video frames from a text prompt.
+     * @param {object} options
+     * @returns {Promise<Array<{width: number, height: number, channel: number, data: Buffer}>>}
+     */
+    async generateVideo(options) {
+        const { signal, ...opts } = options || {};
+        return withAbortSignal(this.#native.generateVideo(opts), signal);
+    }
+
+    /**
+     * Get the default sample method for this model.
+     * @returns {string}
+     */
+    getDefaultSampleMethod() {
+        return this.#native.getDefaultSampleMethod();
+    }
+
+    /**
+     * Get the default scheduler for the given sample method.
+     * @param {string} [sampleMethod]
+     * @returns {string}
+     */
+    getDefaultScheduler(sampleMethod) {
+        return this.#native.getDefaultScheduler(sampleMethod);
+    }
+
+    /**
+     * Free the native context resources.
+     */
+    close() {
+        this.#native.close();
+    }
+
+    /**
+     * Whether the context has been closed.
+     * @returns {boolean}
+     */
+    get isClosed() {
+        return this.#native.isClosed;
+    }
+}
+
+class UpscalerContext {
+    #native;
+
+    /** @internal — use UpscalerContext.create() */
+    constructor(nativeCtx) {
+        this.#native = nativeCtx;
+    }
+
+    /**
+     * Create a new upscaler context asynchronously.
+     * @param {object} options
+     * @returns {Promise<UpscalerContext>}
+     */
+    static async create(options) {
+        const { signal, ...opts } = options || {};
+        const ctx = await withAbortSignal(native.UpscalerContext.create(opts), signal);
+        return new UpscalerContext(ctx);
+    }
+
+    /**
+     * Upscale an image.
+     * @param {{width: number, height: number, channel: number, data: Buffer}} image
+     * @param {number} [upscaleFactor=4]
+     * @param {{ signal?: AbortSignal }} [options]
+     * @returns {Promise<{width: number, height: number, channel: number, data: Buffer}>}
+     */
+    async upscale(image, upscaleFactor = 4, options) {
+        const { signal } = options || {};
+        return withAbortSignal(this.#native.upscale(image, upscaleFactor), signal);
+    }
+
+    /**
+     * Get the upscale factor for this model.
+     * @returns {number}
+     */
+    getUpscaleFactor() {
+        return this.#native.getUpscaleFactor();
+    }
+
+    /**
+     * Free the native context resources.
+     */
+    close() {
+        this.#native.close();
+    }
+
+    /**
+     * Whether the context has been closed.
+     * @returns {boolean}
+     */
+    get isClosed() {
+        return this.#native.isClosed;
+    }
+}
+
+module.exports = {
+    StableDiffusionContext,
+    UpscalerContext,
+
+    // Free functions
+    convert(options) {
+        const { signal, ...opts } = options || {};
+        return withAbortSignal(native.convert(opts), signal);
+    },
+    preprocessCanny: native.preprocessCanny,
+    setLogCallback: native.setLogCallback,
+    setProgressCallback: native.setProgressCallback,
+    setPreviewCallback: native.setPreviewCallback,
+    abort: native.abort,
+    getSystemInfo: native.getSystemInfo,
+    getNumPhysicalCores: native.getNumPhysicalCores,
+    version: native.version,
+    commit: native.commit,
+};

package/src/js/load-bindings.js

@@ -0,0 +1,40 @@
+const path = require('path');
+
+const PLATFORMS = {
+    'darwin-arm64': '@stable-diffusion-cpp-node-api/darwin-arm64',
+    'darwin-x64':   '@stable-diffusion-cpp-node-api/darwin-x64',
+    'linux-x64':    '@stable-diffusion-cpp-node-api/linux-x64',
+    'win32-x64':    '@stable-diffusion-cpp-node-api/win32-x64',
+};
+
+let binding;
+
+function loadBinding() {
+    if (binding) return binding;
+
+    const key = `${process.platform}-${process.arch}`;
+    const pkg = PLATFORMS[key];
+
+    // 1. Try platform-specific npm package
+    if (pkg) {
+        try {
+            binding = require(pkg);
+            return binding;
+        } catch (_) {}
+    }
+
+    // 2. Fallback to local build (development / unsupported platform)
+    try {
+        binding = require(path.resolve(__dirname, '..', '..', 'build', 'Release', 'node_stable_diffusion.node'));
+        return binding;
+    } catch (_) {}
+
+    throw new Error(
+        `stable-diffusion-cpp-node-api: no prebuilt binary for ${key}.\n` +
+        'Supported platforms: ' + Object.keys(PLATFORMS).join(', ') + '.\n' +
+        'To build from source, install from git instead:\n' +
+        '  npm install git+https://github.com/sir-ingvarr/node-stable-diffusion-cpp.git'
+    );
+}
+
+module.exports = loadBinding;