@goodandready/dsh-image-gen 0.10.23 → 0.10.24

package/README.md

@@ -41,6 +41,13 @@
 
 ---
 
+## 🚀 Updates v0.10.24: Quality Block — Publication Boundary, Settings Status, Theme Colors & Module Split (#235–#242)
+* **Publication Boundary**: Added `.gitattributes` with `export-ignore` for `AGENTS.md`, `index.md`, `docs/`, and `.gitea/` so GitHub source archives and `git archive` no longer ship internal workflow files.
+* **Settings Status Fallback**: Corrected provider/config status handling in the Settings Card so partial/unknown states no longer show a false “unavailable”.
+* **Design-System Alignment**: Renamed residual `fal-` CSS class prefixes to the `ig-` system and bound colors to DSH theme variables via `var(--dsw-alias-*, <fallback>)`.
+* **Sensitive File Hardening**: History, cache meta/data, and spend-meter writes now enforce `0600` permissions after write.
+* **Dead Code Removal & Module Split**: Removed unused `listCuratedStyles`; split oversized server modules — `providers.js` utils extracted to `provider-utils.js`, `processing.js` into `processing-basic.js` + `processing-advanced.js`. Client file split is tracked separately (#244).
+
 ## 🚀 Updates v0.10.23: In-App Auto-Updater, Settings Synchronization, Active Probes & Language Purity (#232)
 * **One-Click In-App Auto-Updater**: Direct 1-click update support inside the plugin Settings Card (`UpdaterSection`) backed by `/api/dsh-image-gen/update`. Fetches the npm registry for release manifests, verifies semver differences, and securely triggers `dsh plugin add @goodandready/dsh-image-gen@latest` restricted to loopback and private LAN connections.
 * **1:1 Settings Synchronization**: Fully synchronized host `Config` schema in `lib/index.js` with client UI fields (`lib/client.js`), exposing `autoEnhancePrompt` and `defaultStylePreset` under the `✨ Enhancer` tab.

package/README.ru.md

@@ -34,6 +34,13 @@
 </div>
 
 ---
+## 🚀 Обновления v0.10.24: Блок качества — публикационная граница, статусы настроек, цвета темы и разбиение модулей (#235–#242)
+* **Публикационная граница**: добавлен `.gitattributes` c `export-ignore` для `AGENTS.md`, `index.md`, `docs/` и `.gitea/` — архивы GitHub source и `git archive` больше не содержат внутренние файлы workflow.
+* **Статусы настроек**: исправлен fallback статуса провайдера/конфигурации в карточке настроек — промежуточные/неизвестные состояния больше не показываются ложным «unavailable».
+* **Выравнивание с дизайн-системой**: остаточные CSS-классы `fal-` переименованы в префикс `ig-`; цвета привязаны к переменным темы DSH через `var(--dsw-alias-*, <fallback>)`.
+* **Защита чувствительных файлов**: запись history, cache meta/data и spend-meter после записи получает права `0600`.
+* **Удаление мёртвого кода и разбиение модулей**: удалён неиспользуемый `listCuratedStyles`; укрупнённые server-модули разнесены — утилиты `providers.js` → `provider-utils.js`, `processing.js` → `processing-basic.js` + `processing-advanced.js`. Разбиение client отложено в #244.
+
 ## 🚀 Обновления v0.10.23: Встроенное автообновление, синхронизация настроек, диагностические пробы и чистота языка (#232)
 * **Встроенное обновление в 1 клик**: Прямая проверка и обновление плагина прямо из карточки настроек (`UpdaterSection`) через эндпоинт `/api/dsh-image-gen/update`. Опрашивает реестр npm, сравнивает semver-версии и безопасно запускает установку через `dsh plugin add` с защитой по loopback и доверенной локальной сети (RFC 1918).
 * **Синхронизация настроек 1:1**: Полное выравнивание схемы хоста `Config` в `lib/index.js` и полей UI `FIELDS` в `lib/client.js` — во вкладку «✨ Промпт и стили» добавлены тумблеры `autoEnhancePrompt` и выпадающий список `defaultStylePreset`.

package/README.zh.md

@@ -47,6 +47,13 @@
 
 ---
 
+## 🚀 更新 v0.10.24: 质量加固 — 发布边界、设置状态、主题颜色与模块拆分 (#235–#242)
+* **发布边界**: 新增 `.gitattributes`，对 `AGENTS.md`、`index.md`、`docs/`、`.gitea/` 设置 `export-ignore`，GitHub source 归档与 `git archive` 不再包含内部工作流文件。
+* **设置状态回退**: 修正设置卡片中的提供方/配置状态处理，部分或未知状态不再误显示为 “unavailable”。
+* **对齐设计系统**: 将残留的 `fal-` CSS 类前缀改为 `ig-`，并以 `var(--dsw-alias-*, <fallback>)` 绑定 DSH 主题变量。
+* **敏感文件加固**: 历史记录、缓存 meta/data 与花费计量写入后强制 `0600` 权限。
+* **死代码清理与模块拆分**: 删除未使用的 `listCuratedStyles`；拆分过大的服务端模块 — `providers.js` 工具函数抽到 `provider-utils.js`，`processing.js` 拆为 `processing-basic.js` + `processing-advanced.js`。客户端拆分见 #244。
+
 ## 🚀 更新 v0.10.23: 应用内一键更新、设置同步、真实探针与语言规范 (#232)
 * **应用内一键自动更新**: 设置卡片内新增「插件更新」模块（`UpdaterSection`），配合 `/api/dsh-image-gen/update` 接口。自动查询 npm 官方注册表，对比语义化版本号，并在本地回环或私有局域网安全授权下执行 `dsh plugin add @goodandready/dsh-image-gen@latest`。
 * **1:1 核心配置与界面设置同步**: 严格对齐 `lib/index.js` 宿主 `Config` 与 `lib/client.js` 界面字段，在「✨ 提示词增强」标签页下完整呈现 `autoEnhancePrompt`（智能自动增强提示词）与 `defaultStylePreset`（默认风格预设）。

package/lib/client.js

@@ -22,7 +22,7 @@ window.__ModuleLoader__.load({
       try {
         runtime = require(id)
         if (runtime && typeof runtime.createSnapshotStore === 'function') break
-      } catch (_) {}
+      } catch (_) { /* module not available in this build; try next */ }
     }
 
     const NS = 'dsh-image-gen'
@@ -99,23 +99,23 @@ window.__ModuleLoader__.load({
 .ig-btn:hover:not(:disabled){background:var(--dsw-alias-bg-layer-4, var(--dsw-alias-bg-layer-2));border-color:var(--dsw-alias-label-dimmed, var(--dsw-alias-border-l2))}
 .ig-btn-primary{background:var(--dsw-alias-label-primary);color:var(--dsw-alias-bg-layer-3);border-color:transparent}
 .ig-btn-primary:hover:not(:disabled){opacity:0.9}
-.ig-btn-danger{color:var(--dsw-alias-state-error-primary);border-color:rgba(239,68,68,0.3)}
-.ig-btn-danger:hover:not(:disabled){background:rgba(239,68,68,0.12);border-color:rgba(239,68,68,0.5)}
+.ig-btn-danger{color:var(--dsw-alias-state-error-primary);border-color:var(--dsw-alias-state-error-primary)}
+.ig-btn-danger:hover:not(:disabled){background:var(--dsw-alias-state-error-bg,rgba(239,68,68,0.12));border-color:var(--dsw-alias-state-error-primary)}
 .ig-btn-disabled{opacity:0.5;cursor:not-allowed}
 
 .ig-reset{font-size:11px;color:var(--dsw-alias-state-brand-primary);background:none;border:none;cursor:pointer;padding:0;text-decoration:underline}
 .ig-reset:hover{opacity:0.8}
 
-.ig-alert-ok{padding:10px 14px;border-radius:8px;background:rgba(16,185,129,0.1);color:var(--dsw-alias-state-success-primary);font-size:13px}
-.ig-alert-bad{padding:10px 14px;border-radius:8px;background:rgba(239,68,68,0.1);color:var(--dsw-alias-state-error-primary);font-size:13px}
+.ig-alert-ok{padding:10px 14px;border-radius:8px;background:var(--dsw-alias-state-success-bg,rgba(16,185,129,0.1));color:var(--dsw-alias-state-success-primary);font-size:13px}
+.ig-alert-bad{padding:10px 14px;border-radius:8px;background:var(--dsw-alias-state-error-bg,rgba(239,68,68,0.1));color:var(--dsw-alias-state-error-primary);font-size:13px}
 .ig-alert-err{padding:10px 14px;border-radius:8px;background:rgba(239,68,68,0.1);color:var(--dsw-alias-state-error-primary);font-size:13px}
 .ig-banner-warning{padding:12px 16px;border-radius:8px;background:rgba(245,158,11,0.12);border:1px solid var(--dsw-alias-state-warning-primary);color:var(--dsw-alias-state-warning-primary);font-size:13px;display:flex;align-items:center;gap:10px;font-weight:500}
 
 /* Backward-compatibility alias styles for toolview */
 .fal_head{font-size:13px;font-weight:600;margin-bottom:8px;color:var(--dsw-alias-label-primary)}
-.fal-prompt{font-size:13px;padding:8px 12px;background:var(--dsw-alias-bg-layer-2);border-radius:6px;border:1px solid var(--dsw-alias-border-l2);margin-bottom:8px;word-break:break-word}
-.fal-meta{font-size:11px;color:var(--dsw-alias-label-secondary);margin-top:6px}
-.fal-err{padding:10px;border-radius:6px;background:rgba(239,68,68,0.1);color:var(--dsw-alias-state-error-primary);font-size:12px}
+.ig-prompt{font-size:13px;padding:8px 12px;background:var(--dsw-alias-bg-layer-2);border-radius:6px;border:1px solid var(--dsw-alias-border-l2);margin-bottom:8px;word-break:break-word}
+.ig-meta{font-size:11px;color:var(--dsw-alias-label-secondary);margin-top:6px}
+.ig-err{padding:10px;border-radius:6px;background:var(--dsw-alias-state-error-bg,rgba(239,68,68,0.1));color:var(--dsw-alias-state-error-primary);font-size:12px}
 `
       document.head.appendChild(style)
     }
@@ -328,7 +328,7 @@ window.__ModuleLoader__.load({
         }
       }
       shell() {
-        const snapshot = (this.scope && this.scope.getSnapshot && this.scope.getSnapshot()) || { status: 'ready', writable: true }
+        const snapshot = (this.scope && this.scope.getSnapshot && this.scope.getSnapshot()) || { status: 'unavailable', writable: false }
         const plan = this.plan()
         return {
           available: snapshot.status === 'ready',
@@ -826,9 +826,9 @@ window.__ModuleLoader__.load({
                     left: 0,
                     right: 0,
                     padding: '4px 6px',
-                    background: 'linear-gradient(transparent, rgba(0,0,0,0.8))',
+                    background: 'linear-gradient(transparent, var(--dsw-alias-overlay-scrim,rgba(0,0,0,0.8)))',
                     fontSize: '10px',
-                    color: '#fff',
+                    color: 'var(--dsw-alias-label-on-overlay,#fff)',
                     whiteSpace: 'nowrap',
                     overflow: 'hidden',
                     textOverflow: 'ellipsis',
@@ -846,7 +846,7 @@ window.__ModuleLoader__.load({
               style: {
                 position: 'fixed',
                 inset: 0,
-                background: 'rgba(0,0,0,0.7)',
+                background: 'var(--dsw-alias-overlay-backdrop,rgba(0,0,0,0.7))',
                 zIndex: 10000,
                 display: 'flex',
                 alignItems: 'center',
@@ -889,7 +889,7 @@ window.__ModuleLoader__.load({
               ),
               react.createElement('img', {
                 src: selected.thumbnailUrl || (selected.attachmentId ? '/dsh-image-gen/image?id=' + encodeURIComponent(selected.attachmentId) : ''),
-                style: { width: '100%', borderRadius: '8px', maxHeight: '340px', objectFit: 'contain', background: '#0a0a0c' },
+                style: { width: '100%', borderRadius: '8px', maxHeight: '340px', objectFit: 'contain', background: 'var(--dsw-alias-bg-layer-1,#0a0a0c)' },
               }),
               react.createElement(
                 'div',
@@ -1002,7 +1002,7 @@ window.__ModuleLoader__.load({
                 background: 'var(--dsw-alias-bg-layer-3)',
                 border: '1px solid var(--dsw-alias-border-l2)',
                 borderRadius: '12px',
-                boxShadow: '0 8px 32px rgba(0,0,0,0.4)',
+                boxShadow: 'var(--dsw-alias-shadow-overlay,0 8px 32px rgba(0,0,0,0.4))',
                 zIndex: 9999,
                 padding: '16px',
                 overflowY: 'auto',
@@ -1038,7 +1038,7 @@ window.__ModuleLoader__.load({
 
       const state = (typeof props.useFalSettingsCard === 'function'
         ? props.useFalSettingsCard((s) => s)
-        : null) || props.state || { available: true, writable: true, provider: { text: 'fal' } }
+        : null) || props.state || { available: false, writable: false, provider: { text: 'fal' } }
 
       const disabled = !state.writable
       const currentProvider = (state.provider && state.provider.text) || 'fal'
@@ -1299,7 +1299,7 @@ window.__ModuleLoader__.load({
           args = JSON.parse(raw)
           prompt = args.prompt || ''
         }
-      } catch (_) {}
+      } catch (_) { /* malformed tool args; use empty prompt */ }
 
       const [copied, setCopied] = react.useState(false)
 
@@ -1310,7 +1310,7 @@ window.__ModuleLoader__.load({
           const binding = current && sessions.binding(current)
           const session = binding && binding.session
           if (session && session.prompt) await session.prompt([{ type: 'text', text }], 'queue')
-        } catch (_) {}
+        } catch (_) { /* session prompt delivery failed; non-fatal */ }
       }
 
       const onCopyPrompt = () => {
@@ -1344,10 +1344,10 @@ window.__ModuleLoader__.load({
 
       const body = []
       if (prompt) {
-        body.push(react.createElement('div', { className: 'fal-prompt', key: 'p' }, prompt))
+        body.push(react.createElement('div', { className: 'ig-prompt', key: 'p' }, prompt))
       }
       if (failed) {
-        body.push(react.createElement('div', { className: 'fal-err', key: 'e' }, parsed.text || t('card.unknownError')))
+        body.push(react.createElement('div', { className: 'ig-err', key: 'e' }, parsed.text || t('card.unknownError')))
       } else if (!parsed.attachment && parsed.url) {
         body.push(react.createElement('img', {
           key: 'i',
@@ -2008,7 +2008,7 @@ window.__ModuleLoader__.load({
               console.warn('[dsh-image-gen] native sidebar registration failed', e)
             }
           })
-        } catch (e) {}
+        } catch (e) { /* native sidebar unavailable */ }
 
         try {
           ctx.inject(['betterSidebar'], (sctx) => {
@@ -2026,7 +2026,7 @@ window.__ModuleLoader__.load({
               console.warn('[dsh-image-gen] betterSidebar registerTab failed', e)
             }
           })
-        } catch (e) {}
+        } catch (e) { /* betterSidebar unavailable */ }
       }
 
       // Conversation header utilities chip (quick-access gallery button in chat header)

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'
@@ -472,6 +473,7 @@ export async function writeHistory(entries) {
   try {
     await mkdir(path.dirname(historyFile()), { recursive: true })
     await writeFile(historyFile(), JSON.stringify(entries, null, 2))
+    enforceSecurePermissions(historyFile())
   } catch (e) { /* history write failure is non-fatal */ }
 }
 

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. */