caracms 0.0.0-stage → 0.2.0

package/src/editor/server/media/handler.ts

@@ -0,0 +1,221 @@
+/**
+ * The media routes (M5b Phase 2), one handler behind `/_caracms/media/[...path]`
+ * (../../routes/media.ts). The routes, what they take and give: ../../types.ts →
+ * `MEDIA_ENDPOINTS`. A security boundary: it takes files and ids from the browser and
+ * writes to the bucket and Mux.
+ *
+ * - **Live mode**: the guard's prefix rule has already required a session (401) and, for
+ *   a POST, the same origin (403); this checks both again (defence in depth, as the live
+ *   handlers do). **Local mode** works with no sign-in, the origin still checked for a POST.
+ * - **No lock** (Decision 7): an upload, or reading the library, changes no document.
+ * - **Every reply is `Cache-Control: private, no-store`.**
+ * - **Unconfigured: 503 with a sentence naming what's missing**, images (the bucket and
+ *   imgproxy) and clips (Mux) apart: one missing never disables the other.
+ * - **The Mux token never reaches the browser, nor do Mux's error bodies** (server log
+ *   only). Ids are checked against `^[A-Za-z0-9]{1,128}$` before they reach a URL.
+ * - **The upload has its own body cap** (40 MB, upload.ts), not the write route's 2 MB or
+ *   live mode's 16 KB; the video upload's JSON is held to 16 KB.
+ * - **M6c G4: `POST replace`** (Replace… on a file, Decision 9) is the one media route that
+ *   changes documents: the mode's store does it under the same rules as a move (replace.ts;
+ *   live mode takes each document's lock), with the tab's header as a write has it. The new
+ *   file must already be in the bucket.
+ */
+import type { ResolvedSite } from '../../../config.ts';
+import type { Person } from '../../../live/messages.ts';
+import { IMAGE_WIDTHS, thumbnailUrl, type MediaSettings } from '../../../media.ts';
+import type {
+	ApiError,
+	LibraryClip,
+	MediaClipsResponse,
+	MediaFileUploadResponse,
+	MediaImagesResponse,
+	MediaRefusal,
+	MediaUnset,
+	MediaUploadResponse,
+	ReplaceFileResponse,
+	VideoUploadResponse,
+	VideoUploadStatus,
+} from '../../types.ts';
+import { MEDIA_MAX_BYTES, RELEASE_HEADER } from '../../types.ts';
+import type { DraftsStore } from '../drafts-store.ts';
+import { parseReplaceBody } from '../replace.ts';
+import { checkOrigin, seqOf, tabOf, WriteRefused } from '../write.ts';
+import { BucketError, s3Bucket, type Bucket } from './bucket.ts';
+import { readImagesConfig, readMuxConfig } from './config.ts';
+import { isFileKey } from '../../../files.ts';
+import { entryOf, fileEntryOf, libraryFor, mediaUses, UPLOADS, type Library, type MediaUses } from './library.ts';
+import { memoryMedia } from './memory.ts';
+import { clipTitle, muxClient, MuxRouteError, MUX_ID, type Clip, type MuxClient } from './mux.ts';
+import { readCapped, storeUpload, tooLargeMessage, UploadRefused, uploadName } from './upload.ts';
+
+export const MEDIA_PREFIX = '/_caracms/media/';
+const HEADERS = { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'private, no-store' };
+const json = (status: number, body: unknown, extra: Record<string, string> = {}) => new Response(JSON.stringify(body), { status, headers: { ...HEADERS, ...extra } });
+const JSON_CAP = 16_384;
+/** A key the thumbnail route signs: an upload's, nothing else. */
+const UPLOAD_KEY = /^uploads\/[0-9a-f]{12}\/[^/\u0000-\u001f\u007f]{1,255}$/;
+
+type Env = Record<string, string | undefined>;
+
+export interface MediaContext {
+	site: Pick<ResolvedSite, 'root' | 'collections' | 'blocks'>;
+	/** The mode's store (server/mode.ts): where-used reads its listing. */
+	store: DraftsStore;
+	mode: 'local' | 'live';
+	/** The signed-in person (live mode); null in local mode. */
+	person: Person | null;
+	env?: Env;
+	production?: boolean;
+	log?: (line: string) => void;
+	/** Mux's and the bucket's `fetch` (tests). Memory mode never uses it. */
+	fetch?: typeof fetch;
+}
+
+/** The image side, ready: the library and the signing settings. */
+function images(ctx: MediaContext): { library: Library; signing: MediaSettings } | Response {
+	const config = readImagesConfig(ctx.env ?? process.env, ctx.production);
+	if (config.kind === 'unset') return json(503, { error: config.message, code: 'media-unset', missing: config.missing } satisfies MediaUnset);
+	if (config.kind === 'memory') return { library: libraryFor('memory', () => memoryMedia().bucket), signing: config.signing };
+	const b = config.bucket;
+	return { library: libraryFor(`s3:${b.endpoint}:${b.bucket}:${b.accessKeyId}`, (): Bucket => s3Bucket(b, ctx.fetch)), signing: config.signing };
+}
+
+function mux(ctx: MediaContext): MuxClient | Response {
+	const config = readMuxConfig(ctx.env ?? process.env, ctx.production);
+	if (config.kind === 'unset') return json(503, { error: config.message, code: 'mux-unset', missing: config.missing } satisfies MediaUnset);
+	const log = ctx.log ?? ((line: string) => console.error(line));
+	if (config.kind === 'memory') return muxClient({ tokenId: 'memory', tokenSecret: 'memory', fetch: memoryMedia().mux.fetch, log });
+	return muxClient({ tokenId: config.tokenId, tokenSecret: config.tokenSecret, fetch: ctx.fetch, log });
+}
+
+const withUses = (clip: Clip, uses: MediaUses): LibraryClip => ({ ...clip, usedIn: clip.playbackId ? (uses.clips.get(clip.playbackId) ?? []) : [] });
+
+async function readJson(request: Request, shape = '{ "name": "<file name>" }'): Promise<Record<string, unknown>> {
+	const type = (request.headers.get('content-type') ?? '').split(';')[0]!.trim().toLowerCase();
+	if (type !== 'application/json') throw new WriteRefused(415, `Send JSON: ${shape}.`);
+	const body = await readCapped(request, JSON_CAP);
+	if (!body.ok) throw new WriteRefused(413, 'That body is too large.');
+	try {
+		const value = JSON.parse(new TextDecoder().decode(body.bytes)) as unknown;
+		if (value && typeof value === 'object' && !Array.isArray(value)) return value as Record<string, unknown>;
+	} catch {
+		/* below */
+	}
+	throw new WriteRefused(400, `Send JSON: ${shape}.`);
+}
+
+/** Answer one request under `/_caracms/media/`. */
+export async function handleMedia(request: Request, ctx: MediaContext): Promise<Response> {
+	const log = ctx.log ?? ((line: string) => console.error(line));
+	const url = new URL(request.url);
+	const rest = url.pathname.startsWith(MEDIA_PREFIX) ? url.pathname.slice(MEDIA_PREFIX.length) : null;
+	const parts = rest === null ? [] : rest.split('/').filter(Boolean);
+	const [route, id, extra] = parts;
+	const method = request.method.toUpperCase();
+	const only = (allowed: string): Response | null =>
+		method === allowed ? null : json(405, { error: `This route takes ${allowed}.` } satisfies ApiError, { Allow: allowed });
+
+	try {
+		// Defence in depth: the guard already did both in live mode.
+		if (ctx.mode === 'live' && !ctx.person) return json(401, { error: 'signed-out', code: 'signed-out' } satisfies ApiError);
+		if (method !== 'GET') checkOrigin(request);
+		const by = ctx.mode === 'live' ? (ctx.person?.email ?? null) : null;
+
+		if (route === 'upload' && id === undefined) {
+			const refusedMethod = only('POST');
+			if (refusedMethod) return refusedMethod;
+			const side = images(ctx);
+			if (side instanceof Response) {
+				await request.body?.cancel().catch(() => {});
+				return side;
+			}
+			const body = await readCapped(request, MEDIA_MAX_BYTES);
+			if (!body.ok) return json(413, { error: tooLargeMessage(body.size), code: 'too-large' } satisfies MediaRefusal);
+			const stored = await storeUpload(side.library.bucket, { bytes: body.bytes, name: uploadName(request), by }, { head: (key) => side.library.metaOf(key) });
+			if (stored.created) side.library.added(stored.key, stored.meta);
+			const uses = await mediaUses(ctx.store, ctx.site);
+			const status = stored.created ? 201 : 200;
+			if (isFileKey(stored.key)) return json(status, { file: fileEntryOf(stored.key, stored.meta, uses), created: stored.created } satisfies MediaFileUploadResponse);
+			const image = entryOf(side.signing, stored.key, stored.meta, uses);
+			return json(status, { image, created: stored.created } satisfies MediaUploadResponse);
+		}
+
+		if (route === 'images' && id === undefined) {
+			const refusedMethod = only('GET');
+			if (refusedMethod) return refusedMethod;
+			const side = images(ctx);
+			if (side instanceof Response) return side;
+			const uses = await mediaUses(ctx.store, ctx.site);
+			const [listed, files] = await Promise.all([side.library.images(side.signing, uses), side.library.files(uses)]);
+			return json(200, { images: listed, files } satisfies MediaImagesResponse);
+		}
+
+		if (route === 'replace' && id === undefined) {
+			const refusedMethod = only('POST');
+			if (refusedMethod) return refusedMethod;
+			const side = images(ctx);
+			if (side instanceof Response) {
+				await request.body?.cancel().catch(() => {});
+				return side;
+			}
+			const body = parseReplaceBody(await readJson(request, '{ "from": "<the file\'s key>", "to": "<the new file\'s key>" }'));
+			if (!(await side.library.metaOf(body.to))) return json(404, { error: "The new file isn't in the library, so nothing was changed. Upload it again.", code: 'not-found' } satisfies ApiError);
+			const context = { person: ctx.person, tab: tabOf(request), release: request.headers.get(RELEASE_HEADER) === '1', seq: seqOf(request) };
+			return json(200, (await ctx.store.replaceFile(body, context)) satisfies ReplaceFileResponse);
+		}
+
+		if (route === 'thumbnail' && id === undefined) {
+			const refusedMethod = only('GET');
+			if (refusedMethod) return refusedMethod;
+			const side = images(ctx);
+			if (side instanceof Response) return side;
+			const key = url.searchParams.get('key') ?? '';
+			const width = Number(url.searchParams.get('width') ?? '320');
+			if (!UPLOAD_KEY.test(key) || !key.startsWith(UPLOADS) || isFileKey(key)) return json(400, { error: 'key must be an image upload\'s key (uploads/<hash>/<name>); a file has no thumbnail.' } satisfies ApiError);
+			if (!IMAGE_WIDTHS.includes(width)) return json(400, { error: `width must be one of ${IMAGE_WIDTHS.join(', ')}.` } satisfies ApiError);
+			return new Response(null, { status: 302, headers: { Location: thumbnailUrl(side.signing, key, width), 'Cache-Control': 'private, no-store' } });
+		}
+
+		// ── Clips ──
+		const known = route === 'video-upload' || route === 'clips' || route === 'playback';
+		if (!known || extra !== undefined || (route === 'playback' && id === undefined)) return json(404, { error: 'Not found.' } satisfies ApiError);
+		if (id !== undefined && !MUX_ID.test(id)) return json(404, { error: 'Not found.' } satisfies ApiError);
+
+		if (route === 'video-upload' && id === undefined) {
+			const refusedMethod = only('POST');
+			if (refusedMethod) return refusedMethod;
+			const client = mux(ctx);
+			if (client instanceof Response) return client;
+			// cors_origin is the request's own origin, as the browser sent it (checkOrigin has
+			// matched its host to this request's). No Origin, no upload: Mux takes the PUT only from it.
+			const origin = request.headers.get('origin');
+			if (!origin || origin === 'null') return json(403, { error: 'Video uploads are only accepted from the editor on this site.' } satisfies ApiError);
+			const body = await readJson(request);
+			const title = clipTitle(body.name);
+			if (!title) return json(400, { error: 'Send the file name: { "name": "<file name>" }.' } satisfies ApiError);
+			const upload = await client.createUpload(new URL(origin).origin, title);
+			return json(201, upload satisfies VideoUploadResponse);
+		}
+
+		const refusedMethod = only('GET');
+		if (refusedMethod) return refusedMethod;
+		const client = mux(ctx);
+		if (client instanceof Response) return client;
+		if (route === 'video-upload') return json(200, (await client.upload(id!)) satisfies VideoUploadStatus);
+		const uses = await mediaUses(ctx.store, ctx.site);
+		if (route === 'clips' && id === undefined) return json(200, { clips: (await client.clips()).map((c) => withUses(c, uses)) } satisfies MediaClipsResponse);
+		if (route === 'clips') return json(200, withUses(await client.clip(id!), uses) satisfies LibraryClip);
+		return json(200, withUses(await client.clipOfPlayback(id!), uses) satisfies LibraryClip);
+	} catch (error) {
+		if (error instanceof UploadRefused) return json(error.status, { error: error.message, code: error.code } satisfies MediaRefusal);
+		if (error instanceof MuxRouteError) return json(error.status, { error: error.message } satisfies ApiError);
+		if (error instanceof WriteRefused) return json(error.status, { error: error.message, ...error.body });
+		if (error instanceof BucketError) {
+			log(`[caracms] media bucket: ${error.message}`);
+			const said = error.status !== null && error.status >= 400 && error.status < 500;
+			return json(502, { error: said ? 'The media bucket refused that, so nothing was stored.' : "The media bucket didn't answer, so nothing was stored. Try again in a moment." } satisfies ApiError);
+		}
+		log(`[caracms] ${url.pathname} failed: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}`);
+		return json(500, { error: 'Something went wrong with the media library.' } satisfies ApiError);
+	}
+}

package/src/editor/server/media/library.ts

@@ -0,0 +1,254 @@
+/**
+ * The library (M5b Decision 7): the bucket's `uploads/` as `LibraryImage`s, newest first,
+ * each with where it's used and an alt text already used for it.
+ *
+ * - **Where it's used** is worked out from the store on every listing (`mediaUses`): each
+ *   document in the store's listing (the `drafts` copy with autosaves in live mode, the
+ *   disk in local mode), read whole, any value with an image `key` or a clip `video` in
+ *   it, in any block, a kept unknown one and the brand's logo included (the content still
+ *   names it, so it's used). **An alt text already used** is the first non-empty one in
+ *   the listing's document order, decorative ones skipped (nothing records which was
+ *   written last).
+ *   **A focal point already set** is chosen the same way, on its own: the first one in the
+ *   listing's document order, whether or not that use has the alt text, decorative ones
+ *   included (a focal point is a spot on the photo, not on a crop or a meaning).
+ * - **Cost:** the bucket's listing is kept per process for 60 seconds, and this process's
+ *   own uploads are added at once (an upload from another place the site runs shows within
+ *   a minute). **An object's metadata is kept by key for the life of the process**: a key
+ *   never changes what it points at. No paging in v1.
+ * - **M6c G4: files** (`caracms/files`' types) are listed beside the images, each with the
+ *   documents that **link** to it, found by schema (relink.ts → `fileLinksIn`: link fields,
+ *   buttons and rich text, in blocks, page fields, fields documents, shared blocks and
+ *   Site Settings), so a plain-text mention of its address doesn't count (Decision 8).
+ * - **Thumbnails are signed URLs in the listing** (`thumbnail`, `thumbnail2x`: `rs:fit` at
+ *   320 and 640, rungs of the page's ladder, so they share its cache). The signing key
+ *   never leaves the server; the bucket key is in every image path anyway.
+ */
+import { join } from 'node:path';
+import type { ResolvedSite } from '../../../config.ts';
+import { fileTypeOf, isFileKey } from '../../../files.ts';
+import { isClipValue, isImageValue, parseFocal } from '../../../media-value.ts';
+import { thumbnailUrl, type MediaSettings } from '../../../media.ts';
+import { fileLinksIn } from '../../../relink.ts';
+import type { FileUse, LibraryFile, LibraryImage, MediaUse } from '../../types.ts';
+import type { DraftsStore } from '../drafts-store.ts';
+import type { Bucket, BucketObject, ObjectMeta } from './bucket.ts';
+import { onMediaReset } from './memory.ts';
+
+/** The prefix every upload goes under (Decision 6). */
+export const UPLOADS = 'uploads/';
+export const LISTING_TTL_MS = 60_000;
+const IMAGE_KEY = /^uploads\/[^/]+\/[^/]+\.(?:jpe?g|png|webp|avif|heic|heif|gif|svg)$/i;
+const HEAD_CONCURRENCY = 8;
+
+export interface MediaUses {
+	/** Image key → the documents that use it, the first non-empty alt text and the first focal point. */
+	images: Map<string, { usedIn: MediaUse[]; alt: string | null; focal: [number, number] | null }>;
+	/** Playback ID → the documents that use it. */
+	clips: Map<string, MediaUse[]>;
+	/** M6c G4: a file's key → the documents that link to it (by schema), with how many links each. */
+	files: Map<string, FileUse[]>;
+}
+
+/** Every image and clip the store's documents name, and every file they link to, in the listing's order. */
+export async function mediaUses(store: DraftsStore, site: Pick<ResolvedSite, 'root' | 'collections' | 'blocks'>): Promise<MediaUses> {
+	const entries = await store.list();
+	const source = await store.source();
+	const texts = await Promise.all(entries.map((e) => source.readText(join(site.root, e.file)).catch(() => null)));
+	const images: MediaUses['images'] = new Map();
+	const clips: MediaUses['clips'] = new Map();
+	const files: MediaUses['files'] = new Map();
+	entries.forEach((entry, i) => {
+		const text = texts[i];
+		if (!text) return;
+		let raw: unknown;
+		try {
+			raw = JSON.parse(text);
+		} catch {
+			return;
+		}
+		const use: MediaUse = { collection: entry.collection, path: entry.path, title: entry.label };
+		const collection = site.collections[entry.collection];
+		if (collection) {
+			for (const link of fileLinksIn(text, site, collection)) {
+				let list = files.get(link.key);
+				if (!list) files.set(link.key, (list = []));
+				const mine = list.find((u) => u.collection === use.collection && u.path === use.path);
+				if (mine) mine.links++;
+				else list.push({ ...use, links: 1 });
+			}
+		}
+		const add = (list: MediaUse[]) => {
+			if (!list.some((u) => u.collection === use.collection && u.path === use.path)) list.push(use);
+		};
+		walk(raw, (value) => {
+			if (isImageValue(value)) {
+				const key = value.key.trim();
+				let found = images.get(key);
+				if (!found) images.set(key, (found = { usedIn: [], alt: null, focal: null }));
+				add(found.usedIn);
+				const alt = typeof value.alt === 'string' ? value.alt.trim() : '';
+				if (found.alt === null && alt && value.decorative !== true) found.alt = alt;
+				found.focal ??= parseFocal(value.focal) ?? null;
+				return true;
+			}
+			if (isClipValue(value)) {
+				const playbackId = value.video.trim();
+				let found = clips.get(playbackId);
+				if (!found) clips.set(playbackId, (found = []));
+				add(found);
+				return true;
+			}
+			return false;
+		});
+	});
+	return { images, clips, files };
+}
+
+/** Every object and array in `value`, depth first in document order; `visit` returning true stops the descent there. */
+function walk(value: unknown, visit: (value: Record<string, unknown>) => boolean, depth = 0): void {
+	if (depth > 64 || !value || typeof value !== 'object') return;
+	if (Array.isArray(value)) {
+		for (const item of value) walk(item, visit, depth + 1);
+		return;
+	}
+	const object = value as Record<string, unknown>;
+	if (visit(object)) return;
+	for (const child of Object.values(object)) walk(child, visit, depth + 1);
+}
+
+/** The bucket's listing and metadata, cached as Decision 7 says. One per bucket, per process. */
+export class Library {
+	private listing: { at: number; objects: Map<string, BucketObject> } | null = null;
+	private loading: Promise<Map<string, BucketObject>> | null = null;
+	private readonly meta = new Map<string, ObjectMeta>();
+
+	readonly bucket: Bucket;
+	private readonly now: () => number;
+
+	constructor(bucket: Bucket, now: () => number = () => Date.now()) {
+		this.bucket = bucket;
+		this.now = now;
+	}
+
+	/** The objects under `uploads/`: the bucket's listing, at most 60 s old, with this process's uploads in it. */
+	async objects(): Promise<BucketObject[]> {
+		if (!this.listing || this.now() - this.listing.at >= LISTING_TTL_MS) {
+			this.loading ??= this.bucket
+				.list(UPLOADS)
+				.then((list) => {
+					const objects = new Map(list.filter((o) => IMAGE_KEY.test(o.key) || isFileKey(o.key)).map((o) => [o.key, o]));
+					// An upload this process made while the listing was on its way stays in it.
+					for (const [key, o] of this.listing?.objects ?? []) if (!objects.has(key) && this.meta.has(key)) objects.set(key, o);
+					this.listing = { at: this.now(), objects };
+					return objects;
+				})
+				.finally(() => {
+					this.loading = null;
+				});
+			await this.loading;
+		}
+		return [...this.listing!.objects.values()];
+	}
+
+	/** An object's metadata: kept for the process once read (a key never changes). Null: no such object. */
+	async metaOf(key: string): Promise<ObjectMeta | null> {
+		const kept = this.meta.get(key);
+		if (kept) return kept;
+		const meta = await this.bucket.head(key);
+		if (meta) this.meta.set(key, meta);
+		return meta;
+	}
+
+	/** This process's own upload: in the listing and the metadata at once. */
+	added(key: string, meta: ObjectMeta): void {
+		this.meta.set(key, meta);
+		this.listing?.objects.set(key, { key, lastModified: meta.lastModified, size: meta.size });
+	}
+
+	/** The library's images, newest first, each with where it's used. */
+	async images(signing: MediaSettings, uses: MediaUses): Promise<LibraryImage[]> {
+		return (await this.read((key) => !isFileKey(key))).map(([key, meta]) => entryOf(signing, key, meta, uses));
+	}
+
+	/** M6c G4: the library's files, newest first, each with what links to it. */
+	async files(uses: MediaUses): Promise<LibraryFile[]> {
+		return (await this.read(isFileKey)).map(([key, meta]) => fileEntryOf(key, meta, uses));
+	}
+
+	/** The listing's objects that `which` keeps, with their metadata, newest first (one gone since the listing is left out). */
+	private async read(which: (key: string) => boolean): Promise<[string, ObjectMeta][]> {
+		const objects = (await this.objects()).filter((o) => which(o.key));
+		const metas = await mapLimit(objects, HEAD_CONCURRENCY, (o) => this.metaOf(o.key));
+		const out: [string, ObjectMeta][] = [];
+		objects.forEach((o, i) => {
+			const meta = metas[i];
+			if (meta === null) return; // gone between listing and reading: not shown
+			out.push([o.key, { ...meta!, lastModified: o.lastModified ?? meta!.lastModified, size: o.size ?? meta!.size }]);
+		});
+		return out.sort(([ak, a], [bk, b]) => (b.lastModified ?? '').localeCompare(a.lastModified ?? '') || ak.localeCompare(bk));
+	}
+}
+
+/** M6c G4: one file's library entry. */
+export function fileEntryOf(key: string, meta: ObjectMeta, uses: MediaUses): LibraryFile {
+	return {
+		kind: 'file',
+		key,
+		name: meta.name || key.slice(key.lastIndexOf('/') + 1),
+		type: fileTypeOf(key)?.label ?? '',
+		bytes: meta.size,
+		uploadedAt: meta.lastModified,
+		by: meta.by || null,
+		usedIn: uses.files.get(key) ?? [],
+	};
+}
+
+/** One image's library entry. */
+export function entryOf(signing: MediaSettings, key: string, meta: ObjectMeta, uses: MediaUses): LibraryImage {
+	const used = uses.images.get(key);
+	return {
+		kind: 'image',
+		key,
+		name: meta.name || key.slice(key.lastIndexOf('/') + 1),
+		w: meta.w,
+		h: meta.h,
+		bytes: meta.size,
+		uploadedAt: meta.lastModified,
+		by: meta.by || null,
+		thumbnail: thumbnailUrl(signing, key, 320),
+		thumbnail2x: thumbnailUrl(signing, key, 640),
+		usedIn: used?.usedIn ?? [],
+		alt: used?.alt ?? null,
+		focal: used?.focal ?? null,
+	};
+}
+
+async function mapLimit<T, R>(items: readonly T[], limit: number, fn: (item: T) => Promise<R>): Promise<R[]> {
+	const out = new Array<R>(items.length);
+	let next = 0;
+	const worker = async () => {
+		while (next < items.length) {
+			const i = next++;
+			out[i] = await fn(items[i]!);
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+	return out;
+}
+
+const SHARED = Symbol.for('caracms.mediaLibraries');
+type Shared = { [SHARED]?: Map<string, Library> };
+
+/** The process's library for a bucket (by `id`: `memory`, or the endpoint, bucket and access key). */
+export function libraryFor(id: string, make: () => Bucket): Library {
+	const g = globalThis as Shared;
+	if (!g[SHARED]) {
+		g[SHARED] = new Map();
+		const libraries = g[SHARED];
+		onMediaReset(() => libraries.clear());
+	}
+	let library = g[SHARED].get(id);
+	if (!library) g[SHARED].set(id, (library = new Library(make())));
+	return library;
+}

package/src/editor/server/media/memory.ts

@@ -0,0 +1,184 @@
+/**
+ * `CARACMS_MEDIA=memory` (M5b Decision 5): an in-memory bucket and a fake Mux, one of
+ * each per process, so a test (or a browser test, whose dev server runs in the test's
+ * process) can seed them and look at what the routes did. **Refused on a production
+ * server** (config.ts), and **it always wins**: with it set, nothing touches the real
+ * bucket or Mux, whatever else is set.
+ *
+ *   const media = memoryMedia();
+ *   media.bucket.seed('uploads/3f9a1c07b2e4/harbour-wall.jpg', { w: 4000, h: 2667, name: 'Harbour wall.jpg', uploadedAt: '2026-10-16T09:00:00Z' });
+ *   media.mux.seedClip({ playbackId: 'abc', title: 'Kiln', mp4: 'ready' });           // placeable
+ *   media.mux.seedClip({ playbackId: 'def', mp4: 'preparing' });                       // processing
+ *   media.mux.seedClip({ status: 'errored', error: { type: 'invalid_input', messages: ['no video track'] } });
+ *   media.reset();                                                                     // empty again, caches dropped
+ *
+ * The fake Mux is a `fetch` that answers Mux's API (`/video/v1/uploads`, `/assets`,
+ * `/playback-ids`), paging the list with `next_cursor`, so the real client (mux.ts) runs
+ * against it. A direct upload's `url` is `https://mux.test/upload/<id>`: a browser test
+ * routes that PUT itself, then calls `receive(id)` (the file arrived: an asset, preparing)
+ * and `ready(assetId)` (the asset and its MP4 are ready).
+ */
+import { MemoryBucket } from './bucket.ts';
+import { MUX_API } from './mux.ts';
+
+type Json = any;
+
+export interface SeedClip {
+	id?: string;
+	playbackId?: string | null;
+	/** Mux's asset status. Default `ready`. */
+	status?: 'preparing' | 'ready' | 'errored';
+	/** The `highest` MP4's status; `none` for an asset with no static rendition. Default `ready`. */
+	mp4?: 'ready' | 'preparing' | 'errored' | 'skipped' | 'none';
+	title?: string | null;
+	duration?: number;
+	w?: number;
+	h?: number;
+	/** ISO. Default now. */
+	createdAt?: string;
+	error?: { type?: string; messages?: string[] };
+}
+
+let counter = 0;
+const id = (prefix: string) => `${prefix}${(++counter).toString(36).padStart(6, '0')}${Math.random().toString(36).slice(2, 10)}`.replace(/[^A-Za-z0-9]/g, '');
+
+export class MemoryMux {
+	readonly assets = new Map<string, Json>();
+	readonly uploads = new Map<string, Json>();
+	/** Every request the fake answered: `{ method, path, body }` (the upload settings and `cors_origin` are checked from here). */
+	readonly requests: { method: string; path: string; body: Json }[] = [];
+	/** The next request answers this instead (a full plan, a refused token). */
+	failNext: { status: number; body: string } | null = null;
+	/** The list's page size (Mux's is up to 100), small in tests of the cursor. */
+	pageSize = 100;
+	now: () => number = () => Date.now();
+
+	seedClip(seed: SeedClip = {}): string {
+		const assetId = seed.id ?? id('asset');
+		const playbackId = seed.playbackId === undefined ? id('pb') : seed.playbackId;
+		const mp4 = seed.mp4 ?? 'ready';
+		this.assets.set(assetId, {
+			id: assetId,
+			status: seed.status ?? 'ready',
+			created_at: String(Math.floor((seed.createdAt ? Date.parse(seed.createdAt) : this.now()) / 1000)),
+			duration: seed.duration ?? 12.5,
+			aspect_ratio: '16:9',
+			playback_ids: playbackId ? [{ id: playbackId, policy: 'public' }] : [],
+			static_renditions: mp4 === 'none' ? undefined : { files: [{ resolution: 'highest', name: 'highest.mp4', status: mp4 }] },
+			tracks: [{ type: 'video', max_width: seed.w ?? 1920, max_height: seed.h ?? 1080 }],
+			meta: seed.title === null ? {} : { title: seed.title ?? 'A clip' },
+			...(seed.error ? { errors: seed.error } : {}),
+		});
+		return assetId;
+	}
+
+	/** An upload's file has arrived: Mux makes its asset, preparing, with its MP4 to come. Returns the asset id. */
+	receive(uploadId: string, seed: Omit<SeedClip, 'id' | 'status' | 'mp4'> = {}): string {
+		const upload = this.uploads.get(uploadId);
+		if (!upload) throw new Error(`no upload ${uploadId}`);
+		const assetId = this.seedClip({ ...seed, title: seed.title ?? upload.new_asset_settings?.meta?.title ?? null, status: 'preparing', mp4: 'preparing' });
+		upload.status = 'asset_created';
+		upload.asset_id = assetId;
+		return assetId;
+	}
+
+	/** The asset and its MP4 are ready (or set any part: `{ status, mp4 }`). */
+	ready(assetId: string, to: { status?: SeedClip['status']; mp4?: Exclude<SeedClip['mp4'], 'none'> } = {}): void {
+		const asset = this.assets.get(assetId);
+		if (!asset) throw new Error(`no asset ${assetId}`);
+		asset.status = to.status ?? 'ready';
+		asset.static_renditions = { files: [{ resolution: 'highest', name: 'highest.mp4', status: to.mp4 ?? 'ready' }] };
+	}
+
+	clear(): void {
+		this.assets.clear();
+		this.uploads.clear();
+		this.requests.length = 0;
+		this.failNext = null;
+		this.pageSize = 100;
+	}
+
+	/** Mux's API, in memory: what the client (mux.ts) is given as its `fetch`. */
+	readonly fetch: typeof fetch = async (input, init) => {
+		const url = new URL(typeof input === 'string' ? input : input instanceof URL ? input.href : input.url);
+		const method = (init?.method ?? 'GET').toUpperCase();
+		const body = typeof init?.body === 'string' ? (JSON.parse(init.body) as Json) : null;
+		const path = url.pathname;
+		this.requests.push({ method, path: path + url.search, body });
+		const reply = (status: number, value: unknown) => new Response(typeof value === 'string' ? value : JSON.stringify(value), { status, headers: { 'Content-Type': 'application/json' } });
+		if (url.origin !== MUX_API) return reply(404, { error: { type: 'not_found', messages: ['not Mux'] } });
+		if (this.failNext) {
+			const { status, body: text } = this.failNext;
+			this.failNext = null;
+			return reply(status, text);
+		}
+		const notFound = () => reply(404, { error: { type: 'not_found', messages: ['The requested resource does not exist.'] } });
+		let m: RegExpExecArray | null;
+		if (path === '/video/v1/uploads' && method === 'POST') {
+			const uploadId = id('up');
+			const upload = { id: uploadId, url: `https://mux.test/upload/${uploadId}`, status: 'waiting', cors_origin: body?.cors_origin, new_asset_settings: body?.new_asset_settings, asset_id: undefined as string | undefined };
+			this.uploads.set(uploadId, upload);
+			return reply(201, { data: upload });
+		}
+		if ((m = /^\/video\/v1\/uploads\/([^/]+)$/.exec(path)) && method === 'GET') {
+			const upload = this.uploads.get(m[1]!);
+			return upload ? reply(200, { data: upload }) : notFound();
+		}
+		if (path === '/video/v1/assets' && method === 'GET') {
+			const all = [...this.assets.values()];
+			const start = Number(url.searchParams.get('cursor') ?? '0') || 0;
+			const size = Math.min(this.pageSize, Number(url.searchParams.get('limit') ?? '100') || 100);
+			const page = all.slice(start, start + size);
+			const next = start + size < all.length ? String(start + size) : null;
+			return reply(200, { data: page, next_cursor: next });
+		}
+		if ((m = /^\/video\/v1\/assets\/([^/]+)$/.exec(path)) && method === 'GET') {
+			const asset = this.assets.get(m[1]!);
+			return asset ? reply(200, { data: asset }) : notFound();
+		}
+		if ((m = /^\/video\/v1\/playback-ids\/([^/]+)$/.exec(path)) && method === 'GET') {
+			for (const asset of this.assets.values()) {
+				if ((asset.playback_ids as Json[]).some((p) => p.id === m![1])) return reply(200, { data: { id: m[1], policy: 'public', object: { type: 'asset', id: asset.id } } });
+			}
+			// Mux's answer for an ID from another environment.
+			return reply(400, { error: { type: 'invalid_parameters', messages: ['Playback ID belongs to a mismatching environment'] } });
+		}
+		return notFound();
+	};
+}
+
+export interface MemoryMedia {
+	bucket: MemoryBucket;
+	mux: MemoryMux;
+	/** Empty both, and drop the library's caches (library.ts). */
+	reset(): void;
+}
+
+const SHARED = Symbol.for('caracms.memoryMedia');
+const RESETS = Symbol.for('caracms.mediaCaches');
+type Shared = { [SHARED]?: MemoryMedia; [RESETS]?: Set<() => void> };
+
+/** Register a cache to drop on `reset()` (library.ts's listing and metadata caches). */
+export function onMediaReset(fn: () => void): void {
+	const g = globalThis as Shared;
+	(g[RESETS] ??= new Set()).add(fn);
+}
+
+/** The process's in-memory bucket and fake Mux. */
+export function memoryMedia(): MemoryMedia {
+	const g = globalThis as Shared;
+	if (!g[SHARED]) {
+		const bucket = new MemoryBucket();
+		const mux = new MemoryMux();
+		g[SHARED] = {
+			bucket,
+			mux,
+			reset() {
+				bucket.clear();
+				mux.clear();
+				for (const fn of g[RESETS] ?? []) fn();
+			},
+		};
+	}
+	return g[SHARED];
+}