@inoo-ch/payload-image-optimizer 1.8.1 → 1.9.0

package/src/components/RegenerationButton.tsx

@@ -25,11 +25,15 @@ export const RegenerationButton: React.FC = () => {
   const [force, setForce] = useState(false)
   const [error, setError] = useState<string | null>(null)
   const [stalled, setStalled] = useState(false)
+  const [cancelled, setCancelled] = useState(false)
   const [collectionSlug, setCollectionSlug] = useState<string | null>(null)
   const [stats, setStats] = useState<RegenerationProgress | null>(null)
   const [confirming, setConfirming] = useState(false)
   const intervalRef = useRef<ReturnType<typeof setInterval> | null>(null)
   const stallRef = useRef({ lastProcessed: 0, stallCount: 0 })
+  // Snapshot of complete+errored at the moment regeneration starts,
+  // so we can compute batch-relative progress for selective regeneration.
+  const baselineRef = useRef<number | null>(null)
   const prevIsRunningRef = useRef(false)
 
   // Extract collection slug from URL after mount to avoid hydration mismatch
@@ -77,9 +81,19 @@ export const RegenerationButton: React.FC = () => {
         `/api/image-optimizer/regenerate?collection=${collectionSlug}`,
       )
       if (res.ok) {
-        const data: RegenerationProgress = await res.json()
+        const data = await res.json()
         setProgress(data)
 
+        // Stop polling if server reports cancellation
+        if (data.cancelled) {
+          setCancelled(true)
+          setIsRunning(false)
+          setStalled(false)
+          stopPolling()
+          sessionStorage.removeItem(SESSION_KEY)
+          return
+        }
+
         // Stop polling when no more pending
         if (data.pending <= 0) {
           setIsRunning(false)
@@ -169,16 +183,38 @@ export const RegenerationButton: React.FC = () => {
     setConfirming(false)
   }
 
+  const handleStop = async () => {
+    if (!collectionSlug) return
+    try {
+      await fetch('/api/image-optimizer/regenerate', {
+        method: 'DELETE',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ collectionSlug }),
+      })
+      setCancelled(true)
+      setIsRunning(false)
+      setStalled(false)
+      stopPolling()
+      sessionStorage.removeItem(SESSION_KEY)
+      fetchStats()
+    } catch {
+      // ignore cancel errors
+    }
+  }
+
   // Phase 2: Actually start regeneration (after user confirms)
   const handleConfirm = async () => {
     if (!collectionSlug) return
     setConfirming(false)
     setError(null)
     setStalled(false)
+    setCancelled(false)
     setIsRunning(true)
     setQueued(null)
     setProgress(null)
     stallRef.current = { lastProcessed: 0, stallCount: 0 }
+    // Capture current complete+errored as baseline before new jobs run
+    baselineRef.current = stats ? stats.complete + stats.errored : 0
 
     try {
       const requestBody: Record<string, unknown> = { collectionSlug, force }
@@ -222,9 +258,20 @@ export const RegenerationButton: React.FC = () => {
 
   if (!collectionSlug) return null
 
+  // When a batch is running, compute progress relative to the queued count
+  // (not the total collection) so selective regeneration shows e.g. 1/2, not 1/167.
+  const batchTotal = queued ?? progress?.total ?? 0
+  const batchProcessed = progress
+    ? (progress.complete + progress.errored) - (baselineRef.current ?? 0)
+    : 0
+  const batchComplete = progress
+    ? progress.complete - Math.max((baselineRef.current ?? 0) - (progress.errored), 0)
+    : 0
+  const batchErrored = progress ? Math.max(batchProcessed - Math.max(batchComplete, 0), 0) : 0
+
   const progressPercent =
-    progress && progress.total > 0
-      ? Math.round(((progress.complete + progress.errored) / progress.total) * 100)
+    batchTotal > 0
+      ? Math.min(Math.round((batchProcessed / batchTotal) * 100), 100)
       : 0
 
   const showProgressBar = (isRunning && progress) || (stalled && progress)
@@ -247,26 +294,41 @@ export const RegenerationButton: React.FC = () => {
         flexWrap: 'wrap',
       }}
     >
-      {!confirming && (
+      {!confirming && !isRunning && (
         <button
           onClick={handlePreflight}
-          disabled={isRunning}
           style={{
-            backgroundColor: isRunning ? '#9ca3af' : '#4f46e5',
+            backgroundColor: '#4f46e5',
             color: '#fff',
             border: 'none',
             borderRadius: '6px',
             padding: '8px 16px',
             fontSize: '14px',
             fontWeight: 500,
-            cursor: isRunning ? 'not-allowed' : 'pointer',
+            cursor: 'pointer',
           }}
         >
-          {isRunning
-            ? 'Processing images...'
-            : hasSelection
-              ? `Regenerate ${selectionCount} Selected`
-              : 'Regenerate All Images'}
+          {hasSelection
+            ? `Regenerate ${selectionCount} Selected`
+            : 'Regenerate All Images'}
+        </button>
+      )}
+
+      {!confirming && isRunning && (
+        <button
+          onClick={handleStop}
+          style={{
+            backgroundColor: '#ef4444',
+            color: '#fff',
+            border: 'none',
+            borderRadius: '6px',
+            padding: '8px 16px',
+            fontSize: '14px',
+            fontWeight: 500,
+            cursor: 'pointer',
+          }}
+        >
+          Stop Processing
         </button>
       )}
 
@@ -336,12 +398,18 @@ export const RegenerationButton: React.FC = () => {
         </span>
       )}
 
-      {queued === 0 && !isRunning && !stalled && !confirming && (
+      {queued === 0 && !isRunning && !stalled && !confirming && !cancelled && (
         <span style={{ color: '#10b981', fontSize: '13px' }}>
           All images already optimized.
         </span>
       )}
 
+      {cancelled && !isRunning && !confirming && (
+        <span style={{ color: '#f59e0b', fontSize: '13px' }}>
+          Processing cancelled.
+        </span>
+      )}
+
       {stalled && progress && (
         <span style={{ color: '#f59e0b', fontSize: '13px' }}>
           Processing appears slow — {progress.pending} image{progress.pending !== 1 ? 's' : ''} still pending.
@@ -360,10 +428,10 @@ export const RegenerationButton: React.FC = () => {
             }}
           >
             <span>
-              {progress.complete} / {progress.total} complete
+              {Math.max(batchProcessed, 0)} / {batchTotal} complete
             </span>
-            {progress.errored > 0 && (
-              <span style={{ color: '#ef4444' }}>{progress.errored} errors</span>
+            {batchErrored > 0 && (
+              <span style={{ color: '#ef4444' }}>{batchErrored} errors</span>
             )}
             <span>{progressPercent}%</span>
           </div>
@@ -379,16 +447,16 @@ export const RegenerationButton: React.FC = () => {
             <div
               style={{
                 height: '100%',
-                width: `${progress.total > 0 ? Math.round((progress.complete / progress.total) * 100) : 0}%`,
+                width: `${batchTotal > 0 ? Math.min(Math.round(((batchProcessed - batchErrored) / batchTotal) * 100), 100) : 0}%`,
                 backgroundColor: '#10b981',
                 transition: 'width 0.3s ease',
               }}
             />
-            {progress.errored > 0 && (
+            {batchErrored > 0 && (
               <div
                 style={{
                   height: '100%',
-                  width: `${progress.total > 0 ? Math.round((progress.errored / progress.total) * 100) : 0}%`,
+                  width: `${batchTotal > 0 ? Math.round((batchErrored / batchTotal) * 100) : 0}%`,
                   backgroundColor: '#ef4444',
                   transition: 'width 0.3s ease',
                 }}
@@ -398,14 +466,14 @@ export const RegenerationButton: React.FC = () => {
         </div>
       )}
 
-      {!isRunning && !stalled && progress && progress.complete > 0 && queued !== 0 && !confirming && (
+      {!isRunning && !stalled && !cancelled && progress && batchProcessed > 0 && queued !== 0 && !confirming && (
         <span style={{ fontSize: '13px' }}>
-          <span style={{ color: progress.errored > 0 ? '#f59e0b' : '#10b981' }}>
-            Done! {progress.complete}/{progress.total} optimized (across entire collection).
+          <span style={{ color: batchErrored > 0 ? '#f59e0b' : '#10b981' }}>
+            Done! {Math.max(batchProcessed - batchErrored, 0)}/{batchTotal} optimized.
           </span>
-          {progress.errored > 0 && (
+          {batchErrored > 0 && (
             <span style={{ color: '#ef4444' }}>
-              {' '}{progress.errored} failed.
+              {' '}{batchErrored} failed.
             </span>
           )}
         </span>

package/src/defaults.ts

@@ -1,6 +1,19 @@
 import type { CollectionSlug } from 'payload'
 
 import type { ImageOptimizerConfig, ResolvedCollectionOptimizerConfig, ResolvedImageOptimizerConfig } from './types.js'
+import { uuidFilename } from './utilities/filenameStrategies.js'
+
+/**
+ * Resolve the generateFilename option:
+ * - Explicit `generateFilename` callback takes priority
+ * - `uniqueFileNames: true` maps to `uuidFilename` for backwards compat
+ * - Otherwise undefined (keep original filename)
+ */
+const resolveGenerateFilename = (config: ImageOptimizerConfig) => {
+  if (config.generateFilename) return config.generateFilename
+  if (config.uniqueFileNames) return uuidFilename
+  return undefined
+}
 
 export const resolveConfig = (config: ImageOptimizerConfig): ResolvedImageOptimizerConfig => ({
   clientOptimization: config.clientOptimization ?? true,
@@ -9,11 +22,12 @@ export const resolveConfig = (config: ImageOptimizerConfig): ResolvedImageOptimi
   formats: config.formats ?? [
     { format: 'webp', quality: 80 },
   ],
+  generateFilename: resolveGenerateFilename(config),
   generateThumbHash: config.generateThumbHash ?? true,
   maxDimensions: config.maxDimensions ?? { width: 2560, height: 2560 },
+  regenerateButton: config.regenerateButton ?? true,
   replaceOriginal: config.replaceOriginal ?? true,
   stripMetadata: config.stripMetadata ?? true,
-  uniqueFileNames: config.uniqueFileNames ?? false,
 })
 
 export const resolveCollectionConfig = (

package/src/endpoints/regenerate.ts

@@ -4,6 +4,32 @@ import type { CollectionSlug, Where } from 'payload'
 import type { ResolvedImageOptimizerConfig } from '../types.js'
 import { waitUntil } from '../utilities/waitUntil.js'
 
+type CollectionState = { startedAt?: number; cancelledAt?: number; queued?: number }
+type StateCollections = Record<string, CollectionState>
+
+const GLOBAL_SLUG = 'image-optimizer-state'
+
+async function getCollectionState(payload: any, slug: string): Promise<CollectionState> {
+  try {
+    const state = await payload.findGlobal({ slug: GLOBAL_SLUG })
+    return (state?.collections as StateCollections)?.[slug] || {}
+  } catch {
+    return {}
+  }
+}
+
+async function setCollectionState(payload: any, slug: string, update: Partial<CollectionState>): Promise<void> {
+  let existing: StateCollections = {}
+  try {
+    const state = await payload.findGlobal({ slug: GLOBAL_SLUG })
+    existing = (state?.collections as StateCollections) || {}
+  } catch {
+    // Global may not exist yet
+  }
+  existing[slug] = { ...existing[slug], ...update }
+  await payload.updateGlobal({ slug: GLOBAL_SLUG, data: { collections: existing } })
+}
+
 export const createRegenerateHandler = (resolvedConfig: ResolvedImageOptimizerConfig) => {
   const handler: PayloadHandler = async (req) => {
     if (!req.user) {
@@ -87,6 +113,13 @@ export const createRegenerateHandler = (resolvedConfig: ResolvedImageOptimizerCo
 
     req.payload.logger.info(`Image optimizer: queued ${queued} images from '${collectionSlug}' for regeneration`)
 
+    // Clear any previous cancellation and record the start time + batch size
+    await setCollectionState(req.payload, collectionSlug, {
+      startedAt: Date.now(),
+      cancelledAt: undefined,
+      queued,
+    })
+
     // Fire the job runner — use waitUntil to keep the serverless function alive
     // after the response is sent, so jobs actually complete on Vercel/serverless.
     if (queued > 0) {
@@ -136,13 +169,48 @@ export const createRegenerateStatusHandler = (resolvedConfig: ResolvedImageOptim
       },
     })
 
+    // Include cancellation state so the UI can react
+    const collState = await getCollectionState(req.payload, collectionSlug)
+    const cancelled = !!(collState.cancelledAt && collState.startedAt && collState.cancelledAt > collState.startedAt)
+
     return Response.json({
       collectionSlug,
       total: total.totalDocs,
       complete: complete.totalDocs,
       errored: errored.totalDocs,
       pending: total.totalDocs - complete.totalDocs - errored.totalDocs,
+      cancelled,
+    })
+  }
+
+  return handler
+}
+
+export const createCancelHandler = (resolvedConfig: ResolvedImageOptimizerConfig) => {
+  const handler: PayloadHandler = async (req) => {
+    if (!req.user) {
+      return Response.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    let body: { collectionSlug?: string }
+    try {
+      body = await req.json!()
+    } catch {
+      body = {}
+    }
+
+    const collectionSlug = body.collectionSlug
+    if (!collectionSlug || !resolvedConfig.collections[collectionSlug as CollectionSlug]) {
+      return Response.json({ error: 'Invalid or unconfigured collection slug' }, { status: 400 })
+    }
+
+    await setCollectionState(req.payload, collectionSlug, {
+      cancelledAt: Date.now(),
     })
+
+    req.payload.logger.info(`Image optimizer: cancellation requested for '${collectionSlug}'`)
+
+    return Response.json({ cancelled: true, collectionSlug })
   }
 
   return handler

package/src/hooks/beforeChange.ts

@@ -1,4 +1,3 @@
-import crypto from 'crypto'
 import path from 'path'
 import type { CollectionBeforeChangeHook } from 'payload'
 
@@ -16,24 +15,22 @@ export const createBeforeChangeHook = (
 
     if (!req.file || !req.file.data || !req.file.mimetype?.startsWith('image/')) return data
 
-    // Rename file to UUID before any processing, so the storage adapter
-    // never sees the original filename. Prevents Vercel Blob "already exists"
-    // errors and avoids leaking original filenames to storage.
-    // On focal-point or crop re-uploads (where Payload re-sends the same file),
-    // reuse the existing UUID filename to avoid unnecessary file churn and
-    // broken previews.
-    if (resolvedConfig.uniqueFileNames) {
+    // Apply custom filename strategy (seoFilename, uuidFilename, or user-provided).
+    // The callback returns a stem (no extension) — we append the original extension here,
+    // and replaceOriginal may swap it to the target format extension later.
+    if (resolvedConfig.generateFilename) {
       const existingFilename = (originalDoc as Record<string, unknown> | undefined)?.filename as string | undefined
-      if (existingFilename) {
-        // Reuse the existing filename (may get a new extension below if replaceOriginal changes format)
-        req.file.name = existingFilename
-        data.filename = existingFilename
-      } else {
-        const ext = path.extname(req.file.name)
-        const uuid = crypto.randomUUID()
-        req.file.name = `${uuid}${ext}`
-        data.filename = req.file.name
-      }
+      const ext = path.extname(req.file.name)
+      const stem = resolvedConfig.generateFilename({
+        altText: (data as Record<string, unknown>).alt as string | undefined,
+        originalFilename: req.file.name,
+        mimeType: req.file.mimetype,
+        collectionSlug,
+        existingFilename,
+      })
+      const newFilename = `${stem}${ext}`
+      req.file.name = newFilename
+      data.filename = newFilename
     }
 
     const originalSize = req.file.data.length

package/src/index.ts

@@ -9,12 +9,13 @@ import { createBeforeChangeHook } from './hooks/beforeChange.js'
 import { createAfterChangeHook } from './hooks/afterChange.js'
 import { createConvertFormatsHandler } from './tasks/convertFormats.js'
 import { createRegenerateDocumentHandler } from './tasks/regenerateDocument.js'
-import { createRegenerateHandler, createRegenerateStatusHandler } from './endpoints/regenerate.js'
+import { createRegenerateHandler, createRegenerateStatusHandler, createCancelHandler } from './endpoints/regenerate.js'
 
-export type { ImageOptimizerConfig, ImageFormat, FormatQuality, CollectionOptimizerConfig, ImageOptimizerData, MediaResource, MediaSizeVariant, FieldsOverride } from './types.js'
+export type { ImageOptimizerConfig, ImageFormat, FormatQuality, CollectionOptimizerConfig, ImageOptimizerData, MediaResource, MediaSizeVariant, FieldsOverride, GenerateFilename, GenerateFilenameArgs } from './types.js'
 export { defaultImageOptimizerFields } from './fields/imageOptimizerField.js'
 
 export { encodeImageToThumbHash, decodeThumbHashToDataURL } from './utilities/thumbhash.js'
+export { uuidFilename, seoFilename } from './utilities/filenameStrategies.js'
 
 /**
  * Recommended maxDuration for the Payload API route on Vercel.
@@ -69,10 +70,14 @@ export const imageOptimizer =
                   },
                 }
               : {}),
-            beforeListTable: [
-              ...(collection.admin?.components?.beforeListTable || []),
-              '@inoo-ch/payload-image-optimizer/client#RegenerationButton',
-            ],
+            ...(resolvedConfig.regenerateButton
+            ? {
+                beforeListTable: [
+                  ...(collection.admin?.components?.beforeListTable || []),
+                  '@inoo-ch/payload-image-optimizer/client#RegenerationButton',
+                ],
+              }
+            : {}),
           },
         },
       }
@@ -91,6 +96,17 @@ export const imageOptimizer =
     return {
       ...config,
       collections,
+      globals: [
+        ...(config.globals || []),
+        {
+          slug: 'image-optimizer-state',
+          admin: { hidden: true },
+          access: { read: () => true, update: () => true },
+          fields: [
+            { name: 'collections', type: 'json' },
+          ],
+        },
+      ],
       i18n,
       jobs: {
         ...config.jobs,
@@ -135,6 +151,11 @@ export const imageOptimizer =
           method: 'get',
           handler: createRegenerateStatusHandler(resolvedConfig),
         },
+        {
+          path: '/image-optimizer/regenerate',
+          method: 'delete',
+          handler: createCancelHandler(resolvedConfig),
+        },
       ],
     }
   }

package/src/tasks/regenerateDocument.ts

@@ -1,4 +1,3 @@
-import crypto from 'crypto'
 import fs from 'fs/promises'
 import path from 'path'
 
@@ -10,9 +9,22 @@ import { stripAndResize, generateThumbHash, convertFormat } from '../processing/
 import { resolveStaticDir } from '../utilities/resolveStaticDir.js'
 import { fetchFileBuffer, isCloudStorage } from '../utilities/storage.js'
 
+const GLOBAL_SLUG = 'image-optimizer-state'
+
 export const createRegenerateDocumentHandler = (resolvedConfig: ResolvedImageOptimizerConfig) => {
   return async ({ input, req }: { input: { collectionSlug: string; docId: string }; req: any }) => {
     try {
+      // Check cancellation before processing
+      try {
+        const state = await req.payload.findGlobal({ slug: GLOBAL_SLUG })
+        const collState = (state?.collections as Record<string, any>)?.[input.collectionSlug]
+        if (collState?.cancelledAt && collState.cancelledAt > (collState.startedAt || 0)) {
+          return { output: { status: 'cancelled', reason: 'user-cancelled' } }
+        }
+      } catch {
+        // Global may not exist yet — proceed normally
+      }
+
       const doc = await req.payload.findByID({
         collection: input.collectionSlug as CollectionSlug,
         id: input.docId,
@@ -75,11 +87,19 @@ export const createRegenerateDocumentHandler = (resolvedConfig: ResolvedImageOpt
       if (cloudStorage) {
         // Cloud storage: re-upload the optimized file via Payload's update API.
         // This triggers the cloud adapter's afterChange hook which uploads to cloud.
-        // When uniqueFileNames is enabled, generate a new UUID filename to avoid
+        // When a filename strategy is configured, generate a new filename to avoid
         // Vercel Blob "already exists" errors (the adapter doesn't support allowOverwrite).
-        if (resolvedConfig.uniqueFileNames) {
+        if (resolvedConfig.generateFilename) {
           const ext = path.extname(newFilename)
-          newFilename = `${crypto.randomUUID()}${ext}`
+          const stem = resolvedConfig.generateFilename({
+            altText: doc.alt as string | undefined,
+            originalFilename: safeFilename,
+            mimeType: doc.mimeType as string,
+            collectionSlug: input.collectionSlug,
+            // No existingFilename — regeneration should always create a fresh name
+            // to avoid cloud storage "already exists" errors
+          })
+          newFilename = `${stem}${ext}`
         }
 
         const updateData: Record<string, any> = {

package/src/types.ts

@@ -2,6 +2,29 @@ import type { CollectionSlug, Field } from 'payload'
 
 export type ImageFormat = 'webp' | 'avif'
 
+export type GenerateFilenameArgs = {
+  /** Alt text from the document (if the collection has an `alt` field) */
+  altText?: string
+  /** Original uploaded filename (e.g., "IMG_2847.jpg") */
+  originalFilename: string
+  /** The MIME type (e.g., "image/jpeg") */
+  mimeType: string
+  /** The collection slug this file belongs to */
+  collectionSlug: string
+  /** Existing filename from a previous upload (set on re-uploads / focal point changes).
+   *  Strategies should typically reuse this to avoid cloud storage churn. */
+  existingFilename?: string
+}
+
+/**
+ * Custom filename generation function.
+ * Return the filename **stem** (without extension) — the plugin appends the
+ * correct extension based on format conversion settings.
+ *
+ * Built-in strategies: `uuidFilename`, `seoFilename`
+ */
+export type GenerateFilename = (args: GenerateFilenameArgs) => string
+
 export type FormatQuality = {
   format: ImageFormat
   quality: number // 1-100
@@ -21,13 +44,37 @@ export type ImageOptimizerConfig = {
   disabled?: boolean
   fieldsOverride?: FieldsOverride
   formats?: FormatQuality[]
+  /** Custom filename generation strategy. Return the filename **stem** (no extension).
+   * The plugin appends the correct extension based on format conversion settings.
+   *
+   * Built-in strategies:
+   * - `uuidFilename` — UUID-based, collision-free (same as `uniqueFileNames: true`)
+   * - `seoFilename` — Human-readable from alt text + timestamp
+   *
+   * When set, `uniqueFileNames` is ignored.
+   *
+   * @example
+   * ```ts
+   * import { imageOptimizer, seoFilename } from '@inoo-ch/payload-image-optimizer'
+   *
+   * imageOptimizer({
+   *   collections: { media: true },
+   *   generateFilename: seoFilename,
+   * })
+   * ```
+   */
+  generateFilename?: GenerateFilename
   generateThumbHash?: boolean
   maxDimensions?: { width: number; height: number }
+  /** Show the "Regenerate All Images" button in the collection list view.
+   * Defaults to `true`. */
+  regenerateButton?: boolean
   replaceOriginal?: boolean
   stripMetadata?: boolean
   /** Replace original filenames with UUIDs (e.g., `photo.jpg` → `a1b2c3d4.webp`).
    * Prevents Vercel Blob "already exists" errors and avoids leaking original filenames.
-   * Defaults to `false`. */
+   * Defaults to `false`.
+   * @deprecated Use `generateFilename: uuidFilename` instead. */
   uniqueFileNames?: boolean
 }
 
@@ -43,8 +90,10 @@ export type ResolvedImageOptimizerConfig = Required<
   clientOptimization: boolean
   collections: ImageOptimizerConfig['collections']
   disabled: boolean
+  /** Resolved filename generator. `undefined` means keep original filename. */
+  generateFilename?: GenerateFilename
+  regenerateButton: boolean
   replaceOriginal: boolean
-  uniqueFileNames: boolean
 }
 
 export type ImageOptimizerData = {

package/src/utilities/filenameStrategies.ts

@@ -0,0 +1,61 @@
+import crypto from 'crypto'
+import path from 'path'
+
+import type { GenerateFilenameArgs } from '../types.js'
+import { stripDiacritics } from './stripDiacritics.js'
+import { toKebabCase } from './toKebabCase.js'
+
+const MAX_STEM_LENGTH = 60
+
+/**
+ * UUID-based filename strategy.
+ *
+ * Generates collision-free filenames like `a1b2c3d4-e5f6-7890-abcd-ef1234567890`.
+ * On re-uploads (focal point / crop changes), reuses the existing filename stem
+ * to avoid unnecessary file churn on cloud storage.
+ */
+export const uuidFilename = ({ existingFilename }: GenerateFilenameArgs): string => {
+  if (existingFilename) {
+    return path.parse(existingFilename).name
+  }
+  return crypto.randomUUID()
+}
+
+/**
+ * SEO-friendly filename strategy.
+ *
+ * Generates human-readable, URL-safe filenames from alt text:
+ *   "Geländer aus Edelstahl" → `gelander-aus-edelstahl-20260327T120000Z`
+ *
+ * Processing pipeline:
+ *  1. Uses alt text, falls back to original filename stem, then "media"
+ *  2. Strips diacritics (ä→a, ö→o, ü→u, é→e)
+ *  3. Converts to kebab-case
+ *  4. Truncates to 60 characters (clean break, no trailing hyphens)
+ *  5. Appends ISO timestamp for uniqueness (YYYYMMDDTHHMMSSmmm)
+ *
+ * On re-uploads, reuses the existing filename stem to avoid cloud storage churn.
+ */
+export const seoFilename = ({
+  altText,
+  existingFilename,
+  originalFilename,
+}: GenerateFilenameArgs): string => {
+  if (existingFilename) {
+    return path.parse(existingFilename).name
+  }
+
+  const source = altText?.trim() || path.parse(originalFilename).name || 'media'
+  const slug = toKebabCase(stripDiacritics(source))
+
+  // Truncate cleanly — don't leave a trailing hyphen
+  const truncated = slug.length > MAX_STEM_LENGTH
+    ? slug.slice(0, MAX_STEM_LENGTH).replace(/-$/, '')
+    : slug
+
+  // Append timestamp for uniqueness (ISO-ish, no colons for filesystem safety)
+  const now = new Date()
+  const timestamp = now.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z')
+
+  return `${truncated || 'media'}-${timestamp}`
+}

package/src/utilities/stripDiacritics.ts

@@ -0,0 +1,10 @@
+/**
+ * Strip diacritics (combining marks) from a string using Unicode NFKD normalization.
+ *
+ * Examples: ä→a, ö→o, ü→u, é→e, ñ→n
+ *
+ * Note: This maps ä→a (not ä→ae). For German, the ae/oe/ue transliteration
+ * is sometimes preferred for SEO — but plain ASCII is simpler and works well for URLs.
+ */
+export const stripDiacritics = (input: string): string =>
+  input.normalize('NFKD').replace(/[\u0300-\u036f]/g, '')