img-upload-kit 0.0.0-stage → 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,89 @@
+# Changelog
+
+All notable changes to `img-upload-kit` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.0] - 2026-11-06
+
+See [`MIGRATION.md`](./MIGRATION.md) for step-by-step v1.x to v2.0.0 upgrade instructions and before/after examples.
+
+### Breaking Changes
+
+- **Dependencies**: Moved `sharp` and `lqip-modern` to optional `peerDependencies` (loaded lazily in `img-upload-kit/server` and `img-upload-kit/cli` with actionable install errors). Removed `lucide-react` in favor of zero-dependency inlined SVG icons (`src/react/icons.tsx`).
+- **SVG Disabled by Default**: Removed `image/svg+xml` from `DEFAULT_ALLOWED_FORMATS` and all `STANDARD_PRESETS`. Enable via `allowSvg: true` on `createImageUploader`, a preset, or per-upload options.
+- **Secure-by-Default HTTP Handler**: `createUploadHttpHandler` now ignores client `FormData` overrides (`customFilename`, `folder`, `maxWidth`, `maxHeight`, `outputFormat`, `quality`) unless explicitly opted in via `allowClientOverrides`.
+- **Context-Aware `authorize(ctx)`**: `UploadHttpHandlerOptions.authorize` now receives `AuthorizeContext` (`{ action, request, path?, bucket?, preset? }`).
+- **`<AnimatedImage>` Reveal Parity & Error State**: Default `animationDuration` changed from `700` ms to `600` ms with `scale(1.02 -> 1)` settle reveal (`revealScale`, default `1.02`), `inset: 0; scale(1.1); blur(20px)` placeholder geometry, immediate `5/6` placeholder fade, and `colorPlaceholder="flat"` default for color-only placeholders. On load error, the placeholder remains visible while the broken image is hidden (`data-state="error"`).
+- **Storage, Blur & CLI Contracts**: Removed phantom `-blur.avif` / `-thumb.avif` deletes in Supabase `deleteByUrl`; made `?t=` preview cache-busting opt-in (`appendCacheBuster`); excluded 40px LQIP data URLs from `createSrcSetWithBlur`; preserved `/<bucket>/<path>` in `normalizeImagePath` for Supabase URLs; made `mirrorBufferLocally` async (`Promise<string>`); moved CLI auto-execution to `dist/bin.js`.
+- **Package `exports`**: Updated `package.json` `exports` to nested `import` / `require` conditions with `.d.ts` and `.d.cts` types.
+
+### Security
+
+- **Binary Magic-Byte Sniffing (`sniffImageFormat`)**: Verified binary signatures (JPEG, PNG, GIF, WebP, AVIF/HEIF `ftyp`, TIFF, SVG) against `allowedFormats` before Sharp decoding, blocking spoofed MIME types.
+- **Built-in SVG Sanitizer (`sanitizeSvg`)**: Dependency-free allowlist sanitizer when `allowSvg: true` that strips `<script>`, `<foreignObject>`, `<iframe|embed|object>`, `on*` handlers, unsafe `href`/`xlink:href` targets, and `<!ENTITY`/`DOCTYPE` declarations.
+- **HTTP Handler Guards**: Added streaming `maxBodyBytes` enforcement (HTTP `413`), `allowedOrigins` CSRF validation (HTTP `403`), `DELETE` bucket allowlist enforcement (HTTP `403`), client filename extension enforcement + non-upsert collision suffixing, generic HTTP `500` error bodies with `onError(error, ctx)`, and `limitInputPixels` (default 50 MP) decompression-bomb protection.
+- **Local Filesystem Containment**: Hardened `createLocalFsStorageAdapter` with `path.relative` traversal checks, Windows drive/colon rejection, and atomic `flag: 'wx'` writes when `upsert: false`.
+
+### Added
+
+- **Responsive Image Variants (`variantWidths`)**: Generate multi-width responsive variants (`<base>-<w>w.<ext>`) in parallel, returning `variants: ImageVariant[]` and `srcSet` on `UploadedImageData` and cleaning up all variants in `deleteImage`. `<AnimatedImage image={data} />` automatically wires `srcSet` and default `sizes="100vw"` when `fill` is set.
+- **Clipboard Paste & Mobile Camera Capture**: Added `enablePaste` (default `true`), `pasteTarget: 'dropzone' | 'document'`, and `capture?: 'user' | 'environment'` across `<SingleImageUpload>`, `<MultiImageUpload>`, and headless controllers (`useClipboardPaste`).
+- **Per-Tile Cancel & Retry**: Added per-upload `AbortController` cancellation (`cancel(id)` / tile Cancel button) and per-tile or batch retry (`retry(id)` / `retryAll()`), plus `onUploadStart`, `onUploadComplete`, and `onUploadCancel` callbacks.
+- **Form Integration (`name`, `formValue`, `ref`, `required`, `minImages`)**: Synchronized `<input type="hidden" name={name} />` (`formValue: 'url' | 'json'`), `forwardRef<ImageUploadHandle>` (`{ focus, open, clear }`), `onBlur`, and native constraint validation for `required` and `minImages`.
+- **`<AnimatedImage>` Props**: Added first-class `priority` and `quality` props (preventing Next.js `loading="lazy"` conflicts), `revealScale`, `colorPlaceholder: 'flat' | 'gradient'`, `neutralColors`, `fallbackSrc` (single automatic retry), `renderError`, and `var(--token)` support in `resolveBackgroundColor`.
+- **Edge-Safe Handler & Modular CSS Exports**: Added `img-upload-kit/server/handler` (zero Sharp/`node:fs` imports), `img-upload-kit/styles/*.css` layer exports, and `scripts/check-dist.mjs` build verification.
+
+### Fixed
+
+- **RSC `'use client'` & Shared Singletons**: Preserved `'use client'` directives at the top of all client chunks and deduplicated `ImageUploadContext` and `blurService` across `img-upload-kit/react`, `img-upload-kit/headless`, and `img-upload-kit/blur`.
+- **Server & Storage Correctness**: Fixed passthrough EXIF `.rotate()` and dimension swapping (EXIF 5–8), preserved GIF/TIFF/HEIF format labels, held `AsyncSemaphore` slots until timed-out Sharp jobs settle, rolled back uploaded storage objects when `onUploadRecord` throws, added S3 `IfNoneMatch: '*'` for `upsert: false`, and paginated S3/Supabase `list()`.
+- **React State, Memory & Accessibility**: Fixed parallel upload progress races (`uploadTracker`), stale alt text on replacement, `URL.createObjectURL` preview cleanup, modal focus trapping/restoration (`useDialog`), WAI-ARIA radio keyboard navigation in `<QualitySelector>`, `role="progressbar"` attributes, and `aria-live="polite"` upload announcements.
+
+### Performance
+
+- **Single-Decode Blur Pipeline**: `generateBlurPlaceholder` now decodes the source image once into a 128 px buffer and derives the WebP LQIP data URL, 4-edge dominant color histogram, and BlurHash from the shared buffer (reducing Sharp decodes from 3–4 to 1).
+- **Web Crypto & Object URLs**: Replaced `FileReader.readAsDataURL` client previews with zero-copy `URL.createObjectURL` and migrated server hashing to `globalThis.crypto`.
+
+## [1.1.0] - 2026-10-31
+
+### Added
+
+- **AnimatedImage Component (`img-upload-kit/react`)**:
+  - High-performance progressive blur-up display component with GPU-accelerated crossfade.
+  - Native `<img>` attribute pass-through and framework-agnostic `as` prop (e.g. `as={Image}` for Next.js with `imageComponentProps`).
+  - Hierarchical placeholder fallback cascade: `blurDataUrl` (LQIP) > `blurHash` (client canvas decode) > `blurColor` (gradient SVG).
+  - Shimmer highlight animation (`showShimmer`), staggered transition timing, and full `prefers-reduced-motion` compliance.
+  - Semantic slot targeting (`data-slot`, `data-state`, `aria-busy`) and unstyled mode support.
+- **Headless Reveal State Machine (`useImageReveal`)**:
+  - Headless hook managing progressive reveal states (`isLoaded`, `showPlaceholder`, `hasError`, `imgRef`, `handleLoad`, `handleError`).
+  - Guarantees pre-decode verification via `HTMLImageElement.decode()` before revealing sharp asset.
+  - Synchronous reset on `srcKey` changes and automatic detection of pre-cached images.
+- **Placeholder Utilities**:
+  - `createFallbackBlurSvg`: Generates lightweight inline SVG gradients derived from dominant color.
+  - `resolveMeaningfulColor`: Filters out generic neutral/black/white database defaults and validates color tokens.
+  - `resolvePlaceholderUrl`: Deterministically selects the best available placeholder asset.
+
+### Changed & Hardened
+
+- **Server Validation Error Mapping**: Updated `createUploadHttpHandler.POST` to map client validation errors directly to HTTP 400 Bad Request.
+- **Collision Retry Discrimination**: Fixed collision detection in `uploadRetry.ts` to strictly match `already exists` and `EEXIST` error codes.
+- **Sharp Mobile EXIF Auto-Rotation**: Added `.rotate()` during Sharp pipeline initialization in `imageOptimizer.ts`.
+- **Transparent PNG Color Extraction**: Hardened `colorHistogram.ts` to ignore pixels with `alpha < 8`.
+- **BlurHash & SVG Detection**: Enhanced SVG validation in `blurGenerator.ts` and clamped BlurHash components to valid ranges (1–9).
+- **Storage Parity & Upsert Semantics**: Implemented `deleteByUrl` in `createLocalFsStorageAdapter` and aligned default `upsert` semantics to `true`.
+- **React Pure State Updaters & Controlled Value Sync**: Refactored `useMultiImageState.ts` and `useSingleImageState.ts` for strict React 18/19 concurrent rendering purity.
+- **Batch Preemption Clearing in Multi-Upload**: Fixed retention window in `MultiImageUpload.tsx` when preempted by a new upload batch.
+
+## [1.0.0] - 2026-10-31
+
+### Added
+
+- **Core Types & Utilities (`img-upload-kit`)**: Universal visual role presets (`thumbnail`, `avatar`, `card`, `cover`, `hero`, `logo`, `original`), `defineUploadPresets`, `UploadKitRegister`, bilingual (`en` / `ar`) validation, byte formatters, and RGB/HEX color utilities.
+- **Server Optimization & Upload Pipeline (`img-upload-kit/server`)**: `createImageUploader`, `createUploadHttpHandler`, `optimizeImage` with Sharp AVIF size-guarding, and `generateBlurPlaceholder` (WebP LQIP, BlurHash, 4-edge color histogram).
+- **Pluggable Storage Adapters (`img-upload-kit/storage`)**: `createSupabaseStorageAdapter`, `createS3StorageAdapter`, `createLocalFsStorageAdapter`, `createMemoryStorageAdapter`, and `onUploadRecord`.
+- **Blur Manifest Service (`img-upload-kit/blur`)**: `BlurService` and `createBlurService` with bounded `LRUCache`.
+- **Pure React UI & Styles (`img-upload-kit/react`, `img-upload-kit/styles.css`)**: `<ImageUploadProvider>`, `<ImageUpload>`, `<SingleImageUpload>`, `<MultiImageUpload>`, `<BlurImage>`, and `<QualitySelector>` with RTL & `--iuk-*` tokens.
+- **Headless Hooks & Primitives (`img-upload-kit/headless`)**: `HeadlessSingleUpload`, `HeadlessMultiUpload`, `useSingleUpload`, `useMultiUpload`, `useImageUpload`, `useDropzone`, `useFilePreview`.
+- **Blur Manifest CLI (`img-upload-kit/cli`)**: `img-upload-kit` / `blur-cli` binaries (`generate`, `validate`, `sync`, `cleanup`, `health`, `inspect`).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mo Elsherbiny (https://www.buildwithsherbo.com/)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MIGRATION.md

@@ -0,0 +1,192 @@
+# Migrating from v1.x to v2.0.0
+
+`img-upload-kit` v2.0.0 hardens security by default, aligns `<AnimatedImage>` with production motion standards, fixes RSC `'use client'` bundling and shared React contexts, and introduces responsive variants, clipboard paste, camera capture, per-tile cancel/retry, and native form integration.
+
+---
+
+## 1. Dependencies & Peer Dependencies (`sharp`, `lqip-modern`, `lucide-react`)
+
+- **`sharp` & `lqip-modern` are now optional peer dependencies.** Client-only or Edge consumers no longer download native Sharp binaries when installing `img-upload-kit`. Server (`img-upload-kit/server`) and CLI (`img-upload-kit/cli`) consumers must install `sharp` (and optionally `lqip-modern`).
+- **`lucide-react` has been removed.** All UI icons are now inlined inside `img-upload-kit/react` (`src/react/icons.tsx`) with zero external icon dependencies.
+- **Node.js `>= 20.0.0`** is recommended for development and server runtimes.
+
+### Before (v1.x)
+```bash
+npm install img-upload-kit
+```
+
+### After (v2.0.0)
+```bash
+# Client-only / React UI:
+npm install img-upload-kit react react-dom
+
+# Server / Full-Stack (Next.js, Remix, Hono, Node.js) or CLI:
+npm install img-upload-kit sharp lqip-modern
+```
+
+---
+
+## 2. SVG Uploads Disabled by Default (`allowSvg`) & Magic-Byte Sniffing
+
+- **SVG (`image/svg+xml`) is disabled by default** across `DEFAULT_ALLOWED_FORMATS` and all `STANDARD_PRESETS` (including `logo`) to prevent stored XSS and XXE out of the box.
+- **Opt-in with `allowSvg: true`** on `createImageUploader`, a preset, or a per-upload call. When enabled, SVGs pass through a built-in dependency-free allowlist sanitizer (`sanitizeSvg`) that strips `<script>`, `<foreignObject>`, `on*` handlers, unsafe `href`/`xlink:href` URIs, and `<!ENTITY` declarations.
+- **Mandatory magic-byte sniffing (`sniffImageFormat`)**: Every upload inspects binary magic bytes rather than trusting `file.type`. Spoofed files (e.g. SVG or HTML disguised as `image/png`) are rejected with `UploadValidationError` (HTTP `400`).
+
+### Before (v1.x)
+```ts
+const uploader = createImageUploader({ storage });
+// SVG was accepted on card, cover, hero, logo, original without sanitization
+await uploader.uploadImage(svgFile, { preset: 'logo' });
+```
+
+### After (v2.0.0)
+```ts
+const uploader = createImageUploader({
+  storage,
+  allowSvg: false, // Default — opt in globally or per preset:
+  presets: defineUploadPresets({
+    logo: {
+      folder: 'logos',
+      maxDimensions: { width: 800, height: 800 },
+      allowSvg: true, // Sanitizes SVG before storage
+    },
+  }),
+});
+```
+
+---
+
+## 3. Secure-by-Default HTTP Handler (`allowClientOverrides`, `maxBodyBytes`, `allowedOrigins`, `onError`)
+
+`createUploadHttpHandler` now ignores client-supplied `FormData` overrides (`customFilename`, `folder`, `maxWidth`, `maxHeight`, `outputFormat`, `quality`) unless explicitly enabled via `allowClientOverrides`:
+
+- **Client overrides**: Clamped to preset `maxDimensions`. Client `customFilename` never forces `upsert: true` (preventing arbitrary object overwrites) and always uses the optimized output extension. Invalid `quality` values return HTTP `400`.
+- **Body size & CSRF protection**: Enforces `maxBodyBytes` (streaming byte limit, HTTP `413`) and `allowedOrigins` (HTTP `403`).
+- **`DELETE` bucket allowlist**: Rejects attempts to delete URLs/buckets outside the uploader's configured buckets (HTTP `403`).
+- **Generic `500` responses**: Internal error messages and paths are never leaked to clients (`{ "error": "Internal server error" }`); inspect raw errors with `onError(error, ctx)`.
+- **Edge-safe handler subpath**: Import `createUploadHttpHandler` from `img-upload-kit/server/handler` when running in Edge runtimes without Sharp or `node:fs`.
+
+### Before (v1.x)
+```ts
+// Client FormData could freely override folder, customFilename, maxWidth, quality
+export const { POST, DELETE } = createUploadHttpHandler({ uploader });
+```
+
+### After (v2.0.0)
+```ts
+export const { POST, DELETE } = createUploadHttpHandler({
+  uploader,
+  maxBodyBytes: 15 * 1024 * 1024,
+  allowedOrigins: ['https://app.example.com'],
+  allowClientOverrides: {
+    filename: true,
+    folder: (folder) => (folder.startsWith('users/') ? folder : null),
+    dimensions: true, // Clamped to preset maxDimensions
+    format: true,
+    quality: true,
+  },
+  onError: (error, ctx) => {
+    console.error(`[upload:${ctx.action}]`, error);
+  },
+});
+```
+
+---
+
+## 4. Context-Aware `authorize(ctx)` Signature
+
+`UploadHttpHandlerOptions.authorize` now receives an `AuthorizeContext` object (`{ action, request, path?, bucket?, preset? }`) instead of a bare `Request`. Throwing inside `authorize` now returns HTTP `401 Unauthorized` instead of `500`.
+
+### Before (v1.x)
+```ts
+const handler = createUploadHttpHandler({
+  uploader,
+  authorize: async (request: Request) => {
+    return request.headers.get('authorization') === 'Bearer secret';
+  },
+});
+```
+
+### After (v2.0.0)
+```ts
+const handler = createUploadHttpHandler({
+  uploader,
+  authorize: async ({ action, request, preset, bucket, path }) => {
+    if (action === 'delete' && bucket !== 'media') return false;
+    return request.headers.get('authorization') === 'Bearer secret';
+  },
+});
+```
+
+---
+
+## 5. `<AnimatedImage>` Visual Defaults, `priority`, & Error Handling
+
+1. **Reveal animation & timing**: Default `animationDuration` changed from `700` ms to `600` ms. The image now transitions from `opacity: 0; transform: scale(1.02)` to `opacity: 1; transform: scale(1)` (`revealScale` prop, default `1.02`). The placeholder uses `inset: 0; scale(1.1); blur(20px)`, fades immediately (`0ms` delay) over `duration * 5 / 6` (`500ms`), and unmounts at `duration + 50ms`.
+2. **Color-only placeholder (`colorPlaceholder`)**: When only `blurColor` is provided (no `blurDataUrl` or `blurHash`), `<AnimatedImage>` defaults to `colorPlaceholder="flat"` (paints wrapper `backgroundColor` without mounting an extra SVG `<img>`). Pass `colorPlaceholder="gradient"` for the v1 SVG layer. Wrapper backgrounds also accept `var(--css-token)`.
+3. **First-class `priority` & `quality`**: Passing `priority` sets `loading="eager"` + `fetchPriority="high"` on native `<img>` and forwards `priority` to custom `as={Image}` components without conflicting with `loading="lazy"`.
+4. **Placeholder-preserving error state**: On load error, the placeholder remains visible, the broken `<img>` is hidden (`visibility: hidden`, `data-state="error"`), `fallbackSrc` is retried once if provided, and `renderError={({ src, retry }) => ...}` renders custom recovery UI.
+
+### Before (v1.x)
+```tsx
+// Next.js threw when passing priority via imageComponentProps due to forced loading="lazy"
+<AnimatedImage
+  image={img}
+  as={Image}
+  imageComponentProps={{ priority: true, quality: 85 }}
+/>
+```
+
+### After (v2.0.0)
+```tsx
+// First-class priority & quality props, fallbackSrc, and optional v1 fade restore:
+<AnimatedImage
+  image={img}
+  as={Image}
+  priority
+  quality={85}
+  fallbackSrc="/images/fallback.webp"
+  renderError={({ retry }) => <button onClick={retry}>Retry</button>}
+  // Optional: restore v1 pure opacity fade & SVG color gradient
+  animationDuration={700}
+  revealScale={1}
+  colorPlaceholder="gradient"
+/>
+```
+
+---
+
+## 6. Storage, Preview Cache-Busting, Blur & CLI Updates
+
+- **Supabase `deleteByUrl`**: No longer issues speculative deletes for non-existent `-blur.avif` / `-thumb.avif` sibling paths.
+- **Opt-in `?t=` preview cache-buster**: `<SingleImageUpload>` and `<PreviewTile>` no longer append `?t=...` by default (which previously invalidated pre-signed S3/R2/GCS URLs). Opt in with `<PreviewTile appendCacheBuster />` or `appendCacheBuster(url, { enabled: true })` (signed URLs are always skipped).
+- **`createSrcSetWithBlur` & `preloadImageWithBlur`**: `createSrcSetWithBlur` no longer injects the 40px LQIP data URL into `srcset`, and `preloadImageWithBlur` deduplicates `<link rel="preload">` tags without overriding `imagesrcset`.
+- **`normalizeImagePath`**: Preserves `/<bucket>/<path>` for Supabase public URLs consistently with S3 path-style URLs.
+- **`mirrorBufferLocally` & CLI entry**: `mirrorBufferLocally` is now async (`Promise<string>`). Importing `img-upload-kit/cli` has zero side effects (the CLI binary entry moved to `dist/bin.js`).
+
+### Before (v1.x)
+```tsx
+// Mutated preview URLs with ?t=..., breaking X-Amz-Signature on presigned URLs
+<PreviewTile preview={item} onRemove={onRemove} />
+```
+
+### After (v2.0.0)
+```tsx
+// Preserves URLs verbatim by default; opt in when overwriting static paths:
+<PreviewTile preview={item} onRemove={onRemove} appendCacheBuster />
+```
+
+---
+
+## 7. Package `exports` & Per-Layer CSS Subpaths
+
+`package.json` `exports` now use nested `import` / `require` conditions with dedicated `.d.ts` and `.d.cts` declarations, and expose individual CSS layers under `img-upload-kit/styles/*.css`:
+
+```ts
+// Full stylesheet (unchanged):
+import 'img-upload-kit/styles.css';
+
+// Or import individual CSS layers in v2.0:
+import 'img-upload-kit/styles/tokens.css';
+import 'img-upload-kit/styles/animated-image.css';
+```

package/README.md

@@ -1,3 +1,243 @@
-# Temporary Holding Version
+# img-upload-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Production-grade, zero-lock-in image upload and processing framework with **Sharp AVIF/WebP optimization**, **smart size-guarding**, **responsive `srcSet` variants**, **WebP LQIP & BlurHash placeholders**, **4-edge dominant color extraction**, **pluggable storage adapters**, **4 styling tiers**, and the **`<AnimatedImage />` blur-up display component** for React & Next.js.
+
+[![Live Interactive Demo](https://img.shields.io/badge/Live%20Demo-upload--kit.buildwithsherbo.com-0284c7?style=for-the-badge)](https://upload-kit.buildwithsherbo.com)
+[![npm version](https://img.shields.io/npm/v/img-upload-kit?color=38bdf8&style=for-the-badge)](https://www.npmjs.com/package/img-upload-kit)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](./LICENSE)
+[![Studio Repo](https://img.shields.io/badge/Studio%20Code-image--upload--kit--studio-1e293b?style=for-the-badge&logo=github)](https://github.com/MoElsherbiny/image-upload-kit-studio)
+
+---
+
+## Interactive Studio & Live Demo
+
+Experience the full pipeline live in your browser: 👉 **[upload-kit.buildwithsherbo.com](https://upload-kit.buildwithsherbo.com)**
+
+- **Watch Code Stream Live**: Synchronized Shiki IDE writing `<AnimatedImage />`, upload route, and UI code while the live preview mutates at 60 FPS.
+- **4-Layer Placeholder Lab**: Side-by-side comparison of **4-Edge Ambient Color** (0 B runtime), **Client BlurHash** (~28 chars), **WebP LQIP Data URL** (<1 KB), and the final **Sharp AVIF/WebP** asset.
+- **Sharp Size-Guard Sandbox**: Drop or paste any image to inspect real-time byte savings, responsive `srcSet` variants, dimensions, and color extraction.
+- **Upgrading from v1.x?** Read the [**v2.0 Migration Guide (`MIGRATION.md`)**](./MIGRATION.md).
+
+---
+
+## Installation
+
+```bash
+# Client / React UI only (zero native dependencies):
+npm install img-upload-kit react react-dom
+
+# Server / Full-Stack (Next.js, Remix, Hono, SvelteKit, Node) or CLI:
+npm install img-upload-kit sharp lqip-modern
+
+# pnpm / yarn / bun:
+pnpm add img-upload-kit sharp lqip-modern
+```
+
+> **Requirements**: Node.js `>= 20.0.0` on the server for `sharp` and Web Fetch `Request`/`FormData` APIs. React `>= 18.0.0` for UI components (`lucide-react` is no longer required — all icons are inlined).
+
+---
+
+## Subpath Exports Reference
+
+| Subpath | Environment | Key Exports |
+| --- | --- | --- |
+| `img-upload-kit` | Universal | `STANDARD_PRESETS`, `defineUploadPresets`, types, color utils, validators, `createMemoryStorageAdapter`, `decodeBlurHashToDataURL`, `getBlurData` |
+| `img-upload-kit/server` | Node.js | `createImageUploader`, `createUploadHttpHandler`, `optimizeImage`, `generateBlurPlaceholder`, `sniffImageFormat`, `sanitizeSvg` |
+| `img-upload-kit/server/handler` | Node / Edge | Edge-safe `createUploadHttpHandler` (zero Sharp or `node:fs` imports at module load) |
+| `img-upload-kit/storage` | Node / Edge | `createStorageAdapter`, `createS3StorageAdapter`, `createSupabaseStorageAdapter`, `createLocalFsStorageAdapter` |
+| `img-upload-kit/blur` | Universal | `BlurService`, `createBlurService`, `decodeBlurHashToDataURL`, `LRUCache` |
+| `img-upload-kit/react` | React Client | `<ImageUploadProvider>`, `<SingleImageUpload>`, `<MultiImageUpload>`, `<AnimatedImage>`, `<BlurImage>` |
+| `img-upload-kit/headless` | React Client | `<HeadlessSingleUpload>`, `<HeadlessMultiUpload>`, `useSingleUpload`, `useMultiUpload`, `useDropzone` |
+| `img-upload-kit/cli` | Node CLI | CLI binaries (`img-upload-kit` / `blur-cli`) for build-time manifest generation |
+| `img-upload-kit/styles.css` | CSS | Complete stylesheet (`--iuk-*` tokens, dark mode, RTL) + per-layer `img-upload-kit/styles/*.css` |
+
+---
+
+## Universal Presets & Responsive Variants (`variantWidths`)
+
+Built-in visual role presets balance dimension constraints, compression quality, and blur generation. By default, only raster formats (`JPEG, PNG, WebP, AVIF`) are accepted and verified via binary magic-byte sniffing; opt into sanitized SVG support per preset or uploader with `allowSvg: true`.
+
+| Preset | Max Dimensions | Max Size | Quality | Default Formats | Notes |
+| --- | --- | --- | --- | --- | --- |
+| `thumbnail` | `600x600` | 5 MB | Q78 | JPEG, PNG, WebP, AVIF | Compact grid thumbnails |
+| `avatar` | `512x512` | 5 MB | Q80 | JPEG, PNG, WebP, AVIF | Square user profiles |
+| `card` | `1200x900` | 8 MB | Q85 | JPEG, PNG, WebP, AVIF | Content & product cards |
+| `cover` | `1920x1080` | 10 MB | Q88 | JPEG, PNG, WebP, AVIF | Wide section banners |
+| `hero` | `2560x1440` | 15 MB | Q92 | JPEG, PNG, WebP, AVIF | Full-bleed hero headers |
+| `logo` | `800x800` | 5 MB | Q90 | JPEG, PNG, WebP, AVIF | Set `allowSvg: true` for sanitized vector SVGs |
+| `original` | `4096x4096` | 25 MB | Q95 | JPEG, PNG, WebP, AVIF | Master archival fidelity |
+
+```ts
+import { defineUploadPresets } from 'img-upload-kit';
+
+export const presets = defineUploadPresets({
+  hero: {
+    folder: 'banners/hero',
+    maxDimensions: { width: 2560, height: 1440 },
+    variantWidths: [640, 1024, 1920], // Encodes <base>-640w.avif, etc. + populates data.srcSet
+    maxSizeMB: 15,
+    quality: 90,
+    includeBlurHash: true,
+  },
+  logo: {
+    folder: 'brand/logos',
+    maxDimensions: { width: 800, height: 800 },
+    allowSvg: true, // Runs built-in allowlist SVG sanitizer before storage
+  },
+});
+```
+
+---
+
+## Server Uploader & Secure-by-Default HTTP Handler
+
+`createUploadHttpHandler` enforces binary magic-byte sniffing, streaming `maxBodyBytes` limits (HTTP `413`), `allowedOrigins` CSRF checks (HTTP `403`), bucket allowlists on `DELETE`, and generic `500` responses with `onError`. Client `FormData` overrides are ignored unless explicitly enabled in `allowClientOverrides`:
+
+```ts
+// app/api/upload/route.ts (Next.js App Router, Remix, Hono, SvelteKit)
+import { createImageUploader, createUploadHttpHandler } from 'img-upload-kit/server';
+import { createS3StorageAdapter } from 'img-upload-kit/storage';
+import { presets } from '@/lib/upload-presets';
+
+const storage = createS3StorageAdapter({
+  publicBaseUrl: 'https://cdn.example.com',
+  defaultBucket: 'media',
+  putObject: (input) => s3.send(new PutObjectCommand(input)),
+  deleteObject: (input) => s3.send(new DeleteObjectCommand(input)),
+});
+
+export const uploader = createImageUploader({ storage, defaultBucket: 'media', presets });
+
+export const { POST, DELETE } = createUploadHttpHandler({
+  uploader,
+  maxBodyBytes: 16 * 1024 * 1024,
+  allowedOrigins: ['https://app.example.com'],
+  authorize: async ({ action, request, preset, bucket, path }) => {
+    const user = await verifySession(request);
+    if (!user) return false;
+    if (action === 'delete') return user.role === 'admin' && bucket === 'media';
+    return true;
+  },
+  allowClientOverrides: {
+    filename: true, // Sanitized, forced to output extension, never overwrites existing files
+    folder: (folder) => (folder.startsWith('users/') ? folder : null),
+    dimensions: true, // Clamped to preset maxDimensions
+    format: true,
+    quality: true,
+  },
+  onError: (error, ctx) => console.error(`[upload:${ctx.action}]`, error),
+});
+```
+
+---
+
+## React Upload UI: Paste, Camera Capture, Cancel/Retry & Forms
+
+`<SingleImageUpload>` and `<MultiImageUpload>` support **clipboard image paste** (`Ctrl+V` / `Cmd+V`), **mobile camera capture** (`capture="environment"`), **per-tile cancel & retry** (backed by per-upload `AbortController`), and **native HTML form / React Hook Form integration** (`name`, `formValue`, `ref`, `required`, `minImages`, `onBlur`):
+
+```tsx
+import { useRef, useState } from 'react';
+import {
+  ImageUploadProvider,
+  SingleImageUpload,
+  MultiImageUpload,
+  type ImageUploadHandle,
+} from 'img-upload-kit/react';
+import type { UploadedImageData } from 'img-upload-kit';
+import 'img-upload-kit/styles.css';
+
+export function ProductMediaForm() {
+  const uploadRef = useRef<ImageUploadHandle>(null);
+  const [cover, setCover] = useState<UploadedImageData | null>(null);
+  const [gallery, setGallery] = useState<UploadedImageData[]>([]);
+
+  return (
+    <ImageUploadProvider endpoint="/api/upload" locale="en">
+      <form onSubmit={(e) => { e.preventDefault(); /* FormData includes coverUrl & galleryJson */ }}>
+        <SingleImageUpload
+          ref={uploadRef}
+          preset="cover"
+          label="Cover Photo"
+          name="coverUrl"
+          formValue="url"
+          required
+          enablePaste
+          pasteTarget="document"
+          capture="environment"
+          value={cover}
+          onChange={setCover}
+        />
+        <MultiImageUpload
+          mode="multiple"
+          preset="card"
+          label="Product Gallery"
+          name="galleryJson"
+          formValue="json"
+          required
+          minImages={2}
+          maxImages={10}
+          value={gallery}
+          onChange={setGallery}
+          onUploadCancel={(id) => console.log('Cancelled tile:', id)}
+        />
+        <button type="submit">Save Product</button>
+      </form>
+    </ImageUploadProvider>
+  );
+}
+```
+
+---
+
+## AnimatedImage (Progressive Blur-Up & Settle Reveal)
+
+`<AnimatedImage />` delivers a 60 FPS settle reveal (`opacity: 0 -> 1` + `scale(1.02 -> 1)` over `600ms ease-in-out`), pre-decodes via `img.decode()` before crossfading, auto-wires responsive `srcSet` from `image.variants`, and preserves the blurred backdrop on load error with automatic `fallbackSrc` retry:
+
+```tsx
+import { AnimatedImage } from 'img-upload-kit/react';
+import Image from 'next/image';
+import 'img-upload-kit/styles.css';
+
+// 1. Direct shorthand with UploadedImageData (auto-wires variants srcSet, LQIP, blurColor):
+<AnimatedImage image={img} showShimmer />
+
+// 2. Next.js App Router (as={Image} + first-class priority & quality props):
+<div style={{ position: 'relative', aspectRatio: '16/9' }}>
+  <AnimatedImage
+    image={img}
+    as={Image}
+    fill
+    priority
+    quality={85}
+    sizes="(max-width: 768px) 100vw, 1200px"
+    fallbackSrc="/images/fallback-hero.webp"
+    renderError={({ retry }) => <button type="button" onClick={retry}>Reload</button>}
+  />
+</div>
+```
+
+---
+
+## The 4 Styling Tiers
+
+1. **Tier 1 — CSS Variables (`--iuk-*`)**: Automatic dark mode and RTL (`dir="rtl"`) with customizable `--iuk-primary`, `--iuk-surface`, and `--iuk-radius-*` tokens.
+2. **Tier 2 — Unstyled + Slots (`unstyled` + `classNames`)**: Strip built-in styles and target slots (`dropzone`, `tile`, `browseButton`) with Tailwind `data-[state=dragging|uploading|error]:*` selectors.
+3. **Tier 3 — Partial Slot Renderers**: Override specific regions via `renderDropzone`, `renderPreview`, `renderTile`, `renderHeader`, or `renderEmptyDropzone`.
+4. **Tier 4 — Headless Primitives (`img-upload-kit/headless`)**: Full control via `<HeadlessSingleUpload>`, `<HeadlessMultiUpload>`, `useSingleUpload`, and `useMultiUpload` (including `cancel(id)`, `retry(id)`, `retryAll()`, and clipboard paste).
+
+---
+
+## Documentation & Links
+
+- [v2.0 Migration Guide (`MIGRATION.md`)](./MIGRATION.md) & [Post-v2.0 Roadmap (`ROADMAP.md`)](./ROADMAP.md)
+- [AI Agent Contributor Guide (`AGENTS.md`)](./AGENTS.md)
+- [Custom Styling & Headless Guide (`docs/CUSTOM_STYLING.md`)](./docs/CUSTOM_STYLING.md)
+- [AnimatedImage & Blur-Up Guide (`docs/ANIMATED_IMAGE.md`)](./docs/ANIMATED_IMAGE.md)
+- [Architecture & Internals (`docs/ARCHITECTURE.md`)](./docs/ARCHITECTURE.md)
+- [Framework & Storage Recipes (`docs/FRAMEWORK_RECIPES.md`)](./docs/FRAMEWORK_RECIPES.md)
+- [Contributing Guide (`CONTRIBUTING.md`)](./CONTRIBUTING.md) & [Changelog (`CHANGELOG.md`)](./CHANGELOG.md)
+
+## License & Author
+
+**Author & Identity**: [buildwithsherbo](https://www.buildwithsherbo.com/) — Mohamed Elsherbiny ([@MoElsherbiny](https://github.com/MoElsherbiny) · [mo@buildwithsherbo.com](mailto:mo@buildwithsherbo.com))
+Distributed under the [MIT License](./LICENSE).