@goodandready/dsh-image-gen 0.10.23 → 0.10.25

package/lib/providers.js

@@ -1,239 +1,90 @@
 /**
  * Returns candidate API key names considering known aliases (e.g. FAL_API_KEY <-> FAL_KEY).
  */
-export function resolveApiKeyCandidates(ref) {
-  if (!ref) return []
-  const candidates = [ref]
-  if (ref === 'FAL_API_KEY') candidates.push('FAL_KEY')
-  else if (ref === 'FAL_KEY') candidates.push('FAL_API_KEY')
-  return candidates
-}
-
-
-export const PROVIDER_MAX_COUNTS = {
-  fal: 4,
-  replicate: 4,
-  custom: 10,
-  seedream: 10,
-  gemini: 4,
-  codex: 1,
-  grok: 1,
-  local: 4,
-}
-
-export function clampProviderCount(provider, count) {
-  const max = PROVIDER_MAX_COUNTS[provider] || 4
-  return normalizeCount(count, max)
-}
-
-export function buildEndpointUrl(baseURL, pathSuffix) {
-  const base = String(baseURL || '').trim().replace(/\/+$/, '')
-  const suffix = String(pathSuffix || '').trim().replace(/^\/+/, '')
-  return `${base}/${suffix}`
-}
-
-export function createAbortError(message = 'Image generation cancelled') {
-  const err = new Error(message)
-  err.name = 'AbortError'
-  return err
-}
-
-
-/** Fast Laplacian-like sharpness and entropy estimator across image scanlines. */
-export function estimateSharpnessAndVariance(bytes) {
-  const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes || [])
-  if (!buf || buf.length < 64) {
-    return { score: 0, passed: false, isBlank: true, reason: 'Empty or corrupt image buffer' }
-  }
-  let sum = 0
-  let diffSum = 0
-  const sampleStep = Math.max(1, Math.floor(buf.length / 4096))
-  let count = 0
-  for (let i = 8; i < buf.length - sampleStep; i += sampleStep) {
-    const v = buf[i]
-    const nextV = buf[i + sampleStep]
-    sum += v
-    diffSum += Math.abs(v - nextV)
-    count++
-  }
-  const avgDiff = count > 0 ? diffSum / count : 0
-  if (avgDiff < 2) {
-    return { score: 0.1, passed: false, isBlank: true, reason: 'Image appears blank or solid monochrome' }
-  }
-  const score = Math.min(0.98, Math.max(0.3, +(0.5 + (avgDiff / 255) * 0.5).toFixed(2)))
-  return { score, passed: score >= 0.5, isBlank: false, avgDiff: +avgDiff.toFixed(2) }
-}
-
-/** Adaptive color palette quantizer for SVG vectorization. */
-export function quantizePalette(colorMode = 'color', paletteSize = 16) {
-  if (colorMode === 'binary') return ['#000000', '#ffffff']
-  if (colorMode === 'grayscale') return ['#000000', '#444444', '#888888', '#cccccc', '#ffffff']
-  // Standard vibrant UI vector palette
-  return [
-    '#000000', '#ffffff', '#e11d48', '#2563eb',
-    '#16a34a', '#ca8a04', '#9333ea', '#0891b2',
-    '#475569', '#64748b', '#94a3b8', '#cbd5e1'
-  ].slice(0, Math.max(2, paletteSize))
-}
-
-
-/** Format parameters in standard Automatic1111 / ComfyUI text format for drag-and-drop support. */
-export function formatA1111Parameters(metadata = {}) {
-  if (typeof metadata === 'string') return metadata
-  const prompt = metadata.prompt || ''
-  const neg = metadata.negative_prompt || metadata.negativePrompt || ''
-  const seed = metadata.seed ?? ''
-  const size = metadata.size || (metadata.width && metadata.height ? `${metadata.width}x${metadata.height}` : '1024x1024')
-  const model = metadata.model || metadata.provider || ''
-  const steps = metadata.steps || 20
-  const cfg = metadata.cfg_scale || metadata.guidance_scale || 7
-
-  let out = prompt
-  if (neg) out += `\nNegative prompt: ${neg}`
-  out += `\nSteps: ${steps}, Sampler: Euler, CFG scale: ${cfg}, Seed: ${seed}, Size: ${size}, Model: ${model}`
-  return out
-}
-
-
-import { createHash } from 'node:crypto'
-
-/** Deterministic sha256 hash for image generation caching. */
-export function computeGenerationHash({ provider, model, prompt, seed, size, style }) {
-  const norm = [
-    String(provider || '').trim().toLowerCase(),
-    String(model || '').trim().toLowerCase(),
-    String(prompt || '').trim(),
-    String(seed ?? ''),
-    String(size || '').trim().toLowerCase(),
-    String(style || '').trim().toLowerCase(),
-  ].join('|')
-  return createHash('sha256').update(norm).digest('hex')
-}
-
-// Image generation provider implementations.
-//
-// A provider receives a generation job and returns finished image bytes. Everything
-// that follows (attachments, workspace files, links, card rendering) is shared
-// across all providers and lives in index.js.
-//
-// Network is injected via fetchImpl and keys via resolveKey, enabling fully isolated unit tests.
-
-export const PROVIDER_KEYS = ['fal', 'custom', 'codex', 'grok', 'local', 'seedream', 'gemini', 'replicate']
-
-/** Clamp count from tool arguments to range 1..4. */
-/** Provider fallback ordering: primary provider first, followed by PROVIDER_KEYS. */
-export function fallbackOrder(primary) {
-  return [primary, ...PROVIDER_KEYS.filter((k) => k !== primary)]
-}
-
-/**
- * Iterates through candidate generators, returning the first successful result.
- * Throws an aggregate error if all candidates fail.
- * @param generators - array of (key, seed) => Promise<generated> functions.
- * @param order - candidate key evaluation order.
- */
-
-/** Calculate exponential backoff delay with jitter. */
-export function calculateBackoff(attempt, baseInterval = 500, maxInterval = 5000, jitterFactor = 0.2) {
-  const exp = Math.min(maxInterval, baseInterval * Math.pow(1.3, attempt))
-  const jitter = exp * jitterFactor * (Math.random() * 2 - 1)
-  return Math.max(100, Math.floor(exp + jitter))
-}
-
-/** Check if an error is a fatal client error that should NOT be cascaded to other providers. */
-export function isFatalClientError(error) {
-  const msg = (error?.message || String(error || '')).toLowerCase()
-  return (
-    msg.includes('content policy') ||
-    msg.includes('safety system') ||
-    msg.includes('nsfw') ||
-    msg.includes('moderation') ||
-    msg.includes('bad request (http 400') ||
-    msg.includes('invalid_prompt') ||
-    msg.includes('prompt is required') ||
-    msg.includes('unsupported image format') ||
-    msg.includes('402 payment required') ||
-    msg.includes('insufficient_quota') ||
-    msg.includes('insufficient credits') ||
-    msg.includes('exceeded your current quota') ||
-    msg.includes('balance is insufficient')
-  )
-}
-
-/**
- * Safely extract a human-readable message from any error, object, or response.
- * Completely eliminates "[object Object]" and prevents duplicate provider prefixes (e.g. "codex: codex: ...").
- */
-export function formatErrorMessage(e, providerKey = '') {
-  if (e === null || e === undefined) {
-    return providerKey ? `${providerKey}: unknown error` : 'unknown error'
-  }
-
-  let msg = ''
-  if (typeof e === 'string') {
-    msg = e
-  } else if (typeof e === 'object') {
-    if (typeof e.message === 'string' && e.message && e.message !== '[object Object]') {
-      msg = e.message
-    } else if (typeof e.detail === 'string' && e.detail) {
-      msg = e.detail
-    } else if (e.error) {
-      if (typeof e.error === 'string') msg = e.error
-      else if (typeof e.error.message === 'string') msg = e.error.message
-      else if (typeof e.error.detail === 'string') msg = e.error.detail
-      else {
-        try { msg = JSON.stringify(e.error) } catch {}
-      }
-    } else if (typeof e.statusText === 'string' && e.statusText) {
-      msg = `HTTP ${e.status || ''} ${e.statusText}`.trim()
-    } else if (typeof e.cause === 'string') {
-      msg = e.cause
-    } else if (e.cause && typeof e.cause.message === 'string') {
-      msg = e.cause.message
-    }
 
-    if (!msg || msg === '[object Object]') {
-      try {
-        const json = JSON.stringify(e)
-        if (json && json !== '{}') {
-          msg = json.slice(0, 500)
-        }
-      } catch {}
-    }
-
-    if (!msg || msg === '[object Object]') {
-      const keys = Object.getOwnPropertyNames(e)
-      if (keys.length) {
-        msg = `error [${keys.join(', ')}]`
-      } else {
-        msg = String(e)
-      }
-    }
-  } else {
-    msg = String(e)
-  }
-
-  msg = String(msg || 'unknown error').trim()
-
-  if (providerKey) {
-    const prefixRegex = new RegExp(`^${providerKey}\\s*:\\s*`, 'i')
-    while (prefixRegex.test(msg)) {
-      msg = msg.replace(prefixRegex, '').trim()
-    }
-  }
-
-  if (!msg || msg === '[object Object]') {
-    msg = 'unknown error object'
-  } else if (msg.includes('[object Object]')) {
-    msg = msg.replace(/\[object Object\]/g, 'unknown error object').trim()
-  }
-
-  if (providerKey) {
-    return `${providerKey}: ${msg}`
-  }
-
-  return msg
-}
+// Utilities and constants extracted to provider-utils.js (#239)
+import {
+  resolveApiKeyCandidates,
+  PROVIDER_MAX_COUNTS,
+  clampProviderCount,
+  buildEndpointUrl,
+  createAbortError,
+  estimateSharpnessAndVariance,
+  quantizePalette,
+  formatA1111Parameters,
+  computeGenerationHash,
+  PROVIDER_KEYS,
+  fallbackOrder,
+  calculateBackoff,
+  isFatalClientError,
+  formatErrorMessage,
+  resolveSubscriptionSize,
+  SUBSCRIPTION_SIZES,
+  IMAGE_SIZES,
+  OUTPUT_FORMATS,
+  SIZE_PIXELS,
+  normalizeCount,
+} from './provider-utils.js'
+
+// Per-backend factories (#218)
+import { createFalGenerator } from './providers/backends/fal.js'
+import { createCustomGenerator } from './providers/backends/custom.js'
+import { createSubscriptionGenerator } from './providers/backends/subscription.js'
+import { createLocalGenerator } from './providers/backends/local.js'
+import { createSeedreamGenerator } from './providers/backends/seedream.js'
+import { createGeminiGenerator } from './providers/backends/gemini.js'
+import { createReplicateGenerator } from './providers/backends/replicate.js'
+export {
+  falAuthHeader,
+  normalizeMediaType,
+  submitJob,
+  pollStatus,
+  buildEditForm,
+  estimateCost,
+  pxSize,
+  ASPECT_RATIOS,
+  sizeToPixels,
+  snapToMultipleOf64,
+  snapDimensions,
+  extractComfyNodeErrors,
+} from './providers/shared-helpers.js'
+
+import {
+  falAuthHeader,
+  normalizeMediaType,
+  submitJob,
+  pollStatus,
+  buildEditForm,
+  estimateCost,
+  pxSize,
+  snapToMultipleOf64,
+  snapDimensions,
+  extractComfyNodeErrors,
+} from './providers/shared-helpers.js'
+
+// Re-export utilities so existing imports from './providers.js' continue to work
+export {
+  resolveApiKeyCandidates,
+  PROVIDER_MAX_COUNTS,
+  clampProviderCount,
+  buildEndpointUrl,
+  createAbortError,
+  estimateSharpnessAndVariance,
+  quantizePalette,
+  formatA1111Parameters,
+  computeGenerationHash,
+  PROVIDER_KEYS,
+  fallbackOrder,
+  calculateBackoff,
+  isFatalClientError,
+  formatErrorMessage,
+  resolveSubscriptionSize,
+  SUBSCRIPTION_SIZES,
+  IMAGE_SIZES,
+  OUTPUT_FORMATS,
+  SIZE_PIXELS,
+  normalizeCount,
+} from './provider-utils.js'
 
 export async function tryGenerate(generators, order, seed, promptArg) {
   const refusals = []
@@ -251,11 +102,6 @@ export async function tryGenerate(generators, order, seed, promptArg) {
   throw new Error(`Image generation failed on all providers. ${refusals.join('; ')}`)
 }
 
-export function normalizeCount(count, max = 4) {
-  const n = Math.floor(Number(count))
-  if (!Number.isFinite(n)) return 1
-  return Math.max(1, Math.min(max, n))
-}
 
 // Subscription services use their own aspect ratio taxonomy.
 // Normalize named sizes to standard square, landscape, and portrait equivalents.
@@ -264,82 +110,7 @@ export function normalizeCount(count, max = 4) {
  * Supports named sizes (landscape_16_9, etc.), aspect ratios (16:9, 3:2, 9:16),
  * and pixel dimensions [width, height], preserving requested proportions.
  */
-export function resolveSubscriptionSize(size, aspectPixels, aspectRatio) {
-  if (size && SUBSCRIPTION_SIZES[size]) {
-    return SUBSCRIPTION_SIZES[size]
-  }
-  const ratio = String(aspectRatio || '').trim()
-  if (ratio === '16:9' || ratio === '3:2' || ratio === '4:3') {
-    return '1536x1024'
-  }
-  if (ratio === '9:16' || ratio === '2:3' || ratio === '3:4') {
-    return '1024x1536'
-  }
-  if (ratio === '1:1') {
-    return '1024x1024'
-  }
-  if (Array.isArray(aspectPixels) && aspectPixels.length === 2) {
-    const [w, h] = aspectPixels
-    if (w > h) return '1536x1024'
-    if (h > w) return '1024x1536'
-    return '1024x1024'
-  }
-  return '1024x1024'
-}
-
-export const SUBSCRIPTION_SIZES = {
-  square_hd: '1024x1024',
-  square: '1024x1024',
-  portrait_4_3: '1024x1536',
-  portrait_16_9: '1024x1536',
-  landscape_4_3: '1536x1024',
-  landscape_16_9: '1536x1024',
-}
-
-/** Image sizes accepted by fal-ai/flux-2/klein (and most FAL flux models). */
-export const IMAGE_SIZES = [
-  'square_hd',
-  'square',
-  'portrait_4_3',
-  'portrait_16_9',
-  'landscape_4_3',
-  'landscape_16_9',
-]
-
-/** Output formats accepted by the model. */
-export const OUTPUT_FORMATS = ['png', 'jpeg', 'webp']
-
-// Named sizes are a unified abstraction across all providers.
-// FAL accepts named identifiers; OpenAI-compatible gateways require WxH resolution.
-export const SIZE_PIXELS = {
-  square_hd: '1024x1024',
-  square: '512x512',
-  portrait_4_3: '768x1024',
-  portrait_16_9: '576x1024',
-  landscape_4_3: '1024x768',
-  landscape_16_9: '1024x576',
-}
-
-/** Normalize a raw key into a FAL `Authorization: Key <key>` value. */
-export function falAuthHeader(key) {
-  const trimmed = String(key ?? '').trim()
-  if (!trimmed) return ''
-  return trimmed.startsWith('Key ') || trimmed.startsWith('key ')
-    ? trimmed
-    : `Key ${trimmed}`
-}
-
 /** Map a content type onto the attachment service's supported set. */
-export function normalizeMediaType(contentType, fallbackFormat) {
-  const raw = String(contentType ?? '').toLowerCase()
-  if (raw.includes('jpeg') || raw.includes('jpg')) return 'image/jpeg'
-  if (raw.includes('webp')) return 'image/webp'
-  if (raw.includes('png')) return 'image/png'
-  if (fallbackFormat === 'jpeg') return 'image/jpeg'
-  if (fallbackFormat === 'webp') return 'image/webp'
-  return 'image/png'
-}
-
 /** Generation metadata written to companion sidecar file. */
 export function buildSidecar({
   prompt, size, format, seed, provider, deliverAs,
@@ -349,58 +120,7 @@ export function buildSidecar({
 }
 
 /** Submit a generation job to the FAL queue. */
-export async function submitJob(fetchImpl, baseURL, model, key, body, signal) {
-  const res = await fetchImpl(`${baseURL}/${model}`, {
-    method: 'POST',
-    headers: {
-      Authorization: falAuthHeader(key),
-      'Content-Type': 'application/json',
-    },
-    body: JSON.stringify(body),
-    signal,
-  })
-  const data = await res.json().catch(() => ({}))
-  if (!res.ok || !data.request_id) {
-    const detail = typeof data.detail === 'string' ? data.detail : JSON.stringify(data).slice(0, 600)
-    throw new Error(`FAL submit failed (HTTP ${res.status}): ${detail}`)
-  }
-  return data
-}
-
 /** Poll the FAL status endpoint until completion, failure, timeout, or abort. */
-export async function pollStatus(fetchImpl, statusUrl, key, signal, pollIntervalMs = 500, timeoutMs = 180000) {
-  const deadline = Date.now() + timeoutMs
-  let attempt = 0
-  for (;;) {
-    if (signal?.aborted) throw new Error('FAL generation cancelled')
-    if (Date.now() > deadline) throw new Error(`FAL generation timed out after ${timeoutMs} ms`)
-    if (attempt > 0) {
-      const delay = calculateBackoff(attempt - 1, pollIntervalMs, 5000)
-      await new Promise((resolve) => {
-        const timer = setTimeout(resolve, delay)
-        if (signal) {
-          signal.addEventListener('abort', () => {
-            clearTimeout(timer)
-            resolve()
-          }, { once: true })
-        }
-      })
-    }
-    attempt++
-    if (signal?.aborted) throw new Error('FAL generation cancelled')
-    const res = await fetchImpl(statusUrl, { headers: { Authorization: falAuthHeader(key) }, signal })
-    const data = await res.json().catch(() => ({}))
-    const status = data.status
-    if (status === 'COMPLETED') return data
-    if (status === 'ERROR' || data.error || data.detail) {
-      throw new Error(`FAL generation failed: ${JSON.stringify(data).slice(0, 600)}`)
-    }
-    if (status !== 'IN_QUEUE' && status !== 'IN_PROGRESS') {
-      throw new Error(`Unexpected FAL status "${status}": ${JSON.stringify(data).slice(0, 300)}`)
-    }
-  }
-}
-
 /**
  * @param deps {{fetchImpl: Function, resolveKey: (ref: string) => Promise<string>, cfg: object}}
  * @param job {{prompt: string, size: string, format: string, seed: number|undefined, signal: AbortSignal}}
@@ -411,51 +131,11 @@ export async function pollStatus(fetchImpl, statusUrl, key, signal, pollInterval
 
 /** Named size -> [width, height] for local APIs. */
 /** Aspect ratio -> [width, height] (pixels, normalized to 1024 base). */
-export const ASPECT_RATIOS = {
-  '1:1': [1024, 1024],
-  '16:9': [1344, 768],
-  '9:16': [768, 1344],
-  '4:3': [1152, 896],
-  '3:4': [896, 1152],
-  '3:2': [1152, 768],
-  '2:3': [768, 1152],
-}
-
 /** Pixel dimensions: aspectPixels (if specified) or mapped from named size. */
 /** Snap a pixel dimension to nearest multiple of 64. */
-export function snapToMultipleOf64(dim, minVal = 256, maxVal = 2048) {
-  const n = Math.round(Number(dim) / 64) * 64
-  return Math.max(minVal, Math.min(maxVal, n))
-}
 
-export function snapDimensions(width, height) {
-  return [snapToMultipleOf64(width), snapToMultipleOf64(height)]
-}
-
-export function pxSize(aspectPixels, size) {
-  if (aspectPixels) return snapDimensions(aspectPixels[0], aspectPixels[1])
-  const [w, h] = sizeToPixels(size)
-  return snapDimensions(w, h)
-}
-
-export function sizeToPixels(size) {
-  const px = SIZE_PIXELS[size]
-  if (!px) return [1024, 1024]
-  const [w, h] = px.split('x').map(Number)
-  return [w, h]
-}
 
 /** Assemble multipart body for /images/edits (OpenAI-compatible edit). */
-export function buildEditForm({ source, mask, prompt, size, strength }) {
-  const form = new FormData()
-  form.append('image', new Blob([source.bytes], { type: source.mediaType || 'image/png' }), 'source.png')
-  if (mask) form.append('mask', new Blob([mask.bytes], { type: mask.mediaType || 'image/png' }), 'mask.png')
-  form.append('prompt', prompt)
-  if (size) form.append('size', size)
-  if (strength !== undefined) form.append('strength', String(strength))
-  return form
-}
-
 /** Compare two images: ratio of differing pixels (0..1). */
 export async function pixelDiff(a, b) {
   if (!a || !b) return { error: 'missing image' }
@@ -503,438 +183,19 @@ export async function saveAttachmentSafe(ctx, { bytes, mediaType, name }) {
   }
 }
 
-export function extractComfyNodeErrors(entry) {
-  if (!entry || typeof entry !== 'object') return ''
-  const status = entry.status
-  if (status && status.status_str === 'error') {
-    const msgs = status.messages || []
-    const errList = []
-    for (const m of msgs) {
-      if (Array.isArray(m) && m[0] === 'execution_error') {
-        const d = m[1] || {}
-        errList.push(`node ${d.node_id || 'unknown'} (${d.node_type || ''}): ${d.exception_message || d.exception_type || 'execution failed'}`)
-      }
-    }
-    if (errList.length) return errList.join('; ')
-    return status.status_str || 'execution error'
-  }
-  return ''
-}
 
 export function makeProviders(deps, job) {
-  const { fetchImpl, resolveKey, cfg } = deps
-  const { prompt, size, format, seed, signal, negativePrompt, guidanceScale, source, mask, strength, quality, style, aspectPixels, aspectRatio } = job
-
-  async function fal(seedArg = seed, promptArg = prompt) {
-    const key = await resolveKey(cfg.apiKeyEnv)
-    const isEdit = Boolean(source && source.bytes)
-    const targetModel = isEdit
-      ? (mask && mask.bytes ? 'fal-ai/flux-pro/v1/inpaint' : 'fal-ai/flux/dev/image-to-image')
-      : cfg.model
-    const body = { prompt: promptArg, image_size: size, num_images: 1 }
-    if (seedArg !== undefined) body.seed = seedArg
-    if (negativePrompt !== undefined) body.negative_prompt = negativePrompt
-    if (guidanceScale !== undefined) body.guidance_scale = guidanceScale
-    if (format !== 'png') body.output_format = format
-    if (isEdit) {
-      body.image_url = `data:${source.mediaType || 'image/png'};base64,${Buffer.from(source.bytes).toString('base64')}`
-      if (mask && mask.bytes) {
-        body.mask_url = `data:${mask.mediaType || 'image/png'};base64,${Buffer.from(mask.bytes).toString('base64')}`
-      }
-      if (strength !== undefined) {
-        body.strength = strength
-      }
-    }
-
-    const submit = await submitJob(fetchImpl, cfg.baseURL, targetModel, key, body, signal)
-    const statusUrl = submit.status_url || `${cfg.baseURL}/${cfg.model}/requests/${submit.request_id}/status`
-    const statusBody = await pollStatus(fetchImpl, statusUrl, key, signal, cfg.pollIntervalMs, cfg.timeoutMs)
-
-    const resultRes = await fetchImpl(statusBody.response_url, {
-      headers: { Authorization: falAuthHeader(key) },
-      signal,
-    })
-    const result = await resultRes.json().catch(() => ({}))
-    const image = result.images && result.images[0]
-    if (!image || !image.url) {
-      throw new Error(`FAL returned no images: ${JSON.stringify(result).slice(0, 600)}`)
-    }
-    const download = await fetchImpl(image.url, { signal })
-    if (!download.ok) {
-      throw new Error(`Failed to download generated image (HTTP ${download.status})`)
-    }
-    return {
-      bytes: Buffer.from(await download.arrayBuffer()),
-      mediaType: normalizeMediaType(image.content_type, format),
-      width: image.width ?? 0,
-      height: image.height ?? 0,
-      seed: result.seed ?? seedArg ?? 0,
-      sourceUrl: image.url,
-      cost: result.cost,
-    }
-  }
-
-  // OpenAI-compatible image API. Single HTTP request instead of queue polling.
-  async function custom(seedArg = seed, promptArg = prompt) {
-    const base = String(cfg.customBaseURL || '').replace(/\/+$/, '')
-    if (!base) throw new Error('Custom image provider: base URL is not configured (Settings → Image generation)')
-    if (!cfg.customModel) throw new Error('Custom image provider: model is not configured')
-
-    // Empty key reference indicates unauthenticated gateway.
-    const key = cfg.customKeyEnv ? await resolveKey(cfg.customKeyEnv) : ''
-    const headers = { 'Content-Type': 'application/json' }
-    if (key) headers.Authorization = `Bearer ${key}`
-
-    // Omit response_format; modern models return either base64 or URL.
-    const endpoint = buildEndpointUrl(base, source ? 'images/edits' : 'images/generations')
-    const res = await fetchImpl(endpoint, {
-      method: 'POST',
-      headers,
-      body: source
-        ? buildEditForm({ source, mask, prompt: promptArg, size: cfg.customSize || (aspectPixels ? aspectPixels.join('x') : SIZE_PIXELS[size]) || size, strength })
-        : JSON.stringify({
-            model: cfg.customModel,
-            prompt: promptArg,
-            n: 1,
-            size: cfg.customSize || (aspectPixels ? aspectPixels.join('x') : SIZE_PIXELS[size]) || size,
-            ...(negativePrompt !== undefined ? { negative_prompt: negativePrompt } : {}),
-            ...(guidanceScale !== undefined ? { guidance_scale: guidanceScale } : {}),
-            ...(quality && quality !== 'auto' ? { quality } : {}),
-          }),
-      signal,
-    })
-    const data = await res.json().catch(() => ({}))
-    if (!res.ok) {
-      if (res.status === 503) {
-        const msg = (data?.error?.message || JSON.stringify(data)).toLowerCase()
-        if (msg.includes('no available channel') || msg.includes('model_not_found')) {
-          throw new Error(`Custom image API has no provisioned channel for "${cfg.customModel}" (HTTP 503); check gateway channel and routing configuration`)
-        }
-      }
-      const detail = formatErrorMessage(data?.error || data)
-      throw new Error(`Image API failed (HTTP ${res.status}): ${detail}`)
-    }
-    const item = data?.data?.[0]
-    if (!item) {
-      throw new Error(`Image API returned no images: ${JSON.stringify(data).slice(0, 600)}`)
-    }
-
-    if (item.b64_json) {
-      return {
-        bytes: Buffer.from(item.b64_json, 'base64'),
-        mediaType: normalizeMediaType(data.output_format || '', format),
-        width: 0,
-        height: 0,
-        seed: seedArg ?? 0,
-        sourceUrl: '',
-      }
-    }
-    if (!item.url) {
-      throw new Error(`Image API returned neither b64_json nor url: ${JSON.stringify(item).slice(0, 300)}`)
-    }
-    const download = await fetchImpl(item.url, { signal })
-    if (!download.ok) {
-      throw new Error(`Failed to download generated image (HTTP ${download.status})`)
-    }
-    const contentType = download.headers && typeof download.headers.get === 'function'
-      ? download.headers.get('content-type')
-      : ''
-    return {
-      bytes: Buffer.from(await download.arrayBuffer()),
-      mediaType: normalizeMediaType(contentType, format),
-      width: 0,
-      height: 0,
-      seed: seedArg ?? 0,
-      sourceUrl: item.url,
-    }
-  }
-
-  // Subscription generation: dsh-subscriptions handles session authentication.
-  function subscription(provider) {
-    return async function generate(seedArg = seed, promptArg = prompt) {
-      if (source) {
-        return { ok: false, provider, reason: `${provider}: does not support image editing — use fal, custom, or local` }
-      }
-      const images = deps.subscriptionImages
-      if (!images || typeof images.generate !== 'function') {
-        return {
-          ok: false,
-          provider,
-          reason: `${provider}: requires dsh-subscriptions plugin to manage session authentication`,
-        }
-      }
-      let produced
-      try {
-        produced = await images.generate({
-          provider,
-          prompt: promptArg,
-          size: resolveSubscriptionSize(size, aspectPixels, aspectRatio),
-          quality: cfg.subscriptionQuality || undefined,
-          signal,
-        })
-      } catch (e) {
-        return { ok: false, provider, reason: formatErrorMessage(e, provider) }
-      }
-      const first = Array.isArray(produced) ? produced[0] : null
-      if (!first || !first.b64_json) {
-        return { ok: false, provider, reason: `${provider}: no image returned in response` }
-      }
-      return {
-        bytes: Buffer.from(first.b64_json, 'base64'),
-        // Subscription outputs default to PNG media type.
-        mediaType: 'image/png',
-        width: 0,
-        height: 0,
-        seed: seedArg ?? 0,
-        sourceUrl: '',
-        revisedPrompt: first.revisedPrompt || '',
-      }
-    }
-  }
-
-  // Local generation: ComfyUI (queue + poll) or Automatic1111 (txt2img).
-  async function local(seedArg = seed, promptArg = prompt) {
-    const base = String(cfg.localBaseURL || '').replace(/\/+$/, '')
-    if (!base) throw new Error('Local image provider: server address is not configured (Settings → Image generation)')
-    const [width, height] = pxSize(aspectPixels, size)
-    const kind = cfg.localKind === 'a1111' ? 'a1111' : 'comfyui'
-
-    if (kind === 'a1111') {
-      const isImg2Img = Boolean(source && source.bytes)
-      const endpoint = `${base}${isImg2Img ? '/sdapi/v1/img2img' : '/sdapi/v1/txt2img'}`
-      const body = {
-        prompt: promptArg,
-        negative_prompt: negativePrompt,
-        width,
-        height,
-        steps: cfg.localSteps ?? 20,
-        cfg_scale: cfg.localCfg ?? 7,
-        seed: seedArg ?? -1,
-      }
-      if (isImg2Img) {
-        body.init_images = [Buffer.from(source.bytes).toString('base64')]
-        body.denoising_strength = strength ?? (mask ? 0.75 : 0.35)
-        if (mask && mask.bytes) {
-          body.mask = Buffer.from(mask.bytes).toString('base64')
-        }
-      }
-      if (cfg.localModel) body.override_settings = { sd_model_checkpoint: cfg.localModel }
-      const res = await fetchImpl(endpoint, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(body),
-        signal,
-      })
-      if (!res.ok) {
-        throw new Error(`Local A1111 failed (HTTP ${res.status}): ${String(await res.text().catch(() => '')).slice(0, 300)}`)
-      }
-      const data = await res.json().catch(() => ({}))
-      const b64 = data.images && data.images[0]
-      if (!b64) throw new Error('Local A1111 returned no images')
-      return {
-        bytes: Buffer.from(b64, 'base64'),
-        mediaType: normalizeMediaType('image/png', format),
-        width,
-        height,
-        seed: seedArg ?? 0,
-        sourceUrl: '',
-      }
-    }
-
-    // ComfyUI: submit via /prompt, poll /history/{prompt_id} until completed.
-    const promptId = `dsh-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`
-    const workflow = {
-      prompt: {
-        '3': { class_type: 'KSampler', inputs: { seed: seedArg ?? 0, steps: cfg.localSteps ?? 20, cfg: cfg.localCfg ?? 7, sampler_name: 'euler', scheduler: 'normal', denoise: 1, model: ['4', 0], positive: ['6', 0], negative: ['7', 0], latent_image: ['5', 0] } },
-        '4': { class_type: 'CheckpointLoaderSimple', inputs: { ckpt_name: cfg.localModel || 'v1-5-pruned-emaonly.safetensors' } },
-        '5': { class_type: 'EmptyLatentImage', inputs: { width, height, batch_size: 1 } },
-        '6': { class_type: 'CLIPTextEncode', inputs: { text: promptArg, clip: ['4', 1] } },
-        '7': { class_type: 'CLIPTextEncode', inputs: { text: negativePrompt || '', clip: ['4', 1] } },
-        '8': { class_type: 'VAEDecode', inputs: { samples: ['3', 0], vae: ['4', 2] } },
-        '9': { class_type: 'SaveImage', inputs: { filename_prefix: 'dsh', images: ['8', 0] } },
-      },
-    }
-    const submit = await fetchImpl(`${base}/prompt`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ prompt: workflow, client_id: promptId }),
-      signal,
-    })
-    if (!submit.ok) {
-      throw new Error(`Local ComfyUI submit failed (HTTP ${submit.status}): ${String(await submit.text().catch(() => '')).slice(0, 300)}`)
-    }
-    const submitData = await submit.json().catch(() => ({}))
-    const pid = submitData.prompt_id
-    if (!pid) throw new Error('Local ComfyUI did not return a prompt_id')
-
-    const deadline = Date.now() + cfg.timeoutMs
-    let attempt = 0
-    for (;;) {
-      if (signal?.aborted) throw new Error('Local ComfyUI generation cancelled')
-      if (Date.now() > deadline) throw new Error(`Local ComfyUI timed out after ${cfg.timeoutMs} ms`)
-      if (attempt > 0) {
-        const cDelay = calculateBackoff(attempt - 1, cfg.pollIntervalMs || 1000, 5000)
-        await new Promise((resolve) => {
-          const timer = setTimeout(resolve, cDelay)
-          if (signal) {
-            signal.addEventListener('abort', () => { clearTimeout(timer); resolve() }, { once: true })
-          }
-        })
-      }
-      attempt++
-      const hist = await fetchImpl(`${base}/history/${pid}`, { signal })
-      if (!hist.ok) continue
-      const histData = await hist.json().catch(() => ({}))
-      const entry = histData[pid]
-      if (entry) {
-        const comfyErr = extractComfyNodeErrors(entry)
-        if (comfyErr) {
-          throw new Error(`Local ComfyUI execution failed: ${comfyErr}`)
-        }
-      }
-      if (entry && entry.outputs) {
-        const outputs = entry.outputs
-        const img = Object.values(outputs).flatMap((o) => o.images || []).find((i) => i && i.filename)
-        if (img) {
-          const dl = await fetchImpl(`${base}/view?filename=${encodeURIComponent(img.filename)}&subfolder=${encodeURIComponent(img.subfolder || '')}&type=${encodeURIComponent(img.type || 'output')}`, { signal })
-          if (!dl.ok) throw new Error(`Local ComfyUI download failed (HTTP ${dl.status})`)
-          return {
-            bytes: Buffer.from(await dl.arrayBuffer()),
-            mediaType: normalizeMediaType('image/png', format),
-            width,
-            height,
-            seed: seedArg ?? 0,
-            sourceUrl: '',
-          }
-        }
-      }
-    }
-  }
-
-  // Seedream (ByteDance): OpenAI-compatible images API.
-  async function seedream(seedArg = seed, promptArg = prompt) {
-    const key = await resolveKey(cfg.seedreamKeyEnv)
-    const base = (cfg.seedreamBaseURL || 'https://api.bytedanceapi.com/v1').replace(/\/+$/, '')
-    const res = await fetchImpl(`${base}/images/generations`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${key}` },
-      body: JSON.stringify({
-        model: cfg.seedreamModel || 'seedream-4.0',
-        prompt: promptArg,
-        n: 1,
-        size: (aspectPixels ? aspectPixels.join('x') : SIZE_PIXELS[size]) || size,
-        ...(negativePrompt !== undefined ? { negative_prompt: negativePrompt } : {}),
-        ...(quality !== undefined ? { quality } : {}),
-        ...(style !== undefined ? { style } : {}),
-      }),
-      signal,
-    })
-    const data = await res.json().catch(() => ({}))
-    if (!res.ok) {
-      const detail = data?.error?.message || JSON.stringify(data).slice(0, 600)
-      throw new Error(`Seedream failed (HTTP ${res.status}): ${detail}`)
-    }
-    const item = data?.data?.[0]
-    if (!item) throw new Error('Seedream returned no images')
-    if (item.b64_json) {
-      return { bytes: Buffer.from(item.b64_json, 'base64'), mediaType: normalizeMediaType('image/png', format), width: 0, height: 0, seed: seedArg ?? 0, sourceUrl: '' }
-    }
-    if (!item.url) throw new Error('Seedream returned neither b64_json nor url')
-    const dl = await fetchImpl(item.url, { signal })
-    if (!dl.ok) throw new Error(`Seedream download failed (HTTP ${dl.status})`)
-    return { bytes: Buffer.from(await dl.arrayBuffer()), mediaType: normalizeMediaType('image/png', format), width: 0, height: 0, seed: seedArg ?? 0, sourceUrl: item.url }
-  }
-
-  // Gemini (Google): generateContent / imagen via GenAI API.
-  async function gemini(seedArg = seed, promptArg = prompt) {
-    const key = await resolveKey(cfg.geminiKeyEnv)
-    const model = cfg.geminiModel || 'gemini-2.0-flash-exp-image-generation'
-    const res = await fetchImpl(`https://generativelanguage.googleapis.com/v1beta/models/${model}:generateContent?key=${encodeURIComponent(key)}`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        contents: [{ parts: [{ text: promptArg }] }],
-        generationConfig: { responseModalities: ['IMAGE'], ...(quality !== undefined ? { imageConfig: { imageQuality: quality } } : {}), ...(style !== undefined ? { imageConfig: { imageStyle: style } } : {}) },
-      }),
-      signal,
-    })
-    const data = await res.json().catch(() => ({}))
-    if (!res.ok) {
-      const detail = data?.error?.message || JSON.stringify(data).slice(0, 600)
-      throw new Error(`Gemini failed (HTTP ${res.status}): ${detail}`)
-    }
-    const part = data?.candidates?.[0]?.content?.parts?.find((p) => p.inlineData?.data)
-    if (!part) throw new Error('Gemini returned no image')
-    return { bytes: Buffer.from(part.inlineData.data, 'base64'), mediaType: normalizeMediaType(part.inlineData.mimeType || 'image/png', format), width: 0, height: 0, seed: seedArg ?? 0, sourceUrl: '' }
-  }
-
-
-  // Replicate provider: API submit & polling
-  async function replicate(seedArg = seed, promptArg = prompt) {
-    const key = await resolveKey(cfg.replicateKeyEnv || 'REPLICATE_API_TOKEN')
-    if (!key) throw new Error('Replicate API token is not configured (Settings → Image generation → replicateKeyEnv)')
-    const model = cfg.replicateModel || 'black-forest-labs/flux-schnell'
-    const [width, height] = pxSize(aspectPixels, size)
-    const body = {
-      input: {
-        prompt: promptArg,
-        aspect_ratio: aspectPixels ? `${aspectPixels[0]}:${aspectPixels[1]}` : (ASPECT_RATIOS[size] || '1:1'),
-        seed: seedArg,
-        ...(negativePrompt ? { negative_prompt: negativePrompt } : {}),
-        ...(source && source.bytes ? {
-          image: `data:${source.mediaType || 'image/png'};base64,${Buffer.from(source.bytes).toString('base64')}`,
-          ...(mask && mask.bytes ? { mask: `data:${mask.mediaType || 'image/png'};base64,${Buffer.from(mask.bytes).toString('base64')}` } : {}),
-          ...(strength !== undefined ? { prompt_strength: strength } : {}),
-        } : {}),
-      },
-    }
-    const res = await fetchImpl(`https://api.replicate.com/v1/models/${model}/predictions`, {
-      method: 'POST',
-      headers: {
-        Authorization: `Bearer ${key}`,
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify(body),
-      signal,
-    })
-    const data = await res.json().catch(() => ({}))
-    if (!res.ok) {
-      throw new Error(`Replicate submit failed (HTTP ${res.status}): ${data.detail || JSON.stringify(data).slice(0, 300)}`)
-    }
-    let pred = data
-    if (pred.status !== 'succeeded') {
-      const pollUrl = pred.urls?.get || `https://api.replicate.com/v1/predictions/${pred.id}`
-      const deadline = Date.now() + (cfg.timeoutMs || 180000)
-      let attempt = 0
-    while (pred.status !== 'succeeded') {
-        if (signal?.aborted) throw new Error('Replicate generation cancelled')
-        if (Date.now() > deadline) throw new Error('Replicate generation timed out')
-        if (pred.status === 'failed' || pred.status === 'canceled') {
-          throw new Error(`Replicate failed: ${pred.error || 'unknown error'}`)
-        }
-        const repDelay = calculateBackoff(attempt++, cfg.pollIntervalMs || 1000, 5000)
-        await new Promise((r) => setTimeout(r, repDelay))
-        const pRes = await fetchImpl(pollUrl, { headers: { Authorization: `Bearer ${key}` }, signal })
-        pred = await pRes.json().catch(() => ({}))
-      }
-    }
-    const output = Array.isArray(pred.output) ? pred.output[0] : pred.output
-    if (!output) throw new Error('Replicate returned no image output')
-    const dl = await fetchImpl(output, { signal })
-    if (!dl.ok) throw new Error(`Replicate download failed (HTTP ${dl.status})`)
-    const bytes = Buffer.from(await dl.arrayBuffer())
-    return {
-      bytes,
-      mediaType: normalizeMediaType(dl.headers?.get?.('content-type') || 'image/png', format),
-      width,
-      height,
-      seed: seedArg ?? 0,
-      cost: estimateCost('replicate', model),
-      sourceUrl: output,
-    }
+  const subscription = createSubscriptionGenerator(deps, job)
+  return {
+    fal: createFalGenerator(deps, job),
+    custom: createCustomGenerator(deps, job),
+    codex: subscription('codex'),
+    grok: subscription('grok'),
+    local: createLocalGenerator(deps, job),
+    seedream: createSeedreamGenerator(deps, job),
+    gemini: createGeminiGenerator(deps, job),
+    replicate: createReplicateGenerator(deps, job),
   }
-
-  return { fal, custom, codex: subscription('codex'), grok: subscription('grok'), local, seedream, gemini, replicate }
 }
 
 
@@ -1039,21 +300,6 @@ export function traceToSvg(imageBytes, { colorMode = 'color', paletteSize = 16,
 }
 
 
-export function estimateCost(provider, model, { count = 1 } = {}) {
-  const p = String(provider).toLowerCase()
-  if (p === 'fal') {
-    if (String(model).includes('schnell') || String(model).includes('klein')) return 0.003 * count
-    if (String(model).includes('dev')) return 0.025 * count
-    if (String(model).includes('clarity') || String(model).includes('upscale')) return 0.01 * count
-    return 0.005 * count
-  }
-  if (p === 'replicate') return 0.003 * count
-  if (p === 'seedream') return 0.004 * count
-  if (p === 'gemini') return 0.03 * count
-  if (p === 'codex' || p === 'grok' || p === 'local') return 0.0
-  return 0.01 * count
-}
-
 
 export const STYLE_PRESETS = {
   cinematic: {
@@ -1143,6 +389,7 @@ export async function blendImagesFal({ fetchImpl, resolveKey, cfg }, { images, w
 }
 
 /** Direct image editing (inpainting / img2img) via selected provider. */
+/** @internal — direct provider call path for integration tests */
 export async function editImageDirect(deps, job) {
   const providers = makeProviders(deps, job)
   const providerKey = job.provider || deps.cfg.defaultProvider || 'fal'
@@ -1152,6 +399,7 @@ export async function editImageDirect(deps, job) {
 }
 
 /** Direct image variation via selected provider. */
+/** @internal — direct provider call path for integration tests */
 export async function varyImageDirect(deps, job) {
   const providers = makeProviders(deps, {
     ...job,