img-upload-kit 1.1.1 → 2.0.0

package/CHANGELOG.md

@@ -5,6 +5,47 @@ 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
@@ -26,49 +67,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed & Hardened
 
-- **Server Validation Error Mapping**:
-  - Updated `createUploadHttpHandler.POST` to map client validation errors (file size limits, unsupported MIME types, missing file payloads) directly to HTTP 400 Bad Request instead of internal server errors.
-- **Collision Retry Discrimination**:
-  - Fixed collision detection in `uploadRetry.ts` to strictly match `already exists` and `EEXIST` error codes without falsely triggering on `does not exist` messages.
-- **Sharp Mobile EXIF Auto-Rotation**:
-  - Added `.rotate()` during Sharp pipeline initialization in `imageOptimizer.ts` to automatically orient smartphone and digital camera uploads according to EXIF orientation metadata.
-- **Transparent PNG Color Extraction**:
-  - Hardened `colorHistogram.ts` to ignore pixels with `alpha < 8`, preventing transparent PNG graphics from skewing dominant edge colors toward black or white.
-- **BlurHash & SVG Detection**:
-  - Enhanced SVG validation in `blurGenerator.ts` to perform case-insensitive checks across the initial 1024 bytes and clamped BlurHash components to valid ranges (1–9).
-- **Storage Parity & Upsert Semantics**:
-  - Implemented `deleteByUrl` in `createLocalFsStorageAdapter` for parity with cloud storage providers.
-  - Aligned default `upsert` semantics to `true` across all adapters for consistent overwrite behavior.
-- **React Pure State Updaters & Controlled Value Sync**:
-  - Refactored `useMultiImageState.ts` and `useSingleImageState.ts` to maintain synchronous `previewsRef` snapshots.
-  - Removed side-effect dispatches (`emitImmediateChange`) from inside `setPreviews` functional updaters for strict React 18/19 concurrent rendering purity.
-  - Properly reset uploaded data and blur previews when single uploader `value` transitions to `null`.
-- **Batch Preemption Clearing in Multi-Upload**:
-  - Fixed retention window in `MultiImageUpload.tsx`: active batch references are now explicitly cleared when an in-flight retention timer is preempted by a new upload batch.
+- **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 project-agnostic visual role presets (`thumbnail`, `avatar`, `card`, `cover`, `hero`, `logo`, `original`).
-  - `defineUploadPresets` helper and `UploadKitRegister` TypeScript module augmentation for global preset autocomplete.
-  - Bilingual (`en` / `ar`) file validation, quality level presets, byte formatters, and RGB/HEX color utilities.
-- **Server Optimization & Upload Pipeline (`img-upload-kit/server`)**:
-  - `createImageUploader` with preset inheritance, path sanitization, SHA-256 content hashing, retry handling, and `AsyncSemaphore` concurrency control.
-  - `createUploadHttpHandler` returning Web Standard `POST` and `DELETE` Fetch handlers (`Request` -> `Response`) compatible with Next.js App Router, Remix, React Router, Hono, SvelteKit, and Node servers.
-  - `optimizeImage` powered by Sharp with smart AVIF size-guarding (preventing file bloat on pre-compressed JPEGs), WebP fallback, and SVG passthrough.
-  - `generateBlurPlaceholder` generating compact WebP LQIP data URLs, optional BlurHash strings, and 4-edge weighted dominant color histograms.
-- **Pluggable Storage Adapters (`img-upload-kit/storage`)**:
-  - `StorageAdapter` contract and `createStorageAdapter` authoring helper.
-  - Built-in `createSupabaseStorageAdapter`, `createS3StorageAdapter` (AWS S3, Cloudflare R2, MinIO, DigitalOcean Spaces), `createLocalFsStorageAdapter` (with path-traversal protection), and `createMemoryStorageAdapter`.
-  - `onUploadRecord` hook for persisting upload metadata to Prisma, Drizzle, or analytics pipelines.
-- **Blur Manifest Service (`img-upload-kit/blur`)**:
-  - `BlurService` and `createBlurService` with bounded `LRUCache`, normalized URL/path lookup, and SVG fallback placeholders.
-- **Pure React UI & Styles (`img-upload-kit/react`, `img-upload-kit/styles.css`)**:
-  - Framework-agnostic `<ImageUploadProvider>`, `<ImageUpload>`, `<SingleImageUpload>`, `<MultiImageUpload>`, `<BlurImage>`, and `<QualitySelector>`.
-  - First-class English & Arabic (`dir="rtl"`) localization, custom `renderImage` adapter slot, and themeable `--iuk-*` CSS custom properties.
-- **Headless Hooks & Primitives (`img-upload-kit/headless`)**:
-  - Unstyled controllers: `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`) for build-time `blur-hashes.json` generation.
+- **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/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';
+```