emdash-plugin-r2-variants 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# emdash-plugin-r2-variants
+
+## 0.1.0
+
+- First release: `Image` component, Portable Text `image` block, dark-mode
+  variants, and a daily cleanup job.
+- `variantsBinding` option: store resized copies in a separate public bucket so
+  the media bucket stays private.
+- Security: accept only storage keys EmDash itself would serve, validate focal
+  points and colours from content, skip originals over 25 MB, validate options.
+- Uses EmDash's exported helpers and constants instead of copies. Removed the
+  `prefix` option.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 RJS Tech Solutions LLP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,216 @@
-# Temporary Holding Version
+# emdash-plugin-r2-variants
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An [EmDash](https://github.com/emdash-cms/emdash) plugin for sites on Cloudflare
+that resizes each image once and stores the resized copies in R2. Pages point their
+`srcset` at the stored files.
+
+By default, EmDash resizes media through the Cloudflare Images binding on every
+request to `/_image` and sends `Cache-Control: max-age=0`, so every image view runs
+your Worker and calls the Images service.
+
+## Benefits
+
+- **Lower Cloudflare Images usage.** Each width is resized once per version of an
+  image. Cloudflare bills unique resizes again each month, so without the plugin a
+  site pays for the same resizes every month.
+- **Fewer Worker requests.** With a public variants bucket, image requests are
+  served by R2 and the Cloudflare cache without invoking your Worker.
+- **Faster repeat views.** Stored copies are sent with a one-year `immutable`
+  cache header, so browsers and the Cloudflare cache keep them. A replaced image
+  gets new URLs, so nobody sees a stale copy.
+- **Little template work.** `Image` takes the same props as EmDash's. Images in
+  rich-text content and dark-mode variants are handled with no template changes.
+- **Private originals.** The resized copies can live in their own public bucket
+  while the media bucket stays private.
+
+**Status:** version 0.1.0, early release.
+
+## How it works
+
+- **Rendering.** The plugin's `Image` component reads
+  `_variants/<storageKey>/manifest.json` from the bucket and checks it against the
+  original's current etag. If they match, it renders an `<img>` whose `srcset` lists
+  the stored files.
+- **First view.** If there is no manifest yet, or the original has changed, that
+  request renders with EmDash's own image component. After the response, the plugin
+  creates every configured width with the Images binding and writes the manifest
+  last. The next render uses the stored files.
+- **Images in body content.** The plugin registers its own Portable Text `image`
+  block, so images inside rich text work the same way with no template changes.
+- **Dark-mode images.** When an image has a `darkVariant`, both images are served
+  from stored files. EmDash's light and dark classes switch between them.
+- **Replaced media.** EmDash overwrites a replaced file under the same key, which
+  gives it a new etag. Variants live under `<storageKey>/<etag>/`, so a replaced
+  image gets new URLs and cached copies of the old version are never shown.
+- **Cleanup.** A daily job at 03:17 UTC deletes variants whose original was deleted
+  or replaced. The first media upload schedules it.
+
+## Requirements
+
+- EmDash 1.1 or later with R2 storage from `@emdash-cms/cloudflare`
+- `@astrojs/cloudflare` with its default Images binding (`IMAGES`)
+
+This is a **native** EmDash plugin. It is registered under `plugins` and runs with
+the site's authority, because it needs the R2 and Images bindings and ships Astro
+components. EmDash's plugin registry distributes only sandboxed plugins, so this
+package is distributed through npm.
+
+## Install
+
+```sh
+npm install emdash-plugin-r2-variants
+```
+
+Add a second R2 bucket for the resized copies in `wrangler.jsonc`:
+
+```jsonc
+"r2_buckets": [
+	{ "binding": "MEDIA", "bucket_name": "my-site-media" },
+	{ "binding": "IMAGE_VARIANTS", "bucket_name": "my-site-variants" }
+]
+```
+
+Register the plugin in `astro.config.mjs`:
+
+```js
+import { r2 } from "@emdash-cms/cloudflare";
+import emdash from "emdash/astro";
+import { r2Variants } from "emdash-plugin-r2-variants";
+
+export default defineConfig({
+	integrations: [
+		emdash({
+			storage: r2({ binding: "MEDIA" }),
+			plugins: [
+				r2Variants({
+					binding: "MEDIA",
+					variantsBinding: "IMAGE_VARIANTS",
+					publicUrl: "https://images.example.com",
+				}),
+			],
+		}),
+	],
+});
+```
+
+### Keep the media bucket private
+
+Give the variants their own bucket and attach the public domain only to that
+bucket. A public domain on the media bucket would expose every object in it: the
+full-size originals, which may carry EXIF location data, and EmDash's private
+`transfers/` folder of import and export files. EmDash's own media route refuses
+those paths, but a bucket domain bypasses the route.
+
+Without `variantsBinding`, the copies are stored in the media bucket under
+`_variants/`. Where visitors load them from depends on `publicUrl`:
+
+| `variantsBinding` | `publicUrl` | Copies stored in | Visitors load them from                              |
+| ----------------- | ----------- | ---------------- | ---------------------------------------------------- |
+| set               | set         | variants bucket  | the variants bucket's public domain, with no Worker  |
+| set               | not set     | —                | the plugin refuses to start                          |
+| not set           | not set     | media bucket     | EmDash's media route, through the Worker             |
+| not set           | set         | media bucket     | the media bucket's public domain (unsafe, see below) |
+
+The first row is the recommended setup.
+
+With neither option set, the media bucket stays private. Each image view still
+runs the Worker and reads from R2, though it never resizes. EmDash's media route
+sends `Cache-Control: max-age=0, must-revalidate`, so browsers check each image
+again on every page load. This mode suits local development.
+
+The last row works only if the media bucket has a public domain, which exposes
+every file in it as described above. Don't use it.
+
+In templates, import `Image` from the plugin instead of from `emdash/ui`. It takes
+the same props.
+
+```astro
+---
+import { Image } from "emdash-plugin-r2-variants/astro";
+---
+<Image image={post.data.featured_image} width={960} />
+```
+
+## Options
+
+| Option            | Default                       | Description                                                                                                  |
+| ----------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `binding`         | `"MEDIA"`                     | R2 binding that EmDash stores media in.                                                                            |
+| `variantsBinding` | media bucket                  | R2 binding for the resized copies. Requires `publicUrl`.                                                           |
+| `publicUrl`       | `""`                          | `https://` custom domain attached to the variants bucket. When empty, EmDash's media route serves the copies through the Worker. |
+| `widths`          | `[320, 640, 960, 1280, 1920]` | Widths to create, up to 4000. Widths larger than the original are skipped, and the original width is always added. |
+| `format`          | `"webp"`                      | `"webp"` or `"avif"`.                                                                                        |
+| `quality`         | `85`                          | Encoder quality.                                                                                             |
+
+## Production setup
+
+1. Create the variants bucket. In the Cloudflare dashboard, connect a custom domain
+   to it (for example `images.example.com`) and set it as `publicUrl`. Avoid `r2.dev`
+   URLs, which are rate limited. Leave the media bucket without any public access.
+2. Add a Cache Rule for that hostname that caches everything with a long edge TTL.
+   Each variant URL contains the original's etag, so the file behind a URL never
+   changes.
+3. Add a cron trigger to `wrangler.jsonc` so EmDash's scheduled handler runs plugin
+   jobs, for example `"triggers": { "crons": ["* * * * *"] }`.
+
+## Security
+
+- Storage keys are read from content, so the plugin accepts only keys that
+  EmDash's own media route would serve (`isSafeTransformKey` from EmDash). Files
+  in private folders such as `transfers/` are never resized or published.
+- Focal points and placeholder colours also come from content. Only numbers from
+  0 to 1 and hex colours reach the `style` attribute.
+- WebP and AVIF output carries no EXIF metadata, so GPS data in originals never
+  reaches the public copies.
+- Originals larger than 25 MB, and formats other than JPEG, PNG, WebP and AVIF,
+  are not resized. EmDash renders them as before.
+- The plugin adds no routes. Resizing happens only for images that content
+  references, when a page renders.
+- Options are checked when `astro.config.mjs` loads. `publicUrl` must use
+  `https://`.
+
+## Verify it works
+
+1. Open a page with images twice. The second time, the `<img>` `src` and `srcset`
+   point at `/_variants/.../<width>.webp`, on your `publicUrl` domain if one is set.
+2. List the variants bucket: `wrangler r2 object list <variants-bucket> --prefix _variants/`.
+3. After the first media upload, the dashboard's scheduled tasks include
+   `r2-variants` / `cleanup`.
+
+## Costs
+
+- Each width is resized once per version of an image, rather than once a month or
+  once per data centre.
+- With `publicUrl` set, visitors' image requests are served by R2 and the Cloudflare
+  cache, without a Worker invocation.
+- Each page render makes two R2 reads per image: one for the manifest and one for
+  the original's metadata. Caching rendered pages keeps this small.
+
+## Limitations
+
+- These are rendered by EmDash as before: linked images in body content, gallery
+  blocks, and images from external media providers.
+- If a site passes its own `image` component to `<PortableText>`, that component
+  takes precedence over the plugin's.
+- Pages served from stored files show the dominant-colour placeholder. They do not
+  show the blurhash placeholder.
+- SVG and GIF files are served unchanged.
+- Cloudflare only: resizing uses the Images binding.
+
+## Development
+
+```sh
+npm test   # node --test; needs no Cloudflare account
+```
+
+| Path                       | Contents                                                       |
+| -------------------------- | -------------------------------------------------------------- |
+| `src/index.js`             | Plugin descriptor for `astro.config.mjs`. Safe to load in Node. |
+| `src/plugin.js`            | Runtime plugin: hooks and the cleanup job.                     |
+| `src/variants.js`          | Resize, manifest, cleanup and `srcset` logic, with tests.      |
+| `src/runtime.js`           | Worker bindings shared by the components.                      |
+| `src/astro/`               | `Image`, the Portable Text `ImageBlock`, and `blockComponents`.  |
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "emdash-plugin-r2-variants",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Image variants plugin for EmDash CMS - stores each resized image in R2 once and serves it without a Worker transform",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./plugin": "./src/plugin.js",
+    "./astro": "./src/astro/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.js",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "emdash",
+    "emdash-plugin",
+    "cms",
+    "plugin",
+    "images",
+    "responsive-images",
+    "r2",
+    "cloudflare",
+    "astro"
+  ],
+  "author": "RJS Tech Solutions LLP",
+  "license": "MIT",
+  "peerDependencies": {
+    "astro": ">=6",
+    "emdash": ">=1.1.0"
+  },
+  "scripts": {
+    "test": "node --test src/"
+  },
+  "devDependencies": {
+    "emdash": ">=1.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rjstech2020/emdash-plugin-r2-variants.git"
+  },
+  "homepage": "https://github.com/rjstech2020/emdash-plugin-r2-variants#readme",
+  "bugs": {
+    "url": "https://github.com/rjstech2020/emdash-plugin-r2-variants/issues"
+  }
+}

package/src/astro/Image.astro

@@ -0,0 +1,64 @@
+---
+/**
+ * Drop-in replacement for `Image` from "emdash/ui".
+ *
+ * When stored variants exist for the current original (and for the dark-mode
+ * image, if there is one), renders plain <img> tags whose srcset points at
+ * them, so a visitor's request never reaches the Worker when `publicUrl` is
+ * set. Otherwise renders EmDash's own Image for this request; the missing
+ * variants are created after the response.
+ *
+ * Dark-mode switching uses the emdash-image--light/--dark classes. Their CSS
+ * ships with EmDash's Image, which this component imports.
+ */
+import type { ComponentProps } from "astro/types";
+import { Image as EmDashImage } from "emdash/ui";
+
+import { lookup, storageKeyOf } from "../runtime.js";
+import { imgAttrs } from "../variants.js";
+
+type Props = ComponentProps<typeof EmDashImage>;
+
+const props = Astro.props;
+const { image, darkVariant, alt, width, height, priority, placeholder = true, class: className, id, ...attrs } = props;
+
+const asValue = (v: unknown) => (v && typeof v === "object" ? (v as Record<string, any>) : null);
+const light = asValue(image);
+const dark = asValue(darkVariant ?? light?.darkVariant);
+
+const lightKey = storageKeyOf(light);
+const darkKey = dark ? storageKeyOf(dark) : undefined;
+// Every image shown must be local media; otherwise EmDash renders the whole thing.
+const usable = lightKey && (!dark || darkKey);
+const [lightManifest, darkManifest] = usable
+	? await Promise.all([lookup(lightKey), darkKey ? lookup(darkKey) : null])
+	: [null, null];
+const ready = lightManifest && (!dark || darkManifest);
+
+function render(value: Record<string, any>, manifest: any, variantClass: string | undefined, elementId: string | undefined) {
+	const a = imgAttrs(manifest, {
+		width,
+		height,
+		focalX: value.focalX,
+		focalY: value.focalY,
+		dominantColor: placeholder ? (value.dominantColor ?? value.meta?.dominantColor) : undefined,
+	});
+	return {
+		...a,
+		id: elementId,
+		alt: alt ?? light?.alt ?? "",
+		loading: priority ? "eager" : "lazy",
+		fetchpriority: priority ? "high" : undefined,
+		decoding: "async",
+		class: [variantClass, className].filter(Boolean).join(" ") || undefined,
+		...attrs,
+	};
+}
+
+const lightImg = ready ? render(light!, lightManifest, dark ? "emdash-image--light" : undefined, id) : null;
+const darkImg = ready && dark ? render(dark, darkManifest, "emdash-image--dark", id ? `${id}--dark` : undefined) : null;
+---
+
+{lightImg ? <img {...lightImg} /> : <EmDashImage {...props} />}
+{darkImg && <img {...darkImg} />}
+

package/src/astro/ImageBlock.astro

@@ -0,0 +1,91 @@
+---
+/**
+ * Portable Text `image` block. Registered through the plugin's componentsEntry,
+ * so every <PortableText> on the site uses it without template changes.
+ *
+ * Renders EmDash's markup (figure, alignment, caption) with stored variants.
+ * Falls back to EmDash's own block for linked images, external providers, and
+ * images whose variants don't exist yet.
+ */
+import { PTImage } from "emdash/ui";
+
+import { lookup, storageKeyOf } from "../runtime.js";
+import { imgAttrs } from "../variants.js";
+
+const props = Astro.props;
+const { node, placeholder = true } = props;
+const asset = node?.asset;
+
+const ALIGNMENTS = new Set(["left", "center", "right", "wide", "full"]);
+const positive = (v: unknown) => (typeof v === "number" && Number.isFinite(v) && v > 0 ? v : undefined);
+const key = node?.link ? undefined : storageKeyOf(asset);
+const manifest = key ? await lookup(key) : null;
+
+const img = manifest
+	? {
+			...imgAttrs(manifest, {
+				width: positive(node.displayWidth),
+				height: positive(node.displayHeight),
+				dominantColor: placeholder ? (node.dominantColor ?? asset.meta?.dominantColor) : undefined,
+			}),
+			alt: node.alt ?? "",
+			title: node.title,
+			loading: "lazy",
+			decoding: "async",
+		}
+	: null;
+---
+
+{
+	img ? (
+		<figure class:list={["emdash-image", ALIGNMENTS.has(node.alignment) && `emdash-image--align-${node.alignment}`]}>
+			<img {...img} />
+			{node.caption && <figcaption>{node.caption}</figcaption>}
+		</figure>
+	) : (
+		<PTImage {...props} />
+	)
+}
+
+<style>
+	/* Copied from EmDash's Portable Text image block, whose styles are scoped to it. */
+	.emdash-image {
+		margin: 1.5rem 0;
+	}
+	.emdash-image figcaption {
+		font-size: 0.875rem;
+		color: var(--emdash-caption-color, var(--color-muted, #666));
+		margin-top: 0.5rem;
+		text-align: center;
+	}
+	.emdash-image--align-left,
+	.emdash-image--align-right {
+		width: fit-content;
+		max-width: 50%;
+	}
+	.emdash-image--align-left {
+		float: left;
+		margin: 0 1.5rem 1rem 0;
+	}
+	.emdash-image--align-right {
+		float: right;
+		margin: 0 0 1rem 1.5rem;
+	}
+	.emdash-image--align-center {
+		width: fit-content;
+		margin-inline: auto;
+	}
+	.emdash-image--align-wide,
+	.emdash-image--align-full {
+		width: 100%;
+	}
+	@media (max-width: 640px) {
+		.emdash-image--align-left,
+		.emdash-image--align-right {
+			float: none;
+			width: 100%;
+			max-width: 100%;
+			margin-inline: 0;
+		}
+	}
+</style>

package/src/astro/index.ts

@@ -0,0 +1,20 @@
+/**
+ * Astro components for sites using the plugin.
+ *
+ * `blockComponents` is the plugin's componentsEntry: EmDash merges it over its
+ * own Portable Text components, so body-content images need no template change.
+ *
+ * @example
+ * ```astro
+ * ---
+ * import { Image } from "emdash-plugin-r2-variants/astro";
+ * ---
+ * <Image image={post.data.featured_image} width={960} />
+ * ```
+ */
+import ImageComponent from "./Image.astro";
+import ImageBlockComponent from "./ImageBlock.astro";
+
+export const blockComponents = { image: ImageBlockComponent };
+
+export { ImageComponent as Image, ImageBlockComponent as ImageBlock };

package/src/index.d.ts

@@ -0,0 +1,23 @@
+import type { PluginDescriptor } from "emdash";
+
+export interface R2VariantsOptions {
+	/** R2 binding EmDash stores media in. Default "MEDIA". */
+	binding?: string;
+	/**
+	 * R2 binding for the resized copies. Recommended when the copies get a public
+	 * domain, so the media bucket (originals, EmDash's private files) stays private.
+	 * Requires `publicUrl`. Default: the media bucket.
+	 */
+	variantsBinding?: string;
+	/** https:// custom domain attached to the variants bucket, e.g. "https://images.example.com". Empty: serve through EmDash's media route. */
+	publicUrl?: string;
+	/** Widths to create, in pixels, up to 4000. Default [320, 640, 960, 1280, 1920]. */
+	widths?: number[];
+	/** Output format. Default "webp". */
+	format?: "webp" | "avif";
+	/** Encoder quality, 1-100. Default: EmDash's transform quality (85). */
+	quality?: number;
+}
+
+export function r2Variants(options?: R2VariantsOptions): PluginDescriptor<R2VariantsOptions>;
+export default r2Variants;

package/src/index.js

@@ -0,0 +1,23 @@
+/**
+ * Plugin descriptor for astro.config.mjs. Validates options when the config
+ * loads, so a broken setup fails the build rather than the first request.
+ */
+import { validate } from "./variants.js";
+
+/**
+ * @param {Partial<import("./variants.js").Config>} [options]
+ * @returns {import("emdash").PluginDescriptor}
+ */
+export function r2Variants(options = {}) {
+	validate(options);
+	return {
+		id: "r2-variants",
+		version: "0.1.0",
+		format: "native",
+		entrypoint: "emdash-plugin-r2-variants/plugin",
+		componentsEntry: "emdash-plugin-r2-variants/astro",
+		options,
+	};
+}
+
+export default r2Variants;

package/src/plugin.js

@@ -0,0 +1,35 @@
+/**
+ * Native plugin runtime. EmDash imports `createPlugin` from here and calls it
+ * with the descriptor's options when the site starts.
+ */
+import { env } from "cloudflare:workers";
+import { definePlugin } from "emdash";
+
+import { bindings, cleanup, configure } from "./variants.js";
+
+const scheduleCleanup = async (_event, ctx) => {
+	await ctx.cron.schedule("cleanup", { schedule: "17 3 * * *" });
+};
+
+/** @param {Partial<import("./variants.js").Config>} options */
+export function createPlugin(options = {}) {
+	configure(options);
+	return definePlugin({
+		id: "r2-variants",
+		version: "0.1.0",
+		// media:read is what EmDash requires for media:afterUpload.
+		capabilities: ["media:read"],
+		hooks: {
+			// Plugins declared in astro.config never get plugin:activate, so the
+			// first upload schedules the job too. schedule() upserts by name.
+			"plugin:activate": scheduleCleanup,
+			"media:afterUpload": scheduleCleanup,
+			cron: async (event, ctx) => {
+				if (event.name !== "cleanup") return;
+				const { media, variants } = bindings();
+				const removed = await cleanup(env[media], env[variants]);
+				ctx.log.info("Removed stale image variants", { removed });
+			},
+		},
+	});
+}

package/src/runtime.js

@@ -0,0 +1,46 @@
+/**
+ * Worker-side glue shared by the Astro components: finds the stored variants
+ * for a media value, or schedules their creation after the response.
+ */
+import { env, waitUntil } from "cloudflare:workers";
+import { matchInternalMediaKey } from "emdash/media/image-endpoint";
+
+import { bindings, generate, isSafeKey, readManifest } from "./variants.js";
+
+/** Resize jobs in flight in this isolate, so parallel first views share one. */
+const pending = new Map();
+
+/**
+ * Storage key of a local media value. Field values carry `meta.storageKey`;
+ * Portable Text assets carry the media URL. Both come from content, so only
+ * keys EmDash itself would serve are accepted.
+ */
+export function storageKeyOf(value) {
+	if (!value || typeof value !== "object" || (value.provider ?? "local") !== "local") return undefined;
+	const key = value.meta?.storageKey ?? matchInternalMediaKey(value.url);
+	return isSafeKey(key) ? key : undefined;
+}
+
+/**
+ * Manifest for the given storage key, or null. On a miss the variants are
+ * created after the response, so the next render can use them.
+ * @returns {Promise<import("./variants.js").Manifest | null>}
+ */
+export async function lookup(storageKey) {
+	const names = bindings();
+	const media = env[names.media];
+	const variants = env[names.variants];
+	if (!isSafeKey(storageKey) || !media || !variants) return null;
+	const manifest = await readManifest(media, variants, storageKey).catch(() => null);
+	if (manifest) return manifest;
+
+	const images = env[globalThis.__ASTRO_IMAGES_BINDING_NAME || "IMAGES"];
+	if (images && !pending.has(storageKey)) {
+		const job = generate(media, variants, images, storageKey)
+			.catch((error) => console.error("[r2-variants] generate failed", storageKey, error))
+			.finally(() => pending.delete(storageKey));
+		pending.set(storageKey, job);
+		waitUntil(job);
+	}
+	return null;
+}

package/src/variants.js

@@ -0,0 +1,201 @@
+/**
+ * Core logic. Free of `cloudflare:workers`, so it loads in astro.config.mjs and
+ * under `node --test`.
+ *
+ * Layout in the variants bucket (the media bucket unless `variantsBinding` is set):
+ *   _variants/<storageKey>/manifest.json           which variants exist, for which original
+ *   _variants/<storageKey>/<etag>/<width>.<format> one resized copy per width
+ *
+ * The original's R2 etag is part of every variant path. EmDash's "replace media"
+ * overwrites the original under the same key, which changes the etag, so a
+ * replaced image gets new URLs and long-lived CDN copies never go stale.
+ */
+import {
+	DEFAULT_TRANSFORM_QUALITY,
+	IMMUTABLE_IMAGE_CACHE,
+	MAX_TRANSFORM_DIMENSION,
+	isSafeTransformKey,
+} from "emdash/media/image-endpoint";
+
+/** @typedef {{ binding: string, variantsBinding: string, publicUrl: string, widths: number[], format: "webp" | "avif", quality: number }} Config */
+/** @typedef {{ key: string, etag: string, format: string, width: number, height: number, widths: number[] }} Manifest */
+
+const PREFIX = "_variants";
+// Both output formats drop all EXIF metadata, so GPS data in originals never reaches the public copies.
+const FORMATS = { webp: "image/webp", avif: "image/avif" };
+const RESIZABLE = new Set(["image/jpeg", "image/png", "image/webp", "image/avif"]);
+// Originals are buffered in Worker memory; larger files keep EmDash's own rendering.
+const MAX_SOURCE_BYTES = 25 * 1024 * 1024;
+const HEX_COLOR = /^#[0-9a-f]{3,8}$/i;
+
+/** @type {Config} */
+export const config = {
+	binding: "MEDIA",
+	variantsBinding: "",
+	publicUrl: "",
+	widths: [320, 640, 960, 1280, 1920],
+	format: "webp",
+	quality: DEFAULT_TRANSFORM_QUALITY,
+};
+
+/**
+ * Options merged over the defaults. Throws on a setup that would break images.
+ * @param {Partial<Config>} options
+ * @returns {Config}
+ */
+export function validate(options = {}) {
+	const c = { ...config, ...options, publicUrl: (options.publicUrl ?? config.publicUrl).replace(/\/+$/, "") };
+	const fail = (message) => {
+		throw new Error(`[r2-variants] ${message}`);
+	};
+	if (c.publicUrl && !c.publicUrl.startsWith("https://")) fail("`publicUrl` must start with https://.");
+	// EmDash's media route only reads the media bucket, so a separate bucket needs its own domain.
+	if (c.variantsBinding && c.variantsBinding !== c.binding && !c.publicUrl) {
+		fail("`variantsBinding` requires `publicUrl`: the custom domain attached to that bucket.");
+	}
+	if (!FORMATS[c.format]) fail('`format` must be "webp" or "avif".');
+	if (!Number.isInteger(c.quality) || c.quality < 1 || c.quality > 100) fail("`quality` must be an integer from 1 to 100.");
+	if (!c.widths.length || !c.widths.every((w) => Number.isInteger(w) && w > 0 && w <= MAX_TRANSFORM_DIMENSION)) {
+		fail(`\`widths\` must be integers from 1 to ${MAX_TRANSFORM_DIMENSION}.`);
+	}
+	return c;
+}
+
+/** @param {Partial<Config>} options */
+export function configure(options) {
+	Object.assign(config, validate(options));
+}
+
+/** Binding names for originals and variants. */
+export const bindings = () => ({ media: config.binding, variants: config.variantsBinding || config.binding });
+
+/** Storage keys EmDash itself would serve: flat `{ulid}{ext}` names, never private folders such as `transfers/`. */
+export const isSafeKey = (key) => typeof key === "string" && isSafeTransformKey(key);
+
+const manifestKey = (key) => `${PREFIX}/${key}/manifest.json`;
+
+/**
+ * The manifest for `key`, or null when variants are missing or were made from
+ * an earlier version of the original.
+ * @returns {Promise<Manifest | null>}
+ */
+export async function readManifest(media, variants, key) {
+	const [original, stored] = await Promise.all([media.head(key), variants.get(manifestKey(key))]);
+	if (!original || !stored) return null;
+	const m = await stored.json();
+	return m.etag === original.etag ? { ...m, key } : null;
+}
+
+/**
+ * Resize the original once per configured width and store the results.
+ * Widths larger than the original are skipped; the original width (capped at
+ * EmDash's transform limit) is always included.
+ * @returns {Promise<Manifest | null>} null when the original is missing, too large, or not a resizable raster.
+ */
+export async function generate(media, variants, images, key) {
+	const original = await media.get(key);
+	if (!original) return null;
+	if (!RESIZABLE.has(original.httpMetadata?.contentType) || original.size > MAX_SOURCE_BYTES) {
+		await original.body?.cancel();
+		return null;
+	}
+	const bytes = await original.arrayBuffer();
+	const { width, height } = await images.info(new Response(bytes).body);
+	if (!width || !height) return null;
+
+	const largest = Math.min(width, MAX_TRANSFORM_DIMENSION);
+	const widths = [...new Set([...config.widths.filter((w) => w < largest), largest])].sort((a, b) => a - b);
+	const { etag } = original;
+	const { format } = config;
+	for (const w of widths) {
+		const out = await images
+			.input(new Response(bytes).body)
+			.transform({ width: w })
+			.output({ format: FORMATS[format], quality: config.quality });
+		// R2 needs a known length, so buffer instead of streaming.
+		await variants.put(`${PREFIX}/${key}/${etag}/${w}.${format}`, await out.response().arrayBuffer(), {
+			httpMetadata: { contentType: FORMATS[format], cacheControl: IMMUTABLE_IMAGE_CACHE },
+		});
+	}
+
+	const manifest = { etag, format, width, height, widths };
+	// Written last: a manifest only exists once every variant it lists does.
+	await variants.put(manifestKey(key), JSON.stringify(manifest), {
+		httpMetadata: { contentType: "application/json", cacheControl: "no-cache" },
+	});
+	return { ...manifest, key };
+}
+
+/**
+ * Delete variants whose original was deleted or replaced.
+ * @returns {Promise<number>} objects removed
+ */
+export async function cleanup(media, variants) {
+	const prefix = `${PREFIX}/`;
+	const etags = new Map(); // storageKey -> current etag, or null when the original is gone
+	const currentEtag = async (key) => {
+		if (!etags.has(key)) etags.set(key, (await media.head(key))?.etag ?? null);
+		return etags.get(key);
+	};
+
+	let removed = 0;
+	let cursor;
+	do {
+		const page = await variants.list({ prefix, cursor });
+		const stale = [];
+		for (const { key: name } of page.objects) {
+			const [key, second, third] = name.slice(prefix.length).split("/");
+			const etag = await currentEtag(key);
+			// <key>/manifest.json stays while the original exists; <key>/<etag>/<file> only for the current etag.
+			if (etag === null || (third !== undefined && second !== etag)) stale.push(name);
+		}
+		if (stale.length) await variants.delete(stale);
+		removed += stale.length;
+		cursor = page.truncated ? page.cursor : undefined;
+	} while (cursor);
+	return removed;
+}
+
+/** Public URL of one variant. Without `publicUrl`, EmDash's media route serves it. */
+function variantUrl(m, width) {
+	const path = `${PREFIX}/${m.key}/${m.etag}/${width}.${m.format}`;
+	return config.publicUrl ? `${config.publicUrl}/${path}` : `/_emdash/api/media/file/${path}`;
+}
+
+/**
+ * srcset/src/sizes for an image displayed `displayWidth` CSS pixels wide.
+ * Lists variants up to 2x the display width for high-density screens.
+ */
+export function responsive(m, displayWidth) {
+	const fits = m.widths.filter((w) => w <= displayWidth * 2);
+	const src = m.widths.find((w) => w >= displayWidth) ?? m.widths.at(-1);
+	return {
+		src: variantUrl(m, src),
+		srcset: (fits.length ? fits : [m.widths[0]]).map((w) => `${variantUrl(m, w)} ${w}w`).join(", "),
+		sizes: `(min-width: ${displayWidth}px) ${displayWidth}px, 100vw`,
+	};
+}
+
+const unit = (v) => typeof v === "number" && v >= 0 && v <= 1;
+const percent = (v) => `${Math.round(v * 10000) / 100}%`;
+
+/**
+ * <img> attributes for a stored image. `width`/`height` are the display size;
+ * either may be omitted and is then derived from the original's aspect ratio.
+ * A display box with a different aspect ratio is filled with object-fit: cover.
+ * Focal point and colour come from content, so only well-formed values reach the style attribute.
+ */
+export function imgAttrs(m, { width, height, focalX, focalY, dominantColor } = {}) {
+	const ratio = m.width / m.height;
+	const w = width ?? (height ? Math.round(height * ratio) : m.width);
+	const h = height ?? Math.round(w / ratio);
+	const style = [
+		"max-width:100%;height:auto",
+		Math.abs(w / h - ratio) > 0.01 && "object-fit:cover",
+		unit(focalX) && unit(focalY) && `object-position:${percent(focalX)} ${percent(focalY)}`,
+		HEX_COLOR.test(dominantColor ?? "") && `background-color:${dominantColor}`,
+	]
+		.filter(Boolean)
+		.join(";");
+	return { ...responsive(m, w), width: w, height: h, style };
+}