emdash 0.35.0 → 0.36.0

package/src/emdash-runtime.ts

@@ -9,10 +9,11 @@
 
 import { Permissions } from "@emdash-cms/auth";
 import type { Element } from "@emdash-cms/blocks";
-import { Kysely, sql, type Dialect } from "kysely";
+import { Kysely, type Dialect } from "kysely";
 import virtualConfig from "virtual:emdash/config";
 import { z } from "zod";
 
+import { ErrorCode } from "./api/errors.js";
 import { assertMediaUsageActivationWriteAllowed } from "./api/media-usage-write-fence.js";
 import { validateRev } from "./api/rev.js";
 import type {
@@ -43,30 +44,20 @@ import type {
 	ContentItem as ContentItemInternal,
 	ContentDateField,
 } from "./database/repositories/types.js";
+import type { ImageValue } from "./fields/types.js";
 import { getI18nConfig } from "./i18n/config.js";
 import { repairLocaleCasing } from "./i18n/repair-locale-casing.js";
 import { warnAboutUnconfiguredTaxonomyLocales } from "./i18n/taxonomy-locale-diagnostic.js";
 import { normalizeMediaValue } from "./media/normalize.js";
 import type { MediaProvider, MediaProviderCapabilities } from "./media/types.js";
-import {
-	MEDIA_USAGE_COLLECTION_DELETION_LIMITS,
-	processDueMediaUsageCollectionDeletions,
-} from "./media/usage/collection-deletion-processor.js";
+import { activateMediaUsageCapture } from "./media/usage/activation.js";
 import {
 	deleteContentMediaUsage,
 	findNonTranslatableSiblingContentIds,
 	markContentMediaUsageCollectionStale,
 	refreshContentMediaUsageAfterWrite,
 } from "./media/usage/content-refresh.js";
-import {
-	MEDIA_USAGE_RECONCILIATION_LIMITS,
-	processDueMediaUsageReconciliation,
-} from "./media/usage/reconciliation-processor.js";
-import {
-	MEDIA_USAGE_WORK_PROCESSING_LIMITS,
-	processDueMediaUsageWork,
-	processMediaUsageWorkAfterWrite,
-} from "./media/usage/work-processor.js";
+import { processMediaUsageWorkAfterWrite } from "./media/usage/work-processor.js";
 import { createSandboxRunnerOptions } from "./plugins/sandbox/runner-options.js";
 import { getSandboxRouteErrorDetails } from "./plugins/sandbox/types.js";
 import type {
@@ -227,6 +218,7 @@ import {
 	type RouteCallerInput,
 	type RouteMeta,
 } from "./plugins/routes.js";
+import { isContentSaveRejection } from "./plugins/save-rejection.js";
 import type { CronScheduler } from "./plugins/scheduler/types.js";
 import { PluginStateRepository } from "./plugins/state.js";
 import { syncDeclaredStorageIndexes } from "./plugins/storage-indexes.js";
@@ -434,6 +426,28 @@ export interface EmDashRuntimeParts {
 	pipelineRef: { current: HookPipeline };
 }
 
+/**
+ * A `ContentSaveRejectedError` carries a message the plugin wrote for the
+ * editor; every other exception stays internal and is replaced by a generic
+ * message so hook internals cannot leak through the API.
+ */
+function beforeSaveFailure(error: unknown) {
+	if (isContentSaveRejection(error)) {
+		return {
+			success: false as const,
+			error: { code: ErrorCode.SAVE_REJECTED, message: error.message },
+		};
+	}
+	console.error("EmDash: content:beforeSave hook failed:", error);
+	return {
+		success: false as const,
+		error: {
+			code: ErrorCode.CONTENT_HOOK_ERROR,
+			message: "A plugin hook failed while saving content",
+		},
+	};
+}
+
 /**
  * Convert a ContentItem to Record<string, unknown> for hook consumption.
  * Hooks receive the full item as a flat record.
@@ -553,62 +567,6 @@ const marketplaceManifestCache = new Map<
 const sandboxedRouteMetaCache = new Map<string, Map<string, RouteMeta>>();
 let sandboxRunner: SandboxRunner | null = null;
 
-export const MEDIA_USAGE_MAINTENANCE_QUERY_RESERVATIONS = Object.freeze({
-	entryWork: MEDIA_USAGE_WORK_PROCESSING_LIMITS.ordinaryStatementsPerJob,
-	collectionDeletion: MEDIA_USAGE_COLLECTION_DELETION_LIMITS.maxQueriesPerTick,
-	reconciliation: MEDIA_USAGE_RECONCILIATION_LIMITS.maxQueriesPerTick,
-	maxClassQueries: Math.max(
-		MEDIA_USAGE_WORK_PROCESSING_LIMITS.ordinaryStatementsPerJob,
-		MEDIA_USAGE_COLLECTION_DELETION_LIMITS.maxQueriesPerTick,
-		MEDIA_USAGE_RECONCILIATION_LIMITS.maxQueriesPerTick,
-	),
-	eventCeiling: 40,
-});
-
-export type MediaUsageMaintenanceTaskClass =
-	| "entry_work"
-	| "collection_deletion"
-	| "reconciliation";
-
-export type MediaUsageMaintenanceResult =
-	| { outcome: "inactive" | "admission_closed"; taskClass: null; turn: null }
-	| { outcome: "processed"; taskClass: MediaUsageMaintenanceTaskClass; turn: number };
-
-async function runScheduledMediaUsageLane(
-	db: Kysely<Database>,
-): Promise<MediaUsageMaintenanceResult> {
-	const queriesAlreadySpent = getRequestContext()?.metrics?.dbCount ?? 0;
-	if (
-		queriesAlreadySpent + 1 + MEDIA_USAGE_MAINTENANCE_QUERY_RESERVATIONS.maxClassQueries >
-		MEDIA_USAGE_MAINTENANCE_QUERY_RESERVATIONS.eventCeiling
-	) {
-		return { outcome: "admission_closed", taskClass: null, turn: null };
-	}
-
-	const activation = await db
-		.updateTable("_emdash_media_usage_activation")
-		.set({
-			media_usage_maintenance_turn: sql<number>`(media_usage_maintenance_turn + 1) % 3`,
-		})
-		.where("task_key", "=", "incremental_capture")
-		.where("state", "=", "active")
-		.returning("media_usage_maintenance_turn")
-		.executeTakeFirst();
-	if (!activation) return { outcome: "inactive", taskClass: null, turn: null };
-
-	const turn = activation.media_usage_maintenance_turn;
-	if (turn === 0) {
-		await processDueMediaUsageWork(db);
-		return { outcome: "processed", taskClass: "entry_work", turn };
-	}
-	if (turn === 1) {
-		await processDueMediaUsageCollectionDeletions(db);
-		return { outcome: "processed", taskClass: "collection_deletion", turn };
-	}
-	await processDueMediaUsageReconciliation(db);
-	return { outcome: "processed", taskClass: "reconciliation", turn };
-}
-
 /**
  * EmDashRuntime - singleton per worker
  */
@@ -814,10 +772,6 @@ export class EmDashRuntime {
 		return { published };
 	}
 
-	async runScheduledMediaUsageTasks(): Promise<MediaUsageMaintenanceResult> {
-		return runScheduledMediaUsageLane(this.db);
-	}
-
 	/**
 	 * Materialize plugin-declared storage indexes, once per process.
 	 *
@@ -1448,6 +1402,15 @@ export class EmDashRuntime {
 		// per-isolate lock keyed by the configured db so a reclaimed-and-rerun
 		// create() can't apply the seed a second time concurrently.
 		if (seedGate.collectionCount === 0 && !seedGate.setupDone) {
+			try {
+				const activation = await activateMediaUsageCapture(db, { writersDrained: true });
+				if (activation.outcome !== "active") {
+					throw new Error("Fresh-site media usage activation did not complete");
+				}
+			} catch (error) {
+				await disposeReadDb();
+				throw error;
+			}
 			const seedKey = deps.config.database?.entrypoint ?? "default";
 			const seedHolder = getSeedHolder();
 			try {
@@ -1756,14 +1719,6 @@ export class EmDashRuntime {
 				if (deps.createScheduler) {
 					const scheduler = deps.createScheduler(cronExecutor);
 					cronScheduler = scheduler;
-					const runMediaUsageMaintenance = async () => {
-						const runtime = runtimeRef.current;
-						if (runtime) {
-							await runtime.runScheduledMediaUsageTasks();
-						} else {
-							await runScheduledMediaUsageLane(db);
-						}
-					};
 
 					// Run scheduled publishing and system cleanup alongside each tick.
 					// Pass storage so cleanupPendingUploads can delete orphaned files.
@@ -1797,16 +1752,7 @@ export class EmDashRuntime {
 						// Never throws; no-op unless scheduled backups are enabled and due.
 						await maybeRunScheduledBackup(db, storage ?? undefined);
 						await recordSchedulerHeartbeatSafely(db);
-						if (!scheduler.setMediaUsageMaintenance) {
-							try {
-								await runMediaUsageMaintenance();
-							} catch (error) {
-								console.error("[media-usage] Scheduled maintenance failed:", error);
-							}
-						}
 					});
-					scheduler.setMediaUsageMaintenance?.(runMediaUsageMaintenance);
-
 					// start() is void on the timer scheduler but the interface
 					// allows a promise (alarm-backed schedulers); we don't block on it.
 					void scheduler.start();
@@ -2969,8 +2915,12 @@ export class EmDashRuntime {
 		// Run beforeSave hooks (trusted plugins)
 		let processedData = body.data;
 		if (this.hooks.hasHooks("content:beforeSave")) {
-			const hookResult = await this.hooks.runContentBeforeSave(body.data, collection, true);
-			processedData = hookResult.content;
+			try {
+				const hookResult = await this.hooks.runContentBeforeSave(body.data, collection, true);
+				processedData = hookResult.content;
+			} catch (error) {
+				return beforeSaveFailure(error);
+			}
 		}
 
 		// Run beforeSave hooks (sandboxed plugins)
@@ -3065,12 +3015,16 @@ export class EmDashRuntime {
 		let processedData = bodyWithoutRev.data;
 		if (bodyWithoutRev.data) {
 			if (this.hooks.hasHooks("content:beforeSave")) {
-				const hookResult = await this.hooks.runContentBeforeSave(
-					bodyWithoutRev.data,
-					collection,
-					false,
-				);
-				processedData = hookResult.content;
+				try {
+					const hookResult = await this.hooks.runContentBeforeSave(
+						bodyWithoutRev.data,
+						collection,
+						false,
+					);
+					processedData = hookResult.content;
+				} catch (error) {
+					return beforeSaveFailure(error);
+				}
 			}
 
 			// Run sandboxed beforeSave hooks
@@ -3456,9 +3410,11 @@ export class EmDashRuntime {
 
 	async handleMediaList(params: {
 		cursor?: string;
+		page?: number;
 		limit?: number;
 		mimeType?: string | readonly string[];
 		q?: string;
+		folderId?: string | null;
 	}) {
 		return handleMediaList(this.db, params);
 	}
@@ -3519,7 +3475,15 @@ export class EmDashRuntime {
 
 	async handleMediaUpdate(
 		id: string,
-		input: { alt?: string; caption?: string; width?: number; height?: number },
+		input: {
+			alt?: string;
+			caption?: string;
+			width?: number;
+			height?: number;
+			folderId?: string | null;
+			focalX?: number | null;
+			focalY?: number | null;
+		},
 	) {
 		const result = await handleMediaUpdate(this.db, id, input);
 		// Resolved media references in site settings (`logo`, `favicon`,
@@ -3690,14 +3654,14 @@ export class EmDashRuntime {
 		for (const contentId of new Set(contentIds)) {
 			try {
 				const work = await processMediaUsageWorkAfterWrite(this.db, collection, contentId);
-				if (work.outcome !== "inactive") return;
+				if (work.outcome !== "inactive") continue;
 				await refreshContentMediaUsageAfterWrite(this.db, collection, contentId);
 			} catch (error) {
 				console.error(
 					`[media-usage] Failed after content write ${collection}/${contentId}:`,
 					error,
 				);
-				return;
+				continue;
 			}
 		}
 	}
@@ -4056,7 +4020,11 @@ export class EmDashRuntime {
 			if (value == null) continue;
 
 			try {
-				const normalized = await normalizeMediaValue(value, getProvider);
+				// Only image fields carry a dark variant.
+				const normalized =
+					field.type === "image"
+						? await normalizeImageValue(value, getProvider)
+						: await normalizeMediaValue(value, getProvider);
 				if (normalized) {
 					result[field.slug] = normalized;
 				}
@@ -4083,7 +4051,7 @@ export class EmDashRuntime {
 						const subValue = normalizedItem[slug];
 						if (subValue == null) continue;
 						try {
-							const normalized = await normalizeMediaValue(subValue, getProvider);
+							const normalized = await normalizeImageValue(subValue, getProvider);
 							if (normalized) {
 								normalizedItem[slug] = normalized;
 							}
@@ -4125,7 +4093,10 @@ export class EmDashRuntime {
 					result = record;
 				}
 			} catch (error) {
-				console.error(`EmDash: Sandboxed plugin ${id} beforeSave hook error:`, error);
+				console.error(
+					`EmDash: Sandboxed plugin ${id} beforeSave hook threw; a sandboxed plugin cannot cancel a save, so the save continues:`,
+					error,
+				);
 			}
 		}
 
@@ -4437,3 +4408,37 @@ export class EmDashRuntime {
 		return status === undefined || status === "active";
 	}
 }
+
+/**
+ * Normalize an image field value together with its `darkVariant`. The media
+ * normalizer only keeps the media item's own keys, so the variant is normalized
+ * separately and reattached.
+ */
+async function normalizeImageValue(
+	value: unknown,
+	getProvider: (id: string) => MediaProvider | undefined,
+): Promise<ImageValue | null> {
+	const primary = await normalizePrimaryImageValue(value, getProvider);
+	if (!primary || !isRecord(value) || value.darkVariant == null) return primary;
+	const darkVariant = await normalizeMediaValue(value.darkVariant, getProvider);
+	return darkVariant ? { ...primary, darkVariant } : primary;
+}
+
+/**
+ * Normalize the primary image of an image field value.
+ *
+ * A legacy string URL that the admin upgraded to `{ id: "", src: url }` so it
+ * can carry a dark variant still has to normalize as a string: as an object it
+ * counts as local media, which strips `src` and leaves nothing behind. The
+ * upgrade outlives the variant — an editor can add one and remove it again —
+ * so the shape decides, not the presence of `darkVariant`.
+ */
+async function normalizePrimaryImageValue(
+	value: unknown,
+	getProvider: (id: string) => MediaProvider | undefined,
+): Promise<ImageValue | null> {
+	if (isRecord(value) && !value.id && typeof value.src === "string" && !value.provider) {
+		return normalizeMediaValue(value.src, getProvider);
+	}
+	return normalizeMediaValue(value, getProvider);
+}

package/src/fields/image.ts

@@ -2,7 +2,7 @@ import { z } from "astro/zod";
 
 import type { FieldDefinition, ImageValue } from "./types.js";
 
-const imageSchema = z.object({
+const mediaSchema = z.object({
 	id: z.string(),
 	src: z.string().optional(),
 	alt: z.string().optional(),
@@ -17,10 +17,16 @@ const imageSchema = z.object({
 	meta: z.record(z.string(), z.unknown()).optional(),
 });
 
+const imageSchema = mediaSchema.extend({
+	darkVariant: mediaSchema.optional(),
+});
+
 export interface ImageOptions {
 	required?: boolean;
 	maxSize?: number; // in bytes
 	allowedTypes?: string[]; // MIME types — exact or prefix
+	/** Offer editors a second slot for a dark-color-scheme counterpart of the image. */
+	darkVariant?: boolean;
 }
 
 export function image(options: ImageOptions = {}): FieldDefinition<ImageValue | undefined> {

package/src/fields/types.ts

@@ -51,9 +51,13 @@ export type { MediaValue } from "../media/types.js";
 import type { MediaValue } from "../media/types.js";
 
 /**
- * @deprecated Use MediaValue instead. ImageValue is an alias for backwards compatibility.
+ * Persisted image field value: the media item shown by default, plus an
+ * optional counterpart for dark color schemes.
  */
-export type ImageValue = MediaValue;
+export interface ImageValue extends MediaValue {
+	/** Media item shown instead of the primary one when the page renders in a dark color scheme. */
+	darkVariant?: MediaValue;
+}
 
 /**
  * Persisted file field value.

package/src/index.ts

@@ -84,6 +84,9 @@ export {
 	handleMediaCreate,
 	handleMediaUpdate,
 	handleMediaDelete,
+	handleMediaUsageActivationAdvance,
+	handleMediaUsageProgress,
+	handleMediaUsageRepair,
 	handleRevisionList,
 	handleRevisionGet,
 	handleRevisionRestore,
@@ -243,6 +246,8 @@ export {
 	PluginManager,
 	createPluginManager,
 	PluginRouteError,
+	ContentSaveRejectedError,
+	isContentSaveRejection,
 	// Scheduler (Node timer heartbeat — used by virtual:emdash/scheduler)
 	NodeCronScheduler,
 	// Sandbox

package/src/media/focal-point.ts

@@ -0,0 +1,37 @@
+export interface FocalPoint {
+	focalX: number;
+	focalY: number;
+}
+
+export interface FocalPointUpdate {
+	focalX?: number | null;
+	focalY?: number | null;
+}
+
+function isFocalCoordinate(value: unknown): value is number {
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
+}
+
+export function normalizeFocalPoint(focalX: unknown, focalY: unknown): FocalPoint | null {
+	if (!isFocalCoordinate(focalX) || !isFocalCoordinate(focalY)) return null;
+	return { focalX, focalY };
+}
+
+export function isValidFocalPointUpdate(input: FocalPointUpdate): boolean {
+	const hasX = input.focalX !== undefined;
+	const hasY = input.focalY !== undefined;
+	if (!hasX && !hasY) return true;
+	if (!hasX || !hasY) return false;
+	if (input.focalX === null || input.focalY === null) {
+		return input.focalX === null && input.focalY === null;
+	}
+	return normalizeFocalPoint(input.focalX, input.focalY) !== null;
+}
+
+export function focalPointToObjectPosition(focalX: unknown, focalY: unknown): string | undefined {
+	const point = normalizeFocalPoint(focalX, focalY);
+	if (!point) return undefined;
+	const x = Math.round(point.focalX * 10_000) / 100;
+	const y = Math.round(point.focalY * 10_000) / 100;
+	return `${x}% ${y}%`;
+}

package/src/media/local-runtime.ts

@@ -73,6 +73,8 @@ export const createMediaProvider: CreateMediaProviderFn<LocalMediaRuntimeConfig>
 					size: item.size ?? undefined,
 					width: item.width ?? undefined,
 					height: item.height ?? undefined,
+					focalX: item.focalX ?? undefined,
+					focalY: item.focalY ?? undefined,
 					blurhash: item.blurhash ?? undefined,
 					dominantColor: item.dominantColor ?? undefined,
 					alt: item.alt ?? undefined,
@@ -99,6 +101,8 @@ export const createMediaProvider: CreateMediaProviderFn<LocalMediaRuntimeConfig>
 				size: item.size ?? undefined,
 				width: item.width ?? undefined,
 				height: item.height ?? undefined,
+				focalX: item.focalX ?? undefined,
+				focalY: item.focalY ?? undefined,
 				blurhash: item.blurhash ?? undefined,
 				dominantColor: item.dominantColor ?? undefined,
 				alt: item.alt ?? undefined,
@@ -225,6 +229,8 @@ export function repoItemToProviderItem(item: {
 	size: number | null;
 	width: number | null;
 	height: number | null;
+	focalX?: number | null;
+	focalY?: number | null;
 	alt: string | null;
 	caption: string | null;
 	storageKey: string;
@@ -238,6 +244,8 @@ export function repoItemToProviderItem(item: {
 		size: item.size ?? undefined,
 		width: item.width ?? undefined,
 		height: item.height ?? undefined,
+		focalX: item.focalX ?? undefined,
+		focalY: item.focalY ?? undefined,
 		blurhash: item.blurhash ?? undefined,
 		dominantColor: item.dominantColor ?? undefined,
 		alt: item.alt ?? undefined,

package/src/media/mime.ts

@@ -23,6 +23,7 @@ export const EXTENSION_TO_MIME: Readonly<Record<string, string>> = {
 	".jpeg": "image/jpeg",
 	".gif": "image/gif",
 	".webp": "image/webp",
+	".avif": "image/avif",
 	".svg": "image/svg+xml",
 	".mp3": "audio/mpeg",
 	".wav": "audio/wav",

package/src/media/normalize.ts

@@ -9,6 +9,7 @@
  * the provider's `get()` method.
  */
 
+import { normalizeFocalPoint } from "./focal-point.js";
 import type { MediaProvider, MediaProviderItem, MediaValue } from "./types.js";
 
 export const INTERNAL_MEDIA_PREFIX = "/_emdash/api/media/file/";
@@ -138,6 +139,7 @@ async function resolveInternalUrl(
 		return { provider: "external", id: "", src: url };
 	}
 
+	const focalPoint = normalizeFocalPoint(item.focalX, item.focalY);
 	return {
 		provider: "local",
 		id: item.id,
@@ -145,6 +147,7 @@ async function resolveInternalUrl(
 		mimeType: item.mimeType,
 		width: item.width,
 		height: item.height,
+		...focalPoint,
 		blurhash: item.blurhash,
 		dominantColor: item.dominantColor,
 		alt: item.alt,
@@ -169,6 +172,7 @@ async function resolveLocalId(
 
 	if (!item) return null;
 
+	const focalPoint = normalizeFocalPoint(item.focalX, item.focalY);
 	return {
 		provider: "local",
 		id: item.id,
@@ -176,6 +180,7 @@ async function resolveLocalId(
 		mimeType: item.mimeType,
 		width: item.width,
 		height: item.height,
+		...focalPoint,
 		blurhash: item.blurhash,
 		dominantColor: item.dominantColor,
 		alt: item.alt,
@@ -234,6 +239,11 @@ function recordToMediaValue(obj: Record<string, unknown>): MediaValue {
 	if (typeof obj.mimeType === "string") result.mimeType = obj.mimeType;
 	if (typeof obj.width === "number") result.width = obj.width;
 	if (typeof obj.height === "number") result.height = obj.height;
+	const focalPoint = normalizeFocalPoint(obj.focalX, obj.focalY);
+	if (focalPoint) {
+		result.focalX = focalPoint.focalX;
+		result.focalY = focalPoint.focalY;
+	}
 	if (typeof obj.blurhash === "string") result.blurhash = obj.blurhash;
 	if (typeof obj.dominantColor === "string") result.dominantColor = obj.dominantColor;
 	if (typeof obj.alt === "string") result.alt = obj.alt;

package/src/media/types.ts

@@ -6,6 +6,8 @@
  * alongside the built-in local media library.
  */
 
+import { normalizeFocalPoint } from "./focal-point.js";
+
 /**
  * Serializable media provider configuration descriptor
  * Returned by provider config functions (e.g., unsplash(), mux())
@@ -85,6 +87,9 @@ export interface MediaProviderItem {
 	/** Dimensions (for images/video) */
 	width?: number;
 	height?: number;
+	/** Default focal point for cover-cropped displays */
+	focalX?: number;
+	focalY?: number;
 	/** LQIP blurhash placeholder (images only) */
 	blurhash?: string;
 	/** LQIP dominant-color placeholder, as a CSS color (images only) */
@@ -264,6 +269,9 @@ export interface MediaValue {
 	mimeType?: string;
 	width?: number;
 	height?: number;
+	/** Default focal point copied when the media item is selected */
+	focalX?: number;
+	focalY?: number;
 	/** Cached LQIP blurhash placeholder (images only) */
 	blurhash?: string;
 	/** Cached LQIP dominant-color placeholder, as a CSS color (images only) */
@@ -278,6 +286,7 @@ export interface MediaValue {
  * Convert a MediaProviderItem to a MediaValue for storage
  */
 export function mediaItemToValue(providerId: string, item: MediaProviderItem): MediaValue {
+	const focalPoint = normalizeFocalPoint(item.focalX, item.focalY);
 	return {
 		provider: providerId,
 		id: item.id,
@@ -285,6 +294,7 @@ export function mediaItemToValue(providerId: string, item: MediaProviderItem): M
 		mimeType: item.mimeType,
 		width: item.width,
 		height: item.height,
+		...focalPoint,
 		blurhash: item.blurhash,
 		dominantColor: item.dominantColor,
 		alt: item.alt,