emdash 0.35.0 → 0.37.0

package/src/emdash-runtime.ts

@@ -9,10 +9,12 @@
 
 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 { buildManifestCollections } from "./api/handlers/manifest.js";
 import { assertMediaUsageActivationWriteAllowed } from "./api/media-usage-write-fence.js";
 import { validateRev } from "./api/rev.js";
 import type {
@@ -20,7 +22,7 @@ import type {
 	PluginAdminPage,
 	PluginDashboardWidget,
 } from "./astro/integration/runtime.js";
-import type { EmDashManifest, ManifestCollection } from "./astro/types.js";
+import type { EmDashManifest } from "./astro/types.js";
 import { getAuthMode } from "./auth/mode.js";
 import { getTrustedProxyHeaders } from "./auth/trusted-proxy.js";
 import type { ContentFieldFilters } from "./content-list-query.js";
@@ -43,30 +45,21 @@ 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 { inspectSandboxHookResult } from "./plugins/sandbox/hook-result.js";
 import { createSandboxRunnerOptions } from "./plugins/sandbox/runner-options.js";
 import { getSandboxRouteErrorDetails } from "./plugins/sandbox/types.js";
 import type {
@@ -75,6 +68,7 @@ import type {
 	SandboxRunnerFactory,
 } from "./plugins/sandbox/types.js";
 import type {
+	ContentHookEvent,
 	ResolvedPlugin,
 	MediaItem,
 	PluginManifest,
@@ -90,7 +84,6 @@ import type {
 	UserInfo,
 } from "./plugins/types.js";
 import { recordSchedulerHeartbeatSafely } from "./scheduler-health.js";
-import { MAX_COLLECTION_LIST_COLUMNS, type FieldType } from "./schema/types.js";
 import { isMissingTableError } from "./utils/db-errors.js";
 import { hashString } from "./utils/hash.js";
 import { createInitLock, type InitLock, initWithLock } from "./utils/init-lock.js";
@@ -198,6 +191,7 @@ import {
 	handleMediaGet,
 	handleMediaCreate,
 	handleMediaUpdate,
+	handleMediaReplaceMetadata,
 	handleMediaDelete,
 	handleRevisionList,
 	handleRevisionGet,
@@ -227,6 +221,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";
@@ -237,41 +232,9 @@ import { publishDueContent, type PublishedRef } from "./scheduled-publish.js";
 import { FTSManager } from "./search/fts-manager.js";
 import { invalidateSiteSettingsCache } from "./settings/index.js";
 
-/**
- * Map schema field types to editor field kinds
- */
-const FIELD_TYPE_TO_KIND: Record<FieldType, string> = {
-	string: "string",
-	slug: "string",
-	url: "url",
-	text: "richText",
-	number: "number",
-	integer: "number",
-	boolean: "boolean",
-	datetime: "datetime",
-	select: "select",
-	multiSelect: "multiSelect",
-	portableText: "portableText",
-	image: "image",
-	file: "file",
-	reference: "reference",
-	json: "json",
-	repeater: "repeater",
-};
-
 const DRAFT_ONLY_UPDATE_KEYS = new Set(["data", "slug", "locale", "skipRevision"]);
 const MAX_DRAFT_STAGE_ATTEMPTS = 32;
 
-const LIST_COLUMN_FIELD_TYPES: ReadonlySet<FieldType> = new Set([
-	"string",
-	"number",
-	"integer",
-	"boolean",
-	"datetime",
-	"select",
-	"multiSelect",
-]);
-
 /**
  * Sandboxed plugin entry from virtual module
  */
@@ -434,6 +397,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 +538,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 +743,6 @@ export class EmDashRuntime {
 		return { published };
 	}
 
-	async runScheduledMediaUsageTasks(): Promise<MediaUsageMaintenanceResult> {
-		return runScheduledMediaUsageLane(this.db);
-	}
-
 	/**
 	 * Materialize plugin-declared storage indexes, once per process.
 	 *
@@ -1448,6 +1373,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 +1690,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 +1723,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();
@@ -2506,103 +2423,10 @@ export class EmDashRuntime {
 	 * is two queries in practice; never N+1.
 	 */
 	private async _buildManifest(): Promise<EmDashManifest> {
-		// Build collections from database.
+		// Build collections from the live database.
 		// Use this.db (ALS-aware getter) so playground mode picks up the
 		// per-session DO database instead of the hardcoded singleton.
-		const manifestCollections: Record<string, ManifestCollection> = {};
-		try {
-			const registry = new SchemaRegistry(this.db);
-			const dbCollections = await registry.listCollectionsWithFields();
-			for (const collection of dbCollections) {
-				const fields: Record<
-					string,
-					{
-						kind: string;
-						label?: string;
-						required?: boolean;
-						widget?: string;
-						// Two shapes: legacy enum-style `[{ value, label }]` for select widgets,
-						// or arbitrary `Record<string, unknown>` for plugin field widgets that
-						// need per-field config (e.g. a checkbox grid receiving its column defs).
-						options?: Array<{ value: string; label: string }> | Record<string, unknown>;
-						id?: string;
-						validation?: Record<string, unknown>;
-					}
-				> = {};
-
-				for (const field of collection.fields) {
-					const entry: (typeof fields)[string] = {
-						kind: FIELD_TYPE_TO_KIND[field.type] ?? "string",
-						label: field.label,
-						required: field.required,
-					};
-					// Always include the field's database ID so the admin can forward it
-					// to upload/media-list API calls for MIME allowlist widening.
-					entry.id = field.id;
-					if (field.widget) entry.widget = field.widget;
-					// Plugin field widgets read their per-field config from `field.options`,
-					// which the seed schema types as `Record<string, unknown>`. Pass it
-					// through to the manifest so plugin widgets in the admin SPA receive it.
-					if (field.options) {
-						entry.options = field.options;
-					}
-					// Legacy: select/multiSelect enum options live on `field.validation.options`.
-					// Wins over `field.options` to preserve existing behavior for enum widgets.
-					if (field.validation?.options) {
-						entry.options = field.validation.options.map((v) => ({
-							value: v,
-							label: v.charAt(0).toUpperCase() + v.slice(1),
-						}));
-					}
-					// Include full validation for repeater fields (subFields, minItems, maxItems)
-					// and for file/image fields (allowedMimeTypes).
-					if (
-						(field.type === "repeater" || field.type === "file" || field.type === "image") &&
-						field.validation
-					) {
-						entry.validation = { ...field.validation };
-					}
-					fields[field.slug] = entry;
-				}
-
-				const configuredListColumns = collection.admin?.listColumns ?? [];
-				const fieldTypes = new Map(collection.fields.map((field) => [field.slug, field.type]));
-				const listColumns: string[] = [];
-				for (const slug of configuredListColumns) {
-					if (listColumns.includes(slug)) continue;
-					const fieldType = fieldTypes.get(slug);
-					if (!fieldType || !LIST_COLUMN_FIELD_TYPES.has(fieldType)) {
-						console.warn(
-							`EmDash: Ignoring unsupported or unknown list column "${slug}" in collection "${collection.slug}".`,
-						);
-						continue;
-					}
-					if (listColumns.length >= MAX_COLLECTION_LIST_COLUMNS) {
-						console.warn(
-							`EmDash: Collection "${collection.slug}" declares more than ${MAX_COLLECTION_LIST_COLUMNS} list columns; extra columns are ignored.`,
-						);
-						break;
-					}
-					listColumns.push(slug);
-				}
-
-				manifestCollections[collection.slug] = {
-					label: collection.label,
-					labelSingular: collection.labelSingular || collection.label,
-					supports: collection.supports || [],
-					hasSeo: collection.hasSeo,
-					urlPattern: collection.urlPattern,
-					routable: collection.routable !== false,
-					titleField: collection.titleField,
-					dateField: collection.dateField,
-					...(collection.hidden ? { hidden: true } : {}),
-					listColumns: listColumns.length > 0 ? listColumns : undefined,
-					fields,
-				};
-			}
-		} catch (error) {
-			console.debug("EmDash: Could not load database collections:", error);
-		}
+		const manifestCollections = await buildManifestCollections({}, this.db);
 
 		// Build plugins manifest
 		const manifestPlugins: Record<
@@ -2768,7 +2592,11 @@ export class EmDashRuntime {
 		const i18nConfig = virtualConfig?.i18n ?? getI18nConfig();
 		const i18n =
 			i18nConfig && i18nConfig.locales && i18nConfig.locales.length > 1
-				? { defaultLocale: i18nConfig.defaultLocale, locales: i18nConfig.locales }
+				? {
+						defaultLocale: i18nConfig.defaultLocale,
+						locales: i18nConfig.locales,
+						prefixDefaultLocale: i18nConfig.prefixDefaultLocale,
+					}
 				: undefined;
 
 		// Normalize the experimental registry config for browser consumption.
@@ -2969,12 +2797,18 @@ 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)
-		processedData = await this.runSandboxedBeforeSave(processedData, collection, true);
+		const sandboxResult = await this.runSandboxedBeforeSave(processedData, collection, true);
+		if (!sandboxResult.success) return sandboxResult;
+		processedData = sandboxResult.data;
 
 		// Normalize media fields (fill dimensions, storageKey, etc.)
 		processedData = await this.normalizeMediaFields(collection, processedData);
@@ -3065,16 +2899,28 @@ 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,
+						resolvedItem?.id,
+					);
+					processedData = hookResult.content;
+				} catch (error) {
+					return beforeSaveFailure(error);
+				}
 			}
 
 			// Run sandboxed beforeSave hooks
-			processedData = await this.runSandboxedBeforeSave(processedData!, collection, false);
+			const sandboxResult = await this.runSandboxedBeforeSave(
+				processedData!,
+				collection,
+				false,
+				resolvedItem?.id,
+			);
+			if (!sandboxResult.success) return sandboxResult;
+			processedData = sandboxResult.data;
 
 			// Normalize media fields (fill dimensions, storageKey, etc.)
 			processedData = await this.normalizeMediaFields(collection, processedData);
@@ -3317,7 +3163,7 @@ export class EmDashRuntime {
 
 	async handleContentListTrashed(
 		collection: string,
-		params: { cursor?: string; limit?: number } = {},
+		params: { cursor?: string; limit?: number; locale?: string } = {},
 	) {
 		return handleContentListTrashed(this.db, collection, params);
 	}
@@ -3350,8 +3196,8 @@ export class EmDashRuntime {
 		return result;
 	}
 
-	async handleContentCountTrashed(collection: string) {
-		return handleContentCountTrashed(this.db, collection);
+	async handleContentCountTrashed(collection: string, params: { locale?: string } = {}) {
+		return handleContentCountTrashed(this.db, collection, params);
 	}
 
 	async handleContentDuplicate(collection: string, id: string, authorId?: string) {
@@ -3373,6 +3219,7 @@ export class EmDashRuntime {
 			publishedAt?: string;
 			requireScheduledDue?: boolean;
 			expectedScheduledAt?: string;
+			_rev?: string;
 		} = {},
 	) {
 		const result = await handleContentPublish(this.db, collection, id, options);
@@ -3388,8 +3235,8 @@ export class EmDashRuntime {
 		return result;
 	}
 
-	async handleContentUnpublish(collection: string, id: string) {
-		const result = await handleContentUnpublish(this.db, collection, id);
+	async handleContentUnpublish(collection: string, id: string, options: { _rev?: string } = {}) {
+		const result = await handleContentUnpublish(this.db, collection, id, options);
 		if (result.success && result.data) {
 			await this.refreshContentUsageAfterSuccessfulWrite(collection, [result.data.item.id]);
 		}
@@ -3434,8 +3281,8 @@ export class EmDashRuntime {
 		return handleContentCountScheduled(this.db, collection);
 	}
 
-	async handleContentDiscardDraft(collection: string, id: string) {
-		const result = await handleContentDiscardDraft(this.db, collection, id);
+	async handleContentDiscardDraft(collection: string, id: string, options: { _rev?: string } = {}) {
+		const result = await handleContentDiscardDraft(this.db, collection, id, options);
 		if (result.success && result.data) {
 			await this.refreshContentUsageAfterSuccessfulWrite(collection, [result.data.item.id]);
 		}
@@ -3456,9 +3303,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);
 	}
@@ -3478,6 +3327,7 @@ export class EmDashRuntime {
 		blurhash?: string;
 		dominantColor?: string;
 		authorId?: string;
+		folderId?: string | null;
 	}) {
 		// Run beforeUpload hooks
 		let processedInput = input;
@@ -3519,7 +3369,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`,
@@ -3534,6 +3392,18 @@ export class EmDashRuntime {
 		return result;
 	}
 
+	async handleMediaReplaceMetadata(
+		id: string,
+		expectedStorageKey: string,
+		input: { size: number; width: number; height: number; contentHash: string },
+	) {
+		const result = await handleMediaReplaceMetadata(this.db, id, expectedStorageKey, input);
+		if (result.success) {
+			invalidateSiteSettingsCache();
+		}
+		return result;
+	}
+
 	async handleMediaDelete(id: string) {
 		const result = await handleMediaDelete(this.db, id);
 		// Same reasoning as `handleMediaUpdate`: if the deleted media row
@@ -3690,14 +3560,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 +3926,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 +3957,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;
 							}
@@ -4103,7 +3977,8 @@ export class EmDashRuntime {
 		content: Record<string, unknown>,
 		collection: string,
 		isNew: boolean,
-	): Promise<Record<string, unknown>> {
+		contentId?: string,
+	) {
 		let result = content;
 
 		for (const [pluginKey, plugin] of this.sandboxedPlugins) {
@@ -4111,11 +3986,30 @@ export class EmDashRuntime {
 			if (!id || !this.isPluginEnabled(id)) continue;
 
 			try {
-				const hookResult = await plugin.invokeHook("content:beforeSave", {
-					content: result,
-					collection,
-					isNew,
-				});
+				const event: ContentHookEvent = { content: result, collection, isNew };
+				if (contentId !== undefined) event.id = contentId;
+				const hookResult = await plugin.invokeHook("content:beforeSave", event);
+				const inspection = inspectSandboxHookResult(hookResult);
+				if (inspection.kind === "error") {
+					return {
+						success: false as const,
+						error: {
+							code: ErrorCode.SAVE_REJECTED,
+							message: "Save rejected by a sandboxed plugin",
+							details: { pluginId: id, reason: inspection.error.reason },
+						},
+					};
+				}
+				if (inspection.kind === "malformed") {
+					console.error(`EmDash: Sandboxed plugin ${id} returned an invalid hook result`);
+					return {
+						success: false as const,
+						error: {
+							code: ErrorCode.CONTENT_HOOK_ERROR,
+							message: "A plugin hook failed while saving content",
+						},
+					};
+				}
 				if (hookResult && typeof hookResult === "object" && !Array.isArray(hookResult)) {
 					// Sandbox returns unknown; convert to record by iterating own properties
 					const record: Record<string, unknown> = {};
@@ -4125,11 +4019,18 @@ 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 failed:`, error);
+				return {
+					success: false as const,
+					error: {
+						code: ErrorCode.CONTENT_HOOK_ERROR,
+						message: "A plugin hook failed while saving content",
+					},
+				};
 			}
 		}
 
-		return result;
+		return { success: true as const, data: result };
 	}
 
 	private async runSandboxedBeforeDelete(id: string, collection: string): Promise<boolean> {
@@ -4437,3 +4338,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);
+}