image-renditions 0.1.0 → 0.3.0

package/README.md

@@ -8,10 +8,10 @@ Resize and re-encode uploaded images when a page first shows them, store each re
 
 ```html
 <img
-  src="/_renditions/v1/avatar.faf7e221f65dd97945e352a57e805252.avif/avatars/42.jpg"
+  src="/_renditions/v1/avatar.faf7e221f65d.avif/avatars/42.jpg"
   srcset="
-    /_renditions/v1/avatar.faf7e221f65dd97945e352a57e805252.avif/avatars/42.jpg    1x,
-    /_renditions/v1/avatar@2x.b62b90cf6c3ed57e4c1c27da0c36d778.avif/avatars/42.jpg 2x
+    /_renditions/v1/avatar.faf7e221f65d.avif/avatars/42.jpg    1x,
+    /_renditions/v1/avatar@2x.b62b90cf6c3e.avif/avatars/42.jpg 2x
   "
   alt=""
 />
@@ -23,7 +23,13 @@ Resize and re-encode uploaded images when a page first shows them, store each re
 
 With an S3 bucket, or a directory that outlives deploys and is shared by every replica, app servers keep no image files: renditions survive redeploys, and any replica serves any of them.
 
-The h3 handler supports h3 1.15 or newer and h3 2, and the Nuxt module requires Nuxt 4.
+The library is modular, with pluggable parts:
+
+- [HTTP](#h3-and-other-frameworks): an event handler for h3 1.15 or newer and h3 2, and a framework-neutral handler for other servers.
+- [Processing](#processing): a processor built on sharp.
+- [Storage](#storage): an S3 bucket or a file system directory, chosen separately for uploads and renditions.
+- [Nuxt](#quick-start): a Nuxt 4 module that registers the handler and the `<RenditionImg>` component.
+- [Extending](#extending): other storage, image libraries, and state shared between replicas plug in through the interfaces of `image-renditions/server`.
 
 ## When not to use it
 
@@ -62,7 +68,7 @@ Create a handler for rendition URLs, for example one that reads uploads from the
 
 ```ts
 // server/renditions.ts
-import { S3 } from "@aws-sdk/client-s3"
+import { S3Client } from "@aws-sdk/client-s3"
 import { defineRenditionEventHandler } from "image-renditions/h3"
 import { createS3Results, createS3Source } from "image-renditions/s3"
 import { createRenditionServer } from "image-renditions/server"
@@ -70,9 +76,10 @@ import { createSharpProcessor } from "image-renditions/sharp"
 
 import catalog from "#shared/renditions"
 
-const client = new S3({ region: "us-east-1" })
+const client = new S3Client({ region: "us-east-1" })
 
 const server = createRenditionServer({
+  catalog,
   source: createS3Source({ client, bucket: "uploads" }),
   results: createS3Results({
     client,
@@ -82,7 +89,7 @@ const server = createRenditionServer({
   processor: createSharpProcessor(),
 })
 
-export default defineRenditionEventHandler({ catalog, server })
+export default defineRenditionEventHandler({ server })
 ```
 
 A rendition of `avatars/42.jpg` is stored in `renditions` at `avatars/42.jpg/<hash>.avif`, and `publicUrl` is where browsers load it from.
@@ -129,6 +136,8 @@ Options of a preset, or of `defaults`, which every preset overrides field by fie
 - `quality` — encoder quality from 1 to 100, by default 50 for `avif` and 80 for `webp` and `jpeg`; `png` is lossless.
 - `effort` — CPU effort of the `avif` (0–9) and `webp` (0–6) encoders, 4 by default; other formats ignore it.
 - `densities` — pixel densities to render, `[1]` by default.
+- `animation` — `first-frame` (default) renders the first frame of animated sources, and `preserve` keeps the animation of GIF and WebP sources; see [Animation](#animation).
+- `originals` — extensions of sources shown as they are, so no option above applies to them; see [Originals](#originals).
 
 Options of the catalog:
 
@@ -143,11 +152,13 @@ Renaming a preset keeps its stored renditions.
 `<RenditionImg>` renders `src`, and a `srcset` when the preset has several densities.
 
 - It also renders `width` and `height` when the image always has the preset size: with `contain`, or with `cover` and `fill` when `enlarge` is set.
-  Otherwise a small source keeps its own size, so size such images with CSS.
+  It renders neither for other presets, including ones that set a single side, so size their images with CSS.
 - A `src` that is already a URL, such as `blob:` or `https:`, renders unchanged, for example a preview of a file being uploaded.
-- A path no rendition URL can address, such as one with a `..` segment, renders no `src` instead of breaking the page.
+- An unsafe path, such as one with a `..` segment, renders no `src` instead of breaking the page.
+- A source whose extension the preset lists in [`originals`](#originals) renders as it is.
+- A GIF or WebP source of a preset with [`animation: "preserve"`](#animation) renders its animated variants.
 
-`useRenditions()` builds the same URLs in code, prefixed with `app.baseURL`:
+`useRenditions()` builds the same URLs in code, prefixing rendition URLs with `app.baseURL`:
 
 ```ts
 const renditions = useRenditions()
@@ -155,14 +166,19 @@ const renditions = useRenditions()
 renditions.url("cover", post.coverPath)
 renditions.url("avatar", path, { density: 2 })
 renditions.srcset("avatar", path)
-renditions.attrs("avatar", path) // attributes <RenditionImg> renders, for your own img element
+renditions.attrs("avatar", path) // src, srcset and size of <RenditionImg>, for your own img element
 ```
 
+`url()` and `srcset()` return `undefined` for an unsafe path.
+
 Module options, under `renditions`:
 
 - `catalog` — module exporting the catalog by default; required.
 - `handler` — optional module exporting the h3 handler by default, mounted at the catalog base path.
 - `defaultScope` — optional [scope](#scopes) for `<RenditionImg>` and `useRenditions()`.
+- `originalUrl` — module building URLs of [originals](#originals); required when a preset lists `originals`.
+- `imgAttrs` — attributes every `<RenditionImg>` renders, such as `{ loading: "lazy", decoding: "async" }`.
+  An attribute of the element overrides them, for example `loading="eager"` on an image above the fold.
 
 > For users coming from `@nuxt/image`: this module is not an `@nuxt/image` provider, so instead of `<NuxtImg>` and `useImage()`, use `<RenditionImg>` and `useRenditions()` with catalog presets.
 
@@ -180,25 +196,37 @@ Scopes and `resolveSource` let the server decide where a path lives:
 
 Without `resolveSource`, an unscoped path is the key itself, and scoped paths are rejected.
 
-For example, with uploads of several tenants and files shared between them:
+For example, with uploads of several tenants and files shared between them, declare both scopes in the catalog:
+
+```ts
+// shared/renditions.ts
+export default defineCatalog({
+  scopes: ["tenant", "shared"],
+  presets: {
+    // ...
+  },
+})
+```
+
+- Scope names are type-checked against the catalog, like preset names.
+- `catalog.url()` requires a scope.
+  `useRenditions()` and `<RenditionImg>` use the module's `defaultScope` when a call has no scope, and throw a `RangeError` when there is neither.
+- The server rejects a target with another scope or no scope as `invalid-request`, so `resolveSource` receives only the declared scopes.
+- `ScopeName<typeof catalog>` is the union of the scopes, and `PresetName<typeof catalog>` is the union of the preset names.
+
+The catalog of the server types the scopes `resolveSource` receives, so it handles each of them:
 
 ```ts
 // server/renditions.ts
-const server = createRenditionServer<{ tenant: string }>({
+const server = createRenditionServer({
+  catalog,
   // source, results and processor as in the quick start
-  resolveSource({ scope, path }, { tenant }) {
-    if (scope === "tenant") {
-      return { sourceKey: `tenants/${tenant}/${path}` }
-    }
-    if (scope === "shared") {
-      return { sourceKey: `shared/${path}` }
-    }
-    return undefined
+  resolveSource({ scope, path }, { tenant }: { tenant: string }) {
+    return { sourceKey: scope === "tenant" ? `tenants/${tenant}/${path}` : `shared/${path}` }
   },
 })
 
 export default defineRenditionEventHandler({
-  catalog,
   server,
   // findTenant() is your lookup, for example by host.
   getContext: async event => ({ tenant: await findTenant(event) }),
@@ -206,26 +234,112 @@ export default defineRenditionEventHandler({
 ```
 
 - If `resolveSource` returns `undefined`, the request fails with `404`.
-- `resolveSource` receives unscoped paths too, with an undefined `scope`.
+- Without scopes in the catalog, `resolveSource` receives any scope a URL has, or none, and rejects the ones it does not serve.
 - Map different scopes to different keys even for equal paths.
 - A rendition is stored in the result store at `<sourceKey>/<hash>.<extension>`.
   To keep renditions in the bucket of uploads, also return a `resultPrefix` that no source key starts with, such as `` `renditions/${sourceKey}` ``, to use instead of `sourceKey`.
-- S3 limits a key to 1024 bytes in UTF-8, and a rendition key adds up to 38 bytes to its result prefix.
+- S3 limits a key to 1024 bytes in UTF-8, and the library writes a rendition under a key up to 18 bytes longer than its result prefix.
   If source keys can come that close to the limit, return a shorter `resultPrefix`, or their renditions fail as `invalid-request`.
 
 Derive the context from the URL only, host included, for example from the tenant's domain: browsers and CDNs cache the redirect to a rendition by its URL for a day.
 If the context depends on cookies or a session, pass `redirectCacheControl: "no-store"` to `defineRenditionEventHandler()`, or one tenant may get the rendition of another.
 
-With the Nuxt module, `defaultScope: "tenant"` makes `tenant` the scope of every image, and `scope` selects another one:
+With the Nuxt module, `defaultScope: "tenant"` makes `tenant` the scope of every image, and `scope` selects another one; the build fails when the catalog declares scopes without the default one:
 
 ```vue
 <RenditionImg preset="cover" :src="template.coverPath" scope="shared" alt="" />
 ```
 
+## Originals
+
+Some sources are better shown as they are: SVG stays crisp at any zoom, and [`createSharpProcessor()`](#processing) cannot decode ICO or BMP.
+`originals` lists the extensions of such sources, in lowercase and without the dot:
+
+```ts
+export default defineCatalog({
+  defaults: { originals: ["svg", "ico", "bmp"] },
+  presets: {
+    logo: { height: 32 },
+    // Email clients do not show SVG.
+    "email-logo": { height: 32, originals: [] },
+  },
+})
+```
+
+For such a path, `<RenditionImg>` and `useRenditions()` give the URL of the source itself:
+
+- `url()` returns it for every declared density, and `srcset()` returns `undefined`.
+- `<RenditionImg>` renders no `srcset`, `width` or `height`, so size such images with CSS.
+- `gif` in the list shows every GIF as it is, because a path does not tell an animated GIF from a still one.
+  Leave it out and set [`animation: "preserve"`](#animation) instead to shrink animated GIFs.
+- Only the extension is checked, not the content, and the server still renders the source when its rendition URL is requested.
+- Changing `originals` keeps the hashes of the preset.
+
+Only the app knows where its sources are served from, so it builds their URLs.
+Set the module option `originalUrl` to a module whose default export is a composable returning a function from the scope and the logical path to the URL:
+
+```ts
+// app/renditions/original-url.ts
+import { encodePath, type RenditionTarget } from "image-renditions"
+
+export default function useOriginalUrl() {
+  const { uploadsUrl } = useRuntimeConfig().public
+  return ({ path }: RenditionTarget) => `${uploadsUrl}/${encodePath(path)}`
+}
+```
+
+```ts
+// nuxt.config.ts
+export default defineNuxtConfig({
+  renditions: {
+    catalog: "#shared/renditions",
+    originalUrl: "~/renditions/original-url",
+  },
+})
+```
+
+- `useRenditions()` calls the composable every time it is called, so the composable may use other composables.
+- The function receives the scope after `defaultScope`, and a path that is safe but not encoded: `encodePath()` keeps characters such as `#` and `?` inside the path.
+- The URL it returns is used as is, without `app.baseURL`.
+- The build fails when a preset lists `originals` and `originalUrl` is not set.
+
+> `<img>` never runs scripts of an SVG, but an SVG opened as a page runs them on the site it is served from.
+> Keep SVG files that users upload from running scripts as part of the app in any of these ways:
+>
+> - Serve them from a separate domain rather than a subdomain of the app.
+> - Serve them with a `Content-Security-Policy: sandbox` response header.
+> - Store them with `Content-Disposition: attachment`, which S3 keeps with the object, so browsers download such a file instead of opening it.
+
+## Animation
+
+A rendition of an animated source shows its first frame.
+`animation: "preserve"` keeps the animation of GIF and WebP sources instead:
+
+```ts
+export default defineCatalog({
+  presets: {
+    thumb: { width: 96, height: 96 },
+    content: { width: 800, densities: [1, 2], animation: "preserve" },
+  },
+})
+```
+
+- A path with the `gif` or `webp` extension gets variants of its own, which `url()`, `srcset()` and `<RenditionImg>` choose by the extension, as a path does not tell an animated source from a still one.
+- These variants are WebP and take `quality` and `effort` only from a preset whose `format` is `webp`, since values for another format do not suit WebP.
+- A still GIF or WebP source renders as a still WebP image.
+- Only the extension is checked, and the server renders any source with these variants when their URL is requested.
+- The variants of other sources keep their hashes, so only GIF and WebP sources render again.
+- [`originals`](#originals) take precedence, so a preset that lists `gif` in them shows GIF sources as they are.
+
+To render the animated variants ahead of a request, pass the source path to `catalog.variants()`, as in [Rendering outside requests](#rendering-outside-requests).
+
+How much of an animation a rendition keeps depends on the processor; see [Processing](#processing) for `createSharpProcessor()`.
+`createRenditionServer()` fails when its processor cannot render a variant of the catalog.
+
 ## Storage
 
 The server reads sources from a source store and writes renditions to a result store, which may be of different kinds.
-Both source stores fail sources larger than 50 MiB as unsupported; pass `maxBytes` to `createS3Source()` or `createFileSystemSource()` to change the limit.
+Both source stores fail sources larger than 50 MiB as `source-too-large`; pass `maxBytes` to `createS3Source()` or `createFileSystemSource()` to change the limit.
 
 ### S3 storage
 
@@ -233,12 +347,13 @@ To keep uploads and renditions in S3 buckets, use the stores of `image-rendition
 
 ```ts
 // server/renditions.ts
-import { S3 } from "@aws-sdk/client-s3"
+import { S3Client } from "@aws-sdk/client-s3"
 import { createS3Results, createS3Source } from "image-renditions/s3"
 
-const client = new S3({ region: "us-east-1" })
+const client = new S3Client({ region: "us-east-1" })
 
 const server = createRenditionServer({
+  catalog,
   source: createS3Source({ client, bucket: "uploads" }),
   results: createS3Results({
     client,
@@ -249,7 +364,7 @@ const server = createRenditionServer({
 })
 ```
 
-The stores take the aggregated `S3` client of AWS SDK v3 or any object with its `getObject`, `headObject` and `putObject` methods.
+The stores take a client of AWS SDK v3, the bare `S3Client` or the aggregated `S3`.
 `createS3Results()` writes renditions with `Cache-Control: public, max-age=31536000, immutable`; pass it `cacheControl` to change the header.
 The bucket of renditions must serve them publicly at `publicUrl`, directly or through a CDN.
 
@@ -262,6 +377,7 @@ To keep uploads and renditions on a disk served by a web server, use the stores
 import { createFileSystemResults, createFileSystemSource } from "image-renditions/fs"
 
 const server = createRenditionServer({
+  catalog,
   source: createFileSystemSource({ root: "/data/uploads" }),
   results: createFileSystemResults({ root: "/data/renditions", publicUrl: "/renditions" }),
   processor: createSharpProcessor(),
@@ -278,10 +394,21 @@ location /renditions/ {
 ## Processing
 
 `createSharpProcessor()` from `image-renditions/sharp` processes images with [sharp](https://sharp.pixelplumbing.com).
-Sources over 100 megapixels fail as unsupported; pass `maxInputPixels` to `createSharpProcessor()` to change the limit.
+Sources over 100 megapixels fail as `source-too-large`; pass `maxInputPixels` to `createSharpProcessor()` to change the limit, or `0` to remove it.
 A source that a preset would scale beyond 16383 pixels on a side, such as a narrow strip enlarged to the preset width, is scaled less to stay within that limit, so its rendition is smaller than the preset sets.
 Under `cover`, such a source is cropped instead, and its rendition keeps the preset size.
 
+`createSharpProcessor()` keeps the [animation](#animation) of GIF and WebP sources.
+It does not crop animations by `entropy` or `attention`, so a server fails to start with a preset that combines them.
+It renders the first frame of other animated sources, such as APNG and animated AVIF, of an animation with an EXIF orientation, and of an animation beyond a limit:
+
+- `maxFrames` — most frames, 1000 by default.
+- `maxAnimationPixels` — most pixels of all frames, each counted at the larger of the source and the rendition size, 50 megapixels by default.
+
+`0` removes a limit.
+An animation at the pixel limit may take about 4 bytes of memory per pixel, and its encoder needs more, so plan memory for `limits.concurrency` such renditions at once.
+Changing the limits keeps stored renditions as they are; bump `pipelineVersion` to render them again.
+
 To process images with another library, implement the [`Processor`](#extending) interface and pass your implementation to `createRenditionServer()` as `processor`.
 
 ## h3 and other frameworks
@@ -307,7 +434,7 @@ It takes the same options without `getContext` and returns a function from the r
 // server.ts
 import { createRenditionHandler } from "image-renditions/server"
 
-const renditions = createRenditionHandler({ catalog, server })
+const renditions = createRenditionHandler({ server })
 
 export default {
   fetch(request: Request) {
@@ -322,21 +449,39 @@ Build URLs in the app with the catalog, which is safe to import in browsers:
 
 ```ts
 catalog.url("avatar", { path: "avatars/42.jpg" })
-// /_renditions/v1/avatar.faf7e221f65dd97945e352a57e805252.avif/avatars/42.jpg
+// /_renditions/v1/avatar.faf7e221f65d.avif/avatars/42.jpg
 
 catalog.srcset("avatar", { scope: "tenant", path: "avatars/42.jpg" })
 ```
 
+They throw a `RangeError` for an unsafe path; check stored paths with `isSafePath()` first.
+With [originals](#originals) in the catalog, check `catalog.isOriginal()` and build the URL of such a source yourself:
+
+```ts
+function logoUrl(path: string) {
+  if (!isSafePath(path)) {
+    return undefined
+  }
+  if (catalog.isOriginal("logo", path)) {
+    return `https://uploads.example.com/${encodePath(path)}`
+  }
+  return catalog.url("logo", { path })
+}
+```
+
 ## Rendering outside requests
 
 `server.ensure()` publishes one density of a preset without a request, for example right after an upload:
 
 ```ts
-for (const { recipe } of catalog.variants("avatar")) {
-  await server.ensure(recipe, { scope: "tenant", path: "avatars/42.jpg" }, { tenant: "acme" })
+const path = "avatars/42.jpg"
+for (const { recipe } of catalog.variants("avatar", path)) {
+  await server.ensure(recipe, { scope: "tenant", path }, { tenant: "acme" })
 }
 ```
 
+The path chooses the [animated](#animation) variants of sources that have them.
+
 It resolves to the key and public URL of the rendition after it is written or found in storage.
 
 ## How a request is served
@@ -383,7 +528,8 @@ The handler responds to a failure with the status of its reason:
 - `invalid-request` (404): malformed URL, `resolveSource` rejected the target, or a key is unsafe or too long for the store
 - `unknown-recipe` (404): hash neither in the catalog nor known as published
 - `source-not-found` (404): no source under the resolved key
-- `unsupported-source` (422): source cannot be decoded or rendered, or exceeds a size limit
+- `unsupported-source` (422): source cannot be decoded or processed
+- `source-too-large` (422): source exceeds a byte or pixel limit
 - `source-error` (502): reading the source failed
 - `processing-failed` (500): processing failed for a reason other than the source
 - `storage-error` (502): checking for or writing the rendition failed
@@ -401,22 +547,25 @@ Otherwise the request fails as `unknown-recipe` without calling the stores, so m
 
 ```ts
 export default defineRenditionEventHandler({
-  catalog,
   server,
   getContext,
-  onFailure({ reason, error, address, context }) {
+  async onFailure({ reason, error, target, context }) {
     if (reason === "storage-error" || reason === "processing-failed") {
       reportError(error)
     }
-    if (reason === "unknown-recipe" && address) {
-      // originalUrl() is your absolute URL of the uploaded file at the scope and path of the address.
-      return Response.redirect(originalUrl(address, context), 302)
+    if (reason === "unknown-recipe" && target) {
+      // Here sources are public, so an outdated URL shows the original instead.
+      const { sourceKey } = await server.resolve(target, context)
+      return Response.redirect(`https://uploads.example.com/${encodePath(sourceKey)}`, 302)
     }
     return undefined
   },
 })
 ```
 
+- `target` is the target of the URL, absent when the URL is malformed or its scope is not declared.
+- `server.resolve()` returns the keys a target resolves to with `resolveSource`, after checking that they are safe.
+
 Returning `undefined` keeps the default response.
 Every failure response, including a replaced one, is sent with `Cache-Control: no-store`.
 
@@ -426,6 +575,7 @@ Implement an interface from `image-renditions/server` and pass your implementati
 
 - To use other storage, implement `SourceStore` or `ResultStore` and pass it as `source` or `results`.
 - To process images with another library, implement `Processor` and pass it as `processor`.
+  Implement its `assertRecipe()` to reject recipes it cannot render, such as animations, when the server is created.
 - To share the index of published renditions between replicas, for example in Redis, implement `ReadinessIndex` and pass it as `readiness.shared`.
   If a call fails or exceeds `indexTimeout`, the server reports the error to `onError` and checks storage instead, while [outdated URLs](#outdated-urls) fail as `unknown-recipe`.
 - To render each rendition once across replicas, implement `Coordinator` as a shared lock and pass it as `coordinator`.
@@ -439,6 +589,7 @@ The built-in stores and processor implement the same interfaces and serve as exa
   Keep private images out of what `resolveSource` maps, for example by serving only the folders of public images.
 - A source must never change under its key: renditions of a replaced source keep showing the old image.
   Store new content under a new key.
-- Deleting a source leaves its renditions in storage under its result prefix.
-- Animated sources render their first frame, SVG sources are rasterized at the target size, and EXIF orientation is applied.
+- Deleting a source leaves its renditions in storage under its result prefix, which `server.resolve()` returns.
+- A rendition of an animated source shows its first frame unless the preset sets [`animation: "preserve"`](#animation), a rendition of an SVG source is rasterized at the target size, and EXIF orientation is applied.
+  A preset shows such sources as they are when it lists their extensions in [`originals`](#originals).
 - Source paths are limited to 1024 characters.

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/fs.d.mts

@@ -1,10 +1,10 @@
-import { n as ResultStore, r as SourceStore } from "./stores-DFDRMZcC.mjs";
+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 are unsupported. */
+  /** Largest source file, in bytes; larger sources fail as too large. */
   maxBytes?: number;
 }
 /** Options of {@link createFileSystemResults}. */

package/dist/fs.mjs

@@ -10,7 +10,7 @@ function createFileSystemSource({ root, maxBytes = 52428800 }) {
 		const path = resolvePath(root, key);
 		const stats = await stat(path).catch(ignoreMissing);
 		if (!stats?.isFile()) return;
-		if (stats.size > maxBytes) throw new RenditionError("unsupported-source", `The source ${key} exceeds ${maxBytes} bytes.`);
+		if (stats.size > maxBytes) throw new RenditionError("source-too-large", `The source ${key} exceeds ${maxBytes} bytes.`);
 		return new Uint8Array(await readFile(path, { signal }));
 	} };
 }

package/dist/h3.d.mts

@@ -1,4 +1,4 @@
-import { r as RenditionHandlerOptions } from "./handler-BFV_vIr4.mjs";
+import { r as RenditionHandlerOptions } from "./handler-RAQFWtrg.mjs";
 import { EventHandler, H3Event } from "h3";
 //#region src/h3.d.ts
 /** Source of the application context of a request. */
@@ -16,12 +16,12 @@ interface ContextOptions<Context> {
  *
  * `getContext` may be omitted when the server accepts an `undefined` context.
  */
-export type RenditionEventHandlerOptions<Context> = RenditionHandlerOptions<Context> & (undefined extends Context ? Partial<ContextOptions<Context>> : ContextOptions<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>(options: RenditionEventHandlerOptions<Context>): EventHandler;
+export declare function defineRenditionEventHandler<Context, Scope extends string = string>(options: RenditionEventHandlerOptions<Context, Scope>): EventHandler;
 //#endregion
 export {};

package/dist/h3.mjs

@@ -1,4 +1,4 @@
-import { t as createRenditionHandler } from "./handler-BHMwNZnI.mjs";
+import { t as createRenditionHandler } from "./handler-D5toFJ55.mjs";
 import { defineEventHandler } from "h3";
 //#region src/h3.ts
 /**