@gjsify/image-generation 0.0.0-stage → 0.64.29

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# @gjsify/image-generation
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Image generation in the WebML CG lifecycle shape: an `ImageGenerator` with `availability()`, `create({ monitor, signal })` and `destroy()`, a pure-TypeScript PNG decoder, and a local stable-diffusion.cpp engine for diffusion models on Node and GJS. The engine is a parameter, so an app can plug in a remote provider without gjsify shipping it.
+
+Part of the [gjsify](https://github.com/gjsify/gjsify) project. **Tier 3 (experimental, ADR 0003)**: the `ImageGenerator` and the engine's availability logic are unit-tested on Node and GJS; the sd.cpp engine is tested against a fake addon only. No real model has run through this port yet. Design: ADR 0137.
+
+## Installation
+
+```bash
+gjsify install @gjsify/image-generation
+```
+
+The root export needs nothing else. The sd.cpp engine needs its optional peers:
+
+```bash
+gjsify install stable-diffusion-cpp-node-api @stable-diffusion-cpp-node-api/linux-x64 @stable-diffusion-cpp-node-api/linux-x64-vulkan
+gjsify install @gjsify/napi   # GJS only
+```
+
+## Usage
+
+```typescript
+import { ImageGenerator, decode } from '@gjsify/image-generation';
+import { sdCppImageGeneration } from '@gjsify/image-generation/sdcpp';
+
+const engine = sdCppImageGeneration({ store, model: 'my-model' });
+
+if ((await ImageGenerator.availability({ engine })) !== 'unavailable') {
+    const generator = await ImageGenerator.create({
+        engine,
+        monitor: (m) => m.addEventListener('downloadprogress', (e) => console.log(e.loaded)),
+    });
+    const result = await generator.generate({ prompt: 'a cat in a spaceship' });
+    const image = await decode(result.blob);   // { width, height, data: Uint8ClampedArray }
+    await generator.destroy();
+}
+```
+
+`create()` downloads the model when it is missing (through `@gjsify/model-store`, digest-checked) and loads it. `availability()` reads no model bytes: it checks for the prebuilt binaries, the model file, and whether the machine has the memory for it (`@gjsify/machine-fit`).
+
+## Exports
+
+- **`.`** — `ImageGenerator`, `decode()`, and the types around them.
+- **`./engine`** — the `ImageEngine` / `ImageEngineFactory` interfaces for writing an engine of your own, local or remote.
+- **`./sdcpp`** — `sdCppImageGeneration(options)`, the engine factory that wraps stable-diffusion.cpp.
+
+What `ImageGenerator` guarantees for every engine:
+
+- One `generate()` runs at a time; later calls queue behind it.
+- Requests are validated before they reach the engine (positive integers where given, valid init image, finite LoRA multipliers).
+- An aborted `signal` rejects at once. A signal that is already aborted never reaches the engine.
+- `destroy()` waits for the calls it has already accepted, then frees the engine. Later calls reject.
+
+## The sd.cpp engine
+
+| Option | Default | |
+|---|---|---|
+| `store` | — | a `ModelStore<ImageModelEntry>` with the model manifest |
+| `model` | — | an id from the store |
+| `gpu` | `auto` | a `GpuSetting`, e.g. `parseGpuSetting(env.MYAPP_GPU)` from `@gjsify/machine-fit` |
+| `gpuGuardDir` | shared by all gjsify GPU engines | where the GPU guard keeps its pin |
+| `probe` | live machine probe | the machine `availability()` asks |
+
+The model entry extends `ModelEntry` with sd.cpp-specific roles:
+
+- `diffusionModel`: which file in `entry.files` is the diffusion checkpoint (required).
+- `vae`: optional VAE file name.
+- `llm`: optional text-encoder / LLM file name (e.g. Qwen for Z-Image).
+- `backend`: optional per-module device assignment, e.g. `te=cpu`.
+- `defaultWidth` / `defaultHeight`: the size the footprint was measured at.
+- `footprintBytes`: measured working set at the default size.
+
+`ImageRequest` carries `prompt`, optional `negativePrompt`, `width`, `height`, `steps`, `guidance`, `seed`, `sampler`, `scheduler`, `loras` and an `init` image for img2img.
+
+### Files the person already has
+
+For a checkpoint the person downloaded themselves, pass `local` instead of `store` and `model`. Nothing is fetched or verified:
+
+```typescript
+const engine = sdCppImageGeneration({
+    local: { modelId: 'my-checkpoint', diffusionModel: '/models/sdxl.safetensors', vae: '/models/vae.safetensors' },
+});
+```
+
+`availability()` is `available` when every named file exists and `unavailable` otherwise, never `downloadable`. `create()` throws and names the missing files. `LocalImageModel` takes `modelId` and `diffusionModel` (both required), `vae`, `llm`, `backend`, `defaultWidth` / `defaultHeight` (512 when absent) and `footprintBytes`. The memory check runs only when `footprintBytes` is given.
+
+**The GPU guard.** A Vulkan driver can hang a process instead of failing. Before going to the GPU, the engine leaves a pin in `gpuGuardDir` and removes it when the work finishes. A pin left over from a crash keeps the next run on the CPU and reports it through `onGpuPinned`. `gpu: 'on'` removes the pin.
+
+### Bundling for GJS
+
+`./sdcpp` imports `@gjsify/napi` statically. Evaluating the module loads no addon and no model. The import is static because a bundled dynamic `import('@gjsify/napi')` never settles on GJS: its modules with top-level await become lazy async initialisers, and the import hangs without an error.
+
+On GJS the native addon is loaded through `@gjsify/napi`. Start the app with `gjsify run` so the napi typelib is found.
+
+On macOS and Windows the sd.cpp engine runs on Node only, because the GJS route loads stable-diffusion-cpp-node-api's Linux prebuilt binaries.
+
+## License
+
+MIT

package/lib/esm/_virtual/_rolldown/runtime.js

@@ -0,0 +1 @@
+var e=Object.defineProperty,__name=(t,n)=>e(t,`name`,{value:n,configurable:!0});export{__name};

package/lib/esm/decode.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{inflateSync as e}from"node:zlib";const t=new Uint8Array([137,80,78,71,13,10,26,10]);function makeCrcTable(){let e=new Uint32Array(256);for(let t=0;t<256;t++){let n=t;for(let e=0;e<8;e++)n=n&1?3988292384^n>>>1:n>>>1;e[t]=n}return e}const n=makeCrcTable();function crc32(e){let t=-1;for(let r=0;r<e.length;r++)t=n[(t^e[r])&255]^t>>>8;return~t}function readUint32(e,t){return e[t]<<24|e[t+1]<<16|e[t+2]<<8|e[t+3]}function typeOf(e,t){return String.fromCharCode(e[t],e[t+1],e[t+2],e[t+3])}function assertPngSignature(e){if(e.length<t.length)throw Error(`PNG decoder: not a PNG file`);for(let n=0;n<t.length;n++)if(e[n]!==t[n])throw Error(`PNG decoder: not a PNG file`)}function paeth(e,t,n){let r=e+t-n,i=Math.abs(r-e),a=Math.abs(r-t),o=Math.abs(r-n);return i<=a&&i<=o?e:a<=o?t:n}function parseIhdr(e){let t=readUint32(e,0),n=readUint32(e,4),r=e[8],i=e[9],a=e[10],o=e[11],s=e[12];if(a!==0)throw Error(`PNG decoder: unsupported compression method`);if(o!==0)throw Error(`PNG decoder: unsupported filter method`);if(s!==0)throw Error(`PNG decoder: interlaced PNGs are not supported`);if(r!==8)throw Error(`PNG decoder: unsupported bit depth ${r}`);let c=i===2?3:i===6?4:0;if(c===0)throw Error(`PNG decoder: unsupported color type ${i} (only 8-bit RGB/RGBA)`);return{width:t,height:n,bitDepth:r,colorType:i,channels:c}}function unfilter(e,t,n,r){let i=t*r,a=new Uint8ClampedArray(i*n);for(let t=0;t<n;t++){let n=e[t*(i+1)],o=t*(i+1)+1,s=(t-1)*i,c=t*i;for(let l=0;l<i;l++){let i=e[o+l],u=l>=r?a[c+l-r]:0,d=t>0?a[s+l]:0,f=t>0&&l>=r?a[s+l-r]:0,p=0;switch(n){case 0:p=i;break;case 1:p=i+u;break;case 2:p=i+d;break;case 3:p=i+Math.trunc((u+d)/2);break;case 4:p=i+paeth(u,d,f);break;default:throw Error(`PNG decoder: unknown filter ${n} at row ${t}`)}a[c+l]=p&255}}return a}function expandRgbToRgba(e){let t=e.length/3,n=new Uint8ClampedArray(t*4);for(let t=0,r=0;t<e.length;t+=3,r+=4)n[r]=e[t],n[r+1]=e[t+1],n[r+2]=e[t+2],n[r+3]=255;return n}async function decode(n){let r=new Uint8Array(await n.arrayBuffer());assertPngSignature(r);let i=t.length,a,o=[];for(;i<r.length;){if(i+12>r.length)throw Error(`PNG decoder: truncated chunk`);let e=readUint32(r,i),t=typeOf(r,i+4);if(i+12+e>r.length)throw Error(`PNG decoder: truncated chunk data`);let n=r.subarray(i+8,i+8+e);if(readUint32(r,i+8+e)!==crc32(r.subarray(i+4,i+8+e)))throw Error(`PNG decoder: CRC mismatch in ${t} chunk`);switch(t){case`IHDR`:if(a!==void 0)throw Error(`PNG decoder: duplicate IHDR`);a=parseIhdr(n);break;case`IDAT`:o.push(n);break;case`IEND`:i=r.length;break}i+=12+e}if(a===void 0)throw Error(`PNG decoder: missing IHDR`);if(o.length===0)throw Error(`PNG decoder: missing IDAT`);let s=o.reduce((e,t)=>e+t.length,0),c=new Uint8Array(s),l=0;for(let e of o)c.set(e,l),l+=e.length;let u=e(c),d=a.width*a.channels,f=a.height*(d+1);if(u.length!==f)throw Error(`PNG decoder: inflated ${u.length} bytes, expected ${f}`);let p=unfilter(u,a.width,a.height,a.channels);return{width:a.width,height:a.height,data:a.channels===3?expandRgbToRgba(p):p}}export{decode};

package/lib/esm/encode.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{deflateSync as e}from"node:zlib";import{Blob as t}from"@gjsify/buffer";function makeCrcTable(){let e=new Uint32Array(256);for(let t=0;t<256;t++){let n=t;for(let e=0;e<8;e++)n=n&1?3988292384^n>>>1:n>>>1;e[t]=n}return e}const n=makeCrcTable();function crc32(e){let t=-1;for(let r=0;r<e.length;r++)t=n[(t^e[r])&255]^t>>>8;return~t}function writeUint32(e){return new Uint8Array([e>>>24&255,e>>>16&255,e>>>8&255,e&255])}function typeBytes(e){return new TextEncoder().encode(e)}function makeChunk(e,t){let n=typeBytes(e),r=new Uint8Array(n.length+t.length);r.set(n),r.set(t,n.length);let i=new Uint8Array(4+r.length+4);return i.set(writeUint32(t.length)),i.set(r,4),i.set(writeUint32(crc32(r)),4+r.length),i}function encodeRaw(t,n,r,i){if(t.length!==n*r*i)throw Error(`Pixel buffer is ${t.length} bytes, expected ${n*r*i}.`);let a=n*i,o=new Uint8Array(r*(a+1));for(let e=0;e<r;e++)o[e*(a+1)]=0,o.set(t.subarray(e*a,(e+1)*a),e*(a+1)+1);return e(o)}function encodePng(e){let{width:n,height:r,rgb:i}=e,a=new Uint8Array([n>>>24&255,n>>>16&255,n>>>8&255,n&255,r>>>24&255,r>>>16&255,r>>>8&255,r&255,8,2,0,0,0]),o=encodeRaw(i,n,r,3),s=[new Uint8Array([137,80,78,71,13,10,26,10]),makeChunk(`IHDR`,a),makeChunk(`IDAT`,o),makeChunk(`IEND`,new Uint8Array)],c=s.reduce((e,t)=>e+t.length,0),l=new Uint8Array(c),u=0;for(let e of s)l.set(e,u),u+=e.length;return new t([l],{type:`image/png`})}function encodePngRgba(e){let{width:n,height:r,rgba:i}=e,a=new Uint8Array([n>>>24&255,n>>>16&255,n>>>8&255,n&255,r>>>24&255,r>>>16&255,r>>>8&255,r&255,8,6,0,0,0]),o=encodeRaw(i,n,r,4),s=[new Uint8Array([137,80,78,71,13,10,26,10]),makeChunk(`IHDR`,a),makeChunk(`IDAT`,o),makeChunk(`IEND`,new Uint8Array)],c=s.reduce((e,t)=>e+t.length,0),l=new Uint8Array(c),u=0;for(let e of s)l.set(e,u),u+=e.length;return new t([l],{type:`image/png`})}export{encodePng,encodePngRgba};

package/lib/esm/generator.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";function untilAborted(e){if(e===void 0)return{promise:new Promise(()=>{}),dispose(){}};let onAbort=()=>{};return{promise:new Promise((t,n)=>{onAbort=()=>n(e.reason),e.addEventListener(`abort`,onAbort,{once:!0})}),dispose:()=>e.removeEventListener(`abort`,onAbort)}}function validateRequest(e){if(!e.prompt||typeof e.prompt!=`string`)throw TypeError(`ImageRequest.prompt must be a non-empty string`);if(e.width!==void 0&&(!Number.isInteger(e.width)||e.width<=0))throw RangeError(`ImageRequest.width must be a positive integer`);if(e.height!==void 0&&(!Number.isInteger(e.height)||e.height<=0))throw RangeError(`ImageRequest.height must be a positive integer`);if(e.steps!==void 0&&(!Number.isInteger(e.steps)||e.steps<=0))throw RangeError(`ImageRequest.steps must be a positive integer`);if(e.guidance!==void 0&&(!Number.isFinite(e.guidance)||e.guidance<0))throw RangeError(`ImageRequest.guidance must be a non-negative finite number`);if(e.seed!==void 0&&!Number.isInteger(e.seed))throw RangeError(`ImageRequest.seed must be an integer`);if(e.init!==void 0){let{width:t,height:n,rgb:r,strength:i}=e.init;if(!Number.isInteger(t)||t<=0||!Number.isInteger(n)||n<=0)throw RangeError(`InitImage.width and height must be positive integers`);if(!(r instanceof Uint8Array)||r.length!==t*n*3)throw RangeError(`InitImage.rgb must be a Uint8Array of width * height * 3 bytes`);if(!Number.isFinite(i)||i<0||i>1)throw RangeError(`InitImage.strength must be between 0 and 1`)}if(e.loras!==void 0)for(let t of e.loras){if(typeof t.path!=`string`||t.path.length===0)throw TypeError(`LoraRef.path must be a non-empty string`);if(!Number.isFinite(t.multiplier))throw TypeError(`LoraRef.multiplier must be a finite number`)}}var e=class ImageGenerator{#e;#t=Promise.resolve();#n=!1;constructor(e){this.#e=e}static availability(e){return e.engine.availability()}static async create(e){e.signal?.throwIfAborted();let t=await e.engine.create({monitor:e.monitor,signal:e.signal});if(e.signal?.aborted&&(await t.destroy().catch(()=>void 0),e.signal.throwIfAborted()),!t.modelId||typeof t.modelId!=`string`)throw await t.destroy().catch(()=>void 0),Error(`engine ${t.info.name} reports no modelId`);return new ImageGenerator(t)}get engine(){return this.#e.info}get modelId(){return this.#e.modelId}get backend(){return this.#e.backend}async generate(e,t={}){return validateRequest(e),this.#r(t,n=>this.#e.generate(e,{signal:n,onProgress:t.onProgress}))}async destroy(){this.#n||(this.#n=!0,await this.#t.catch(()=>void 0),await this.#e.destroy())}#r(e,t){if(this.#n)return Promise.reject(Error(`ImageGenerator was destroyed`));let{signal:n}=e;if(n?.aborted)return Promise.reject(n.reason);let r=this.#t.catch(()=>void 0).then(async()=>{n?.throwIfAborted();let e=await t(n);if(!e.blob||!(e.blob instanceof Blob))throw TypeError(`engine ${this.#e.info.name} returned no Blob`);if(e.blob.size===0)throw Error(`engine ${this.#e.info.name} returned an empty PNG`);if(!Number.isInteger(e.width)||!Number.isInteger(e.height)||e.width<=0||e.height<=0)throw Error(`engine ${this.#e.info.name} returned invalid size ${e.width}x${e.height}`);return e});this.#t=r;let i=untilAborted(n);return Promise.race([r,i.promise]).finally(i.dispose)}};export{e as ImageGenerator};

package/lib/esm/index.js

@@ -0,0 +1 @@
+import{decode as e}from"./decode.js";import{ImageGenerator as t}from"./generator.js";export{t as ImageGenerator,e as decode};

package/lib/esm/sdcpp-bin.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{existsSync as e}from"node:fs";import{dirname as t,join as n,resolve as r}from"node:path";import i from"node:process";import{hasVulkan as a}from"@gjsify/machine-fit";const o=`GJSIFY_SDCPP_ADDON`,s=`node_stable_diffusion.node`,c=`@stable-diffusion-cpp-node-api`;function ancestors(e){let n=[];for(let i=r(e);;i=t(i))if(n.push(i),t(i)===i)return n}function currentTarget(e=i){return`${e.platform}-${e.arch}`}function addonPath(e,t){return n(e,`node_modules`,c,t,s)}function findAddon(e=i.env,t){return findAddonForTarget(currentTarget(),t,e)}var AddonMissingError=class extends Error{};const l=new Set([`linux-x64`,`linux-arm64`]),u=new Set([`linux-x64`,`linux-arm64`,`darwin-arm64`,`darwin-x64`,`win32-x64`]);function hasPrebuiltBins(e=currentTarget(),t=runningOnGjs()){return t?l.has(e):u.has(e)}function runningOnGjs(e=globalThis){return e.imports!==void 0&&e.process?.versions?.gjs!==void 0}function backendCandidates(e,t,n){if(!l.has(e)||t===`off`||e!==`linux-x64`)return[e];let r=`${e}-vulkan`;return t===`on`||a(n)?[r,e]:[e]}function addonDir(e=currentTarget(),n){return t(findAddonForTarget(e,n))}function findAddonForTarget(t,r,a=i.env){let c=a[o]?.trim();if(c){let t=c.endsWith(`.node`)?c:n(c,s);if(e(t))return t;throw new AddonMissingError(`${o}=${c} has no ${s}`)}let l=[...r?ancestors(r):[],...ancestors(i.cwd())];for(let n of l){let r=addonPath(n,t);if(e(r))return r}throw new AddonMissingError(`No stable-diffusion.cpp addon for ${t}: install stable-diffusion-cpp-node-api or set ${o}.`)}export{o as ADDON_ENV,s as ADDON_FILE,AddonMissingError,c as SDCPP_PACKAGE,addonDir,addonPath,backendCandidates,currentTarget,findAddon,hasPrebuiltBins,runningOnGjs};

package/lib/esm/sdcpp-engine.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{encodePng as e}from"./encode.js";import{currentTarget as t,hasPrebuiltBins as n,runningOnGjs as r}from"./sdcpp-bin.js";import{existsSync as i}from"node:fs";import{checkFit as a,createGpuGuard as o,defaultGuardDir as s,onBattery as c,readMachineMemory as l,systemProbe as u}from"@gjsify/machine-fit";const d={name:`sd.cpp`,locality:`local`};var GenerationAborted=class extends Error{constructor(){super(`Aborted`),this.name=`AbortError`}};function toNativeOptions(e,t,n){let r={prompt:e.prompt,width:t,height:n,seed:e.seed??Math.floor(Math.random()*2**32),sampleParams:{sampleSteps:e.steps??20,guidance:{txtCfg:e.guidance??7.5}}};return e.negativePrompt&&(r.negativePrompt=e.negativePrompt),e.sampler&&(r.sampleParams.sampleMethod=e.sampler),e.scheduler&&(r.sampleParams.scheduler=e.scheduler),e.loras?.length&&(r.loras=e.loras.map(e=>({path:e.path,multiplier:e.multiplier}))),e.init&&(r.initImage={width:e.init.width,height:e.init.height,channel:3,data:e.init.rgb},r.strength=e.init.strength),r}function contextOptions(e){let t={diffusionModelPath:e.diffusionModel};return e.vae&&(t.vaePath=e.vae),e.llm&&(t.llmPath=e.llm),e.backend&&(t.backend=e.backend),t}function toNativeContext(e,t){return contextOptions({diffusionModel:t[e.diffusionModel],vae:e.vae?t[e.vae]:void 0,llm:e.llm?t[e.llm]:void 0,backend:e.backend})}function storeSource(e){let{store:t}=e,n=t.require(e.model);return assertModelFiles(n),{modelId:n.modelId,backend:n.backend,footprintBytes:n.footprintBytes,width:n.defaultWidth,height:n.defaultHeight,availability:async()=>t.availability(n.id),async prepare(e){let r=await t.install(n.id,{monitor:e.monitor,signal:e.signal});return{diffusionModel:r.files[n.diffusionModel],vae:n.vae?r.files[n.vae]:void 0,llm:n.llm?r.files[n.llm]:void 0,backend:n.backend}}}}function missingFiles(e){return[e.diffusionModel,e.vae,e.llm].filter(e=>e!==void 0&&e!==``&&!i(e))}function localSource(e){if(!e.modelId)throw Error(`sd.cpp local model needs a modelId`);if(!e.diffusionModel)throw Error(`sd.cpp local model '${e.modelId}' needs a diffusionModel path`);return{modelId:e.modelId,backend:e.backend,footprintBytes:e.footprintBytes,width:e.defaultWidth??512,height:e.defaultHeight??512,availability:async()=>missingFiles(e).length===0?`available`:`unavailable`,async prepare(){let t=missingFiles(e);if(t.length>0)throw Error(`sd.cpp model '${e.modelId}' has missing files: ${t.join(`, `)}`);return{diffusionModel:e.diffusionModel,vae:e.vae,llm:e.llm,backend:e.backend}}}}function resolveSize(e,t){return{width:e.width??t.width,height:e.height??t.height}}let f=!1;function defaultOnGpuPinned(e){console.error(`The GPU is switched off for image generation: process ${e.pid} died while using it (${e.at}). Turn the GPU setting on to try it again.`)}function assertModelFiles(e){let t=new Set(e.files.map(e=>e.file));if(!t.has(e.diffusionModel))throw Error(`sd.cpp model '${e.id}' names '${e.diffusionModel}' as diffusionModel, but it is not in files`);if(e.vae&&!t.has(e.vae))throw Error(`sd.cpp model '${e.id}' names '${e.vae}' as vae, but it is not in files`);if(e.llm&&!t.has(e.llm))throw Error(`sd.cpp model '${e.id}' names '${e.llm}' as llm, but it is not in files`)}function isCpuOnly(e){return e===void 0?!1:e.split(`,`).every(e=>e.trim().toLowerCase()===`cpu`)}function createSdCppEngine(i,p){let m=`local`in p?localSource(p.local):storeSource(p),h=p.gpu??`auto`,g,gpuGuard=()=>g??=o({dir:p.gpuGuardDir??s(`gjsify`)}),gpuBarred=()=>{if(isCpuOnly(m.backend)||h===`off`)return!0;if(h===`on`)return gpuGuard().clear(),!1;let e=gpuGuard().pin();return e===void 0?!1:(f||(f=!0,(p.onGpuPinned??defaultOnGpuPinned)(e)),!0)};return{info:d,async availability(){let e=p.probe??u();if(c(e)||!n(t(e),r()))return`unavailable`;if(m.footprintBytes!==void 0){let t=l(e);if(a(m.footprintBytes,t).placement===`none`)return`unavailable`}return m.availability()},async create(t={}){let n=await m.prepare(t);t.signal?.throwIfAborted();let r,a,o=!1,open=async()=>{r??=await i();let e=gpuBarred(),t=contextOptions(n);e&&!t.backend&&(t.backend=`cpu`),a??=await r.StableDiffusionContext.create(t),o=!e};if(await open(),!a)throw Error(`sd.cpp context did not open`);let generate=async t=>{let{width:n,height:r}=resolveSize(t,m),i=toNativeOptions(t,n,r),o=(await a.generateImage(i))[0];if(!o)throw Error(`The engine returned no image.`);if(o.channel!==3)throw Error(`sd.cpp returned ${o.channel} channels, expected 3`);let s=new Uint8Array(o.data);return{blob:e({width:o.width,height:o.height,rgb:s}),width:o.width,height:o.height,seed:i.seed,modelId:m.modelId}};return{info:d,modelId:m.modelId,get backend(){return o?`gpu`:`cpu`},async generate(e,t={}){let{signal:n,onProgress:i}=t;if(n?.aborted)throw new GenerationAborted;let onAbort=()=>a.abort();n?.addEventListener(`abort`,onAbort,{once:!0});let work=async()=>(r.setProgressCallback(i?({step:e,steps:t,time:n})=>i({step:e,steps:t,seconds:n}):null),await generate(e));try{return o?await gpuGuard().during(work):await work()}catch(e){throw n?.aborted?new GenerationAborted:e}finally{n?.removeEventListener(`abort`,onAbort),r.setProgressCallback(null)}},async destroy(){a?.close(),a=void 0}}}}}export{GenerationAborted,d as SDCPP_ENGINE,createSdCppEngine,toNativeContext,toNativeOptions};

package/lib/esm/sdcpp.js

@@ -0,0 +1 @@
+import"./_virtual/_rolldown/runtime.js";import{AddonMissingError as e,addonDir as t,addonPath as n,backendCandidates as r,currentTarget as i,findAddon as a,hasPrebuiltBins as o,runningOnGjs as s}from"./sdcpp-bin.js";import{SDCPP_ENGINE as c,createSdCppEngine as l,toNativeContext as u,toNativeOptions as d}from"./sdcpp-engine.js";import{dirname as f}from"node:path";import{fileURLToPath as p}from"node:url";import{loadAddon as m}from"@gjsify/napi";async function loadSdAddon(){return m(a(process.env,f(p(import.meta.url))))}function sdCppImageGeneration(e){return l(loadSdAddon,e)}export{e as AddonMissingError,c as SDCPP_ENGINE,t as addonDir,n as addonPath,r as backendCandidates,i as currentTarget,a as findAddon,o as hasPrebuiltBins,s as runningOnGjs,sdCppImageGeneration,u as toNativeContext,d as toNativeOptions};

package/lib/types/decode.d.ts

@@ -0,0 +1,10 @@
+import type { DecodedImage } from './engine.js';
+export interface PngHeader {
+    readonly width: number;
+    readonly height: number;
+    readonly bitDepth: number;
+    readonly colorType: number;
+    readonly channels: number;
+}
+/** Decode a PNG blob to the structural shape of `ImageData`. */
+export declare function decode(blob: Blob): Promise<DecodedImage>;

package/lib/types/encode.d.ts

@@ -0,0 +1,16 @@
+export interface RgbImage {
+    readonly width: number;
+    readonly height: number;
+    /** Tightly packed RGB, `width * height * 3` bytes. */
+    readonly rgb: Uint8Array;
+}
+export interface RgbaImage {
+    readonly width: number;
+    readonly height: number;
+    /** Tightly packed RGBA, `width * height * 4` bytes. */
+    readonly rgba: Uint8Array;
+}
+/** Encode an RGB image as a PNG `Blob`. */
+export declare function encodePng(image: RgbImage): Blob;
+/** Encode an RGBA image as a PNG `Blob`. */
+export declare function encodePngRgba(image: RgbaImage): Blob;

package/lib/types/engine.d.ts

@@ -0,0 +1,83 @@
+import type { CreateMonitorCallback } from '@gjsify/model-store';
+/** The WebML CG availability states. */
+export type Availability = 'unavailable' | 'downloadable' | 'downloading' | 'available';
+/** Which engine runs, so a surface can say where the image is drawn (ADR 0132 § 3). */
+export interface EngineInfo {
+    readonly name: string;
+    readonly locality: 'local' | 'remote';
+}
+export interface LoraRef {
+    /** Verified file path for this LoRA. */
+    readonly path: string;
+    /** Strength, typically 0..1. */
+    readonly multiplier: number;
+}
+/** A starting image for img2img; `strength` 0..1 says how far to move from it. */
+export interface InitImage {
+    readonly width: number;
+    readonly height: number;
+    /** Tightly packed RGB, `width * height * 3` bytes. */
+    readonly rgb: Uint8Array;
+    readonly strength: number;
+}
+/** What to draw. Defaults and upper bounds are the engine's. */
+export interface ImageRequest {
+    readonly prompt: string;
+    readonly negativePrompt?: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly steps?: number;
+    /** Classifier-free guidance scale. */
+    readonly guidance?: number;
+    readonly seed?: number;
+    readonly sampler?: string;
+    readonly scheduler?: string;
+    readonly loras?: readonly LoraRef[];
+    readonly init?: InitImage;
+}
+export interface GenerateProgress {
+    readonly step: number;
+    readonly steps: number;
+    /** Seconds spent so far on the current step. */
+    readonly seconds: number;
+}
+export interface GenerateOptions {
+    readonly signal?: AbortSignal;
+    readonly onProgress?: (progress: GenerateProgress) => void;
+}
+/** The structural shape of `ImageData` from `@gjsify/canvas2d-core`, without the dependency. */
+export interface DecodedImage {
+    readonly width: number;
+    readonly height: number;
+    /** RGBA, `width * height * 4` bytes. */
+    readonly data: Uint8ClampedArray;
+}
+/** One generated image: the engine's PNG bytes plus the metadata needed to record it. */
+export interface ImageResult {
+    readonly blob: Blob;
+    readonly width: number;
+    readonly height: number;
+    /** The seed the engine used, so a liked image can be reproduced. */
+    readonly seed: number;
+    readonly modelId: string;
+}
+export interface EngineCreateOptions {
+    readonly monitor?: CreateMonitorCallback;
+    readonly signal?: AbortSignal;
+}
+/** A loaded model. Every method may be called again after the previous call settled. */
+export interface ImageEngine {
+    readonly info: EngineInfo;
+    /** What produced the image, recorded by a gallery next to it. */
+    readonly modelId: string;
+    /** Where the image is drawn right now, when the engine knows; it can change mid-run. */
+    readonly backend?: 'gpu' | 'cpu';
+    generate(request: ImageRequest, options?: GenerateOptions): Promise<ImageResult>;
+    destroy(): Promise<void>;
+}
+/** How `ImageGenerator` asks an engine whether it can run, and starts it. */
+export interface ImageEngineFactory {
+    readonly info: EngineInfo;
+    availability(): Promise<Availability>;
+    create(options?: EngineCreateOptions): Promise<ImageEngine>;
+}

package/lib/types/generator.d.ts

@@ -0,0 +1,20 @@
+import type { Availability, EngineCreateOptions, EngineInfo, GenerateOptions, ImageEngineFactory, ImageRequest, ImageResult } from './engine.js';
+export interface ImageGeneratorAvailabilityOptions {
+    readonly engine: ImageEngineFactory;
+}
+export interface ImageGeneratorCreateOptions extends EngineCreateOptions {
+    readonly engine: ImageEngineFactory;
+}
+export declare class ImageGenerator {
+    #private;
+    private constructor();
+    static availability(options: ImageGeneratorAvailabilityOptions): Promise<Availability>;
+    /** Downloads the model when the engine needs one and it is missing, then loads it. */
+    static create(options: ImageGeneratorCreateOptions): Promise<ImageGenerator>;
+    get engine(): EngineInfo;
+    get modelId(): string;
+    get backend(): 'gpu' | 'cpu' | undefined;
+    generate(request: ImageRequest, options?: GenerateOptions): Promise<ImageResult>;
+    /** Waits for a running call, then frees the model. Later calls reject. */
+    destroy(): Promise<void>;
+}

package/lib/types/generator.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/index.d.ts

@@ -0,0 +1,3 @@
+export { ImageGenerator, type ImageGeneratorAvailabilityOptions, type ImageGeneratorCreateOptions, } from './generator.js';
+export { decode } from './decode.js';
+export type { Availability, DecodedImage, EngineCreateOptions, EngineInfo, GenerateOptions, GenerateProgress, ImageEngine, ImageEngineFactory, ImageRequest, ImageResult, InitImage, LoraRef, } from './engine.js';

package/lib/types/png.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/lib/types/sdcpp-bin.d.ts

@@ -0,0 +1,40 @@
+import { type GpuSetting, type MachineProbe } from '@gjsify/machine-fit';
+export declare const ADDON_ENV = "GJSIFY_SDCPP_ADDON";
+export declare const ADDON_FILE = "node_stable_diffusion.node";
+export declare const SDCPP_PACKAGE = "@stable-diffusion-cpp-node-api";
+/** This machine, as stable-diffusion-cpp-node-api names its binary directories. */
+export declare function currentTarget(probe?: Pick<MachineProbe, 'platform' | 'arch'>): string;
+/** The addon file inside the package's per-target directory. */
+export declare function addonPath(root: string, target: string): string;
+/**
+ * Where the addon is: `GJSIFY_SDCPP_ADDON` (a `.node` file or its directory)
+ * first, then the `node_modules` above the running bundle and above the working
+ * directory — a bundle cannot resolve a package at run time, but it sits inside
+ * the checkout that installed it.
+ */
+export declare function findAddon(env?: Record<string, string | undefined>, here?: string): string;
+export declare class AddonMissingError extends Error {
+}
+/** Is there an addon build for this machine? A table lookup, so it is free to ask. */
+export declare function hasPrebuiltBins(target?: string, onGjs?: boolean): boolean;
+/** What {@link runningOnGjs} looks at; injected so the Node-with-node-gi case is testable. */
+export interface RuntimeHost {
+    imports?: unknown;
+    process?: {
+        versions?: {
+            gjs?: string;
+        };
+    };
+}
+/**
+ * Is this GJS? Not "is there an `imports`": node-gi defines `globalThis.imports`
+ * on Node too, and asking only that sent a Node app down the `@gjsify/napi` route.
+ */
+export declare function runningOnGjs(host?: RuntimeHost): boolean;
+/**
+ * The GJS builds to try, best first; the last is always the CPU build. Only
+ * Linux x64 has a Vulkan variant.
+ */
+export declare function backendCandidates(target: string, gpu: GpuSetting, probe: MachineProbe): string[];
+/** The directory holding the addon and its backends, for `@gjsify/napi`. */
+export declare function addonDir(target?: string, here?: string): string;

package/lib/types/sdcpp-engine.d.ts

@@ -0,0 +1,130 @@
+import type { ModelEntry, ModelStore } from '@gjsify/model-store';
+import { type GpuPin, type GpuSetting, type MachineProbe } from '@gjsify/machine-fit';
+import type { EngineInfo, ImageEngineFactory, ImageRequest } from './engine.js';
+export declare const SDCPP_ENGINE: EngineInfo;
+/** A fetchable image model: one or more verified files plus sd.cpp's role mapping. */
+export interface ImageModelEntry extends ModelEntry {
+    /** What a gallery records next to the image (`ImageGenerator.modelId`). */
+    readonly modelId: string;
+    /** Which file in {@link ModelEntry.files} is the diffusion checkpoint. */
+    readonly diffusionModel: string;
+    /** Optional VAE file name. */
+    readonly vae?: string;
+    /** Optional text-encoder / LLM file name (e.g. Qwen for Z-Image). */
+    readonly llm?: string;
+    /** Per-module device assignment, e.g. `te=cpu` — see sd.cpp's docs/backend.md. */
+    readonly backend?: string;
+    /** Default width the footprint was measured at. */
+    readonly defaultWidth: number;
+    /** Default height the footprint was measured at. */
+    readonly defaultHeight: number;
+    /** Working set at defaultWidth/defaultHeight, measured, not derived from file size. */
+    readonly footprintBytes: number;
+}
+/** Fields every sd.cpp engine takes, whatever supplies the model files. */
+export interface SdCppCommonOptions {
+    /** The person's GPU switch, e.g. `parseGpuSetting(env.MYAPP_GPU)`. `on` also lifts a pin. */
+    readonly gpu?: GpuSetting;
+    /**
+     * Where the GPU guard keeps its pin. Default: the one shared by every
+     * gjsify GPU engine (ADR 0132 § 6).
+     */
+    readonly gpuGuardDir?: string;
+    /** Told once per process when a pin keeps this engine on the CPU. Default: a line on stderr. */
+    readonly onGpuPinned?: (pin: GpuPin) => void;
+    /** The machine `availability()` asks. */
+    readonly probe?: MachineProbe;
+}
+/** The model comes from a {@link ModelStore}: fetched, verified and placed by the store. */
+export interface SdCppEngineOptions<E extends ImageModelEntry = ImageModelEntry> extends SdCppCommonOptions {
+    /** A store that contains the model manifest. */
+    readonly store: ModelStore<E>;
+    /** Model id from the store; `create()` requires one. */
+    readonly model: string;
+}
+/**
+ * A model that already sits on disk, chosen by the person (a checkpoint they downloaded
+ * themselves). Nothing is fetched or verified: the files either exist or the engine is
+ * `unavailable`.
+ */
+export interface LocalImageModel {
+    /** What a gallery records next to the image (`ImageGenerator.modelId`). */
+    readonly modelId: string;
+    /** Path of the diffusion checkpoint. */
+    readonly diffusionModel: string;
+    /** Path of the VAE, if the model needs a separate one. */
+    readonly vae?: string;
+    /** Path of the text encoder / LLM, if the model family needs one. */
+    readonly llm?: string;
+    /** Per-module device assignment, e.g. `te=cpu` — see sd.cpp's docs/backend.md. */
+    readonly backend?: string;
+    /** Size used when a request names none. Default 512x512. */
+    readonly defaultWidth?: number;
+    readonly defaultHeight?: number;
+    /**
+     * Working set at the default size. Optional: without it `availability()` cannot say the
+     * machine is too small, and the model simply tries to load.
+     */
+    readonly footprintBytes?: number;
+}
+export interface SdCppLocalOptions extends SdCppCommonOptions {
+    readonly local: LocalImageModel;
+}
+export type SdCppOptions<E extends ImageModelEntry = ImageModelEntry> = SdCppEngineOptions<E> | SdCppLocalOptions;
+export interface NativeGenerateOptions {
+    prompt: string;
+    negativePrompt?: string;
+    width: number;
+    height: number;
+    seed: number;
+    sampleParams: {
+        sampleSteps: number;
+        guidance: {
+            txtCfg: number;
+        };
+        sampleMethod?: string;
+        scheduler?: string;
+    };
+    loras?: Array<{
+        path: string;
+        multiplier: number;
+    }>;
+    initImage?: {
+        width: number;
+        height: number;
+        channel: number;
+        data: Uint8Array;
+    };
+    strength?: number;
+}
+export interface NativeImage {
+    width: number;
+    height: number;
+    channel: number;
+    data: ArrayLike<number>;
+}
+export interface NativeContext {
+    generateImage(options: NativeGenerateOptions): Promise<NativeImage[]>;
+    abort(): void;
+    close(): void;
+}
+/** The slice of the addon this engine uses; also what tests fake. */
+export interface SdAddon {
+    StableDiffusionContext: {
+        create(options: Record<string, unknown>): Promise<NativeContext>;
+    };
+    setProgressCallback(callback: ((data: {
+        step: number;
+        steps: number;
+        time: number;
+    }) => void) | null): void;
+    setLogCallback?(callback: ((level: number, message: string) => void) | null): void;
+}
+export declare class GenerationAborted extends Error {
+    constructor();
+}
+/** Request → the addon's option object. Pure, so the mapping is testable without a GPU. */
+export declare function toNativeOptions(request: ImageRequest, width: number, height: number): NativeGenerateOptions;
+export declare function toNativeContext(model: ImageModelEntry, files: Record<string, string>): Record<string, unknown>;
+/** {@link sdCppImageGeneration} with the addon loader passed in. */
+export declare function createSdCppEngine<E extends ImageModelEntry = ImageModelEntry>(loadAddon: () => Promise<SdAddon>, options: SdCppOptions<E>): ImageEngineFactory;

package/lib/types/sdcpp.d.ts

@@ -0,0 +1,10 @@
+import type { ImageEngineFactory } from './engine.js';
+import { type ImageModelEntry, type SdCppOptions } from './sdcpp-engine.js';
+export { SDCPP_ENGINE, type ImageModelEntry, type LocalImageModel, type NativeGenerateOptions, type NativeImage, type SdAddon, type SdCppCommonOptions, type SdCppEngineOptions, type SdCppLocalOptions, type SdCppOptions, toNativeContext, toNativeOptions, } from './sdcpp-engine.js';
+export { addonDir, addonPath, AddonMissingError, backendCandidates, currentTarget, findAddon, hasPrebuiltBins, runningOnGjs, } from './sdcpp-bin.js';
+/**
+ * The sd.cpp image-generation engine factory, for `ImageGenerator.availability()` and
+ * `ImageGenerator.create()`. Pass `{ store, model }` for a fetched model or `{ local }` for
+ * files the person already has.
+ */
+export declare function sdCppImageGeneration<E extends ImageModelEntry = ImageModelEntry>(options: SdCppOptions<E>): ImageEngineFactory;

package/lib/types/sdcpp.spec.d.ts

@@ -0,0 +1,2 @@
+declare const _default: () => Promise<void>;
+export default _default;

package/package.json

@@ -1,6 +1,100 @@
 {
-  "name": "@gjsify/image-generation",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@gjsify/image-generation",
+    "version": "0.64.29",
+    "description": "Image generation in the WebML CG lifecycle shape: an ImageGenerator with availability(), create({ monitor, signal }) and destroy(), and a local stable-diffusion.cpp engine for diffusion models on Node and GJS.",
+    "module": "lib/esm/index.js",
+    "types": "lib/types/index.d.ts",
+    "type": "module",
+    "sideEffects": false,
+    "exports": {
+        ".": {
+            "types": "./lib/types/index.d.ts",
+            "default": "./lib/esm/index.js"
+        },
+        "./engine": {
+            "types": "./lib/types/engine.d.ts",
+            "default": "./lib/esm/engine.js"
+        },
+        "./sdcpp": {
+            "types": "./lib/types/sdcpp.d.ts",
+            "default": "./lib/esm/sdcpp.js"
+        }
+    },
+    "files": [
+        "lib",
+        "!lib/types/**/*.spec.d.ts"
+    ],
+    "scripts": {
+        "clear": "gjsify clear lib tmp tsconfig.tsbuildinfo test.gjs.mjs test.node.mjs",
+        "check": "gjsify tsc --noEmit",
+        "build": "gjsify run build:gjsify && gjsify run build:types",
+        "build:gjsify": "gjsify build --library 'src/**/*.{ts,js}' --exclude 'src/**/*.spec.{mts,ts}' 'src/test.{mts,ts}'",
+        "build:types": "gjsify tsc",
+        "build:test": "gjsify run build:test:gjs && gjsify run build:test:node",
+        "build:test:gjs": "gjsify build src/test.mts --app gjs --outfile test.gjs.mjs --external @gjsify/napi",
+        "build:test:node": "gjsify build src/test.mts --app node --outfile test.node.mjs --external @gjsify/napi",
+        "test": "gjsify run build:gjsify && gjsify run build:test && gjsify run test:node && gjsify run test:gjs",
+        "test:gjs": "gjsify run test.gjs.mjs",
+        "test:node": "node test.node.mjs"
+    },
+    "keywords": [
+        "image-generation",
+        "diffusion",
+        "ai",
+        "stable-diffusion",
+        "sd.cpp",
+        "webml"
+    ],
+    "dependencies": {
+        "@gjsify/buffer": "^0.64.29",
+        "@gjsify/fs": "^0.64.29",
+        "@gjsify/machine-fit": "^0.64.29",
+        "@gjsify/model-store": "^0.64.29",
+        "@gjsify/path": "^0.64.29",
+        "@gjsify/process": "^0.64.29",
+        "@gjsify/zlib": "^0.64.29"
+    },
+    "peerDependencies": {
+        "@gjsify/napi": "^0.64.19"
+    },
+    "peerDependenciesMeta": {
+        "@gjsify/napi": {
+            "optional": true
+        }
+    },
+    "devDependencies": {
+        "@gjsify/cli": "^0.64.29",
+        "@gjsify/unit": "^0.64.29",
+        "@types/node": "^25.9.2",
+        "typescript": "^6.0.3"
+    },
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/gjsify/gjsify.git",
+        "directory": "packages/gjs/image-generation"
+    },
+    "bugs": {
+        "url": "https://github.com/gjsify/gjsify/issues"
+    },
+    "homepage": "https://github.com/gjsify/gjsify/tree/main/packages/gjs/image-generation#readme",
+    "gjsify": {
+        "tier": 3,
+        "runtimes": {
+            "gjs": "polyfill",
+            "node": "none",
+            "browser": "none",
+            "nativescript": "none"
+        },
+        "os": {
+            "linux": "supported",
+            "darwin": "partial",
+            "win32": "partial"
+        },
+        "osNotes": {
+            "darwin": "The sd.cpp engine runs on Node only: the GJS route loads stable-diffusion.cpp's Linux prebuilt binaries.",
+            "win32": "The sd.cpp engine runs on Node only: the GJS route loads stable-diffusion.cpp's Linux prebuilt binaries."
+        },
+        "headless": true
+    }
+}