emdash 0.35.0 → 0.37.0

package/src/mcp/server.ts

@@ -21,8 +21,10 @@ import {
 	contentBylineInputSchema,
 	contentSeoInput,
 	createCollectionBody,
+	createTaxonomyDefBody,
 	updateCollectionBody,
 	updateFieldBody,
+	updateTaxonomyDefBody,
 } from "#api/schemas.js";
 
 import type { MediaUsageRepairRequest } from "../api/schemas/media-usage.js";
@@ -37,8 +39,34 @@ import { decodeBase64, encodeBase64 } from "../utils/base64.js";
 const COLLECTION_SLUG_PATTERN = /^[a-z][a-z0-9_]*$/;
 /** http(s) scheme matcher used by `settings_update` URL validation. */
 const HTTP_SCHEME_PATTERN = /^https?:\/\//i;
+/**
+ * Shared wording for the `_rev` parameter on write tools. Agents only see the
+ * tool schema, so the retry protocol is stated here.
+ */
+const REV_PARAM_DESCRIPTION =
+	"Revision token proving you have read the current item. Call content_get " +
+	"first and pass back the _rev it returns. If this call fails with CONFLICT " +
+	"the item changed in the meantime: call content_get again and retry with " +
+	"the new token.";
+
+/**
+ * Replaces Zod's "expected string, received undefined" for a caller that never
+ * read the schema, so the message says where the token comes from.
+ */
+const REV_MISSING_ERROR =
+	"_rev is required: call content_get for this item and pass back the _rev it returns.";
+
 const TAXONOMY_CURSOR_VERSION = 2;
 const MAX_TAXONOMY_CURSOR_LENGTH = 2048;
+const contentDateTimeInputSchema = z.iso
+	.datetime({ offset: true, message: "must be an ISO 8601 datetime" })
+	.or(
+		z.iso.datetime({
+			offset: true,
+			precision: -1,
+			message: "must be an ISO 8601 datetime",
+		}),
+	);
 
 // ---------------------------------------------------------------------------
 // Shared schemas — kept in sync with `api/schemas/settings.ts` (which the
@@ -150,6 +178,12 @@ const schemaUpdateCollectionToolSchema = z.object({
 	commentsAutoApproveUsers: updateCollectionBody.shape.commentsAutoApproveUsers.describe(
 		"Whether comments from authenticated users are automatically approved",
 	),
+	titleField: updateCollectionBody.shape.titleField.describe(
+		"Field slug to use as the Title column in admin lists; pass null to fall back to the default",
+	),
+	dateField: updateCollectionBody.shape.dateField.describe(
+		"Datetime field slug to use as the Date column in admin lists; pass null to fall back to the default",
+	),
 });
 
 const schemaUpdateFieldToolSchema = z.object({
@@ -617,6 +651,13 @@ function extractContentId(data: unknown): string | undefined {
 	return typeof item?.id === "string" ? item.id : undefined;
 }
 
+/** Extract the `_rev` token from a content handler response. */
+function extractContentRev(data: unknown): string | undefined {
+	if (!data || typeof data !== "object") return undefined;
+	const rev = (data as Record<string, unknown>)._rev;
+	return typeof rev === "string" ? rev : undefined;
+}
+
 // ---------------------------------------------------------------------------
 // Server factory
 // ---------------------------------------------------------------------------
@@ -827,8 +868,9 @@ export function createMcpServer(
 			title: "Get Content",
 			description:
 				"Get a single content item by its ID or slug. Returns the full content data " +
-				"including all field values, metadata, and a _rev token for optimistic " +
-				"concurrency (pass _rev back when updating to detect conflicts).",
+				"including all field values, metadata, and a _rev token. content_update, " +
+				"content_publish, content_unpublish and content_discard_draft require that " +
+				"token, so read the item here before calling them.",
 			inputSchema: z.object({
 				collection: z.string().describe("Collection slug (e.g. 'posts', 'pages')"),
 				id: z.string().describe("Content item ID (ULID) or slug"),
@@ -995,9 +1037,12 @@ export function createMcpServer(
 				"in the 'data' object — unspecified fields are left unchanged. Rich text " +
 				"(portableText) fields accept a Markdown string (recommended, converted " +
 				"automatically); use a Portable Text JSON array only for complex content " +
-				"Markdown can't express (custom blocks, embeds). Pass the " +
-				"_rev token from content_get to enable optimistic concurrency checking " +
-				"(the update fails if the item was modified since you read it). " +
+				"Markdown can't express (custom blocks, embeds). Requires the _rev " +
+				"token from content_get, so read the item before updating it: the " +
+				"update fails if the item changed since that read. When status is not " +
+				"set, a change to a published item is staged as a draft, so the " +
+				"response shows the new values while the live version keeps the old " +
+				"ones until content_publish. " +
 				"`seo` and `bylines` are persisted alongside the field updates in a " +
 				"single transaction. `publishedAt` requires the content:publish_any " +
 				"permission and is useful for migrations or correcting historical dates.",
@@ -1043,16 +1088,12 @@ export function createMcpServer(
 					.describe(
 						"Replace taxonomy term assignments as { taxonomyName: [termSlug, ...] }. Term slugs are resolved in the entry's locale. Only named taxonomies are touched; other taxonomies are left unchanged. Pass an empty array to clear a taxonomy.",
 					),
-				publishedAt: z.iso
-					.datetime({ offset: true, message: "must be an ISO 8601 datetime" })
+				publishedAt: contentDateTimeInputSchema
 					.nullish()
 					.describe(
 						"Override the publication timestamp (ISO 8601). Requires content:publish_any permission. Pass null to clear. Useful for content migrations.",
 					),
-				_rev: z
-					.string()
-					.optional()
-					.describe("Revision token from content_get for conflict detection"),
+				_rev: z.string({ error: REV_MISSING_ERROR }).describe(REV_PARAM_DESCRIPTION),
 			}),
 		},
 		async (args, extra) => {
@@ -1090,6 +1131,7 @@ export function createMcpServer(
 			// Status transitions route through dedicated handlers for proper revision management
 			if (args.status === "published") {
 				requireOwnership(extra, ownerId, "content:publish_own", "content:publish_any");
+				let rev: string | undefined = args._rev;
 				if (
 					args.data ||
 					args.slug ||
@@ -1110,12 +1152,16 @@ export function createMcpServer(
 						_rev: args._rev,
 					});
 					if (!updateResult.success) return unwrap(updateResult);
+					rev = extractContentRev(updateResult.data);
 				}
-				return unwrap(await emdash.handleContentPublish(args.collection, resolvedId));
+				return unwrap(
+					await emdash.handleContentPublish(args.collection, resolvedId, { _rev: rev }),
+				);
 			}
 
 			if (args.status === "draft") {
 				requireOwnership(extra, ownerId, "content:publish_own", "content:publish_any");
+				let rev: string | undefined = args._rev;
 				if (
 					args.data ||
 					args.slug ||
@@ -1136,8 +1182,11 @@ export function createMcpServer(
 						_rev: args._rev,
 					});
 					if (!updateResult.success) return unwrap(updateResult);
+					rev = extractContentRev(updateResult.data);
 				}
-				return unwrap(await emdash.handleContentUnpublish(args.collection, resolvedId));
+				return unwrap(
+					await emdash.handleContentUnpublish(args.collection, resolvedId, { _rev: rev }),
+				);
 			}
 
 			return unwrap(
@@ -1260,8 +1309,8 @@ export function createMcpServer(
 			inputSchema: z.object({
 				collection: z.string().describe("Collection slug"),
 				id: z.string().describe("Content item ID or slug"),
-				publishedAt: z.iso
-					.datetime({ offset: true, message: "must be an ISO 8601 datetime" })
+				_rev: z.string({ error: REV_MISSING_ERROR }).describe(REV_PARAM_DESCRIPTION),
+				publishedAt: contentDateTimeInputSchema
 					.optional()
 					.describe(
 						"Override publication timestamp (ISO 8601). Requires content:publish_any permission. Useful when importing content with original publish dates.",
@@ -1297,6 +1346,7 @@ export function createMcpServer(
 			return unwrap(
 				await emdash.handleContentPublish(args.collection, resolvedId, {
 					publishedAt: args.publishedAt,
+					_rev: args._rev,
 				}),
 			);
 		},
@@ -1308,10 +1358,11 @@ export function createMcpServer(
 			title: "Unpublish Content",
 			description:
 				"Unpublish a content item, reverting it to draft status. It will no " +
-				"longer be visible on the live site but its content is preserved.",
+				"longer be visible on the live site, but its content and publication date are preserved.",
 			inputSchema: z.object({
 				collection: z.string().describe("Collection slug"),
 				id: z.string().describe("Content item ID or slug"),
+				_rev: z.string({ error: REV_MISSING_ERROR }).describe(REV_PARAM_DESCRIPTION),
 			}),
 		},
 		async (args, extra) => {
@@ -1332,7 +1383,9 @@ export function createMcpServer(
 			);
 
 			const resolvedId = extractContentId(existing.data) ?? args.id;
-			return unwrap(await ec.handleContentUnpublish(args.collection, resolvedId));
+			return unwrap(
+				await ec.handleContentUnpublish(args.collection, resolvedId, { _rev: args._rev }),
+			);
 		},
 	);
 
@@ -1440,6 +1493,7 @@ export function createMcpServer(
 			inputSchema: z.object({
 				collection: z.string().describe("Collection slug"),
 				id: z.string().describe("Content item ID or slug"),
+				_rev: z.string({ error: REV_MISSING_ERROR }).describe(REV_PARAM_DESCRIPTION),
 			}),
 			annotations: { destructiveHint: true },
 		},
@@ -1461,7 +1515,9 @@ export function createMcpServer(
 			);
 
 			const resolvedId = extractContentId(existing.data) ?? args.id;
-			return unwrap(await ec.handleContentDiscardDraft(args.collection, resolvedId));
+			return unwrap(
+				await ec.handleContentDiscardDraft(args.collection, resolvedId, { _rev: args._rev }),
+			);
 		},
 	);
 
@@ -1969,7 +2025,7 @@ export function createMcpServer(
 							.describe("Target collection slug for reference fields"),
 						rows: z.number().optional().describe("Number of rows for textarea"),
 					})
-					.passthrough()
+					.loose()
 					.optional()
 					.describe("Widget configuration"),
 				searchable: z
@@ -2168,7 +2224,6 @@ export function createMcpServer(
 					.optional()
 					.describe("Base64-encoded file contents. Provide exactly one of base64 / url."),
 				url: z
-					.string()
 					.url()
 					.optional()
 					.describe(
@@ -2423,6 +2478,158 @@ export function createMcpServer(
 		},
 	);
 
+	server.registerTool(
+		"taxonomy_get",
+		{
+			title: "Get Taxonomy Definition",
+			description:
+				"Get a single taxonomy definition by name. Taxonomy definitions describe " +
+				"a classification system (e.g. categories or tags), which collections " +
+				"it applies to, and whether it is hierarchical. Pass `locale` to resolve " +
+				"a specific translation; otherwise the lowest matching locale is returned.",
+			inputSchema: z.object({
+				name: z.string().describe("Taxonomy name (e.g. 'categories', 'tags')"),
+				locale: z.string().optional().describe("Locale to resolve the definition for"),
+			}),
+			annotations: { readOnlyHint: true },
+		},
+		async (args, extra) => {
+			requireScope(extra, "content:read");
+			const ec = getEmDash(extra);
+			try {
+				const { handleTaxonomyGet } = await import("../api/handlers/taxonomies.js");
+				return unwrap(await handleTaxonomyGet(ec.db, args.name, { locale: args.locale }));
+			} catch (error) {
+				return respondHandlerError(error, "TAXONOMY_GET_ERROR");
+			}
+		},
+	);
+
+	server.registerTool(
+		"taxonomy_create",
+		{
+			title: "Create Taxonomy Definition",
+			description:
+				"Create a new taxonomy definition. Definitions are per-locale; pass " +
+				"`locale` when the same taxonomy name exists in multiple translations. " +
+				"`collections` names which content types the taxonomy applies to. " +
+				"If `translationOf` is set, the new definition joins the source's " +
+				"translation group and inherits `hierarchical` and `collections` from " +
+				"the source when those fields are omitted.",
+			inputSchema: z.object({
+				name: createTaxonomyDefBody.shape.name.describe(
+					"Taxonomy name (lowercase letters, numbers, underscores)",
+				),
+				label: createTaxonomyDefBody.shape.label.describe("Display name"),
+				labelSingular: createTaxonomyDefBody.shape.labelSingular.describe(
+					"Singular form of the display name",
+				),
+				hierarchical: createTaxonomyDefBody.shape.hierarchical.describe(
+					"Whether the taxonomy supports parent/child terms (defaults to false, or inherited from translationOf)",
+				),
+				collections: createTaxonomyDefBody.shape.collections.describe(
+					"Collection slugs this taxonomy applies to (defaults to [], or inherited from translationOf)",
+				),
+				locale: z.string().optional().describe("Locale for this definition (e.g. 'fr-fr')"),
+				translationOf: z
+					.string()
+					.optional()
+					.describe("Existing taxonomy definition id to create this locale variant from"),
+			}),
+		},
+		async (args, extra) => {
+			requireScope(extra, "taxonomies:manage");
+			requireRole(extra, Role.EDITOR);
+			const ec = getEmDash(extra);
+			try {
+				const { handleTaxonomyCreate } = await import("../api/handlers/taxonomies.js");
+				return unwrap(
+					await handleTaxonomyCreate(ec.db, {
+						name: args.name,
+						label: args.label,
+						labelSingular: args.labelSingular,
+						hierarchical: args.hierarchical,
+						collections: args.collections,
+						locale: args.locale,
+						translationOf: args.translationOf,
+					}),
+				);
+			} catch (error) {
+				return respondHandlerError(error, "TAXONOMY_CREATE_ERROR");
+			}
+		},
+	);
+
+	server.registerTool(
+		"taxonomy_update",
+		{
+			title: "Update Taxonomy Definition",
+			description:
+				"Update an existing taxonomy definition. The taxonomy `name` cannot be " +
+				"changed. Pass `locale` to update a specific translation; otherwise the " +
+				"lowest matching locale is updated. Any field may be omitted to leave it " +
+				"unchanged.",
+			inputSchema: z.object({
+				name: z.string().describe("Taxonomy name to update"),
+				label: updateTaxonomyDefBody.shape.label.describe("New display name"),
+				labelSingular: updateTaxonomyDefBody.shape.labelSingular.describe(
+					"New singular display name; pass null to clear",
+				),
+				hierarchical: updateTaxonomyDefBody.shape.hierarchical.describe(
+					"Whether the taxonomy supports parent/child terms",
+				),
+				collections: updateTaxonomyDefBody.shape.collections.describe(
+					"Collection slugs this taxonomy applies to",
+				),
+				locale: z.string().optional().describe("Locale of the definition to update"),
+			}),
+		},
+		async (args, extra) => {
+			requireScope(extra, "taxonomies:manage");
+			requireRole(extra, Role.EDITOR);
+			const ec = getEmDash(extra);
+			try {
+				const { handleTaxonomyUpdate } = await import("../api/handlers/taxonomies.js");
+				return unwrap(
+					await handleTaxonomyUpdate(ec.db, args.name, {
+						label: args.label,
+						labelSingular: args.labelSingular,
+						hierarchical: args.hierarchical,
+						collections: args.collections,
+						locale: args.locale,
+					}),
+				);
+			} catch (error) {
+				return respondHandlerError(error, "TAXONOMY_UPDATE_ERROR");
+			}
+		},
+	);
+
+	server.registerTool(
+		"taxonomy_delete",
+		{
+			title: "Delete Taxonomy Definition",
+			description:
+				"Delete a taxonomy definition and all of its terms in every locale, " +
+				"along with any content assignments those terms hold. This cannot be undone.",
+			inputSchema: z.object({
+				name: z.string().describe("Taxonomy name to delete"),
+			}),
+			annotations: { destructiveHint: true },
+		},
+		async (args, extra) => {
+			requireScope(extra, "taxonomies:manage");
+			requireRole(extra, Role.EDITOR);
+			const ec = getEmDash(extra);
+			try {
+				const { handleTaxonomyDelete } = await import("../api/handlers/taxonomies.js");
+				return unwrap(await handleTaxonomyDelete(ec.db, args.name));
+			} catch (error) {
+				return respondHandlerError(error, "TAXONOMY_DELETE_ERROR");
+			}
+		},
+	);
+
 	server.registerTool(
 		"taxonomy_list_terms",
 		{
@@ -3026,10 +3233,7 @@ export function createMcpServer(
 					.describe("Favicon media reference ({ mediaId, alt? })"),
 				url: z
 					.union([
-						z
-							.string()
-							.url()
-							.refine((u) => HTTP_SCHEME_PATTERN.test(u), "URL must use http or https"),
+						z.url().refine((u) => HTTP_SCHEME_PATTERN.test(u), "URL must use http or https"),
 						z.literal(""),
 					])
 					.optional()

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/image-endpoint.ts

@@ -50,9 +50,12 @@ export interface ImageTransformOptions {
 	quality?: number;
 }
 
-/** Long-lived immutable cache -- transform output is deterministic per key+params. */
+/** Long-lived cache for content-addressed image URLs. */
 export const IMMUTABLE_IMAGE_CACHE = "public, max-age=31536000, immutable";
 
+/** Cache policy for media keys that Replace original may overwrite. */
+export const MUTABLE_MEDIA_CACHE_CONTROL = "public, max-age=0, must-revalidate";
+
 /**
  * Raster types safe to render inline. Anything else (SVG, PDF, ...) is served
  * as an attachment so it can't execute as an active document. Mirrors the
@@ -77,7 +80,7 @@ const SAFE_INLINE_IMAGE_TYPES = new Set([
 export function originalMediaHeaders(contentType: string): Record<string, string> {
 	return {
 		"Content-Type": contentType,
-		"Cache-Control": IMMUTABLE_IMAGE_CACHE,
+		"Cache-Control": MUTABLE_MEDIA_CACHE_CONTROL,
 		"X-Content-Type-Options": "nosniff",
 		"Content-Security-Policy":
 			"sandbox; default-src 'none'; img-src 'self'; style-src 'unsafe-inline'",

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,11 +9,22 @@
  * 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/";
 const URL_PATTERN = /^https?:\/\//;
 
+export function normalizeLegacyExternalMediaValue(value: MediaValue): MediaValue {
+	if (value.provider !== "external-url") return value;
+	const src = value.src ?? value.previewUrl;
+	return {
+		...value,
+		provider: "external",
+		...(src === undefined ? {} : { src }),
+	};
+}
+
 /**
  * Normalize a media field value into a consistent MediaValue shape.
  *
@@ -40,16 +51,17 @@ export async function normalizeMediaValue(
 	// Must have at least an id to be a valid media value
 	if (!("id" in value) && !("src" in value)) return null;
 
-	const provider = (typeof value.provider === "string" ? value.provider : undefined) || "local";
-	const id = typeof value.id === "string" ? value.id : "";
+	const parsed = normalizeLegacyExternalMediaValue(recordToMediaValue(value));
+	const provider = parsed.provider || "local";
+	const id = parsed.id;
 
 	// External URLs — return as-is, no server-side dimension detection
 	if (provider === "external") {
-		return recordToMediaValue(value);
+		return parsed;
 	}
 
 	// Build the base value from the input
-	const result: MediaValue = { ...recordToMediaValue(value), provider };
+	const result: MediaValue = { ...parsed, provider };
 
 	// For local media, strip `src` — it's derived at display time from storageKey
 	if (provider === "local") {
@@ -138,6 +150,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 +158,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 +183,7 @@ async function resolveLocalId(
 
 	if (!item) return null;
 
+	const focalPoint = normalizeFocalPoint(item.focalX, item.focalY);
 	return {
 		provider: "local",
 		id: item.id,
@@ -176,6 +191,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 +250,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,