image-edit-tools 1.0.0

package/docs/MCP.md

@@ -0,0 +1,106 @@
+# MCP Tools Reference
+
+This package exposes 17 Model Context Protocol (MCP) tools for AI agents.
+
+## Exposed Tools
+
+### image_crop
+**Description**: Crops an image. Supports absolute coords, ratio, aspect ratio, or subject mode.
+**Parameters**:
+- `image` (string, required): Base64 data URI, HTTP URL, or local path
+- `mode` (string): 'absolute' | 'ratio' | 'aspect' | 'subject'
+- `x`, `y`, `width`, `height` (number)
+- `left`, `top`, `right`, `bottom` (number)
+- `aspectRatio` (string), `anchor` (string)
+
+### image_resize
+**Description**: Resizes an image. Specify width/height or a scale multiplier.
+**Parameters**:
+- `image` (string, required)
+- `width`, `height`, `scale` (number)
+- `fit` (string): 'cover' | 'contain' | 'fill' | 'inside' | 'outside'
+
+### image_pad
+**Description**: Pads an image edges. Supports absolute edges or square target size with custom color.
+**Parameters**:
+- `image` (string, required)
+- `top`, `right`, `bottom`, `left` (number)
+- `size` (number)
+- `color` (string)
+
+### image_adjust
+**Description**: Adjusts brightness, contrast, saturation, hue, sharpness, and temperature (-100 to 100).
+**Parameters**:
+- `image` (string, required)
+- `brightness`, `contrast`, `saturation`, `hue`, `sharpness`, `temperature` (number)
+
+### image_filter
+**Description**: Applies preset filters: grayscale, sepia, invert, vintage, unsharp, or blur with radius.
+**Parameters**:
+- `image` (string, required)
+- `preset` (string, required): 'grayscale' | 'sepia' | 'invert' | 'vintage' | 'unsharp' | 'blur'
+- `radius` (number)
+
+### image_blur_region
+**Description**: Blurs specific absolute regions in the image.
+**Parameters**:
+- `image` (string, required)
+- `regions` (array of objects)
+
+### image_add_text
+**Description**: Adds text layers. Requires x, y, text, font size, and optional alignment parameters.
+**Parameters**:
+- `image` (string, required)
+- `layers` (array of objects)
+
+### image_composite
+**Description**: Composites images together with blend modes.
+**Parameters**:
+- `image` (string, required)
+- `layers` (array of objects)
+
+### image_watermark
+**Description**: Applies watermarks either text or image at discrete positions or tiled.
+**Parameters**:
+- `image` (string, required)
+- `type` (string, required): 'text' | 'image'
+- `text`, `imageLayer`, `position`, `opacity`
+
+### image_remove_bg
+**Description**: Removes background using AI model RMBG-1.4. Optionally replaces with color or image.
+**Parameters**:
+- `image` (string, required)
+- `replaceColor`, `replaceImage` (string)
+
+### image_convert
+**Description**: Converts image to jpeg, png, webp, avif, or gif.
+**Parameters**:
+- `image` (string, required)
+- `format` (string, required)
+- `quality` (number), `stripMetadata` (boolean)
+
+### image_optimize
+**Description**: Optimizes an image to fit max size in KB or max dimension.
+**Parameters**:
+- `image` (string, required)
+- `maxSizeKB`, `maxDimension` (number), `autoFormat` (boolean)
+
+### image_get_metadata
+**Description**: Returns image metadata.
+**Parameters**: `image` (string, required)
+
+### image_get_dominant_colors
+**Description**: Returns hex values of the primary colors.
+**Parameters**: `image` (string, required), `count` (number)
+
+### image_detect_faces
+**Description**: Detects bounding boxes around faces.
+**Parameters**: `image` (string, required)
+
+### image_extract_text
+**Description**: Runs OCR to extract text.
+**Parameters**: `image` (string, required), `lang` (string)
+
+### image_pipeline
+**Description**: Runs a sequence of operations seamlessly.
+**Parameters**: `image` (string, required), `operations` (array of objects)

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "image-edit-tools",
+  "version": "1.0.0",
+  "description": "Deterministic image editing SDK for AI agents. Ships with MCP tools.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "image-edit-tools": "./dist/mcp/server.js"
+  },
+  "exports": {
+    ".": "./dist/index.js",
+    "./mcp": "./dist/mcp/server.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:unit": "vitest run tests/unit",
+    "test:integration": "vitest run tests/integration",
+    "test:e2e": "vitest run tests/e2e",
+    "docs": "typedoc --out docs/api src/index.ts",
+    "prepublishOnly": "npm run build && npm run test:coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.1.0",
+    "@xenova/transformers": "^2.17.2",
+    "color-thief-node": "^1.0.4",
+    "node-fetch": "^3.3.2",
+    "sharp": "^0.33.5",
+    "tesseract.js": "^5.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.2",
+    "@vitest/coverage-v8": "^1.6.0",
+    "tsx": "^4.21.0",
+    "typedoc": "^0.25.13",
+    "typescript": "^5.4.5",
+    "vitest": "^1.6.0"
+  },
+  "keywords": [
+    "image",
+    "editing",
+    "mcp",
+    "ai-agent",
+    "claude",
+    "sharp",
+    "typescript"
+  ],
+  "license": "MIT"
+}

package/scripts/generate-fixtures.js

@@ -0,0 +1,33 @@
+import fs from 'fs';
+import path from 'path';
+import sharp from 'sharp';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const fixDir = path.join(__dirname, '../tests/fixtures');
+
+fs.mkdirSync(fixDir, { recursive: true });
+
+async function run() {
+  await sharp({ create: { width: 400, height: 300, channels: 3, background: { r: 255, g: 0, b: 0 } } })
+    .jpeg()
+    .toFile(path.join(fixDir, 'sample.jpg'));
+    
+  await sharp({ create: { width: 400, height: 300, channels: 4, background: { r: 0, g: 255, b: 0, alpha: 0.5 } } })
+    .png()
+    .toFile(path.join(fixDir, 'sample.png'));
+    
+  await sharp({ create: { width: 400, height: 300, channels: 3, background: { r: 0, g: 0, b: 255 } } })
+    .webp()
+    .toFile(path.join(fixDir, 'sample.webp'));
+    
+  await sharp({ create: { width: 100, height: 100, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } } })
+    .composite([{ input: Buffer.from('<svg><circle cx="50" cy="50" r="40" fill="red" /></svg>'), left: 0, top: 0 }])
+    .png()
+    .toFile(path.join(fixDir, 'logo.png'));
+
+  console.log('Fixtures generated successfully.');
+}
+
+run().catch(console.error);

package/src/index.ts

@@ -0,0 +1,24 @@
+export * from './types.js';
+export * from './utils/result.js';
+export * from './utils/load-image.js';
+
+export { crop } from './ops/crop.js';
+export { resize } from './ops/resize.js';
+export { pad } from './ops/pad.js';
+export { adjust } from './ops/adjust.js';
+export { filter } from './ops/filter.js';
+export { blurRegion } from './ops/blur-region.js';
+export { addText } from './ops/add-text.js';
+export { composite } from './ops/composite.js';
+export { watermark } from './ops/watermark.js';
+export { overlay } from './ops/overlay.js';
+export { removeBg } from './ops/remove-bg.js';
+export { detectSubject } from './ops/detect-subject.js';
+export { convert } from './ops/convert.js';
+export { optimize } from './ops/optimize.js';
+export { getMetadata } from './ops/get-metadata.js';
+export { getDominantColors } from './ops/get-dominant-colors.js';
+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';

package/src/mcp/index.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import './server.js';

package/src/mcp/server.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
+import { allTools, handleTool } from './tools.js'
+
+const server = new Server(
+  { name: 'image-edit-tools', version: '1.0.0' },
+  { capabilities: { tools: {} } }
+)
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: allTools }))
+
+server.setRequestHandler(CallToolRequestSchema, async (req) => {
+  const { name, arguments: args } = req.params
+  const text = await handleTool(name, args ?? {})
+  return { content: [{ type: 'text', text }] }
+})
+
+const transport = new StdioServerTransport()
+await server.connect(transport)

package/src/mcp/tools.ts

@@ -0,0 +1,276 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+import * as api from '../index.js';
+import { ImageInput } from '../types.js';
+
+export const allTools: Tool[] = [
+  {
+    name: 'image_crop',
+    description: 'Crops an image. Supports absolute coords, ratio, aspect ratio, or subject mode.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        image: { type: 'string', description: 'Base64 data URI, HTTP URL, or local path' },
+        mode: { type: 'string', enum: ['absolute', 'ratio', 'aspect', 'subject'] },
+        x: { type: 'number' }, y: { type: 'number' }, width: { type: 'number' }, height: { type: 'number' },
+        left: { type: 'number' }, top: { type: 'number' }, right: { type: 'number' }, bottom: { type: 'number' },
+        aspectRatio: { type: 'string' }, anchor: { type: 'string' }
+      },
+      required: ['image']
+    }
+  },
+  {
+    name: 'image_resize',
+    description: 'Resizes an image. Specify width/height or a scale multiplier.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        image: { type: 'string' },
+        width: { type: 'number' }, height: { type: 'number' }, scale: { type: 'number' },
+        fit: { type: 'string', enum: ['cover', 'contain', 'fill', 'inside', 'outside'] },
+        kernel: { type: 'string' }
+      },
+      required: ['image']
+    }
+  },
+  {
+    name: 'image_pad',
+    description: 'Pads an image edges. Supports absolute edges or square target size with custom color.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        image: { type: 'string' },
+        top: { type: 'number' }, right: { type: 'number' }, bottom: { type: 'number' }, left: { type: 'number' },
+        size: { type: 'number' }, color: { type: 'string' }
+      },
+      required: ['image']
+    }
+  },
+  {
+    name: 'image_adjust',
+    description: 'Adjusts brightness, contrast, saturation, hue, sharpness, and temperature (-100 to 100).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        image: { type: 'string' },
+        brightness: { type: 'number', description: 'Range: -100 to 100' }, 
+        contrast: { type: 'number', description: 'Range: -100 to 100' }, 
+        saturation: { type: 'number', description: 'Range: -100 to 100' },
+        hue: { type: 'number', description: 'Range: 0 to 360' }, 
+        sharpness: { type: 'number', description: 'Range: 0 to 100' }, 
+        temperature: { type: 'number', description: 'Range: -100 to 100' }
+      },
+      required: ['image']
+    }
+  },
+  {
+    name: 'image_filter',
+    description: 'Applies preset filters: grayscale, sepia, invert, vintage, unsharp, or blur with radius.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        image: { type: 'string' },
+        preset: { type: 'string', enum: ['grayscale', 'sepia', 'invert', 'vintage', 'unsharp', 'blur'] },
+        radius: { type: 'number' }
+      },
+      required: ['image', 'preset']
+    }
+  },
+  {
+    name: 'image_blur_region',
+    description: 'Blurs specific absolute regions in the image.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        image: { type: 'string' },
+        regions: { 
+          type: 'array', 
+          items: { 
+            type: 'object',
+            properties: { 
+              x: { type: 'number' }, y: { type: 'number' }, 
+              width: { type: 'number' }, height: { type: 'number' }, 
+              radius: { type: 'number', description: 'Blur radius' } 
+            },
+            required: ['x', 'y', 'width', 'height']
+          } 
+        }
+      },
+      required: ['image']
+    }
+  },
+  {
+    name: 'image_add_text',
+    description: 'Adds text layers. Requires x, y, text, font size, and optional alignment parameters.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        image: { type: 'string' },
+        layers: { type: 'array', items: { type: 'object' } }
+      },
+      required: ['image']
+    }
+  },
+  {
+    name: 'image_composite',
+    description: 'Composites images together with blend modes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        image: { type: 'string' },
+        layers: { type: 'array', items: { type: 'object' } }
+      },
+      required: ['image']
+    }
+  },
+  {
+    name: 'image_watermark',
+    description: 'Applies watermarks either text or image at discrete positions or tiled.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        image: { type: 'string' },
+        type: { type: 'string', enum: ['text', 'image'] },
+        text: { type: 'string' }, imageLayer: { type: 'string' },
+        position: { type: 'string' }, opacity: { type: 'number' }
+      },
+      required: ['image', 'type']
+    }
+  },
+  {
+    name: 'image_remove_bg',
+    description: 'Removes background using AI model RMBG-1.4. Optionally replaces with color or image.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        image: { type: 'string' },
+        replaceColor: { type: 'string' },
+        replaceImage: { type: 'string' }
+      },
+      required: ['image']
+    }
+  },
+  {
+    name: 'image_convert',
+    description: 'Converts image to jpeg, png, webp, avif, or gif.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        image: { type: 'string' },
+        format: { type: 'string', enum: ['jpeg', 'png', 'webp', 'avif', 'gif'] },
+        quality: { type: 'number' },
+        stripMetadata: { type: 'boolean' }
+      },
+      required: ['image', 'format']
+    }
+  },
+  {
+    name: 'image_optimize',
+    description: 'Optimizes an image to fit max size in KB or max dimension.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        image: { type: 'string' },
+        maxSizeKB: { type: 'number' }, maxDimension: { type: 'number' }, autoFormat: { type: 'boolean' }
+      },
+      required: ['image']
+    }
+  },
+  {
+    name: 'image_get_metadata',
+    description: 'Returns image metadata like dimensions, format, hasAlpha.',
+    inputSchema: { type: 'object', properties: { image: { type: 'string' } }, required: ['image'] }
+  },
+  {
+    name: 'image_get_dominant_colors',
+    description: 'Returns hex values of the primary colors in the image.',
+    inputSchema: { type: 'object', properties: { image: { type: 'string' }, count: { type: 'number' } }, required: ['image'] }
+  },
+  {
+    name: 'image_detect_faces',
+    description: 'Detects bounding boxes around faces/people in the image using AI.',
+    inputSchema: { type: 'object', properties: { image: { type: 'string' } }, required: ['image'] }
+  },
+  {
+    name: 'image_extract_text',
+    description: 'Runs OCR using tesseract.js to extract text from the image.',
+    inputSchema: { type: 'object', properties: { image: { type: 'string' }, lang: { type: 'string' } }, required: ['image'] }
+  },
+  {
+    name: 'image_pipeline',
+    description: 'Runs a sequence of operations on the image seamlessly in memory.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        image: { type: 'string' },
+        operations: { type: 'array', items: { type: 'object' } }
+      },
+      required: ['image', 'operations']
+    }
+  },
+  {
+    name: 'image_batch',
+    description: 'Runs a single operation on multiple images.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        images: { type: 'array', items: { type: 'string' } },
+        operation: { type: 'string' },
+        options: { type: 'object' }
+      },
+      required: ['images', 'operation', 'options']
+    }
+  }
+];
+
+export async function handleTool(name: string, args: Record<string, any>): Promise<string> {
+  const image = args.image as ImageInput;
+  let result: any;
+  
+  if (name === 'image_pipeline') result = await api.pipeline(image, args.operations);
+  else if (name === 'image_batch') result = await api.batch(args.images, args.operation, args.options);
+  else if (name === 'image_crop') result = await api.crop(image, args as any);
+  else if (name === 'image_resize') result = await api.resize(image, args as any);
+  else if (name === 'image_pad') result = await api.pad(image, args as any);
+  else if (name === 'image_adjust') result = await api.adjust(image, args as any);
+  else if (name === 'image_filter') result = await api.filter(image, args as any);
+  else if (name === 'image_blur_region') result = await api.blurRegion(image, args as any);
+  else if (name === 'image_add_text') result = await api.addText(image, args as any);
+  else if (name === 'image_composite') result = await api.composite(image, args as any);
+  else if (name === 'image_watermark') {
+    const opts = { ...args };
+    if (opts.type === 'image' && opts.imageLayer) opts.image = opts.imageLayer;
+    result = await api.watermark(image, opts as any);
+  }
+  else if (name === 'image_remove_bg') result = await api.removeBg(image, args as any);
+  else if (name === 'image_convert') result = await api.convert(image, args as any);
+  else if (name === 'image_optimize') result = await api.optimize(image, args as any);
+  else if (name === 'image_get_metadata') {
+    const meta = await api.getMetadata(image);
+    return JSON.stringify(meta.ok ? meta.data : { error: meta.error, code: meta.code });
+  }
+  else if (name === 'image_get_dominant_colors') {
+    const cols = await api.getDominantColors(image, args.count);
+    return JSON.stringify(cols);
+  }
+  else if (name === 'image_detect_faces') {
+    const faces = await api.detectFaces(image);
+    return JSON.stringify(faces);
+  }
+  else if (name === 'image_extract_text') {
+    const txt = await api.extractText(image, args);
+    return JSON.stringify(txt);
+  }
+  else {
+    return JSON.stringify({ error: `Tool ${name} not implemented`, code: 'INVALID_INPUT' });
+  }
+
+  if (result && !result.ok) {
+    return JSON.stringify({ error: result.error, code: result.code });
+  } else if (result && Buffer.isBuffer(result.data)) {
+    const fmt = args.format || 'png';
+    const b64 = result.data.toString('base64');
+    return JSON.stringify({ ok: true, data: `data:image/${fmt};base64,${b64}` });
+  }
+
+  return JSON.stringify(result);
+}

package/src/ops/add-text.ts

@@ -0,0 +1,139 @@
+import sharp from 'sharp';
+import { TextLayer, 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';
+
+function wrapText(text: string, fontSize: number, maxWidth?: number): string[] {
+  if (!maxWidth) return [text];
+  const charWidth = fontSize * 0.6; // Approximation
+  const maxChars = Math.max(1, Math.floor(maxWidth / charWidth));
+  const words = text.split(' ');
+  const lines: string[] = [];
+  let currentLine = '';
+
+  for (const word of words) {
+    if ((currentLine + ' ' + word).trim().length <= maxChars) {
+      currentLine = (currentLine + ' ' + word).trim();
+    } else {
+      if (currentLine) lines.push(currentLine);
+      currentLine = word;
+    }
+  }
+  if (currentLine) lines.push(currentLine);
+  return lines;
+}
+
+function getAnchorProps(anchor: TextAnchor = 'top-left'): { textAnchor: string, dominantBaseline: string } {
+  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';
+
+  let dominantBaseline = 'hanging'; // top
+  if (yAlign === 'bottom') dominantBaseline = 'auto'; // bottom is harder, usually means using y directly on baseline, but we can do mathematical offset. We'll rely on SVG baselines.
+  else if (yAlign === 'middle' || yAlign === 'center') dominantBaseline = 'middle';
+  else if (yAlign === 'auto') dominantBaseline = 'auto';
+  // Sharp's librsvg supports dominant-baseline: text-before-edge (top), middle, alphabetic (bottom)
+  const baselineMap: Record<string, string> = { top: 'text-before-edge', middle: 'middle', bottom: 'alphabetic', center: 'middle' };
+
+  let textAnchor = 'start';
+  if (xAlign === 'center') textAnchor = 'middle';
+  else if (xAlign === 'right') textAnchor = 'end';
+
+  return { textAnchor, dominantBaseline: baselineMap[yAlign] || 'text-before-edge' };
+}
+
+export async function addText(input: ImageInput, options: { layers: TextLayer[] }): Promise<ImageResult> {
+  try {
+    const buffer = await loadImage(input);
+    const meta = await getImageMetadata(buffer);
+    
+    if (!options.layers || !Array.isArray(options.layers)) {
+      return err('Layers array required', ErrorCode.INVALID_INPUT);
+    }
+
+    const { width, height } = meta;
+
+    let defs = '';
+    let svgBody = '';
+    let fontImports = new Set<string>();
+
+    for (let i = 0; i < options.layers.length; i++) {
+      const layer = options.layers[i];
+      const fontSize = layer.fontSize ?? 24;
+      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));
+
+      const { textAnchor, dominantBaseline } = getAnchorProps(layer.anchor);
+
+      let align = textAnchor;
+      if (layer.align) {
+        align = layer.align === 'left' ? 'start' : layer.align === 'right' ? 'end' : 'middle';
+      }
+
+      const style = `font-family: ${fontFamily}; font-size: ${fontSize}px; fill: ${color}; opacity: ${opacity}; text-anchor: ${align}; dominant-baseline: ${dominantBaseline};`;
+      
+      let layerSvg = '';
+
+      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;
+        }
+
+        if (dominantBaseline === 'middle') {
+          rectY = layer.y - (totalHeight / 2) - pad;
+        } else if (dominantBaseline === 'alphabetic') { // 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 += `<text x="${layer.x}" y="${layer.y}" style="${style}">`;
+      lines.forEach((line, idx) => {
+        let dy = idx === 0 ? 0 : fontSize * lineHeight;
+        layerSvg += `<tspan x="${layer.x}" dy="${dy}">${line}</tspan>`;
+      });
+      layerSvg += `</text>`;
+
+      svgBody += `<g style="isolation: isolate">${layerSvg}</g>`;
+    }
+
+    const fontStyle = fontImports.size > 0 ? `<style>${Array.from(fontImports).join('\n')}</style>` : '';
+
+    const svgString = `<svg width="${width}" height="${height}" xmlns="http://www.w3.org/2000/svg">
+      ${fontStyle}
+      ${defs}
+      ${svgBody}
+    </svg>`;
+
+    const output = await sharp(buffer)
+      .composite([{ input: Buffer.from(svgString), blend: 'over' }])
+      .toBuffer();
+    
+    return ok(output);
+  } catch (e: any) {
+    const msg = e.message || '';
+    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);
+    return err(msg, ErrorCode.PROCESSING_FAILED);
+  }
+}