image-edit-tools 1.0.5 → 1.0.8

package/dist/utils/font-loader.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Resolves a fontUrl to a local `file://` path usable by librsvg.
+ *
+ * Handles three cases:
+ * - `file://` or absolute path → returned as `file://` URI
+ * - `https://fonts.googleapis.com/css*` → fetches CSS, extracts font URL, downloads binary
+ * - Direct binary URL (`.woff`, `.woff2`, `.ttf`, `.otf`) → downloads and caches
+ *
+ * Cache is stored in `os.tmpdir()` with prefix `iet-font-`. No TTL (font files are immutable).
+ *
+ * @param fontUrl - The font URL to resolve
+ * @returns A `file://` URI pointing to a local font file
+ * @throws {Error} If network fetch fails or CSS contains no font URLs
+ *
+ * @example
+ * // Google Fonts CSS URL
+ * const path = await resolveFontUrl('https://fonts.googleapis.com/css2?family=Jua');
+ * // → 'file:///tmp/iet-font-abcdef1234567890.woff2'
+ *
+ * @example
+ * // Direct font binary URL
+ * const path = await resolveFontUrl('https://example.com/font.woff2');
+ * // → 'file:///tmp/iet-font-0123456789abcdef.woff2'
+ */
+export declare function resolveFontUrl(fontUrl: string): Promise<string>;
+//# sourceMappingURL=font-loader.d.ts.map

package/dist/utils/font-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"font-loader.d.ts","sourceRoot":"","sources":["../../src/utils/font-loader.ts"],"names":[],"mappings":"AAoCA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CA0DrE"}

package/dist/utils/font-loader.js

@@ -0,0 +1,103 @@
+import { createHash } from 'crypto';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { writeFile, access } from 'fs/promises';
+import fetch from 'node-fetch';
+const CACHE_DIR = tmpdir();
+const CACHE_PREFIX = 'iet-font-';
+/**
+ * Generates a deterministic cache file path for a given URL.
+ * Uses SHA-256 hash truncated to 16 hex chars to avoid filename collisions.
+ *
+ * @param url - The font binary URL to hash
+ * @returns Absolute path without extension in the OS temp directory
+ */
+function cacheKey(url) {
+    return join(CACHE_DIR, CACHE_PREFIX + createHash('sha256').update(url).digest('hex').slice(0, 16));
+}
+/**
+ * Extracts the file extension from a URL, stripping query parameters.
+ *
+ * @param url - URL to extract extension from
+ * @returns File extension (e.g. 'woff2', 'ttf') or 'woff2' as default
+ */
+function extractExtension(url) {
+    const lastSegment = url.split('/').pop() ?? '';
+    const withoutQuery = lastSegment.split('?')[0];
+    const ext = withoutQuery.split('.').pop() ?? 'woff2';
+    return ext;
+}
+/**
+ * Resolves a fontUrl to a local `file://` path usable by librsvg.
+ *
+ * Handles three cases:
+ * - `file://` or absolute path → returned as `file://` URI
+ * - `https://fonts.googleapis.com/css*` → fetches CSS, extracts font URL, downloads binary
+ * - Direct binary URL (`.woff`, `.woff2`, `.ttf`, `.otf`) → downloads and caches
+ *
+ * Cache is stored in `os.tmpdir()` with prefix `iet-font-`. No TTL (font files are immutable).
+ *
+ * @param fontUrl - The font URL to resolve
+ * @returns A `file://` URI pointing to a local font file
+ * @throws {Error} If network fetch fails or CSS contains no font URLs
+ *
+ * @example
+ * // Google Fonts CSS URL
+ * const path = await resolveFontUrl('https://fonts.googleapis.com/css2?family=Jua');
+ * // → 'file:///tmp/iet-font-abcdef1234567890.woff2'
+ *
+ * @example
+ * // Direct font binary URL
+ * const path = await resolveFontUrl('https://example.com/font.woff2');
+ * // → 'file:///tmp/iet-font-0123456789abcdef.woff2'
+ */
+export async function resolveFontUrl(fontUrl) {
+    // Already a local path — pass through
+    if (fontUrl.startsWith('file://')) {
+        return fontUrl;
+    }
+    if (fontUrl.startsWith('/')) {
+        return `file://${fontUrl}`;
+    }
+    // Determine the actual binary URL to download
+    let binaryUrl = fontUrl;
+    if (fontUrl.includes('fonts.googleapis.com/css')) {
+        // Google Fonts CSS endpoint — fetch CSS and extract the font binary URL
+        const cssRes = await fetch(fontUrl, {
+            headers: {
+                // Desktop UA ensures we get woff2 (most compact modern format)
+                'User-Agent': 'Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+            },
+        });
+        if (!cssRes.ok) {
+            throw new Error(`Google Fonts CSS fetch failed: ${cssRes.status}`);
+        }
+        const css = await cssRes.text();
+        // Extract all url() references pointing to font binary files
+        const urls = [...css.matchAll(/url\((https[^)]+\.(?:woff2?|ttf|otf)[^)]*)\)/g)].map((m) => m[1]);
+        if (urls.length === 0) {
+            throw new Error('No font URL found in Google Fonts CSS');
+        }
+        // Prefer woff2 for smaller file size, fallback to first match
+        binaryUrl = urls.find((u) => u.endsWith('.woff2')) ?? urls[0];
+    }
+    // Check cache before downloading
+    const ext = extractExtension(binaryUrl);
+    const cacheFile = `${cacheKey(binaryUrl)}.${ext}`;
+    try {
+        await access(cacheFile);
+        // Cache hit
+        return `file://${cacheFile}`;
+    }
+    catch {
+        // Cache miss — download the binary
+        const res = await fetch(binaryUrl);
+        if (!res.ok) {
+            throw new Error(`Font download failed: ${res.status} ${binaryUrl}`);
+        }
+        const buf = Buffer.from(await res.arrayBuffer());
+        await writeFile(cacheFile, buf);
+        return `file://${cacheFile}`;
+    }
+}
+//# sourceMappingURL=font-loader.js.map

package/dist/utils/font-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"font-loader.js","sourceRoot":"","sources":["../../src/utils/font-loader.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "image-edit-tools",
-  "version": "1.0.5",
+  "version": "1.0.8",
   "description": "Deterministic image editing SDK for AI agents. Ships with MCP tools.",
   "author": "swimmingkiim",
   "homepage": "https://github.com/swimmingkiim/image-edit-tools#readme",

package/src/index.ts

@@ -22,3 +22,8 @@ export { detectFaces } from './ops/detect-faces.js';
 export { extractText } from './ops/extract-text.js';
 export { pipeline } from './ops/pipeline.js';
 export { batch } from './ops/batch.js';
+export { rotate } from './ops/rotate.js';
+export { gradientOverlay } from './ops/gradient-overlay.js';
+export { clipToShape } from './ops/clip-to-shape.js';
+export { drawShape } from './ops/draw-shape.js';
+export { dropShadow } from './ops/drop-shadow.js';

package/src/mcp/tools.ts

@@ -219,6 +219,80 @@ export const allTools: Tool[] = [
       },
       required: ['images', 'operation', 'options']
     }
+  },
+  {
+    name: 'image_rotate',
+    description: 'Rotates an image by an arbitrary angle. Exposed areas are transparent by default.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        image: { type: 'string' },
+        angle: { type: 'number', description: 'Rotation angle in degrees (0-360), clockwise' },
+        background: { type: 'string', description: 'Background color for exposed areas. Default: transparent' }
+      },
+      required: ['image', 'angle']
+    }
+  },
+  {
+    name: 'image_gradient_overlay',
+    description: 'Applies a gradient overlay for text readability. Great for placing text over photos.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        image: { type: 'string' },
+        direction: { type: 'string', enum: ['top','bottom','left','right','top-left','top-right','bottom-left','bottom-right'] },
+        color: { type: 'string', description: 'Gradient color. Default: #000000' },
+        opacity: { type: 'number', description: '0-1. Default: 0.7' },
+        coverage: { type: 'number', description: '0-1 how much of image is covered. Default: 0.5' }
+      },
+      required: ['image']
+    }
+  },
+  {
+    name: 'image_clip_to_shape',
+    description: 'Clips an image to a shape: circle, ellipse, or rounded-rect. Perfect for profile photos.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        image: { type: 'string' },
+        shape: { type: 'string', enum: ['circle', 'ellipse', 'rounded-rect'] },
+        borderRadius: { type: 'number', description: 'For rounded-rect. Default: 32' }
+      },
+      required: ['image', 'shape']
+    }
+  },
+  {
+    name: 'image_draw_shape',
+    description: 'Creates a new image containing a shape (rect, circle, ellipse, line). Use with composite to layer.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        width: { type: 'number' }, height: { type: 'number' },
+        shape: { type: 'string', enum: ['rect', 'circle', 'ellipse', 'line'] },
+        fill: { type: 'string' }, fillOpacity: { type: 'number' },
+        stroke: { type: 'string' }, strokeWidth: { type: 'number' },
+        borderRadius: { type: 'number' },
+        cx: { type: 'number' }, cy: { type: 'number' }, r: { type: 'number' }, ry: { type: 'number' },
+        x1: { type: 'number' }, y1: { type: 'number' }, x2: { type: 'number' }, y2: { type: 'number' }
+      },
+      required: ['width', 'height', 'shape']
+    }
+  },
+  {
+    name: 'image_drop_shadow',
+    description: 'Adds a drop shadow behind the image. Expands canvas to fit shadow.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        image: { type: 'string' },
+        color: { type: 'string', description: 'Shadow color. Default: rgba(0,0,0,0.5)' },
+        offsetX: { type: 'number', description: 'Default: 4' },
+        offsetY: { type: 'number', description: 'Default: 4' },
+        blur: { type: 'number', description: 'Blur radius. Default: 8' },
+        expand: { type: 'boolean', description: 'Expand canvas. Default: true' }
+      },
+      required: ['image']
+    }
   }
 ];
 
@@ -260,6 +334,18 @@ export async function handleTool(name: string, args: Record<string, any>): Promi
     const txt = await api.extractText(image, args);
     return JSON.stringify(txt);
   }
+  else if (name === 'image_rotate') result = await api.rotate(image, args as any);
+  else if (name === 'image_gradient_overlay') result = await api.gradientOverlay(image, args as any);
+  else if (name === 'image_clip_to_shape') result = await api.clipToShape(image, args as any);
+  else if (name === 'image_draw_shape') {
+    result = await api.drawShape(args as any);
+    if (result && result.ok && Buffer.isBuffer(result.data)) {
+      const b64 = result.data.toString('base64');
+      return JSON.stringify({ ok: true, data: `data:image/png;base64,${b64}` });
+    }
+    return JSON.stringify(result);
+  }
+  else if (name === 'image_drop_shadow') result = await api.dropShadow(image, args as any);
   else {
     return JSON.stringify({ error: `Tool ${name} not implemented`, code: 'INVALID_INPUT' });
   }

package/src/ops/add-text.ts

@@ -1,9 +1,19 @@
 import sharp from 'sharp';
-import { TextLayer, ImageInput, ImageResult, ErrorCode, TextAnchor } from '../types.js';
+import { TextLayer, TextSpan, ImageInput, ImageResult, ErrorCode, TextAnchor } from '../types.js';
 import { loadImage } from '../utils/load-image.js';
 import { err, ok } from '../utils/result.js';
 import { getImageMetadata } from '../utils/validate.js';
+import { resolveFontUrl } from '../utils/font-loader.js';
 
+/**
+ * Wraps text into lines that fit within a maximum pixel width.
+ * Uses a character-width approximation of `fontSize * 0.6`.
+ *
+ * @param text - The text to wrap
+ * @param fontSize - Font size in pixels
+ * @param maxWidth - Maximum line width in pixels (optional)
+ * @returns Array of text lines
+ */
 function wrapText(text: string, fontSize: number, maxWidth?: number): string[] {
   if (!maxWidth) return [text];
   const charWidth = fontSize * 0.6; // Approximation
@@ -24,6 +34,12 @@ function wrapText(text: string, fontSize: number, maxWidth?: number): string[] {
   return lines;
 }
 
+/**
+ * Escapes special XML characters to prevent SVG injection.
+ *
+ * @param text - Raw text to escape
+ * @returns XML-safe string
+ */
 function escapeXml(text: string): string {
   return text
     .replace(/&/g, '&')
@@ -33,23 +49,26 @@ function escapeXml(text: string): string {
     .replace(/'/g, ''');
 }
 
+/**
+ * Computes SVG text-anchor and y-offset based on the anchor setting.
+ * librsvg only reliably supports `dominant-baseline: auto` (alphabetic),
+ * so vertical alignment is achieved via manual y-offset.
+ *
+ * @param anchor - The text anchor position
+ * @param fontSize - Font size for offset calculation
+ * @returns Object with `textAnchor` SVG attribute and `yOffset` pixel shift
+ */
 function getAnchorProps(anchor: TextAnchor = 'top-left', fontSize: number = 24): { textAnchor: string, yOffset: number } {
   const parts = anchor.split('-');
   const yAlign = parts.length === 2 ? parts[0] : parts[0] === 'center' ? 'middle' : parts[0];
   const xAlign = parts.length === 2 ? parts[1] : parts[0] === 'center' ? 'center' : 'left';
 
-  // librsvg does NOT reliably support dominant-baseline values other than 'auto' (alphabetic).
-  // Instead of relying on dominant-baseline, we compute a y-offset to position text correctly.
-  // With 'auto' (alphabetic baseline), y = text baseline (bottom of caps).
-  // To make y = text top, we shift down by ~0.8 * fontSize.
-  // To make y = text middle, we shift down by ~0.35 * fontSize.
   let yOffset = 0;
   if (yAlign === 'top') {
     yOffset = Math.round(fontSize * 0.8);
   } else if (yAlign === 'middle' || yAlign === 'center') {
     yOffset = Math.round(fontSize * 0.35);
   }
-  // 'bottom' / 'auto' → yOffset = 0 (alphabetic baseline is already at y)
 
   let textAnchor = 'start';
   if (xAlign === 'center') textAnchor = 'middle';
@@ -58,6 +77,127 @@ function getAnchorProps(anchor: TextAnchor = 'top-left', fontSize: number = 24):
   return { textAnchor, yOffset };
 }
 
+/**
+ * Builds SVG `<tspan>` elements from an array of inline spans.
+ * Handles style inheritance, `\n` line breaks, and highlight rects.
+ *
+ * @param spans - Array of TextSpan objects
+ * @param layer - Parent TextLayer for default values
+ * @param renderY - The computed y position for the text element
+ * @returns Object containing `tspanSvg`, `highlightSvg`, and `approxMaxWidth`
+ */
+function buildSpansSvg(
+  spans: TextSpan[],
+  layer: TextLayer,
+  renderY: number,
+): { tspanSvg: string; highlightSvg: string; approxMaxWidth: number } {
+  const baseFontSize = layer.fontSize ?? 24;
+  const baseColor = layer.color ?? '#000000';
+  const lineHeight = layer.lineHeight ?? 1.2;
+
+  let tspanSvg = '';
+  let highlightSvg = '';
+
+  // Track cursor position for highlight rects and line breaks
+  let cursorX = layer.x;
+  let currentLineY = renderY;
+  let isFirstOnLine = true;
+  let maxLineWidth = 0;
+  let currentLineWidth = 0;
+
+  for (const span of spans) {
+    const spanFontSize = span.fontSize ?? baseFontSize;
+    const spanColor = span.color ?? baseColor;
+
+    // Split on \n to handle line breaks within a single span
+    const segments = span.text.split('\n');
+
+    for (let segIdx = 0; segIdx < segments.length; segIdx++) {
+      // Handle line break (every segment after the first means a \n was found)
+      if (segIdx > 0) {
+        // Flush current line width
+        if (currentLineWidth > maxLineWidth) maxLineWidth = currentLineWidth;
+        currentLineWidth = 0;
+        cursorX = layer.x;
+        currentLineY += baseFontSize * lineHeight;
+        isFirstOnLine = true;
+      }
+
+      const segText = segments[segIdx];
+      if (segText.length === 0) continue;
+
+      const segWidth = segText.length * spanFontSize * 0.6;
+
+      // Highlight rect (rendered BEFORE text so it appears behind)
+      if (span.highlight) {
+        highlightSvg += `<rect x="${cursorX}" y="${currentLineY - spanFontSize * 0.8}" width="${segWidth}" height="${spanFontSize}" fill="${span.highlight}" />`;
+      }
+
+      // Build inline style overrides
+      const styleAttrs: string[] = [];
+      if (span.bold) styleAttrs.push('font-weight: bold');
+      if (span.italic) styleAttrs.push('font-style: italic');
+      if (span.color) styleAttrs.push(`fill: ${spanColor}`);
+      if (span.fontSize) styleAttrs.push(`font-size: ${spanFontSize}px`);
+
+      const styleAttr = styleAttrs.length > 0 ? ` style="${styleAttrs.join('; ')};"` : '';
+
+      if (isFirstOnLine) {
+        // First tspan on a line: reset x and apply dy for line break
+        const dy = currentLineY === renderY ? 0 : baseFontSize * lineHeight;
+        if (dy > 0) {
+          tspanSvg += `<tspan x="${layer.x}" dy="${dy}"${styleAttr}>${escapeXml(segText)}</tspan>`;
+        } else {
+          tspanSvg += `<tspan${styleAttr}>${escapeXml(segText)}</tspan>`;
+        }
+        isFirstOnLine = false;
+      } else {
+        tspanSvg += `<tspan${styleAttr}>${escapeXml(segText)}</tspan>`;
+      }
+
+      cursorX += segWidth;
+      currentLineWidth += segWidth;
+    }
+  }
+
+  // Final line width check
+  if (currentLineWidth > maxLineWidth) maxLineWidth = currentLineWidth;
+
+  return {
+    tspanSvg,
+    highlightSvg,
+    approxMaxWidth: maxLineWidth,
+  };
+}
+
+/**
+ * Adds text layers onto an image using SVG overlay compositing.
+ *
+ * Supports two rendering modes:
+ * 1. **Plain text** — uses `layer.text` with optional `maxWidth` wrapping
+ * 2. **Inline spans** — uses `layer.spans[]` for mixed-style rendering
+ *
+ * Font loading: if `layer.fontUrl` starts with `https://`, the font is
+ * automatically downloaded and cached locally for librsvg compatibility.
+ *
+ * @param input - Source image (Buffer, URL, data-URI, or file path)
+ * @param options - Object containing `layers` array of `TextLayer`
+ * @returns ImageResult with the composited image buffer
+ *
+ * @example
+ * // Plain text
+ * await addText(buffer, { layers: [{ text: 'Hello', x: 10, y: 50 }] });
+ *
+ * @example
+ * // Inline spans
+ * await addText(buffer, { layers: [{
+ *   x: 10, y: 50, fontSize: 28, color: '#333',
+ *   spans: [
+ *     { text: 'normal ' },
+ *     { text: 'bold', bold: true, color: '#000' },
+ *   ]
+ * }] });
+ */
 export async function addText(input: ImageInput, options: { layers: TextLayer[] }): Promise<ImageResult> {
   try {
     const buffer = await loadImage(input);
@@ -81,13 +221,14 @@ export async function addText(input: ImageInput, options: { layers: TextLayer[]
       const color = layer.color ?? '#000000';
       const opacity = layer.opacity ?? 1.0;
       const fontFamily = layer.fontFamily ?? 'sans-serif';
-      if (layer.fontUrl) fontImports.add(`@import url('${layer.fontUrl}');`);
 
-      const lines = wrapText(layer.text, fontSize, layer.maxWidth);
-      const lineHeight = layer.lineHeight ?? 1.2;
-      const totalHeight = lines.length * fontSize * lineHeight;
-      const approxMaxWidth = Math.max(...lines.map(l => l.length * fontSize * 0.6));
+      // ── Font loading ──────────────────────────────────────────────
+      if (layer.fontUrl) {
+        const localUrl = await resolveFontUrl(layer.fontUrl);
+        fontImports.add(`@font-face { font-family: '${fontFamily}'; src: url('${localUrl}'); }`);
+      }
 
+      const lineHeight = layer.lineHeight ?? 1.2;
       const { textAnchor, yOffset } = getAnchorProps(layer.anchor, fontSize);
       const renderY = layer.y + yOffset;
 
@@ -97,48 +238,142 @@ export async function addText(input: ImageInput, options: { layers: TextLayer[]
       }
 
       // Always use dominant-baseline: auto (alphabetic) — the only value librsvg reliably supports
-      const style = `font-family: ${fontFamily}; font-size: ${fontSize}px; fill: ${color}; opacity: ${opacity}; text-anchor: ${align}; dominant-baseline: auto;`;
-      
+      let style = `font-family: ${fontFamily}; font-size: ${fontSize}px; fill: ${color}; opacity: ${opacity}; text-anchor: ${align}; dominant-baseline: auto;`;
+
+      // Letter spacing
+      if (layer.letterSpacing) {
+        style += ` letter-spacing: ${layer.letterSpacing}px;`;
+      }
+
+      // Stroke (outline) — paint-order renders stroke behind fill
+      if (layer.stroke) {
+        style += ` stroke: ${layer.stroke.color}; stroke-width: ${layer.stroke.width}px; paint-order: stroke;`;
+      }
+
       let layerSvg = '';
+      let totalHeight: number;
+      let approxMaxWidth: number;
+      let layerTextPreview: string;
 
-      if (layer.background) {
-        const bg = layer.background;
-        const pad = bg.padding ?? 0;
-        const bgOpacity = bg.opacity ?? 1.0;
-        const radius = bg.borderRadius ?? 0;
-
-        // Background rect is positioned relative to the *intended* y (layer.y), not renderY
-        let rectX = layer.x - pad;
-        let rectY = layer.y - pad;
-        
-        if (textAnchor === 'middle') {
-          rectX = layer.x - (approxMaxWidth / 2) - pad;
-        } else if (textAnchor === 'end') {
-          rectX = layer.x - approxMaxWidth - pad;
+      // ── Spans mode vs plain text mode ─────────────────────────────
+      if (layer.spans && layer.spans.length > 0) {
+        // Emit warnings for spans mode edge cases
+        if (layer.text) {
+          warnings.push('text field ignored when spans is provided');
+        }
+        if (layer.maxWidth) {
+          warnings.push('maxWidth is not supported with spans');
         }
 
-        // Adjust for anchor vertical alignment
-        const parts = (layer.anchor ?? 'top-left').split('-');
-        const vAlign = parts.length === 2 ? parts[0] : parts[0] === 'center' ? 'middle' : parts[0];
-        if (vAlign === 'middle' || vAlign === 'center') {
-          rectY = layer.y - (totalHeight / 2) - pad;
-        } else if (vAlign === 'bottom') {
-          rectY = layer.y - totalHeight - pad + fontSize;
+        const spansResult = buildSpansSvg(layer.spans, layer, renderY);
+        approxMaxWidth = spansResult.approxMaxWidth;
+
+        // Count line breaks to compute totalHeight
+        const fullText = layer.spans.map((s) => s.text).join('');
+        const lineCount = (fullText.match(/\n/g) ?? []).length + 1;
+        totalHeight = lineCount * fontSize * lineHeight;
+
+        layerTextPreview = fullText.slice(0, 20);
+
+        // Background rect
+        if (layer.background) {
+          const bg = layer.background;
+          const pad = bg.padding ?? 0;
+          const bgOpacity = bg.opacity ?? 1.0;
+          const radius = bg.borderRadius ?? 0;
+
+          let rectX = layer.x - pad;
+          let rectY = layer.y - pad;
+          
+          if (textAnchor === 'middle') {
+            rectX = layer.x - (approxMaxWidth / 2) - pad;
+          } else if (textAnchor === 'end') {
+            rectX = layer.x - approxMaxWidth - pad;
+          }
+
+          const parts = (layer.anchor ?? 'top-left').split('-');
+          const vAlign = parts.length === 2 ? parts[0] : parts[0] === 'center' ? 'middle' : parts[0];
+          if (vAlign === 'middle' || vAlign === 'center') {
+            rectY = layer.y - (totalHeight / 2) - pad;
+          } else if (vAlign === 'bottom') {
+            rectY = layer.y - totalHeight - pad + fontSize;
+          }
+
+          layerSvg += `<rect x="${rectX}" y="${rectY}" width="${approxMaxWidth + pad * 2}" height="${totalHeight + pad * 2}" fill="${bg.color}" opacity="${bgOpacity}" rx="${radius}" ry="${radius}" />`;
         }
 
-        layerSvg += `<rect x="${rectX}" y="${rectY}" width="${approxMaxWidth + pad * 2}" height="${totalHeight + pad * 2}" fill="${bg.color}" opacity="${bgOpacity}" rx="${radius}" ry="${radius}" />`;
-      }
+        // Highlight rects (behind text)
+        layerSvg += spansResult.highlightSvg;
 
-      layerSvg += `<text x="${layer.x}" y="${renderY}" style="${style}">`;
-      lines.forEach((line, idx) => {
-        let dy = idx === 0 ? 0 : fontSize * lineHeight;
-        layerSvg += `<tspan x="${layer.x}" dy="${dy}">${escapeXml(line)}</tspan>`;
-      });
-      layerSvg += `</text>`;
+        // Shadow for spans mode
+        if (layer.textShadow) {
+          const ts = layer.textShadow;
+          const shadowStyle = `font-family: ${fontFamily}; font-size: ${fontSize}px; fill: ${ts.color}; opacity: ${opacity}; text-anchor: ${align}; dominant-baseline: auto;${layer.letterSpacing ? ` letter-spacing: ${layer.letterSpacing}px;` : ''}`;
+          const sx = layer.x + ts.offsetX;
+          const sy = renderY + ts.offsetY;
+          layerSvg += `<text x="${sx}" y="${sy}" style="${shadowStyle}">${spansResult.tspanSvg}</text>`;
+        }
+
+        // Main text element with spans
+        layerSvg += `<text x="${layer.x}" y="${renderY}" style="${style}">${spansResult.tspanSvg}</text>`;
+      } else {
+        // ── Plain text mode (existing logic) ─────────────────────────
+        const lines = wrapText(layer.text, fontSize, layer.maxWidth);
+        totalHeight = lines.length * fontSize * lineHeight;
+        approxMaxWidth = Math.max(...lines.map(l => l.length * fontSize * 0.6));
+        layerTextPreview = layer.text.slice(0, 20);
+
+        if (layer.background) {
+          const bg = layer.background;
+          const pad = bg.padding ?? 0;
+          const bgOpacity = bg.opacity ?? 1.0;
+          const radius = bg.borderRadius ?? 0;
+
+          let rectX = layer.x - pad;
+          let rectY = layer.y - pad;
+          
+          if (textAnchor === 'middle') {
+            rectX = layer.x - (approxMaxWidth / 2) - pad;
+          } else if (textAnchor === 'end') {
+            rectX = layer.x - approxMaxWidth - pad;
+          }
+
+          const parts = (layer.anchor ?? 'top-left').split('-');
+          const vAlign = parts.length === 2 ? parts[0] : parts[0] === 'center' ? 'middle' : parts[0];
+          if (vAlign === 'middle' || vAlign === 'center') {
+            rectY = layer.y - (totalHeight / 2) - pad;
+          } else if (vAlign === 'bottom') {
+            rectY = layer.y - totalHeight - pad + fontSize;
+          }
+
+          layerSvg += `<rect x="${rectX}" y="${rectY}" width="${approxMaxWidth + pad * 2}" height="${totalHeight + pad * 2}" fill="${bg.color}" opacity="${bgOpacity}" rx="${radius}" ry="${radius}" />`;
+        }
+
+        // Text shadow: render a duplicate text behind the main text
+        if (layer.textShadow) {
+          const ts = layer.textShadow;
+          const shadowStyle = `font-family: ${fontFamily}; font-size: ${fontSize}px; fill: ${ts.color}; opacity: ${opacity}; text-anchor: ${align}; dominant-baseline: auto;${layer.letterSpacing ? ` letter-spacing: ${layer.letterSpacing}px;` : ''}`;
+          const sx = layer.x + ts.offsetX;
+          const sy = renderY + ts.offsetY;
+          layerSvg += `<text x="${sx}" y="${sy}" style="${shadowStyle}">`;
+          lines.forEach((line, idx) => {
+            let dy = idx === 0 ? 0 : fontSize * lineHeight;
+            layerSvg += `<tspan x="${sx}" dy="${dy}">${escapeXml(line)}</tspan>`;
+          });
+          layerSvg += `</text>`;
+        }
+
+        layerSvg += `<text x="${layer.x}" y="${renderY}" style="${style}">`;
+        lines.forEach((line, idx) => {
+          let dy = idx === 0 ? 0 : fontSize * lineHeight;
+          layerSvg += `<tspan x="${layer.x}" dy="${dy}">${escapeXml(line)}</tspan>`;
+        });
+        layerSvg += `</text>`;
+      }
 
       svgBody += `<g style="isolation: isolate">${layerSvg}</g>`;
 
-      // Compute bounding box for overflow detection (using intended y, not renderY)
+      // ── Bounding box / overflow detection ──────────────────────────
       let boxX = layer.x;
       let boxY = layer.y;
       if (textAnchor === 'middle') boxX -= approxMaxWidth / 2;
@@ -155,7 +390,7 @@ export async function addText(input: ImageInput, options: { layers: TextLayer[]
 
       if (boxX < 0 || boxY < 0 || boxRight > width || boxBottom > height) {
         warnings.push(
-          `Text layer ${i} ("${layer.text.slice(0, 20)}...") extends beyond canvas bounds.`
+          `Text layer ${i} ("${layerTextPreview}...") extends beyond canvas bounds.`
         );
       }
     }
@@ -180,6 +415,9 @@ export async function addText(input: ImageInput, options: { layers: TextLayer[]
     if (msg.includes('HTTP')) return err(msg, ErrorCode.FETCH_FAILED);
     if (msg.includes('ENOENT')) return err('File not found', ErrorCode.INVALID_INPUT);
     if (msg.includes('unsupported image format')) return err('Corrupt or unsupported input', ErrorCode.INVALID_INPUT);
+    if (msg.includes('Font download failed') || msg.includes('Google Fonts CSS fetch failed')) {
+      return err(msg, ErrorCode.FETCH_FAILED);
+    }
     return err(msg, ErrorCode.PROCESSING_FAILED);
   }
 }