@goodandready/dsh-image-gen 0.11.11 → 0.11.13

package/README.md

@@ -167,6 +167,14 @@
 * **Cache & History Consistency**: Ensured content-addressed disk cache hits synchronize seamlessly with generation history and sidecar metadata.
 * **Test Suite Expansion**: Added `test/batch4-hardening.test.mjs`, expanding test coverage to **128 automated unit tests (100% pass)**.
 
+### 🚀 What's New in v0.11.12
+* **Character Sheet Generator (`generate_character_sheet`, #181)**: Synthesizes consistent character turnaround and model sheets (1x3, 2x2, emotions) preserving facial features and attire across anime, 3D, concept, and comic styles.
+* **FaceID & Portrait Consistency (`face_reference`, #183)**: FaceID / IP-Adapter prompt directives and `face` anchor mode in `set_style_anchor` for persistent facial likeness across scenes.
+* **OCR Localization & Text Replacement (`replace_image_text`, #180)**: Automated OCR text detection via `dsh-vision-bridge`, seamless background inpainting, and crisp typography replacement at original coordinates.
+* **3D Isometric Diagram Beautifier (`beautify_diagram`, #185)**: Converts raw Mermaid/Graphviz architecture diagrams into stunning 3D isometric tech illustrations for documentation and hero headers.
+* **Interactive Inpainting Canvas (#328)**: In-chat masking overlay with aspect ratio auto-detection, adjustable brush/eraser, and direct prompt dispatch.
+* **Live Progress Stream (#329)**: Real-time progress bar, stage indicators, and denoising step counters in `FalImageCard`.
+
 ### 🚀 What's New in v0.11.9
 * **ComfyUI Local Backend Payload Fix (#322, GitHub #7)**: Eliminated redundant nesting in `lib/providers/backends/local.js` that wrapped workflows as `{ prompt: { prompt: workflowGraph } }`, resolving `missing_node_type: Node 'ID #prompt' has no class_type` HTTP 400 errors during local ComfyUI generations. Added node shape validation before submission.
 

package/lib/anchor-helpers.js

@@ -1,9 +1,9 @@
-// anchor-helpers.js — Character & Style Reference Anchor manager (#283).
+// anchor-helpers.js — Character & Style Reference Anchor manager (#283, #183).
 // Maintains active visual identity and style reference across multi-turn sessions.
 
 /**
  * In-memory registry of active visual anchors keyed by scopeId (e.g. session id).
- * Structure: Map<string, { image: string, label: string, mode: 'character'|'style', strength: number, updatedAt: string }>
+ * Structure: Map<string, { image: string, label: string, mode: 'character'|'style'|'face', strength: number, updatedAt: string }>
  */
 const sessionAnchors = new Map()
 
@@ -11,10 +11,11 @@ const sessionAnchors = new Map()
  * Normalizes anchor strength between 0.1 and 1.0.
  *
  * @param {number|undefined} val
+ * @param {number} [defaultVal=0.65]
  * @returns {number}
  */
-export function normalizeAnchorStrength(val) {
-  if (typeof val !== 'number' || Number.isNaN(val)) return 0.65
+export function normalizeAnchorStrength(val, defaultVal = 0.65) {
+  if (typeof val !== 'number' || Number.isNaN(val)) return defaultVal
   return Math.min(1.0, Math.max(0.1, Number(val.toFixed(2))))
 }
 
@@ -25,7 +26,7 @@ export function normalizeAnchorStrength(val) {
  * @param {object} data
  * @param {string} data.image Image URL, attachment ID (sha256:...), or local path
  * @param {string} [data.label] Human-readable description of character/style
- * @param {'character'|'style'} [data.mode='style']
+ * @param {'character'|'style'|'face'} [data.mode='style']
  * @param {number} [data.strength=0.65]
  * @returns {object} The stored anchor record
  */
@@ -35,9 +36,11 @@ export function setSessionAnchor(scopeId, data = {}) {
     throw new Error('An anchor image (URL, path, or attachment ID) is required.')
   }
 
-  const mode = data.mode === 'character' ? 'character' : 'style'
-  const strength = normalizeAnchorStrength(data.strength)
-  const label = String(data.label || (mode === 'character' ? 'Character Anchor' : 'Style Anchor')).trim()
+  const mode = data.mode === 'character' || data.mode === 'face' ? data.mode : 'style'
+  const defaultStrength = mode === 'face' || mode === 'character' ? 0.75 : 0.65
+  const strength = normalizeAnchorStrength(data.strength, defaultStrength)
+  const defaultLabel = mode === 'face' ? 'Portrait Reference' : (mode === 'character' ? 'Character Anchor' : 'Style Anchor')
+  const label = String(data.label || defaultLabel).trim()
 
   const anchor = {
     image: String(data.image).trim(),
@@ -95,9 +98,35 @@ export function applyAnchorPromptHints(anchor, prompt) {
   // Avoid duplicate injection if user already mentioned the anchor label
   if (lower.includes(labelLower)) return prompt
 
-  if (anchor.mode === 'character') {
+  if (anchor.mode === 'face' || anchor.mode === 'character') {
     return `${prompt}, visual character anchor: ${anchor.label}, maintaining consistent facial features, costume, and physical identity`
   }
 
   return `${prompt}, visual style anchor: ${anchor.label}, maintaining consistent aesthetic palette, rendering technique, and lighting`
 }
+
+/**
+ * Builds prompt directives for FaceID / IP-Adapter portrait consistency (#183).
+ *
+ * @param {object} options
+ * @param {string} options.prompt Core scene description
+ * @param {number} [options.faceStrength=0.75] Identity preservation weight (0.1 - 1.0)
+ * @param {string} [options.characterName] Optional character identifier
+ * @returns {{ prompt: string, negativePrompt: string, faceStrength: number }}
+ */
+export function buildFaceConsistencyPrompt(options = {}) {
+  const basePrompt = String(options.prompt || '').trim()
+  const faceStrength = normalizeAnchorStrength(options.faceStrength, 0.75)
+  const nameSuffix = options.characterName ? ` of ${options.characterName}` : ''
+
+  const faceDirective = `FaceID facial identity match${nameSuffix} (strength: ${faceStrength}), preserving exact facial structure, eye shape, nose, lips, jawline and recognizable facial landmarks from portrait reference`
+  const combinedPrompt = basePrompt ? `${basePrompt}, ${faceDirective}` : faceDirective
+
+  const faceNegative = 'altered face, different face, distorted facial features, asymmetric eyes, morphed facial landmarks, low facial detail, blurry face'
+
+  return {
+    prompt: combinedPrompt,
+    negativePrompt: faceNegative,
+    faceStrength,
+  }
+}

package/lib/character-sheet-helpers.js

@@ -0,0 +1,115 @@
+// character-sheet-helpers.js — helper functions for character_sheet_generator tool (#181).
+
+export const CHARACTER_SHEET_LAYOUTS = {
+  turnaround: {
+    name: 'turnaround',
+    label: 'Full Turnaround (4-view horizontal)',
+    aspectRatio: '16:9',
+    views: ['front view', 'side profile view', 'three-quarter view', 'back view'],
+    directive: 'full character turnaround sheet showing multiple sequential angles: front view, side profile view, three-quarter view, and back view arranged horizontally',
+  },
+  '1x3': {
+    name: '1x3',
+    label: 'Triptych (Front, Side, Back)',
+    aspectRatio: '16:9',
+    views: ['front view', 'side view', 'back view'],
+    directive: 'character model sheet with 3 full-body views: front view, side view, back view side-by-side',
+  },
+  '2x2': {
+    name: '2x2',
+    label: 'Quad Grid (2x2 Multi-Angle)',
+    aspectRatio: '1:1',
+    views: ['front view', 'three-quarter view', 'close-up portrait', 'back view'],
+    directive: '2x2 character reference sheet grid featuring: top-left front view, top-right three-quarter view, bottom-left close-up facial portrait, bottom-right back view',
+  },
+  emotions: {
+    name: 'emotions',
+    label: 'Facial Expression Sheet (4 Expressions)',
+    aspectRatio: '1:1',
+    views: ['neutral', 'happy / smiling', 'focused / intense', 'shocked / surprised'],
+    directive: 'character facial expression sheet displaying identical character with 4 distinct expressions: neutral, happy/smiling, focused/intense, and surprised',
+  },
+}
+
+export const CHARACTER_SHEET_STYLES = {
+  concept_art: {
+    name: 'concept_art',
+    label: 'Digital Concept Art',
+    directive: 'digital concept art, character model sheet, clean sharp silhouette, production reference, ArtStation featured',
+  },
+  anime: {
+    name: 'anime',
+    label: 'Anime & Manga',
+    directive: 'clean modern anime production sheet, precise lineart, cel-shaded coloring, animation design document',
+  },
+  '3d_animation': {
+    name: '3d_animation',
+    label: '3D Feature Film CGI',
+    directive: '3D animated feature film character model, subsurface scattering, Octane render, Pixar/Dreamworks aesthetic, cinematic lighting',
+  },
+  pixel_art: {
+    name: 'pixel_art',
+    label: '16-bit Pixel Art',
+    directive: 'crisp 16-bit pixel art character design sheet, game asset sprite reference, clean pixel clusters, retro aesthetic',
+  },
+  realistic: {
+    name: 'realistic',
+    label: 'Cinematic Photorealism',
+    directive: 'cinematic studio photography, detailed skin texture, 85mm lens, neutral gray studio backdrop, master lighting',
+  },
+  comic: {
+    name: 'comic',
+    label: 'Graphic Novel / Comic',
+    directive: 'graphic novel art style, dynamic ink lines, bold cross-hatching, rich comic book color palette',
+  },
+}
+
+/**
+ * Builds the specialized prompt for generating consistent character sheets.
+ *
+ * @param {object} options
+ * @param {string} options.prompt Base character description
+ * @param {string} [options.layout] 'turnaround' | '1x3' | '2x2' | 'emotions'
+ * @param {string} [options.style] Style preset key
+ * @param {string} [options.negativePrompt] Optional negative directives
+ * @returns {{ prompt: string, negativePrompt: string, aspectRatio: string, views: string[] }}
+ */
+export function buildCharacterSheetPrompt(options = {}) {
+  const baseDesc = String(options.prompt || '').trim()
+  if (!baseDesc) {
+    throw new Error('Character description prompt is required for character sheet generation')
+  }
+
+  const layoutKey = options.layout && CHARACTER_SHEET_LAYOUTS[options.layout]
+    ? options.layout
+    : 'turnaround'
+  const layoutDef = CHARACTER_SHEET_LAYOUTS[layoutKey]
+
+  const styleKey = options.style && CHARACTER_SHEET_STYLES[options.style]
+    ? options.style
+    : 'concept_art'
+  const styleDef = CHARACTER_SHEET_STYLES[styleKey]
+
+  const consistencyAnchor = 'single unified character sheet, identical person across all angles, same facial features, same hairstyle, identical outfit and colors, consistent proportions, neutral neutral background'
+
+  const finalPrompt = [
+    layoutDef.directive,
+    `Character: ${baseDesc}`,
+    styleDef.directive,
+    consistencyAnchor,
+  ].filter(Boolean).join(', ')
+
+  const defaultNegative = 'different characters, inconsistent face, mismatched clothing, cropped limbs, cluttered background, chaotic layout, watermark, low quality, distorted anatomy'
+  const finalNegative = options.negativePrompt
+    ? `${defaultNegative}, ${options.negativePrompt}`
+    : defaultNegative
+
+  return {
+    prompt: finalPrompt,
+    negativePrompt: finalNegative,
+    aspectRatio: layoutDef.aspectRatio,
+    views: layoutDef.views,
+    layout: layoutKey,
+    style: styleKey,
+  }
+}

package/lib/client.js

@@ -140,6 +140,12 @@ window.__ModuleLoader__.load({
 .ig-progressive-wrap{position:relative;width:100%;overflow:hidden;border-radius:8px;border:1px solid var(--dsw-alias-border-l2);background:var(--dsw-alias-bg-layer-2);min-height:160px;display:flex;align-items:center;justify-content:center}
 .ig-draft-img{position:absolute;inset:0;width:100%;height:100%;object-fit:contain;filter:blur(6px);opacity:0.75;transform:scale(1.02);transition:opacity 0.4s ease}
 .ig-final-img{position:relative;width:100%;height:auto;display:block;opacity:1;transition:opacity 0.35s ease}
+
+.ig-progress-container{display:flex;flex-direction:column;gap:5px;padding:8px 10px;background:var(--dsw-alias-bg-layer-2);border:1px solid var(--dsw-alias-border-l2);border-radius:8px;margin-top:6px}
+.ig-progress-meta{display:flex;justify-content:space-between;align-items:center;font-size:11px;color:var(--dsw-alias-label-secondary);font-weight:500}
+.ig-progress-track{height:6px;width:100%;background:var(--dsw-alias-bg-layer-1);border-radius:3px;overflow:hidden;position:relative}
+.ig-progress-fill{height:100%;background:var(--dsw-alias-state-brand);border-radius:3px;transition:width 0.25s ease-in-out}
+
 .ig-draft-overlay{position:absolute;bottom:8px;left:8px;padding:3px 8px;border-radius:4px;background:color-mix(in srgb, var(--dsw-alias-bg-layer-1) 80%, transparent);font-size:11px;font-weight:600;color:var(--dsw-alias-label-primary);display:flex;align-items:center;gap:6px;backdrop-filter:blur(4px)}
 
 @media (prefers-reduced-motion: reduce){
@@ -1543,6 +1549,9 @@ window.__ModuleLoader__.load({
           src: displaySrc,
           draftSrc,
           isRunning: running,
+          progress: typeof parsed?.progress === 'number' ? parsed.progress : (typeof block?.progress === 'number' ? block.progress : undefined),
+          step: parsed?.step || block?.step,
+          stage: parsed?.stage || block?.stage,
           alt: prompt || 'generated image',
           t,
         }))
@@ -1645,6 +1654,8 @@ window.__ModuleLoader__.load({
         react,
         t,
         parsed,
+        imgUrl: parsed.imageUrl || parsed.url || parsed.attachment?.url,
+        targetRef: parsed.attachmentId || parsed.attachment?.attachmentId || parsed.imageUrl || parsed.url,
         onClose: () => setInpaintOpen(false),
       }) : null
 
@@ -1710,11 +1721,14 @@ window.__ModuleLoader__.load({
           current.seed !== undefined ? `seed: ${current.seed}` : (current.timestamp ? new Date(current.timestamp).toLocaleTimeString() : '')
         )
       )
-    }    // -------------------------------------------------------------- Progressive Draft Preview (#147)
+    }    // -------------------------------------------------------------- Progressive Draft & Live Progress Preview (#147, #329)
     function ProgressiveImagePreview(props) {
       const src = props.src
       const draftSrc = props.draftSrc
       const isRunning = props.isRunning
+      const progress = typeof props.progress === 'number' ? Math.min(100, Math.max(0, props.progress)) : undefined
+      const step = props.step
+      const stage = props.stage || (progress !== undefined && progress < 100 ? 'Rendering...' : 'Complete')
       const alt = props.alt || 'Generated image'
       const t = props.t || ((k) => k)
 
@@ -1724,7 +1738,28 @@ window.__ModuleLoader__.load({
         setLoaded(false)
       }, [src])
 
-      if (isRunning && !src && draftSrc) {
+      const showProgress = isRunning || (progress !== undefined && progress < 100)
+
+      const progressElement = showProgress ? react.createElement(
+        'div',
+        { className: 'ig-progress-container' },
+        react.createElement(
+          'div',
+          { className: 'ig-progress-meta' },
+          react.createElement('span', null, '⚡ ' + stage + (step ? ' (' + step + ')' : '')),
+          progress !== undefined ? react.createElement('span', { style: { fontWeight: '700', color: 'var(--dsw-alias-state-brand)' } }, Math.round(progress) + '%') : null
+        ),
+        react.createElement(
+          'div',
+          { className: 'ig-progress-track' },
+          react.createElement('div', {
+            className: 'ig-progress-fill',
+            style: { width: (progress !== undefined ? progress : 45) + '%' },
+          })
+        )
+      ) : null
+
+      if (showProgress && !src && draftSrc) {
         return react.createElement(
           'div',
           { className: 'ig-progressive-wrap' },
@@ -1737,10 +1772,15 @@ window.__ModuleLoader__.load({
             'div',
             { className: 'ig-draft-overlay' },
             '⚡ ' + (t('card.draftPreview') || 'Rendering draft...')
-          )
+          ),
+          progressElement
         )
       }
 
+      if (!src && !draftSrc && showProgress) {
+        return progressElement
+      }
+
       if (!src && !draftSrc) return null
 
       return react.createElement(
@@ -1758,12 +1798,14 @@ window.__ModuleLoader__.load({
           className: 'ig-final-img',
           style: { opacity: loaded || !draftSrc ? 1 : 0.8 },
           onLoad: () => setLoaded(true),
-        }) : null
+        }) : null,
+        progressElement
       )
-    }// 105-inpaint-canvas.js — Interactive in-chat canvas drawing overlay for inpainting (#285, #301).
+    }
+// 105-inpaint-canvas.js — Interactive in-chat canvas drawing overlay for inpainting (#285, #301, #328).
 
     function InpaintCanvas(props) {
-      const { imgUrl, targetRef, onClose, t } = props
+      const { imgUrl, targetRef, parsed, onClose, t } = props
       const canvasRef = react.useRef(null)
       const isDrawingRef = react.useRef(false)
       const undoStackRef = react.useRef([])
@@ -1772,6 +1814,10 @@ window.__ModuleLoader__.load({
       const [hasStrokes, setHasStrokes] = react.useState(false)
       const [copied, setCopied] = react.useState(false)
       const [inpaintPrompt, setInpaintPrompt] = react.useState('')
+      const [canvasDims, setCanvasDims] = react.useState({ width: 512, height: 512, ratio: '1/1' })
+
+      const effectiveImgUrl = imgUrl || parsed?.imageUrl || parsed?.url || parsed?.attachment?.url || ''
+      const effectiveTargetRef = targetRef || parsed?.attachmentId || parsed?.attachment?.attachmentId || parsed?.imageUrl || parsed?.url || 'current image'
 
       const initCanvas = react.useCallback(() => {
         const canvas = canvasRef.current
@@ -1785,7 +1831,19 @@ window.__ModuleLoader__.load({
 
       react.useEffect(() => {
         initCanvas()
-      }, [initCanvas])
+      }, [initCanvas, canvasDims])
+
+      function handleImageLoaded(e) {
+        if (e.target && e.target.naturalWidth && e.target.naturalHeight) {
+          const nw = e.target.naturalWidth
+          const nh = e.target.naturalHeight
+          // Scale dimensions down to manageable working canvas size (max 768)
+          const scale = Math.min(1, 768 / Math.max(nw, nh))
+          const cw = Math.round(nw * scale)
+          const ch = Math.round(nh * scale)
+          setCanvasDims({ width: cw, height: ch, ratio: `${cw}/${ch}` })
+        }
+      }
 
       function getPos(e, canvas) {
         const rect = canvas.getBoundingClientRect()
@@ -1902,13 +1960,21 @@ window.__ModuleLoader__.load({
         if (!canvas) return
         const maskDataUrl = canvas.toDataURL('image/png')
         const promptText = inpaintPrompt.trim() || 'inpaint masked region'
-        const instruction = 'Use edit_image with prompt: "' + promptText + '", source_image: "' + targetRef + '", mask: "' + maskDataUrl + '"'
+        const instruction = 'Use edit_image with prompt: "' + promptText + '", source_image: "' + effectiveTargetRef + '", mask: "' + maskDataUrl + '"'
 
         if (typeof navigator !== 'undefined' && navigator.clipboard) {
           navigator.clipboard.writeText(instruction)
           setCopied(true)
           setTimeout(() => setCopied(false), 2500)
         }
+
+        try {
+          const textarea = document.querySelector('textarea[placeholder*="message"], textarea[class*="chat"], textarea')
+          if (textarea) {
+            textarea.value = instruction
+            if (typeof window !== 'undefined' && typeof window.Event === 'function') textarea.dispatchEvent(new window.Event('input', { bubbles: true }))
+          }
+        } catch (_err) { /* non-fatal: optional textarea dispatch */ }
       }
 
       return react.createElement(
@@ -2004,7 +2070,7 @@ window.__ModuleLoader__.load({
               position: 'relative',
               width: '100%',
               maxWidth: '512px',
-              aspectRatio: '1/1',
+              aspectRatio: canvasDims.ratio,
               borderRadius: '8px',
               overflow: 'hidden',
               border: '1px solid var(--dsw-alias-border-l2)',
@@ -2014,9 +2080,10 @@ window.__ModuleLoader__.load({
               touchAction: 'none',
             },
           },
-          imgUrl ? react.createElement('img', {
-            src: imgUrl,
+          effectiveImgUrl ? react.createElement('img', {
+            src: effectiveImgUrl,
             alt: 'Source for Inpaint',
+            onLoad: handleImageLoaded,
             style: {
               position: 'absolute',
               top: 0,
@@ -2030,8 +2097,8 @@ window.__ModuleLoader__.load({
           }) : null,
           react.createElement('canvas', {
             ref: canvasRef,
-            width: 512,
-            height: 512,
+            width: canvasDims.width,
+            height: canvasDims.height,
             style: {
               position: 'absolute',
               top: 0,
@@ -3009,6 +3076,12 @@ window.__ModuleLoader__.load({
         'smart_crop_image',
         'export_asset_pack',
         'generate_ui_asset',
+        'generate_character_sheet',
+        'replace_image_text',
+        'beautify_diagram',
+        'generate_seamless_pattern',
+        'generate_spritesheet',
+        'sketch_to_image',
       ]
 
       for (const toolName of toolviewTools) {

package/lib/diagram-helpers.js

@@ -0,0 +1,105 @@
+// diagram-helpers.js — helper functions for beautify_diagram tool (#185).
+
+export const DIAGRAM_3D_STYLES = {
+  isometric_3d: {
+    name: 'isometric_3d',
+    label: 'Glossy 3D Isometric Architecture',
+    directive: 'ultra-detailed 3D isometric architecture visualization, floating frosted glassmorphism node panels, luminous glowing neon data pipelines, soft ambient occlusion, Octane 3D render, tech presentation hero graphic',
+  },
+  cyber_blueprint: {
+    name: 'cyber_blueprint',
+    label: 'Holographic Cyber Blueprint',
+    directive: 'holographic 3D engineering schematic, isometric grid perspective, glowing cyan and amber circuit traces, semi-transparent HUD modules, high-tech enterprise infrastructure',
+  },
+  clay_minimal: {
+    name: 'clay_minimal',
+    label: 'Minimalist Tactile Clay Render',
+    directive: 'minimalist 3D isometric clay render, smooth matte ceramic node blocks, soft directional studio lighting, elegant pastel palette on clean backdrop, tactile editorial illustration',
+  },
+  glossy_dark: {
+    name: 'glossy_dark',
+    label: 'Obsidian Glass Dark Mode',
+    directive: 'dark obsidian glassmorphic 3D diagram, luminous neon accent borders, dark slate background, glowing fiber-optic connectors, enterprise cloud architecture showcase',
+  },
+}
+
+/**
+ * Extracts nodes and connections from raw Mermaid or Graphviz diagram text.
+ *
+ * @param {string} sourceCode
+ * @returns {{ nodes: string[], connections: string[], summary: string }}
+ */
+export function parseMermaidStructure(sourceCode = '') {
+  const text = String(sourceCode).trim()
+  if (!text) {
+    return { nodes: [], connections: [], summary: 'generic multi-tiered system topology' }
+  }
+
+  const nodes = new Set()
+  const connections = []
+
+  // Extract node labels inside brackets: A[Client App], B(API Gateway), C[(Database)]
+  const bracketMatches = text.matchAll(/([A-Za-z0-9_]+)\s*(\[|\(|\{\[|\(\[)([\s\S]*?)(\]|\)|\}\]|\)\])/g)
+  for (const m of bracketMatches) {
+    const label = m[3]?.replace(/^[\(\[\{]+|[\)\]\}]+$/g, '').trim()
+    if (label && label.length < 50) {
+      nodes.add(label)
+    }
+  }
+
+  // Extract connection arrows: -->, ==>, -.->
+  const arrowLines = text.split('\n').filter((l) => l.includes('-->') || l.includes('==>') || l.includes('-.->'))
+  for (const line of arrowLines.slice(0, 10)) {
+    const cleaned = line.replace(/\[.*?\]|\(.*?\)/g, '').trim()
+    if (cleaned) connections.push(cleaned)
+  }
+
+  const nodeList = Array.from(nodes)
+  let summary = ''
+  if (nodeList.length > 0) {
+    summary = `nodes representing ${nodeList.slice(0, 6).join(', ')} connected in structured data flow`
+  } else {
+    summary = 'structured multi-node architectural graph showing sequential service pipelines'
+  }
+
+  return {
+    nodes: nodeList,
+    connections,
+    summary,
+  }
+}
+
+/**
+ * Builds the prompt for beautify_diagram image synthesis.
+ *
+ * @param {object} options
+ * @param {string} options.diagram Raw Mermaid code, SVG, or description
+ * @param {string} [options.style] Style preset key from DIAGRAM_3D_STYLES
+ * @param {string} [options.title] Optional main title
+ * @param {string} [options.aspectRatio='16:9']
+ * @returns {{ prompt: string, negativePrompt: string, style: string, parsedNodes: string[] }}
+ */
+export function buildDiagramIllustrationPrompt(options = {}) {
+  const { diagram, style = 'isometric_3d', title, aspectRatio = '16:9' } = options
+  const styleDef = DIAGRAM_3D_STYLES[style] || DIAGRAM_3D_STYLES.isometric_3d
+
+  const parsed = parseMermaidStructure(diagram)
+  const titlePart = title ? `titled "${title}", ` : ''
+
+  const corePrompt = [
+    `high-end 3D architectural illustration ${titlePart}`,
+    `depicting ${parsed.summary}`,
+    styleDef.directive,
+    'clean isometric angle, centered composition, pristine technical depth, 8k resolution, suitable for developer documentation and hero banner',
+  ].filter(Boolean).join(', ')
+
+  const negativePrompt = 'messy handwriting, scribbles, low resolution, 2D flat wireframe, unreadable blurry text, broken geometry, chaotic distortion, watermark'
+
+  return {
+    prompt: corePrompt,
+    negativePrompt,
+    style: styleDef.name,
+    parsedNodes: parsed.nodes,
+    aspectRatio,
+  }
+}

package/lib/index.js

@@ -312,7 +312,10 @@ export function apply(ctx, rawConfig) {
       }
       try {
         const u = new URL(req.url, 'http://localhost')
-        const provider = u.searchParams.get('provider') || config.provider || 'fal'
+        const qProvider = u.searchParams.get('provider')
+        const provider = (typeof qProvider === 'string' && qProvider.trim())
+          || (typeof config?.provider === 'string' && config.provider.trim())
+          || 'fal'
         const deps = {
           fetchImpl: fetch,
           resolveKey: (ref) => resolveApiKey(ctx, ref),

package/lib/providers.js

@@ -378,7 +378,7 @@ export async function blendImagesFal({ fetchImpl, resolveKey, cfg }, { images, w
 /** @internal — direct provider call path for integration tests */
 export async function editImageDirect(deps, job) {
   const providers = makeProviders(deps, job)
-  const providerKey = job.provider || deps.cfg.defaultProvider || 'fal'
+  const providerKey = (typeof job?.provider === 'string' && job.provider.trim()) || (typeof deps?.cfg?.provider === 'string' && deps.cfg.provider.trim()) || (typeof deps?.cfg?.defaultProvider === 'string' && deps.cfg.defaultProvider.trim()) || 'fal'
   const fn = providers[providerKey] || providers.fal || providers.custom
   if (!fn) throw new Error(`Provider "${providerKey}" does not support image editing`)
   return fn(job.seed, job.prompt)
@@ -391,7 +391,7 @@ export async function varyImageDirect(deps, job) {
     ...job,
     strength: job.variationStrength ?? job.strength ?? 0.35,
   })
-  const providerKey = job.provider || deps.cfg.defaultProvider || 'fal'
+  const providerKey = (typeof job?.provider === 'string' && job.provider.trim()) || (typeof deps?.cfg?.provider === 'string' && deps.cfg.provider.trim()) || (typeof deps?.cfg?.defaultProvider === 'string' && deps.cfg.defaultProvider.trim()) || 'fal'
   const fn = providers[providerKey] || providers.fal || providers.custom
   if (!fn) throw new Error(`Provider "${providerKey}" does not support image variations`)
   return fn(job.seed, job.prompt)
@@ -428,7 +428,11 @@ export function toLosslessJson(val) {
 export async function testProviderConnection(deps, providerId) {
   const { fetchImpl = fetch, resolveKey, cfg } = deps
   const start = Date.now()
-  const p = (providerId || cfg.defaultProvider || 'fal').toLowerCase()
+  const rawProvider = (typeof providerId === 'string' && providerId.trim())
+    || (typeof cfg?.provider === 'string' && cfg.provider.trim())
+    || (typeof cfg?.defaultProvider === 'string' && cfg.defaultProvider.trim())
+    || 'fal'
+  const p = rawProvider.toLowerCase()
 
   try {
     if (p === 'fal') {

package/lib/register-tools.js

@@ -15,6 +15,9 @@ import { registerAnchorTools } from './tools/anchor.js'
 import { registerUiAssetTools } from './tools/ui-asset.js'
 import { registerStyleMatrixTools } from './tools/style-matrix.js'
 import { registerThemePairTools } from './tools/theme-pair.js'
+import { registerCharacterSheetTools } from './tools/character-sheet.js'
+import { registerVisionOcrTools } from './tools/vision-ocr.js'
+import { registerDiagramTools } from './tools/diagram.js'
 
 /**
  * Registers every image-gen tool on the host tools service.
@@ -37,4 +40,7 @@ export function registerAllTools(ctx, deps) {
   registerUiAssetTools(ctx, deps)
   registerStyleMatrixTools(ctx, deps)
   registerThemePairTools(ctx, deps)
-}
+  registerCharacterSheetTools(ctx, deps)
+  registerVisionOcrTools(ctx, deps)
+  registerDiagramTools(ctx, deps)
+}

package/lib/security.js

@@ -64,7 +64,8 @@ export function enforceSecurePermissions(filePath) {
   try {
     chmodSync(filePath, 0o600)
     return true
-  } catch {
+  } catch (_err) {
+    /* non-fatal: permission change error */
     return false
   }
 }
@@ -143,7 +144,7 @@ export function extractHostName(hostHeader) {
   try {
     const url = new URL(`http://${trimmed}`)
     return url.hostname.replace(/^\[|\]$/g, '')
-  } catch {
+  } catch (_err) {
     return trimmed.replace(/^\[|\]$/g, '').split(':')[0] || ''
   }
 }
@@ -210,7 +211,7 @@ export function isTrustedLocalRequest(req) {
       if (url.host.toLowerCase() !== host.toLowerCase()) {
         return false
       }
-    } catch {
+    } catch (_err) {
       return false
     }
   }
@@ -226,7 +227,7 @@ export function isTrustedLocalRequest(req) {
       if (!isLoopbackAddress(refererHostName) && !isPrivateLanAddress(refererHostName)) {
         return false
       }
-    } catch {
+    } catch (_err) {
       return false
     }
   }

package/lib/settings-route.js

@@ -79,7 +79,7 @@ export function registerSettingsRoutes(ctx, { live, getSettingsApi, setLiveConfi
       let payload
       try {
         payload = JSON.parse(buf.toString('utf8') || '{}')
-      } catch {
+      } catch (_err) {
         res.writeHead(400, { 'Content-Type': 'application/json' })
         res.end(JSON.stringify({ ok: false, error: 'invalid JSON' }))
         return

package/lib/tools/anchor.js

@@ -30,8 +30,8 @@ export function registerAnchorTools(ctx, deps) {
           },
           mode: {
             type: 'string',
-            enum: ['style', 'character'],
-            description: 'Anchor mode: "character" preserves facial/physical identity; "style" preserves artistic rendering, lighting, and palette. Default: style.',
+            enum: ['style', 'character', 'face'],
+            description: 'Anchor mode: "face" preserves facial portrait identity via FaceID/IP-Adapter; "character" preserves overall character traits; "style" preserves aesthetic palette. Default: style.',
           },
           strength: {
             type: 'number',