img-upload-kit 1.1.1 → 2.0.1

package/README.md

@@ -1,259 +1,243 @@
-# img-upload-kit
-
-Production-grade, zero-lock-in image upload and processing framework with **Sharp AVIF/WebP optimization**, **smart size-guarding**, **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 any image to inspect real-time byte savings, dimensions, and color extraction.
-- **Studio Source Code**: Open source at [`MoElsherbiny/image-upload-kit-studio`](https://github.com/MoElsherbiny/image-upload-kit-studio).
-
----
-
-## The Problems Solved
-
-1. **Pipeline Fragmentation**: Eliminates stitching separate libraries for file validation, resizing, AVIF/WebP conversion, placeholder generation, storage uploading, and UI forms. Provides one unified pipeline from browser dropzone to CDN.
-2. **AVIF Bloat on Pre-compressed JPEGs**: Naive AVIF converters expand pre-compressed inputs by 30–80%. Our **Sharp Size-Guard** evaluates output bytes against source size, scales quality proportionally, and falls back to WebP or passthrough.
-3. **Cumulative Layout Shift (CLS)**: Eliminates layout shifts by generating instant **WebP LQIP data URLs** (<8KB), client-decoded **BlurHash** strings, and **4-edge ambient colors** before full-resolution assets load.
-4. **Storage Vendor Lock-in**: Decouples application logic from cloud vendors via a uniform `StorageAdapter` contract across AWS S3, Cloudflare R2, Supabase, Local Filesystem, or In-Memory (testing).
-5. **UI Styling Lock-in**: Provides 4 styling tiers: default `--iuk-*` CSS tokens, `unstyled` mode with Tailwind/CSS Modules, partial slot renderers, or 100% headless hooks and primitives.
-
----
-
-## Installation
-
-```bash
-# npm
-npm install img-upload-kit
-# pnpm
-pnpm add img-upload-kit
-# yarn
-yarn add img-upload-kit
-# bun
-bun add img-upload-kit
-
-# Optional peer dependencies (only if using React or Headless UI):
-npm install react react-dom
-```
-
-> **Requirements**: Node.js `>= 18.17.0` on the server for `sharp` and Web Fetch `Request`/`FormData` APIs. React `>= 18.0.0` for UI components.
-
----
-
-## 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` |
-| `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 powered by `--iuk-*` design tokens (supports dark mode & RTL) |
-
----
-
-## Universal Presets Reference
-
-Built-in visual role presets balance dimension constraints, compression quality, and blur generation:
-
-| Preset | Max Dimensions | Max Size | Quality | Allowed Formats | Blur / Notes |
-| --- | --- | --- | --- | --- | --- |
-| `thumbnail` | `600x600` | 5 MB | Q78 | JPEG, PNG, WebP, AVIF | Medium quality, compact size |
-| `avatar` | `512x512` | 5 MB | Q80 | JPEG, PNG, WebP, AVIF | Medium quality, square profile |
-| `card` | `1200x900` | 8 MB | Q85 | JPEG, PNG, WebP, AVIF, SVG | High quality content cards |
-| `cover` | `1920x1080` | 10 MB | Q88 | JPEG, PNG, WebP, AVIF, SVG | High quality wide banners |
-| `hero` | `2560x1440` | 15 MB | Q92 | JPEG, PNG, WebP, AVIF, SVG | Maximum detail for hero headers |
-| `logo` | `800x800` | 5 MB | Q90 | JPEG, PNG, WebP, AVIF, SVG | Vector SVG passthrough & sharp edges |
-| `original` | `4096x4096` | 25 MB | Q95 | JPEG, PNG, WebP, AVIF, SVG | Preserves maximum master fidelity |
-
-```ts
-import { defineUploadPresets } from 'img-upload-kit';
-
-export const presets = defineUploadPresets({
-  'product-gallery': {
-    folder: 'catalog/products',
-    maxDimensions: { width: 1600, height: 1600 },
-    maxSizeMB: 10,
-    quality: 85,
-    includeBlurHash: true,
-  },
-});
-```
-
----
-
-## Subpath Usage Guides
-
-### 1. Server Uploader & Route Handler (`/server` & `/storage`)
-
-```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';
-
-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' });
-export const { POST, DELETE } = createUploadHttpHandler({ uploader });
-```
-
-### 2. Client Provider & Upload UI (`/react` & `/styles.css`)
-
-```tsx
-import { useState } from 'react';
-import { ImageUploadProvider, SingleImageUpload, MultiImageUpload } from 'img-upload-kit/react';
-import type { UploadedImageData } from 'img-upload-kit';
-import 'img-upload-kit/styles.css';
-
-export function MediaForm() {
-  const [avatar, setAvatar] = useState<UploadedImageData | null>(null);
-  const [gallery, setGallery] = useState<UploadedImageData[]>([]);
-
-  return (
-    <ImageUploadProvider endpoint="/api/upload" locale="en">
-      <SingleImageUpload preset="avatar" label="Avatar" value={avatar} onChange={setAvatar} />
-      <MultiImageUpload preset="card" label="Gallery" value={gallery} onChange={setGallery} maxImages={10} />
-    </ImageUploadProvider>
-  );
-}
-```
-
-### 3. Build-Time Blur Manifests & Runtime Lookup (`/cli` & `/blur`)
-
-```bash
-npx img-upload-kit generate --dir ./public/images --out ./src/blur-manifest.json
-```
-```ts
-import { createBlurService } from 'img-upload-kit/blur';
-import manifest from './blur-manifest.json';
-
-const blurService = createBlurService({ manifest });
-const { color, blur: blurDataUrl } = blurService.getProgressiveData('/images/hero.avif');
-```
-
----
-
-## The 4 Styling Tiers
-
-Customize UI components cleanly at any level of abstraction:
-
-### Tier 1: CSS Variables (`--iuk-*`) & Automatic Dark Mode
-```css
-:root {
-  --iuk-primary: #4f46e5;
-  --iuk-primary-hover: #4338ca;
-  --iuk-radius-md: 14px;
-}
-.dark { --iuk-primary: #818cf8; --iuk-surface: #0f172a; }
-```
-
-### Tier 2: Unstyled Mode with `classNames` & `data-[state=*]` (Tailwind CSS)
-```tsx
-<SingleImageUpload
-  unstyled value={avatar} onChange={setAvatar}
-  classNames={{
-    dropzone: 'rounded-2xl border-2 border-dashed p-6 text-center data-[state=dragging]:border-indigo-500',
-    browseButton: 'rounded-lg bg-indigo-600 px-4 py-2 text-white',
-  }}
-/>
-```
-
-### Tier 3: Partial Slot Renderers
-```tsx
-<SingleImageUpload
-  value={avatar} onChange={setAvatar}
-  renderDropzone={(ctx) => (
-    <div {...ctx.dropzoneProps} className="p-8 border border-dashed rounded-xl">
-      <button type="button" onClick={ctx.openFileDialog}>Select Photo</button>
-    </div>
-  )}
-/>
-```
-
-### Tier 4: Headless Hooks & Primitives (`/headless`)
-```tsx
-import { HeadlessSingleUpload, useDropzone } from 'img-upload-kit/headless';
-
-<HeadlessSingleUpload preset="avatar" value={avatar} onChange={setAvatar}>
-  {(ctrl) => (
-    <div {...ctrl.getDropzoneProps()}>
-      <input {...ctrl.getInputProps()} />
-      {ctrl.preview ? <img src={ctrl.preview} alt="" /> : <button type="button" onClick={ctrl.openFileDialog}>Upload</button>}
-    </div>
-  )}
-</HeadlessSingleUpload>
-```
-
----
-
-## AnimatedImage (Blur-Up Display Component)
-
-`<AnimatedImage />` provides an instant blur-up placeholder crossfade to full resolution without layout shift:
-
-```tsx
-import { AnimatedImage } from 'img-upload-kit/react';
-import 'img-upload-kit/styles.css';
-
-// 1. Direct shorthand with UploadedImageData:
-<AnimatedImage image={img} showShimmer />
-
-// 2. Explicit props in standard React:
-<AnimatedImage
-  src={img.url}
-  alt={img.altText || 'Product'}
-  blurDataUrl={img.blurDataUrl}
-  blurHash={img.blurHash}
-  blurColor={img.blurColor}
-  width={800}
-  height={600}
-  showShimmer
-/>
-
-// 3. Next.js App Router (as={Image}):
-import Image from 'next/image';
-<div style={{ position: 'relative', aspectRatio: '16/9' }}>
-  <AnimatedImage image={img} as={Image} fill sizes="100vw" imageComponentProps={{ priority: true, quality: 80 }} />
-</div>
-```
-
----
-
-## Documentation
-
-- [AI Agent Contributor Guide (`AGENTS.md`)](./AGENTS.md) — Architecture, guardrails, and styling tiers for AI agents.
-- [Custom Styling & Headless Guide (`docs/CUSTOM_STYLING.md`)](./docs/CUSTOM_STYLING.md) — Theming, slots, and headless recipes.
-- [AnimatedImage & Blur-Up Guide (`docs/ANIMATED_IMAGE.md`)](./docs/ANIMATED_IMAGE.md) — Progressive reveal component architecture.
-- [Architecture & Internals (`docs/ARCHITECTURE.md`)](./docs/ARCHITECTURE.md) — Sharp size-guarding and 4-edge color math.
-- [Framework & Storage Recipes (`docs/FRAMEWORK_RECIPES.md`)](./docs/FRAMEWORK_RECIPES.md) — Next.js, Hono, Remix, S3, Supabase recipes.
-- [Interactive Studio Code](https://github.com/MoElsherbiny/image-upload-kit-studio) — Source for the live demo playground.
-- [Contributing Guide (`CONTRIBUTING.md`)](./CONTRIBUTING.md) & [Changelog (`CHANGELOG.md`)](./CHANGELOG.md).
-
-## License & Author
-
-**Author & Identity**: [buildwithsherbo](https://www.buildwithsherbo.com/) — Mohamed Elsherbiny
-- **Website**: [buildwithsherbo.com](https://www.buildwithsherbo.com/)
-- **Live Demo**: [upload-kit.buildwithsherbo.com](https://upload-kit.buildwithsherbo.com)
-- **GitHub**: [@MoElsherbiny](https://github.com/MoElsherbiny)
-- **Email**: [mo@buildwithsherbo.com](mailto:mo@buildwithsherbo.com)
-
-Distributed under the [MIT License](./LICENSE).
+# img-upload-kit
+
+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).