image-renditions 0.2.0 → 0.4.0

package/README.md

@@ -8,10 +8,10 @@ Resize and re-encode uploaded images when a page first shows them, store each re
 
 ```html
 <img
-  src="/_renditions/v1/avatar.faf7e221f65dd97945e352a57e805252.avif/avatars/42.jpg"
+  src="/_renditions/v1/avatar.faf7e221f65d.avif/avatars/42.jpg"
   srcset="
-    /_renditions/v1/avatar.faf7e221f65dd97945e352a57e805252.avif/avatars/42.jpg    1x,
-    /_renditions/v1/avatar@2x.b62b90cf6c3ed57e4c1c27da0c36d778.avif/avatars/42.jpg 2x
+    /_renditions/v1/avatar.faf7e221f65d.avif/avatars/42.jpg    1x,
+    /_renditions/v1/avatar@2x.b62b90cf6c3e.avif/avatars/42.jpg 2x
   "
   alt=""
 />
@@ -23,7 +23,13 @@ Resize and re-encode uploaded images when a page first shows them, store each re
 
 With an S3 bucket, or a directory that outlives deploys and is shared by every replica, app servers keep no image files: renditions survive redeploys, and any replica serves any of them.
 
-The h3 handler supports h3 1.15 or newer and h3 2, and the Nuxt module requires Nuxt 4.
+The library is modular, with pluggable parts:
+
+- [HTTP](#h3-and-other-frameworks): an event handler for h3 1.15 or newer and h3 2, and a framework-neutral handler for other servers.
+- [Processing](#processing): a processor built on sharp.
+- [Storage](#storage): an S3 bucket or a file system directory, chosen separately for uploads and renditions.
+- [Nuxt](#quick-start): a Nuxt 4 module that registers the handler and the `<RenditionImg>` component.
+- [Extending](#extending): other storage, image libraries, and state shared between replicas plug in through the interfaces of `image-renditions/server`.
 
 ## When not to use it
 
@@ -232,7 +238,7 @@ export default defineRenditionEventHandler({
 - Map different scopes to different keys even for equal paths.
 - A rendition is stored in the result store at `<sourceKey>/<hash>.<extension>`.
   To keep renditions in the bucket of uploads, also return a `resultPrefix` that no source key starts with, such as `` `renditions/${sourceKey}` ``, to use instead of `sourceKey`.
-- S3 limits a key to 1024 bytes in UTF-8, and a rendition key adds up to 38 bytes to its result prefix.
+- S3 limits a key to 1024 bytes in UTF-8, and the library writes a rendition under a key up to 18 bytes longer than its result prefix.
   If source keys can come that close to the limit, return a shorter `resultPrefix`, or their renditions fail as `invalid-request`.
 
 Derive the context from the URL only, host included, for example from the tenant's domain: browsers and CDNs cache the redirect to a rendition by its URL for a day.
@@ -403,6 +409,18 @@ It renders the first frame of other animated sources, such as APNG and animated
 An animation at the pixel limit may take about 4 bytes of memory per pixel, and its encoder needs more, so plan memory for `limits.concurrency` such renditions at once.
 Changing the limits keeps stored renditions as they are; bump `pipelineVersion` to render them again.
 
+When a preset keeps the animation and a GIF or WebP animation renders its first frame because of its EXIF orientation or a limit, `createRenditionServer()` passes it to `onDegradation` once the rendition is written.
+The reason is `animation-orientation`, `animation-frames` or `animation-pixels`, and the message has the values involved, so you can log such renditions and tune the limits:
+
+```ts
+const server = createRenditionServer({
+  // ...
+  onDegradation({ message, target }) {
+    console.warn(`The rendition of ${target.path} is degraded: ${message}`)
+  },
+})
+```
+
 To process images with another library, implement the [`Processor`](#extending) interface and pass your implementation to `createRenditionServer()` as `processor`.
 
 ## h3 and other frameworks
@@ -443,7 +461,7 @@ Build URLs in the app with the catalog, which is safe to import in browsers:
 
 ```ts
 catalog.url("avatar", { path: "avatars/42.jpg" })
-// /_renditions/v1/avatar.faf7e221f65dd97945e352a57e805252.avif/avatars/42.jpg
+// /_renditions/v1/avatar.faf7e221f65d.avif/avatars/42.jpg
 
 catalog.srcset("avatar", { scope: "tenant", path: "avatars/42.jpg" })
 ```
@@ -570,6 +588,7 @@ Implement an interface from `image-renditions/server` and pass your implementati
 - To use other storage, implement `SourceStore` or `ResultStore` and pass it as `source` or `results`.
 - To process images with another library, implement `Processor` and pass it as `processor`.
   Implement its `assertRecipe()` to reject recipes it cannot render, such as animations, when the server is created.
+  Return `degradation` from its `process()` to report an image that falls short of its recipe to `onDegradation`.
 - To share the index of published renditions between replicas, for example in Redis, implement `ReadinessIndex` and pass it as `readiness.shared`.
   If a call fails or exceeds `indexTimeout`, the server reports the error to `onError` and checks storage instead, while [outdated URLs](#outdated-urls) fail as `unknown-recipe`.
 - To render each rendition once across replicas, implement `Coordinator` as a shared lock and pass it as `coordinator`.

package/dist/h3.d.mts

@@ -1,4 +1,4 @@
-import { r as RenditionHandlerOptions } from "./handler-9XP5SZhg.mjs";
+import { r as RenditionHandlerOptions } from "./handler-P49xsp3S.mjs";
 import { EventHandler, H3Event } from "h3";
 //#region src/h3.d.ts
 /** Source of the application context of a request. */

package/dist/h3.mjs

@@ -1,4 +1,4 @@
-import { t as createRenditionHandler } from "./handler-CPJllrYi.mjs";
+import { t as createRenditionHandler } from "./handler-D5toFJ55.mjs";
 import { defineEventHandler } from "h3";
 //#region src/h3.ts
 /**

package/dist/{handler-CPJllrYi.mjs → handler-D5toFJ55.mjs}

@@ -1,5 +1,5 @@
-import { a as parseRenditionPath } from "./url-BAU5GYXC.mjs";
 import { r as toDeclaredTarget } from "./scopes-C1kzqQHz.mjs";
+import { i as parseRenditionPath } from "./url-C6PtYIEf.mjs";
 import { t as RenditionError } from "./error-DViVpVmH.mjs";
 //#region src/server/handler.ts
 const failureStatus = {

package/dist/{handler-9XP5SZhg.d.mts → handler-P49xsp3S.d.mts}

@@ -1,8 +1,8 @@
 import { r as Recipe, s as RenditionFormat } from "./recipe-BT8D60Qb.mjs";
 import { a as RenditionTarget, t as Catalog } from "./catalog-D11xkViN.mjs";
-import { n as RenditionAddress } from "./url-BVH3ZB0F.mjs";
+import { n as RenditionAddress } from "./url-DoJdUx9J.mjs";
 import { i as StoreCallOptions, n as ResultStore, r as SourceStore } from "./stores-P-TUmax4.mjs";
-import { t as Processor } from "./processor-DvyPs-OZ.mjs";
+import { r as Processor, t as Degradation } from "./processor-Dd3jqaOW.mjs";
 //#region src/server/error.d.ts
 /** Why a rendition could not be served. */
 type RenditionFailureReason =
@@ -124,6 +124,21 @@ interface RenditionServerOptions<Context, Scope extends string = string> {
    * It is not awaited, and its own failures are ignored.
    */
   onError?(error: unknown): void;
+  /**
+   * Receives a degradation the processor reports for a rendition it rendered, such as the first frame of an animation beyond a limit, once the rendition is written.
+   *
+   * Later requests for the rendition do not report it again.
+   * It is not awaited, and its own failures are ignored.
+   */
+  onDegradation?(degradation: RenditionDegradation<Context, Scope>): void;
+}
+/** Degradation a processor reported for a rendition the server wrote. */
+interface RenditionDegradation<Context, Scope extends string = string> extends Degradation {
+  recipe: Recipe;
+  target: RenditionTarget<Scope>;
+  /** Context of the call that rendered the rendition, which may be any of the concurrent calls for it. */
+  context: Context;
+  rendition: Rendition;
 }
 /** Published rendition. */
 interface Rendition {
@@ -224,4 +239,4 @@ type RenditionHandler<Context> = (request: RenditionRequest, getContext: () => C
  */
 declare function createRenditionHandler<Context, Scope extends string = string>({ server, onFailure, redirectCacheControl }: RenditionHandlerOptions<Context, Scope>): RenditionHandler<Context>;
 //#endregion
-export { RenditionFailureReason as _, createRenditionHandler as a, RenditionServerOptions as c, MemoryReadinessIndexOptions as d, ReadinessIndex as f, RenditionError as g, createLocalCoordinator as h, RenditionRequest as i, SourceResolution as l, Coordinator as m, RenditionHandler as n, Rendition as o, createMemoryReadinessIndex as p, RenditionHandlerOptions as r, RenditionServer as s, RenditionFailure as t, createRenditionServer as u };
+export { RenditionError as _, createRenditionHandler as a, RenditionServer as c, createRenditionServer as d, MemoryReadinessIndexOptions as f, createLocalCoordinator as g, Coordinator as h, RenditionRequest as i, RenditionServerOptions as l, createMemoryReadinessIndex as m, RenditionHandler as n, Rendition as o, ReadinessIndex as p, RenditionHandlerOptions as r, RenditionDegradation as s, RenditionFailure as t, SourceResolution as u, RenditionFailureReason as v };

package/dist/hash-CHipV1N6.mjs

@@ -0,0 +1,16 @@
+import { o as serializeRecipe } from "./recipe-BavgOq0b.mjs";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils.js";
+//#region src/hash.ts
+/**
+* Length of a recipe hash in hex digits, which keeps 48 bits of SHA-256.
+*
+* It tells apart the few thousand recipes an application may have over its lifetime, and a catalog rejects a collision among its own recipes.
+*/
+const RECIPE_HASH_LENGTH = 12;
+/** Identifies a recipe by the truncated SHA-256 of its canonical serialization. */
+function hashRecipe(recipe) {
+	return bytesToHex(sha256(utf8ToBytes(serializeRecipe(recipe)))).slice(0, RECIPE_HASH_LENGTH);
+}
+//#endregion
+export { hashRecipe as t };

package/dist/index.d.mts

@@ -1,9 +1,7 @@
 import { a as RenditionAnimation, c as RenditionOptions, d as formatContentTypes, f as formatExtensions, i as RecipeInput, l as RenditionPosition, m as serializeRecipe, n as RECIPE_ENGINE_VERSION, o as RenditionFit, p as normalizeRecipe, r as Recipe, s as RenditionFormat, t as MAX_DIMENSION, u as SourcePolicy } from "./recipe-BT8D60Qb.mjs";
 import { a as RenditionTarget, c as defineCatalog, i as PresetName, n as CatalogDefinition, o as RenditionVariant, r as PresetDefinition, s as ScopeName, t as Catalog } from "./catalog-D11xkViN.mjs";
-import { a as formatRenditionPath, i as assertBasePath, n as RenditionAddress, o as parseRenditionPath, r as URL_FORMAT_VERSION, t as DEFAULT_BASE_PATH } from "./url-BVH3ZB0F.mjs";
+import { i as parseRenditionPath, n as RenditionAddress, r as formatRenditionPath, t as DEFAULT_BASE_PATH } from "./url-DoJdUx9J.mjs";
 //#region src/hash.d.ts
-/** Length of a recipe hash in hex digits, which keeps 128 bits of SHA-256. */
-export declare const RECIPE_HASH_LENGTH = 32;
 /** Identifies a recipe by the truncated SHA-256 of its canonical serialization. */
 export declare function hashRecipe(recipe: Recipe): string;
 //#endregion
@@ -20,4 +18,4 @@ export declare function encodePath(path: string): string;
 /** Checks that a scope is a short token that needs no URL encoding. */
 export declare function isSafeScope(scope: string): boolean;
 //#endregion
-export { Catalog, CatalogDefinition, DEFAULT_BASE_PATH, MAX_DIMENSION, PresetDefinition, PresetName, RECIPE_ENGINE_VERSION, Recipe, RecipeInput, RenditionAddress, RenditionAnimation, RenditionFit, RenditionFormat, RenditionOptions, RenditionPosition, RenditionTarget, RenditionVariant, ScopeName, SourcePolicy, URL_FORMAT_VERSION, assertBasePath, defineCatalog, formatContentTypes, formatExtensions, formatRenditionPath, normalizeRecipe, parseRenditionPath, serializeRecipe };
+export { Catalog, CatalogDefinition, DEFAULT_BASE_PATH, MAX_DIMENSION, PresetDefinition, PresetName, RECIPE_ENGINE_VERSION, Recipe, RecipeInput, type RenditionAddress, RenditionAnimation, RenditionFit, RenditionFormat, RenditionOptions, RenditionPosition, RenditionTarget, RenditionVariant, ScopeName, SourcePolicy, defineCatalog, formatContentTypes, formatExtensions, formatRenditionPath, normalizeRecipe, parseRenditionPath, serializeRecipe };

package/dist/index.mjs

@@ -1,7 +1,8 @@
 import { a as normalizeRecipe, i as formatExtensions, n as RECIPE_ENGINE_VERSION, o as serializeRecipe, r as formatContentTypes, t as MAX_DIMENSION } from "./recipe-BavgOq0b.mjs";
-import { a as parseRenditionPath, i as formatRenditionPath, n as URL_FORMAT_VERSION, o as RECIPE_HASH_LENGTH, r as assertBasePath, s as hashRecipe, t as DEFAULT_BASE_PATH } from "./url-BAU5GYXC.mjs";
+import { t as hashRecipe } from "./hash-CHipV1N6.mjs";
 import { n as isSafePath, r as isSafeScope, t as encodePath } from "./path-hNFUjCbA.mjs";
 import { t as assertDeclaredScope } from "./scopes-C1kzqQHz.mjs";
+import { i as parseRenditionPath, n as assertBasePath, r as formatRenditionPath, t as DEFAULT_BASE_PATH } from "./url-C6PtYIEf.mjs";
 //#region src/catalog.ts
 /** Extensions of sources that get animated variants, as a path does not tell an animated source from a still one. */
 const ANIMATED_EXTENSIONS = ["gif", "webp"];
@@ -64,7 +65,11 @@ function defineCatalog(definition) {
 			originals: Object.freeze([...originals]),
 			animatedVariants
 		});
-		for (const variant of [...variants, ...animatedVariants ?? []]) if (!variantsByHash.has(variant.hash)) variantsByHash.set(variant.hash, variant);
+		for (const variant of [...variants, ...animatedVariants ?? []]) {
+			const known = variantsByHash.get(variant.hash);
+			if (known && serializeRecipe(known.recipe) !== serializeRecipe(variant.recipe)) throw new RangeError(`Variants "${known.label}" and "${variant.label}" have different recipes of the same hash; change pipelineVersion to change every hash.`);
+			if (!known) variantsByHash.set(variant.hash, variant);
+		}
 	}
 	function getPreset(preset) {
 		const found = presetsByName.get(preset);
@@ -120,4 +125,4 @@ function wrapRangeError(context, fn) {
 	}
 }
 //#endregion
-export { DEFAULT_BASE_PATH, MAX_DIMENSION, RECIPE_ENGINE_VERSION, RECIPE_HASH_LENGTH, URL_FORMAT_VERSION, assertBasePath, defineCatalog, encodePath, formatContentTypes, formatExtensions, formatRenditionPath, hashRecipe, isSafePath, isSafeScope, normalizeRecipe, parseRenditionPath, serializeRecipe };
+export { DEFAULT_BASE_PATH, MAX_DIMENSION, RECIPE_ENGINE_VERSION, defineCatalog, encodePath, formatContentTypes, formatExtensions, formatRenditionPath, hashRecipe, isSafePath, isSafeScope, normalizeRecipe, parseRenditionPath, serializeRecipe };

package/dist/{processor-DvyPs-OZ.d.mts → processor-Dd3jqaOW.d.mts}

@@ -1,6 +1,22 @@
 import { r as Recipe } from "./recipe-BT8D60Qb.mjs";
 import { t as EncodedImage } from "./stores-P-TUmax4.mjs";
 //#region src/server/processor.d.ts
+/** Shortfall of a rendered image against its recipe, which a processor reports. */
+interface Degradation {
+  /** Code of the shortfall, such as `animation-frames`. */
+  reason: string;
+  /** Human-readable description with the values involved, such as an exceeded limit. */
+  message: string;
+}
+/** Image a processor renders. */
+interface ProcessedImage extends EncodedImage {
+  /**
+   * Shortfall the processor detected, such as the first frame of an animation beyond a limit.
+   *
+   * Its absence does not promise that the image renders the recipe in full.
+   */
+  degradation?: Degradation;
+}
 /** Renders a source image according to a recipe. */
 interface Processor {
   /**
@@ -8,7 +24,7 @@ interface Processor {
    *
    * Rejects with a `RenditionError` of reason `unsupported-source` when the source cannot be decoded or processed, and of reason `source-too-large` when it exceeds a size limit.
    */
-  process(source: Uint8Array, recipe: Recipe): Promise<EncodedImage>;
+  process(source: Uint8Array, recipe: Recipe): Promise<ProcessedImage>;
   /**
    * Checks that the processor renders a recipe as it describes.
    *
@@ -19,4 +35,4 @@ interface Processor {
   assertRecipe?(recipe: Recipe): void;
 }
 //#endregion
-export { Processor as t };
+export { ProcessedImage as n, Processor as r, Degradation as t };

package/dist/server.d.mts

@@ -1,4 +1,4 @@
-import { _ as RenditionFailureReason, a as createRenditionHandler, c as RenditionServerOptions, d as MemoryReadinessIndexOptions, f as ReadinessIndex, g as RenditionError, h as createLocalCoordinator, i as RenditionRequest, l as SourceResolution, m as Coordinator, n as RenditionHandler, o as Rendition, p as createMemoryReadinessIndex, r as RenditionHandlerOptions, s as RenditionServer, t as RenditionFailure, u as createRenditionServer } from "./handler-9XP5SZhg.mjs";
+import { _ as RenditionError, a as createRenditionHandler, c as RenditionServer, d as createRenditionServer, f as MemoryReadinessIndexOptions, g as createLocalCoordinator, h as Coordinator, i as RenditionRequest, l as RenditionServerOptions, m as createMemoryReadinessIndex, n as RenditionHandler, o as Rendition, p as ReadinessIndex, r as RenditionHandlerOptions, s as RenditionDegradation, t as RenditionFailure, u as SourceResolution, v as RenditionFailureReason } from "./handler-P49xsp3S.mjs";
 import { i as StoreCallOptions, n as ResultStore, r as SourceStore, t as EncodedImage } from "./stores-P-TUmax4.mjs";
-import { t as Processor } from "./processor-DvyPs-OZ.mjs";
-export { Coordinator, EncodedImage, MemoryReadinessIndexOptions, Processor, ReadinessIndex, Rendition, RenditionError, RenditionFailure, RenditionFailureReason, RenditionHandler, RenditionHandlerOptions, RenditionRequest, RenditionServer, RenditionServerOptions, ResultStore, SourceResolution, SourceStore, StoreCallOptions, createLocalCoordinator, createMemoryReadinessIndex, createRenditionHandler, createRenditionServer };
+import { n as ProcessedImage, r as Processor, t as Degradation } from "./processor-Dd3jqaOW.mjs";
+export { Coordinator, Degradation, EncodedImage, MemoryReadinessIndexOptions, ProcessedImage, Processor, ReadinessIndex, Rendition, RenditionDegradation, RenditionError, RenditionFailure, RenditionFailureReason, RenditionHandler, RenditionHandlerOptions, RenditionRequest, RenditionServer, RenditionServerOptions, ResultStore, SourceResolution, SourceStore, StoreCallOptions, createLocalCoordinator, createMemoryReadinessIndex, createRenditionHandler, createRenditionServer };

package/dist/server.mjs

@@ -1,9 +1,9 @@
 import { i as formatExtensions, s as assertInteger } from "./recipe-BavgOq0b.mjs";
-import { s as hashRecipe } from "./url-BAU5GYXC.mjs";
+import { t as hashRecipe } from "./hash-CHipV1N6.mjs";
 import { n as isSafePath } from "./path-hNFUjCbA.mjs";
 import { n as isDeclaredScope } from "./scopes-C1kzqQHz.mjs";
 import { t as RenditionError } from "./error-DViVpVmH.mjs";
-import { t as createRenditionHandler } from "./handler-CPJllrYi.mjs";
+import { t as createRenditionHandler } from "./handler-D5toFJ55.mjs";
 //#region src/server/coordinator.ts
 /** Creates a coordinator that merges concurrent equal requests within the process. */
 function createLocalCoordinator() {
@@ -88,7 +88,7 @@ const MAX_TIMEOUT = 2 ** 31 - 1;
 * @throws {RangeError} When a limit is not an integer in its range, or the processor cannot render a variant of the catalog.
 */
 function createRenditionServer(options) {
-	const { catalog, source, results, processor, resolveSource = resolveUnscoped, onError } = options;
+	const { catalog, source, results, processor, resolveSource = resolveUnscoped, onError, onDegradation } = options;
 	const memory = createMemoryReadinessIndex(options.readiness?.memory);
 	const shared = options.readiness?.shared;
 	const coordinator = options.coordinator ?? createLocalCoordinator();
@@ -148,28 +148,26 @@ function createRenditionServer(options) {
 		try {
 			return await withTimeout(indexTimeout, call);
 		} catch (error) {
-			report(error);
+			notify(onError, error);
 			return;
 		}
 	}
-	/** Passes an error to `onError` without waiting for it, so a failing or hanging callback cannot affect the operation. */
-	function report(error) {
-		try {
-			Promise.resolve(onError?.(error)).catch(() => {});
-		} catch {}
-	}
 	function callStorage(reason, call) {
 		return withTimeout(storageTimeout, call).catch((error) => {
 			throw error instanceof RenditionError ? error : new RenditionError(reason, `Storage call failed: ${error}`, { cause: error });
 		});
 	}
 	async function render(recipe, sourceKey, key) {
-		const data = await callStorage("source-error", (signal) => source.read(sourceKey, { signal }));
-		if (!data) throw new RenditionError("source-not-found", `The source ${sourceKey} does not exist.`);
-		const image = await processor.process(data, recipe).catch((error) => {
+		const input = await callStorage("source-error", (signal) => source.read(sourceKey, { signal }));
+		if (!input) throw new RenditionError("source-not-found", `The source ${sourceKey} does not exist.`);
+		const { data, contentType, degradation } = await processor.process(input, recipe).catch((error) => {
 			throw error instanceof RenditionError ? error : new RenditionError("processing-failed", `Processing failed: ${error}`, { cause: error });
 		});
-		await callStorage("storage-error", (signal) => results.write(key, image, { signal }));
+		await callStorage("storage-error", (signal) => results.write(key, {
+			data,
+			contentType
+		}, { signal }));
+		return degradation;
 	}
 	return {
 		catalog,
@@ -180,7 +178,16 @@ function createRenditionServer(options) {
 			if (await isIndexed(rendition.url)) return rendition;
 			return coordinator.run(rendition.url, async () => {
 				if (!await isIndexed(rendition.url)) {
-					if (!await callStorage("storage-error", (signal) => results.exists(rendition.key, { signal }))) await limiter.run(() => render(recipe, sourceKey, rendition.key));
+					if (!await callStorage("storage-error", (signal) => results.exists(rendition.key, { signal }))) {
+						const degradation = await limiter.run(() => render(recipe, sourceKey, rendition.key));
+						if (degradation) notify(onDegradation, {
+							...degradation,
+							recipe,
+							target,
+							context,
+							rendition: { ...rendition }
+						});
+					}
 					await markPublished(rendition.url);
 				}
 				return rendition;
@@ -193,6 +200,12 @@ function createRenditionServer(options) {
 		resolve
 	};
 }
+/** Calls an optional callback without waiting for it, so a failing or hanging callback cannot affect the operation. */
+function notify(callback, value) {
+	try {
+		Promise.resolve(callback?.(value)).catch(() => {});
+	} catch {}
+}
 /**
 * Runs a call with an abort signal that fires after the timeout.
 *

package/dist/sharp.d.mts

@@ -1,4 +1,4 @@
-import { t as Processor } from "./processor-DvyPs-OZ.mjs";
+import { r as Processor } from "./processor-Dd3jqaOW.mjs";
 //#region src/processors/sharp/processor.d.ts
 /** Options of {@link createSharpProcessor}. */
 export interface SharpProcessorOptions {

package/dist/sharp.mjs

@@ -115,12 +115,13 @@ function createSharpProcessor({ maxInputPixels = 1e8, maxAnimationPixels = 5e7,
 		assertRecipe,
 		async process(source, recipe) {
 			assertRecipe(recipe);
-			const data = await render(source, recipe, maxInputPixels, limits).catch((error) => {
+			const { data, degradation } = await render(source, recipe, maxInputPixels, limits).catch((error) => {
 				throw error instanceof RenditionError ? error : new RenditionError("unsupported-source", "The source cannot be processed.", { cause: error });
 			});
 			return {
 				data: new Uint8Array(data),
-				contentType: formatContentTypes[recipe.format]
+				contentType: formatContentTypes[recipe.format],
+				degradation
 			};
 		}
 	};
@@ -150,7 +151,8 @@ async function render(source, recipe, maxInputPixels, limits) {
 		width = raster.width;
 		height = raster.height;
 	}
-	const frames = keepsAnimation(recipe, metadata, limits) ? {
+	const animation = planAnimation(recipe, metadata, limits);
+	const frames = animation.animated ? {
 		animated: true,
 		limitInputPixels: limits.maxAnimationPixels
 	} : { pages: 1 };
@@ -164,6 +166,12 @@ async function render(source, recipe, maxInputPixels, limits) {
 	if (resize) pipeline = pipeline.resize(resize);
 	if (recipe.format === "jpeg") pipeline = pipeline.flatten({ background: parseColor(recipe.background) });
 	pipeline = pipeline.toColourspace("srgb");
+	return {
+		data: await encode(pipeline, recipe),
+		degradation: animation.degradation
+	};
+}
+function encode(pipeline, recipe) {
 	switch (recipe.format) {
 		case "avif": return pipeline.avif({
 			quality: recipe.quality,
@@ -178,14 +186,26 @@ async function render(source, recipe, maxInputPixels, limits) {
 	}
 }
 /**
-* Whether a rendition keeps the animation of a source, judged by the metadata of its first frame.
+* Plans whether a rendition keeps the animation of a source, judged by the metadata of its first frame.
 *
 * Sharp resizes and crops the frames one by one, so the planned geometry of the first frame applies to every frame.
 */
-function keepsAnimation(recipe, { format, pages = 1, width, height, orientation = 1 }, { maxAnimationPixels, maxFrames }) {
-	if (recipe.animation !== "preserve" || format !== "gif" && format !== "webp" || pages < 2 || orientation !== 1) return false;
+function planAnimation(recipe, { format, pages = 1, width, height, orientation = 1 }, { maxAnimationPixels, maxFrames }) {
+	if (recipe.animation !== "preserve" || format !== "gif" && format !== "webp" || pages < 2) return { animated: false };
+	if (orientation !== 1) return degrade("animation-orientation", `Sharp cannot apply the EXIF orientation ${orientation} to the frames of an animation.`);
+	if (maxFrames > 0 && pages > maxFrames) return degrade("animation-frames", `The animation of ${pages} frames exceeds the frame limit of ${maxFrames}.`);
 	const pixels = Math.max(width * height, estimateRenditionArea(recipe, width, height)) * pages;
-	return (maxFrames === 0 || pages <= maxFrames) && (maxAnimationPixels === 0 || pixels <= maxAnimationPixels);
+	if (maxAnimationPixels > 0 && pixels > maxAnimationPixels) return degrade("animation-pixels", `The animation of ${pixels} pixels exceeds the animation pixel limit of ${maxAnimationPixels}.`);
+	return { animated: true };
+}
+function degrade(reason, message) {
+	return {
+		animated: false,
+		degradation: {
+			reason,
+			message
+		}
+	};
 }
 /**
 * Checks that sharp can keep an animation where a recipe asks for it.

package/dist/{url-BAU5GYXC.mjs → url-C6PtYIEf.mjs}

@@ -1,15 +1,5 @@
-import { i as formatExtensions, o as serializeRecipe } from "./recipe-BavgOq0b.mjs";
+import { i as formatExtensions } from "./recipe-BavgOq0b.mjs";
 import { n as isSafePath, r as isSafeScope, t as encodePath } from "./path-hNFUjCbA.mjs";
-import { sha256 } from "@noble/hashes/sha2.js";
-import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils.js";
-//#region src/hash.ts
-/** Length of a recipe hash in hex digits, which keeps 128 bits of SHA-256. */
-const RECIPE_HASH_LENGTH = 32;
-/** Identifies a recipe by the truncated SHA-256 of its canonical serialization. */
-function hashRecipe(recipe) {
-	return bytesToHex(sha256(utf8ToBytes(serializeRecipe(recipe)))).slice(0, 32);
-}
-//#endregion
 //#region src/url.ts
 /** Version segment of the rendition URL format this library builds and parses. */
 const URL_FORMAT_VERSION = "v1";
@@ -26,7 +16,8 @@ function formatRenditionPath(basePath, { scope, label, hash, format, path }) {
 	const extension = formatExtensions[format];
 	if (!isSafeLabel(label) || !isHash(hash) || !extension) throw new RangeError(`Invalid rendition variant "${label}.${hash}.${extension ?? format}".`);
 	if (!isSafePath(path)) throw new RangeError(`Unsafe rendition source path "${path}".`);
-	return `${basePath}/v1/${scope === void 0 ? "" : `${scope}/`}${label}.${hash}.${extension}/${encodePath(path)}`;
+	const scopePrefix = scope === void 0 ? "" : `${scope}/`;
+	return `${basePath}/${URL_FORMAT_VERSION}/${scopePrefix}${label}.${hash}.${extension}/${encodePath(path)}`;
 }
 /**
 * Parses the path of a rendition URL, ignoring any query string.
@@ -34,7 +25,7 @@ function formatRenditionPath(basePath, { scope, label, hash, format, path }) {
 * Returns `undefined` for a path outside `basePath`, another URL format version, or malformed or unsafe parts.
 */
 function parseRenditionPath(basePath, url) {
-	const prefix = `${basePath}/v1/`;
+	const prefix = `${basePath}/${URL_FORMAT_VERSION}/`;
 	const pathname = url.split("?", 1)[0];
 	if (!pathname.startsWith(prefix)) return;
 	const parts = pathname.slice(prefix.length).split("/");
@@ -67,8 +58,13 @@ const formats = Object.keys(formatExtensions);
 function isSafeLabel(label) {
 	return /^[\w@.-]{1,64}$/.test(label);
 }
+/**
+* Checks that a recipe hash is 1 to 64 ASCII letters, digits, `_` or `-`, which need no encoding in a URL or a storage key.
+*
+* The grammar does not fix the format of hashes, so a hash the catalog cannot produce is looked up as a published rendition instead of making the URL malformed.
+*/
 function isHash(hash) {
-	return hash.length === 32 && /^[\da-f]+$/.test(hash);
+	return /^[\w-]{1,64}$/.test(hash);
 }
 function decodeSegment(segment) {
 	try {
@@ -78,4 +74,4 @@ function decodeSegment(segment) {
 	}
 }
 //#endregion
-export { parseRenditionPath as a, formatRenditionPath as i, URL_FORMAT_VERSION as n, RECIPE_HASH_LENGTH as o, assertBasePath as r, hashRecipe as s, DEFAULT_BASE_PATH as t };
+export { parseRenditionPath as i, assertBasePath as n, formatRenditionPath as r, DEFAULT_BASE_PATH as t };

package/dist/{url-BVH3ZB0F.d.mts → url-DoJdUx9J.d.mts}

@@ -1,7 +1,5 @@
 import { s as RenditionFormat } from "./recipe-BT8D60Qb.mjs";
 //#region src/url.d.ts
-/** Version segment of the rendition URL format this library builds and parses. */
-declare const URL_FORMAT_VERSION = "v1";
 /** Mount path of the rendition handler unless a catalog sets another one. */
 declare const DEFAULT_BASE_PATH = "/_renditions";
 /** Parts of a rendition URL. */
@@ -28,11 +26,5 @@ declare function formatRenditionPath(basePath: string, { scope, label, hash, for
  * Returns `undefined` for a path outside `basePath`, another URL format version, or malformed or unsafe parts.
  */
 declare function parseRenditionPath(basePath: string, url: string): RenditionAddress | undefined;
-/**
- * Checks that a base path is absolute, has no trailing slash and needs no URL encoding.
- *
- * @throws {RangeError} When the base path is invalid.
- */
-declare function assertBasePath(basePath: string): void;
 //#endregion
-export { formatRenditionPath as a, assertBasePath as i, RenditionAddress as n, parseRenditionPath as o, URL_FORMAT_VERSION as r, DEFAULT_BASE_PATH as t };
+export { parseRenditionPath as i, RenditionAddress as n, formatRenditionPath as r, DEFAULT_BASE_PATH as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "image-renditions",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "On-demand image transformations that persist every result to durable storage and keep app servers stateless.",
   "homepage": "https://github.com/IlyaSemenov/image-renditions#readme",
   "bugs": "https://github.com/IlyaSemenov/image-renditions/issues",