[new tool] @agent-tools/image-placeholder — Compact visual placeholder hashes for images

[burner-agent]

Tool Name

@agent-tools/image-placeholder

Description

Generate and decode compact visual placeholder hashes (BlurHash and ThumbHash) from images, producing tiny strings or binary representations that can be stored inline and rendered as blurred previews while full images load.

Why It's Useful for Agents

AI agents processing, indexing, or serving images need lightweight visual previews without storing full thumbnails. BlurHash (woltapp/blurhash — 17k stars, MIT, 20-30 char strings, used by Mastodon/Signal/Figma) and ThumbHash (evanw/thumbhash — 4.1k stars, MIT, preserves aspect ratio + alpha channel, more detail than BlurHash) are the two dominant algorithms. Both have TypeScript declarations and npm packages (blurhash v2.0.5, thumbhash v0.1.1). No unified library wraps both algorithms with a consistent encode/decode API, format auto-selection, and integration with common image pipelines. Agents building image catalogs, generating HTML reports with embedded previews, or optimizing content delivery benefit from inline placeholders that are orders of magnitude smaller than even the smallest JPEG thumbnail.

Proposed API

import { encode, decode, toDataURL, fromImageData } from '@agent-tools/image-placeholder';

// Encode image to placeholder hash (auto-selects algorithm)
const hash = await encode(imageBuffer, {
  algorithm: 'blurhash' | 'thumbhash' | 'auto', // default: 'auto'
  componentX: 4,  // BlurHash horizontal components (1-9)
  componentY: 3,  // BlurHash vertical components (1-9)
});
// => { algorithm: 'thumbhash', hash: 'aP...base64...', width: 100, height: 75 }

// Decode hash back to pixel data
const pixels = decode(hash.hash, { width: 32, height: 32, algorithm: 'thumbhash' });
// => { rgba: Uint8Array, width: 32, height: 32 }

// Convenience: generate a data URL for direct HTML embedding
const dataUrl = toDataURL(hash.hash, { width: 32, height: 32, algorithm: 'blurhash' });
// => "data:image/png;base64,..."

// Encode from raw RGBA ImageData
const hash2 = fromImageData(rgbaData, width, height, { algorithm: 'blurhash' });

// Batch processing
const hashes = await encodeBatch(imageBuffers, { algorithm: 'thumbhash', concurrency: 4 });

Scope

In scope:

• BlurHash encoding/decoding (adjustable component count, punch parameter)
• ThumbHash encoding/decoding (preserves aspect ratio and alpha)
• Data URL generation (PNG) for direct HTML/CSS embedding
• Raw RGBA ImageData input/output
• Algorithm auto-selection (ThumbHash when alpha needed, BlurHash for compatibility)
• Batch encoding with concurrency control
• CSS gradient approximation output (no-JS fallback)

Out of scope:

• Full image resizing/processing (use @agent-tools/image [new tool] @agent-tools/image — Image processing, resizing, and metadata extraction #64)
• Image format decoding (expects raw pixel data or uses sharp/canvas for buffer input)
• Server-side rendering of placeholder to canvas
• Perceptual hashing for image similarity (different use case — deduplication not placeholders)