@ereo/plugin-images 0.1.6

package/README.md

@@ -0,0 +1,197 @@
+# @ereo/plugin-images
+
+Complete image optimization plugin for the EreoJS framework. Provides automatic image optimization, blur placeholders, responsive srcset generation, and art direction support.
+
+## Installation
+
+```bash
+bun add @ereo/plugin-images sharp
+```
+
+## Quick Start
+
+```typescript
+// ereo.config.ts
+import { defineConfig } from '@ereo/core';
+import images from '@ereo/plugin-images';
+
+export default defineConfig({
+  plugins: [
+    images({
+      formats: { webp: true, avif: true },
+      quality: 80,
+    }),
+  ],
+});
+```
+
+```tsx
+// In your components
+import { Image, Picture } from '@ereo/plugin-images/components';
+import heroImg from './hero.jpg';
+
+function Hero() {
+  return (
+    <Image
+      src={heroImg}
+      alt="Hero image"
+      placeholder="blur"
+      priority
+    />
+  );
+}
+```
+
+## Key Features
+
+- **Automatic Optimization**: Compress and resize images at build time
+- **Modern Formats**: Generate WebP and AVIF variants automatically
+- **Blur Placeholders**: Create LQIP (Low Quality Image Placeholders) for smooth loading
+- **Responsive Images**: Generate srcset with multiple sizes for different viewports
+- **Image and Picture Components**: React components with built-in optimization
+- **Dominant Color Extraction**: Extract colors for placeholder backgrounds using k-means clustering
+- **Runtime Middleware**: On-demand image processing in development
+- **Build-time Processing**: Batch optimize all images during production build
+- **Two-Tier Caching**: Memory and disk caching for optimized images
+- **Format Negotiation**: Automatic best format selection based on browser Accept header
+
+## Supported Formats
+
+**Input:** JPEG, PNG, WebP, AVIF, GIF, SVG
+
+**Output:** WebP, AVIF, JPEG, PNG
+
+## Exports
+
+### Main Plugin
+
+```ts
+import images from '@ereo/plugin-images';
+// or
+import { imagesPlugin } from '@ereo/plugin-images';
+```
+
+### Components
+
+```ts
+import { Image, Picture } from '@ereo/plugin-images/components';
+```
+
+### Processing Utilities
+
+```ts
+import {
+  // Image processor
+  createImageProcessor,
+  ImageProcessor,
+  createSharpProcessor,
+  SharpProcessor,
+
+  // Blur generation
+  generateBlurPlaceholder,
+  generateShimmerSVG,
+  generateShimmerDataURL,
+
+  // Color extraction
+  extractDominantColor,
+  rgbToHex,
+  hexToRgb,
+  getContrastColor,
+} from '@ereo/plugin-images';
+```
+
+### Build Utilities
+
+```ts
+import {
+  createBuildOptimizer,
+  optimizeImages,
+  BuildOptimizer,
+  createManifestManager,
+  ImageManifestManager,
+} from '@ereo/plugin-images';
+```
+
+### Runtime Utilities
+
+```ts
+import {
+  createImageMiddleware,
+  imageMiddleware,
+  MemoryCache,
+  DiskCache,
+  TwoTierCache,
+  generateCacheKey,
+} from '@ereo/plugin-images';
+```
+
+### Configuration Utilities
+
+```ts
+import {
+  validateConfig,
+  matchesRemotePattern,
+  ConfigValidationError,
+  DEFAULT_DEVICE_SIZES,
+  DEFAULT_IMAGE_SIZES,
+  DEFAULT_QUALITY,
+  MAX_DIMENSION,
+  IMAGE_PATH_PREFIX,
+  SUPPORTED_INPUT_FORMATS,
+  SUPPORTED_OUTPUT_FORMATS,
+  FORMAT_MIME_TYPES,
+  getAllSizes,
+  getSizesForWidth,
+} from '@ereo/plugin-images';
+```
+
+### TypeScript Types
+
+```ts
+import type {
+  ImageProps,
+  PictureProps,
+  PictureSource,
+  StaticImageData,
+  PlaceholderType,
+  ObjectFit,
+  ObjectPosition,
+  ImageLoading,
+  ImageDecoding,
+  ImageLoader,
+  ImageLoaderParams,
+  ImagePluginConfig,
+  RemotePattern,
+  ImageManifestEntry,
+  ImageVariant,
+  ImageOptimizationParams,
+  ProcessedImage,
+} from '@ereo/plugin-images';
+```
+
+## Documentation
+
+For full documentation, visit the [EreoJS Images Plugin Documentation](https://ereojs.dev/docs/api/plugins/images).
+
+### Documentation Sections
+
+- **[Basic Usage](#quick-start)** - Getting started with the plugin
+- **[Image Component](https://ereojs.dev/docs/api/plugins/images#image-component)** - Props and examples
+- **[Picture Component](https://ereojs.dev/docs/api/plugins/images#picture-component)** - Art direction support
+- **[TypeScript API Reference](https://ereojs.dev/docs/api/plugins/images#typescript-api-reference)** - All exported interfaces
+- **[ImageProcessor Direct Usage](https://ereojs.dev/docs/api/plugins/images#imageprocessor-direct-usage)** - Programmatic processing
+- **[BuildOptimizer Integration](https://ereojs.dev/docs/api/plugins/images#buildoptimizer-integration)** - Build-time optimization
+- **[ManifestManager](https://ereojs.dev/docs/api/plugins/images#manifestmanager)** - Tracking processed images
+- **[Blur Generation Functions](https://ereojs.dev/docs/api/plugins/images#blur-generation-functions)** - LQIP utilities
+- **[Color Utilities](https://ereojs.dev/docs/api/plugins/images#color-utilities)** - Color extraction and manipulation
+- **[Error Handling](https://ereojs.dev/docs/api/plugins/images#error-handling)** - ConfigValidationError and patterns
+- **[Caching](https://ereojs.dev/docs/api/plugins/images#caching)** - Memory and disk cache
+- **[Troubleshooting Guide](https://ereojs.dev/docs/api/plugins/images#troubleshooting-guide)** - Common issues and solutions
+
+## Part of EreoJS
+
+This package is part of the [EreoJS](https://github.com/ereojs/ereo) monorepo - a modern full-stack JavaScript framework.
+
+## License
+
+MIT

package/dist/build/manifest.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @ereo/plugin-images - Image Manifest Generation
+ *
+ * Track processed images and their variants.
+ */
+import type { ImageManifestEntry, ImageVariant } from '../components/types';
+/**
+ * Image manifest for tracking all processed images.
+ */
+export interface ImageManifest {
+    /** Manifest version */
+    version: number;
+    /** Build timestamp */
+    buildTime: number;
+    /** Map of source paths to image entries */
+    images: Record<string, ImageManifestEntry>;
+}
+/**
+ * Image manifest manager.
+ */
+export declare class ImageManifestManager {
+    private manifest;
+    private readonly manifestPath;
+    private dirty;
+    constructor(outDir: string);
+    /**
+     * Load the manifest from disk.
+     */
+    load(): Promise<void>;
+    /**
+     * Save the manifest to disk.
+     */
+    save(): Promise<void>;
+    /**
+     * Add or update an image entry.
+     */
+    addImage(sourcePath: string, data: Omit<ImageManifestEntry, 'hash'>): void;
+    /**
+     * Get an image entry by source path.
+     */
+    getImage(sourcePath: string): ImageManifestEntry | undefined;
+    /**
+     * Check if an image needs reprocessing.
+     */
+    needsReprocessing(sourcePath: string, fileHash: string): boolean;
+    /**
+     * Remove an image entry.
+     */
+    removeImage(sourcePath: string): void;
+    /**
+     * Get all image entries.
+     */
+    getAllImages(): Record<string, ImageManifestEntry>;
+    /**
+     * Get total number of images.
+     */
+    getImageCount(): number;
+    /**
+     * Get total number of variants.
+     */
+    getVariantCount(): number;
+    /**
+     * Get total size of all variants.
+     */
+    getTotalSize(): number;
+    /**
+     * Clear all entries.
+     */
+    clear(): void;
+    /**
+     * Generate a hash for an image entry.
+     */
+    private generateHash;
+}
+/**
+ * Generate a virtual module for image metadata.
+ *
+ * This creates a JavaScript module that exports the image metadata
+ * for use by the Image component at runtime.
+ */
+export declare function generateImageModule(entry: ImageManifestEntry, publicPath: string): string;
+/**
+ * Generate a srcset string from image variants.
+ */
+export declare function generateSrcset(variants: ImageVariant[], publicPath: string, format?: string): string;
+/**
+ * Get the best variant for a given width and format.
+ */
+export declare function getBestVariant(variants: ImageVariant[], width: number, format?: string): ImageVariant | undefined;
+/**
+ * Create a new manifest manager.
+ */
+export declare function createManifestManager(outDir: string): ImageManifestManager;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/build/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/build/manifest.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,kBAAkB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAE5E;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAC5C;AAWD;;GAEG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAA0C;IAC1D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,KAAK,CAAS;gBAEV,MAAM,EAAE,MAAM;IAI1B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAa3B;;OAEG;IACH,QAAQ,CACN,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC,GACrC,IAAI;IAWP;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,kBAAkB,GAAG,SAAS;IAI5D;;OAEG;IACH,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAQhE;;OAEG;IACH,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAKrC;;OAEG;IACH,YAAY,IAAI,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC;IAIlD;;OAEG;IACH,aAAa,IAAI,MAAM;IAIvB;;OAEG;IACH,eAAe,IAAI,MAAM;IAOzB;;OAEG;IACH,YAAY,IAAI,MAAM;IAQtB;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,OAAO,CAAC,YAAY;CAUrB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,kBAAkB,EACzB,UAAU,EAAE,MAAM,GACjB,MAAM,CAUR;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,YAAY,EAAE,EACxB,UAAU,EAAE,MAAM,EAClB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAMR;AAED;;GAEG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,YAAY,EAAE,EACxB,KAAK,EAAE,MAAM,EACb,MAAM,CAAC,EAAE,MAAM,GACd,YAAY,GAAG,SAAS,CAY1B;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,oBAAoB,CAE1E"}

package/dist/build/optimizer.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @ereo/plugin-images - Build-time Image Optimizer
+ *
+ * Scans and processes images during the build phase.
+ */
+import type { ImagePluginConfig } from '../components/types';
+import { type ImageManifestManager } from './manifest';
+/**
+ * Build optimizer options.
+ */
+export interface BuildOptimizerOptions {
+    /** Project root directory */
+    root: string;
+    /** Output directory for optimized images */
+    outDir: string;
+    /** Plugin configuration */
+    config?: ImagePluginConfig;
+    /** Directories to scan for images */
+    scanDirs?: string[];
+    /** Whether to force reprocessing all images */
+    force?: boolean;
+    /** Progress callback */
+    onProgress?: (current: number, total: number, file: string) => void;
+}
+/**
+ * Build result statistics.
+ */
+export interface BuildResult {
+    /** Number of images processed */
+    processed: number;
+    /** Number of images skipped (unchanged) */
+    skipped: number;
+    /** Total variants generated */
+    variants: number;
+    /** Total output size in bytes */
+    totalSize: number;
+    /** Processing time in milliseconds */
+    duration: number;
+    /** Any errors encountered */
+    errors: Array<{
+        file: string;
+        error: string;
+    }>;
+}
+/**
+ * Build-time image optimizer.
+ */
+export declare class BuildOptimizer {
+    private readonly config;
+    private readonly processor;
+    private readonly manifest;
+    private readonly root;
+    private readonly outDir;
+    private readonly scanDirs;
+    private readonly force;
+    private readonly onProgress?;
+    constructor(options: BuildOptimizerOptions);
+    /**
+     * Run the build optimization.
+     */
+    run(): Promise<BuildResult>;
+    /**
+     * Process a single image file.
+     */
+    private processImage;
+    /**
+     * Scan directories for image files.
+     */
+    private scanForImages;
+    /**
+     * Recursively scan a directory for images.
+     */
+    private scanDirectory;
+    /**
+     * Get output formats based on config and image type.
+     */
+    private getOutputFormats;
+    /**
+     * Generate a variant file path.
+     */
+    private getVariantPath;
+    /**
+     * Hash a buffer for cache invalidation.
+     */
+    private hashBuffer;
+    /**
+     * Get the manifest manager.
+     */
+    getManifest(): ImageManifestManager;
+}
+/**
+ * Create a build optimizer instance.
+ */
+export declare function createBuildOptimizer(options: BuildOptimizerOptions): BuildOptimizer;
+/**
+ * Run a build optimization.
+ */
+export declare function optimizeImages(options: BuildOptimizerOptions): Promise<BuildResult>;
+//# sourceMappingURL=optimizer.d.ts.map

package/dist/build/optimizer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimizer.d.ts","sourceRoot":"","sources":["../../src/build/optimizer.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,iBAAiB,EAAoC,MAAM,qBAAqB,CAAC;AAE/F,OAAO,EAAyB,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAI9E;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,qCAAqC;IACrC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,+CAA+C;IAC/C,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wBAAwB;IACxB,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACrE;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,sCAAsC;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuB;IAChD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAU;IAChC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAyD;gBAEzE,OAAO,EAAE,qBAAqB;IAW1C;;OAEG;IACG,GAAG,IAAI,OAAO,CAAC,WAAW,CAAC;IAiEjC;;OAEG;YACW,YAAY;IA4G1B;;OAEG;YACW,aAAa;IAgB3B;;OAEG;YACW,aAAa;IAqB3B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAoBxB;;OAEG;IACH,OAAO,CAAC,cAAc;IAOtB;;OAEG;IACH,OAAO,CAAC,UAAU;IAIlB;;OAEG;IACH,WAAW,IAAI,oBAAoB;CAGpC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,qBAAqB,GAAG,cAAc,CAEnF;AAED;;GAEG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,WAAW,CAAC,CAGzF"}

package/dist/components/Image.d.ts

@@ -0,0 +1,28 @@
+/**
+ * @ereo/plugin-images - Image Component
+ *
+ * Optimized image component with automatic srcset, placeholders, and lazy loading.
+ */
+import React from 'react';
+import type { ImageProps } from './types';
+/**
+ * EreoJS Image Component
+ *
+ * A drop-in replacement for the HTML img element with automatic optimization.
+ *
+ * @example
+ * // Basic usage
+ * <Image src="/hero.jpg" alt="Hero image" width={800} height={600} />
+ *
+ * // With static import
+ * import heroImg from './hero.jpg';
+ * <Image src={heroImg} alt="Hero" placeholder="blur" />
+ *
+ * // Fill parent container
+ * <div style={{ position: 'relative', width: '100%', height: 400 }}>
+ *   <Image src="/bg.jpg" alt="Background" fill objectFit="cover" />
+ * </div>
+ */
+export declare const Image: React.ForwardRefExoticComponent<ImageProps & React.RefAttributes<HTMLImageElement>>;
+export default Image;
+//# sourceMappingURL=Image.d.ts.map

package/dist/components/Image.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Image.d.ts","sourceRoot":"","sources":["../../src/components/Image.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAA2D,MAAM,OAAO,CAAC;AAChF,OAAO,KAAK,EAAE,UAAU,EAAsC,MAAM,SAAS,CAAC;AA2F9E;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,KAAK,qFAkOhB,CAAC;AAIH,eAAe,KAAK,CAAC"}

package/dist/components/Picture.d.ts

@@ -0,0 +1,36 @@
+/**
+ * @ereo/plugin-images - Picture Component
+ *
+ * Art direction component for responsive images with different sources.
+ */
+import React from 'react';
+import type { PictureProps } from './types';
+/**
+ * EreoJS Picture Component
+ *
+ * Provides art direction for responsive images, allowing different images
+ * to be served at different breakpoints.
+ *
+ * @example
+ * // Art direction with different images for mobile/desktop
+ * <Picture
+ *   alt="Hero image"
+ *   sources={[
+ *     { src: heroMobile, media: '(max-width: 640px)' },
+ *     { src: heroDesktop, media: '(min-width: 641px)' },
+ *   ]}
+ * />
+ *
+ * // With format-based sources
+ * <Picture
+ *   alt="Product photo"
+ *   sources={[
+ *     { src: '/product.avif', type: 'image/avif' },
+ *     { src: '/product.webp', type: 'image/webp' },
+ *     { src: '/product.jpg' },
+ *   ]}
+ * />
+ */
+export declare const Picture: React.ForwardRefExoticComponent<PictureProps & React.RefAttributes<HTMLImageElement>>;
+export default Picture;
+//# sourceMappingURL=Picture.d.ts.map

package/dist/components/Picture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Picture.d.ts","sourceRoot":"","sources":["../../src/components/Picture.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAwC,MAAM,OAAO,CAAC;AAC7D,OAAO,KAAK,EAAE,YAAY,EAAqD,MAAM,SAAS,CAAC;AAiF/F;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,OAAO,uFAgOlB,CAAC;AAIH,eAAe,OAAO,CAAC"}

package/dist/components/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @ereo/plugin-images - Component Exports
+ *
+ * React components for optimized images.
+ */
+export { Image, default as ImageComponent } from './Image';
+export { Picture, default as PictureComponent } from './Picture';
+export type { ImageProps, PictureProps, PictureSource, StaticImageData, PlaceholderType, ObjectFit, ObjectPosition, ImageLoading, ImageDecoding, ImageLoader, ImageLoaderParams, } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,KAAK,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,SAAS,CAAC;AAC3D,OAAO,EAAE,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,WAAW,CAAC;AACjE,YAAY,EACV,UAAU,EACV,YAAY,EACZ,aAAa,EACb,eAAe,EACf,eAAe,EACf,SAAS,EACT,cAAc,EACd,YAAY,EACZ,aAAa,EACb,WAAW,EACX,iBAAiB,GAClB,MAAM,SAAS,CAAC"}