@gjsify/image-generation 0.64.28 → 0.64.30

package/README.md

@@ -72,6 +72,18 @@ The model entry extends `ModelEntry` with sd.cpp-specific roles:
 
 `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

package/lib/esm/sdcpp-engine.js

@@ -1 +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{checkFit as i,createGpuGuard as a,defaultGuardDir as o,onBattery as s,readMachineMemory as c,systemProbe as l}from"@gjsify/machine-fit";const u={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 toNativeContext(e,t){let n={diffusionModelPath:t[e.diffusionModel]};return e.vae&&(n.vaePath=t[e.vae]),e.llm&&(n.llmPath=t[e.llm]),e.backend&&(n.backend=e.backend),n}function defaultSize(e){return{width:e.defaultWidth,height:e.defaultHeight}}function resolveSize(e,t){let{width:n,height:r}=defaultSize(t);return{width:e.width??n,height:e.height??r}}let d=!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(f,p){let m=p.store,h=m.require(p.model);assertModelFiles(h);let g=p.gpu??`auto`,_,gpuGuard=()=>_??=a({dir:p.gpuGuardDir??o(`gjsify`)}),gpuBarred=()=>{if(isCpuOnly(h.backend)||g===`off`)return!0;if(g===`on`)return gpuGuard().clear(),!1;let e=gpuGuard().pin();return e===void 0?!1:(d||(d=!0,(p.onGpuPinned??defaultOnGpuPinned)(e)),!0)};return{info:u,async availability(){let e=p.probe??l();if(s(e)||!n(t(e),r()))return`unavailable`;let a=c(e);return i(h.footprintBytes,a).placement===`none`?`unavailable`:m.availability(h.id)},async create(t={}){let n=await m.install(h.id,{monitor:t.monitor,signal:t.signal});t.signal?.throwIfAborted();let r,i,a=!1,open=async()=>{r??=await f();let e=gpuBarred(),t=toNativeContext(h,n.files);e&&!t.backend&&(t.backend=`cpu`),i??=await r.StableDiffusionContext.create(t),a=!e};if(await open(),!i)throw Error(`sd.cpp context did not open`);let generate=async t=>{let{width:n,height:r}=resolveSize(t,h),a=toNativeOptions(t,n,r),o=(await i.generateImage(a))[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:a.seed,modelId:h.modelId}};return{info:u,modelId:h.modelId,get backend(){return a?`gpu`:`cpu`},async generate(e,t={}){let{signal:n,onProgress:o}=t;if(n?.aborted)throw new GenerationAborted;let onAbort=()=>i.abort();n?.addEventListener(`abort`,onAbort,{once:!0});let work=async()=>(r.setProgressCallback(o?({step:e,steps:t,time:n})=>o({step:e,steps:t,seconds:n}):null),await generate(e));try{return a?await gpuGuard().during(work):await work()}catch(e){throw n?.aborted?new GenerationAborted:e}finally{n?.removeEventListener(`abort`,onAbort),r.setProgressCallback(null)}},async destroy(){i?.close(),i=void 0}}}}}export{GenerationAborted,u as SDCPP_ENGINE,createSdCppEngine,toNativeContext,toNativeOptions};
+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/types/sdcpp-engine.d.ts

@@ -21,11 +21,8 @@ export interface ImageModelEntry extends ModelEntry {
     /** Working set at defaultWidth/defaultHeight, measured, not derived from file size. */
     readonly footprintBytes: number;
 }
-export interface SdCppEngineOptions<E extends ImageModelEntry = ImageModelEntry> {
-    /** A store that contains the model manifest. */
-    readonly store: ModelStore<E>;
-    /** Model id from the store; `create()` requires one. */
-    readonly model: string;
+/** 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;
     /**
@@ -38,6 +35,42 @@ export interface SdCppEngineOptions<E extends ImageModelEntry = ImageModelEntry>
     /** 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;
@@ -94,4 +127,4 @@ export declare class GenerationAborted extends Error {
 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: SdCppEngineOptions<E>): ImageEngineFactory;
+export declare function createSdCppEngine<E extends ImageModelEntry = ImageModelEntry>(loadAddon: () => Promise<SdAddon>, options: SdCppOptions<E>): ImageEngineFactory;

package/lib/types/sdcpp.d.ts

@@ -1,6 +1,10 @@
 import type { ImageEngineFactory } from './engine.js';
-import { type ImageModelEntry, type SdCppEngineOptions } from './sdcpp-engine.js';
-export { SDCPP_ENGINE, type ImageModelEntry, type NativeGenerateOptions, type NativeImage, type SdAddon, type SdCppEngineOptions, toNativeContext, toNativeOptions, } from './sdcpp-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()`. */
-export declare function sdCppImageGeneration<E extends ImageModelEntry = ImageModelEntry>(options: SdCppEngineOptions<E>): ImageEngineFactory;
+/**
+ * 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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/image-generation",
-    "version": "0.64.28",
+    "version": "0.64.30",
     "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",
@@ -46,13 +46,13 @@
         "webml"
     ],
     "dependencies": {
-        "@gjsify/buffer": "^0.64.28",
-        "@gjsify/fs": "^0.64.28",
-        "@gjsify/machine-fit": "^0.64.28",
-        "@gjsify/model-store": "^0.64.28",
-        "@gjsify/path": "^0.64.28",
-        "@gjsify/process": "^0.64.28",
-        "@gjsify/zlib": "^0.64.28"
+        "@gjsify/buffer": "^0.64.30",
+        "@gjsify/fs": "^0.64.30",
+        "@gjsify/machine-fit": "^0.64.30",
+        "@gjsify/model-store": "^0.64.30",
+        "@gjsify/path": "^0.64.30",
+        "@gjsify/process": "^0.64.30",
+        "@gjsify/zlib": "^0.64.30"
     },
     "peerDependencies": {
         "@gjsify/napi": "^0.64.19"
@@ -63,8 +63,8 @@
         }
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.64.28",
-        "@gjsify/unit": "^0.64.28",
+        "@gjsify/cli": "^0.64.30",
+        "@gjsify/unit": "^0.64.30",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },