image-renditions 0.0.0-stage → 0.2.0

package/dist/index.mjs

@@ -0,0 +1,123 @@
+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 { n as isSafePath, r as isSafeScope, t as encodePath } from "./path-hNFUjCbA.mjs";
+import { t as assertDeclaredScope } from "./scopes-C1kzqQHz.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"];
+/**
+* Validates a catalog and computes the recipe and hash of every preset density.
+*
+* Preset names are only labels: renaming a preset keeps its hashes and thus its stored renditions.
+*
+* @throws {RangeError} When the catalog is invalid.
+*/
+function defineCatalog(definition) {
+	const basePath = definition.basePath ?? "/_renditions";
+	assertBasePath(basePath);
+	const scopes = definition.scopes && Object.freeze([...definition.scopes]);
+	if (scopes) {
+		if (scopes.length === 0) throw new RangeError("Catalog scopes must not be empty.");
+		for (const [index, scope] of scopes.entries()) {
+			if (!isSafeScope(scope)) throw new RangeError(`Invalid rendition scope "${scope}".`);
+			if (scopes.indexOf(scope) !== index) throw new RangeError(`Duplicate rendition scope "${scope}".`);
+		}
+	}
+	const pipeline = definition.pipelineVersion ?? 1;
+	const presets = Object.freeze(Object.keys(definition.presets));
+	const presetsByName = /* @__PURE__ */ new Map();
+	const variantsByHash = /* @__PURE__ */ new Map();
+	for (const preset of presets) {
+		if (!/^[\w-]{1,64}$/.test(preset)) throw new RangeError(`Invalid preset name "${preset}".`);
+		const { densities = [1], originals = [], animation = "first-frame", ...options } = {
+			...definition.defaults,
+			...omitUndefined(definition.presets[preset])
+		};
+		if (densities.length === 0 || new Set(densities).size !== densities.length) throw new RangeError(`Preset "${preset}" must declare unique densities.`);
+		if (!originals.every((extension) => /^[\da-z]+$/.test(extension))) throw new RangeError(`Preset "${preset}" must list original extensions in lowercase and without the dot.`);
+		const sortedDensities = [...densities].sort((a, b) => a - b);
+		const createVariants = (variantOptions, animation) => Object.freeze(sortedDensities.map((density) => {
+			const recipe = wrapRangeError(`preset "${preset}"`, () => normalizeRecipe({
+				options: variantOptions,
+				density,
+				pipeline,
+				policy: definition.sources,
+				animation
+			}));
+			return Object.freeze({
+				preset,
+				density,
+				label: density === 1 ? preset : `${preset}@${density}x`,
+				recipe,
+				hash: hashRecipe(recipe)
+			});
+		}));
+		const variants = createVariants(options, "first-frame");
+		const animatedVariants = animation === "first-frame" ? void 0 : createVariants(options.format === "webp" ? options : {
+			...options,
+			format: "webp",
+			quality: void 0,
+			effort: void 0
+		}, animation);
+		presetsByName.set(preset, {
+			variants,
+			originals: Object.freeze([...originals]),
+			animatedVariants
+		});
+		for (const variant of [...variants, ...animatedVariants ?? []]) if (!variantsByHash.has(variant.hash)) variantsByHash.set(variant.hash, variant);
+	}
+	function getPreset(preset) {
+		const found = presetsByName.get(preset);
+		if (!found) throw new RangeError(`Unknown rendition preset "${preset}".`);
+		return found;
+	}
+	function variants(preset, path) {
+		const { variants, animatedVariants } = getPreset(preset);
+		return animatedVariants && path !== void 0 && hasExtension(path, ANIMATED_EXTENSIONS) ? animatedVariants : variants;
+	}
+	function variant(preset, density = 1, path) {
+		const found = variants(preset, path).find((variant) => variant.density === density);
+		if (!found) throw new RangeError(`Preset "${preset}" has no density ${density}.`);
+		return found;
+	}
+	function formatVariantUrl({ label, hash, recipe }, { scope, path }) {
+		assertDeclaredScope(scopes, scope);
+		return formatRenditionPath(basePath, {
+			scope,
+			label,
+			hash,
+			format: recipe.format,
+			path
+		});
+	}
+	return Object.freeze({
+		basePath,
+		presets,
+		scopes,
+		variants,
+		variant,
+		originals: (preset) => getPreset(preset).originals,
+		isOriginal: (preset, path) => hasExtension(path, getPreset(preset).originals),
+		allVariants: Object.freeze([...variantsByHash.values()]),
+		findVariant: (hash) => variantsByHash.get(hash),
+		url: (preset, target, density) => formatVariantUrl(variant(preset, density, target.path), target),
+		srcset: (preset, target) => variants(preset, target.path).map((variant) => `${formatVariantUrl(variant, target)} ${variant.density}x`).join(", ")
+	});
+}
+/** Whether the extension of a path is in a list of lowercase extensions. */
+function hasExtension(path, extensions) {
+	const extension = /\.([^./]+)$/.exec(path)?.[1]?.toLowerCase();
+	return extension !== void 0 && extensions.includes(extension);
+}
+function omitUndefined(value) {
+	return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== void 0));
+}
+function wrapRangeError(context, fn) {
+	try {
+		return fn();
+	} catch (error) {
+		throw error instanceof RangeError ? new RangeError(`Invalid ${context}: ${error.message}`, { cause: error }) : error;
+	}
+}
+//#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 };

package/dist/nuxt/runtime.d.mts

@@ -0,0 +1,90 @@
+import { a as RenditionTarget, t as Catalog } from "../catalog-D11xkViN.mjs";
+import { PropType } from "vue";
+//#region src/nuxt/runtime.d.ts
+/** Attributes of an `img` element showing a rendition. */
+export interface RenditionImgAttrs {
+  /** Absent for an unsafe path. */
+  src?: string;
+  srcset?: string;
+  width?: number;
+  height?: number;
+}
+/**
+ * Attributes every `<RenditionImg>` renders, such as `{ loading: "lazy", decoding: "async" }`.
+ *
+ * Attributes of an element override them; `src`, `srcset`, `width` and `height` belong to the rendition alone.
+ */
+export type DefaultImgAttrs = Record<string, string | number | boolean> & {
+  src?: never;
+  srcset?: never;
+  width?: never;
+  height?: never;
+};
+/** Options of a rendition URL. */
+export interface RenditionUrlOptions<Scope extends string = string> {
+  /** Scope of the path; defaults to the module's `defaultScope`. */
+  scope?: Scope;
+  /** Density of the variant; defaults to `1`. */
+  density?: number;
+}
+/** Options of {@link createRenditionHelpers}. */
+export interface RenditionHelpersOptions<Scope extends string = string> {
+  /** Scope of calls that set none. */
+  defaultScope?: Scope;
+  /**
+   * Composable returning a function that builds the URL of a source shown as it is; required when a preset lists `originals`.
+   *
+   * The function receives a safe logical path, which it must encode.
+   */
+  useOriginalUrl?: () => (target: RenditionTarget<Scope>) => string;
+  imgAttrs?: DefaultImgAttrs;
+}
+/**
+ * Binds `useRenditions()` and `<RenditionImg>` to a catalog.
+ *
+ * The Nuxt module calls it in a generated module; applications use the generated helpers.
+ *
+ * @throws {Error} When a preset lists `originals` and `useOriginalUrl` is missing.
+ * @throws {RangeError} When `defaultScope` is not one of the scopes the catalog declares, or `imgAttrs` sets a rendition attribute.
+ */
+export declare function createRenditionHelpers<Name extends string, Scope extends string = string>(catalog: Catalog<Name, Scope>, { defaultScope, useOriginalUrl, imgAttrs }?: RenditionHelpersOptions<NoInfer<Scope>>): {
+  useRenditions: () => {
+    url: (preset: Name, path: string, { scope, density }?: RenditionUrlOptions<Scope>) => string | undefined;
+    srcset: (preset: Name, path: string, { scope }?: Pick<RenditionUrlOptions<Scope>, "scope">) => string | undefined;
+    attrs: (preset: Name, path: string, { scope }?: Pick<RenditionUrlOptions<Scope>, "scope">) => RenditionImgAttrs;
+  };
+  RenditionImg: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    preset: {
+      type: PropType<Name>;
+      required: true;
+    };
+    /** Logical source path inside the scope, or a URL shown as is. */
+    src: {
+      type: StringConstructor;
+      required: true;
+    };
+    scope: {
+      type: PropType<Scope>;
+      default: undefined;
+    };
+  }>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+  }>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    preset: {
+      type: PropType<Name>;
+      required: true;
+    };
+    /** Logical source path inside the scope, or a URL shown as is. */
+    src: {
+      type: StringConstructor;
+      required: true;
+    };
+    scope: {
+      type: PropType<Scope>;
+      default: undefined;
+    };
+  }>> & Readonly<{}>, {
+    scope: unknown extends Scope ? keyof Scope extends never ? undefined : Scope : Scope;
+  }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+};
+//#endregion

package/dist/nuxt/runtime.mjs

@@ -0,0 +1,129 @@
+import { n as isSafePath, r as isSafeScope } from "../path-hNFUjCbA.mjs";
+import { n as isDeclaredScope, r as toDeclaredTarget, t as assertDeclaredScope } from "../scopes-C1kzqQHz.mjs";
+import { t as findRenditionAttr } from "../img-attrs-BoCAHpl5.mjs";
+import { useRuntimeConfig } from "nuxt/app";
+import { defineComponent, h } from "vue";
+//#region src/nuxt/runtime.ts
+/**
+* Binds `useRenditions()` and `<RenditionImg>` to a catalog.
+*
+* The Nuxt module calls it in a generated module; applications use the generated helpers.
+*
+* @throws {Error} When a preset lists `originals` and `useOriginalUrl` is missing.
+* @throws {RangeError} When `defaultScope` is not one of the scopes the catalog declares, or `imgAttrs` sets a rendition attribute.
+*/
+function createRenditionHelpers(catalog, { defaultScope, useOriginalUrl, imgAttrs } = {}) {
+	if (!useOriginalUrl && catalog.presets.some((preset) => catalog.originals(preset).length > 0)) throw new Error("[image-renditions] Pass `useOriginalUrl`, as a preset of the catalog lists `originals`.");
+	if (defaultScope !== void 0 && !isDeclaredScope(catalog.scopes, defaultScope)) throw new RangeError(`Undeclared default rendition scope "${defaultScope}".`);
+	const renditionAttr = findRenditionAttr(imgAttrs);
+	if (renditionAttr) throw new RangeError(`Default image attribute "${renditionAttr}" is set by the rendition.`);
+	/** Builds rendition URLs below the application base URL. */
+	function useRenditions() {
+		const base = useRuntimeConfig().app.baseURL.replace(/\/$/, "");
+		const originalUrl = useOriginalUrl?.();
+		/**
+		* Target of a path in the scope of a call, or `undefined` for an unsafe path.
+		*
+		* The scope is checked here because the URL of an original does not go through the rendition URL builder, which checks it too.
+		*/
+		function resolveTarget(path, scope) {
+			if (!isSafePath(path)) return;
+			const resolved = scope ?? defaultScope;
+			if (resolved !== void 0 && !isSafeScope(resolved)) throw new RangeError(`Invalid rendition scope "${resolved}".`);
+			assertDeclaredScope(catalog.scopes, resolved);
+			return toDeclaredTarget(catalog.scopes, resolved, path);
+		}
+		function formatUrl(preset, target, density) {
+			return base + catalog.url(preset, target, density);
+		}
+		function formatSrcset(preset, target) {
+			return catalog.variants(preset).map(({ density }) => `${formatUrl(preset, target, density)} ${density}x`).join(", ");
+		}
+		/**
+		* URL of a rendition of a logical path, or of the source itself at every declared density when the preset lists its extension in `originals`.
+		*
+		* Returns `undefined` for an unsafe path, such as one with a `..` segment, so stored data never breaks rendering.
+		*
+		* @throws {RangeError} When the preset is unknown or does not declare the density, or the scope is invalid or not one the catalog declares.
+		*/
+		function url(preset, path, { scope, density } = {}) {
+			const target = resolveTarget(path, scope);
+			if (!target) return;
+			if (catalog.isOriginal(preset, path)) {
+				catalog.variant(preset, density);
+				return originalUrl(target);
+			}
+			return formatUrl(preset, target, density);
+		}
+		/**
+		* `srcset` attribute value listing every density of a preset.
+		*
+		* Returns `undefined` for an unsafe path, like `url()`, and for a source shown as it is, which has no densities.
+		*
+		* @throws {RangeError} When the preset is unknown, or the scope is invalid or not one the catalog declares.
+		*/
+		function srcset(preset, path, { scope } = {}) {
+			const target = resolveTarget(path, scope);
+			return target && !catalog.isOriginal(preset, path) ? formatSrcset(preset, target) : void 0;
+		}
+		/**
+		* Attributes of an `img` element showing every density of a preset.
+		*
+		* `width` and `height` are set only when the output always has the size of the preset box, so they never distort the image.
+		* A source that is already a URL, such as a `blob:`, `data:` or `https:` one, is returned unchanged as `src`.
+		* A source whose extension the preset lists in `originals` gets only the `src` of the source itself.
+		* An unsafe path, such as one with a `..` segment, yields no `src`, so stored data never breaks rendering.
+		*/
+		function attrs(preset, path, { scope } = {}) {
+			if (/^(?:[a-z][\d+.a-z-]*:|\/\/)/i.test(path)) return { src: path };
+			const target = resolveTarget(path, scope);
+			if (!target) return {};
+			if (catalog.isOriginal(preset, path)) return { src: originalUrl(target) };
+			const { recipe } = catalog.variant(preset);
+			const boxed = recipe.fit === "contain" || (recipe.fit === "cover" || recipe.fit === "fill") && recipe.enlarge;
+			return {
+				src: formatUrl(preset, target),
+				srcset: catalog.variants(preset).length > 1 ? formatSrcset(preset, target) : void 0,
+				width: boxed ? recipe.width : void 0,
+				height: boxed ? recipe.height : void 0
+			};
+		}
+		return {
+			url,
+			srcset,
+			attrs
+		};
+	}
+	return {
+		useRenditions,
+		RenditionImg: defineComponent({
+			name: "RenditionImg",
+			props: {
+				preset: {
+					type: String,
+					required: true
+				},
+				/** Logical source path inside the scope, or a URL shown as is. */
+				src: {
+					type: String,
+					required: true
+				},
+				scope: {
+					type: String,
+					default: void 0
+				}
+			},
+			setup(props) {
+				const renditions = useRenditions();
+				return () => {
+					return h("img", {
+						...imgAttrs,
+						...renditions.attrs(props.preset, props.src, { scope: props.scope })
+					});
+				};
+			}
+		})
+	};
+}
+//#endregion
+export { createRenditionHelpers };

package/dist/nuxt.d.mts

@@ -0,0 +1,31 @@
+import { DefaultImgAttrs } from "./nuxt/runtime.mjs";
+import { NuxtModule } from "nuxt/schema";
+//#region src/nuxt/module.d.ts
+/** Options of the `image-renditions/nuxt` module, under the `renditions` key of the Nuxt config. */
+export interface ModuleOptions {
+  /**
+   * Module whose default export is the catalog, such as `#shared/renditions`.
+   *
+   * It is bundled into both the client and the server, so it must import only the browser-safe `image-renditions` entry.
+   */
+  catalog?: string;
+  /** Module whose default export is the h3 event handler of renditions, mounted at the catalog base path. */
+  handler?: string;
+  /** Scope for `<RenditionImg>` and `useRenditions()`, one of the catalog scopes if it declares them; their `scope` overrides it. */
+  defaultScope?: string;
+  /**
+   * Module whose default export is a composable returning a function that builds the URL of a source shown as it is, such as `~/renditions/original-url`.
+   *
+   * Required when a preset lists `originals`.
+   * The function receives the scope, after `defaultScope`, and a safe logical path, which it must encode.
+   */
+  originalUrl?: string;
+  /** Attributes every `<RenditionImg>` renders, such as `{ loading: "lazy", decoding: "async" }`; attributes of an element override them. */
+  imgAttrs?: DefaultImgAttrs;
+}
+/**
+ * Nuxt module that mounts the rendition handler and provides `useRenditions()` and `<RenditionImg>` typed by the catalog.
+ */
+declare const module: NuxtModule<ModuleOptions>;
+//#endregion
+export { module as default };

package/dist/nuxt.mjs

@@ -0,0 +1,60 @@
+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
+/**
+* Nuxt module that mounts the rendition handler and provides `useRenditions()` and `<RenditionImg>` typed by the catalog.
+*/
+const module = defineNuxtModule({
+	meta: {
+		name: "image-renditions",
+		configKey: "renditions"
+	},
+	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)
+		});
+		const template = addTemplate({
+			filename: "image-renditions.ts",
+			write: true,
+			getContents: () => [
+				`import catalog from ${formatImportSpecifier(catalogPath)}`,
+				...originalUrlPath ? [`import useOriginalUrl from ${formatImportSpecifier(originalUrlPath)}`] : [],
+				`import { createRenditionHelpers } from "image-renditions/nuxt/runtime"`,
+				"",
+				`export const { useRenditions, RenditionImg } = createRenditionHelpers(catalog, {`,
+				`  defaultScope: ${JSON.stringify(defaultScope)},`,
+				`  useOriginalUrl: ${originalUrlPath ? "useOriginalUrl" : "undefined"},`,
+				`  imgAttrs: ${JSON.stringify(imgAttrs)},`,
+				`})`,
+				""
+			].join("\n")
+		});
+		addImports({
+			name: "useRenditions",
+			from: template.dst
+		});
+		addComponent({
+			name: "RenditionImg",
+			export: "RenditionImg",
+			filePath: template.dst
+		});
+	}
+});
+function formatImportSpecifier(path) {
+	return JSON.stringify(path.replace(/\.[cm]?[jt]s$/, ""));
+}
+//#endregion
+export { module as default };

package/dist/path-hNFUjCbA.mjs

@@ -0,0 +1,22 @@
+//#region src/path.ts
+/** Longest accepted logical path or storage key, in UTF-16 code units. */
+const MAX_PATH_LENGTH = 1024;
+/**
+* Checks that a slash-separated path addresses exactly one storage object.
+*
+* Unsafe or ambiguous paths are rejected rather than normalized, so one object never gets several URLs:
+* no leading, trailing or repeated slashes, no `.` or `..` segments, no backslashes, which Windows file systems treat as separators, no NUL characters, which end strings in file system APIs, and no unpaired surrogates, which have no URL encoding.
+*/
+function isSafePath(path) {
+	return path.length > 0 && path.length <= MAX_PATH_LENGTH && !/[\\\u0000]|\p{Cs}/u.test(path) && path.split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}
+/** Percent-encodes each segment of a slash-separated path for use in a URL path. */
+function encodePath(path) {
+	return path.split("/").map(encodeURIComponent).join("/");
+}
+/** Checks that a scope is a short token that needs no URL encoding. */
+function isSafeScope(scope) {
+	return /^[\w-]{1,64}$/.test(scope);
+}
+//#endregion
+export { isSafePath as n, isSafeScope as r, encodePath as t };

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-BT8D60Qb.d.mts

@@ -0,0 +1,104 @@
+//#region src/recipe.d.ts
+/** Output encoding of a rendition. */
+type RenditionFormat = "avif" | "webp" | "jpeg" | "png";
+/**
+ * How a resized source fills a box of both `width` and `height`.
+ *
+ * `cover` crops what overflows, `contain` letterboxes, and `fill` stretches.
+ * `inside` and `outside` keep the aspect ratio, so one side of the output is smaller or larger than the box.
+ */
+type RenditionFit = "cover" | "contain" | "fill" | "inside" | "outside";
+/**
+ * Which part of the source stays in view when `cover` crops it or `contain` letterboxes it.
+ * `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";
+  /** `auto` applies the EXIF orientation before resizing; metadata never reaches the output. */
+  orientation: "auto";
+}
+/** Transformation and encoding parameters, as written in a preset or in catalog defaults. */
+interface RenditionOptions {
+  /** Target width in CSS pixels at density 1. */
+  width?: number;
+  /** Target height in CSS pixels at density 1. */
+  height?: number;
+  /** Applies only when both `width` and `height` are set; defaults to `cover`. */
+  fit?: RenditionFit;
+  /** Applies only to `cover` and `contain`; defaults to `center`. */
+  position?: RenditionPosition;
+  /** Allows upscaling sources smaller than the target box. */
+  enlarge?: boolean;
+  /**
+   * Hex color `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa` for `contain` letterboxing and for flattening transparency into JPEG.
+   * Letterboxing defaults to transparent and JPEG flattening to white.
+   */
+  background?: string;
+  /** Defaults to `avif`. */
+  format?: RenditionFormat;
+  /** Encoder quality from 1 to 100; ignored by `png`. */
+  quality?: number;
+  /** CPU effort of the `avif` (0–9) and `webp` (0–6) encoders. */
+  effort?: number;
+}
+/**
+ * Fully explicit, canonical description of one rendition.
+ *
+ * Fields that cannot affect the output are omitted and applicable defaults are filled in, so equivalent options give equal recipes.
+ */
+interface Recipe {
+  /** Library-owned version of recipe semantics. */
+  readonly engine: number;
+  /** Application-owned version that changes every recipe at once. */
+  readonly pipeline: number;
+  readonly width?: number;
+  readonly height?: number;
+  readonly fit?: RenditionFit;
+  readonly position?: RenditionPosition;
+  readonly enlarge?: boolean;
+  readonly background?: string;
+  readonly format: RenditionFormat;
+  readonly quality?: number;
+  readonly effort?: number;
+  readonly svg: SourcePolicy["svg"];
+  readonly animation: RenditionAnimation;
+  readonly orientation: SourcePolicy["orientation"];
+}
+/** File extension of each output format, used in rendition URLs and storage keys. */
+declare const formatExtensions: Record<RenditionFormat, string>;
+/** MIME type of each output format. */
+declare const formatContentTypes: Record<RenditionFormat, string>;
+/** Library-owned recipe version; bumping it regenerates every rendition of every application. */
+declare const RECIPE_ENGINE_VERSION = 1;
+/** Upper bound of a rendition side in physical pixels; WebP cannot encode larger sides. */
+declare const MAX_DIMENSION = 16383;
+/** Input of {@link normalizeRecipe}. */
+interface RecipeInput {
+  options: RenditionOptions;
+  /** Multiplier from CSS pixels to physical pixels. */
+  density?: number;
+  /** 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, animation }: RecipeInput): Recipe;
+/** Serializes a recipe deterministically: sorted keys, no undefined fields, no whitespace. */
+declare function serializeRecipe(recipe: Recipe): string;
+//#endregion
+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 };