image-renditions 0.0.0-stage → 0.1.0

package/dist/handler-BFV_vIr4.d.mts

@@ -0,0 +1,207 @@
+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";
+//#region src/server/error.d.ts
+/** Why a rendition could not be served. */
+type RenditionFailureReason =
+/** The URL is malformed, the source resolver rejected its target, or a key is unsafe or too long for the store. */
+"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. */
+"unsupported-source" |
+/** Reading the source failed for a reason other than its absence. */
+"source-error" |
+/** Processing failed for a reason other than the source. */
+"processing-failed" |
+/** Checking for or writing the result in storage failed. */
+"storage-error" |
+/** The processing queue is full, or a request waited in it for too long. */
+"overloaded";
+/** Failure of a rendition operation, with a reason a failure policy can tell apart. */
+declare class RenditionError extends Error {
+  readonly reason: RenditionFailureReason;
+  name: string;
+  constructor(reason: RenditionFailureReason, message?: string, options?: ErrorOptions);
+}
+//#endregion
+//#region src/server/coordinator.d.ts
+/**
+ * Serializes work on the same rendition.
+ *
+ * Callers with an equal key share the outcome of one task run.
+ * A cross-replica implementation can hold a distributed lock instead, because the task rechecks whether the rendition is already published.
+ * The server sets no timeout on `run`, so a distributed lock must limit how long it waits.
+ */
+interface Coordinator {
+  run<T>(key: string, task: () => Promise<T>): Promise<T>;
+}
+/** Creates a coordinator that merges concurrent equal requests within the process. */
+declare function createLocalCoordinator(): Coordinator;
+//#endregion
+//#region src/server/readiness.d.ts
+/**
+ * Positive knowledge that renditions are published, keyed by their public URL.
+ *
+ * An index never records failures or absence.
+ * A lost entry costs one storage check for a recipe in the catalog, but leaves a recipe missing from the catalog unservable.
+ */
+interface ReadinessIndex {
+  has(url: string, options?: StoreCallOptions): boolean | Promise<boolean>;
+  add(url: string, options?: StoreCallOptions): void | Promise<void>;
+}
+/** Options of {@link createMemoryReadinessIndex}. */
+interface MemoryReadinessIndexOptions {
+  /** Entries kept before the least recently used ones are evicted. */
+  maxEntries?: number;
+}
+/**
+ * Creates a process-local readiness index with least-recently-used eviction.
+ *
+ * @throws {RangeError} When `maxEntries` is not a non-negative integer.
+ */
+declare function createMemoryReadinessIndex({ maxEntries }?: MemoryReadinessIndexOptions): ReadinessIndex;
+//#endregion
+//#region src/server/server.d.ts
+/** Storage locations of a source and its renditions. */
+interface SourceResolution {
+  /** Key of the source object in the source store. */
+  sourceKey: string;
+  /**
+   * Key prefix of every rendition of the source; a rendition is stored at `<resultPrefix>/<hash>.<extension>`.
+   *
+   * Defaults to `sourceKey`, which suits a result store separate from the source store.
+   * Different sources must have different prefixes, and in a store shared with sources the prefixes must stay apart from source keys, such as under `renditions/`.
+   */
+  resultPrefix?: string;
+}
+/** Options of {@link createRenditionServer}. */
+interface RenditionServerOptions<Context> {
+  source: SourceStore;
+  results: ResultStore;
+  processor: Processor;
+  /**
+   * Maps a target to storage locations within the application context, such as a tenant.
+   *
+   * Returns `undefined` when the target must not be served, for example an unknown scope.
+   * 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>;
+  readiness?: {
+    /** Process-local index consulted first. */
+    memory?: MemoryReadinessIndexOptions;
+    /**
+     * Index shared between replicas, consulted after the memory index.
+     *
+     * Each call gets an abort signal that fires after `limits.indexTimeout`; the server stops waiting then, even if the call goes on.
+     */
+    shared?: ReadinessIndex;
+  };
+  /** Merges work on the same rendition; process-local by default. */
+  coordinator?: Coordinator;
+  limits?: {
+    /** Renditions processed at once, including their source download. */
+    concurrency?: number;
+    /** Renditions waiting for a processing slot; more fail as `overloaded`. */
+    queueSize?: number;
+    /** Milliseconds a rendition may wait for a processing slot before it fails as `overloaded`. */
+    queueTimeout?: number;
+    /** Milliseconds each storage call may take before it fails; the store receives an abort signal to cancel its work. */
+    storageTimeout?: number;
+    /** Milliseconds each shared readiness index call may take before it counts as failed; the index receives an abort signal to cancel its work. */
+    indexTimeout?: number;
+  };
+  /**
+   * Receives errors that do not fail the operation, such as an unavailable shared readiness index.
+   *
+   * It is not awaited, and its own failures are ignored.
+   */
+  onError?(error: unknown): void;
+}
+/** Published rendition. */
+interface Rendition {
+  /** Key in the result store. */
+  key: string;
+  /** Public URL. */
+  url: string;
+}
+/** Generates renditions and finds published ones. */
+interface RenditionServer<Context> {
+  /**
+   * Makes sure the rendition of a target is published and returns it.
+   *
+   * Resolves only after the rendition is written or confirmed to exist.
+   *
+   * @throws {RenditionError} When the rendition cannot be published.
+   */
+  ensure(recipe: Recipe, target: RenditionTarget, 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.
+   */
+  findPublished(hash: string, format: RenditionFormat, target: RenditionTarget, context: Context): Promise<Rendition | undefined>;
+}
+/**
+ * Creates a rendition server over source and result stores.
+ *
+ * @throws {RangeError} When a limit is not an integer in its range.
+ */
+declare function createRenditionServer<Context>(options: RenditionServerOptions<Context>): RenditionServer<Context>;
+//#endregion
+//#region src/server/handler.d.ts
+/** HTTP request fields a rendition handler reads. */
+interface RenditionRequest {
+  method: string;
+  /** Request path in its wire encoding, with an optional query string. */
+  path: string;
+}
+/** Failed rendition request, as passed to a failure policy. */
+interface RenditionFailure<Context> {
+  reason: RenditionFailureReason;
+  error: RenditionError;
+  /** Parsed rendition URL, absent when the URL is malformed. */
+  address?: RenditionAddress;
+  context: Context;
+}
+/** Options of {@link createRenditionHandler}. */
+interface RenditionHandlerOptions<Context> {
+  /** Catalog whose recipes are generated on demand. */
+  catalog: Catalog;
+  server: RenditionServer<Context>;
+  /**
+   * 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>;
+  /**
+   * `Cache-Control` of redirects to published renditions; `public, max-age=86400` by default.
+   *
+   * Keep it moderate: the target URL depends on storage configuration, and a cached redirect cannot be revoked.
+   * Use `no-store` when the context depends on cookies or a session, because caches reuse a redirect for every request of its URL.
+   */
+  redirectCacheControl?: string;
+}
+/**
+ * Serves rendition URLs by redirecting to published renditions.
+ *
+ * `getContext` returns the application context, such as a tenant.
+ * The handler calls it at most once, and only for a request it passes to the server or a failure it passes to `onFailure`, so unsupported methods and malformed URLs skip a lookup.
+ * Its failures propagate unchanged, without `onFailure`.
+ */
+type RenditionHandler<Context> = (request: RenditionRequest, getContext: () => Context | Promise<Context>) => Promise<Response>;
+/**
+ * Creates a framework-independent rendition handler.
+ *
+ * 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>;
+//#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/handler-BHMwNZnI.mjs

@@ -0,0 +1,76 @@
+import { a as parseRenditionPath } from "./url-BIvAw2BR.mjs";
+import { t as RenditionError } from "./error-DViVpVmH.mjs";
+//#region src/server/handler.ts
+const failureStatus = {
+	"invalid-request": 404,
+	"unknown-recipe": 404,
+	"source-not-found": 404,
+	"unsupported-source": 422,
+	"source-error": 502,
+	"processing-failed": 500,
+	"storage-error": 502,
+	overloaded: 503
+};
+/**
+* Creates a framework-independent rendition handler.
+*
+* 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) {
+		const response = (onFailure && await onFailure({
+			reason: error.reason,
+			error,
+			address,
+			context: await getContext()
+		})) ?? new Response(error.reason, {
+			status: failureStatus[error.reason],
+			headers: {
+				"content-type": "text/plain",
+				...error.reason === "overloaded" && { "retry-after": "1" }
+			}
+		});
+		const headers = new Headers(response.headers);
+		headers.set("cache-control", "no-store");
+		return new Response(response.body, {
+			status: response.status,
+			statusText: response.statusText,
+			headers
+		});
+	}
+	return async ({ method, path }, getContext) => {
+		if (method !== "GET" && method !== "HEAD") return new Response(null, {
+			status: 405,
+			headers: {
+				allow: "GET, HEAD",
+				"cache-control": "no-store"
+			}
+		});
+		const address = parseRenditionPath(catalog.basePath, path);
+		if (!address) return fail(new RenditionError("invalid-request", "Malformed rendition URL."), 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);
+		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}.`);
+			return new Response(null, {
+				status: 307,
+				headers: {
+					location: rendition.url,
+					"cache-control": redirectCacheControl
+				}
+			});
+		} catch (error) {
+			if (error instanceof RenditionError) return fail(error, address, () => context);
+			throw error;
+		}
+	};
+}
+//#endregion
+export { createRenditionHandler as t };

package/dist/index.d.mts

@@ -0,0 +1,23 @@
+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";
+//#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
+//#region src/path.d.ts
+/**
+ * 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.
+ */
+export declare function isSafePath(path: string): boolean;
+/** Percent-encodes each segment of a slash-separated path for use in a URL path. */
+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 };

package/dist/index.mjs

@@ -0,0 +1,84 @@
+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 { n as isSafePath, r as isSafeScope, t as encodePath } from "./path-hNFUjCbA.mjs";
+//#region src/catalog.ts
+/**
+* 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 pipeline = definition.pipelineVersion ?? 1;
+	const presets = Object.freeze(Object.keys(definition.presets));
+	const variantsByPreset = /* @__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 } = {
+			...definition.defaults,
+			...withoutUndefined(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) => {
+			const recipe = wrapRangeError(`preset "${preset}"`, () => normalizeRecipe({
+				options,
+				density,
+				pipeline,
+				policy: definition.sources
+			}));
+			return Object.freeze({
+				preset,
+				density,
+				label: density === 1 ? preset : `${preset}@${density}x`,
+				recipe,
+				hash: hashRecipe(recipe)
+			});
+		}));
+		variantsByPreset.set(preset, variants);
+		for (const variant of variants) if (!variantsByHash.has(variant.hash)) variantsByHash.set(variant.hash, variant);
+	}
+	function variants(preset) {
+		const found = variantsByPreset.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);
+		if (!found) throw new RangeError(`Preset "${preset}" has no density ${density}.`);
+		return found;
+	}
+	function variantUrl({ label, hash, recipe }, { scope, path }) {
+		return formatRenditionPath(basePath, {
+			scope,
+			label,
+			hash,
+			format: recipe.format,
+			path
+		});
+	}
+	return Object.freeze({
+		basePath,
+		presets,
+		variants,
+		variant,
+		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(", ")
+	});
+}
+function withoutUndefined(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,64 @@
+import { t as Catalog } from "../catalog-CSnosQ1L.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. */
+  src?: string;
+  srcset?: string;
+  width?: number;
+  height?: number;
+}
+/** Options of a rendition URL. */
+export interface RenditionUrlOptions {
+  /** Scope of the path; defaults to the module's `defaultScope`. */
+  scope?: string;
+  /** Density of the variant; defaults to `1`. */
+  density?: number;
+}
+/**
+ * Binds `useRenditions()` and `<RenditionImg>` to a catalog.
+ *
+ * The Nuxt module calls it in a generated module; applications use the generated helpers.
+ */
+export declare function createRenditionHelpers<Name extends string>(catalog: Catalog<Name>, defaultScope?: string): {
+  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;
+  };
+  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: StringConstructor;
+      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: StringConstructor;
+      default: undefined;
+    };
+  }>> & Readonly<{}>, {
+    scope: string;
+  }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
+};
+//#endregion

package/dist/nuxt/runtime.mjs

@@ -0,0 +1,78 @@
+import { n as isSafePath } from "../path-hNFUjCbA.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.
+*/
+function createRenditionHelpers(catalog, defaultScope) {
+	/** Builds rendition URLs below the application base URL. */
+	function useRenditions() {
+		const base = useRuntimeConfig().app.baseURL.replace(/\/$/, "");
+		function url(preset, path, { scope, density } = {}) {
+			return base + catalog.url(preset, {
+				scope: scope ?? defaultScope,
+				path
+			}, density);
+		}
+		function srcset(preset, path, { scope } = {}) {
+			return catalog.variants(preset).map(({ density }) => `${url(preset, path, {
+				scope,
+				density
+			})} ${density}x`).join(", ");
+		}
+		/**
+		* 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.
+		*/
+		function attrs(preset, path, options = {}) {
+			if (/^(?:[a-z][\d+.a-z-]*:|\/\/)/i.test(path)) return { src: path };
+			if (!isSafePath(path)) return {};
+			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,
+				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 () => h("img", renditions.attrs(props.preset, props.src, { scope: props.scope }));
+			}
+		})
+	};
+}
+//#endregion
+export { createRenditionHelpers };

package/dist/nuxt.d.mts

@@ -0,0 +1,21 @@
+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()`; their `scope` overrides it. */
+  defaultScope?: string;
+}
+/**
+ * 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,45 @@
+import { r as isSafeScope } from "./path-hNFUjCbA.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 }, 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 catalogPath = await resolvePath(catalogModule);
+		const catalog = await createJiti(nuxt.options.rootDir, { alias: nuxt.options.alias }).import(catalogPath, { default: true });
+		if (handler) addServerHandler({
+			route: `${catalog.basePath}/**`,
+			handler: await resolvePath(handler)
+		});
+		const template = addTemplate({
+			filename: "image-renditions.ts",
+			write: true,
+			getContents: () => [
+				`import catalog from ${JSON.stringify(catalogPath.replace(/\.[cm]?[jt]s$/, ""))}`,
+				`import { createRenditionHelpers } from "image-renditions/nuxt/runtime"`,
+				"",
+				`export const { useRenditions, RenditionImg } = createRenditionHelpers(catalog, ${JSON.stringify(defaultScope)})`,
+				""
+			].join("\n")
+		});
+		addImports({
+			name: "useRenditions",
+			from: template.dst
+		});
+		addComponent({
+			name: "RenditionImg",
+			export: "RenditionImg",
+			filePath: template.dst
+		});
+	}
+});
+//#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-_xuwB7Aa.d.mts

@@ -0,0 +1,14 @@
+import { r as Recipe } from "./recipe-Je9DxqO1.mjs";
+import { t as EncodedImage } from "./stores-DFDRMZcC.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.
+   */
+  process(source: Uint8Array, recipe: Recipe): Promise<EncodedImage>;
+}
+//#endregion
+export { Processor as t };