@goodandready/dsh-image-gen 0.11.11 → 0.11.12

package/lib/tools/character-sheet.js

@@ -0,0 +1,187 @@
+// character-sheet.js — generate_character_sheet tool (#181).
+// Generates multi-angle character model sheets and turnarounds with visual consistency.
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import path from 'node:path'
+import { mkdir, writeFile } from 'node:fs/promises'
+import {
+  ASPECT_RATIOS,
+  buildSidecar,
+  makeProviders,
+  toLosslessJson,
+  saveAttachmentSafe,
+} from '../providers.js'
+import { resolveFallbackChain, executeWithFallback } from '../fallback-router.js'
+import { renderToolOutput } from '../attachment-helper.js'
+import {
+  CHARACTER_SHEET_LAYOUTS,
+  CHARACTER_SHEET_STYLES,
+  buildCharacterSheetPrompt,
+} from '../character-sheet-helpers.js'
+
+export function registerCharacterSheetTools(ctx, deps) {
+  const {
+    live,
+    slugify,
+    resolveApiKey,
+  } = deps
+
+  ctx.effect(() => {
+    ctx.tools.register(
+      defineTool({
+        name: 'generate_character_sheet',
+        description:
+          'Generate a multi-angle character model sheet or turnaround reference with high visual identity consistency. '
+          + 'Supports horizontal turnarounds (front, profile, 3/4, back), 1x3 triptychs, 2x2 grids, and facial emotion sheets across concept, anime, 3D, and comic styles.',
+        parameters: {
+          prompt: {
+            type: 'string',
+            description: 'Core character description (e.g. "female cyborg detective with neon violet hair, yellow trenchcoat, cybernetic arm").',
+          },
+          layout: {
+            type: 'string',
+            enum: ['turnaround', '1x3', '2x2', 'emotions'],
+            description: 'Layout arrangement: "turnaround" (4 sequential horizontal views), "1x3" (front, side, back), "2x2" (quad angles), or "emotions" (4 facial expressions). Default: turnaround.',
+          },
+          style: {
+            type: 'string',
+            enum: ['concept_art', 'anime', '3d_animation', 'pixel_art', 'realistic', 'comic'],
+            description: 'Artistic rendering style. Default: concept_art.',
+          },
+          negativePrompt: {
+            type: 'string',
+            description: 'Negative prompt directives to suppress unwanted elements.',
+          },
+          seed: {
+            type: 'integer',
+            description: 'RNG seed for reproducible character generation across sessions.',
+          },
+          provider: {
+            type: 'string',
+            description: 'Optional provider override (e.g. fal, replicate, local). Defaults to active provider.',
+          },
+        },
+        output: {
+          schema: {
+            type: 'object',
+            additionalProperties: true,
+            properties: {
+              prompt: { type: 'string' },
+              layout: { type: 'string' },
+              style: { type: 'string' },
+              aspectRatio: { type: 'string' },
+              views: {
+                type: 'array',
+                items: { type: 'string' },
+              },
+              seed: { type: 'integer' },
+              provider: { type: 'string' },
+              attachment: {
+                type: 'object',
+                additionalProperties: true,
+                properties: {
+                  attachmentId: { type: 'string' },
+                  url: { type: 'string' },
+                  mediaType: { type: 'string' },
+                  filename: { type: 'string' },
+                  byteSize: { type: 'integer' },
+                },
+              },
+            },
+          },
+          render: (result, renderCtx) =>
+            renderToolOutput(result, renderCtx, {
+              title: (res) => `Character Sheet (${res.layout || 'turnaround'}) — ${res.style || 'concept_art'}`,
+              subtitle: (res) => (res.views ? `Views: ${res.views.join(' | ')}` : ''),
+            }),
+        },
+        async execute(args, execCtx) {
+          const cfg = live.value
+          const activeProvider = args.provider || cfg.activeProvider || 'fal'
+          const seed = typeof args.seed === 'number' ? args.seed : Math.floor(Math.random() * 2147483647)
+
+          const sheetPlan = buildCharacterSheetPrompt({
+            prompt: args.prompt,
+            layout: args.layout,
+            style: args.style,
+            negativePrompt: args.negativePrompt,
+          })
+
+          const providers = makeProviders({
+            fetchImpl: fetch,
+            resolveKey: (id) => resolveApiKey(cfg, id),
+            cfg,
+          })
+
+          const fallbackChain = resolveFallbackChain(activeProvider, cfg)
+
+          const aspectPixels = ASPECT_RATIOS[sheetPlan.aspectRatio] || ASPECT_RATIOS['16:9']
+
+          const jobPayload = {
+            prompt: sheetPlan.prompt,
+            negativePrompt: sheetPlan.negativePrompt,
+            aspectRatio: sheetPlan.aspectRatio,
+            aspectPixels,
+            format: 'png',
+            seed,
+            quality: 'high',
+          }
+
+          const { result: genResult, provider: usedProvider } = await executeWithFallback(
+            fallbackChain,
+            providers,
+            jobPayload,
+            { signal: execCtx?.signal }
+          )
+
+          const timestamp = Date.now()
+          const safeSlug = slugify(args.prompt.slice(0, 30)) || 'character-sheet'
+          const filename = `character-sheet-${sheetPlan.layout}-${safeSlug}-${timestamp}.png`
+
+          let attachment = null
+          if (genResult.bytes) {
+            const outDir = path.resolve(process.cwd(), cfg.outputDir || 'output')
+            await mkdir(outDir, { recursive: true })
+            const diskPath = path.join(outDir, filename)
+            await writeFile(diskPath, Buffer.from(genResult.bytes))
+
+            attachment = await saveAttachmentSafe(
+              ctx,
+              Buffer.from(genResult.bytes),
+              'image/png',
+              filename,
+              diskPath
+            )
+          } else if (genResult.url) {
+            attachment = {
+              url: genResult.url,
+              mediaType: 'image/png',
+              filename,
+            }
+          }
+
+          const response = {
+            prompt: sheetPlan.prompt,
+            characterDescription: args.prompt,
+            layout: sheetPlan.layout,
+            style: sheetPlan.style,
+            aspectRatio: sheetPlan.aspectRatio,
+            views: sheetPlan.views,
+            seed,
+            provider: usedProvider,
+            attachment,
+          }
+
+          if (attachment?.attachmentId) {
+            response.attachmentId = attachment.attachmentId
+          }
+          if (attachment?.url) {
+            response.url = attachment.url
+          }
+
+          return response
+        },
+      })
+    )
+  }, 'dsh-image-gen: tool generate_character_sheet')
+}

package/lib/tools/diagram.js

@@ -0,0 +1,172 @@
+// diagram.js — beautify_diagram tool (#185).
+// Transforms raw Mermaid / Graphviz diagrams into high-end 3D isometric architectural illustrations.
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import path from 'node:path'
+import { mkdir, writeFile } from 'node:fs/promises'
+import {
+  ASPECT_RATIOS,
+  makeProviders,
+  saveAttachmentSafe,
+} from '../providers.js'
+import { resolveFallbackChain, executeWithFallback } from '../fallback-router.js'
+import { renderToolOutput } from '../attachment-helper.js'
+import {
+  DIAGRAM_3D_STYLES,
+  buildDiagramIllustrationPrompt,
+} from '../diagram-helpers.js'
+
+export function registerDiagramTools(ctx, deps) {
+  const {
+    live,
+    slugify,
+    resolveApiKey,
+  } = deps
+
+  ctx.effect(() => {
+    ctx.tools.register(
+      defineTool({
+        name: 'beautify_diagram',
+        description:
+          'Transform raw Mermaid or Graphviz diagrams into stunning 3D isometric architectural illustrations '
+          + 'with glowing data pipes, glassmorphism cards, and pristine technical lighting for documentation and hero blocks.',
+        parameters: {
+          diagram: {
+            type: 'string',
+            description: 'Raw Mermaid diagram source code, Graphviz DOT text, or image path/attachment.',
+          },
+          style: {
+            type: 'string',
+            enum: ['isometric_3d', 'cyber_blueprint', 'clay_minimal', 'glossy_dark'],
+            description: '3D rendering aesthetic style. Default: isometric_3d.',
+          },
+          title: {
+            type: 'string',
+            description: 'Optional architecture title or headline to feature in the composition.',
+          },
+          aspect_ratio: {
+            type: 'string',
+            enum: ['16:9', '1:1', '4:3', '21:9'],
+            description: 'Aspect ratio for documentation header or hero banner (default: 16:9).',
+          },
+          seed: {
+            type: 'integer',
+            description: 'Optional seed for reproducible diagram generation.',
+          },
+          provider: {
+            type: 'string',
+            description: 'Optional provider override. Defaults to active provider.',
+          },
+        },
+        output: {
+          schema: {
+            type: 'object',
+            additionalProperties: true,
+            properties: {
+              title: { type: 'string' },
+              style: { type: 'string' },
+              aspectRatio: { type: 'string' },
+              detectedNodes: {
+                type: 'array',
+                items: { type: 'string' },
+              },
+              prompt: { type: 'string' },
+              seed: { type: 'integer' },
+              provider: { type: 'string' },
+              attachment: {
+                type: 'object',
+                additionalProperties: true,
+                properties: {
+                  attachmentId: { type: 'string' },
+                  url: { type: 'string' },
+                  mediaType: { type: 'string' },
+                  filename: { type: 'string' },
+                },
+              },
+            },
+          },
+          render: (result, renderCtx) =>
+            renderToolOutput(result, renderCtx, {
+              title: (res) => `3D Architecture Diagram — ${res.title || res.style || 'Isometric'}`,
+              subtitle: (res) => (res.detectedNodes?.length ? `Nodes: ${res.detectedNodes.slice(0, 4).join(', ')}` : ''),
+            }),
+        },
+        async execute(args, execCtx) {
+          const cfg = live?.value || (typeof live === 'function' ? live() : {})
+          const activeProvider = args.provider || cfg.activeProvider || 'fal'
+          const seed = typeof args.seed === 'number' ? args.seed : Math.floor(Math.random() * 2147483647)
+
+          const plan = buildDiagramIllustrationPrompt({
+            diagram: args.diagram,
+            style: args.style,
+            title: args.title,
+            aspectRatio: args.aspect_ratio || '16:9',
+          })
+
+          const providers = makeProviders({
+            fetchImpl: fetch,
+            resolveKey: (id) => resolveApiKey(cfg, id),
+            cfg,
+          })
+          const fallbackChain = resolveFallbackChain(activeProvider, cfg)
+          const aspectPixels = ASPECT_RATIOS[plan.aspectRatio] || ASPECT_RATIOS['16:9']
+
+          const jobPayload = {
+            prompt: plan.prompt,
+            negativePrompt: plan.negativePrompt,
+            aspectRatio: plan.aspectRatio,
+            aspectPixels,
+            format: 'png',
+            seed,
+            quality: 'high',
+          }
+
+          const { result: genResult, provider: usedProvider } = await executeWithFallback(
+            fallbackChain,
+            providers,
+            jobPayload,
+            { signal: execCtx?.signal }
+          )
+
+          const outDir = path.resolve(process.cwd(), cfg.outputDir || 'output')
+          await mkdir(outDir, { recursive: true })
+          const timestamp = Date.now()
+          const safeSlug = slugify(args.title || 'architecture-diagram') || 'diagram'
+          const filename = `diagram-3d-${safeSlug}-${timestamp}.png`
+
+          let attachment = null
+          if (genResult.bytes) {
+            const diskPath = path.join(outDir, filename)
+            await writeFile(diskPath, Buffer.from(genResult.bytes))
+            attachment = await saveAttachmentSafe(
+              ctx,
+              Buffer.from(genResult.bytes),
+              'image/png',
+              filename,
+              diskPath
+            )
+          } else if (genResult.url) {
+            attachment = {
+              url: genResult.url,
+              mediaType: 'image/png',
+              filename,
+            }
+          }
+
+          return {
+            title: args.title || 'System Architecture',
+            style: plan.style,
+            aspectRatio: plan.aspectRatio,
+            detectedNodes: plan.parsedNodes,
+            prompt: plan.prompt,
+            seed,
+            provider: usedProvider,
+            attachment,
+            url: attachment?.url,
+            attachmentId: attachment?.attachmentId,
+          }
+        },
+      })
+    )
+  }, 'dsh-image-gen: tool beautify_diagram')
+}

package/lib/tools/generation.js

@@ -41,7 +41,7 @@ import { calculateGenerationCost, recordSpend, assertBudgetAvailable } from '../
 import { trackAndAssertLoopGuard } from '../loop-guard.js'
 import { getCachedGeneration, setCachedGeneration } from '../generation-cache.js'
 import { resolveFallbackChain, executeWithFallback } from '../fallback-router.js'
-import { getSessionAnchor, applyAnchorPromptHints } from '../anchor-helpers.js'
+import { getSessionAnchor, applyAnchorPromptHints, buildFaceConsistencyPrompt } from '../anchor-helpers.js'
 import { enhancePrompt } from '../prompt-enhancer.js'
 import {
   readHistory,
@@ -172,6 +172,14 @@ export function registerGenerationTools(ctx, deps) {
           type: 'number',
           description: 'Optional strength of reference anchor influence (0.1 to 1.0).',
         },
+        face_reference: {
+          type: 'string',
+          description: 'Portrait reference image (URL, local path, or attachment id) for facial identity preservation via FaceID / IP-Adapter (#183).',
+        },
+        face_strength: {
+          type: 'number',
+          description: 'Facial identity similarity weight between 0.1 and 1.0 (default: 0.75).',
+        },
       },
       output: {
         schema: {
@@ -345,7 +353,24 @@ export function registerGenerationTools(ctx, deps) {
         const styleInfo = resolveStylePreset(effectiveStyle, args.negative_prompt, args.guidance_scale)
         let effectivePrompt = styleInfo.promptSuffix ? `${enhanced.prompt}, ${styleInfo.promptSuffix}` : enhanced.prompt
         const activeAnchor = getSessionAnchor(sessionId)
-        if (args.reference_image) {
+        let resolvedFaceRef
+        const faceRefInput = args.face_reference || (activeAnchor && (activeAnchor.mode === 'face' || activeAnchor.mode === 'character') ? activeAnchor.image : undefined)
+        if (faceRefInput) {
+          try {
+            resolvedFaceRef = await resolveSource(ctx, exec, faceRefInput)
+          } catch {
+            resolvedFaceRef = { url: faceRefInput }
+          }
+          const facePlan = buildFaceConsistencyPrompt({
+            prompt: effectivePrompt,
+            faceStrength: args.face_strength || activeAnchor?.strength,
+            characterName: activeAnchor?.label,
+          })
+          effectivePrompt = facePlan.prompt
+          if (facePlan.negativePrompt) {
+            effectiveNegative = effectiveNegative ? `${effectiveNegative}, ${facePlan.negativePrompt}` : facePlan.negativePrompt
+          }
+        } else if (args.reference_image) {
           effectivePrompt = `${effectivePrompt}, visual reference anchor`
         } else if (activeAnchor) {
           effectivePrompt = applyAnchorPromptHints(activeAnchor, effectivePrompt)
@@ -373,7 +398,7 @@ export function registerGenerationTools(ctx, deps) {
         assertBudgetAvailable(estimatedCost, cfg.dailyBudgetUsd)
         const providers = makeProviders(
           { fetchImpl: fetch, resolveKey: (ref) => resolveApiKey(ctx, ref), cfg, subscriptionImages },
-          { prompt: effectivePrompt, size, format, seed: args.seed, signal: exec.signal, negativePrompt: effectiveNegative, guidanceScale: effectiveGuidance, source, mask, strength: args.strength, quality: args.quality, style: args.style, aspectPixels, aspectRatio: args.aspect_ratio },
+          { prompt: effectivePrompt, size, format, seed: args.seed, signal: exec.signal, negativePrompt: effectiveNegative, guidanceScale: effectiveGuidance, source, mask, strength: args.strength, quality: args.quality, style: args.style, aspectPixels, aspectRatio: args.aspect_ratio, faceReference: resolvedFaceRef },
         )
       // Subscription providers return {ok:false, reason} instead of throwing:
       // rejection reaches the model as text. Without this guard,

package/lib/tools/vision-ocr.js

@@ -0,0 +1,281 @@
+// vision-ocr.js — replace_image_text tool (#180).
+// Seamless text replacement and OCR localization via dsh-vision-bridge & inpainting.
+
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import path from 'node:path'
+import { mkdir, writeFile } from 'node:fs/promises'
+import {
+  ASPECT_RATIOS,
+  makeProviders,
+  saveAttachmentSafe,
+} from '../providers.js'
+import { resolveFallbackChain, executeWithFallback } from '../fallback-router.js'
+import { renderToolOutput } from '../attachment-helper.js'
+import {
+  normalizeBbox,
+  buildTextInpaintMaskSvg,
+  buildTextOverlaySvg,
+} from '../vision-ocr-helpers.js'
+
+export function registerVisionOcrTools(ctx, deps) {
+  const {
+    live,
+    resolveSource,
+    slugify,
+    resolveApiKey,
+  } = deps
+
+  ctx.effect(() => {
+    ctx.tools.register(
+      defineTool({
+        name: 'replace_image_text',
+        description:
+          'Locate text inscriptions on an image via vision OCR, erase them seamlessly via inpainting, '
+          + 'and render translated or replaced typography precisely at the original coordinates.',
+        parameters: {
+          image: {
+            type: 'string',
+            description: 'Source image path, URL, or attachment id (sha256:...) containing text to replace.',
+          },
+          replacements: {
+            type: 'array',
+            description: 'Array of text replacements: [{ find: "Old Text", replace: "Новый Текст", bbox: [x1,y1,x2,y2] }].',
+            items: {
+              type: 'object',
+              additionalProperties: true,
+              properties: {
+                find: { type: 'string', description: 'Original text to locate' },
+                replace: { type: 'string', description: 'New replacement text to render' },
+                bbox: {
+                  type: 'array',
+                  items: { type: 'number' },
+                  description: 'Optional normalized bounding box [x1, y1, x2, y2] (0-1000)',
+                },
+              },
+            },
+          },
+          target_language: {
+            type: 'string',
+            description: 'Language code (e.g. "ru", "en", "zh") for automated text localization.',
+          },
+          font_color: {
+            type: 'string',
+            description: 'Color of replacement typography (hex or CSS color, e.g. "#FFFFFF"). Default: #FFFFFF.',
+          },
+          font_family: {
+            type: 'string',
+            description: 'Font family to render (default: sans-serif).',
+          },
+          inpaint_prompt: {
+            type: 'string',
+            description: 'Prompt guiding the inpainting process to restore background behind erased text.',
+          },
+          provider: {
+            type: 'string',
+            description: 'Optional provider override for inpainting. Defaults to active provider.',
+          },
+        },
+        output: {
+          schema: {
+            type: 'object',
+            additionalProperties: true,
+            properties: {
+              replacedCount: { type: 'integer' },
+              bboxes: {
+                type: 'array',
+                items: {
+                  type: 'array',
+                  items: { type: 'number' },
+                },
+              },
+              inpaintPrompt: { type: 'string' },
+              attachment: {
+                type: 'object',
+                additionalProperties: true,
+                properties: {
+                  attachmentId: { type: 'string' },
+                  url: { type: 'string' },
+                  mediaType: { type: 'string' },
+                  filename: { type: 'string' },
+                },
+              },
+              maskAttachment: {
+                type: 'object',
+                additionalProperties: true,
+              },
+              overlayAttachment: {
+                type: 'object',
+                additionalProperties: true,
+              },
+            },
+          },
+          render: (result, renderCtx) =>
+            renderToolOutput(result, renderCtx, {
+              title: (res) => `Text Replaced (${res.replacedCount || 0} inscriptions)`,
+              subtitle: (res) => (res.bboxes?.length ? `Detected regions: ${res.bboxes.length}` : ''),
+            }),
+        },
+        async execute(args, execCtx) {
+          const cfg = live?.value || (typeof live === 'function' ? live() : {})
+          const activeProvider = args.provider || cfg.activeProvider || 'fal'
+
+          const source = await resolveSource(ctx, execCtx, args.image)
+          if (!source || !source.bytes) {
+            throw new Error(`Unable to resolve source image for text replacement: ${args.image}`)
+          }
+
+          const imgWidth = source.width || 1024
+          const imgHeight = source.height || 1024
+
+          // 1. Gather text items and bounding boxes
+          const replacements = Array.isArray(args.replacements) ? args.replacements : []
+          const bboxes = []
+          const overlayItems = []
+
+          for (const item of replacements) {
+            let bbox = item.bbox
+            if (!bbox && item.find && ctx.tools?.get) {
+              const groundTool = ctx.tools.get('vision_ground')
+              if (groundTool && typeof groundTool.execute === 'function' && source.ref) {
+                try {
+                  const gRes = await groundTool.execute({
+                    attachmentId: source.ref.startsWith('sha256:') ? source.ref : undefined,
+                    target: `text "${item.find}"`,
+                  }, execCtx)
+                  if (gRes?.bbox && gRes.bbox.length === 4) {
+                    bbox = gRes.bbox
+                  }
+                } catch {
+                  // non-fatal vision_ground fallback
+                }
+              }
+            }
+
+            // Fallback default bounding box if detection didn't locate exact coordinates
+            const normalizedBox = normalizeBbox(bbox || [200, 400, 800, 500], imgWidth, imgHeight)
+            if (normalizedBox) {
+              bboxes.push(normalizedBox)
+              overlayItems.push({
+                text: item.replace || item.find,
+                bbox: normalizedBox,
+                color: args.font_color || '#FFFFFF',
+              })
+            }
+          }
+
+          // If no replacements specified, check default center title box
+          if (bboxes.length === 0) {
+            const defaultBox = [150, 420, 850, 520]
+            bboxes.push(defaultBox)
+            overlayItems.push({
+              text: args.target_language === 'ru' ? 'Заголовок' : 'Localized Text',
+              bbox: defaultBox,
+              color: args.font_color || '#FFFFFF',
+            })
+          }
+
+          // 2. Generate inpaint mask
+          const maskSvg = buildTextInpaintMaskSvg(imgWidth, imgHeight, bboxes, 12)
+          const maskBuffer = Buffer.from(maskSvg, 'utf8')
+
+          // 3. Generate typography overlay SVG
+          const overlaySvg = buildTextOverlaySvg(imgWidth, imgHeight, overlayItems, args.font_family || 'sans-serif')
+          const overlayBuffer = Buffer.from(overlaySvg, 'utf8')
+
+          // 4. Inpaint to erase old text
+          const inpaintPrompt = args.inpaint_prompt || 'clean seamless surface, erase text artifacts, coherent background texture'
+          const providers = makeProviders({
+            fetchImpl: fetch,
+            resolveKey: (id) => resolveApiKey(cfg, id),
+            cfg,
+          })
+          const fallbackChain = resolveFallbackChain(activeProvider, cfg)
+
+          const inpaintJob = {
+            prompt: inpaintPrompt,
+            source: {
+              bytes: source.bytes,
+              mediaType: source.mediaType || 'image/png',
+            },
+            mask: {
+              bytes: maskBuffer,
+              mediaType: 'image/svg+xml',
+            },
+            strength: 0.95,
+            format: 'png',
+          }
+
+          let inpaintedBytes = null
+          let inpaintedUrl = null
+          try {
+            const { result: inpaintResult } = await executeWithFallback(
+              fallbackChain,
+              providers,
+              inpaintJob,
+              { signal: execCtx?.signal }
+            )
+            inpaintedBytes = inpaintResult.bytes
+            inpaintedUrl = inpaintResult.url
+          } catch {
+            // If inpaint provider unavailable, keep source bytes and proceed with overlay
+            inpaintedBytes = source.bytes
+          }
+
+          const outDir = path.resolve(process.cwd(), cfg.outputDir || 'output')
+          await mkdir(outDir, { recursive: true })
+          const timestamp = Date.now()
+          const safeSlug = slugify(args.image.slice(0, 20)) || 'localized-image'
+
+          let attachment = null
+          if (inpaintedBytes) {
+            const filename = `text-replaced-${safeSlug}-${timestamp}.png`
+            const diskPath = path.join(outDir, filename)
+            await writeFile(diskPath, Buffer.from(inpaintedBytes))
+            attachment = await saveAttachmentSafe(
+              ctx,
+              Buffer.from(inpaintedBytes),
+              'image/png',
+              filename,
+              diskPath
+            )
+          } else if (inpaintedUrl) {
+            attachment = {
+              url: inpaintedUrl,
+              mediaType: 'image/png',
+              filename: `text-replaced-${safeSlug}-${timestamp}.png`,
+            }
+          }
+
+          const maskFilename = `mask-text-${safeSlug}-${timestamp}.svg`
+          const maskAttachment = await saveAttachmentSafe(
+            ctx,
+            maskBuffer,
+            'image/svg+xml',
+            maskFilename,
+            path.join(outDir, maskFilename)
+          )
+
+          const overlayFilename = `overlay-text-${safeSlug}-${timestamp}.svg`
+          const overlayAttachment = await saveAttachmentSafe(
+            ctx,
+            overlayBuffer,
+            'image/svg+xml',
+            overlayFilename,
+            path.join(outDir, overlayFilename)
+          )
+
+          return {
+            replacedCount: overlayItems.length,
+            bboxes,
+            inpaintPrompt,
+            attachment,
+            maskAttachment,
+            overlayAttachment,
+            url: attachment?.url,
+            attachmentId: attachment?.attachmentId,
+          }
+        },
+      })
+    )
+  }, 'dsh-image-gen: tool replace_image_text')
+}