image-renditions 0.0.0-stage → 0.2.0

package/dist/catalog-D11xkViN.d.mts

@@ -0,0 +1,130 @@
+import { a as RenditionAnimation, c as RenditionOptions, r as Recipe, u as SourcePolicy } from "./recipe-BT8D60Qb.mjs";
+//#region src/catalog.d.ts
+/** Named transformation in a catalog. */
+interface PresetDefinition extends RenditionOptions {
+  /** Pixel densities to render, as multipliers of `width` and `height`; defaults to `[1]`. */
+  densities?: readonly number[];
+  /**
+   * Extensions of source files shown as they are instead of rendered, such as `svg`, in lowercase and without the dot.
+   *
+   * Such sources are shown as they are whatever the other options, including `animation`.
+   * They do not affect hashes, and the server still renders such a source when its rendition URL is requested.
+   */
+  originals?: readonly string[];
+  /**
+   * How renditions show animated sources; `first-frame` by default.
+   *
+   * With `preserve`, sources with the `gif` or `webp` extension get variants of their own in `webp` that keep the animation, which take `quality` and `effort` only from a `webp` preset.
+   * The variants of other sources keep their hashes.
+   */
+  animation?: RenditionAnimation;
+}
+/** Shared configuration of renditions, imported by both the client and the server. */
+interface CatalogDefinition<Name extends string = string, Scope extends string = string> {
+  /** Path the rendition handler is mounted at, `/_renditions` by default. */
+  basePath?: string;
+  /** Bumping it gives every variant a new hash, so every rendition is generated again. */
+  pipelineVersion?: number;
+  /** Options of every preset; a preset overrides them field by field. */
+  defaults?: PresetDefinition;
+  /** How special kinds of sources are rendered. */
+  sources?: Partial<SourcePolicy>;
+  /**
+   * Scopes a logical path can belong to, such as `tenant`; every target then has one of them.
+   *
+   * Without them, a target may have any scope or none.
+   */
+  scopes?: readonly Scope[];
+  presets: Record<Name, PresetDefinition>;
+}
+/**
+ * One density of a preset, which is a separate recipe with its own hash.
+ *
+ * A preset that preserves animation has a second variant at each density for GIF and WebP sources.
+ */
+interface RenditionVariant {
+  readonly preset: string;
+  readonly density: number;
+  /** Readable URL label, such as `avatar` or `avatar@2x`. */
+  readonly label: string;
+  readonly recipe: Recipe;
+  readonly hash: string;
+}
+/**
+ * Source a rendition is made from.
+ *
+ * `Scope` is the union of the scopes a catalog declares, which makes `scope` required, or `string` for a catalog without them.
+ */
+type RenditionTarget<Scope extends string = string> = {
+  /** Logical source path inside the scope. */
+  path: string;
+} & (string extends Scope ? {
+  /** Application-defined space of the path, such as a tenant; omitted when the application has one space. */
+  scope?: string;
+} : {
+  /** Space of the path, one of the scopes of the catalog. */
+  scope: Scope;
+});
+/** Validated catalog with its variants and URL builders. */
+interface Catalog<Name extends string = string, Scope extends string = string> {
+  readonly basePath: string;
+  readonly presets: readonly Name[];
+  /** Scopes every target has one of, if the catalog declares them. */
+  readonly scopes?: readonly Scope[];
+  /**
+   * Variants of a preset ordered by density.
+   *
+   * With the path of a GIF or WebP source of a preset that preserves animation, they are the variants that keep it.
+   */
+  variants(preset: Name, path?: string): readonly RenditionVariant[];
+  /**
+   * Variant of a preset at a density, `1` by default, chosen by the source path like in `variants()`.
+   *
+   * @throws {RangeError} When the preset does not declare the density.
+   */
+  variant(preset: Name, density?: number, path?: string): RenditionVariant;
+  /**
+   * Extensions of source files a preset shows as they are instead of rendered.
+   *
+   * @throws {RangeError} When the preset is unknown.
+   */
+  originals(preset: Name): readonly string[];
+  /**
+   * Whether a preset shows a source as it is instead of rendered, judged by the extension of its path.
+   *
+   * @throws {RangeError} When the preset is unknown.
+   */
+  isOriginal(preset: Name, path: string): boolean;
+  /** Every variant of every preset, one per hash. */
+  readonly allVariants: readonly RenditionVariant[];
+  /** Variant with a recipe hash, if the catalog has one. */
+  findVariant(hash: string): RenditionVariant | undefined;
+  /**
+   * Root-relative URL of a rendition.
+   *
+   * @throws {RangeError} When the preset is unknown or does not declare the density, the scope is not one the catalog declares, or the scope or path is unsafe to put into the URL.
+   */
+  url(preset: Name, target: RenditionTarget<Scope>, density?: number): string;
+  /**
+   * `srcset` attribute value listing every density of a preset.
+   *
+   * @throws {RangeError} When the preset is unknown, the scope is not one the catalog declares, or the scope or path is unsafe to put into the URL.
+   */
+  srcset(preset: Name, target: RenditionTarget<Scope>): string;
+}
+/** Preset names of a catalog, such as `PresetName<typeof catalog>`. */
+type PresetName<C extends Pick<Catalog, "presets">> = C["presets"][number];
+/** Scopes a catalog declares, or `string` when it declares none. */
+type ScopeName<C extends Pick<Catalog, "scopes">> = NonNullable<C["scopes"]>[number];
+/**
+ * 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.
+ */
+declare function defineCatalog<const Name extends string, const Scope extends string = string>(definition: CatalogDefinition<Name, Scope> & (string extends Scope ? unknown : {
+  scopes: readonly Scope[];
+})): Catalog<Name, Scope>;
+//#endregion
+export { RenditionTarget as a, defineCatalog as c, PresetName as i, CatalogDefinition as n, RenditionVariant as o, PresetDefinition as r, ScopeName as s, Catalog as t };

package/dist/error-DViVpVmH.mjs

@@ -0,0 +1,12 @@
+//#region src/server/error.ts
+/** Failure of a rendition operation, with a reason a failure policy can tell apart. */
+var RenditionError = class extends Error {
+	reason;
+	name = "RenditionError";
+	constructor(reason, message = reason, options) {
+		super(message, options);
+		this.reason = reason;
+	}
+};
+//#endregion
+export { RenditionError as t };

package/dist/fs.d.mts

@@ -0,0 +1,25 @@
+import { n as ResultStore, r as SourceStore } from "./stores-P-TUmax4.mjs";
+//#region src/stores/fs.d.ts
+/** Options of {@link createFileSystemSource}. */
+export interface FileSystemSourceOptions {
+  /** Directory source keys are resolved in. */
+  root: string;
+  /** Largest source file, in bytes; larger sources fail as too large. */
+  maxBytes?: number;
+}
+/** Options of {@link createFileSystemResults}. */
+export interface FileSystemResultsOptions {
+  /** Directory renditions are written to. */
+  root: string;
+  /**
+   * URL the directory is served at, such as `https://cdn.example.com/renditions` or `/renditions`.
+   *
+   * The web server in front of it sets `Cache-Control`; renditions never change, so it can mark them immutable.
+   */
+  publicUrl: string;
+}
+/** Creates a source store reading files from a directory. */
+export declare function createFileSystemSource({ root, maxBytes }: FileSystemSourceOptions): SourceStore;
+/** Creates a result store writing files to a directory that a web server serves. */
+export declare function createFileSystemResults({ root, publicUrl }: FileSystemResultsOptions): ResultStore;
+//#endregion

package/dist/fs.mjs

@@ -0,0 +1,50 @@
+import { n as isSafePath, t as encodePath } from "./path-hNFUjCbA.mjs";
+import { t as RenditionError } from "./error-DViVpVmH.mjs";
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, resolve, sep } from "node:path";
+//#region src/stores/fs.ts
+/** Creates a source store reading files from a directory. */
+function createFileSystemSource({ root, maxBytes = 52428800 }) {
+	return { async read(key, { signal }) {
+		const path = resolvePath(root, key);
+		const stats = await stat(path).catch(ignoreMissing);
+		if (!stats?.isFile()) return;
+		if (stats.size > maxBytes) throw new RenditionError("source-too-large", `The source ${key} exceeds ${maxBytes} bytes.`);
+		return new Uint8Array(await readFile(path, { signal }));
+	} };
+}
+/** Creates a result store writing files to a directory that a web server serves. */
+function createFileSystemResults({ root, publicUrl }) {
+	return {
+		async exists(key) {
+			return (await stat(resolvePath(root, key)).catch(ignoreMissing))?.isFile() ?? false;
+		},
+		async write(key, { data }, { signal }) {
+			const path = resolvePath(root, key);
+			await mkdir(dirname(path), { recursive: true });
+			const temporary = `${path}.${randomUUID()}.tmp`;
+			try {
+				await writeFile(temporary, data, { signal });
+				await rename(temporary, path);
+			} catch (error) {
+				await rm(temporary, { force: true });
+				throw error;
+			}
+		},
+		url: (key) => `${publicUrl.replace(/\/$/, "")}/${encodePath(key)}`
+	};
+}
+function resolvePath(root, key) {
+	const base = resolve(root);
+	const path = resolve(base, key);
+	const prefix = base.endsWith(sep) ? base : base + sep;
+	if (!isSafePath(key) || !path.startsWith(prefix)) throw new RenditionError("invalid-request", `Unsafe storage key ${key}.`);
+	return path;
+}
+function ignoreMissing(error) {
+	if (error.code === "ENOENT" || error.code === "ENOTDIR") return;
+	throw error;
+}
+//#endregion
+export { createFileSystemResults, createFileSystemSource };

package/dist/h3.d.mts

@@ -0,0 +1,27 @@
+import { r as RenditionHandlerOptions } from "./handler-9XP5SZhg.mjs";
+import { EventHandler, H3Event } from "h3";
+//#region src/h3.d.ts
+/** Source of the application context of a request. */
+interface ContextOptions<Context> {
+  /**
+   * Derives the application context, such as a tenant, from the request event.
+   *
+   * Caches reuse a redirect for every request of its URL, so derive the context from the URL and host only, or set `redirectCacheControl` to `no-store`.
+   * It is skipped for unsupported methods and for malformed URLs unless `onFailure` needs the context.
+   */
+  getContext(event: H3Event): Context | Promise<Context>;
+}
+/**
+ * Options of {@link defineRenditionEventHandler}.
+ *
+ * `getContext` may be omitted when the server accepts an `undefined` context.
+ */
+export type RenditionEventHandlerOptions<Context, Scope extends string = string> = RenditionHandlerOptions<Context, Scope> & (undefined extends Context ? Partial<ContextOptions<Context>> : ContextOptions<Context>);
+/**
+ * Defines an h3 event handler serving rendition URLs, for h3 v1 and v2.
+ *
+ * Mount it at the catalog base path with a catch-all route, such as `/_renditions/**`.
+ */
+export declare function defineRenditionEventHandler<Context, Scope extends string = string>(options: RenditionEventHandlerOptions<Context, Scope>): EventHandler;
+//#endregion
+export {};

package/dist/h3.mjs

@@ -0,0 +1,25 @@
+import { t as createRenditionHandler } from "./handler-CPJllrYi.mjs";
+import { defineEventHandler } from "h3";
+//#region src/h3.ts
+/**
+* Defines an h3 event handler serving rendition URLs, for h3 v1 and v2.
+*
+* Mount it at the catalog base path with a catch-all route, such as `/_renditions/**`.
+*/
+function defineRenditionEventHandler(options) {
+	const handler = createRenditionHandler(options);
+	const getContext = options.getContext;
+	return defineEventHandler((event) => handler(readRequest(event), () => getContext?.(event)));
+}
+function readRequest(event) {
+	if (event.url instanceof URL) return {
+		method: event.req.method,
+		path: event.url.pathname + event.url.search
+	};
+	return {
+		method: event.method,
+		path: event.path
+	};
+}
+//#endregion
+export { defineRenditionEventHandler };

package/dist/handler-9XP5SZhg.d.mts

@@ -0,0 +1,227 @@
+import { r as Recipe, s as RenditionFormat } from "./recipe-BT8D60Qb.mjs";
+import { a as RenditionTarget, t as Catalog } from "./catalog-D11xkViN.mjs";
+import { n as RenditionAddress } from "./url-BVH3ZB0F.mjs";
+import { 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 =
+/** 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 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. */
+"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, 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;
+  /**
+   * 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<NoInfer<Scope>>, 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, 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<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} When the target is rejected, with reason `invalid-request`.
+   */
+  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, or the processor cannot render a variant of the catalog.
+ */
+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. */
+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, 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, 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, Scope>): 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, 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/handler-CPJllrYi.mjs

@@ -0,0 +1,78 @@
+import { a as parseRenditionPath } from "./url-BAU5GYXC.mjs";
+import { r as toDeclaredTarget } from "./scopes-C1kzqQHz.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-too-large": 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({ 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],
+			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, 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, target, getContext);
+		const context = await getContext();
+		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, target, () => context);
+			throw error;
+		}
+	};
+}
+//#endregion
+export { createRenditionHandler 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

@@ -0,0 +1,23 @@
+import { a as RenditionAnimation, c as RenditionOptions, d as formatContentTypes, f as formatExtensions, i as RecipeInput, l as RenditionPosition, m as serializeRecipe, n as RECIPE_ENGINE_VERSION, o as RenditionFit, p as normalizeRecipe, r as Recipe, s as RenditionFormat, t as MAX_DIMENSION, u as SourcePolicy } from "./recipe-BT8D60Qb.mjs";
+import { a as RenditionTarget, c as defineCatalog, i as PresetName, n as CatalogDefinition, o as RenditionVariant, r as PresetDefinition, s as ScopeName, t as Catalog } from "./catalog-D11xkViN.mjs";
+import { a as formatRenditionPath, i as assertBasePath, n as RenditionAddress, o as parseRenditionPath, r as URL_FORMAT_VERSION, t as DEFAULT_BASE_PATH } from "./url-BVH3ZB0F.mjs";
+//#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, PresetName, RECIPE_ENGINE_VERSION, Recipe, RecipeInput, RenditionAddress, RenditionAnimation, RenditionFit, RenditionFormat, RenditionOptions, RenditionPosition, RenditionTarget, RenditionVariant, ScopeName, SourcePolicy, URL_FORMAT_VERSION, assertBasePath, defineCatalog, formatContentTypes, formatExtensions, formatRenditionPath, normalizeRecipe, parseRenditionPath, serializeRecipe };