emdash 1.3.0 → 1.3.1

package/src/loader.ts

@@ -20,12 +20,22 @@ import { jsonTextValues } from "./database/json-recordset.js";
 import { selectTaxonomyDefs } from "./database/repositories/taxonomy-def.js";
 import { decodeCursor, encodeCursor, InvalidCursorError } from "./database/repositories/types.js";
 import { validateIdentifier } from "./database/validate.js";
-import { getI18nConfig } from "./i18n/config.js";
+import { getI18nConfig, getLocaleCandidates, type I18nConfig } from "./i18n/config.js";
+import {
+	canonicalLocaleColumn,
+	storedLocaleOrder,
+	localeMatches,
+	localeOrder,
+} from "./i18n/query.js";
 import type { Database } from "./index.js";
 import { primeSeoPanel } from "./page/seo-panel.js";
 import { getRequestContext } from "./request-context.js";
 import { chunks, SQL_BATCH_SIZE } from "./utils/chunks.js";
-import { isMissingColumnError, isMissingTableError } from "./utils/db-errors.js";
+import {
+	isMissingColumnError,
+	getMissingColumnIdentifier,
+	isMissingTableError,
+} from "./utils/db-errors.js";
 
 const FIELD_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
 
@@ -151,7 +161,23 @@ function foldedHydrationSelects(db: Kysely<any>, type: string, outer: string) {
 	const termAgg = pg
 		? sql`coalesce(json_agg(${termObj}) FILTER (WHERE ${selectedTermId} IS NOT NULL), '[]'::json)`
 		: sql`json_group_array(${termObj}) FILTER (WHERE ${selectedTermId} IS NOT NULL)`;
-	const terms = sql`(SELECT ${termAgg} FROM ${sql.ref("content_taxonomies")} AS ct LEFT JOIN ${sql.ref("taxonomies")} AS exact_term ON exact_term.translation_group = ct.taxonomy_id AND exact_term.locale = ${o}.locale LEFT JOIN ${sql.ref("taxonomies")} AS default_term ON default_term.translation_group = ct.taxonomy_id AND default_term.locale = ${defaultLocale} WHERE ct.collection = ${type} AND ct.entry_id = ${o}.translation_group) AS ${sql.ref("_emdash_terms")}`;
+	const hasLocaleAliases = Object.keys(getI18nConfig()?.localeAliases ?? {}).length > 0;
+	const terms = hasLocaleAliases
+		? sql`(SELECT ${termAgg} FROM ${sql.ref("content_taxonomies")} AS ct
+		LEFT JOIN ${sql.ref("taxonomies")} AS exact_term ON exact_term.id = (
+			SELECT candidate.id FROM taxonomies AS candidate
+			WHERE candidate.translation_group = ct.taxonomy_id
+				AND ${canonicalLocaleColumn("candidate.locale")} = ${canonicalLocaleColumn(`${outer}.locale`)}
+			ORDER BY ${storedLocaleOrder("candidate.locale")}, candidate.id LIMIT 1
+		)
+		LEFT JOIN ${sql.ref("taxonomies")} AS default_term ON default_term.id = (
+			SELECT candidate.id FROM taxonomies AS candidate
+			WHERE candidate.translation_group = ct.taxonomy_id
+				AND ${localeMatches("candidate.locale", defaultLocale)}
+			ORDER BY ${localeOrder("candidate.locale", defaultLocale)}, candidate.id LIMIT 1
+		)
+		WHERE ct.collection = ${type} AND ct.entry_id = ${o}.translation_group) AS ${sql.ref("_emdash_terms")}`
+		: sql`(SELECT ${termAgg} FROM ${sql.ref("content_taxonomies")} AS ct LEFT JOIN ${sql.ref("taxonomies")} AS exact_term ON exact_term.translation_group = ct.taxonomy_id AND exact_term.locale = ${o}.locale LEFT JOIN ${sql.ref("taxonomies")} AS default_term ON default_term.translation_group = ct.taxonomy_id AND default_term.locale = ${defaultLocale} WHERE ct.collection = ${type} AND ct.entry_id = ${o}.translation_group) AS ${sql.ref("_emdash_terms")}`;
 
 	const bylineInner = obj(
 		"'id', b.id, 'slug', b.slug, 'displayName', b.display_name, 'bio', b.bio, 'avatarMediaId', b.avatar_media_id, 'avatarStorageKey', m.storage_key, 'avatarAlt', m.alt, 'avatarBlurhash', m.blurhash, 'avatarDominantColor', m.dominant_color, 'websiteUrl', b.website_url, 'userId', b.user_id, 'isGuest', b.is_guest, 'createdAt', b.created_at, 'updatedAt', b.updated_at, 'locale', b.locale, 'translationGroup', b.translation_group",
@@ -162,7 +188,17 @@ function foldedHydrationSelects(db: Kysely<any>, type: string, outer: string) {
 			)
 		: sql.raw("json_object('roleLabel', cb.role_label, 'sortOrder', cb.sort_order, 'byline', ");
 	const credit = sql`${creditObj}${bylineInner})`;
-	const bylines = sql`(SELECT ${agg(credit)} FROM ${sql.ref("_emdash_content_bylines")} AS cb ${foldJoin} ${sql.ref("_emdash_bylines")} AS b ON b.translation_group = cb.byline_id LEFT JOIN ${sql.ref("media")} AS m ON m.id = b.avatar_media_id WHERE cb.collection_slug = ${type} AND cb.content_id = ${o}.id AND b.locale = ${o}.locale) AS ${sql.ref("_emdash_bylines")}`;
+	const bylines = hasLocaleAliases
+		? sql`(SELECT ${agg(credit)} FROM ${sql.ref("_emdash_content_bylines")} AS cb
+		${foldJoin} ${sql.ref("_emdash_bylines")} AS b ON b.id = (
+			SELECT candidate.id FROM _emdash_bylines AS candidate
+			WHERE candidate.translation_group = cb.byline_id
+				AND ${canonicalLocaleColumn("candidate.locale")} = ${canonicalLocaleColumn(`${outer}.locale`)}
+			ORDER BY ${storedLocaleOrder("candidate.locale")}, candidate.id LIMIT 1
+		)
+		LEFT JOIN ${sql.ref("media")} AS m ON m.id = b.avatar_media_id
+		WHERE cb.collection_slug = ${type} AND cb.content_id = ${o}.id) AS ${sql.ref("_emdash_bylines")}`
+		: sql`(SELECT ${agg(credit)} FROM ${sql.ref("_emdash_content_bylines")} AS cb ${foldJoin} ${sql.ref("_emdash_bylines")} AS b ON b.translation_group = cb.byline_id LEFT JOIN ${sql.ref("media")} AS m ON m.id = b.avatar_media_id WHERE cb.collection_slug = ${type} AND cb.content_id = ${o}.id AND b.locale = ${o}.locale) AS ${sql.ref("_emdash_bylines")}`;
 	// Uncorrelated existence probe (evaluated once per statement, not per row):
 	// 1 when `_emdash_bylines` has any row, NULL when empty. An empty table
 	// means an empty fold is authoritative — no credit in any locale, no
@@ -730,12 +766,15 @@ export async function loadEntriesByGroups(
 	const statusFilter = options.publishedOnly ? sql`AND status = ${"published"}` : sql``;
 	const booleanFieldsSelect = foldedBooleanFieldsSelect(db, type);
 	const localeChain = options.localeChain ?? [];
+	const localeCandidates = [
+		...new Set(localeChain.flatMap((locale) => getLocaleCandidates(locale))),
+	];
 	const chainPosition =
-		localeChain.length > 0
+		localeCandidates.length > 0
 			? sql`CASE locale ${sql.join(
-					localeChain.map((locale, index) => sql`WHEN ${locale} THEN ${sql.lit(index)}`),
+					localeCandidates.map((locale, index) => sql`WHEN ${locale} THEN ${sql.lit(index)}`),
 					sql` `,
-				)} ELSE ${sql.lit(localeChain.length)} END,`
+				)} ELSE ${sql.lit(localeCandidates.length)} END,`
 			: sql``;
 
 	const entries: LoadedEntry[] = [];
@@ -818,7 +857,7 @@ function mapRevisionData(
 let virtualConfig:
 	| {
 			database?: { config: unknown };
-			i18n?: { defaultLocale: string; locales: string[]; prefixDefaultLocale?: boolean } | null;
+			i18n?: I18nConfig | null;
 	  }
 	| undefined;
 let virtualCreateDialect: ((config: unknown) => Dialect) | undefined;
@@ -1229,7 +1268,7 @@ async function resolveTermGroups(
 					.as("large"),
 			),
 		);
-	if (locale) query = query.where("locale", "=", locale);
+	if (locale) query = query.where(localeMatches("locale", locale));
 	const rows = await query.execute();
 	const groups = new Set<string>();
 	let large = false;
@@ -1402,7 +1441,7 @@ export function buildTaxonomyPivotQuery(
 	// Authoritative re-check on the joined `ec_*` row.
 	const deletedR = deletedIsNull ? sql`r.deleted_at IS NULL` : sql`r.deleted_at IS NOT NULL`;
 	const statusR = status !== undefined ? sql`AND ${buildStatusCondition(db, status, "r")}` : sql``;
-	const localeR = locale ? sql`AND r.locale = ${locale}` : sql``;
+	const localeR = locale ? sql`AND ${localeMatches("r.locale", locale)}` : sql``;
 
 	if (isIndexedSort) {
 		const sortRef = sql.ref(`r.${primary.field}`);
@@ -1587,6 +1626,8 @@ export interface EntryFilter {
 	 * Used by preview mode to serve draft revision data.
 	 */
 	revisionId?: string;
+	/** Restrict slug resolution to published rows; explicit IDs remain addressable. */
+	publishedOnly?: boolean;
 	/**
 	 * Locale to scope slug lookup. Only affects slug resolution;
 	 * IDs are globally unique and always resolve regardless of locale.
@@ -1638,7 +1679,7 @@ export async function loadPublishedDates(type: string, locale?: string) {
 		SELECT published_at, updated_at FROM ${sql.ref(tableName)}
 		WHERE deleted_at IS NULL
 		AND ${buildStatusCondition(db, "published")}
-		${locale ? sql`AND locale = ${locale}` : sql``}
+		${locale ? sql`AND ${localeMatches("locale", locale)}` : sql``}
 		ORDER BY published_at DESC, id DESC
 	`.execute(db);
 	return result.rows;
@@ -1674,6 +1715,7 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, LoaderCollect
 		 * Load all entries for a content type
 		 */
 		async loadCollection({ filter }) {
+			const callerColumns = new Set<string>();
 			try {
 				// Get DB instance (initializes on first use)
 				const db = await getDb();
@@ -1774,6 +1816,19 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, LoaderCollect
 					return { error: new Error(message) };
 				}
 
+				// Only caller-supplied field columns may fail as invalid filters.
+				// Keep qualifiers so a folded system-table read cannot be mistaken
+				// for a caller field with the same name.
+				for (const key of [...Object.keys(fieldFilters), ...Object.keys(orderBy ?? {})]) {
+					if (!FIELD_NAME_PATTERN.test(key) || SYSTEM_QUERY_KEYS.has(key)) continue;
+					const name = key.toLowerCase();
+					callerColumns.add(name);
+					callerColumns.add(`${tableName}.${name}`);
+					if (taxonomyFilters.length > 0 && Object.keys(fieldFilters).length === 0) {
+						callerColumns.add(`r.${name}`);
+					}
+				}
+
 				// A byline or taxonomy filter with no values matches nothing —
 				// short-circuit before building SQL (an empty `IN ()` is invalid
 				// SQL on both dialects).
@@ -1853,7 +1908,7 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, LoaderCollect
 					// conditions reference unprefixed columns as before.
 					const orderByClause = buildOrderByClause(orderBy);
 					const statusCondition = buildStatusCondition(db, status);
-					const localeFilter = locale ? sql`AND locale = ${locale}` : sql``;
+					const localeFilter = locale ? sql`AND ${localeMatches("locale", locale)}` : sql``;
 					const cursorCond = cursorCondition ? sql`AND ${cursorCondition}` : sql``;
 					const fieldConds = buildFieldConditions(db, fieldFilters);
 					const fieldCondsSQL =
@@ -1874,7 +1929,7 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, LoaderCollect
 								AND ct.entry_id = ${sql.ref(tableName)}.translation_group
 								AND t.name = ${f.name}
 								AND t.slug IN (${sql.join(f.slugs.map((s) => sql`${s}`))})
-							${locale ? sql`AND t.locale = ${locale}` : sql``}
+							${locale ? sql`AND ${localeMatches("t.locale", locale)}` : sql``}
 						)`,
 									),
 									sql` `,
@@ -1990,14 +2045,15 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, LoaderCollect
 					},
 				};
 			} catch (error) {
-				// Handle missing table/column gracefully - return empty collection.
-				// Missing table happens before migrations have run.
-				// Missing column happens when a where filter references a non-existent field.
+				// Missing tables are expected before migrations run. Only a missing
+				// caller field is an invalid filter; other columns indicate schema errors.
 				const message = error instanceof Error ? error.message : String(error);
-				if (isMissingTableError(error) || isMissingColumnError(error)) {
-					if (isMissingColumnError(error)) {
-						console.warn(`[emdash] where filter: ${message}`);
-					}
+				if (isMissingTableError(error)) {
+					return { entries: [] };
+				}
+				const missingColumn = getMissingColumnIdentifier(error);
+				if (missingColumn && callerColumns.has(missingColumn)) {
+					console.warn(`[emdash] where filter: ${message}`);
 					return { entries: [] };
 				}
 
@@ -2063,19 +2119,21 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, LoaderCollect
 					)
 					FROM (SELECT ${bylinesExistSelect}, ${booleanFieldsSelect}) AS metadata
 				) AS _emdash_entry_metadata`;
+				const slugVisibility = filter?.publishedOnly ? sql`AND c.status = ${"published"}` : sql``;
 				const result = locale
 					? await sql<Record<string, unknown>>`
 							SELECT c.*, ${seoSelect}, ${termsSelect}, ${bylinesSelect}, ${metadataSelect}
 							FROM ${sql.ref(tableName)} AS c
 							WHERE c.deleted_at IS NULL
-							AND ((c.slug = ${id} AND c.locale = ${locale}) OR c.id = ${id})
+							AND ((c.slug = ${id} AND ${localeMatches("c.locale", locale)} ${slugVisibility}) OR c.id = ${id})
+							ORDER BY CASE WHEN c.id = ${id} THEN 0 ELSE 1 END, ${localeOrder("c.locale", locale)}, c.id
 							LIMIT 1
 						`.execute(db)
 					: await sql<Record<string, unknown>>`
 							SELECT c.*, ${seoSelect}, ${termsSelect}, ${bylinesSelect}, ${metadataSelect}
 							FROM ${sql.ref(tableName)} AS c
 							WHERE c.deleted_at IS NULL
-							AND (c.slug = ${id} OR c.id = ${id})
+							AND ((c.slug = ${id} ${slugVisibility}) OR c.id = ${id})
 							LIMIT 1
 						`.execute(db);
 

package/src/mcp/server.ts

@@ -41,6 +41,7 @@ import { invalidateRouteCache } from "../cache/route-cache.js";
 import { convertDataForRead, convertDataForWrite } from "../client/portable-text.js";
 import type { FieldSchema } from "../client/portable-text.js";
 import { decodeCursor, InvalidCursorError } from "../database/repositories/types.js";
+import { resolveConfiguredLocale } from "../i18n/config.js";
 import type { RouteCallerInput } from "../plugins/routes.js";
 import {
 	TRANSFER_SCOPES,
@@ -560,6 +561,14 @@ function isPublished(t: unknown): boolean {
 	);
 }
 
+function isEntry(t: unknown, idOrSlug: string): boolean {
+	return (
+		typeof t === "object" &&
+		t !== null &&
+		(("id" in t && t.id === idOrSlug) || ("slug" in t && t.slug === idOrSlug))
+	);
+}
+
 function getExtra(extra: { authInfo?: { extra?: Record<string, unknown> } }): EmDashExtra {
 	const payload = extra.authInfo?.extra as EmDashExtra | undefined;
 	if (!payload?.emdash) {
@@ -1138,6 +1147,15 @@ export function createMcpServer(
 						error: { code: "NOT_FOUND", message: `Content item not found: ${args.id}` },
 					});
 				}
+				// handleContentGet overlays the draft revision onto item.data and
+				// moves the published values to item.liveData.
+				if (item) {
+					if (item.liveData && typeof item.liveData === "object") {
+						item.data = item.liveData;
+					}
+					delete item.liveData;
+					delete item.draftRevisionId;
+				}
 			}
 			if (result.success && args.markdown && result.data?.item) {
 				await applyReadMarkdown(ec, args.collection, [result.data.item]);
@@ -1983,6 +2001,8 @@ export function createMcpServer(
 			const result = await ec.handleContentTranslations(args.collection, args.id);
 			// Filter out non-published translations for users without draft
 			// access so a subscriber can't enumerate locales that aren't yet live.
+			// The requested entry is one of the translations; if it isn't
+			// published, report it as not found so its id or slug can't be probed.
 			if (result.success && !canReadDrafts(extra)) {
 				const data =
 					result.data && typeof result.data === "object"
@@ -1991,6 +2011,12 @@ export function createMcpServer(
 						: undefined;
 				const translations = Array.isArray(data?.translations) ? data.translations : [];
 				const filtered = translations.filter(isPublished);
+				if (!filtered.some((t) => isEntry(t, args.id))) {
+					return unwrap({
+						success: false,
+						error: { code: "NOT_FOUND", message: `Content item not found: ${args.id}` },
+					});
+				}
 				return unwrap({
 					success: true,
 					data: { ...data, translations: filtered },
@@ -3182,7 +3208,8 @@ export function createMcpServer(
 					if (
 						!cursorTerm ||
 						cursorTerm.name !== args.taxonomy ||
-						(args.locale !== undefined && cursorTerm.locale !== args.locale)
+						(args.locale !== undefined &&
+							resolveConfiguredLocale(cursorTerm.locale) !== resolveConfiguredLocale(args.locale))
 					) {
 						return respondError("INVALID_CURSOR", "Pagination cursor no longer identifies a term");
 					}

package/src/media/caption.ts

@@ -0,0 +1,30 @@
+interface CaptionedMedia {
+	caption?: string;
+	meta?: Record<string, unknown>;
+}
+
+export function getMediaCaption(value: { caption?: unknown; meta?: unknown }): string | undefined {
+	if (typeof value.caption === "string") return value.caption;
+	if (
+		value.meta &&
+		typeof value.meta === "object" &&
+		"caption" in value.meta &&
+		typeof value.meta.caption === "string"
+	) {
+		return value.meta.caption;
+	}
+	return undefined;
+}
+
+/** Keep the legacy metadata alias consistent with the per-use caption. */
+export function syncMediaCaption<T extends CaptionedMedia>(value: T): T {
+	const caption = getMediaCaption(value);
+	if (caption === undefined) return value;
+	return {
+		...value,
+		caption,
+		...(value.meta && Object.hasOwn(value.meta, "caption")
+			? { meta: { ...value.meta, caption } }
+			: {}),
+	};
+}

package/src/media/image-endpoint.ts

@@ -193,6 +193,8 @@ const SAFE_STORAGE_KEY = /^[A-Za-z0-9._-]+$/;
 
 /** Plain decimal digits only -- rejects "1e3", "0x10", "+5", whitespace. */
 const DECIMAL_DIGITS = /^\d+$/;
+const NUMERIC_QUALITY = /^-?\d+(?:\.\d+)?(?:e[+-]?\d+)?$/i;
+const QUALITY_PRESETS: Record<string, number> = { low: 25, mid: 50, high: 80, max: 100 };
 
 /** Whether a storage key is safe to resolve against the storage backend. */
 export function isSafeTransformKey(key: string): boolean {
@@ -256,8 +258,9 @@ export function resolveTransformQuality(
  * Parse and validate `?w=&h=&f=&q=` query params. Width is required (it sizes
  * the rendition); dimensions are bounded so a request can't ask for an
  * unbounded or nonsensical transform. Format falls back to
- * {@link DEFAULT_TRANSFORM_FORMAT} when not requested. `q` is validated when
- * present but otherwise left `undefined` so the caller can apply a per-format
+ * {@link DEFAULT_TRANSFORM_FORMAT} when not requested. `q` accepts Astro presets
+ * or finite numbers rounded and clamped to 1-100. It is otherwise left
+ * `undefined` so the caller can apply a per-format
  * default (lossy formats get one, lossless PNG does not — see
  * {@link DEFAULT_TRANSFORM_QUALITY}).
  */
@@ -281,11 +284,15 @@ export function parseTransformParams(params: URLSearchParams): ParsedTransformPa
 	let quality: number | undefined;
 	const qualityRaw = params.get("q");
 	if (qualityRaw !== null) {
-		const q = Number(qualityRaw);
-		if (!Number.isInteger(q) || q < 1 || q > 100) {
-			return { ok: false, message: "Invalid 'q' (quality), expected 1-100" };
+		if (Object.hasOwn(QUALITY_PRESETS, qualityRaw)) {
+			quality = QUALITY_PRESETS[qualityRaw];
+		} else {
+			const q = NUMERIC_QUALITY.test(qualityRaw) ? Number(qualityRaw) : Number.NaN;
+			if (!Number.isFinite(q)) {
+				return { ok: false, message: "Invalid 'q' (quality), expected a number or Astro preset" };
+			}
+			quality = Math.round(Math.min(100, Math.max(1, q)));
 		}
-		quality = q;
 	}
 
 	return { ok: true, options: { width, height, format, quality } };

package/src/media/local-runtime.ts

@@ -79,6 +79,7 @@ export const createMediaProvider: CreateMediaProviderFn<LocalMediaRuntimeConfig>
 					blurhash: item.blurhash ?? undefined,
 					dominantColor: item.dominantColor ?? undefined,
 					alt: item.alt ?? undefined,
+					caption: item.caption ?? undefined,
 					previewUrl: `/_emdash/api/media/file/${item.storageKey}`,
 					meta: {
 						storageKey: item.storageKey,
@@ -107,6 +108,7 @@ export const createMediaProvider: CreateMediaProviderFn<LocalMediaRuntimeConfig>
 				blurhash: item.blurhash ?? undefined,
 				dominantColor: item.dominantColor ?? undefined,
 				alt: item.alt ?? undefined,
+				caption: item.caption ?? undefined,
 				previewUrl: `/_emdash/api/media/file/${item.storageKey}`,
 				meta: {
 					storageKey: item.storageKey,
@@ -236,6 +238,7 @@ export function repoItemToProviderItem(item: {
 		blurhash: item.blurhash ?? undefined,
 		dominantColor: item.dominantColor ?? undefined,
 		alt: item.alt ?? undefined,
+		caption: item.caption ?? undefined,
 		previewUrl: `/_emdash/api/media/file/${item.storageKey}`,
 		meta: {
 			storageKey: item.storageKey,

package/src/media/normalize.ts

@@ -9,6 +9,7 @@
  * the provider's `get()` method.
  */
 
+import { syncMediaCaption } from "./caption.js";
 import { normalizeFocalPoint } from "./focal-point.js";
 import type { MediaProvider, MediaProviderItem, MediaValue } from "./types.js";
 
@@ -151,7 +152,7 @@ async function resolveInternalUrl(
 	}
 
 	const focalPoint = normalizeFocalPoint(item.focalX, item.focalY);
-	return {
+	return syncMediaCaption({
 		provider: "local",
 		id: item.id,
 		filename: item.filename,
@@ -162,8 +163,9 @@ async function resolveInternalUrl(
 		blurhash: item.blurhash,
 		dominantColor: item.dominantColor,
 		alt: item.alt,
+		caption: item.caption,
 		meta: item.meta,
-	};
+	});
 }
 
 async function resolveLocalId(
@@ -184,7 +186,7 @@ async function resolveLocalId(
 	if (!item) return null;
 
 	const focalPoint = normalizeFocalPoint(item.focalX, item.focalY);
-	return {
+	return syncMediaCaption({
 		provider: "local",
 		id: item.id,
 		filename: item.filename,
@@ -195,13 +197,15 @@ async function resolveLocalId(
 		blurhash: item.blurhash,
 		dominantColor: item.dominantColor,
 		alt: item.alt,
+		caption: item.caption,
 		meta: item.meta,
-	};
+	});
 }
 
 /**
- * Merge provider data into an existing MediaValue, preserving caller-supplied fields.
- * Caller `alt` takes priority over provider `alt` (per-usage, not per-image).
+ * Fill missing media metadata from a provider.
+ * Caller captions, including empty strings, take priority over provider captions.
+ * Provider alt text fills missing or empty caller alt text.
  */
 function mergeProviderData(existing: MediaValue, item: MediaProviderItem): MediaValue {
 	const result = { ...existing };
@@ -223,12 +227,14 @@ function mergeProviderData(existing: MediaValue, item: MediaProviderItem): Media
 	// Fill missing alt (provider alt is fallback, not override)
 	if (!result.alt && item.alt) result.alt = item.alt;
 
+	if (result.caption == null && item.caption != null) result.caption = item.caption;
+
 	// Fill missing meta (merge, don't replace)
 	if (item.meta) {
 		result.meta = { ...item.meta, ...result.meta };
 	}
 
-	return result;
+	return syncMediaCaption(result);
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -258,6 +264,7 @@ function recordToMediaValue(obj: Record<string, unknown>): MediaValue {
 	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;
+	if (typeof obj.caption === "string") result.caption = obj.caption;
 	if (isRecord(obj.meta)) result.meta = obj.meta;
-	return result;
+	return syncMediaCaption(result);
 }

package/src/media/responsive.ts

@@ -9,6 +9,8 @@
  * resolves inside an Astro project, not in this precompiled package).
  */
 
+import type { EmbedOptions } from "./types.js";
+
 /** Standard responsive breakpoints. Matches CDN-provider srcset generation. */
 export const RESPONSIVE_BREAKPOINTS = [640, 750, 828, 960, 1080, 1280, 1600, 1920];
 
@@ -100,6 +102,7 @@ export type GetImage = (options: {
 	height?: number;
 	widths?: number[];
 	sizes?: string;
+	quality?: EmbedOptions["quality"];
 }) => Promise<{ src: string; srcSet?: { attribute?: string } | undefined }>;
 
 export interface ResponsiveImage {
@@ -127,9 +130,15 @@ export interface ResponsiveImage {
  */
 export async function buildResponsiveImage(
 	getImage: GetImage,
-	opts: { src: string; width?: number; height?: number; originalWidth?: number },
+	opts: {
+		src: string;
+		width?: number;
+		height?: number;
+		originalWidth?: number;
+		quality?: EmbedOptions["quality"];
+	},
 ): Promise<ResponsiveImage | null> {
-	const { src, width, height, originalWidth } = opts;
+	const { src, width, height, originalWidth, quality } = opts;
 	if (!src || !width || !height) return null;
 	if (!ABSOLUTE_HTTP_URL.test(src)) return null;
 	try {
@@ -140,6 +149,7 @@ export async function buildResponsiveImage(
 			height,
 			widths: responsiveWidths(width, originalWidth),
 			sizes,
+			...(quality !== undefined ? { quality } : {}),
 		});
 		// Passthrough: the service returned the source unchanged (unauthorized
 		// host or no optimization available). Don't emit a no-op srcset.

package/src/media/types.ts

@@ -6,6 +6,7 @@
  * alongside the built-in local media library.
  */
 
+import { syncMediaCaption } from "./caption.js";
 import { normalizeFocalPoint } from "./focal-point.js";
 
 /**
@@ -96,6 +97,8 @@ export interface MediaProviderItem {
 	dominantColor?: string;
 	/** Accessibility text */
 	alt?: string;
+	/** Default caption for display or attribution */
+	caption?: string;
 	/** Preview URL for admin UI thumbnail */
 	previewUrl?: string;
 	/** Provider-specific metadata */
@@ -121,6 +124,8 @@ export interface EmbedOptions {
 	height?: number;
 	/** Image format preference */
 	format?: "webp" | "avif" | "jpeg" | "png" | "auto";
+	/** Output quality (numeric or a provider-supported preset). */
+	quality?: number | string;
 }
 
 /**
@@ -143,7 +148,12 @@ export interface ImageEmbed {
 	/** Base URL without transforms, for responsive image generation */
 	cdnBaseUrl?: string;
 	/** For providers with URL-based transforms (Cloudinary, imgix) */
-	getSrc?: (opts: { width?: number; height?: number; format?: string }) => string;
+	getSrc?: (opts: {
+		width?: number;
+		height?: number;
+		format?: string;
+		quality?: EmbedOptions["quality"];
+	}) => string;
 }
 
 export interface VideoEmbed {
@@ -277,6 +287,8 @@ export interface MediaValue {
 	/** Cached LQIP dominant-color placeholder, as a CSS color (images only) */
 	dominantColor?: string;
 	alt?: string;
+	/** Caption for display or attribution */
+	caption?: string;
 
 	/** Provider-specific data needed for embedding */
 	meta?: Record<string, unknown>;
@@ -287,7 +299,7 @@ export interface MediaValue {
  */
 export function mediaItemToValue(providerId: string, item: MediaProviderItem): MediaValue {
 	const focalPoint = normalizeFocalPoint(item.focalX, item.focalY);
-	return {
+	return syncMediaCaption({
 		provider: providerId,
 		id: item.id,
 		filename: item.filename,
@@ -298,6 +310,7 @@ export function mediaItemToValue(providerId: string, item: MediaProviderItem): M
 		blurhash: item.blurhash,
 		dominantColor: item.dominantColor,
 		alt: item.alt,
+		caption: item.caption,
 		meta: item.meta,
-	};
+	});
 }

package/src/menus/index.ts

@@ -14,6 +14,8 @@ import { sql } from "kysely";
 import { menuTag } from "../cache/chrome-tags.js";
 import type { Database } from "../database/types.js";
 import { validateIdentifier } from "../database/validate.js";
+import { getLocaleChainRank, getLocaleRank } from "../i18n/config.js";
+import { localeMatches } from "../i18n/query.js";
 import {
 	resolveLocalizedContentRoutePath,
 	resolveLocale,
@@ -94,13 +96,19 @@ export async function getMenuWithDb(
 		])
 		.where("m.name", "=", name)
 		.orderBy("i.sort_order", "asc");
-	if (chain.length > 0) query = query.where("m.locale", "in", chain);
+	if (chain.length > 0) {
+		query = query.where((eb) => eb.or(chain.map((locale) => localeMatches("m.locale", locale))));
+	}
 	const rows = await query.execute();
-
-	const locales = new Set(rows.map((row) => row.m_locale));
-	const locale =
-		chain.length === 0 ? [...locales].toSorted()[0] : chain.find((l) => locales.has(l));
-	const menuRow = rows.find((row) => row.m_locale === locale);
+	const sortedRows = rows.toSorted((a, b) => {
+		if (chain.length === 0)
+			return a.m_locale.localeCompare(b.m_locale) || a.m_id.localeCompare(b.m_id);
+		return (
+			getLocaleChainRank(a.m_locale, chain) - getLocaleChainRank(b.m_locale, chain) ||
+			a.m_id.localeCompare(b.m_id)
+		);
+	});
+	const menuRow = sortedRows[0];
 	if (!menuRow) return null;
 
 	const menuId = menuRow.m_id;
@@ -146,7 +154,7 @@ export async function getMenusWithDb(
 		.selectFrom("_emdash_menus")
 		.select(["id", "name", "label", "locale"])
 		.orderBy("name", "asc");
-	if (locale !== undefined) query = query.where("locale", "=", locale);
+	if (locale !== undefined) query = query.where(localeMatches("locale", locale));
 	return query.execute();
 }
 
@@ -439,11 +447,13 @@ function shouldPreferLocalizedRow(
 	locale: string,
 ): boolean {
 	if (!existing) return true;
-	if (candidate.locale === locale) return existing.locale !== locale || candidate.id < existing.id;
-	if (existing.locale === locale) return false;
+	const candidateRank = getLocaleRank(candidate.locale, locale);
+	const existingRank = getLocaleRank(existing.locale, locale);
 	return (
-		candidate.locale < existing.locale ||
-		(candidate.locale === existing.locale && candidate.id < existing.id)
+		candidateRank < existingRank ||
+		(candidateRank === existingRank &&
+			(candidate.locale < existing.locale ||
+				(candidate.locale === existing.locale && candidate.id < existing.id)))
 	);
 }
 

package/src/migrations/manifest.ts

@@ -23,6 +23,7 @@ const i18nConfigSchema = z
 	.object({
 		defaultLocale: z.string().min(1),
 		locales: z.array(z.string().min(1)).min(1),
+		localeAliases: z.record(z.string(), z.string()).optional(),
 		fallback: z.record(z.string(), z.string()).optional(),
 		prefixDefaultLocale: z.boolean().optional(),
 	})

package/src/plugins/byline-access.ts

@@ -8,6 +8,7 @@ import {
 } from "../database/repositories/types.js";
 import type { Database } from "../database/types.js";
 import { validateIdentifier } from "../database/validate.js";
+import { localeMatches } from "../i18n/query.js";
 import { chunks, SQL_BATCH_SIZE } from "../utils/chunks.js";
 import type { BylineAccess, BylineCreditInfo, BylineInfo } from "./types.js";
 
@@ -116,7 +117,8 @@ export function createBylineAccess(db: Kysely<Database>): BylineAccess {
 				.orderBy("created_at", "desc")
 				.orderBy("id", "desc")
 				.limit(limit + 1);
-			if (options?.locale !== undefined) query = query.where("locale", "=", options.locale);
+			if (options?.locale !== undefined)
+				query = query.where(localeMatches("locale", options.locale));
 			if (options?.cursor) {
 				const decoded = decodeCursor(options.cursor);
 				query = query.where((eb) =>