@inoo-ch/payload-image-optimizer 1.5.1 → 1.6.1

package/AGENT_DOCS.md

@@ -219,24 +219,24 @@ Get current optimization status for a collection. Requires authentication.
 
 Import from `@inoo-ch/payload-image-optimizer/client`:
 
-### `ImageBox` Component
+### `ImageBox` Component (Recommended)
 
-Drop-in Next.js `<Image>` wrapper with automatic ThumbHash blur placeholders, focal point support, and smooth fade-in transition.
+Drop-in Next.js `<Image>` wrapper — the easiest way to display images with best practices. Automatically handles ThumbHash blur placeholders, focal point positioning, smooth fade-in, responsive variant loading, and smart `sizes` defaults.
 
 ```tsx
 import { ImageBox } from '@inoo-ch/payload-image-optimizer/client'
 
-// With a Payload media resource object
-<ImageBox media={doc.image} alt="Hero" fill sizes="100vw" />
+// Pass the full Payload media document — ImageBox handles everything
+<ImageBox media={doc.heroImage} alt="Hero" fill priority />
 
-// With a plain URL string
-<ImageBox media="/images/fallback.jpg" alt="Fallback" width={800} height={600} />
+// Card grid — explicit sizes hint for responsive loading
+<ImageBox media={doc.image} alt="Card" fill sizes="(max-width: 768px) 100vw, 33vw" />
 
-// Disable fade animation
-<ImageBox media={doc.image} alt="Photo" fade={false} />
+// Fixed dimensions (non-fill)
+<ImageBox media={doc.avatar} alt="Avatar" width={64} height={64} fade={false} />
 
-// Custom fade duration
-<ImageBox media={doc.image} alt="Photo" fadeDuration={300} />
+// Plain URL string fallback
+<ImageBox media="/images/fallback.jpg" alt="Fallback" width={800} height={600} />
 ```
 
 **Props:** Extends all Next.js `ImageProps` (except `src`), plus:
@@ -248,45 +248,92 @@ import { ImageBox } from '@inoo-ch/payload-image-optimizer/client'
 | `fade` | `boolean` | `true` | Enable smooth blur-to-sharp fade transition on load |
 | `fadeDuration` | `number` | `500` | Duration of the fade animation in milliseconds |
 
-Automatically applies:
-- ThumbHash blur placeholder (if available on the media resource)
-- Smooth blur-to-sharp fade transition on image load (disable with `fade={false}`)
-- Focal point positioning via `objectPosition` (using `focalX`/`focalY`)
-- Cache-busting via `updatedAt` query parameter
-- `objectFit: 'cover'` by default (overridable via `style`)
+**What ImageBox does automatically:**
 
-### `FadeImage` Component
+- **ThumbHash blur placeholder** — per-image blur preview from `imageOptimizer.thumbHash`
+- **Responsive variant loader** — when `media.sizes` has Payload size variants (from `imageSizes` collection config), serves pre-generated variants directly instead of going through `/_next/image` re-optimization. Falls back to `/_next/image` when no close match exists.
+- **Smart `sizes` default** — for `fill` mode without explicit `sizes`, uses `(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw` instead of the browser's `100vw` assumption
+- **Focal point positioning** — applies `objectPosition` from `focalX`/`focalY`
+- **Fade transition** — smooth blur-to-sharp animation on load
+- **Cache busting** — appends `updatedAt` as query parameter
 
-Standalone Next.js `<Image>` wrapper with fade-in transition for use with `getImageOptimizerProps()`. Use this when you have a custom image component and want the fade effect without `ImageBox`.
+**Important:** For the variant loader to work, your collection must have `imageSizes` configured in the Payload collection config. This is how Payload generates the width variants. Without `imageSizes`, images still work but go through `/_next/image` as usual.
+
+### `getOptimizedImageProps()` — For Existing Components (e.g., Payload Website Template)
+
+Single-function integration for existing `<NextImage>` components. Returns ThumbHash, focal point, AND variant loader in one spread-friendly object. **This is the recommended way to integrate with the Payload website template's `ImageMedia` component.**
 
 ```tsx
-import { FadeImage, getImageOptimizerProps } from '@inoo-ch/payload-image-optimizer/client'
+import { getOptimizedImageProps } from '@inoo-ch/payload-image-optimizer/client'
 
-const optimizerProps = getImageOptimizerProps(resource)
+// In your existing ImageMedia component — 3 lines to add:
+const optimizedProps = getOptimizedImageProps(resource)
 
-<FadeImage
-  src={resource.url}
-  alt=""
-  width={800}
-  height={600}
-  optimizerProps={optimizerProps}
+<NextImage
+  {...optimizedProps}   // spreads: placeholder, blurDataURL, style, loader
+  src={src}
+  alt={alt}
+  fill={fill}
+  sizes={sizes}
+  quality={80}
+  priority={priority}
+  loading={loading}
 />
 ```
 
-**Props:** Extends all Next.js `ImageProps` (except `placeholder`, `blurDataURL`, `onLoad`), plus:
+**Returns:**
+```ts
+{
+  placeholder: 'blur' | 'empty',
+  blurDataURL?: string,              // data URL from ThumbHash
+  style: { objectPosition: string }, // from focalX/focalY
+  loader?: ImageLoader,              // variant-aware loader (only when media.sizes has variants)
+}
+```
 
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `optimizerProps` | `ImageOptimizerProps` | — | Props returned by `getImageOptimizerProps()` |
-| `fadeDuration` | `number` | `500` | Duration of the fade animation in milliseconds |
+**Payload Website Template integration example:**
+
+If you're using the [Payload website template](https://github.com/payloadcms/payload/tree/main/templates/website), modify `src/components/Media/ImageMedia/index.tsx`:
+
+```diff
++ import { getOptimizedImageProps } from '@inoo-ch/payload-image-optimizer/client'
+
+  export const ImageMedia: React.FC<MediaProps> = (props) => {
+    // ... existing code ...
+
++   const optimizedProps = typeof resource === 'object' ? getOptimizedImageProps(resource) : {}
+
+    return (
+      <picture className={cn(pictureClassName)}>
+        <NextImage
++         {...optimizedProps}
+          alt={alt || ''}
+          className={cn(imgClassName)}
+          fill={fill}
+          height={!fill ? height : undefined}
+-         placeholder="blur"
+-         blurDataURL={placeholderBlur}
+          priority={priority}
+-         quality={100}
++         quality={80}
+          loading={loading}
+          sizes={sizes}
+          src={src}
+          width={!fill ? width : undefined}
+        />
+      </picture>
+    )
+  }
+```
 
-### `getImageOptimizerProps()` Utility
+This replaces the template's hardcoded blur placeholder with per-image ThumbHash, adds focal point support, and enables variant-aware responsive loading — all in a few lines.
 
-For integrating with existing image components (e.g., the Payload website template's `ImageMedia`):
+### `getImageOptimizerProps()` — Low-Level Utility
+
+Returns only ThumbHash placeholder and focal point props (no variant loader). Use when you need granular control or don't want the variant loader.
 
 ```tsx
 import { getImageOptimizerProps } from '@inoo-ch/payload-image-optimizer/client'
-import NextImage from 'next/image'
 
 const optimizerProps = getImageOptimizerProps(media)
 
@@ -301,13 +348,76 @@ const optimizerProps = getImageOptimizerProps(media)
 ```ts
 {
   placeholder: 'blur' | 'empty',
-  blurDataURL?: string,           // data URL from ThumbHash (only when placeholder is 'blur')
-  style: {
-    objectPosition: string,       // e.g. '50% 30%' from focalX/focalY, or 'center'
-  },
+  blurDataURL?: string,
+  style: { objectPosition: string },
 }
 ```
 
+### `createVariantLoader()` — Custom Loader Factory
+
+Creates a Next.js Image `loader` that maps requested widths to pre-generated Payload size variants. Use when building fully custom image components.
+
+```tsx
+import { createVariantLoader } from '@inoo-ch/payload-image-optimizer/client'
+
+const loader = createVariantLoader(media) // returns undefined when no variants
+
+<NextImage loader={loader} src={media.url} sizes="100vw" ... />
+```
+
+**How the hybrid loader works:**
+1. Finds the smallest Payload size variant with width >= requested width
+2. If found → serves the pre-generated variant URL directly (bypasses `/_next/image`)
+3. If no variant is large enough → uses the largest variant if it covers >= 80% of requested width
+4. If no close match at all → falls back to `/_next/image` re-optimization
+
+### `getDefaultSizes()` — Smart Sizes Helper
+
+Returns a sensible default `sizes` attribute for fill-mode images:
+
+```tsx
+import { getDefaultSizes } from '@inoo-ch/payload-image-optimizer/client'
+
+const sizes = getDefaultSizes(true) // '(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw'
+const sizes = getDefaultSizes(false) // undefined (let next/image use 1x/2x descriptors)
+```
+
+### `FadeImage` Component
+
+Standalone Next.js `<Image>` wrapper with fade-in transition for use with `getImageOptimizerProps()`. Use this when you have a custom image component and want the fade effect without `ImageBox`.
+
+```tsx
+import { FadeImage, getImageOptimizerProps } from '@inoo-ch/payload-image-optimizer/client'
+
+const optimizerProps = getImageOptimizerProps(resource)
+
+<FadeImage
+  src={resource.url}
+  alt=""
+  width={800}
+  height={600}
+  optimizerProps={optimizerProps}
+/>
+```
+
+**Props:** Extends all Next.js `ImageProps` (except `placeholder`, `blurDataURL`, `onLoad`), plus:
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `optimizerProps` | `ImageOptimizerProps` | — | Props returned by `getImageOptimizerProps()` |
+| `fadeDuration` | `number` | `500` | Duration of the fade animation in milliseconds |
+
+### Client Utility Decision Guide
+
+| Scenario | Use | Why |
+|----------|-----|-----|
+| **New project, fresh components** | `ImageBox` | Zero-config, handles everything |
+| **Existing project with Payload website template** | `getOptimizedImageProps()` | 3-line change to existing `ImageMedia` |
+| **Custom component, want blur + focal + variants** | `getOptimizedImageProps()` | Single spread, all features |
+| **Custom component, only want blur + focal** | `getImageOptimizerProps()` | Lighter, no loader |
+| **Fully custom loader logic** | `createVariantLoader()` | Granular control |
+| **Custom component with fade animation** | `FadeImage` + `getImageOptimizerProps()` | Fade without ImageBox |
+
 ## Server-Side Utilities
 
 Import from `@inoo-ch/payload-image-optimizer`:
@@ -415,15 +525,46 @@ import type {
   CollectionOptimizerConfig,
   FormatQuality,
   ImageFormat,            // 'webp' | 'avif'
+  MediaResource,          // type for media documents passed to client utilities
+  MediaSizeVariant,       // type for individual size variants in media.sizes
 } from '@inoo-ch/payload-image-optimizer'
 
 import type {
   ImageBoxProps,
   FadeImageProps,
   ImageOptimizerProps,    // return type of getImageOptimizerProps
+  OptimizedImageProps,    // return type of getOptimizedImageProps
 } from '@inoo-ch/payload-image-optimizer/client'
 ```
 
+### `MediaResource` Type
+
+The `MediaResource` type represents a Payload media document as consumed by client utilities. It accepts the full Payload media response including the `sizes` field (generated by Payload when `imageSizes` is configured on the collection).
+
+```ts
+type MediaResource = {
+  url?: string | null
+  alt?: string | null
+  width?: number | null
+  height?: number | null
+  filename?: string | null
+  focalX?: number | null
+  focalY?: number | null
+  imageOptimizer?: { thumbHash?: string | null } | null
+  updatedAt?: string
+  sizes?: Record<string, {
+    url?: string | null
+    width?: number | null
+    height?: number | null
+    mimeType?: string | null
+    filesize?: number | null
+    filename?: string | null
+  } | undefined>
+}
+```
+
+The type is intentionally loose — it structurally matches any Payload media document whether or not the plugin is installed. You can pass your generated Payload types directly without casting.
+
 ## Context Flags
 
 The plugin uses `req.context` flags to control processing:

package/README.md

@@ -17,7 +17,9 @@ Built and maintained by [inoo.ch](https://inoo.ch) — a Swiss digital agency cr
 - **Bulk regeneration** — Re-process existing images from the admin UI with progress tracking
 - **Per-collection config** — Override formats, quality, and dimensions per collection
 - **Admin UI** — Status badges, file size savings, and blur previews in the sidebar
-- **ImageBox component** — Drop-in Next.js `<Image>` wrapper with automatic ThumbHash blur and smooth fade-in
+- **ImageBox component** — Drop-in Next.js `<Image>` wrapper with ThumbHash blur, fade-in, responsive variant loading, and smart `sizes` defaults
+- **Responsive variant loader** — Serves pre-generated Payload size variants directly, bypassing `/_next/image` re-optimization
+- **Template-friendly** — `getOptimizedImageProps()` integrates with the Payload website template in 3 lines
 - **FadeImage component** — Standalone fade-in image for custom setups using `getImageOptimizerProps()`
 
 ## Requirements
@@ -218,32 +220,63 @@ The plugin adds an **Optimization Status** panel to the document sidebar showing
 
 A **Regenerate Images** button appears in collection list views, allowing you to bulk re-process existing images with a real-time progress bar.
 
-## ImageBox Component
+## Displaying Images
 
-The plugin exports an `ImageBox` component — a Next.js `<Image>` wrapper that automatically applies ThumbHash blur placeholders with a smooth blur-to-sharp fade transition:
+### Option 1: `ImageBox` (New Projects)
+
+Drop-in Next.js `<Image>` wrapper — the easiest way to display images with best practices:
 
 ```tsx
 import { ImageBox } from '@inoo-ch/payload-image-optimizer/client'
 
-// Pass a Payload media document directly
-<ImageBox media={doc.heroImage} alt="Hero" />
+// Hero image — fill mode with priority
+<ImageBox media={doc.heroImage} alt="Hero" fill priority />
+
+// Card grid — explicit sizes hint
+<ImageBox media={doc.image} alt="Card" fill sizes="(max-width: 768px) 100vw, 33vw" />
+
+// Fixed dimensions
+<ImageBox media={doc.avatar} alt="Avatar" width={64} height={64} fade={false} />
+```
+
+**What it does automatically:**
+- Per-image ThumbHash blur placeholder
+- Smooth blur-to-sharp fade transition
+- Focal point positioning from `focalX`/`focalY`
+- Responsive variant loader — serves pre-generated Payload size variants directly instead of `/_next/image` re-optimization (when `imageSizes` is configured on the collection)
+- Smart `sizes` default for fill mode — `(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw` instead of the browser's `100vw` assumption
+- Cache busting via `updatedAt`
 
-// Or use a plain URL string
-<ImageBox media="/images/photo.jpg" alt="Photo" width={800} height={600} />
+### Option 2: `getOptimizedImageProps()` (Existing Projects / Payload Website Template)
 
-// Disable fade animation
-<ImageBox media={doc.image} alt="Photo" fade={false} />
+If you're using the [Payload website template](https://github.com/payloadcms/payload/tree/main/templates/website) or have an existing `<NextImage>` component, add 3 lines:
 
-// Custom fade duration (default: 500ms)
-<ImageBox media={doc.image} alt="Photo" fadeDuration={300} />
+```tsx
+import { getOptimizedImageProps } from '@inoo-ch/payload-image-optimizer/client'
+
+const optimizedProps = getOptimizedImageProps(resource)
+
+<NextImage
+  {...optimizedProps}   // ThumbHash blur, focal point, variant loader
+  src={src}
+  alt={alt}
+  fill={fill}
+  sizes={sizes}
+  quality={80}
+/>
 ```
 
-**Features:**
-- Automatic ThumbHash `blurDataURL` from the media document
-- Smooth blur-to-sharp fade transition on load (enabled by default)
-- Respects Payload focal point (`focalX` / `focalY`) for `objectPosition`
-- Lazy loading by default, with `priority` prop for above-the-fold images
-- Cache busting via `updatedAt` timestamp
+This replaces the template's hardcoded blur placeholder with per-image ThumbHash, adds focal point support, and enables responsive variant loading.
+
+### Responsive Variant Loading
+
+When your collection has `imageSizes` configured (e.g., `thumbnail: 300`, `medium: 900`, `large: 1400`), both `ImageBox` and `getOptimizedImageProps()` automatically create a hybrid `next/image` loader that:
+
+1. Picks the smallest pre-generated variant >= the requested width
+2. Serves it directly from your storage (bypasses `/_next/image` — no double optimization)
+3. Falls back to `/_next/image` when no close variant match exists
+
+This means images uploaded to collections with `imageSizes` get responsive loading for free — no extra config needed.
 
 ## Document Schema
 
@@ -310,8 +343,9 @@ Copy-paste this instruction to your AI coding agent to have it autonomously inte
 >
 > 1. Which upload collections should be optimized and with what settings
 > 2. Whether to use `replaceOriginal` or keep originals alongside variants
-> 3. Where to add `<ImageBox>`, `<FadeImage>`, or `getImageOptimizerProps()` in the frontend for ThumbHash blur placeholders with smooth fade-in and focal point support
-> 4. Whether any existing image rendering code should use the optimized variants
+> 3. For **new components**: use `<ImageBox>` — it handles ThumbHash blur, fade-in, focal point, responsive variant loading, and smart `sizes` defaults automatically
+> 4. For **existing components** (especially the Payload website template's `ImageMedia`): use `getOptimizedImageProps(resource)` — a single spread that adds ThumbHash, focal point, and variant loader to any `<NextImage>`
+> 5. If collections have `imageSizes` configured, the variant loader will automatically serve pre-generated size variants directly instead of going through `/_next/image` re-optimization
 >
 > Use the zero-config default (`collections: { <slug>: true }`) unless the project has specific requirements that call for custom settings.
 

package/dist/components/ImageBox.js

@@ -1,8 +1,9 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import React, { useState } from 'react';
+import React, { useMemo, useState } from 'react';
 import NextImage from 'next/image';
 import { getImageOptimizerProps } from '../utilities/getImageOptimizerProps.js';
+import { createVariantLoader, getDefaultSizes } from '../utilities/responsiveImage.js';
 export const ImageBox = ({ media, alt: altFromProps, fill, sizes, priority, loading: loadingFromProps, style: styleFromProps, fade = true, fadeDuration = 500, ...props })=>{
     const [loaded, setLoaded] = useState(false);
     const loading = priority ? undefined : loadingFromProps ?? 'lazy';
@@ -17,7 +18,7 @@ export const ImageBox = ({ media, alt: altFromProps, fill, sizes, priority, load
             alt: altFromProps || '',
             quality: 80,
             fill: fill,
-            sizes: sizes,
+            sizes: sizes ?? getDefaultSizes(fill),
             style: {
                 objectFit: 'cover',
                 objectPosition: 'center',
@@ -34,6 +35,9 @@ export const ImageBox = ({ media, alt: altFromProps, fill, sizes, priority, load
     const alt = altFromProps || media.alt || media.filename || '';
     const src = media.url ? `${media.url}${media.updatedAt ? `?${media.updatedAt}` : ''}` : '';
     const optimizerProps = getImageOptimizerProps(media);
+    const variantLoader = useMemo(()=>createVariantLoader(media), [
+        media
+    ]);
     return /*#__PURE__*/ _jsx(NextImage, {
         ...props,
         src: src,
@@ -42,7 +46,8 @@ export const ImageBox = ({ media, alt: altFromProps, fill, sizes, priority, load
         fill: fill,
         width: !fill ? width : undefined,
         height: !fill ? height : undefined,
-        sizes: sizes,
+        sizes: sizes ?? getDefaultSizes(fill),
+        loader: variantLoader,
         style: {
             objectFit: 'cover',
             ...optimizerProps.style,

package/dist/components/ImageBox.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/components/ImageBox.tsx"],"sourcesContent":["'use client'\n\nimport React, { useState } from 'react'\nimport NextImage, { type ImageProps } from 'next/image'\nimport type { MediaResource } from '../types.js'\nimport { getImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'\n\nexport interface ImageBoxProps extends Omit<ImageProps, 'src' | 'alt'> {\n  media: MediaResource | string\n  alt?: string\n  /** Enable smooth blur-to-sharp fade transition on load. Defaults to `true`. */\n  fade?: boolean\n  /** Duration of the fade animation in milliseconds. Defaults to `500`. */\n  fadeDuration?: number\n}\n\nexport const ImageBox: React.FC<ImageBoxProps> = ({\n  media,\n  alt: altFromProps,\n  fill,\n  sizes,\n  priority,\n  loading: loadingFromProps,\n  style: styleFromProps,\n  fade = true,\n  fadeDuration = 500,\n  ...props\n}) => {\n  const [loaded, setLoaded] = useState(false)\n  const loading = priority ? undefined : (loadingFromProps ?? 'lazy')\n\n  const fadeStyle = fade\n    ? {\n        filter: loaded ? 'blur(0px)' : 'blur(20px)',\n        transition: loaded ? `filter ${fadeDuration}ms ease-in-out` : undefined,\n      }\n    : undefined\n\n  if (typeof media === 'string') {\n    return (\n      <NextImage\n        {...props}\n        src={media}\n        alt={altFromProps || ''}\n        quality={80}\n        fill={fill}\n        sizes={sizes}\n        style={{ objectFit: 'cover', objectPosition: 'center', ...fadeStyle, ...styleFromProps }}\n        priority={priority}\n        loading={loading}\n        onLoad={fade ? () => setLoaded(true) : undefined}\n      />\n    )\n  }\n\n  const width = media.width ?? undefined\n  const height = media.height ?? undefined\n  const alt = altFromProps || (media as any).alt || media.filename || ''\n  const src = media.url ? `${media.url}${media.updatedAt ? `?${media.updatedAt}` : ''}` : ''\n\n  const optimizerProps = getImageOptimizerProps(media)\n\n  return (\n    <NextImage\n      {...props}\n      src={src}\n      alt={alt}\n      quality={80}\n      fill={fill}\n      width={!fill ? width : undefined}\n      height={!fill ? height : undefined}\n      sizes={sizes}\n      style={{ objectFit: 'cover', ...optimizerProps.style, ...fadeStyle, ...styleFromProps }}\n      placeholder={optimizerProps.placeholder}\n      blurDataURL={optimizerProps.blurDataURL}\n      priority={priority}\n      loading={loading}\n      onLoad={fade ? () => setLoaded(true) : undefined}\n    />\n  )\n}\n"],"names":["React","useState","NextImage","getImageOptimizerProps","ImageBox","media","alt","altFromProps","fill","sizes","priority","loading","loadingFromProps","style","styleFromProps","fade","fadeDuration","props","loaded","setLoaded","undefined","fadeStyle","filter","transition","src","quality","objectFit","objectPosition","onLoad","width","height","filename","url","updatedAt","optimizerProps","placeholder","blurDataURL"],"mappings":"AAAA;;AAEA,OAAOA,SAASC,QAAQ,QAAQ,QAAO;AACvC,OAAOC,eAAoC,aAAY;AAEvD,SAASC,sBAAsB,QAAQ,yCAAwC;AAW/E,OAAO,MAAMC,WAAoC,CAAC,EAChDC,KAAK,EACLC,KAAKC,YAAY,EACjBC,IAAI,EACJC,KAAK,EACLC,QAAQ,EACRC,SAASC,gBAAgB,EACzBC,OAAOC,cAAc,EACrBC,OAAO,IAAI,EACXC,eAAe,GAAG,EAClB,GAAGC,OACJ;IACC,MAAM,CAACC,QAAQC,UAAU,GAAGlB,SAAS;IACrC,MAAMU,UAAUD,WAAWU,YAAaR,oBAAoB;IAE5D,MAAMS,YAAYN,OACd;QACEO,QAAQJ,SAAS,cAAc;QAC/BK,YAAYL,SAAS,CAAC,OAAO,EAAEF,aAAa,cAAc,CAAC,GAAGI;IAChE,IACAA;IAEJ,IAAI,OAAOf,UAAU,UAAU;QAC7B,qBACE,KAACH;YACE,GAAGe,KAAK;YACTO,KAAKnB;YACLC,KAAKC,gBAAgB;YACrBkB,SAAS;YACTjB,MAAMA;YACNC,OAAOA;YACPI,OAAO;gBAAEa,WAAW;gBAASC,gBAAgB;gBAAU,GAAGN,SAAS;gBAAE,GAAGP,cAAc;YAAC;YACvFJ,UAAUA;YACVC,SAASA;YACTiB,QAAQb,OAAO,IAAMI,UAAU,QAAQC;;IAG7C;IAEA,MAAMS,QAAQxB,MAAMwB,KAAK,IAAIT;IAC7B,MAAMU,SAASzB,MAAMyB,MAAM,IAAIV;IAC/B,MAAMd,MAAMC,gBAAgB,AAACF,MAAcC,GAAG,IAAID,MAAM0B,QAAQ,IAAI;IACpE,MAAMP,MAAMnB,MAAM2B,GAAG,GAAG,GAAG3B,MAAM2B,GAAG,GAAG3B,MAAM4B,SAAS,GAAG,CAAC,CAAC,EAAE5B,MAAM4B,SAAS,EAAE,GAAG,IAAI,GAAG;IAExF,MAAMC,iBAAiB/B,uBAAuBE;IAE9C,qBACE,KAACH;QACE,GAAGe,KAAK;QACTO,KAAKA;QACLlB,KAAKA;QACLmB,SAAS;QACTjB,MAAMA;QACNqB,OAAO,CAACrB,OAAOqB,QAAQT;QACvBU,QAAQ,CAACtB,OAAOsB,SAASV;QACzBX,OAAOA;QACPI,OAAO;YAAEa,WAAW;YAAS,GAAGQ,eAAerB,KAAK;YAAE,GAAGQ,SAAS;YAAE,GAAGP,cAAc;QAAC;QACtFqB,aAAaD,eAAeC,WAAW;QACvCC,aAAaF,eAAeE,WAAW;QACvC1B,UAAUA;QACVC,SAASA;QACTiB,QAAQb,OAAO,IAAMI,UAAU,QAAQC;;AAG7C,EAAC"}
+{"version":3,"sources":["../../src/components/ImageBox.tsx"],"sourcesContent":["'use client'\n\nimport React, { useMemo, useState } from 'react'\nimport NextImage, { type ImageProps } from 'next/image'\nimport type { MediaResource } from '../types.js'\nimport { getImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'\nimport { createVariantLoader, getDefaultSizes } from '../utilities/responsiveImage.js'\n\nexport interface ImageBoxProps extends Omit<ImageProps, 'src' | 'alt'> {\n  media: MediaResource | string\n  alt?: string\n  /** Enable smooth blur-to-sharp fade transition on load. Defaults to `true`. */\n  fade?: boolean\n  /** Duration of the fade animation in milliseconds. Defaults to `500`. */\n  fadeDuration?: number\n}\n\nexport const ImageBox: React.FC<ImageBoxProps> = ({\n  media,\n  alt: altFromProps,\n  fill,\n  sizes,\n  priority,\n  loading: loadingFromProps,\n  style: styleFromProps,\n  fade = true,\n  fadeDuration = 500,\n  ...props\n}) => {\n  const [loaded, setLoaded] = useState(false)\n  const loading = priority ? undefined : (loadingFromProps ?? 'lazy')\n\n  const fadeStyle = fade\n    ? {\n        filter: loaded ? 'blur(0px)' : 'blur(20px)',\n        transition: loaded ? `filter ${fadeDuration}ms ease-in-out` : undefined,\n      }\n    : undefined\n\n  if (typeof media === 'string') {\n    return (\n      <NextImage\n        {...props}\n        src={media}\n        alt={altFromProps || ''}\n        quality={80}\n        fill={fill}\n        sizes={sizes ?? getDefaultSizes(fill)}\n        style={{ objectFit: 'cover', objectPosition: 'center', ...fadeStyle, ...styleFromProps }}\n        priority={priority}\n        loading={loading}\n        onLoad={fade ? () => setLoaded(true) : undefined}\n      />\n    )\n  }\n\n  const width = media.width ?? undefined\n  const height = media.height ?? undefined\n  const alt = altFromProps || (media as any).alt || media.filename || ''\n  const src = media.url ? `${media.url}${media.updatedAt ? `?${media.updatedAt}` : ''}` : ''\n\n  const optimizerProps = getImageOptimizerProps(media)\n  const variantLoader = useMemo(() => createVariantLoader(media), [media])\n\n  return (\n    <NextImage\n      {...props}\n      src={src}\n      alt={alt}\n      quality={80}\n      fill={fill}\n      width={!fill ? width : undefined}\n      height={!fill ? height : undefined}\n      sizes={sizes ?? getDefaultSizes(fill)}\n      loader={variantLoader}\n      style={{ objectFit: 'cover', ...optimizerProps.style, ...fadeStyle, ...styleFromProps }}\n      placeholder={optimizerProps.placeholder}\n      blurDataURL={optimizerProps.blurDataURL}\n      priority={priority}\n      loading={loading}\n      onLoad={fade ? () => setLoaded(true) : undefined}\n    />\n  )\n}\n"],"names":["React","useMemo","useState","NextImage","getImageOptimizerProps","createVariantLoader","getDefaultSizes","ImageBox","media","alt","altFromProps","fill","sizes","priority","loading","loadingFromProps","style","styleFromProps","fade","fadeDuration","props","loaded","setLoaded","undefined","fadeStyle","filter","transition","src","quality","objectFit","objectPosition","onLoad","width","height","filename","url","updatedAt","optimizerProps","variantLoader","loader","placeholder","blurDataURL"],"mappings":"AAAA;;AAEA,OAAOA,SAASC,OAAO,EAAEC,QAAQ,QAAQ,QAAO;AAChD,OAAOC,eAAoC,aAAY;AAEvD,SAASC,sBAAsB,QAAQ,yCAAwC;AAC/E,SAASC,mBAAmB,EAAEC,eAAe,QAAQ,kCAAiC;AAWtF,OAAO,MAAMC,WAAoC,CAAC,EAChDC,KAAK,EACLC,KAAKC,YAAY,EACjBC,IAAI,EACJC,KAAK,EACLC,QAAQ,EACRC,SAASC,gBAAgB,EACzBC,OAAOC,cAAc,EACrBC,OAAO,IAAI,EACXC,eAAe,GAAG,EAClB,GAAGC,OACJ;IACC,MAAM,CAACC,QAAQC,UAAU,GAAGpB,SAAS;IACrC,MAAMY,UAAUD,WAAWU,YAAaR,oBAAoB;IAE5D,MAAMS,YAAYN,OACd;QACEO,QAAQJ,SAAS,cAAc;QAC/BK,YAAYL,SAAS,CAAC,OAAO,EAAEF,aAAa,cAAc,CAAC,GAAGI;IAChE,IACAA;IAEJ,IAAI,OAAOf,UAAU,UAAU;QAC7B,qBACE,KAACL;YACE,GAAGiB,KAAK;YACTO,KAAKnB;YACLC,KAAKC,gBAAgB;YACrBkB,SAAS;YACTjB,MAAMA;YACNC,OAAOA,SAASN,gBAAgBK;YAChCK,OAAO;gBAAEa,WAAW;gBAASC,gBAAgB;gBAAU,GAAGN,SAAS;gBAAE,GAAGP,cAAc;YAAC;YACvFJ,UAAUA;YACVC,SAASA;YACTiB,QAAQb,OAAO,IAAMI,UAAU,QAAQC;;IAG7C;IAEA,MAAMS,QAAQxB,MAAMwB,KAAK,IAAIT;IAC7B,MAAMU,SAASzB,MAAMyB,MAAM,IAAIV;IAC/B,MAAMd,MAAMC,gBAAgB,AAACF,MAAcC,GAAG,IAAID,MAAM0B,QAAQ,IAAI;IACpE,MAAMP,MAAMnB,MAAM2B,GAAG,GAAG,GAAG3B,MAAM2B,GAAG,GAAG3B,MAAM4B,SAAS,GAAG,CAAC,CAAC,EAAE5B,MAAM4B,SAAS,EAAE,GAAG,IAAI,GAAG;IAExF,MAAMC,iBAAiBjC,uBAAuBI;IAC9C,MAAM8B,gBAAgBrC,QAAQ,IAAMI,oBAAoBG,QAAQ;QAACA;KAAM;IAEvE,qBACE,KAACL;QACE,GAAGiB,KAAK;QACTO,KAAKA;QACLlB,KAAKA;QACLmB,SAAS;QACTjB,MAAMA;QACNqB,OAAO,CAACrB,OAAOqB,QAAQT;QACvBU,QAAQ,CAACtB,OAAOsB,SAASV;QACzBX,OAAOA,SAASN,gBAAgBK;QAChC4B,QAAQD;QACRtB,OAAO;YAAEa,WAAW;YAAS,GAAGQ,eAAerB,KAAK;YAAE,GAAGQ,SAAS;YAAE,GAAGP,cAAc;QAAC;QACtFuB,aAAaH,eAAeG,WAAW;QACvCC,aAAaJ,eAAeI,WAAW;QACvC5B,UAAUA;QACVC,SAASA;QACTiB,QAAQb,OAAO,IAAMI,UAAU,QAAQC;;AAG7C,EAAC"}

package/dist/exports/client.d.ts

@@ -5,5 +5,8 @@ export { FadeImage } from '../components/FadeImage.js';
 export type { FadeImageProps } from '../components/FadeImage.js';
 export { getImageOptimizerProps } from '../utilities/getImageOptimizerProps.js';
 export type { ImageOptimizerProps } from '../utilities/getImageOptimizerProps.js';
+export { getOptimizedImageProps } from '../utilities/getOptimizedImageProps.js';
+export type { OptimizedImageProps } from '../utilities/getOptimizedImageProps.js';
+export { createVariantLoader, getDefaultSizes } from '../utilities/responsiveImage.js';
 export { RegenerationButton } from '../components/RegenerationButton.js';
 export { UploadOptimizer } from '../components/UploadOptimizer.js';

package/dist/exports/client.js

@@ -2,6 +2,8 @@ export { OptimizationStatus } from '../components/OptimizationStatus.js';
 export { ImageBox } from '../components/ImageBox.js';
 export { FadeImage } from '../components/FadeImage.js';
 export { getImageOptimizerProps } from '../utilities/getImageOptimizerProps.js';
+export { getOptimizedImageProps } from '../utilities/getOptimizedImageProps.js';
+export { createVariantLoader, getDefaultSizes } from '../utilities/responsiveImage.js';
 export { RegenerationButton } from '../components/RegenerationButton.js';
 export { UploadOptimizer } from '../components/UploadOptimizer.js';
 

package/dist/exports/client.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/exports/client.ts"],"sourcesContent":["export { OptimizationStatus } from '../components/OptimizationStatus.js'\nexport { ImageBox } from '../components/ImageBox.js'\nexport type { ImageBoxProps } from '../components/ImageBox.js'\nexport { FadeImage } from '../components/FadeImage.js'\nexport type { FadeImageProps } from '../components/FadeImage.js'\nexport { getImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'\nexport type { ImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'\nexport { RegenerationButton } from '../components/RegenerationButton.js'\nexport { UploadOptimizer } from '../components/UploadOptimizer.js'\n"],"names":["OptimizationStatus","ImageBox","FadeImage","getImageOptimizerProps","RegenerationButton","UploadOptimizer"],"mappings":"AAAA,SAASA,kBAAkB,QAAQ,sCAAqC;AACxE,SAASC,QAAQ,QAAQ,4BAA2B;AAEpD,SAASC,SAAS,QAAQ,6BAA4B;AAEtD,SAASC,sBAAsB,QAAQ,yCAAwC;AAE/E,SAASC,kBAAkB,QAAQ,sCAAqC;AACxE,SAASC,eAAe,QAAQ,mCAAkC"}
+{"version":3,"sources":["../../src/exports/client.ts"],"sourcesContent":["export { OptimizationStatus } from '../components/OptimizationStatus.js'\nexport { ImageBox } from '../components/ImageBox.js'\nexport type { ImageBoxProps } from '../components/ImageBox.js'\nexport { FadeImage } from '../components/FadeImage.js'\nexport type { FadeImageProps } from '../components/FadeImage.js'\nexport { getImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'\nexport type { ImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'\nexport { getOptimizedImageProps } from '../utilities/getOptimizedImageProps.js'\nexport type { OptimizedImageProps } from '../utilities/getOptimizedImageProps.js'\nexport { createVariantLoader, getDefaultSizes } from '../utilities/responsiveImage.js'\nexport { RegenerationButton } from '../components/RegenerationButton.js'\nexport { UploadOptimizer } from '../components/UploadOptimizer.js'\n"],"names":["OptimizationStatus","ImageBox","FadeImage","getImageOptimizerProps","getOptimizedImageProps","createVariantLoader","getDefaultSizes","RegenerationButton","UploadOptimizer"],"mappings":"AAAA,SAASA,kBAAkB,QAAQ,sCAAqC;AACxE,SAASC,QAAQ,QAAQ,4BAA2B;AAEpD,SAASC,SAAS,QAAQ,6BAA4B;AAEtD,SAASC,sBAAsB,QAAQ,yCAAwC;AAE/E,SAASC,sBAAsB,QAAQ,yCAAwC;AAE/E,SAASC,mBAAmB,EAAEC,eAAe,QAAQ,kCAAiC;AACtF,SAASC,kBAAkB,QAAQ,sCAAqC;AACxE,SAASC,eAAe,QAAQ,mCAAkC"}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import type { Config } from 'payload';
 import type { ImageOptimizerConfig } from './types.js';
-export type { ImageOptimizerConfig, ImageFormat, FormatQuality, CollectionOptimizerConfig, ImageOptimizerData, MediaResource, FieldsOverride } from './types.js';
+export type { ImageOptimizerConfig, ImageFormat, FormatQuality, CollectionOptimizerConfig, ImageOptimizerData, MediaResource, MediaSizeVariant, FieldsOverride } from './types.js';
 export { defaultImageOptimizerFields } from './fields/imageOptimizerField.js';
 export { encodeImageToThumbHash, decodeThumbHashToDataURL } from './utilities/thumbhash.js';
 /**

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { Config } from 'payload'\nimport { deepMergeSimple } from 'payload/shared'\n\nimport type { ImageOptimizerConfig } from './types.js'\nimport { resolveConfig } from './defaults.js'\nimport { translations } from './translations/index.js'\nimport { getImageOptimizerField } from './fields/imageOptimizerField.js'\nimport { createBeforeChangeHook } from './hooks/beforeChange.js'\nimport { createAfterChangeHook } from './hooks/afterChange.js'\nimport { createConvertFormatsHandler } from './tasks/convertFormats.js'\nimport { createRegenerateDocumentHandler } from './tasks/regenerateDocument.js'\nimport { createRegenerateHandler, createRegenerateStatusHandler } from './endpoints/regenerate.js'\n\nexport type { ImageOptimizerConfig, ImageFormat, FormatQuality, CollectionOptimizerConfig, ImageOptimizerData, MediaResource, FieldsOverride } from './types.js'\nexport { defaultImageOptimizerFields } from './fields/imageOptimizerField.js'\n\nexport { encodeImageToThumbHash, decodeThumbHashToDataURL } from './utilities/thumbhash.js'\n\n/**\n * Recommended maxDuration for the Payload API route on Vercel.\n * Re-export this in your route file:\n *\n *   export { maxDuration } from '@inoo-ch/payload-image-optimizer'\n */\nexport const maxDuration = 60\n\nexport const imageOptimizer =\n  (pluginOptions: ImageOptimizerConfig) =>\n  (config: Config): Config => {\n    const resolvedConfig = resolveConfig(pluginOptions)\n    const targetSlugs = Object.keys(resolvedConfig.collections)\n\n    // Inject fields (and hooks when enabled) into targeted upload collections\n    const collections = (config.collections || []).map((collection) => {\n      if (!targetSlugs.includes(collection.slug)) {\n        return collection\n      }\n\n      // Always inject fields for schema consistency (even when disabled)\n      const fields = [...collection.fields, getImageOptimizerField(pluginOptions.fieldsOverride)]\n\n      if (resolvedConfig.disabled) {\n        return { ...collection, fields }\n      }\n\n      return {\n        ...collection,\n        fields,\n        hooks: {\n          ...collection.hooks,\n          beforeChange: [\n            ...(collection.hooks?.beforeChange || []),\n            createBeforeChangeHook(resolvedConfig, collection.slug),\n          ],\n          afterChange: [\n            ...(collection.hooks?.afterChange || []),\n            createAfterChangeHook(resolvedConfig, collection.slug),\n          ],\n        },\n        admin: {\n          ...collection.admin,\n          components: {\n            ...collection.admin?.components,\n            ...(resolvedConfig.clientOptimization && !collection.admin?.components?.edit?.Upload\n              ? {\n                  edit: {\n                    ...collection.admin?.components?.edit,\n                    Upload: '@inoo-ch/payload-image-optimizer/client#UploadOptimizer',\n                  },\n                }\n              : {}),\n            beforeListTable: [\n              ...(collection.admin?.components?.beforeListTable || []),\n              '@inoo-ch/payload-image-optimizer/client#RegenerationButton',\n            ],\n          },\n        },\n      }\n    })\n\n    const i18n = {\n      ...config.i18n,\n      translations: deepMergeSimple(translations, config.i18n?.translations ?? {}),\n    }\n\n    // If disabled, return with fields injected but no tasks/endpoints\n    if (resolvedConfig.disabled) {\n      return { ...config, collections, i18n }\n    }\n\n    return {\n      ...config,\n      collections,\n      i18n,\n      jobs: {\n        ...config.jobs,\n        tasks: [\n          ...(config.jobs?.tasks || []),\n          {\n            slug: 'imageOptimizer_convertFormats',\n            inputSchema: [\n              { name: 'collectionSlug', type: 'text', required: true },\n              { name: 'docId', type: 'text', required: true },\n            ],\n            outputSchema: [\n              { name: 'variantsGenerated', type: 'number' },\n            ],\n            retries: 2,\n            handler: createConvertFormatsHandler(resolvedConfig),\n          } as any,\n          {\n            slug: 'imageOptimizer_regenerateDocument',\n            inputSchema: [\n              { name: 'collectionSlug', type: 'text', required: true },\n              { name: 'docId', type: 'text', required: true },\n            ],\n            outputSchema: [\n              { name: 'status', type: 'text' },\n              { name: 'reason', type: 'text' },\n            ],\n            retries: 2,\n            handler: createRegenerateDocumentHandler(resolvedConfig),\n          } as any,\n        ],\n      },\n      endpoints: [\n        ...(config.endpoints ?? []),\n        {\n          path: '/image-optimizer/regenerate',\n          method: 'post',\n          handler: createRegenerateHandler(resolvedConfig),\n        },\n        {\n          path: '/image-optimizer/regenerate',\n          method: 'get',\n          handler: createRegenerateStatusHandler(resolvedConfig),\n        },\n      ],\n    }\n  }\n"],"names":["deepMergeSimple","resolveConfig","translations","getImageOptimizerField","createBeforeChangeHook","createAfterChangeHook","createConvertFormatsHandler","createRegenerateDocumentHandler","createRegenerateHandler","createRegenerateStatusHandler","defaultImageOptimizerFields","encodeImageToThumbHash","decodeThumbHashToDataURL","maxDuration","imageOptimizer","pluginOptions","config","resolvedConfig","targetSlugs","Object","keys","collections","map","collection","includes","slug","fields","fieldsOverride","disabled","hooks","beforeChange","afterChange","admin","components","clientOptimization","edit","Upload","beforeListTable","i18n","jobs","tasks","inputSchema","name","type","required","outputSchema","retries","handler","endpoints","path","method"],"mappings":"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"}
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["import type { Config } from 'payload'\nimport { deepMergeSimple } from 'payload/shared'\n\nimport type { ImageOptimizerConfig } from './types.js'\nimport { resolveConfig } from './defaults.js'\nimport { translations } from './translations/index.js'\nimport { getImageOptimizerField } from './fields/imageOptimizerField.js'\nimport { createBeforeChangeHook } from './hooks/beforeChange.js'\nimport { createAfterChangeHook } from './hooks/afterChange.js'\nimport { createConvertFormatsHandler } from './tasks/convertFormats.js'\nimport { createRegenerateDocumentHandler } from './tasks/regenerateDocument.js'\nimport { createRegenerateHandler, createRegenerateStatusHandler } from './endpoints/regenerate.js'\n\nexport type { ImageOptimizerConfig, ImageFormat, FormatQuality, CollectionOptimizerConfig, ImageOptimizerData, MediaResource, MediaSizeVariant, FieldsOverride } from './types.js'\nexport { defaultImageOptimizerFields } from './fields/imageOptimizerField.js'\n\nexport { encodeImageToThumbHash, decodeThumbHashToDataURL } from './utilities/thumbhash.js'\n\n/**\n * Recommended maxDuration for the Payload API route on Vercel.\n * Re-export this in your route file:\n *\n *   export { maxDuration } from '@inoo-ch/payload-image-optimizer'\n */\nexport const maxDuration = 60\n\nexport const imageOptimizer =\n  (pluginOptions: ImageOptimizerConfig) =>\n  (config: Config): Config => {\n    const resolvedConfig = resolveConfig(pluginOptions)\n    const targetSlugs = Object.keys(resolvedConfig.collections)\n\n    // Inject fields (and hooks when enabled) into targeted upload collections\n    const collections = (config.collections || []).map((collection) => {\n      if (!targetSlugs.includes(collection.slug)) {\n        return collection\n      }\n\n      // Always inject fields for schema consistency (even when disabled)\n      const fields = [...collection.fields, getImageOptimizerField(pluginOptions.fieldsOverride)]\n\n      if (resolvedConfig.disabled) {\n        return { ...collection, fields }\n      }\n\n      return {\n        ...collection,\n        fields,\n        hooks: {\n          ...collection.hooks,\n          beforeChange: [\n            ...(collection.hooks?.beforeChange || []),\n            createBeforeChangeHook(resolvedConfig, collection.slug),\n          ],\n          afterChange: [\n            ...(collection.hooks?.afterChange || []),\n            createAfterChangeHook(resolvedConfig, collection.slug),\n          ],\n        },\n        admin: {\n          ...collection.admin,\n          components: {\n            ...collection.admin?.components,\n            ...(resolvedConfig.clientOptimization && !collection.admin?.components?.edit?.Upload\n              ? {\n                  edit: {\n                    ...collection.admin?.components?.edit,\n                    Upload: '@inoo-ch/payload-image-optimizer/client#UploadOptimizer',\n                  },\n                }\n              : {}),\n            beforeListTable: [\n              ...(collection.admin?.components?.beforeListTable || []),\n              '@inoo-ch/payload-image-optimizer/client#RegenerationButton',\n            ],\n          },\n        },\n      }\n    })\n\n    const i18n = {\n      ...config.i18n,\n      translations: deepMergeSimple(translations, config.i18n?.translations ?? {}),\n    }\n\n    // If disabled, return with fields injected but no tasks/endpoints\n    if (resolvedConfig.disabled) {\n      return { ...config, collections, i18n }\n    }\n\n    return {\n      ...config,\n      collections,\n      i18n,\n      jobs: {\n        ...config.jobs,\n        tasks: [\n          ...(config.jobs?.tasks || []),\n          {\n            slug: 'imageOptimizer_convertFormats',\n            inputSchema: [\n              { name: 'collectionSlug', type: 'text', required: true },\n              { name: 'docId', type: 'text', required: true },\n            ],\n            outputSchema: [\n              { name: 'variantsGenerated', type: 'number' },\n            ],\n            retries: 2,\n            handler: createConvertFormatsHandler(resolvedConfig),\n          } as any,\n          {\n            slug: 'imageOptimizer_regenerateDocument',\n            inputSchema: [\n              { name: 'collectionSlug', type: 'text', required: true },\n              { name: 'docId', type: 'text', required: true },\n            ],\n            outputSchema: [\n              { name: 'status', type: 'text' },\n              { name: 'reason', type: 'text' },\n            ],\n            retries: 2,\n            handler: createRegenerateDocumentHandler(resolvedConfig),\n          } as any,\n        ],\n      },\n      endpoints: [\n        ...(config.endpoints ?? []),\n        {\n          path: '/image-optimizer/regenerate',\n          method: 'post',\n          handler: createRegenerateHandler(resolvedConfig),\n        },\n        {\n          path: '/image-optimizer/regenerate',\n          method: 'get',\n          handler: createRegenerateStatusHandler(resolvedConfig),\n        },\n      ],\n    }\n  }\n"],"names":["deepMergeSimple","resolveConfig","translations","getImageOptimizerField","createBeforeChangeHook","createAfterChangeHook","createConvertFormatsHandler","createRegenerateDocumentHandler","createRegenerateHandler","createRegenerateStatusHandler","defaultImageOptimizerFields","encodeImageToThumbHash","decodeThumbHashToDataURL","maxDuration","imageOptimizer","pluginOptions","config","resolvedConfig","targetSlugs","Object","keys","collections","map","collection","includes","slug","fields","fieldsOverride","disabled","hooks","beforeChange","afterChange","admin","components","clientOptimization","edit","Upload","beforeListTable","i18n","jobs","tasks","inputSchema","name","type","required","outputSchema","retries","handler","endpoints","path","method"],"mappings":"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"}

package/dist/types.d.ts

@@ -46,6 +46,14 @@ export type ResolvedImageOptimizerConfig = Required<Pick<ImageOptimizerConfig, '
 export type ImageOptimizerData = {
     thumbHash?: string | null;
 };
+export type MediaSizeVariant = {
+    url?: string | null;
+    width?: number | null;
+    height?: number | null;
+    mimeType?: string | null;
+    filesize?: number | null;
+    filename?: string | null;
+};
 export type MediaResource = {
     url?: string | null;
     alt?: string | null;
@@ -56,4 +64,5 @@ export type MediaResource = {
     focalY?: number | null;
     imageOptimizer?: ImageOptimizerData | null;
     updatedAt?: string;
+    sizes?: Record<string, MediaSizeVariant | undefined>;
 };

package/dist/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/types.ts"],"sourcesContent":["import type { CollectionSlug, Field } from 'payload'\n\nexport type ImageFormat = 'webp' | 'avif'\n\nexport type FormatQuality = {\n  format: ImageFormat\n  quality: number // 1-100\n}\n\nexport type CollectionOptimizerConfig = {\n  formats?: FormatQuality[]\n  maxDimensions?: { width: number; height: number }\n  replaceOriginal?: boolean\n}\n\nexport type FieldsOverride = (args: { defaultFields: Field[] }) => Field[]\n\nexport type ImageOptimizerConfig = {\n  clientOptimization?: boolean\n  collections: Partial<Record<CollectionSlug, true | CollectionOptimizerConfig>>\n  disabled?: boolean\n  fieldsOverride?: FieldsOverride\n  formats?: FormatQuality[]\n  generateThumbHash?: boolean\n  maxDimensions?: { width: number; height: number }\n  replaceOriginal?: boolean\n  stripMetadata?: boolean\n}\n\nexport type ResolvedCollectionOptimizerConfig = {\n  formats: FormatQuality[]\n  maxDimensions: { width: number; height: number }\n  replaceOriginal: boolean\n}\n\nexport type ResolvedImageOptimizerConfig = Required<\n  Pick<ImageOptimizerConfig, 'formats' | 'generateThumbHash' | 'maxDimensions' | 'stripMetadata'>\n> & {\n  clientOptimization: boolean\n  collections: ImageOptimizerConfig['collections']\n  disabled: boolean\n  replaceOriginal: boolean\n}\n\nexport type ImageOptimizerData = {\n  thumbHash?: string | null\n}\n\nexport type MediaResource = {\n  url?: string | null\n  alt?: string | null\n  width?: number | null\n  height?: number | null\n  filename?: string | null\n  focalX?: number | null\n  focalY?: number | null\n  imageOptimizer?: ImageOptimizerData | null\n  updatedAt?: string\n}\n"],"names":[],"mappings":"AAgDA,WAUC"}
+{"version":3,"sources":["../src/types.ts"],"sourcesContent":["import type { CollectionSlug, Field } from 'payload'\n\nexport type ImageFormat = 'webp' | 'avif'\n\nexport type FormatQuality = {\n  format: ImageFormat\n  quality: number // 1-100\n}\n\nexport type CollectionOptimizerConfig = {\n  formats?: FormatQuality[]\n  maxDimensions?: { width: number; height: number }\n  replaceOriginal?: boolean\n}\n\nexport type FieldsOverride = (args: { defaultFields: Field[] }) => Field[]\n\nexport type ImageOptimizerConfig = {\n  clientOptimization?: boolean\n  collections: Partial<Record<CollectionSlug, true | CollectionOptimizerConfig>>\n  disabled?: boolean\n  fieldsOverride?: FieldsOverride\n  formats?: FormatQuality[]\n  generateThumbHash?: boolean\n  maxDimensions?: { width: number; height: number }\n  replaceOriginal?: boolean\n  stripMetadata?: boolean\n}\n\nexport type ResolvedCollectionOptimizerConfig = {\n  formats: FormatQuality[]\n  maxDimensions: { width: number; height: number }\n  replaceOriginal: boolean\n}\n\nexport type ResolvedImageOptimizerConfig = Required<\n  Pick<ImageOptimizerConfig, 'formats' | 'generateThumbHash' | 'maxDimensions' | 'stripMetadata'>\n> & {\n  clientOptimization: boolean\n  collections: ImageOptimizerConfig['collections']\n  disabled: boolean\n  replaceOriginal: boolean\n}\n\nexport type ImageOptimizerData = {\n  thumbHash?: string | null\n}\n\nexport type MediaSizeVariant = {\n  url?: string | null\n  width?: number | null\n  height?: number | null\n  mimeType?: string | null\n  filesize?: number | null\n  filename?: string | null\n}\n\nexport type MediaResource = {\n  url?: string | null\n  alt?: string | null\n  width?: number | null\n  height?: number | null\n  filename?: string | null\n  focalX?: number | null\n  focalY?: number | null\n  imageOptimizer?: ImageOptimizerData | null\n  updatedAt?: string\n  sizes?: Record<string, MediaSizeVariant | undefined>\n}\n"],"names":[],"mappings":"AAyDA,WAWC"}

package/dist/utilities/getOptimizedImageProps.d.ts

@@ -0,0 +1,44 @@
+import type { MediaResource } from '../types.js';
+import { type ImageOptimizerProps } from './getImageOptimizerProps.js';
+type ImageLoaderProps = {
+    src: string;
+    width: number;
+    quality?: number | undefined;
+};
+type ImageLoader = (props: ImageLoaderProps) => string;
+export type OptimizedImageProps = ImageOptimizerProps & {
+    loader?: ImageLoader;
+};
+/**
+ * Returns all optimization props for a Next.js `<Image>` component in a single
+ * spread-friendly object: ThumbHash blur placeholder, focal-point positioning,
+ * and a variant-aware responsive loader.
+ *
+ * Designed as a drop-in enhancement for the Payload website template's `ImageMedia`:
+ *
+ * ```tsx
+ * // In your ImageMedia component — just add the import and spread:
+ * import { getOptimizedImageProps } from '@inoo-ch/payload-image-optimizer/client'
+ *
+ * const optimizedProps = getOptimizedImageProps(resource)
+ *
+ * <NextImage
+ *   {...optimizedProps}
+ *   src={src}
+ *   alt={alt}
+ *   fill={fill}
+ *   sizes={sizes}
+ *   priority={priority}
+ *   loading={loading}
+ * />
+ * ```
+ *
+ * What it returns:
+ * - `placeholder` / `blurDataURL` — per-image ThumbHash (replaces the template's hardcoded blur)
+ * - `style.objectPosition` — focal-point-based positioning
+ * - `loader` — hybrid loader that serves pre-generated Payload size variants directly,
+ *   falling back to `/_next/image` when no close match exists (only present when
+ *   `resource.sizes` has variants)
+ */
+export declare function getOptimizedImageProps(resource: MediaResource | null | undefined): OptimizedImageProps;
+export {};

package/dist/utilities/getOptimizedImageProps.js

@@ -0,0 +1,43 @@
+import { getImageOptimizerProps } from './getImageOptimizerProps.js';
+import { createVariantLoader } from './responsiveImage.js';
+/**
+ * Returns all optimization props for a Next.js `<Image>` component in a single
+ * spread-friendly object: ThumbHash blur placeholder, focal-point positioning,
+ * and a variant-aware responsive loader.
+ *
+ * Designed as a drop-in enhancement for the Payload website template's `ImageMedia`:
+ *
+ * ```tsx
+ * // In your ImageMedia component — just add the import and spread:
+ * import { getOptimizedImageProps } from '@inoo-ch/payload-image-optimizer/client'
+ *
+ * const optimizedProps = getOptimizedImageProps(resource)
+ *
+ * <NextImage
+ *   {...optimizedProps}
+ *   src={src}
+ *   alt={alt}
+ *   fill={fill}
+ *   sizes={sizes}
+ *   priority={priority}
+ *   loading={loading}
+ * />
+ * ```
+ *
+ * What it returns:
+ * - `placeholder` / `blurDataURL` — per-image ThumbHash (replaces the template's hardcoded blur)
+ * - `style.objectPosition` — focal-point-based positioning
+ * - `loader` — hybrid loader that serves pre-generated Payload size variants directly,
+ *   falling back to `/_next/image` when no close match exists (only present when
+ *   `resource.sizes` has variants)
+ */ export function getOptimizedImageProps(resource) {
+    const base = getImageOptimizerProps(resource);
+    if (!resource) return base;
+    const loader = createVariantLoader(resource);
+    return loader ? {
+        ...base,
+        loader
+    } : base;
+}
+
+//# sourceMappingURL=getOptimizedImageProps.js.map

package/dist/utilities/getOptimizedImageProps.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utilities/getOptimizedImageProps.ts"],"sourcesContent":["import type { MediaResource } from '../types.js'\nimport { getImageOptimizerProps, type ImageOptimizerProps } from './getImageOptimizerProps.js'\nimport { createVariantLoader } from './responsiveImage.js'\n\ntype ImageLoaderProps = { src: string; width: number; quality?: number | undefined }\ntype ImageLoader = (props: ImageLoaderProps) => string\n\nexport type OptimizedImageProps = ImageOptimizerProps & {\n  loader?: ImageLoader\n}\n\n/**\n * Returns all optimization props for a Next.js `<Image>` component in a single\n * spread-friendly object: ThumbHash blur placeholder, focal-point positioning,\n * and a variant-aware responsive loader.\n *\n * Designed as a drop-in enhancement for the Payload website template's `ImageMedia`:\n *\n * ```tsx\n * // In your ImageMedia component — just add the import and spread:\n * import { getOptimizedImageProps } from '@inoo-ch/payload-image-optimizer/client'\n *\n * const optimizedProps = getOptimizedImageProps(resource)\n *\n * <NextImage\n *   {...optimizedProps}\n *   src={src}\n *   alt={alt}\n *   fill={fill}\n *   sizes={sizes}\n *   priority={priority}\n *   loading={loading}\n * />\n * ```\n *\n * What it returns:\n * - `placeholder` / `blurDataURL` — per-image ThumbHash (replaces the template's hardcoded blur)\n * - `style.objectPosition` — focal-point-based positioning\n * - `loader` — hybrid loader that serves pre-generated Payload size variants directly,\n *   falling back to `/_next/image` when no close match exists (only present when\n *   `resource.sizes` has variants)\n */\nexport function getOptimizedImageProps(\n  resource: MediaResource | null | undefined,\n): OptimizedImageProps {\n  const base = getImageOptimizerProps(resource)\n\n  if (!resource) return base\n\n  const loader = createVariantLoader(resource)\n\n  return loader ? { ...base, loader } : base\n}\n"],"names":["getImageOptimizerProps","createVariantLoader","getOptimizedImageProps","resource","base","loader"],"mappings":"AACA,SAASA,sBAAsB,QAAkC,8BAA6B;AAC9F,SAASC,mBAAmB,QAAQ,uBAAsB;AAS1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8BC,GACD,OAAO,SAASC,uBACdC,QAA0C;IAE1C,MAAMC,OAAOJ,uBAAuBG;IAEpC,IAAI,CAACA,UAAU,OAAOC;IAEtB,MAAMC,SAASJ,oBAAoBE;IAEnC,OAAOE,SAAS;QAAE,GAAGD,IAAI;QAAEC;IAAO,IAAID;AACxC"}

package/dist/utilities/responsiveImage.d.ts

@@ -0,0 +1,46 @@
+import type { MediaResource } from '../types.js';
+type ImageLoaderProps = {
+    src: string;
+    width: number;
+    quality?: number | undefined;
+};
+type ImageLoader = (props: ImageLoaderProps) => string;
+type ValidVariant = {
+    url: string;
+    width: number;
+};
+/**
+ * Finds the best pre-generated variant for a requested width.
+ *
+ * Strategy:
+ * 1. Pick the smallest variant with width >= requested (no quality loss from upscaling)
+ * 2. If none is large enough, use the largest variant — but only if it covers >= 80%
+ *    of the requested width (minor downscale is acceptable, large gap is not)
+ * 3. Returns null when no suitable variant exists → caller should fall back to /_next/image
+ */
+export declare function findBestVariant(variants: ValidVariant[], requestedWidth: number): ValidVariant | null;
+/**
+ * Creates a Next.js Image `loader` that maps requested widths to pre-generated
+ * Payload size variants when a close match exists, falling back to the default
+ * `/_next/image` optimization pipeline when no suitable variant is available.
+ *
+ * Returns `undefined` when the media has no usable size variants (i.e. no custom
+ * loader needed — let next/image use its default behavior).
+ *
+ * ```tsx
+ * import { createVariantLoader } from '@inoo-ch/payload-image-optimizer/client'
+ *
+ * const loader = createVariantLoader(media)
+ * <NextImage loader={loader} src={media.url} ... />
+ * ```
+ */
+export declare function createVariantLoader(media: MediaResource): ImageLoader | undefined;
+/**
+ * Returns a sensible default `sizes` attribute for responsive images.
+ *
+ * For `fill` mode images without an explicit `sizes` prop, this prevents the
+ * browser from assuming `100vw` (which causes it to always download the
+ * largest srcSet variant regardless of actual display area).
+ */
+export declare function getDefaultSizes(fill: boolean | undefined): string | undefined;
+export {};

package/dist/utilities/responsiveImage.js

@@ -0,0 +1,64 @@
+/**
+ * Extracts usable variants from a Payload media resource's `sizes` field.
+ * Filters out entries missing url or width and sorts by width ascending.
+ */ function getValidVariants(media) {
+    if (!media.sizes) return [];
+    return Object.values(media.sizes).filter((v)=>v != null && typeof v.url === 'string' && typeof v.width === 'number').sort((a, b)=>a.width - b.width);
+}
+/**
+ * Finds the best pre-generated variant for a requested width.
+ *
+ * Strategy:
+ * 1. Pick the smallest variant with width >= requested (no quality loss from upscaling)
+ * 2. If none is large enough, use the largest variant — but only if it covers >= 80%
+ *    of the requested width (minor downscale is acceptable, large gap is not)
+ * 3. Returns null when no suitable variant exists → caller should fall back to /_next/image
+ */ export function findBestVariant(variants, requestedWidth) {
+    if (variants.length === 0) return null;
+    // Smallest variant >= requested width
+    const larger = variants.find((v)=>v.width >= requestedWidth);
+    if (larger) return larger;
+    // No variant large enough — use the largest if it's close
+    const largest = variants[variants.length - 1];
+    if (largest.width >= requestedWidth * 0.8) return largest;
+    return null;
+}
+/**
+ * Creates a Next.js Image `loader` that maps requested widths to pre-generated
+ * Payload size variants when a close match exists, falling back to the default
+ * `/_next/image` optimization pipeline when no suitable variant is available.
+ *
+ * Returns `undefined` when the media has no usable size variants (i.e. no custom
+ * loader needed — let next/image use its default behavior).
+ *
+ * ```tsx
+ * import { createVariantLoader } from '@inoo-ch/payload-image-optimizer/client'
+ *
+ * const loader = createVariantLoader(media)
+ * <NextImage loader={loader} src={media.url} ... />
+ * ```
+ */ export function createVariantLoader(media) {
+    const variants = getValidVariants(media);
+    if (variants.length === 0) return undefined;
+    const cacheBust = media.updatedAt ? `?${media.updatedAt}` : '';
+    return ({ src, width, quality })=>{
+        const match = findBestVariant(variants, width);
+        if (match) {
+            return `${match.url}${cacheBust}`;
+        }
+        // Fall back to next/image optimization for unmatched widths
+        return `/_next/image?url=${encodeURIComponent(src)}&w=${width}&q=${quality || 80}`;
+    };
+}
+/**
+ * Returns a sensible default `sizes` attribute for responsive images.
+ *
+ * For `fill` mode images without an explicit `sizes` prop, this prevents the
+ * browser from assuming `100vw` (which causes it to always download the
+ * largest srcSet variant regardless of actual display area).
+ */ export function getDefaultSizes(fill) {
+    if (!fill) return undefined;
+    return '(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw';
+}
+
+//# sourceMappingURL=responsiveImage.js.map

package/dist/utilities/responsiveImage.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/utilities/responsiveImage.ts"],"sourcesContent":["import type { MediaResource, MediaSizeVariant } from '../types.js'\n\ntype ImageLoaderProps = { src: string; width: number; quality?: number | undefined }\ntype ImageLoader = (props: ImageLoaderProps) => string\n\ntype ValidVariant = { url: string; width: number }\n\n/**\n * Extracts usable variants from a Payload media resource's `sizes` field.\n * Filters out entries missing url or width and sorts by width ascending.\n */\nfunction getValidVariants(media: MediaResource): ValidVariant[] {\n  if (!media.sizes) return []\n\n  return Object.values(media.sizes)\n    .filter((v): v is MediaSizeVariant & { url: string; width: number } =>\n      v != null && typeof v.url === 'string' && typeof v.width === 'number',\n    )\n    .sort((a, b) => a.width - b.width)\n}\n\n/**\n * Finds the best pre-generated variant for a requested width.\n *\n * Strategy:\n * 1. Pick the smallest variant with width >= requested (no quality loss from upscaling)\n * 2. If none is large enough, use the largest variant — but only if it covers >= 80%\n *    of the requested width (minor downscale is acceptable, large gap is not)\n * 3. Returns null when no suitable variant exists → caller should fall back to /_next/image\n */\nexport function findBestVariant(\n  variants: ValidVariant[],\n  requestedWidth: number,\n): ValidVariant | null {\n  if (variants.length === 0) return null\n\n  // Smallest variant >= requested width\n  const larger = variants.find((v) => v.width >= requestedWidth)\n  if (larger) return larger\n\n  // No variant large enough — use the largest if it's close\n  const largest = variants[variants.length - 1]!\n  if (largest.width >= requestedWidth * 0.8) return largest\n\n  return null\n}\n\n/**\n * Creates a Next.js Image `loader` that maps requested widths to pre-generated\n * Payload size variants when a close match exists, falling back to the default\n * `/_next/image` optimization pipeline when no suitable variant is available.\n *\n * Returns `undefined` when the media has no usable size variants (i.e. no custom\n * loader needed — let next/image use its default behavior).\n *\n * ```tsx\n * import { createVariantLoader } from '@inoo-ch/payload-image-optimizer/client'\n *\n * const loader = createVariantLoader(media)\n * <NextImage loader={loader} src={media.url} ... />\n * ```\n */\nexport function createVariantLoader(media: MediaResource): ImageLoader | undefined {\n  const variants = getValidVariants(media)\n  if (variants.length === 0) return undefined\n\n  const cacheBust = media.updatedAt ? `?${media.updatedAt}` : ''\n\n  return ({ src, width, quality }) => {\n    const match = findBestVariant(variants, width)\n\n    if (match) {\n      return `${match.url}${cacheBust}`\n    }\n\n    // Fall back to next/image optimization for unmatched widths\n    return `/_next/image?url=${encodeURIComponent(src)}&w=${width}&q=${quality || 80}`\n  }\n}\n\n/**\n * Returns a sensible default `sizes` attribute for responsive images.\n *\n * For `fill` mode images without an explicit `sizes` prop, this prevents the\n * browser from assuming `100vw` (which causes it to always download the\n * largest srcSet variant regardless of actual display area).\n */\nexport function getDefaultSizes(fill: boolean | undefined): string | undefined {\n  if (!fill) return undefined\n  return '(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw'\n}\n"],"names":["getValidVariants","media","sizes","Object","values","filter","v","url","width","sort","a","b","findBestVariant","variants","requestedWidth","length","larger","find","largest","createVariantLoader","undefined","cacheBust","updatedAt","src","quality","match","encodeURIComponent","getDefaultSizes","fill"],"mappings":"AAOA;;;CAGC,GACD,SAASA,iBAAiBC,KAAoB;IAC5C,IAAI,CAACA,MAAMC,KAAK,EAAE,OAAO,EAAE;IAE3B,OAAOC,OAAOC,MAAM,CAACH,MAAMC,KAAK,EAC7BG,MAAM,CAAC,CAACC,IACPA,KAAK,QAAQ,OAAOA,EAAEC,GAAG,KAAK,YAAY,OAAOD,EAAEE,KAAK,KAAK,UAE9DC,IAAI,CAAC,CAACC,GAAGC,IAAMD,EAAEF,KAAK,GAAGG,EAAEH,KAAK;AACrC;AAEA;;;;;;;;CAQC,GACD,OAAO,SAASI,gBACdC,QAAwB,EACxBC,cAAsB;IAEtB,IAAID,SAASE,MAAM,KAAK,GAAG,OAAO;IAElC,sCAAsC;IACtC,MAAMC,SAASH,SAASI,IAAI,CAAC,CAACX,IAAMA,EAAEE,KAAK,IAAIM;IAC/C,IAAIE,QAAQ,OAAOA;IAEnB,0DAA0D;IAC1D,MAAME,UAAUL,QAAQ,CAACA,SAASE,MAAM,GAAG,EAAE;IAC7C,IAAIG,QAAQV,KAAK,IAAIM,iBAAiB,KAAK,OAAOI;IAElD,OAAO;AACT;AAEA;;;;;;;;;;;;;;CAcC,GACD,OAAO,SAASC,oBAAoBlB,KAAoB;IACtD,MAAMY,WAAWb,iBAAiBC;IAClC,IAAIY,SAASE,MAAM,KAAK,GAAG,OAAOK;IAElC,MAAMC,YAAYpB,MAAMqB,SAAS,GAAG,CAAC,CAAC,EAAErB,MAAMqB,SAAS,EAAE,GAAG;IAE5D,OAAO,CAAC,EAAEC,GAAG,EAAEf,KAAK,EAAEgB,OAAO,EAAE;QAC7B,MAAMC,QAAQb,gBAAgBC,UAAUL;QAExC,IAAIiB,OAAO;YACT,OAAO,GAAGA,MAAMlB,GAAG,GAAGc,WAAW;QACnC;QAEA,4DAA4D;QAC5D,OAAO,CAAC,iBAAiB,EAAEK,mBAAmBH,KAAK,GAAG,EAAEf,MAAM,GAAG,EAAEgB,WAAW,IAAI;IACpF;AACF;AAEA;;;;;;CAMC,GACD,OAAO,SAASG,gBAAgBC,IAAyB;IACvD,IAAI,CAACA,MAAM,OAAOR;IAClB,OAAO;AACT"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inoo-ch/payload-image-optimizer",
-  "version": "1.5.1",
+  "version": "1.6.1",
   "description": "Payload CMS plugin for automatic image optimization — WebP/AVIF conversion, resize, EXIF strip, ThumbHash placeholders, and bulk regeneration",
   "license": "MIT",
   "keywords": [

package/src/components/ImageBox.tsx

@@ -1,9 +1,10 @@
 'use client'
 
-import React, { useState } from 'react'
+import React, { useMemo, useState } from 'react'
 import NextImage, { type ImageProps } from 'next/image'
 import type { MediaResource } from '../types.js'
 import { getImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'
+import { createVariantLoader, getDefaultSizes } from '../utilities/responsiveImage.js'
 
 export interface ImageBoxProps extends Omit<ImageProps, 'src' | 'alt'> {
   media: MediaResource | string
@@ -44,7 +45,7 @@ export const ImageBox: React.FC<ImageBoxProps> = ({
         alt={altFromProps || ''}
         quality={80}
         fill={fill}
-        sizes={sizes}
+        sizes={sizes ?? getDefaultSizes(fill)}
         style={{ objectFit: 'cover', objectPosition: 'center', ...fadeStyle, ...styleFromProps }}
         priority={priority}
         loading={loading}
@@ -59,6 +60,7 @@ export const ImageBox: React.FC<ImageBoxProps> = ({
   const src = media.url ? `${media.url}${media.updatedAt ? `?${media.updatedAt}` : ''}` : ''
 
   const optimizerProps = getImageOptimizerProps(media)
+  const variantLoader = useMemo(() => createVariantLoader(media), [media])
 
   return (
     <NextImage
@@ -69,7 +71,8 @@ export const ImageBox: React.FC<ImageBoxProps> = ({
       fill={fill}
       width={!fill ? width : undefined}
       height={!fill ? height : undefined}
-      sizes={sizes}
+      sizes={sizes ?? getDefaultSizes(fill)}
+      loader={variantLoader}
       style={{ objectFit: 'cover', ...optimizerProps.style, ...fadeStyle, ...styleFromProps }}
       placeholder={optimizerProps.placeholder}
       blurDataURL={optimizerProps.blurDataURL}

package/src/exports/client.ts

@@ -5,5 +5,8 @@ export { FadeImage } from '../components/FadeImage.js'
 export type { FadeImageProps } from '../components/FadeImage.js'
 export { getImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'
 export type { ImageOptimizerProps } from '../utilities/getImageOptimizerProps.js'
+export { getOptimizedImageProps } from '../utilities/getOptimizedImageProps.js'
+export type { OptimizedImageProps } from '../utilities/getOptimizedImageProps.js'
+export { createVariantLoader, getDefaultSizes } from '../utilities/responsiveImage.js'
 export { RegenerationButton } from '../components/RegenerationButton.js'
 export { UploadOptimizer } from '../components/UploadOptimizer.js'

package/src/index.ts

@@ -11,7 +11,7 @@ import { createConvertFormatsHandler } from './tasks/convertFormats.js'
 import { createRegenerateDocumentHandler } from './tasks/regenerateDocument.js'
 import { createRegenerateHandler, createRegenerateStatusHandler } from './endpoints/regenerate.js'
 
-export type { ImageOptimizerConfig, ImageFormat, FormatQuality, CollectionOptimizerConfig, ImageOptimizerData, MediaResource, FieldsOverride } from './types.js'
+export type { ImageOptimizerConfig, ImageFormat, FormatQuality, CollectionOptimizerConfig, ImageOptimizerData, MediaResource, MediaSizeVariant, FieldsOverride } from './types.js'
 export { defaultImageOptimizerFields } from './fields/imageOptimizerField.js'
 
 export { encodeImageToThumbHash, decodeThumbHashToDataURL } from './utilities/thumbhash.js'

package/src/types.ts

@@ -46,6 +46,15 @@ export type ImageOptimizerData = {
   thumbHash?: string | null
 }
 
+export type MediaSizeVariant = {
+  url?: string | null
+  width?: number | null
+  height?: number | null
+  mimeType?: string | null
+  filesize?: number | null
+  filename?: string | null
+}
+
 export type MediaResource = {
   url?: string | null
   alt?: string | null
@@ -56,4 +65,5 @@ export type MediaResource = {
   focalY?: number | null
   imageOptimizer?: ImageOptimizerData | null
   updatedAt?: string
+  sizes?: Record<string, MediaSizeVariant | undefined>
 }

package/src/utilities/getOptimizedImageProps.ts

@@ -0,0 +1,53 @@
+import type { MediaResource } from '../types.js'
+import { getImageOptimizerProps, type ImageOptimizerProps } from './getImageOptimizerProps.js'
+import { createVariantLoader } from './responsiveImage.js'
+
+type ImageLoaderProps = { src: string; width: number; quality?: number | undefined }
+type ImageLoader = (props: ImageLoaderProps) => string
+
+export type OptimizedImageProps = ImageOptimizerProps & {
+  loader?: ImageLoader
+}
+
+/**
+ * Returns all optimization props for a Next.js `<Image>` component in a single
+ * spread-friendly object: ThumbHash blur placeholder, focal-point positioning,
+ * and a variant-aware responsive loader.
+ *
+ * Designed as a drop-in enhancement for the Payload website template's `ImageMedia`:
+ *
+ * ```tsx
+ * // In your ImageMedia component — just add the import and spread:
+ * import { getOptimizedImageProps } from '@inoo-ch/payload-image-optimizer/client'
+ *
+ * const optimizedProps = getOptimizedImageProps(resource)
+ *
+ * <NextImage
+ *   {...optimizedProps}
+ *   src={src}
+ *   alt={alt}
+ *   fill={fill}
+ *   sizes={sizes}
+ *   priority={priority}
+ *   loading={loading}
+ * />
+ * ```
+ *
+ * What it returns:
+ * - `placeholder` / `blurDataURL` — per-image ThumbHash (replaces the template's hardcoded blur)
+ * - `style.objectPosition` — focal-point-based positioning
+ * - `loader` — hybrid loader that serves pre-generated Payload size variants directly,
+ *   falling back to `/_next/image` when no close match exists (only present when
+ *   `resource.sizes` has variants)
+ */
+export function getOptimizedImageProps(
+  resource: MediaResource | null | undefined,
+): OptimizedImageProps {
+  const base = getImageOptimizerProps(resource)
+
+  if (!resource) return base
+
+  const loader = createVariantLoader(resource)
+
+  return loader ? { ...base, loader } : base
+}

package/src/utilities/responsiveImage.ts

@@ -0,0 +1,91 @@
+import type { MediaResource, MediaSizeVariant } from '../types.js'
+
+type ImageLoaderProps = { src: string; width: number; quality?: number | undefined }
+type ImageLoader = (props: ImageLoaderProps) => string
+
+type ValidVariant = { url: string; width: number }
+
+/**
+ * Extracts usable variants from a Payload media resource's `sizes` field.
+ * Filters out entries missing url or width and sorts by width ascending.
+ */
+function getValidVariants(media: MediaResource): ValidVariant[] {
+  if (!media.sizes) return []
+
+  return Object.values(media.sizes)
+    .filter((v): v is MediaSizeVariant & { url: string; width: number } =>
+      v != null && typeof v.url === 'string' && typeof v.width === 'number',
+    )
+    .sort((a, b) => a.width - b.width)
+}
+
+/**
+ * Finds the best pre-generated variant for a requested width.
+ *
+ * Strategy:
+ * 1. Pick the smallest variant with width >= requested (no quality loss from upscaling)
+ * 2. If none is large enough, use the largest variant — but only if it covers >= 80%
+ *    of the requested width (minor downscale is acceptable, large gap is not)
+ * 3. Returns null when no suitable variant exists → caller should fall back to /_next/image
+ */
+export function findBestVariant(
+  variants: ValidVariant[],
+  requestedWidth: number,
+): ValidVariant | null {
+  if (variants.length === 0) return null
+
+  // Smallest variant >= requested width
+  const larger = variants.find((v) => v.width >= requestedWidth)
+  if (larger) return larger
+
+  // No variant large enough — use the largest if it's close
+  const largest = variants[variants.length - 1]!
+  if (largest.width >= requestedWidth * 0.8) return largest
+
+  return null
+}
+
+/**
+ * Creates a Next.js Image `loader` that maps requested widths to pre-generated
+ * Payload size variants when a close match exists, falling back to the default
+ * `/_next/image` optimization pipeline when no suitable variant is available.
+ *
+ * Returns `undefined` when the media has no usable size variants (i.e. no custom
+ * loader needed — let next/image use its default behavior).
+ *
+ * ```tsx
+ * import { createVariantLoader } from '@inoo-ch/payload-image-optimizer/client'
+ *
+ * const loader = createVariantLoader(media)
+ * <NextImage loader={loader} src={media.url} ... />
+ * ```
+ */
+export function createVariantLoader(media: MediaResource): ImageLoader | undefined {
+  const variants = getValidVariants(media)
+  if (variants.length === 0) return undefined
+
+  const cacheBust = media.updatedAt ? `?${media.updatedAt}` : ''
+
+  return ({ src, width, quality }) => {
+    const match = findBestVariant(variants, width)
+
+    if (match) {
+      return `${match.url}${cacheBust}`
+    }
+
+    // Fall back to next/image optimization for unmatched widths
+    return `/_next/image?url=${encodeURIComponent(src)}&w=${width}&q=${quality || 80}`
+  }
+}
+
+/**
+ * Returns a sensible default `sizes` attribute for responsive images.
+ *
+ * For `fill` mode images without an explicit `sizes` prop, this prevents the
+ * browser from assuming `100vw` (which causes it to always download the
+ * largest srcSet variant regardless of actual display area).
+ */
+export function getDefaultSizes(fill: boolean | undefined): string | undefined {
+  if (!fill) return undefined
+  return '(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw'
+}