image-renditions 0.1.0 → 0.3.0

package/dist/nuxt.mjs

@@ -1,4 +1,6 @@
 import { r as isSafeScope } from "./path-hNFUjCbA.mjs";
+import { n as isDeclaredScope } from "./scopes-C1kzqQHz.mjs";
+import { t as findRenditionAttr } from "./img-attrs-BoCAHpl5.mjs";
 import { createJiti } from "jiti";
 import { addComponent, addImports, addServerHandler, addTemplate, defineNuxtModule, resolvePath } from "nuxt/kit";
 //#region src/nuxt/module.ts
@@ -10,11 +12,16 @@ const module = defineNuxtModule({
 		name: "image-renditions",
 		configKey: "renditions"
 	},
-	async setup({ catalog: catalogModule, handler, defaultScope }, nuxt) {
+	async setup({ catalog: catalogModule, handler, defaultScope, originalUrl, imgAttrs }, nuxt) {
 		if (!catalogModule) throw new Error("[image-renditions] Set `renditions.catalog` to the module exporting the catalog.");
 		if (defaultScope !== void 0 && !isSafeScope(defaultScope)) throw new Error(`[image-renditions] Invalid default scope "${defaultScope}".`);
+		const renditionAttr = findRenditionAttr(imgAttrs);
+		if (renditionAttr) throw new Error(`[image-renditions] \`imgAttrs\` cannot set \`${renditionAttr}\`, which the rendition sets.`);
 		const catalogPath = await resolvePath(catalogModule);
 		const catalog = await createJiti(nuxt.options.rootDir, { alias: nuxt.options.alias }).import(catalogPath, { default: true });
+		if (defaultScope !== void 0 && !isDeclaredScope(catalog.scopes, defaultScope)) throw new Error(`[image-renditions] The default scope "${defaultScope}" is not one of the catalog scopes.`);
+		if (!originalUrl && catalog.presets.some((preset) => catalog.originals(preset).length > 0)) throw new Error("[image-renditions] Set `renditions.originalUrl` to the module building URLs of originals, as a preset of the catalog lists `originals`.");
+		const originalUrlPath = originalUrl && await resolvePath(originalUrl);
 		if (handler) addServerHandler({
 			route: `${catalog.basePath}/**`,
 			handler: await resolvePath(handler)
@@ -23,10 +30,15 @@ const module = defineNuxtModule({
 			filename: "image-renditions.ts",
 			write: true,
 			getContents: () => [
-				`import catalog from ${JSON.stringify(catalogPath.replace(/\.[cm]?[jt]s$/, ""))}`,
+				`import catalog from ${formatImportSpecifier(catalogPath)}`,
+				...originalUrlPath ? [`import useOriginalUrl from ${formatImportSpecifier(originalUrlPath)}`] : [],
 				`import { createRenditionHelpers } from "image-renditions/nuxt/runtime"`,
 				"",
-				`export const { useRenditions, RenditionImg } = createRenditionHelpers(catalog, ${JSON.stringify(defaultScope)})`,
+				`export const { useRenditions, RenditionImg } = createRenditionHelpers(catalog, {`,
+				`  defaultScope: ${JSON.stringify(defaultScope)},`,
+				`  useOriginalUrl: ${originalUrlPath ? "useOriginalUrl" : "undefined"},`,
+				`  imgAttrs: ${JSON.stringify(imgAttrs)},`,
+				`})`,
 				""
 			].join("\n")
 		});
@@ -41,5 +53,8 @@ const module = defineNuxtModule({
 		});
 	}
 });
+function formatImportSpecifier(path) {
+	return JSON.stringify(path.replace(/\.[cm]?[jt]s$/, ""));
+}
 //#endregion
 export { module as default };

package/dist/processor-DvyPs-OZ.d.mts

@@ -0,0 +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
+/** Renders a source image according to a recipe. */
+interface Processor {
+  /**
+   * Renders the source.
+   *
+   * 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>;
+  /**
+   * Checks that the processor renders a recipe as it describes.
+   *
+   * `createRenditionServer()` checks every variant of its catalog with it, and `ensure()` every recipe it gets.
+   *
+   * @throws {RangeError} When the processor cannot render the recipe, such as an animation in a format it cannot encode.
+   */
+  assertRecipe?(recipe: Recipe): void;
+}
+//#endregion
+export { Processor as t };

package/dist/{recipe-Je9DxqO1.d.mts → recipe-BT8D60Qb.d.mts}

@@ -13,12 +13,16 @@ type RenditionFit = "cover" | "contain" | "fill" | "inside" | "outside";
  * `entropy` and `attention` choose the crop by content and apply to `cover` only.
  */
 type RenditionPosition = "center" | "top" | "bottom" | "left" | "right" | "entropy" | "attention";
+/**
+ * How a rendition shows an animated source.
+ *
+ * `first-frame` renders its first frame as a still image, and `preserve` keeps the animation.
+ */
+type RenditionAnimation = "first-frame" | "preserve";
 /** How sources of a special kind are turned into a rendition. */
 interface SourcePolicy {
   /** `rasterize` renders vector sources at the resolution the output needs. */
   svg: "rasterize";
-  /** `first-frame` renders animated sources as a still image of their first frame. */
-  animation: "first-frame";
   /** `auto` applies the EXIF orientation before resizing; metadata never reaches the output. */
   orientation: "auto";
 }
@@ -66,7 +70,7 @@ interface Recipe {
   readonly quality?: number;
   readonly effort?: number;
   readonly svg: SourcePolicy["svg"];
-  readonly animation: SourcePolicy["animation"];
+  readonly animation: RenditionAnimation;
   readonly orientation: SourcePolicy["orientation"];
 }
 /** File extension of each output format, used in rendition URLs and storage keys. */
@@ -85,14 +89,16 @@ interface RecipeInput {
   /** Application-owned pipeline version. */
   pipeline: number;
   policy?: Partial<SourcePolicy>;
+  /** Defaults to `first-frame`. */
+  animation?: RenditionAnimation;
 }
 /**
  * Builds the canonical recipe for transformation options at a density.
  *
  * @throws {RangeError} When an option is out of range or inconsistent.
  */
-declare function normalizeRecipe({ options, density, pipeline, policy }: RecipeInput): Recipe;
+declare function normalizeRecipe({ options, density, pipeline, policy, animation }: RecipeInput): Recipe;
 /** Serializes a recipe deterministically: sorted keys, no undefined fields, no whitespace. */
 declare function serializeRecipe(recipe: Recipe): string;
 //#endregion
-export { RenditionFit as a, RenditionPosition as c, formatExtensions as d, normalizeRecipe as f, RecipeInput as i, SourcePolicy as l, RECIPE_ENGINE_VERSION as n, RenditionFormat as o, serializeRecipe as p, Recipe as r, RenditionOptions as s, MAX_DIMENSION as t, formatContentTypes as u };
+export { RenditionAnimation as a, RenditionOptions as c, formatContentTypes as d, formatExtensions as f, RecipeInput as i, RenditionPosition as l, serializeRecipe as m, RECIPE_ENGINE_VERSION as n, RenditionFit as o, normalizeRecipe as p, Recipe as r, RenditionFormat as s, MAX_DIMENSION as t, SourcePolicy as u };

package/dist/{recipe-DmOhQJWE.mjs → recipe-BavgOq0b.mjs}

@@ -25,9 +25,9 @@ const RECIPE_ENGINE_VERSION = 1;
 const MAX_DIMENSION = 16383;
 const defaultSourcePolicy = {
 	svg: "rasterize",
-	animation: "first-frame",
 	orientation: "auto"
 };
+const animations = ["first-frame", "preserve"];
 const formats = [
 	"avif",
 	"webp",
@@ -74,11 +74,12 @@ const effortRange = {
 *
 * @throws {RangeError} When an option is out of range or inconsistent.
 */
-function normalizeRecipe({ options, density = 1, pipeline, policy }) {
+function normalizeRecipe({ options, density = 1, pipeline, policy, animation = "first-frame" }) {
 	assertInteger("pipeline", pipeline, 0, Number.MAX_SAFE_INTEGER);
 	if (!(Number.isFinite(density) && density > 0)) throw new RangeError(`Invalid density ${density}.`);
 	const format = options.format ?? "avif";
 	assertOneOf("format", format, formats);
+	assertOneOf("animation", animation, animations);
 	if (options.fit !== void 0) assertOneOf("fit", options.fit, fits);
 	if (options.position !== void 0) assertOneOf("position", options.position, positions);
 	const color = options.background === void 0 ? void 0 : normalizeColor(options.background);
@@ -105,16 +106,16 @@ function normalizeRecipe({ options, density = 1, pipeline, policy }) {
 		format,
 		quality: format === "png" ? void 0 : options.quality ?? defaultQuality[format],
 		effort: range ? options.effort ?? range.default : void 0,
-		svg: policyValue("svg", policy, ["rasterize"]),
-		animation: policyValue("animation", policy, ["first-frame"]),
-		orientation: policyValue("orientation", policy, ["auto"])
+		svg: resolvePolicyValue("svg", policy, ["rasterize"]),
+		animation,
+		orientation: resolvePolicyValue("orientation", policy, ["auto"])
 	});
 }
 /** Serializes a recipe deterministically: sorted keys, no undefined fields, no whitespace. */
 function serializeRecipe(recipe) {
 	return JSON.stringify(Object.fromEntries(Object.entries(recipe).filter(([, value]) => value !== void 0).sort(([a], [b]) => a < b ? -1 : 1)));
 }
-function policyValue(name, policy, allowed) {
+function resolvePolicyValue(name, policy, allowed) {
 	const value = policy?.[name] ?? defaultSourcePolicy[name];
 	assertOneOf(name, value, allowed);
 	return value;

package/dist/s3.d.mts

@@ -1,43 +1,18 @@
-import { n as ResultStore, r as SourceStore } from "./stores-DFDRMZcC.mjs";
+import { n as ResultStore, r as SourceStore } from "./stores-P-TUmax4.mjs";
+import { S3Client } from "@aws-sdk/client-s3";
 //#region src/stores/s3.d.ts
-/** Per-call options of the S3 client methods. */
-interface S3CallOptions {
-  abortSignal?: AbortSignal;
-}
-/** Location of an S3 object. */
-interface S3ObjectInput {
-  Bucket: string;
-  Key: string;
-}
-/**
- * Subset of an S3 client used by the S3 stores.
- *
- * The aggregated `S3` client of AWS SDK v3 (`@aws-sdk/client-s3`) satisfies it as is; other clients need a thin wrapper.
- */
-export interface S3ClientLike {
-  getObject(input: S3ObjectInput, options?: S3CallOptions): Promise<{
-    Body?: {
-      transformToWebStream(): ReadableStream<Uint8Array>;
-    };
-    ContentLength?: number;
-  }>;
-  headObject(input: S3ObjectInput, options?: S3CallOptions): Promise<unknown>;
-  putObject(input: S3ObjectInput & {
-    Body: Uint8Array;
-    ContentType: string;
-    CacheControl: string;
-  }, options?: S3CallOptions): Promise<unknown>;
-}
 /** Options of {@link createS3Source}. */
 export interface S3SourceOptions {
-  client: S3ClientLike;
+  /** Client of AWS SDK v3, such as `S3Client` or the aggregated `S3`. */
+  client: Pick<S3Client, "send">;
   bucket: string;
-  /** Largest source object, in bytes; larger sources are unsupported. */
+  /** Largest source object, in bytes; larger sources fail as too large. */
   maxBytes?: number;
 }
 /** Options of {@link createS3Results}. */
 export interface S3ResultsOptions {
-  client: S3ClientLike;
+  /** Client of AWS SDK v3, such as `S3Client` or the aggregated `S3`. */
+  client: Pick<S3Client, "send">;
   bucket: string;
   /** Public URL of the bucket root, such as `https://storage.example.com/bucket`; objects must be publicly readable. */
   publicUrl: string;
@@ -48,5 +23,4 @@ export interface S3ResultsOptions {
 export declare function createS3Source({ client, bucket, maxBytes }: S3SourceOptions): SourceStore;
 /** Creates a result store writing objects to an S3 bucket that serves them publicly. */
 export declare function createS3Results({ client, bucket, publicUrl, cacheControl }: S3ResultsOptions): ResultStore;
-//#endregion
-export {};
+//#endregion

package/dist/s3.mjs

@@ -1,5 +1,6 @@
 import { t as encodePath } from "./path-hNFUjCbA.mjs";
 import { t as RenditionError } from "./error-DViVpVmH.mjs";
+import { GetObjectCommand, HeadObjectCommand, PutObjectCommand } from "@aws-sdk/client-s3";
 //#region src/stores/s3.ts
 /** Longest S3 object key, in UTF-8 bytes. */
 const MAX_KEY_BYTES = 1024;
@@ -9,12 +10,12 @@ function createS3Source({ client, bucket, maxBytes = 52428800 }) {
 	return { async read(key, { signal }) {
 		if (!fitsKeyLimit(key)) return;
 		const controller = new AbortController();
-		const output = await client.getObject({
+		const output = await client.send(new GetObjectCommand({
 			Bucket: bucket,
 			Key: key
-		}, { abortSignal: AbortSignal.any([signal, controller.signal]) }).catch(ignoreNotFound);
+		}), { abortSignal: AbortSignal.any([signal, controller.signal]) }).catch(ignoreNotFound);
 		if (!output?.Body) return;
-		const tooLarge = new RenditionError("unsupported-source", `The source ${key} exceeds ${maxBytes} bytes.`);
+		const tooLarge = new RenditionError("source-too-large", `The source ${key} exceeds ${maxBytes} bytes.`);
 		if ((output.ContentLength ?? 0) > maxBytes) {
 			controller.abort();
 			throw tooLarge;
@@ -45,20 +46,20 @@ function createS3Results({ client, bucket, publicUrl, cacheControl = "public, ma
 	return {
 		async exists(key, { signal }) {
 			assertKeyLimit(key);
-			return await client.headObject({
+			return await client.send(new HeadObjectCommand({
 				Bucket: bucket,
 				Key: key
-			}, { abortSignal: signal }).catch(ignoreNotFound) !== void 0;
+			}), { abortSignal: signal }).catch(ignoreNotFound) !== void 0;
 		},
 		async write(key, { data, contentType }, { signal }) {
 			assertKeyLimit(key);
-			await client.putObject({
+			await client.send(new PutObjectCommand({
 				Bucket: bucket,
 				Key: key,
 				Body: data,
 				ContentType: contentType,
 				CacheControl: cacheControl
-			}, { abortSignal: signal });
+			}), { abortSignal: signal });
 		},
 		url: (key) => `${publicUrl.replace(/\/$/, "")}/${encodePath(key)}`
 	};

package/dist/scopes-C1kzqQHz.mjs

@@ -0,0 +1,22 @@
+//#region src/scopes.ts
+/** Checks that a target has a scope the catalog declares; a catalog without scopes accepts any. */
+function isDeclaredScope(scopes, scope) {
+	return !scopes || scope !== void 0 && scopes.includes(scope);
+}
+/**
+* Throws a `RangeError` unless a target has a scope the catalog declares.
+*
+* @throws {RangeError} When the scope is missing or not declared.
+*/
+function assertDeclaredScope(scopes, scope) {
+	if (!isDeclaredScope(scopes, scope)) throw new RangeError(scope === void 0 ? "Missing rendition scope." : `Undeclared rendition scope "${scope}".`);
+}
+/** Target of a scope and a path, typed by the scopes of the catalog, or `undefined` when the catalog does not declare the scope. */
+function toDeclaredTarget(scopes, scope, path) {
+	return isDeclaredScope(scopes, scope) ? {
+		scope,
+		path
+	} : void 0;
+}
+//#endregion
+export { isDeclaredScope as n, toDeclaredTarget as r, assertDeclaredScope 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-BFV_vIr4.mjs";
-import { i as StoreCallOptions, n as ResultStore, r as SourceStore, t as EncodedImage } from "./stores-DFDRMZcC.mjs";
-import { t as Processor } from "./processor-_xuwB7Aa.mjs";
+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-RAQFWtrg.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 };

package/dist/server.mjs

@@ -1,8 +1,9 @@
-import { i as formatExtensions, s as assertInteger } from "./recipe-DmOhQJWE.mjs";
-import { s as hashRecipe } from "./url-BIvAw2BR.mjs";
+import { i as formatExtensions, s as assertInteger } from "./recipe-BavgOq0b.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-BHMwNZnI.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() {
@@ -84,10 +85,10 @@ const MAX_TIMEOUT = 2 ** 31 - 1;
 /**
 * Creates a rendition server over source and result stores.
 *
-* @throws {RangeError} When a limit is not an integer in its range.
+* @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 { source, results, processor, resolveSource = resolveUnscoped, onError } = options;
+	const { catalog, source, results, processor, resolveSource = resolveUnscoped, onError } = options;
 	const memory = createMemoryReadinessIndex(options.readiness?.memory);
 	const shared = options.readiness?.shared;
 	const coordinator = options.coordinator ?? createLocalCoordinator();
@@ -102,13 +103,29 @@ function createRenditionServer(options) {
 		queueSize,
 		queueTimeout
 	});
-	async function locate(hash, format, target, context) {
+	for (const variant of catalog.allVariants) try {
+		processor.assertRecipe?.(variant.recipe);
+	} catch (error) {
+		throw error instanceof RangeError ? new RangeError(`The processor cannot render "${variant.label}": ${error.message}`, { cause: error }) : error;
+	}
+	async function resolve(target, context) {
+		if (!isDeclaredScope(catalog.scopes, target.scope)) throw new RenditionError("invalid-request", `The scope of the target ${describe(target)} is not declared.`);
 		const resolution = await resolveSource(target, context);
 		if (!resolution) throw new RenditionError("invalid-request", `The target ${describe(target)} is not served.`);
-		const key = `${resolution.resultPrefix ?? resolution.sourceKey}/${hash}.${formatExtensions[format]}`;
-		if (!isSafePath(resolution.sourceKey) || !isSafePath(key)) throw new RenditionError("invalid-request", `The target ${describe(target)} resolves to an unsafe key.`);
+		const { sourceKey } = resolution;
+		const resultPrefix = resolution.resultPrefix ?? sourceKey;
+		if (!isSafePath(sourceKey) || !isSafePath(resultPrefix)) throw createUnsafeKeyError(target);
 		return {
-			sourceKey: resolution.sourceKey,
+			sourceKey,
+			resultPrefix
+		};
+	}
+	async function locate(hash, format, target, context) {
+		const { sourceKey, resultPrefix } = await resolve(target, context);
+		const key = `${resultPrefix}/${hash}.${formatExtensions[format]}`;
+		if (!isSafePath(key)) throw createUnsafeKeyError(target);
+		return {
+			sourceKey,
 			rendition: {
 				key,
 				url: results.url(key)
@@ -141,27 +158,29 @@ function createRenditionServer(options) {
 			Promise.resolve(onError?.(error)).catch(() => {});
 		} catch {}
 	}
-	function storageCall(reason, call) {
+	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 storageCall("source-error", (signal) => source.read(sourceKey, { signal }));
+		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) => {
 			throw error instanceof RenditionError ? error : new RenditionError("processing-failed", `Processing failed: ${error}`, { cause: error });
 		});
-		await storageCall("storage-error", (signal) => results.write(key, image, { signal }));
+		await callStorage("storage-error", (signal) => results.write(key, image, { signal }));
 	}
 	return {
+		catalog,
 		async ensure(input, target, context) {
 			const recipe = Object.freeze({ ...input });
+			processor.assertRecipe?.(recipe);
 			const { sourceKey, rendition } = await locate(hashRecipe(recipe), recipe.format, target, context);
 			if (await isIndexed(rendition.url)) return rendition;
 			return coordinator.run(rendition.url, async () => {
 				if (!await isIndexed(rendition.url)) {
-					if (!await storageCall("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 }))) await limiter.run(() => render(recipe, sourceKey, rendition.key));
 					await markPublished(rendition.url);
 				}
 				return rendition;
@@ -170,7 +189,8 @@ function createRenditionServer(options) {
 		async findPublished(hash, format, target, context) {
 			const { rendition } = await locate(hash, format, target, context);
 			return await isIndexed(rendition.url) ? rendition : void 0;
-		}
+		},
+		resolve
 	};
 }
 /**
@@ -191,5 +211,8 @@ function resolveUnscoped({ scope, path }) {
 function describe({ scope, path }) {
 	return scope === void 0 ? path : `${scope}:${path}`;
 }
+function createUnsafeKeyError(target) {
+	return new RenditionError("invalid-request", `The target ${describe(target)} resolves to an unsafe key.`);
+}
 //#endregion
 export { RenditionError, createLocalCoordinator, createMemoryReadinessIndex, createRenditionHandler, createRenditionServer };

package/dist/sharp.d.mts

@@ -1,10 +1,22 @@
-import { t as Processor } from "./processor-_xuwB7Aa.mjs";
+import { t as Processor } from "./processor-DvyPs-OZ.mjs";
 //#region src/processors/sharp/processor.d.ts
 /** Options of {@link createSharpProcessor}. */
 export interface SharpProcessorOptions {
-  /** Largest decoded source, in pixels; larger sources are unsupported. */
+  /** Largest decoded source, in pixels; larger sources fail as too large, and `0` removes the limit. */
   maxInputPixels?: number;
+  /**
+   * Largest animation a recipe keeps, in pixels of all its frames at the larger of the source and the rendition size; `0` removes the limit.
+   *
+   * A larger animation renders its first frame.
+   */
+  maxAnimationPixels?: number;
+  /** Most frames of an animation a recipe keeps; an animation with more renders its first frame, and `0` removes the limit. */
+  maxFrames?: number;
 }
-/** Creates a processor backed by sharp and libvips. */
-export declare function createSharpProcessor({ maxInputPixels }?: SharpProcessorOptions): Processor;
+/**
+ * Creates a processor backed by sharp and libvips.
+ *
+ * @throws {RangeError} When a limit is not a non-negative integer.
+ */
+export declare function createSharpProcessor({ maxInputPixels, maxAnimationPixels, maxFrames }?: SharpProcessorOptions): Processor;
 //#endregion

package/dist/sharp.mjs

@@ -1,4 +1,4 @@
-import { r as formatContentTypes, t as MAX_DIMENSION } from "./recipe-DmOhQJWE.mjs";
+import { r as formatContentTypes, s as assertInteger, t as MAX_DIMENSION } from "./recipe-BavgOq0b.mjs";
 import { t as RenditionError } from "./error-DViVpVmH.mjs";
 import sharp from "sharp";
 //#region src/processors/sharp/resize.ts
@@ -18,7 +18,7 @@ function planResize(recipe, width, height) {
 		withoutEnlargement: !recipe.enlarge
 	};
 	const sized = recipe.width !== void 0 || recipe.height !== void 0;
-	const scale = resizeScale(recipe, width, height) ?? 1;
+	const scale = computeResizeScale(recipe, width, height) ?? 1;
 	const factor = recipe.enlarge ? scale : Math.min(scale, 1);
 	const longest = Math.max(width, height);
 	if (Math.round(longest * factor) <= 16383 || recipe.fit === "fill") return { resize: sized ? options : void 0 };
@@ -66,60 +66,98 @@ function planResize(recipe, width, height) {
 * Returns `undefined` when the recipe sets no size or the source size is unknown.
 * For `fill`, it is the factor of the side that needs more scaling.
 */
-function resizeScale({ width, height, fit }, sourceWidth, sourceHeight) {
+function computeResizeScale({ width, height, fit }, sourceWidth, sourceHeight) {
 	const scales = [width && sourceWidth ? width / sourceWidth : void 0, height && sourceHeight ? height / sourceHeight : void 0].filter((scale) => scale !== void 0);
 	if (scales.length === 0) return;
 	return fit === "inside" || fit === "contain" ? Math.min(...scales) : Math.max(...scales);
 }
+/**
+* Estimates an upper bound of the rendition area of a source of the given size, in pixels.
+*
+* `contain` pads the image to the box, `cover`, `fill` and `inside` keep each side within the box, and other recipes keep the scaled size of the source.
+*/
+function estimateRenditionArea(recipe, width, height) {
+	if (recipe.fit === "contain") return recipe.width * recipe.height;
+	const scale = computeResizeScale(recipe, width, height) ?? 1;
+	const factor = recipe.enlarge ? scale : Math.min(scale, 1);
+	const scaledWidth = Math.ceil(width * factor);
+	const scaledHeight = Math.ceil(height * factor);
+	return recipe.fit === void 0 || recipe.fit === "outside" ? scaledWidth * scaledHeight : Math.min(scaledWidth, recipe.width) * Math.min(scaledHeight, recipe.height);
+}
 /** Converts a normalized `#rrggbbaa` color to the form sharp accepts. */
 function parseColor(color) {
-	const channel = (index) => Number.parseInt(color.slice(1 + index * 2, 3 + index * 2), 16);
+	const parseChannel = (index) => Number.parseInt(color.slice(1 + index * 2, 3 + index * 2), 16);
 	return {
-		r: channel(0),
-		g: channel(1),
-		b: channel(2),
-		alpha: channel(3) / 255
+		r: parseChannel(0),
+		g: parseChannel(1),
+		b: parseChannel(2),
+		alpha: parseChannel(3) / 255
 	};
 }
 //#endregion
 //#region src/processors/sharp/processor.ts
 /** Rasterization density SVG renders at when no scaling is needed, in DPI. */
 const SVG_BASE_DENSITY = 72;
-/** Creates a processor backed by sharp and libvips. */
-function createSharpProcessor({ maxInputPixels = 1e8 } = {}) {
-	return { async process(source, recipe) {
-		const data = await render(source, recipe, maxInputPixels).catch((error) => {
-			throw new RenditionError("unsupported-source", "The source cannot be processed.", { cause: error });
-		});
-		return {
-			data: new Uint8Array(data),
-			contentType: formatContentTypes[recipe.format]
-		};
-	} };
+/**
+* Creates a processor backed by sharp and libvips.
+*
+* @throws {RangeError} When a limit is not a non-negative integer.
+*/
+function createSharpProcessor({ maxInputPixels = 1e8, maxAnimationPixels = 5e7, maxFrames = 1e3 } = {}) {
+	assertInteger("maxInputPixels", maxInputPixels, 0, Number.MAX_SAFE_INTEGER);
+	assertInteger("maxAnimationPixels", maxAnimationPixels, 0, Number.MAX_SAFE_INTEGER);
+	assertInteger("maxFrames", maxFrames, 0, Number.MAX_SAFE_INTEGER);
+	const limits = {
+		maxAnimationPixels,
+		maxFrames
+	};
+	return {
+		assertRecipe,
+		async process(source, recipe) {
+			assertRecipe(recipe);
+			const data = 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]
+			};
+		}
+	};
 }
-async function render(source, recipe, maxInputPixels) {
+async function render(source, recipe, maxInputPixels, limits) {
 	const input = {
 		failOn: "error",
 		limitInputPixels: maxInputPixels
 	};
-	const metadata = await sharp(source, input).metadata();
+	const metadata = await sharp(source, {
+		...input,
+		limitInputPixels: false
+	}).metadata();
+	assertPixels(metadata.width, metadata.height, maxInputPixels);
 	let { width, height } = metadata.autoOrient;
 	let density;
 	if (metadata.format === "svg") {
-		const needed = resizeScale(recipe, width, height) ?? 1;
+		const needed = computeResizeScale(recipe, width, height) ?? 1;
 		const scale = recipe.fit === "cover" || recipe.fit === "fill" ? needed : Math.min(needed, MAX_DIMENSION / Math.max(width, height, 1));
 		density = Math.min(Math.max(SVG_BASE_DENSITY * scale, 1), 1e5);
 		const raster = (await sharp(source, {
 			...input,
-			density
+			density,
+			limitInputPixels: false
 		}).metadata()).autoOrient;
+		assertPixels(raster.width, raster.height, maxInputPixels);
 		width = raster.width;
 		height = raster.height;
 	}
+	const frames = keepsAnimation(recipe, metadata, limits) ? {
+		animated: true,
+		limitInputPixels: limits.maxAnimationPixels
+	} : { pages: 1 };
 	let pipeline = sharp(source, {
 		...input,
 		density,
-		pages: 1
+		...frames
 	}).autoOrient();
 	const { extract, resize } = planResize(recipe, width, height);
 	if (extract) pipeline = pipeline.extract(extract);
@@ -139,5 +177,29 @@ async function render(source, recipe, maxInputPixels) {
 		case "png": return pipeline.png().toBuffer();
 	}
 }
+/**
+* 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;
+	const pixels = Math.max(width * height, estimateRenditionArea(recipe, width, height)) * pages;
+	return (maxFrames === 0 || pages <= maxFrames) && (maxAnimationPixels === 0 || pixels <= maxAnimationPixels);
+}
+/**
+* Checks that sharp can keep an animation where a recipe asks for it.
+*
+* @throws {RangeError} When the recipe keeps an animation in a format other than `webp` or crops it by content.
+*/
+function assertRecipe({ animation, format, position }) {
+	if (animation !== "preserve") return;
+	if (format !== "webp") throw new RangeError(`Animations cannot be encoded as ${format}.`);
+	if (position === "entropy" || position === "attention") throw new RangeError(`Position "${position}" cannot crop an animation.`);
+}
+/** Fails as `source-too-large` when an image of the size exceeds the pixel limit, unless the limit is `0`. */
+function assertPixels(width, height, maxInputPixels) {
+	if (maxInputPixels > 0 && width * height > maxInputPixels) throw new RenditionError("source-too-large", `The source of ${width}×${height} pixels exceeds the limit of ${maxInputPixels}.`);
+}
 //#endregion
 export { createSharpProcessor };

package/dist/{stores-DFDRMZcC.d.mts → stores-P-TUmax4.d.mts}

@@ -20,7 +20,7 @@ interface SourceStore {
    * Reads a source object.
    *
    * Resolves to `undefined` when the object does not exist.
-   * Rejects with a `RenditionError` of reason `unsupported-source` when the object exceeds a size limit.
+   * Rejects with a `RenditionError` of reason `source-too-large` when the object exceeds a size limit.
    */
   read(key: string, options: StoreCallOptions): Promise<Uint8Array | undefined>;
 }