@goodandready/dsh-image-gen 0.10.22 → 0.10.24

package/lib/cost-meter.js

@@ -4,6 +4,7 @@
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { readFileSync, writeFileSync, mkdirSync } from 'node:fs'
+import { enforceSecurePermissions } from './security.js'
 
 /**
  * Standard pricing table per provider and resolution (USD per generation).
@@ -87,7 +88,7 @@ export function loadDailySpend() {
     if (data && data.date === today) {
       return data
     }
-  } catch {}
+  } catch { /* spend file unreadable; return zero */ }
   return { date: today, totalSpendUsd: 0, generations: 0 }
 }
 
@@ -107,6 +108,7 @@ export function recordSpend(usdAmount, { ctx, meta = {} } = {}) {
   try {
     mkdirSync(join(filePath, '..'), { recursive: true })
     writeFileSync(filePath, JSON.stringify(current, null, 2), 'utf8')
+    enforceSecurePermissions(filePath)
   } catch (err) {
     // Non-fatal write failure
   }
@@ -122,7 +124,7 @@ export function recordSpend(usdAmount, { ctx, meta = {} } = {}) {
         meta,
       })
     }
-  } catch {}
+  } catch { /* cost-meter service unavailable */ }
 
   return current
 }

package/lib/generation-cache.js

@@ -4,6 +4,7 @@
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { existsSync, mkdirSync, readFileSync, writeFileSync, statSync, unlinkSync, readdirSync } from 'node:fs'
+import { enforceSecurePermissions } from './security.js'
 
 const DEFAULT_CACHE_MAX_BYTES = 500 * 1024 * 1024 // 500 MB
 
@@ -107,6 +108,8 @@ export function setCachedGeneration(hash, { bytes, mediaType = 'image/png', widt
     writeFileSync(metaPath, JSON.stringify(cacheMeta, null, 2), 'utf8')
     const binBuf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes)
     writeFileSync(dataPath, binBuf)
+    enforceSecurePermissions(metaPath)
+    enforceSecurePermissions(dataPath)
 
     setToL1(hash, {
       bytes: binBuf,
@@ -151,7 +154,7 @@ export function pruneCacheToLimit(maxBytes = DEFAULT_CACHE_MAX_BYTES) {
           size,
           lastAccessed: meta.lastAccessed || meta.createdAt || 0,
         })
-      } catch {}
+      } catch { /* entry meta unreadable; skip */ }
     }
 
     if (totalSize <= maxBytes) return
@@ -165,7 +168,7 @@ export function pruneCacheToLimit(maxBytes = DEFAULT_CACHE_MAX_BYTES) {
         if (existsSync(entry.metaPath)) unlinkSync(entry.metaPath)
         if (existsSync(entry.dataPath)) unlinkSync(entry.dataPath)
         totalSize -= entry.size
-      } catch {}
+      } catch { /* entry unlink failed; skip */ }
     }
-  } catch {}
+  } catch { /* cache dir unreadable; prune skipped */ }
 }

package/lib/index.js

@@ -15,6 +15,7 @@
 import z from '@deepseek-ai/schemastery'
 import { credentialRef } from '@deepseek-ai/dsh-credentials'
 import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { enforceSecurePermissions } from './security.js'
 import { existsSync, unlinkSync } from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
@@ -32,13 +33,14 @@ import {
 
 import { buildDualOutputMarkdown, resolveConversationImage, analyzeImageWithVision } from './resolve-image.js'
 import { registerAllTools } from './register-tools.js'
+import { registerPluginUpdater } from './updater.js'
 
 
 export { IMAGE_SIZES, OUTPUT_FORMATS, PROVIDER_KEYS, buildSidecar, normalizeMediaType, resolveConversationImage, analyzeImageWithVision }
 
 
 /**
- * Сохраняет сгенерированный ассет в воркспейс, регистрирует в attachments и возвращает Dual-Output (#150).
+ * Saves generated asset to workspace, registers with attachments, and returns Dual-Output (#150).
  */
 
 
@@ -126,9 +128,8 @@ export const name = 'dsh-image-gen'
 /** Settings namespace the Web card edits. */
 const NS = 'dsh-image-gen'
 
-// Плагин раньше назывался dsh-fal-image-gen, и у тех, кто им пользовался, все
-// настройки лежат под старым именем. Оно читается как запасное и переносится
-// под новое имя один раз — молча, при первом запуске после обновления.
+// The plugin was previously named dsh-fal-image-gen. Any settings saved
+// under the legacy namespace are read as fallback and migrated once on startup.
 const LEGACY_NS = 'dsh-fal-image-gen'
 export const inject = ['tools', 'attachments', 'credentials', 'webServer', 'settings', 'llm', 'systemPrompt']
 
@@ -320,7 +321,7 @@ export const Config = z.object({
 })
 
 /** Keep a file stem safe for the filesystem. */
-/** Прочитать исходное изображение для правки: путь к файлу или attachment id. */
+/** Read source image for editing: filesystem path or attachment id. */
 export async function resolveSource(ctx, exec, ref) {
   if (!ref) return undefined
   const sessionCwd = exec.agent?.session?.header?.cwd
@@ -368,14 +369,14 @@ export async function resolveApiKey(ctx, ref) {
 }
 
 /**
- * Перенести настройки из-под старого имени плагина.
+ * Migrate settings from legacy plugin name.
  *
- * Берётся сырой пользовательский слой: значения по умолчанию переносить незачем,
- * а отличить их от заданных руками можно только по нему. Если под новым именем
- * человек уже что-то задал, не трогаем ничего — его выбор новее.
+ * Uses raw user layer: default values do not need migration,
+ * distinguishable only from user overrides. If settings are already configured
+ * under the new namespace, preserve them as newer choices.
  *
- * Старый блок остаётся в файле нетронутым: удалять чужие строки из настроек
- * пользователя плагину не по чину, а лишним он не мешает.
+ * The legacy block is left untouched in settings to avoid unexpected deletions.
+ * and causes no conflict with the active namespace.
  */
 function migrateLegacySettings(sctx, scope) {
   try {
@@ -387,19 +388,19 @@ function migrateLegacySettings(sctx, scope) {
     if (mine && typeof mine === 'object' && Object.keys(mine).length > 0) return
     scope.update(structuredClone(legacy))
   } catch (cannotMigrate) {
-    // Настройки не перенеслись — плагин работает на значениях по умолчанию,
-    // и человек задаст своё в карточке. Ронять из-за этого запуск незачем.
+    // Settings migration skipped — fallback to default schema configuration,
+    // and user may configure settings via UI card. No crash required.
   }
 }
 
-/** Каталог истории: общий для всех устройств, переживает рестарт. */
+/** History directory: persists across restarts. */
 export function historyFile() {
   return path.join(process.env.DSH_HOME || path.join(os.homedir(), '.dsh'), 'dsh-image-gen', 'history.json')
 }
 
-/** Прочитать историю из файла (пусто, если файла нет). */
-/** Найти запись истории по seed+prompt, если файл ещё существует. */
-/** Найти запись истории по промпту (без учёта seed), если файл существует. */
+/** Read history from disk file (empty array if not found). */
+/** Find history entry matching seed+prompt if file exists. */
+/** Find history entry matching prompt text if file exists. */
 export function findCachedGeneration(entries, hash) {
   if (!hash || !Array.isArray(entries)) return undefined
   return entries.find((e) => e.cacheHash === hash)
@@ -414,7 +415,7 @@ export async function findCached(entries, seed, prompt) {
   return entries.find((e) => e.seed === seed && e.prompt === prompt)
 }
 
-/** Вернуть запись из кэша, если файл существует; иначе undefined. */
+/** Return cached entry if file exists on disk, otherwise undefined. */
 export async function cachedResult(entry) {
   if (!entry || !entry.path) return undefined
   if (!entry.path || !existsSync(entry.path)) return undefined
@@ -440,7 +441,7 @@ export async function cachedResult(entry) {
   }
 }
 
-/** Удалить файлы и записи истории старше pruneDays дней (включая .json sidecar). */
+/** Prune files and history records older than pruneDays (including sidecars). */
 export async function pruneHistory(entries, pruneDays) {
   if (!pruneDays || pruneDays <= 0) return entries
   const cutoff = Date.now() - pruneDays * 86400000
@@ -448,7 +449,7 @@ export async function pruneHistory(entries, pruneDays) {
   for (const e of entries) {
     const created = e.createdAt ? Date.parse(e.createdAt) : NaN
     if (Number.isFinite(created) && created < cutoff) {
-      try { unlinkSync(e.path) } catch (err) { /* файл уже удалён */ }
+      try { unlinkSync(e.path) } catch (err) { /* file already deleted */ }
       try { unlinkSync(e.path.replace(/\.[^.]+$/, '.json')) } catch (err) { /* sidecar */ }
       continue
     }
@@ -467,20 +468,21 @@ export async function readHistory() {
   }
 }
 
-/** Записать историю в файл (перезапись целиком). */
+/** Save history to disk file (atomic overwrite). */
 export async function writeHistory(entries) {
   try {
     await mkdir(path.dirname(historyFile()), { recursive: true })
     await writeFile(historyFile(), JSON.stringify(entries, null, 2))
-  } catch (e) { /* история не критична */ }
+    enforceSecurePermissions(historyFile())
+  } catch (e) { /* history write failure is non-fatal */ }
 }
 
-/** Отфильтровать записи, чьи файлы ещё существуют; новые первыми. */
+/** Filter entries whose files exist on disk; newest first. */
 export function filterHistory(entries, exists) {
   return entries.filter((e) => exists(e.path)).slice(0, 50)
 }
 
-/** Собрать текст из итератора llm.stream (text-delta / block-end). */
+/** Collect text chunks from llm.stream iterator. */
 export async function collectText(iterable) {
   let out = ''
   let sawDelta = false
@@ -498,7 +500,7 @@ export async function collectText(iterable) {
   return out.trim()
 }
 
-/** Развернуть короткий промпт через чат-модель; при ошибке вернуть исходный. */
+/** Expand short prompt via chat model; return original prompt on error. */
 export function buildEnhancePromptSystemMessage(provider, model) {
   const isFlux = String(model || '').toLowerCase().includes('flux') || provider === 'fal'
   if (isFlux) {
@@ -507,7 +509,7 @@ export function buildEnhancePromptSystemMessage(provider, model) {
   return 'You are an expert prompt engineer for Stable Diffusion models. Expand the user prompt into detailed comma-separated descriptive visual tags including subject, composition, studio lighting, materials, and artistic medium. Reply with ONLY the expanded prompt, no commentary.'
 }
 
-/** Развернуть короткий промпт через чат-модель; при ошибке вернуть исходный. */
+/** Expand short prompt via chat model; return original prompt on error. */
 export async function enhancePrompt(ctx, cfg, prompt, signal, provider) {
   if (!cfg.enhancePrompt) return { prompt, enhanced: false }
   if (String(prompt).length >= (cfg.enhanceBelowChars || 200)) return { prompt, enhanced: false }
@@ -617,10 +619,8 @@ export function apply(ctx, config) {
     }
   })()
 
-  // Два адреса, один обработчик. Новый — тот, что уходит в новые сообщения;
-  // старый остался от прежнего имени плагина, и по нему сделаны ссылки в уже
-  // отправленных: сними его — и картинки в истории разговоров перестанут
-  // показываться.
+  // Two routes, one handler: new route for new messages, legacy route for
+  // backward compatibility with conversation history.
   for (const path of ['/dsh-image-gen/image', '/dsh-fal-image-gen/image']) {
     ctx.effect(() => ctx.webServer.register({
       kind: 'exact',
@@ -629,7 +629,14 @@ export function apply(ctx, config) {
     }), `dsh-image-gen: image route ${path}`)
   }
 
-  // Диагностика подключения к провайдерам
+    // One-click plugin updater route per DSH standard
+  ctx.effect(() => registerPluginUpdater(ctx, {
+    endpoint: '/api/dsh-image-gen/update',
+    packageName: '@goodandready/dsh-image-gen',
+    manifestUrl: new URL('../package.json', import.meta.url),
+  }), 'dsh-image-gen: plugin updater route')
+
+  // Provider connection diagnostics probe
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',
     path: '/dsh-image-gen/diagnostics/test',
@@ -658,7 +665,7 @@ export function apply(ctx, config) {
     },
   }), 'dsh-image-gen: diagnostics test route')
 
-    // История генераций: in-memory список, отфильтрованный по существованию файлов.
+  // Generation history: in-memory list filtered by filesystem existence.
   ctx.effect(() => ctx.webServer.register({
     kind: 'exact',
     path: '/dsh-image-gen/history',

package/lib/loop-guard.js

@@ -55,6 +55,7 @@ export function trackAndAssertLoopGuard(sessionId, {
 /**
  * Resets loop guard counter for a session.
  */
+/** @internal — test helper; not part of the plugin runtime API */
 export function resetLoopGuard(sessionId) {
   const sid = String(sessionId || 'default_session')
   sessionStates.delete(sid)
@@ -63,6 +64,7 @@ export function resetLoopGuard(sessionId) {
 /**
  * Gets current state for debugging/testing.
  */
+/** @internal — test helper; not part of the plugin runtime API */
 export function getLoopGuardState(sessionId) {
   const sid = String(sessionId || 'default_session')
   return sessionStates.get(sid) || { count: 0, lastPrompt: '', lastTimestamp: 0 }

package/lib/prompt-polisher.js

@@ -185,10 +185,3 @@ export function polishPrompt(basePrompt, stylePreset = null, {
   }
 }
 
-export function listCuratedStyles() {
-  return Object.values(CURATED_STYLES).map(s => ({
-    id: s.id,
-    label: s.label,
-    guidanceScale: s.guidanceScale,
-  }))
-}

package/lib/provider-utils.js

@@ -0,0 +1,302 @@
+// lib/provider-utils.js
+// Shared provider utilities and size/format constants extracted from providers.js (#239)
+
+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 normalizeCount(count, max = 4) {
+  const n = Math.floor(Number(count))
+  if (!Number.isFinite(n)) return 1
+  return Math.max(1, Math.min(max, n))
+}
+
+/** @internal — test helper for validating provider count limits */
+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}`
+}
+
+/** @internal — test helper for abort signal simulation */
+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 { msg = String(e.error) }
+      }
+    } 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 { /* response body not JSON; use raw text */ }
+    }
+
+    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
+}
+
+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. */