image-renditions 0.1.0 → 0.3.0

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

@@ -1,4 +1,5 @@
-import { a as parseRenditionPath } from "./url-BIvAw2BR.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 = {
@@ -6,6 +7,7 @@ const failureStatus = {
 	"unknown-recipe": 404,
 	"source-not-found": 404,
 	"unsupported-source": 422,
+	"source-too-large": 422,
 	"source-error": 502,
 	"processing-failed": 500,
 	"storage-error": 502,
@@ -17,12 +19,14 @@ const failureStatus = {
 * A hash from the catalog is rendered on demand.
 * An unknown hash is served only when the readiness indexes know its rendition, so arbitrary hashes cost no storage calls.
 */
-function createRenditionHandler({ catalog, server, onFailure, redirectCacheControl = "public, max-age=86400" }) {
-	async function fail(error, address, getContext) {
+function createRenditionHandler({ server, onFailure, redirectCacheControl = "public, max-age=86400" }) {
+	const { catalog } = server;
+	async function fail(error, address, target, getContext) {
 		const response = (onFailure && await onFailure({
 			reason: error.reason,
 			error,
 			address,
+			target,
 			context: await getContext()
 		})) ?? new Response(error.reason, {
 			status: failureStatus[error.reason],
@@ -48,14 +52,12 @@ function createRenditionHandler({ catalog, server, onFailure, redirectCacheContr
 			}
 		});
 		const address = parseRenditionPath(catalog.basePath, path);
-		if (!address) return fail(new RenditionError("invalid-request", "Malformed rendition URL."), void 0, getContext);
+		if (!address) return fail(new RenditionError("invalid-request", "Malformed rendition URL."), void 0, void 0, getContext);
+		const target = toDeclaredTarget(catalog.scopes, address.scope, address.path);
+		if (!target) return fail(new RenditionError("invalid-request", address.scope === void 0 ? "The URL has no scope." : `The scope ${address.scope} is not declared.`), address, void 0, getContext);
 		const variant = catalog.findVariant(address.hash);
-		if (variant && variant.recipe.format !== address.format) return fail(new RenditionError("invalid-request", "The extension does not match the recipe format."), address, getContext);
+		if (variant && variant.recipe.format !== address.format) return fail(new RenditionError("invalid-request", "The extension does not match the recipe format."), address, target, getContext);
 		const context = await getContext();
-		const target = {
-			scope: address.scope,
-			path: address.path
-		};
 		try {
 			const rendition = variant ? await server.ensure(variant.recipe, target, context) : await server.findPublished(address.hash, address.format, target, context);
 			if (!rendition) throw new RenditionError("unknown-recipe", `Unknown recipe ${address.hash}.`);
@@ -67,7 +69,7 @@ function createRenditionHandler({ catalog, server, onFailure, redirectCacheContr
 				}
 			});
 		} catch (error) {
-			if (error instanceof RenditionError) return fail(error, address, () => context);
+			if (error instanceof RenditionError) return fail(error, address, target, () => context);
 			throw error;
 		}
 	};

package/dist/{handler-BFV_vIr4.d.mts → handler-RAQFWtrg.d.mts}

@@ -1,8 +1,8 @@
-import { o as RenditionFormat, r as Recipe } from "./recipe-Je9DxqO1.mjs";
-import { i as RenditionTarget, t as Catalog } from "./catalog-CSnosQ1L.mjs";
-import { n as RenditionAddress } from "./url-BByyAbmB.mjs";
-import { i as StoreCallOptions, n as ResultStore, r as SourceStore } from "./stores-DFDRMZcC.mjs";
-import { t as Processor } from "./processor-_xuwB7Aa.mjs";
+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-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";
 //#region src/server/error.d.ts
 /** Why a rendition could not be served. */
 type RenditionFailureReason =
@@ -10,8 +10,10 @@ type RenditionFailureReason =
 "invalid-request" |
 /** The recipe hash is not in the catalog, and no rendition with it is known to be published. */
 "unknown-recipe" | "source-not-found" |
-/** The source cannot be decoded or rendered, or exceeds a size limit. */
+/** The source cannot be decoded or processed. */
 "unsupported-source" |
+/** The source exceeds a byte or pixel limit. */
+"source-too-large" |
 /** Reading the source failed for a reason other than its absence. */
 "source-error" |
 /** Processing failed for a reason other than the source. */
@@ -78,7 +80,9 @@ interface SourceResolution {
   resultPrefix?: string;
 }
 /** Options of {@link createRenditionServer}. */
-interface RenditionServerOptions<Context> {
+interface RenditionServerOptions<Context, Scope extends string = string> {
+  /** Catalog of the renditions the server serves, whose scopes type and limit its targets. */
+  catalog: Catalog<string, Scope>;
   source: SourceStore;
   results: ResultStore;
   processor: Processor;
@@ -89,7 +93,7 @@ interface RenditionServerOptions<Context> {
    * Targets of different scopes must map to different locations even when their paths are equal.
    * By default an unscoped path is the source key, and scoped targets are not served.
    */
-  resolveSource?(target: RenditionTarget, context: Context): SourceResolution | undefined | Promise<SourceResolution | undefined>;
+  resolveSource?: (target: RenditionTarget<NoInfer<Scope>>, context: Context) => SourceResolution | undefined | Promise<SourceResolution | undefined>;
   readiness?: {
     /** Process-local index consulted first. */
     memory?: MemoryReadinessIndexOptions;
@@ -129,30 +133,41 @@ interface Rendition {
   url: string;
 }
 /** Generates renditions and finds published ones. */
-interface RenditionServer<Context> {
+interface RenditionServer<Context, Scope extends string = string> {
+  readonly catalog: Catalog<string, Scope>;
   /**
    * Makes sure the rendition of a target is published and returns it.
    *
    * Resolves only after the rendition is written or confirmed to exist.
    *
+   * @throws {RangeError} When the processor cannot render the recipe.
    * @throws {RenditionError} When the rendition cannot be published.
    */
-  ensure(recipe: Recipe, target: RenditionTarget, context: Context): Promise<Rendition>;
+  ensure: (recipe: Recipe, target: RenditionTarget<Scope>, context: Context) => Promise<Rendition>;
   /**
    * Finds a rendition by recipe hash in the readiness indexes, without any storage call.
    *
    * Serves renditions of recipes the catalog no longer contains.
    *
-   * @throws {RenditionError} Of reason `invalid-request` when the target is rejected.
+   * @throws {RenditionError} When the target is rejected, with reason `invalid-request`.
    */
-  findPublished(hash: string, format: RenditionFormat, target: RenditionTarget, context: Context): Promise<Rendition | undefined>;
+  findPublished: (hash: string, format: RenditionFormat, target: RenditionTarget<Scope>, context: Context) => Promise<Rendition | undefined>;
+  /**
+   * Storage locations of a target as `ensure()` uses them, with `resultPrefix` defaulting to `sourceKey`.
+   *
+   * It checks that the catalog declares the scope, calls `resolveSource` and checks that the keys are safe, but does not check that the source exists.
+   * Full rendition keys and the limits of a store are checked only when a rendition is located or stored.
+   *
+   * @throws {RenditionError} When the scope is not declared, or the target is rejected or resolves to an unsafe key, with reason `invalid-request`.
+   */
+  resolve: (target: RenditionTarget<Scope>, context: Context) => Promise<Required<SourceResolution>>;
 }
 /**
  * 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.
  */
-declare function createRenditionServer<Context>(options: RenditionServerOptions<Context>): RenditionServer<Context>;
+declare function createRenditionServer<Context, Scope extends string = string>(options: RenditionServerOptions<Context, Scope>): RenditionServer<Context, Scope>;
 //#endregion
 //#region src/server/handler.d.ts
 /** HTTP request fields a rendition handler reads. */
@@ -162,24 +177,29 @@ interface RenditionRequest {
   path: string;
 }
 /** Failed rendition request, as passed to a failure policy. */
-interface RenditionFailure<Context> {
+interface RenditionFailure<Context, Scope extends string = string> {
   reason: RenditionFailureReason;
   error: RenditionError;
   /** Parsed rendition URL, absent when the URL is malformed. */
   address?: RenditionAddress;
+  /**
+   * Target of the URL, absent when the URL is malformed or its scope is not one the catalog declares.
+   *
+   * It does not mean that `resolveSource` accepts the target or that the source exists.
+   */
+  target?: RenditionTarget<Scope>;
   context: Context;
 }
 /** Options of {@link createRenditionHandler}. */
-interface RenditionHandlerOptions<Context> {
-  /** Catalog whose recipes are generated on demand. */
-  catalog: Catalog;
-  server: RenditionServer<Context>;
+interface RenditionHandlerOptions<Context, Scope extends string = string> {
+  /** Server whose catalog the handler serves. */
+  server: RenditionServer<Context, Scope>;
   /**
    * Builds the response to a failure; `undefined` keeps the default response with a status of the reason.
    *
    * The handler sets `Cache-Control: no-store` on every failure response, including fallbacks such as redirects to the original.
    */
-  onFailure?(failure: RenditionFailure<Context>): Response | undefined | Promise<Response | undefined>;
+  onFailure?(failure: RenditionFailure<Context, Scope>): Response | undefined | Promise<Response | undefined>;
   /**
    * `Cache-Control` of redirects to published renditions; `public, max-age=86400` by default.
    *
@@ -202,6 +222,6 @@ type RenditionHandler<Context> = (request: RenditionRequest, getContext: () => C
  * A hash from the catalog is rendered on demand.
  * An unknown hash is served only when the readiness indexes know its rendition, so arbitrary hashes cost no storage calls.
  */
-declare function createRenditionHandler<Context>({ catalog, server, onFailure, redirectCacheControl }: RenditionHandlerOptions<Context>): RenditionHandler<Context>;
+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 };

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/img-attrs-BoCAHpl5.mjs

@@ -0,0 +1,14 @@
+//#region src/nuxt/img-attrs.ts
+/** Attributes of an `img` element that belong to the rendition alone. */
+const RENDITION_ATTRS = [
+	"src",
+	"srcset",
+	"width",
+	"height"
+];
+/** Name of a default attribute that would set a rendition attribute, in any letter case as HTML ignores it, if there is one. */
+function findRenditionAttr(imgAttrs) {
+	return Object.keys(imgAttrs ?? {}).find((name) => RENDITION_ATTRS.includes(name.toLowerCase()));
+}
+//#endregion
+export { findRenditionAttr as t };

package/dist/index.d.mts

@@ -1,9 +1,7 @@
-import { a as RenditionFit, c as RenditionPosition, d as formatExtensions, f as normalizeRecipe, i as RecipeInput, l as SourcePolicy, n as RECIPE_ENGINE_VERSION, o as RenditionFormat, p as serializeRecipe, r as Recipe, s as RenditionOptions, t as MAX_DIMENSION, u as formatContentTypes } from "./recipe-Je9DxqO1.mjs";
-import { a as RenditionVariant, i as RenditionTarget, n as CatalogDefinition, o as defineCatalog, r as PresetDefinition, t as Catalog } from "./catalog-CSnosQ1L.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-BByyAbmB.mjs";
+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 { 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, RECIPE_ENGINE_VERSION, Recipe, RecipeInput, RenditionAddress, RenditionFit, RenditionFormat, RenditionOptions, RenditionPosition, RenditionTarget, RenditionVariant, 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,11 @@
-import { a as normalizeRecipe, i as formatExtensions, n as RECIPE_ENGINE_VERSION, o as serializeRecipe, r as formatContentTypes, t as MAX_DIMENSION } from "./recipe-DmOhQJWE.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-BIvAw2BR.mjs";
+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 { 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"];
 /**
 * Validates a catalog and computes the recipe and hash of every preset density.
 *
@@ -12,23 +16,34 @@ import { n as isSafePath, r as isSafeScope, t as encodePath } from "./path-hNFUj
 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 variantsByPreset = /* @__PURE__ */ new Map();
+	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], ...options } = {
+		const { densities = [1], originals = [], animation = "first-frame", ...options } = {
 			...definition.defaults,
-			...withoutUndefined(definition.presets[preset])
+			...omitUndefined(definition.presets[preset])
 		};
 		if (densities.length === 0 || new Set(densities).size !== densities.length) throw new RangeError(`Preset "${preset}" must declare unique densities.`);
-		const variants = Object.freeze([...densities].sort((a, b) => a - b).map((density) => {
+		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,
+				options: variantOptions,
 				density,
 				pipeline,
-				policy: definition.sources
+				policy: definition.sources,
+				animation
 			}));
 			return Object.freeze({
 				preset,
@@ -38,20 +53,40 @@ function defineCatalog(definition) {
 				hash: hashRecipe(recipe)
 			});
 		}));
-		variantsByPreset.set(preset, variants);
-		for (const variant of variants) if (!variantsByHash.has(variant.hash)) variantsByHash.set(variant.hash, variant);
+		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 ?? []]) {
+			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 variants(preset) {
-		const found = variantsByPreset.get(preset);
+	function getPreset(preset) {
+		const found = presetsByName.get(preset);
 		if (!found) throw new RangeError(`Unknown rendition preset "${preset}".`);
 		return found;
 	}
-	function variant(preset, density = 1) {
-		const found = variants(preset).find((variant) => variant.density === density);
+	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 variantUrl({ label, hash, recipe }, { scope, path }) {
+	function formatVariantUrl({ label, hash, recipe }, { scope, path }) {
+		assertDeclaredScope(scopes, scope);
 		return formatRenditionPath(basePath, {
 			scope,
 			label,
@@ -63,14 +98,23 @@ function defineCatalog(definition) {
 	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) => variantUrl(variant(preset, density), target),
-		srcset: (preset, target) => variants(preset).map((variant) => `${variantUrl(variant, target)} ${variant.density}x`).join(", ")
+		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(", ")
 	});
 }
-function withoutUndefined(value) {
+/** 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) {
@@ -81,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/nuxt/runtime.d.mts

@@ -1,31 +1,57 @@
-import { t as Catalog } from "../catalog-CSnosQ1L.mjs";
+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 a path no rendition URL can address. */
+  /** 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 {
+export interface RenditionUrlOptions<Scope extends string = string> {
   /** Scope of the path; defaults to the module's `defaultScope`. */
-  scope?: string;
+  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>(catalog: Catalog<Name>, defaultScope?: string): {
+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) => string;
-    srcset: (preset: Name, path: string, { scope }?: Pick<RenditionUrlOptions, "scope">) => string;
-    attrs: (preset: Name, path: string, options?: Pick<RenditionUrlOptions, "scope">) => RenditionImgAttrs;
+    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: {
@@ -38,7 +64,7 @@ export declare function createRenditionHelpers<Name extends string>(catalog: Cat
       required: true;
     };
     scope: {
-      type: StringConstructor;
+      type: PropType<Scope>;
       default: undefined;
     };
   }>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
@@ -54,11 +80,11 @@ export declare function createRenditionHelpers<Name extends string>(catalog: Cat
       required: true;
     };
     scope: {
-      type: StringConstructor;
+      type: PropType<Scope>;
       default: undefined;
     };
   }>> & Readonly<{}>, {
-    scope: string;
+    scope: unknown extends Scope ? keyof Scope extends never ? undefined : Scope : Scope;
   }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
 };
 //#endregion

package/dist/nuxt/runtime.mjs

@@ -1,4 +1,6 @@
-import { n as isSafePath } from "../path-hNFUjCbA.mjs";
+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
@@ -6,38 +8,82 @@ import { defineComponent, h } from "vue";
 * 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) {
+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 } = {}) {
-			return base + catalog.url(preset, {
-				scope: scope ?? defaultScope,
-				path
-			}, 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 } = {}) {
-			return catalog.variants(preset).map(({ density }) => `${url(preset, path, {
-				scope,
-				density
-			})} ${density}x`).join(", ");
+			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 path no rendition URL can address, such as one with a `..` segment, yields no `src`, so stored data never breaks rendering.
+		* 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, options = {}) {
+		function attrs(preset, path, { scope } = {}) {
 			if (/^(?:[a-z][\d+.a-z-]*:|\/\/)/i.test(path)) return { src: path };
-			if (!isSafePath(path)) return {};
+			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: url(preset, path, options),
-				srcset: catalog.variants(preset).length > 1 ? srcset(preset, path, options) : void 0,
+				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
 			};
@@ -69,7 +115,12 @@ function createRenditionHelpers(catalog, defaultScope) {
 			},
 			setup(props) {
 				const renditions = useRenditions();
-				return () => h("img", renditions.attrs(props.preset, props.src, { scope: props.scope }));
+				return () => {
+					return h("img", {
+						...imgAttrs,
+						...renditions.attrs(props.preset, props.src, { scope: props.scope })
+					});
+				};
 			}
 		})
 	};

package/dist/nuxt.d.mts

@@ -1,3 +1,4 @@
+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. */
@@ -10,8 +11,17 @@ export interface ModuleOptions {
   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()`; their `scope` overrides it. */
+  /** 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.