@capacms/sdk 1.0.0-next.0 → 1.0.0-next.10

package/dist/esm/image/shared-params.generated.js

@@ -0,0 +1,461 @@
+// GENERATED by scripts/shared-image.js from packages/shared/src/image/params.ts, the rules the API serves
+// /files/* by. Do not edit: change the source, and the API and this package follow.
+/**
+ * Query parsing, validation and canonicalisation for `GET /files/*`
+ * (ADMIN_UI_OVERHAUL §0i.1, "The image processor, made tight").
+ *
+ * PURE ON PURPOSE. Nothing here touches sharp, the network or the database, so
+ * the whole parameter surface — every accepted value, every rejection, and the
+ * canonical spelling of every URL — is testable without a server and without a
+ * live Backblaze object. That matters for this route in particular: its eight
+ * parity fixtures are all 400/404 cases because a DB hit immediately leaves the
+ * process (docs/TURBINE_PORT_NOTES.md, "Deferred to the P6 cloud parity pass"),
+ * so the transform surface has no golden coverage at all unless it is reachable
+ * from a unit test.
+ *
+ * THE RULE THAT SHAPES EVERYTHING BELOW: a caller that sends only today's three
+ * parameters (`width`, `height`, `blur`) must get today's response. Every
+ * default here is therefore today's behaviour, and the one place that could
+ * have broken it — the canonical-query redirect — is deliberately gated on a
+ * NEW parameter being present. See `canonicalise`.
+ *
+ * WHY IT LIVES IN @capa/shared. `@capacms/sdk` builds image URLs, and a URL
+ * that is not spelled the way `canonicalise` spells it costs every first view
+ * a 301 that the edge then keeps for a year. So the SDK compiles this file into
+ * its own build rather than keeping a second copy of the rules, and its tests
+ * run what it builds back through `canonicalise`. The API imports it from here.
+ */
+/** Content type emitted for each explicitly requestable output format. */
+export const OUTPUT_MIME = {
+    webp: "image/webp",
+    avif: "image/avif",
+    jpeg: "image/jpeg",
+    png: "image/png",
+};
+/**
+ * The longest edge this route will ever produce.
+ *
+ * A cap rather than a clamp, because a clamp makes two different URLs return
+ * the same bytes and therefore occupy two edge objects for one representation.
+ * 4096 is the §0i.1 figure; it is also comfortably above any real layout width
+ * at dpr 3 (1365 CSS px).
+ */
+export const MAX_OUTPUT_EDGE = 4096;
+/** Today's blur bounds, previously applied as a silent clamp. */
+export const MIN_BLUR = 1;
+export const MAX_BLUR = 256;
+/** Default quality for lossy outputs except AVIF. Ignored for png, which is lossless. */
+export const DEFAULT_QUALITY = 80;
+/**
+ * AVIF's own default quality (Penelope Hospitality onboarding, #300). At 80,
+ * AVIF came back larger than WebP at 80; 60 at effort 2 is 16 to 18% smaller
+ * than WebP with equal or better SSIM on eight client photos. The route's
+ * encoder and the effort live in apps/api (image-transform.ts); the number
+ * lives here because canonicalQuery has to know it (see droppableQuality).
+ */
+export const AVIF_DEFAULT_QUALITY = 60;
+/**
+ * The quality an encode into `output` uses when the URL names none.
+ *
+ * The route only ever calls this with a format the URL asked for, explicitly or
+ * through `auto`: with no `format` and no `quality` it selects no encoder at
+ * all and the source keeps its own format (`resolveOutputFormat`).
+ */
+export function defaultQuality(output) {
+    return output === "avif" ? AVIF_DEFAULT_QUALITY : DEFAULT_QUALITY;
+}
+/**
+ * The `quality` canonicalQuery drops from a URL with this `format`, or null
+ * when it keeps every value.
+ *
+ * CANONICALISATION MUST NEVER CHANGE WHAT A URL RENDERS. A value may be dropped
+ * only when the URL without it encodes at that same value. After #300 gave
+ * AVIF its own default, dropping 80 everywhere sent `format=avif&quality=80`
+ * to `format=avif`, which is quality 60.
+ *
+ * - `avif`: null. 80 is not AVIF's default, so it must stay. 60 is, and could
+ *   be dropped without changing the bytes; it is KEPT ON PURPOSE. The SDK's
+ *   frozen URLs (#316, and @capacms/sdk's own tests) include
+ *   `format=avif&quality=60`, which would start taking a 301; and an explicit
+ *   number keeps meaning that number if AVIF's default is retuned, which
+ *   `format=avif` does not. The cost is two edge objects for one image when a
+ *   caller spells the default out.
+ * - `auto`: null. Negotiation picks AVIF (default 60) or WebP or the source's
+ *   own format (default 80), so no single value means "no quality" for every
+ *   browser.
+ * - `webp`, `jpeg`, `png` and no format: DEFAULT_QUALITY, as before.
+ *
+ * KNOWN GAP, older than #300 and left as it is because a URL with no `format`
+ * keeps its spelling: with no format the output follows the SOURCE, which a URL
+ * cannot see. `?quality=80&width=200` on an AVIF or HEIF source is an AVIF at
+ * 80, and `?width=200` keeps sharp's own AVIF default (50). `?quality=80` with
+ * nothing else redirects to the bare URL, which is the stored file, not a
+ * re-encode.
+ */
+export function droppableQuality(format) {
+    if (format === "avif" || format === "auto")
+        return null;
+    return DEFAULT_QUALITY;
+}
+/**
+ * The parameters that existed before §0i.1.
+ *
+ * A URL built only from these is GRANDFATHERED: it is treated as already
+ * canonical and is never redirected, however it is spelled. Without this, every
+ * live `?width=100&height=50` in every customer's markup would start taking a
+ * 301 — which is not a behaviour anyone asked to change, and "keep today's
+ * calls byte-identical" outranks de-duplicating an edge object that has been
+ * duplicated for years already.
+ */
+export const LEGACY_PARAMS = new Set(["width", "height", "blur"]);
+/** Parameters introduced by §0i.1. Their presence is what enables canonicalisation. */
+export const NEW_PARAMS = new Set(["format", "quality", "fit", "dpr", "upscale", "keepMetadata"]);
+/**
+ * Fastify gives `?a=1&a=2` as an array. A repeated parameter has no defensible
+ * meaning here and silently picking one is exactly the "never silently ignored"
+ * failure §0i.1 calls out, so it is a rejection.
+ */
+function single(raw, param) {
+    if (raw === undefined || raw === null)
+        return { ok: true };
+    if (Array.isArray(raw)) {
+        return { ok: false, rejection: { error: `\`${param}\` was given more than once`, param } };
+    }
+    if (typeof raw !== "string") {
+        return { ok: false, rejection: { error: `\`${param}\` must be a single value`, param } };
+    }
+    return { ok: true, value: raw };
+}
+/**
+ * Strict integer parse.
+ *
+ * `parseInt` is what this route used to do and it is the reason `?width=abc`
+ * was a 500: `parseInt("abc")` is NaN, NaN reaches sharp, sharp throws, and the
+ * outer catch turns a bad request into "Failed to process file". `parseInt`
+ * also accepts `12px` and `0x10`. Neither is a width.
+ */
+function strictInt(value) {
+    if (!/^-?\d+$/.test(value.trim()))
+        return null;
+    const n = Number(value.trim());
+    return Number.isSafeInteger(n) ? n : null;
+}
+function strictNumber(value) {
+    if (!/^-?\d+(\.\d+)?$/.test(value.trim()))
+        return null;
+    const n = Number(value.trim());
+    return Number.isFinite(n) ? n : null;
+}
+const BOOL_TRUE = new Set(["1", "true"]);
+const BOOL_FALSE = new Set(["0", "false"]);
+/**
+ * Parse and validate the whole query in one pass.
+ *
+ * Unknown VALUES for a known parameter are rejected. Unknown KEYS are not:
+ * `?v=3` cache-busters and analytics tags are real traffic on a public CDN
+ * origin, and turning them into 400s would break callers who are not using the
+ * image surface at all. They are carried through canonicalisation untouched.
+ */
+export function parseImageParams(query) {
+    const reject = (error, param) => ({ ok: false, rejection: { error, param } });
+    // --- dpr first: it multiplies the dimensions, so the cap has to see it.
+    const dprRaw = single(query.dpr, "dpr");
+    if (!dprRaw.ok)
+        return { ok: false, rejection: dprRaw.rejection };
+    let dpr = 1;
+    if (dprRaw.value !== undefined) {
+        const n = strictNumber(dprRaw.value);
+        if (n === null || n < 1 || n > 3) {
+            return reject("`dpr` must be a number between 1 and 3", "dpr");
+        }
+        dpr = n;
+    }
+    const dimension = (name) => {
+        const raw = single(query[name], name);
+        if (!raw.ok)
+            return raw;
+        if (raw.value === undefined)
+            return { ok: true };
+        const n = strictInt(raw.value);
+        if (n === null || n < 1) {
+            return { ok: false, rejection: { error: `\`${name}\` must be a positive integer`, param: name } };
+        }
+        const effective = Math.round(n * dpr);
+        if (effective > MAX_OUTPUT_EDGE) {
+            return {
+                ok: false,
+                rejection: {
+                    error: `\`${name}\` × \`dpr\` is ${effective}px; the maximum output edge is ${MAX_OUTPUT_EDGE}px`,
+                    param: name,
+                },
+            };
+        }
+        return { ok: true, value: effective };
+    };
+    const w = dimension("width");
+    if (!w.ok)
+        return { ok: false, rejection: w.rejection };
+    const h = dimension("height");
+    if (!h.ok)
+        return { ok: false, rejection: h.rejection };
+    const blurRaw = single(query.blur, "blur");
+    if (!blurRaw.ok)
+        return { ok: false, rejection: blurRaw.rejection };
+    let blur;
+    if (blurRaw.value !== undefined) {
+        const n = strictInt(blurRaw.value);
+        // This used to be `Math.max(1, Math.min(256, parseInt(blur)))` — a silent
+        // clamp, so `blur=99999` and `blur=256` were one representation under two
+        // URLs, and `blur=abc` was a 500.
+        if (n === null || n < MIN_BLUR || n > MAX_BLUR) {
+            return reject(`\`blur\` must be an integer between ${MIN_BLUR} and ${MAX_BLUR}`, "blur");
+        }
+        blur = n;
+    }
+    const formatRaw = single(query.format, "format");
+    if (!formatRaw.ok)
+        return { ok: false, rejection: formatRaw.rejection };
+    let format;
+    if (formatRaw.value !== undefined) {
+        const v = formatRaw.value.trim().toLowerCase();
+        const canon = v === "jpg" ? "jpeg" : v;
+        if (canon !== "webp" && canon !== "avif" && canon !== "jpeg" && canon !== "png" && canon !== "auto") {
+            return reject("`format` must be one of webp, avif, jpeg, png, auto", "format");
+        }
+        format = canon;
+    }
+    const qualityRaw = single(query.quality, "quality");
+    if (!qualityRaw.ok)
+        return { ok: false, rejection: qualityRaw.rejection };
+    let quality;
+    if (qualityRaw.value !== undefined) {
+        const n = strictInt(qualityRaw.value);
+        if (n === null || n < 1 || n > 100) {
+            return reject("`quality` must be an integer between 1 and 100", "quality");
+        }
+        quality = n;
+    }
+    const fitRaw = single(query.fit, "fit");
+    if (!fitRaw.ok)
+        return { ok: false, rejection: fitRaw.rejection };
+    let fit = "inside";
+    if (fitRaw.value !== undefined) {
+        const v = fitRaw.value.trim().toLowerCase();
+        if (v !== "inside" && v !== "cover" && v !== "contain") {
+            return reject("`fit` must be one of inside, cover, contain", "fit");
+        }
+        fit = v;
+    }
+    const flag = (name) => {
+        const raw = single(query[name], name);
+        if (!raw.ok)
+            return raw;
+        if (raw.value === undefined)
+            return { ok: true, value: false };
+        const v = raw.value.trim().toLowerCase();
+        if (BOOL_TRUE.has(v))
+            return { ok: true, value: true };
+        if (BOOL_FALSE.has(v))
+            return { ok: true, value: false };
+        return { ok: false, rejection: { error: `\`${name}\` must be 0 or 1`, param: name } };
+    };
+    const upscale = flag("upscale");
+    if (!upscale.ok)
+        return { ok: false, rejection: upscale.rejection };
+    const keepMetadata = flag("keepMetadata");
+    if (!keepMetadata.ok)
+        return { ok: false, rejection: keepMetadata.rejection };
+    /**
+     * What counts as "the caller asked for a transform".
+     *
+     * `fit`, `dpr` and `upscale` only modify a resize, so on their own they
+     * change nothing — a URL carrying just `?fit=cover` must stay the pass-through
+     * it is today. `keepMetadata` likewise: there is nothing to strip if we are
+     * not re-encoding.
+     */
+    const wantsTransform = w.value !== undefined ||
+        h.value !== undefined ||
+        blur !== undefined ||
+        format !== undefined ||
+        quality !== undefined;
+    return {
+        ok: true,
+        params: {
+            width: w.value,
+            height: h.value,
+            blur,
+            format,
+            quality,
+            fit,
+            dpr,
+            upscale: upscale.value,
+            keepMetadata: keepMetadata.value,
+            wantsTransform,
+        },
+    };
+}
+/** Render a number the way the canonical URL spells it (no trailing zeros). */
+function num(n) {
+    return String(Number(n));
+}
+/**
+ * One key or value of the canonical query, percent-encoded so that a browser
+ * sends it back byte for byte.
+ *
+ * `encodeURIComponent` leaves `'` as it is, but a browser's URL parser
+ * percent-encodes `'` in the query of an http(s) URL. A redirect whose Location
+ * carried a raw `'` was therefore requested as `%27`, which is not the spelling
+ * this module wrote, so it was redirected again, forever. Every other
+ * character `encodeURIComponent` leaves alone (`!` `(` `)` `*` `~` and the
+ * unreserved set) a browser leaves alone too.
+ */
+function encodePart(text) {
+    return encodeURIComponent(text).replace(/'/g, "%27");
+}
+/**
+ * The canonical spelling of a query, so `?width=200&format=webp` and
+ * `?format=webp&width=200` are one edge object rather than two.
+ *
+ * GATED, DELIBERATELY. Canonicalisation only applies once the caller uses a
+ * parameter introduced by §0i.1. A URL made only of `width`/`height`/`blur` is
+ * declared canonical as received, whatever its key order — see LEGACY_PARAMS
+ * for why. The gate is also what keeps the `files-404-params-ignored` parity
+ * fixture (`?width=100&height=50&blur=9`) from becoming a 301.
+ *
+ * @param rawQuery the query string as received, without the leading `?`
+ */
+export function canonicalise(rawQuery, params) {
+    const received = new URLSearchParams(rawQuery);
+    const usesNewParam = [...received.keys()].some((k) => NEW_PARAMS.has(k));
+    if (!usesNewParam)
+        return { query: rawQuery, isCanonical: true };
+    const query = canonicalQuery(rawQuery, params);
+    return { query, isCanonical: query === rawQuery };
+}
+/**
+ * The canonical spelling itself, without `canonicalise`'s gate.
+ *
+ * `canonicalise` is this plus the LEGACY_PARAMS grandfather clause. For a query
+ * that uses a new parameter the two agree; for one made only of
+ * `width`/`height`/`blur` this still sorts and re-spells it, which the API
+ * accepts as canonical too, since the gate declares any legacy spelling
+ * canonical. So a URL built with this is never redirected, whichever
+ * parameters it carries. @capacms/sdk builds every image URL with it.
+ *
+ * @param rawQuery the query string, without the leading `?`; read only for the
+ *   keys this module does not know, which are kept
+ */
+export function canonicalQuery(rawQuery, params) {
+    const received = new URLSearchParams(rawQuery);
+    const keys = [...new Set([...received.keys()])];
+    const out = new Map();
+    // Known parameters are re-rendered from the PARSED value, so `width=0200`,
+    // `format=JPG` and `upscale=true` all collapse onto one spelling. Defaults are
+    // dropped: a URL that asks for the default is the same representation as one
+    // that does not mention it. `quality` only where that is true for every
+    // output the URL can produce (droppableQuality).
+    //
+    // `width`/`height` are re-rendered PRE-dpr, because dpr stays in the URL as
+    // its own term; folding it into the dimension would make `?width=200&dpr=2`
+    // redirect to `?width=400`, which is a different request as far as the caller
+    // who wrote it is concerned.
+    if (params.width !== undefined)
+        out.set("width", num(Math.round(params.width / params.dpr)));
+    if (params.height !== undefined)
+        out.set("height", num(Math.round(params.height / params.dpr)));
+    if (params.blur !== undefined)
+        out.set("blur", num(params.blur));
+    if (params.format !== undefined)
+        out.set("format", params.format);
+    if (params.quality !== undefined && params.quality !== droppableQuality(params.format))
+        out.set("quality", num(params.quality));
+    if (params.fit !== "inside")
+        out.set("fit", params.fit);
+    if (params.dpr !== 1)
+        out.set("dpr", num(params.dpr));
+    if (params.upscale)
+        out.set("upscale", "1");
+    if (params.keepMetadata)
+        out.set("keepMetadata", "1");
+    // Unknown keys are preserved verbatim (first value wins, repeats collapse),
+    // so a cache-buster survives the redirect instead of being silently dropped.
+    //
+    // An empty pair (`&=`, an empty key with an empty value) is dropped: written
+    // back it would be an empty segment, which parses to nothing, so the URL it
+    // redirected to was itself redirected again.
+    for (const key of keys) {
+        if (LEGACY_PARAMS.has(key) || NEW_PARAMS.has(key))
+            continue;
+        const value = received.get(key) ?? "";
+        if (key === "" && value === "")
+            continue;
+        out.set(key, value);
+    }
+    const sorted = [...out.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    return sorted
+        .map(([k, v]) => (v === "" ? encodePart(k) : `${encodePart(k)}=${encodePart(v)}`))
+        .join("&");
+}
+/**
+ * A stable string identifying the transform, for the ETag.
+ *
+ * Built from the RESOLVED parameters rather than the URL, so two spellings of
+ * one representation share an ETag even when the redirect is not in play.
+ * `auto` resolves per request, so the caller passes the resolved format in.
+ */
+export function buildSignature(params, resolvedFormat) {
+    if (!params.wantsTransform)
+        return "raw";
+    const parts = [];
+    if (params.width !== undefined)
+        parts.push(`w${params.width}`);
+    if (params.height !== undefined)
+        parts.push(`h${params.height}`);
+    if (params.width !== undefined || params.height !== undefined) {
+        parts.push(`f${params.fit}`);
+        if (params.upscale)
+            parts.push("up");
+    }
+    if (params.blur !== undefined)
+        parts.push(`b${params.blur}`);
+    if (resolvedFormat)
+        parts.push(`o${resolvedFormat}`);
+    if (params.quality !== undefined)
+        parts.push(`q${params.quality}`);
+    if (params.keepMetadata)
+        parts.push("meta");
+    return parts.join("_") || "raw";
+}
+/**
+ * Which concrete format `format=auto` resolves to for this request.
+ *
+ * Returns null when the client advertises neither modern format, in which case
+ * the source format is kept — `auto` never makes a response worse than the
+ * object already is.
+ *
+ * `q=0` is an explicit REFUSAL in RFC 9110 content negotiation, not a weak
+ * preference, so an entry carrying it is skipped rather than matched.
+ */
+export function resolveAutoFormat(accept) {
+    if (!accept)
+        return null;
+    const offered = new Map();
+    for (const entry of accept.split(",")) {
+        const [type, ...paramParts] = entry.split(";");
+        const name = type.trim().toLowerCase();
+        if (!name)
+            continue;
+        let q = 1;
+        for (const p of paramParts) {
+            const m = /^\s*q\s*=\s*([\d.]+)\s*$/i.exec(p);
+            if (m)
+                q = Number(m[1]);
+        }
+        offered.set(name, Number.isFinite(q) ? q : 1);
+    }
+    if ((offered.get("image/avif") ?? 0) > 0)
+        return "avif";
+    if ((offered.get("image/webp") ?? 0) > 0)
+        return "webp";
+    return null;
+}

package/dist/esm/nextjs/image-loader.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `@capacms/sdk/nextjs/image-loader`: a next/image loader that lets Capa's CDN
+ * resize, in place of Next's own image optimization.
+ *
+ * Its own entry point, apart from `@capacms/sdk/nextjs`, because next/image
+ * runs the loader in the browser: `images.loaderFile` puts this module in
+ * every page that shows an image, and this entry carries the image rules and
+ * nothing else. `@capacms/sdk/nextjs` exports the same functions for server
+ * code.
+ *
+ * ```js
+ * // next.config.mjs
+ * export default { images: { loader: "custom", loaderFile: "./capa-image-loader.js" } };
+ *
+ * // capa-image-loader.js
+ * "use client";
+ * import { createCapaImageLoader } from "@capacms/sdk/nextjs/image-loader";
+ * export default createCapaImageLoader({ format: "webp" });
+ * ```
+ */
+import { type ImageFormat } from "../image/index.js";
+/** What next/image passes a loader. Declared here so this module does not import `next`. */
+export interface CapaImageLoaderProps {
+    src: string;
+    width: number;
+    quality?: number;
+}
+/** A next/image loader. */
+export type CapaImageLoader = (props: CapaImageLoaderProps) => string;
+/** What every image through the loader gets, unless next/image's own props say otherwise. */
+export interface CapaImageLoaderOptions {
+    /**
+     * The format to encode. Left out, each image keeps its own. `auto` picks AVIF
+     * or WebP from the browser's `Accept` header; through the CDN it currently
+     * returns JPEG, so use `webp` until that is fixed.
+     */
+    format?: ImageFormat;
+    /** Quality when an `<Image>` gives none, 1 to 100. Left out, Capa's default, 80. */
+    quality?: number;
+}
+/**
+ * A next/image loader with fixed options. A `src` that is a full Capa URL
+ * (`https://cdn.capacms.com/files/...`, or `https://api.capacms.com/files/...`,
+ * which is built on the CDN host) is resized to the width next/image asks for.
+ * Any other `src` (a file in `public/`, a bare file name, another host) is
+ * returned unchanged.
+ *
+ * The loader never throws, since a throw would fail the render of the whole
+ * page: a `src` or prop the CDN would refuse (`dpr=2` past the 4096-pixel
+ * edge, `quality=abc` in the src, `quality={0}`) gets the `src` back unchanged.
+ * The options given here are checked once, when the loader is made, so a bad
+ * one fails at build time rather than on every image.
+ */
+export declare function createCapaImageLoader(options?: CapaImageLoaderOptions): CapaImageLoader;
+/**
+ * The next/image loader with no options: each image keeps its own format, and
+ * its quality is the `<Image>`'s `quality` prop or Capa's default.
+ */
+export declare const capaImageLoader: CapaImageLoader;
+export default capaImageLoader;

package/dist/esm/nextjs/image-loader.js

@@ -0,0 +1,67 @@
+/**
+ * `@capacms/sdk/nextjs/image-loader`: a next/image loader that lets Capa's CDN
+ * resize, in place of Next's own image optimization.
+ *
+ * Its own entry point, apart from `@capacms/sdk/nextjs`, because next/image
+ * runs the loader in the browser: `images.loaderFile` puts this module in
+ * every page that shows an image, and this entry carries the image rules and
+ * nothing else. `@capacms/sdk/nextjs` exports the same functions for server
+ * code.
+ *
+ * ```js
+ * // next.config.mjs
+ * export default { images: { loader: "custom", loaderFile: "./capa-image-loader.js" } };
+ *
+ * // capa-image-loader.js
+ * "use client";
+ * import { createCapaImageLoader } from "@capacms/sdk/nextjs/image-loader";
+ * export default createCapaImageLoader({ format: "webp" });
+ * ```
+ */
+import { imageUrl, isCapaImageUrl, MAX_OUTPUT_EDGE } from "../image/index.js";
+/**
+ * A next/image loader with fixed options. A `src` that is a full Capa URL
+ * (`https://cdn.capacms.com/files/...`, or `https://api.capacms.com/files/...`,
+ * which is built on the CDN host) is resized to the width next/image asks for.
+ * Any other `src` (a file in `public/`, a bare file name, another host) is
+ * returned unchanged.
+ *
+ * The loader never throws, since a throw would fail the render of the whole
+ * page: a `src` or prop the CDN would refuse (`dpr=2` past the 4096-pixel
+ * edge, `quality=abc` in the src, `quality={0}`) gets the `src` back unchanged.
+ * The options given here are checked once, when the loader is made, so a bad
+ * one fails at build time rather than on every image.
+ */
+export function createCapaImageLoader(options = {}) {
+    const { format, quality } = options;
+    try {
+        imageUrl("x", { format, quality });
+    }
+    catch (error) {
+        throw new TypeError(String(error.message).replace("imageUrl:", "createCapaImageLoader:"));
+    }
+    return (props) => {
+        // Everything inside the try, the props' own destructuring included: a call
+        // with no props object gives back no src rather than throwing.
+        try {
+            const { src, width, quality: asked } = props;
+            if (!isCapaImageUrl(src))
+                return src;
+            return imageUrl(src, {
+                // A width past Capa's edge asks for the edge, which keeps the image resized.
+                width: Math.min(width, MAX_OUTPUT_EDGE),
+                quality: asked ?? quality,
+                format,
+            });
+        }
+        catch {
+            return props?.src;
+        }
+    };
+}
+/**
+ * The next/image loader with no options: each image keeps its own format, and
+ * its quality is the `<Image>`'s `quality` prop or Capa's default.
+ */
+export const capaImageLoader = createCapaImageLoader();
+export default capaImageLoader;

package/dist/esm/nextjs/overlay.d.ts

@@ -0,0 +1,30 @@
+export interface CapaOverlayProps {
+    /** The Capa admin origins allowed to drive the overlay. */
+    adminOrigins: string[];
+    /**
+     * How a save shows. `"in-place"` (the default) re-renders the draft with
+     * `router.refresh()`, and reloads the page only if that has not landed
+     * within `refreshTimeoutMs`. `"reload"` reloads the page on every save.
+     * The scroll position is kept either way.
+     */
+    refresh?: "in-place" | "reload";
+    /** How long an in-place refresh may take before the page reloads instead. 10 seconds. */
+    refreshTimeoutMs?: number;
+}
+/**
+ * The refresh runs in a transition, so `isPending` says when the new draft
+ * has been committed to the screen, and the overlay settles the refresh
+ * then: it puts the scroll position back, and a refresh that has not
+ * committed within `refreshTimeoutMs` reloads.
+ *
+ * While the transition is pending the overlay makes a no-op state update
+ * every `REFRESH_NUDGE_MS`. React 19.2 under Next 15.5 can leave a draft
+ * refresh suspended after every part of its streamed response has arrived:
+ * the page suspends inside an already visible Suspense boundary (a root
+ * `loading.tsx` makes one around every page), and the signal that its data
+ * is ready is lost, so nothing commits until some other state update. Any
+ * state update makes React retry the suspended render, which then completes.
+ * A refresh that commits on its own stops the nudges at once. Draft mode
+ * only: a visitor never runs this component.
+ */
+export declare function CapaOverlay({ adminOrigins, refresh, refreshTimeoutMs }: CapaOverlayProps): null;