caracms 0.0.0-stage → 0.2.0

package/src/media-value.ts

@@ -0,0 +1,239 @@
+/**
+ * A media slot's stored value (M5b Decision 3): an image or a Mux clip, parsed,
+ * written and resolved for the render. Browser-safe (only caracms/files, itself import-free): the editor's
+ * fields read it as the server does. URLs that need signing are NOT built here
+ * (that's `media.ts`, server-only); a clip's Mux URLs are fixed hosts, so they are.
+ *
+ *   an image  { "key": "uploads/…/harbour-wall.jpg", "alt": "…", "focal": [0.4, 0.3], "w": 4000, "h": 2667 }
+ *   a clip    { "video": "<playback ID>", "play": "loop", "poster": 2.5, "name": "…", "duration": 14.2, "w": 1920, "h": 1080 }
+ *
+ * - An image is an object with a non-empty string `key`; a clip one with a non-empty
+ *   string `video`. Anything else parses as `null` (empty), and the serializer leaves
+ *   it in the file untouched unless the field is edited (M3 Decision 7).
+ * - `alt` is always written (`""` when there's none). `decorative: true` only when
+ *   true, after `alt`, and then `alt` is written as `""` (the alt kept as read until
+ *   the field is written; decorative wins at render).
+ * - `focal` is `[x, y]`, fractions from the left and the top, 0–1, rounded to two
+ *   places; half a pair, a value out of 0–1 or nonsense reads as unset (no warning).
+ * - A clip's `play` is `loop` (also what a missing or unknown value reads as) or `player`.
+ *
+ * Parsing is idempotent (a parsed value parses to itself), which the serializer's
+ * "touched?" comparison relies on.
+ */
+import { isFileKey } from './files.ts';
+
+export type MediaOnly = 'image' | 'video';
+export type PlayAs = 'loop' | 'player';
+
+export interface ImageValue {
+	key: string;
+	alt: string;
+	decorative?: true;
+	focal?: [number, number];
+	w?: number;
+	h?: number;
+}
+
+export interface ClipValue {
+	video: string;
+	play: PlayAs;
+	poster?: number;
+	name?: string;
+	duration?: number;
+	w?: number;
+	h?: number;
+}
+
+export type MediaValue = ImageValue | ClipValue;
+
+/** What a block component gets for an image slot (fields.ts → renderValue). */
+export interface RenderImage {
+	kind: 'image';
+	key: string;
+	/** `""` for a decorative image, whatever the file says (decorative wins). */
+	alt: string;
+	decorative: boolean;
+	focal: [number, number] | null;
+	/** `"40% 30%"` when there's a focal point, else null (no `object-position`). */
+	position: string | null;
+	w: number | null;
+	h: number | null;
+}
+
+/** What a block component gets for a clip slot. */
+export interface RenderClip {
+	kind: 'video';
+	playbackId: string;
+	/** `loop` whenever the slot is loop-only (`media({ play: 'loop' })`). */
+	play: PlayAs;
+	name: string;
+	/** The MP4 a loop plays: Mux's `highest` static rendition. */
+	mp4: string;
+	/** Mux's still at `poster` seconds (0, the first frame, when unset), WebP at 1920. */
+	poster: string;
+	duration: number | null;
+	w: number | null;
+	h: number | null;
+}
+
+export type RenderMedia = RenderImage | RenderClip;
+
+const isObject = (value: unknown): value is Record<string, unknown> => !!value && typeof value === 'object' && !Array.isArray(value);
+const nonEmpty = (value: unknown): value is string => typeof value === 'string' && value.trim() !== '';
+const size = (value: unknown): number | undefined => (typeof value === 'number' && Number.isFinite(value) && value > 0 ? value : undefined);
+const round2 = (n: number) => Math.round(n * 100) / 100;
+
+/** A focal point as stored: both numbers finite and within 0–1, rounded to two places; otherwise unset. */
+export function parseFocal(value: unknown): [number, number] | undefined {
+	if (!Array.isArray(value) || value.length !== 2) return undefined;
+	const [x, y] = value;
+	const ok = (n: unknown): n is number => typeof n === 'number' && Number.isFinite(n) && n >= 0 && n <= 1;
+	return ok(x) && ok(y) ? [round2(x), round2(y)] : undefined;
+}
+
+/** Is this an image value (an object with a string `key`)? */
+export const isImageValue = (value: unknown): value is ImageValue => isObject(value) && nonEmpty(value.key);
+/** Is this a clip value (an object with a string `video`, and no `key`)? */
+export const isClipValue = (value: unknown): value is ClipValue => isObject(value) && !nonEmpty(value.key) && nonEmpty(value.video);
+
+/** A raw value as a media value, or null for anything that isn't one. Never throws. */
+export function parseMedia(raw: unknown): MediaValue | null {
+	if (!isObject(raw)) return null;
+	if (nonEmpty(raw.key)) {
+		const out: ImageValue = { key: raw.key.trim(), alt: typeof raw.alt === 'string' ? raw.alt : '' };
+		if (raw.decorative === true) out.decorative = true;
+		const focal = parseFocal(raw.focal);
+		if (focal) out.focal = focal;
+		const w = size(raw.w);
+		const h = size(raw.h);
+		if (w !== undefined) out.w = w;
+		if (h !== undefined) out.h = h;
+		return out;
+	}
+	if (nonEmpty(raw.video)) {
+		const out: ClipValue = { video: raw.video.trim(), play: raw.play === 'player' ? 'player' : 'loop' };
+		if (typeof raw.poster === 'number' && Number.isFinite(raw.poster) && raw.poster >= 0) out.poster = raw.poster;
+		if (nonEmpty(raw.name)) out.name = raw.name;
+		const duration = size(raw.duration);
+		const w = size(raw.w);
+		const h = size(raw.h);
+		if (duration !== undefined) out.duration = duration;
+		if (w !== undefined) out.w = w;
+		if (h !== undefined) out.h = h;
+		return out;
+	}
+	return null;
+}
+
+/** A media value in the order the file stores it (Decision 3): `null` for an empty slot. */
+export function mediaToJson(value: unknown): Record<string, unknown> | null {
+	const v = parseMedia(value);
+	if (!v) return null;
+	if ('key' in v) {
+		const out: Record<string, unknown> = { key: v.key, alt: v.decorative ? '' : v.alt };
+		if (v.decorative) out.decorative = true;
+		if (v.focal) out.focal = v.focal;
+		if (v.w !== undefined) out.w = v.w;
+		if (v.h !== undefined) out.h = v.h;
+		return out;
+	}
+	const out: Record<string, unknown> = { video: v.video, play: v.play };
+	if (v.poster !== undefined) out.poster = v.poster;
+	if (v.name !== undefined) out.name = v.name;
+	if (v.duration !== undefined) out.duration = v.duration;
+	if (v.w !== undefined) out.w = v.w;
+	if (v.h !== undefined) out.h = v.h;
+	return out;
+}
+
+/**
+ * A media value as one line of JSON, the way the demo's files hold it:
+ * `{ "key": "…", "alt": "…", "focal": [0.4, 0.3], "w": 4000, "h": 2667 }`; `null` when empty.
+ */
+export function mediaLine(value: unknown): string {
+	const stored = mediaToJson(value);
+	if (!stored) return 'null';
+	const part = (v: unknown) => (Array.isArray(v) ? `[${v.map((x) => JSON.stringify(x)).join(', ')}]` : JSON.stringify(v));
+	return `{ ${Object.entries(stored)
+		.map(([k, v]) => `${JSON.stringify(k)}: ${part(v)}`)
+		.join(', ')} }`;
+}
+
+/** Which kind a value is: `'image'`, `'video'`, or null when empty. */
+export function mediaKind(value: unknown): MediaOnly | null {
+	const v = parseMedia(value);
+	return v ? ('key' in v ? 'image' : 'video') : null;
+}
+
+/**
+ * The slot's value after picking something new (Decision 3): an image replaces the
+ * whole value, not decorative (a new picture may carry meaning), its alt text and
+ * focal point the ones given (already used for it, Decision 7) or `""` and none. A clip swapped for a clip keeps its play mode and name (`video.md`) and
+ * resets its poster; a clip in an image's slot starts as a loop.
+ */
+export function pickMedia(previous: unknown, picked: { key: string; w?: number; h?: number; alt?: string; focal?: [number, number] | null } | { video: string; duration?: number; w?: number; h?: number }): MediaValue {
+	if ('key' in picked) {
+		return parseMedia({ key: picked.key, alt: picked.alt ?? '', focal: picked.focal ?? undefined, w: picked.w, h: picked.h })!;
+	}
+	const prev = parseMedia(previous);
+	const clip = prev && 'video' in prev ? prev : null;
+	return parseMedia({ video: picked.video, play: clip?.play ?? 'loop', name: clip?.name, duration: picked.duration, w: picked.w, h: picked.h })!;
+}
+
+/** Mux's delivery and thumbnail hosts (fixed for every account). */
+export const MUX_STREAM_URL = 'https://stream.mux.com';
+export const MUX_IMAGE_URL = 'https://image.mux.com';
+/** The poster's width: the ladder's top (Mux upscales on request, so it's a cap too). */
+export const MUX_POSTER_WIDTH = 1920;
+
+/** A clip's MP4: the `highest` static rendition (never `1080p`, which is billed). */
+export const muxMp4 = (playbackId: string) => `${MUX_STREAM_URL}/${encodeURIComponent(playbackId)}/highest.mp4`;
+/** A clip's poster: WebP at 1920, at `time` seconds (0, the first frame, when unset). Never the default PNG. */
+export const muxPoster = (playbackId: string, time?: number) =>
+	`${MUX_IMAGE_URL}/${encodeURIComponent(playbackId)}/thumbnail.webp?width=${MUX_POSTER_WIDTH}&time=${typeof time === 'number' && Number.isFinite(time) && time >= 0 ? time : 0}`;
+
+/**
+ * The render's value for a slot: an image or a clip resolved for the page, or null
+ * when the slot is empty or holds a kind it doesn't take (`only`). `play: 'loop'`
+ * forces a clip to loop. Takes a stored value, or an already-resolved one.
+ */
+export function renderMedia(value: unknown, slot: { only?: MediaOnly; play?: 'loop' } = {}): RenderMedia | null {
+	// M6c G4 (Decision 4): a file's key written into a media value by hand is no image: nothing, never an imgproxy URL for a PDF.
+	if (isObject(value) && isFileKey(typeof value.key === 'string' ? value.key.trim() : null)) return null;
+	if (isObject(value) && (value.kind === 'image' || value.kind === 'video') && (typeof value.key === 'string' || typeof value.playbackId === 'string')) {
+		const resolved = value as unknown as RenderMedia;
+		if (slot.only && slot.only !== resolved.kind) return null;
+		return resolved.kind === 'video' && slot.play === 'loop' ? { ...resolved, play: 'loop' } : resolved;
+	}
+	const v = parseMedia(value);
+	if (!v) return null;
+	if ('key' in v) {
+		if (slot.only === 'video') return null;
+		const focal = v.focal ?? null;
+		return {
+			kind: 'image',
+			key: v.key,
+			alt: v.decorative ? '' : v.alt.trim(),
+			decorative: !!v.decorative,
+			focal,
+			position: focal ? `${Math.round(focal[0] * 100)}% ${Math.round(focal[1] * 100)}%` : null,
+			w: v.w ?? null,
+			h: v.h ?? null,
+		};
+	}
+	if (slot.only === 'image') return null;
+	return {
+		kind: 'video',
+		playbackId: v.video,
+		play: slot.play === 'loop' ? 'loop' : v.play,
+		name: v.name?.trim() ?? '',
+		mp4: muxMp4(v.video),
+		poster: muxPoster(v.video, v.poster),
+		duration: v.duration ?? null,
+		w: v.w ?? null,
+		h: v.h ?? null,
+	};
+}
+
+/** The message on an image with no alt text (Decision 9). */
+export const MISSING_ALT_MESSAGE = "No alt text yet: people who can't see the picture get nothing";

package/src/media.ts

@@ -0,0 +1,255 @@
+/**
+ * The image URL builder (M5b Decision 2): the ONE place that knows imgproxy's URL
+ * shape and signs it. **Server-only** (node:crypto, the signing key): the build and
+ * the preview's server render call it, never the browser. Nothing here is ever put
+ * in `virtual:caracms/config` or an editor prop: only the URLs it returns leave the
+ * server.
+ *
+ *   https://<CARACMS_MEDIA_URL>/<sig>/rs:<fit|fill>:<w>:<h>[/g:fp:<x>:<y>]/q:80/plain/s3://<bucket>/<key>@webp
+ *
+ * - `<sig>` is imgproxy's HMAC-SHA256 over the salt then the path, in base64url
+ *   (docs.imgproxy.net → Signing the URL). A path with no signature, or a wrong one,
+ *   is refused (403).
+ * - A gravity goes only on a `fill` (a `fit` crops nothing; a gravity there would only
+ *   make a second URL for the same file). Quality 80. WebP, always in the URL (never
+ *   imgproxy's auto-format: Railway's CDN ignores `Vary: Accept`); `@png` when the
+ *   media field says `format: 'png'` (M9 Decision 8).
+ * - Sides are rounded and capped at 4000 (imgproxy's `IMGPROXY_MAX_RESULT_DIMENSION`).
+ * - GIFs and SVGs pass through: `/<sig>/plain/s3://<bucket>/<key>`, no resize, no
+ *   format, still signed (a GIF resize drops its animation; an SVG is sharp at any size).
+ *
+ * The variables (Decision 5): `CARACMS_MEDIA_URL` (imgproxy's public origin),
+ * `IMGPROXY_KEY` and `IMGPROXY_SALT` (hex, the values imgproxy has), `S3_BUCKET` (the
+ * bucket in the `s3://` source). `CARACMS_MEDIA=memory` supplies `https://img.test`, a
+ * fixed test key and salt and a test bucket, and is refused on a production server.
+ */
+import { createHmac } from 'node:crypto';
+import type { ImageFormat } from './fields.ts';
+import type { RenderImage } from './media-value.ts';
+
+/** The srcset width ladder every fluid image draws from (Decision 2). 1920 at the top: imgproxy doesn't upscale. */
+export const IMAGE_WIDTHS: readonly number[] = [160, 320, 480, 640, 960, 1280, 1920];
+/** imgproxy's IMGPROXY_MAX_RESULT_DIMENSION: a side is never asked for above it. */
+export const IMAGE_MAX_DIMENSION = 4000;
+export const IMAGE_QUALITY = 80;
+/** Pinned in every resized URL, unless the media field asks for PNG (M9 Decision 8). */
+export const IMAGE_FORMAT: ImageFormat = 'webp';
+/** Fixed mode's densities (Decision 4: 1×, 2×, 3×). */
+export const IMAGE_DENSITIES: readonly number[] = [1, 2, 3];
+
+/** `CARACMS_MEDIA=memory`'s host, key, salt and bucket (tests only; Decision 5). */
+export const MEMORY_MEDIA = {
+	origin: 'https://img.test',
+	key: '7465737420696d6770726f7879206b6579',
+	salt: '7465737420696d6770726f78792073616c74',
+	bucket: 'caracms-test-media',
+} as const;
+
+export interface MediaSettings {
+	/** imgproxy's public origin, no trailing slash. */
+	origin: string;
+	/** Hex, as imgproxy takes them. */
+	key: string;
+	salt: string;
+	bucket: string;
+	memory: boolean;
+}
+
+export type MediaConfig =
+	| { kind: 'ready'; settings: MediaSettings }
+	/** `missing` names the variables that aren't set; `problems` are sentences for anything else wrong. */
+	| { kind: 'unset'; missing: string[]; problems: string[] };
+
+declare const __CARACMS_PRODUCTION__: boolean | undefined;
+
+/** True in the build and the built server (the integration's define), false under `astro dev` and in plain Node. */
+export function isProductionBuild(): boolean {
+	return typeof __CARACMS_PRODUCTION__ === 'boolean' ? __CARACMS_PRODUCTION__ : false;
+}
+
+type Env = Record<string, string | undefined>;
+const HEX = /^(?:[0-9a-fA-F]{2})+$/;
+
+/** The media variables (Decision 5). Read on each call (cheap), so tests can change them. */
+export function readMediaConfig(env: Env = process.env, production = isProductionBuild()): MediaConfig {
+	const get = (name: string) => {
+		const v = env[name]?.trim();
+		return v ? v : null;
+	};
+	const problems: string[] = [];
+	const mode = get('CARACMS_MEDIA');
+	if (mode === 'memory') {
+		if (production) return { kind: 'unset', missing: [], problems: ['CARACMS_MEDIA=memory is for tests and local runs; a production server never uses the in-memory media.'] };
+		return { kind: 'ready', settings: { ...MEMORY_MEDIA, memory: true } };
+	}
+	if (mode) problems.push(`CARACMS_MEDIA must be "memory" or unset (got "${mode}").`);
+	const missing: string[] = [];
+	const need = (name: string) => {
+		const v = get(name);
+		if (!v) missing.push(name);
+		return v ?? '';
+	};
+	const origin = need('CARACMS_MEDIA_URL').replace(/\/+$/, '');
+	const key = need('IMGPROXY_KEY');
+	const salt = need('IMGPROXY_SALT');
+	const bucket = need('S3_BUCKET');
+	if (origin && !/^https?:\/\/[^/]+$/.test(origin)) problems.push(`CARACMS_MEDIA_URL must be an origin like https://img.example.com (got "${origin}").`);
+	if (key && !HEX.test(key)) problems.push('IMGPROXY_KEY must be hex (the same value imgproxy has).');
+	if (salt && !HEX.test(salt)) problems.push('IMGPROXY_SALT must be hex (the same value imgproxy has).');
+	if (missing.length || problems.length) return { kind: 'unset', missing, problems };
+	return { kind: 'ready', settings: { origin, key, salt, bucket, memory: false } };
+}
+
+const FAILED = Symbol.for('caracms.mediaUnsetThrown');
+/** True after the first call in this process: a build without the variables throws its sentence once (Media.astro). */
+export function failedOnce(): boolean {
+	const g = globalThis as { [FAILED]?: true };
+	if (g[FAILED]) return true;
+	g[FAILED] = true;
+	return false;
+}
+
+/** The one sentence a render without the variables gives (Decision 5). */
+export function mediaUnsetMessage(config: Extract<MediaConfig, { kind: 'unset' }>): string {
+	const names = config.missing;
+	const list = names.length <= 1 ? names.join('') : `${names.slice(0, -1).join(', ')} and ${names[names.length - 1]}`;
+	const missing = names.length ? `Images can't be built without ${list}: set ${names.length === 1 ? 'it' : 'them'} to the site's imgproxy and media bucket.` : '';
+	return [missing, ...config.problems].filter(Boolean).join(' ');
+}
+
+/** imgproxy's signature for a path: HMAC-SHA256 with the key, over the salt then the path, base64url. */
+export function signPath(path: string, keyHex: string, saltHex: string): string {
+	return createHmac('sha256', Buffer.from(keyHex, 'hex')).update(Buffer.from(saltHex, 'hex')).update(path).digest('base64url');
+}
+
+/** Does imgproxy resize this key at all? GIFs and SVGs pass through (Decision 2). */
+export const isResizable = (key: string): boolean => !/\.(gif|svg)$/i.test(key);
+
+/** A side, rounded and capped; 0 for "not set". */
+function side(value: number | undefined): number {
+	if (!value || !Number.isFinite(value) || value <= 0) return 0;
+	return Math.min(Math.round(value), IMAGE_MAX_DIMENSION);
+}
+
+/** A key as imgproxy's `plain` source takes it: each part percent-encoded, slashes kept. */
+const sourceOf = (settings: MediaSettings, key: string) => `s3://${settings.bucket}/${key.split('/').map(encodeURIComponent).join('/')}`;
+
+const signed = (settings: MediaSettings, path: string) => `${settings.origin}/${signPath(path, settings.key, settings.salt)}${path}`;
+
+export interface ImageUrlOptions {
+	width?: number;
+	height?: number;
+	/** Default: `fill` with both sides, else `fit`. */
+	resize?: 'fit' | 'fill';
+	/** The focal point, fractions; used only on a `fill`. */
+	focal?: readonly [number, number] | null;
+	/** Default: WebP (M9 Decision 8). */
+	format?: ImageFormat;
+}
+
+/**
+ * One signed URL for a key at one size and shape. A GIF or an SVG gets its
+ * pass-through URL whatever the options; anything else needs a width or a height.
+ */
+export function imageUrl(settings: MediaSettings, key: string, options: ImageUrlOptions = {}): string {
+	if (!isResizable(key)) return signed(settings, `/plain/${sourceOf(settings, key)}`);
+	const width = side(options.width);
+	const height = side(options.height);
+	if (!width && !height) throw new Error(`An image URL needs a width or a height (${key}).`);
+	const resize = options.resize ?? (width && height ? 'fill' : 'fit');
+	const gravity = resize === 'fill' && options.focal ? `/g:fp:${options.focal[0]}:${options.focal[1]}` : '';
+	return signed(settings, `/rs:${resize}:${width}:${height}${gravity}/q:${IMAGE_QUALITY}/plain/${sourceOf(settings, key)}@${options.format ?? IMAGE_FORMAT}`);
+}
+
+/** A slot's part of the ladder: every rung from `min` to `max`, inclusive. */
+export function imageWidths(min = IMAGE_WIDTHS[0]!, max = IMAGE_WIDTHS[IMAGE_WIDTHS.length - 1]!): number[] {
+	const widths = IMAGE_WIDTHS.filter((w) => w >= min && w <= max);
+	if (widths.length === 0) throw new Error(`No ladder width between ${min} and ${max} (ladder: ${IMAGE_WIDTHS.join(', ')}).`);
+	return widths;
+}
+
+/** A library thumbnail (Phase 2): a `fit` at one rung of the ladder (320 by default), so it shares the page's cache. */
+export function thumbnailUrl(settings: MediaSettings, key: string, width = 320): string {
+	return imageUrl(settings, key, { width });
+}
+
+/** What an `<img>` gets: `src`, the `srcset` and `sizes` (none for a pass-through), and its `width`/`height`. */
+export interface ImageAttributes {
+	src: string;
+	srcset?: string;
+	sizes?: string;
+	width?: number;
+	height?: number;
+}
+
+export interface FluidOptions {
+	sizes: string;
+	/** width / height: crop every rung to it (`rs:fill` with the focal point's gravity). None: `rs:fit`. */
+	ratio?: number;
+	minWidth?: number;
+	maxWidth?: number;
+	format?: ImageFormat;
+}
+
+export interface FixedOptions {
+	/** CSS px. One side: `fit`. Both: `fill`, or `fit` with `fit: 'contain'`. */
+	width?: number;
+	height?: number;
+	fit?: 'cover' | 'contain';
+	densities?: readonly number[];
+	format?: ImageFormat;
+}
+
+const naturalHeight = (image: Pick<RenderImage, 'w' | 'h'>, width: number) => (image.w && image.h ? Math.round((width * image.h) / image.w) : undefined);
+const naturalWidth = (image: Pick<RenderImage, 'w' | 'h'>, height: number) => (image.w && image.h ? Math.round((height * image.w) / image.h) : undefined);
+
+/**
+ * A fluid image (the width follows the viewport): a `w` srcset over the ladder.
+ * `width`/`height` are the stored size, capped at the top rung and scaled to the ratio,
+ * so the browser reserves the box (Decision 4).
+ */
+export function fluidImage(settings: MediaSettings, image: Pick<RenderImage, 'key' | 'focal' | 'w' | 'h'>, options: FluidOptions): ImageAttributes {
+	const widths = imageWidths(options.minWidth, options.maxWidth);
+	const top = widths[widths.length - 1]!;
+	const shownWidth = image.w ? Math.min(image.w, top) : options.ratio ? top : undefined;
+	const dims = (w: number | undefined) => {
+		if (!w) return {};
+		const h = options.ratio ? Math.round(w / options.ratio) : naturalHeight(image, w);
+		return h ? { width: w, height: h } : {};
+	};
+	if (!isResizable(image.key)) return { src: imageUrl(settings, image.key), ...dims(image.w ?? undefined) };
+	const at = (w: number) =>
+		options.ratio
+			? imageUrl(settings, image.key, { width: w, height: Math.round(w / options.ratio), focal: image.focal, format: options.format })
+			: imageUrl(settings, image.key, { width: w, format: options.format });
+	return {
+		src: at(top),
+		srcset: widths.map((w) => `${at(w)} ${w}w`).join(', '),
+		sizes: options.sizes,
+		...dims(shownWidth),
+	};
+}
+
+/** A fixed image (a set CSS size: a logo, an icon): an `x` srcset at 1×, 2×, 3×. */
+export function fixedImage(settings: MediaSettings, image: Pick<RenderImage, 'key' | 'focal' | 'w' | 'h'>, options: FixedOptions): ImageAttributes {
+	const { width, height } = options;
+	if (!width && !height) throw new Error(`A fixed image needs a width or a height (${image.key}).`);
+	const box = { width: width ?? naturalWidth(image, height!), height: height ?? naturalHeight(image, width!) };
+	const dims = box.width && box.height ? { width: box.width, height: box.height } : {};
+	if (!isResizable(image.key)) return { src: imageUrl(settings, image.key), ...dims };
+	const both = !!width && !!height;
+	const resize = both && options.fit !== 'contain' ? 'fill' : 'fit';
+	const at = (d: number) => imageUrl(settings, image.key, { width: width ? width * d : 0, height: height ? height * d : 0, resize, focal: image.focal, format: options.format });
+	const densities = options.densities ?? IMAGE_DENSITIES;
+	return { src: at(densities[0] ?? 1), srcset: densities.map((d) => `${at(d)} ${d}x`).join(', '), ...dims };
+}
+
+/**
+ * One fixed-mode URL for a brand slot (Decision 11): the logo or the tab icon, `fit`
+ * at `cssHeight` × 2 (sharp on a 2× screen; the editor's `<img src>` and the icon's
+ * `href` take one URL). An SVG passes through. Null when the media isn't set up.
+ */
+export function brandImageUrl(key: string, cssHeight: number, config: MediaConfig = readMediaConfig()): string | null {
+	if (config.kind !== 'ready') return null;
+	return imageUrl(config.settings, key, { height: cssHeight * 2 });
+}