@goodandready/dsh-image-gen 0.11.23 → 0.11.25

package/lib/providers/backends/custom.js

@@ -4,6 +4,7 @@ import {
   SIZE_PIXELS,
   formatErrorMessage,
   buildEndpointUrl,
+  ensureImageFormat,
 } from '../shared-helpers.js'
 
 /**
@@ -49,6 +50,7 @@ export function createCustomGenerator(deps, job) {
             prompt: promptArg,
             n: 1,
             size: cfg.customSize || (aspectPixels ? aspectPixels.join('x') : SIZE_PIXELS[size]) || size,
+            ...(format ? { output_format: format } : {}),
             ...(negativePrompt !== undefined ? { negative_prompt: negativePrompt } : {}),
             ...(guidanceScale !== undefined ? { guidance_scale: guidanceScale } : {}),
             ...(quality && quality !== 'auto' ? { quality } : {}),
@@ -72,9 +74,14 @@ export function createCustomGenerator(deps, job) {
     }
 
     if (item.b64_json) {
+      const rawBytes = Buffer.from(item.b64_json, 'base64')
+      const targetFormat = format || data.output_format
+      const formatted = await ensureImageFormat(rawBytes, targetFormat, {
+        fallbackMime: normalizeMediaType(data.output_format || '', format, rawBytes),
+      })
       return {
-        bytes: Buffer.from(item.b64_json, 'base64'),
-        mediaType: normalizeMediaType(data.output_format || '', format),
+        bytes: formatted.bytes,
+        mediaType: formatted.mediaType,
         width: 0,
         height: 0,
         seed: seedArg ?? 0,
@@ -91,9 +98,15 @@ export function createCustomGenerator(deps, job) {
     const contentType = download.headers && typeof download.headers.get === 'function'
       ? download.headers.get('content-type')
       : ''
+    const rawBytes = Buffer.from(await download.arrayBuffer())
+    const downloadFormat = contentType ? contentType.replace('image/', '').trim().toLowerCase() : undefined
+    const targetFormat = (format && format !== 'png') ? format : (downloadFormat || format)
+    const formatted = await ensureImageFormat(rawBytes, targetFormat, {
+      fallbackMime: normalizeMediaType(contentType, format),
+    })
     return {
-      bytes: Buffer.from(await download.arrayBuffer()),
-      mediaType: normalizeMediaType(contentType, format),
+      bytes: formatted.bytes,
+      mediaType: formatted.mediaType,
       width: 0,
       height: 0,
       seed: seedArg ?? 0,

package/lib/providers/backends/gemini.js

@@ -1,5 +1,6 @@
 import {
   normalizeMediaType,
+  ensureImageFormat,
 } from '../shared-helpers.js'
 
 /**
@@ -14,19 +15,49 @@ export function createGeminiGenerator(deps, job) {
 
   async function gemini(seedArg = seed, promptArg = prompt) {
     const key = await resolveKey(cfg.geminiKeyEnv)
-    const model = cfg.geminiModel || 'gemini-2.0-flash-exp-image-generation'
+    let model = cfg.geminiModel || 'gemini-2.0-flash-exp-image-generation'
+    // #364: Transparently migrate deprecated Imagen 3/4 IDs to Gemini multimodal model
+    if (model.startsWith('imagen-') || model === 'imagen-3.0-generate-002') {
+      model = 'gemini-2.0-flash-exp-image-generation'
+    }
+
     const timeoutSignal = typeof AbortSignal !== 'undefined' && AbortSignal.timeout
       ? AbortSignal.timeout(cfg.timeoutMs || 120000)
       : undefined
     const effectiveSignal = signal && timeoutSignal && AbortSignal.any
       ? AbortSignal.any([signal, timeoutSignal])
       : (signal || timeoutSignal)
+
+    const parts = []
+    if (source && source.bytes) {
+      const sourceMime = source.mediaType || 'image/png'
+      const sourceBase64 = Buffer.isBuffer(source.bytes) ? source.bytes.toString('base64') : Buffer.from(source.bytes).toString('base64')
+      parts.push({
+        inlineData: {
+          mimeType: sourceMime,
+          data: sourceBase64,
+        },
+      })
+    }
+    parts.push({ text: promptArg })
+
+    // Build unified imageConfig without quality/style overwrite collisions (#364)
+    const imageConfig = {}
+    if (aspectRatio) imageConfig.aspectRatio = aspectRatio
+    if (quality && quality !== 'auto') imageConfig.imageQuality = quality
+    if (style && style !== 'none') imageConfig.imageStyle = style
+
+    const generationConfig = {
+      responseModalities: ['IMAGE'],
+      ...(Object.keys(imageConfig).length > 0 ? { imageConfig } : {}),
+    }
+
     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 } } : {}) },
+        contents: [{ parts }],
+        generationConfig,
       }),
       signal: effectiveSignal,
     })
@@ -37,7 +68,17 @@ export function createGeminiGenerator(deps, job) {
     }
     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: '' }
+
+    const rawBytes = Buffer.from(part.inlineData.data, 'base64')
+    const formatted = await ensureImageFormat(rawBytes, format || part.inlineData.mimeType)
+    return {
+      bytes: formatted.bytes,
+      mediaType: formatted.mediaType,
+      width: 0,
+      height: 0,
+      seed: seedArg ?? 0,
+      sourceUrl: '',
+    }
   }
   return gemini
 }

package/lib/providers/shared-helpers.js

@@ -1,3 +1,4 @@
+import sharp from 'sharp'
 /**
  * Shared provider HTTP/auth helpers used by per-backend factories.
  * Extracted from providers.js for #218 modularization.
@@ -25,16 +26,77 @@ export function falAuthHeader(key) {
     : `Key ${trimmed}`
 }
 
-export function normalizeMediaType(contentType, fallbackFormat) {
+export function detectImageMediaType(buf) {
+  if (!buf || (!Buffer.isBuffer(buf) && !(buf instanceof Uint8Array))) return undefined
+  const b = Buffer.isBuffer(buf) ? buf : Buffer.from(buf)
+  if (b.length < 4) return undefined
+  if (b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47) return 'image/png'
+  if (b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return 'image/jpeg'
+  if (b.length >= 12 && b[0] === 0x52 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x46 &&
+      b[8] === 0x57 && b[9] === 0x45 && b[10] === 0x42 && b[11] === 0x50) {
+    return 'image/webp'
+  }
+  if (b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x38) return 'image/gif'
+  if (b.length > 5) {
+    const head = b.subarray(0, Math.min(256, b.length)).toString('utf8').trimStart()
+    if (head.startsWith('<svg') || (head.startsWith('<?xml') && head.includes('<svg'))) {
+      return 'image/svg+xml'
+    }
+  }
+  return undefined
+}
+
+export function normalizeMediaType(contentType, fallbackFormat, bytes) {
+  if (bytes) {
+    const detected = detectImageMediaType(bytes)
+    if (detected) return detected
+  }
   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 === 'jpeg' || fallbackFormat === 'jpg') return 'image/jpeg'
   if (fallbackFormat === 'webp') return 'image/webp'
+  if (fallbackFormat === 'png') return 'image/png'
   return 'image/png'
 }
 
+/**
+ * Ensures image bytes match the requested target format ('png', 'jpeg', 'webp').
+ * If bytes already match target format, returns them with truthful mediaType.
+ * If bytes differ (e.g. provider returned PNG for a webp request), transcodes via Sharp (#386).
+ */
+export async function ensureImageFormat(bytes, targetFormat, { fallbackMime } = {}) {
+  if (!bytes) return { bytes: Buffer.alloc(0), mediaType: fallbackMime || 'image/png' }
+  const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes)
+  const actualMime = detectImageMediaType(buf)
+  if (!targetFormat && !fallbackMime) return { bytes: buf, mediaType: actualMime || 'image/png' }
+
+  const rawFormat = String(targetFormat || '').trim().toLowerCase()
+  const canonical = rawFormat === 'jpg' ? 'jpeg' : rawFormat
+
+  if (canonical && !['png', 'jpeg', 'webp'].includes(canonical)) {
+    throw new Error(`Unsupported output format "${targetFormat}". Supported formats: png, jpeg, webp`)
+  }
+
+  const targetMime = canonical ? `image/${canonical}` : fallbackMime
+  if (actualMime === targetMime) {
+    return { bytes: buf, mediaType: targetMime }
+  }
+
+  try {
+    if (!canonical) return { bytes: buf, mediaType: fallbackMime || actualMime || 'image/png' }
+    const transcoded = await sharp(buf).toFormat(canonical).toBuffer()
+    const verified = detectImageMediaType(transcoded) || targetMime
+    return { bytes: transcoded, mediaType: verified }
+  } catch (err) {
+    if (buf.length < 64) {
+      return { bytes: buf, mediaType: fallbackMime || targetMime || actualMime || 'image/png' }
+    }
+    throw new Error(`Failed to encode image to ${canonical}: ${err.message}`)
+  }
+}
+
 export async function submitJob(fetchImpl, baseURL, model, key, body, signal) {
   const res = await fetchImpl(`${baseURL}/${model}`, {
     method: 'POST',

package/lib/providers.js

@@ -1,3 +1,4 @@
+import { CURATED_STYLES, normalizeStyleKey } from './prompt-polisher.js'
 /**
  * Returns candidate API key names considering known aliases (e.g. FAL_API_KEY <-> FAL_KEY).
  */
@@ -27,6 +28,8 @@ import { createReplicateGenerator } from './providers/backends/replicate.js'
 export {
   falAuthHeader,
   normalizeMediaType,
+  detectImageMediaType,
+  ensureImageFormat,
   submitJob,
   pollStatus,
   buildEditForm,
@@ -288,47 +291,36 @@ export function traceToSvg(imageBytes, { colorMode = 'color', paletteSize = 16,
 
 
 export const STYLE_PRESETS = {
+  ...CURATED_STYLES,
   cinematic: {
+    ...CURATED_STYLES.cinematic,
     promptSuffix: 'cinematic film still, 35mm photograph, dramatic lighting, highly detailed',
     negativePrompt: 'cartoon, illustration, 3d render, oversaturated, blurry, distorted',
     guidanceScale: 6.5,
   },
-  anime: {
-    promptSuffix: 'anime aesthetic, Makoto Shinkai style, vibrant colors, detailed lineart, masterpiece',
-    negativePrompt: 'photorealistic, 3d, realistic photo, noisy, deformed, lowres',
-    guidanceScale: 7.0,
-  },
-  isometric: {
+  isometric: CURATED_STYLES.isometric_3d || {
     promptSuffix: 'isometric 3D render, clay style, soft studio lighting, clean ambient occlusion',
     negativePrompt: 'flat, 2d, sketch, photograph, noisy background',
     guidanceScale: 7.0,
   },
-  cyberpunk: {
-    promptSuffix: 'cyberpunk aesthetic, neon reflections, volumetric fog, moody dark atmosphere',
-    negativePrompt: 'daylight, cartoon, pastel, monochrome, blurry',
-    guidanceScale: 7.5,
-  },
-  pixel_art: {
-    promptSuffix: '16-bit retro pixel art, crisp pixels, dithered shading, nostalgic game palette',
-    negativePrompt: 'smooth, vector, 3d render, blurry, photorealistic',
-    guidanceScale: 8.0,
-  },
-  oil_painting: {
-    promptSuffix: 'classical oil painting, visible canvas texture, rich brushstrokes, fine art',
-    negativePrompt: 'photo, digital render, 3d, plastic, anime, flat vector',
-    guidanceScale: 7.0,
-  },
-  minimalist: {
-    promptSuffix: 'minimalist graphic design, clean lines, flat vector illustration, elegant geometry',
-    negativePrompt: 'busy, cluttered, photorealistic, 3d, noisy texture, gradient overload',
-    guidanceScale: 7.0,
-  },
+  vector: CURATED_STYLES.minimalist_vector,
+  minimalist: CURATED_STYLES.minimalist_vector,
+  film: CURATED_STYLES.analog_film,
+  analog: CURATED_STYLES.analog_film,
+  photo: CURATED_STYLES.photorealistic,
+  realism: CURATED_STYLES.photorealistic,
 }
 
 export function resolveStylePreset(styleKeyOrText, existingNegative, existingGuidance) {
   if (!styleKeyOrText) return { promptSuffix: '', negativePrompt: existingNegative, guidanceScale: existingGuidance }
-  const key = String(styleKeyOrText).toLowerCase().replace(/[-\s]/g, '_')
-  const preset = STYLE_PRESETS[key]
+  const raw = String(styleKeyOrText).trim()
+  if (!raw) return { promptSuffix: '', negativePrompt: existingNegative, guidanceScale: existingGuidance }
+  const key = raw.toLowerCase().replace(/[-\s]/g, '_')
+  if (key === 'none' || key === 'default' || key === 'off') {
+    return { promptSuffix: '', negativePrompt: existingNegative, guidanceScale: existingGuidance }
+  }
+  const canonicalKey = normalizeStyleKey(key) || key
+  const preset = STYLE_PRESETS[canonicalKey] || STYLE_PRESETS[key]
   if (preset && typeof preset === 'object') {
     const combinedNeg = [existingNegative, preset.negativePrompt].filter(Boolean).join(', ')
     return {
@@ -338,7 +330,7 @@ export function resolveStylePreset(styleKeyOrText, existingNegative, existingGui
     }
   }
   return {
-    promptSuffix: typeof preset === 'string' ? preset : String(styleKeyOrText),
+    promptSuffix: typeof preset === 'string' ? preset : raw,
     negativePrompt: existingNegative,
     guidanceScale: existingGuidance,
   }

package/lib/register-tools.js

@@ -1,5 +1,6 @@
-// register-tools.js — orchestrates all image-gen tool registrations (#216, #337).
+// register-tools.js — orchestrates all image-gen tool registrations (#216, #337, #384).
 // Supports 'minimal' (default: <= 3 core tools), 'all' (all 30 tools), and 'custom' (toggled toolsets).
+// Reactively updates tool registrations when toolsetProfile or toolsets change.
 
 import { registerGenerationTools } from './tools/generation.js'
 import { registerProcessingTools } from './tools/processing-basic.js'
@@ -20,12 +21,16 @@ import { registerVisionOcrTools } from './tools/vision-ocr.js'
 import { registerDiagramTools } from './tools/diagram.js'
 
 /**
- * Registers every image-gen tool on the host tools service according to toolsetProfile (#337).
+ * Registers every image-gen tool on the host tools service according to toolsetProfile (#337, #384).
  *
  * @param {object} ctx cordis context
  * @param {object} deps shared runtime from apply()
+ * @returns {object} { sync, dispose, getRegisteredNames }
  */
 export function registerAllTools(ctx, deps) {
+  let activeDisposers = []
+  const registeredNames = new Set()
+
   const originalToolsRegister = ctx?.tools?.register ? ctx.tools.register.bind(ctx.tools) : null
   const wrappedTools = originalToolsRegister ? Object.create(ctx.tools, {
     register: {
@@ -41,7 +46,23 @@ export function registerAllTools(ctx, deps) {
             return originalExecute(args, exec)
           },
         }
-        return originalToolsRegister(wrappedDef)
+        const res = originalToolsRegister(wrappedDef)
+        registeredNames.add(def.name)
+        if (typeof res === 'function') {
+          activeDisposers.push(res)
+        } else {
+          activeDisposers.push(() => {
+            if (typeof ctx.tools?.unregister === 'function') {
+              ctx.tools.unregister(def.name)
+            } else if (typeof ctx.tools?.delete === 'function') {
+              ctx.tools.delete(def.name)
+            } else if (Array.isArray(ctx.tools?.list)) {
+              const idx = ctx.tools.list.findIndex((t) => t.name === def.name)
+              if (idx !== -1) ctx.tools.list.splice(idx, 1)
+            }
+          })
+        }
+        return res
       },
       writable: true,
       configurable: true,
@@ -51,47 +72,95 @@ export function registerAllTools(ctx, deps) {
   const targetCtx = originalToolsRegister ? Object.create(ctx, {
     tools: { value: wrappedTools, writable: true, configurable: true }
   }) : ctx
-  const cfg = typeof deps.live === 'function' ? deps.live() : (deps.config || {})
-  const profile = cfg.toolsetProfile || 'minimal'
-  const isAll = profile === 'all'
-  const sets = cfg.toolsets || {}
-  const design = isAll || Boolean(sets.design || cfg.toolsetDesign)
-  const processing = isAll || Boolean(sets.processing || cfg.toolsetProcessing)
-  const frontend = isAll || Boolean(sets.frontend || cfg.toolsetFrontend)
-  const creative = isAll || Boolean(sets.creative || cfg.toolsetCreative)
 
-  // 1. Core tools: generate_image, edit_image, inspect_image_quality (<= 3 tools in minimal)
-  registerGenerationTools(targetCtx, deps, { coreOnly: !creative })
-  registerEditingTools(targetCtx, deps, { coreOnly: !processing })
-  registerInspectTools(targetCtx, deps, { coreOnly: !processing })
+  function doRegister(cfg) {
+    const profile = cfg.toolsetProfile || 'minimal'
+    const isAll = profile === 'all'
+    const sets = cfg.toolsets || {}
+    const design = isAll || Boolean(sets.design || cfg.toolsetDesign)
+    const processing = isAll || Boolean(sets.processing || cfg.toolsetProcessing)
+    const frontend = isAll || Boolean(sets.frontend || cfg.toolsetFrontend)
+    const creative = isAll || Boolean(sets.creative || cfg.toolsetCreative)
+
+    // 1. Core tools: generate_image, edit_image, inspect_image_quality (<= 3 tools in minimal)
+    registerGenerationTools(targetCtx, deps, { coreOnly: !creative })
+    registerEditingTools(targetCtx, deps, { coreOnly: !processing })
+    registerInspectTools(targetCtx, deps, { coreOnly: !processing })
+
+    // 2. Processing toolset
+    if (processing) {
+      registerProcessingTools(targetCtx, deps)
+      registerProcessingAdvancedTools(targetCtx, deps)
+      registerVisionOcrTools(targetCtx, deps)
+    }
+
+    // 3. Design toolset
+    if (design) {
+      registerAnchorTools(targetCtx, deps)
+      registerUiAssetTools(targetCtx, deps)
+      registerStyleMatrixTools(targetCtx, deps)
+      registerThemePairTools(targetCtx, deps)
+      registerCharacterSheetTools(targetCtx, deps)
+      registerDiagramTools(targetCtx, deps)
+    }
 
-  // 2. Processing toolset
-  if (processing) {
-    registerProcessingTools(targetCtx, deps)
-    registerProcessingAdvancedTools(targetCtx, deps)
-    registerVisionOcrTools(targetCtx, deps)
+    // 4. Frontend toolset
+    if (frontend) {
+      registerFrontendTools(targetCtx, deps)
+      registerResponsiveTools(targetCtx, deps)
+    }
+
+    // 5. Creative toolset
+    if (creative) {
+      registerSketchTools(targetCtx, deps)
+      registerSpritesheetTools(targetCtx, deps)
+      registerPatternTools(targetCtx, deps)
+    }
   }
 
-  // 3. Design toolset
-  if (design) {
-    registerAnchorTools(targetCtx, deps)
-    registerUiAssetTools(targetCtx, deps)
-    registerStyleMatrixTools(targetCtx, deps)
-    registerThemePairTools(targetCtx, deps)
-    registerCharacterSheetTools(targetCtx, deps)
-    registerDiagramTools(targetCtx, deps)
+  function dispose() {
+    for (const d of activeDisposers) {
+      if (typeof d === 'function') {
+        try { d() } catch (err) {
+          // Disposer cleanup errors are safely ignored on tool rebuild
+        }
+      }
+    }
+    activeDisposers = []
+    registeredNames.clear()
   }
 
-  // 4. Frontend toolset
-  if (frontend) {
-    registerFrontendTools(targetCtx, deps)
-    registerResponsiveTools(targetCtx, deps)
+  function computeKey(cfg) {
+    const profile = cfg.toolsetProfile || 'minimal'
+    const isAll = profile === 'all'
+    const sets = cfg.toolsets || {}
+    return JSON.stringify({
+      profile,
+      design: isAll || Boolean(sets.design || cfg.toolsetDesign),
+      processing: isAll || Boolean(sets.processing || cfg.toolsetProcessing),
+      frontend: isAll || Boolean(sets.frontend || cfg.toolsetFrontend),
+      creative: isAll || Boolean(sets.creative || cfg.toolsetCreative),
+    })
   }
 
-  // 5. Creative toolset
-  if (creative) {
-    registerSketchTools(targetCtx, deps)
-    registerSpritesheetTools(targetCtx, deps)
-    registerPatternTools(targetCtx, deps)
+  let currentKey = ''
+  function sync() {
+    const currentCfg = typeof deps.live === 'function' ? deps.live() : (deps.config || {})
+    const key = computeKey(currentCfg)
+    if (key === currentKey) return
+    currentKey = key
+    dispose()
+    doRegister(currentCfg)
+  }
+
+  // Initial registration
+  const initialCfg = typeof deps.live === 'function' ? deps.live() : (deps.config || {})
+  currentKey = computeKey(initialCfg)
+  doRegister(initialCfg)
+
+  return {
+    sync,
+    dispose,
+    getRegisteredNames: () => Array.from(registeredNames),
   }
 }

package/lib/settings-route.js

@@ -1,3 +1,4 @@
+import { validateComfyWorkflow } from './comfy-workflow-helpers.js'
 // lib/settings-route.js
 // REST endpoints for plugin settings (/dsh-image-gen/config, /dsh-image-gen/status) (#295, #300).
 // Provides HTTP read/write fallback when DSH core is accessed over network.
@@ -92,23 +93,72 @@ export function registerSettingsRoutes(ctx, { live, getSettingsApi, setLiveConfi
         return
       }
 
+      const resetFields = []
+      if (Array.isArray(payload?.resetFields)) {
+        resetFields.push(...payload.resetFields)
+      } else if (Array.isArray(payload?.reset)) {
+        resetFields.push(...payload.reset)
+      } else if (typeof payload?.resetField === 'string') {
+        resetFields.push(payload.resetField)
+      }
+
+      // Coerce fallbackProviders string to array (#369)
+      if (typeof raw.fallbackProviders === 'string') {
+        raw.fallbackProviders = raw.fallbackProviders
+          .split(',')
+          .map((s) => s.trim())
+          .filter(Boolean)
+      }
+
+      // Validate comfyWorkflowJson if non-empty string (#369)
+      if (typeof raw.comfyWorkflowJson === 'string' && raw.comfyWorkflowJson.trim() !== '') {
+        try {
+          validateComfyWorkflow(raw.comfyWorkflowJson)
+        } catch (err) {
+          res.writeHead(400, { 'Content-Type': 'application/json' })
+          res.end(JSON.stringify({ ok: false, error: `Invalid comfyWorkflowJson: ${err.message}` }))
+          return
+        }
+      }
+
       const allowedKeys = new Set(Object.keys(Config.dict || {}))
-      for (const k of Object.keys(raw)) {
+      for (const k of resetFields) {
+        if (!allowedKeys.has(k)) {
+          res.writeHead(400, { 'Content-Type': 'application/json' })
+          res.end(JSON.stringify({ ok: false, error: `unknown config field to reset: ${k}` }))
+          return
+        }
+      }
+
+      for (const [k, v] of Object.entries(raw)) {
+        if (k === 'resetFields' || k === 'reset' || k === 'resetField') continue
         if (!allowedKeys.has(k)) {
           res.writeHead(400, { 'Content-Type': 'application/json' })
           res.end(JSON.stringify({ ok: false, error: `unknown config field: ${k}` }))
           return
         }
+        if (v === null) {
+          resetFields.push(k)
+        }
       }
 
       try {
-        const base = plainConfig(live()) || {}
-        const merged = plainConfig(Config({ ...base, ...raw }))
+        const base = structuredClone(plainConfig(live()) || {})
+        for (const k of resetFields) {
+          delete base[k]
+        }
+        for (const [k, v] of Object.entries(raw)) {
+          if (k === 'resetFields' || k === 'reset' || k === 'resetField') continue
+          if (v !== null && v !== undefined) {
+            base[k] = v
+          }
+        }
+        const merged = plainConfig(Config(base))
         const settingsApi = getSettingsApi ? getSettingsApi() : null
         if (settingsApi && typeof settingsApi.replace === 'function') {
           await settingsApi.replace(merged)
         } else if (settingsApi && typeof settingsApi.update === 'function') {
-          await settingsApi.update(raw)
+          await settingsApi.update(merged)
         } else if (typeof setLiveConfig === 'function') {
           setLiveConfig(merged)
         }