emdash 1.3.0 → 1.4.0

package/src/media/content-disposition.ts

@@ -0,0 +1,56 @@
+/**
+ * Content-Disposition header construction for media downloads.
+ *
+ * The public media file route serves every non-inline type as an attachment.
+ * Without a `filename` parameter the browser falls back to the last path
+ * segment of the URL -- the storage key -- so a downloaded PDF lands in the
+ * user's filesystem named after its ULID. These helpers build a header that
+ * names the file the way the editor uploaded it.
+ */
+
+/**
+ * Characters unsafe in a filename on one or more platforms, plus the quote and
+ * backslash that would otherwise break out of the quoted `filename=` value.
+ */
+// eslint-disable-next-line no-control-regex -- stripping control characters is the point
+const UNSAFE_FILENAME_CHARS = /[\x00-\x1F\x7F"\\/<>:|?*]/g;
+
+/** Anything outside printable ASCII, carried by `filename*` instead. */
+const NON_ASCII = /[^\x20-\x7E]/g;
+
+/**
+ * An ASCII-only, filesystem-safe rendering of `filename`, for the quoted
+ * `filename=` parameter that older clients read.
+ */
+export function toAsciiFilename(filename: string): string {
+	const cleaned = filename
+		.normalize("NFKD")
+		.replaceAll(UNSAFE_FILENAME_CHARS, "-")
+		.replaceAll(NON_ASCII, "")
+		.trim();
+	return cleaned.length > 0 ? cleaned : "download";
+}
+
+/**
+ * Build a `Content-Disposition` value.
+ *
+ * Emits both `filename` (ASCII, quoted) and RFC 5987 `filename*` (UTF-8
+ * percent-encoded) so a name with non-ASCII characters survives. Returns the
+ * bare disposition when no filename is known, which is the pre-existing
+ * behaviour for media with no database row.
+ */
+export function contentDisposition(
+	disposition: "inline" | "attachment",
+	filename?: string | null,
+): string {
+	if (!filename) return disposition;
+	const ascii = toAsciiFilename(filename);
+	// encodeURIComponent leaves ' ( ) * unescaped, but RFC 5987 attr-char does
+	// not allow them; a strict client would discard filename* and fall back to
+	// the ASCII name. Percent-encode them too.
+	const encoded = encodeURIComponent(filename).replace(
+		/['()*]/g,
+		(c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
+	);
+	return `${disposition}; filename="${ascii}"; filename*=UTF-8''${encoded}`;
+}

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";
 
@@ -29,6 +30,7 @@ export function normalizeLegacyExternalMediaValue(value: MediaValue): MediaValue
  * Normalize a media field value into a consistent MediaValue shape.
  *
  * - `null`/`undefined` → `null`
+ * - Empty or whitespace-only string → `null`
  * - Bare URL string → `{ provider: "external", id: "", src: url }`
  * - Bare internal media URL → resolved via local provider's `get()`
  * - Bare local media ID → resolved via local provider's `get()`
@@ -42,6 +44,7 @@ export async function normalizeMediaValue(
 
 	// Bare string URL
 	if (typeof value === "string") {
+		if (value.trim() === "") return null;
 		return normalizeStringUrl(value, getProvider);
 	}
 
@@ -151,7 +154,7 @@ async function resolveInternalUrl(
 	}
 
 	const focalPoint = normalizeFocalPoint(item.focalX, item.focalY);
-	return {
+	return syncMediaCaption({
 		provider: "local",
 		id: item.id,
 		filename: item.filename,
@@ -162,8 +165,9 @@ async function resolveInternalUrl(
 		blurhash: item.blurhash,
 		dominantColor: item.dominantColor,
 		alt: item.alt,
+		caption: item.caption,
 		meta: item.meta,
-	};
+	});
 }
 
 async function resolveLocalId(
@@ -184,7 +188,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 +199,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 +229,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 +266,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/media/usage/content-fields.ts

@@ -4,6 +4,7 @@ import type { Database } from "../../database/types.js";
 import { validateIdentifier } from "../../database/validate.js";
 import { BlockTypeRegistry } from "../../schema/block-type-registry.js";
 import type { BlockType } from "../../schema/block-types.js";
+import { isStoragelessFieldRow } from "../../schema/types.js";
 import { buildCanonicalSha256Fingerprint } from "./projection-fingerprint.js";
 import type { MediaUsageExtractionField, MediaUsageExtractionSubField } from "./types.js";
 import { CONTENT_SOURCE_SCHEMA_VERSION } from "./types.js";
@@ -89,7 +90,7 @@ export async function loadContentMediaUsageFields(
 		.select(["_emdash_fields.slug", "_emdash_fields.type", "_emdash_fields.validation"])
 		.where("_emdash_collections.slug", "=", collectionSlug);
 	if (collectionId !== undefined) query = query.where("_emdash_collections.id", "=", collectionId);
-	const rows = await query.execute();
+	const rows = (await query.execute()).filter((row) => !isStoragelessFieldRow(row));
 
 	const extractionFields: ContentMediaUsageField[] = [];
 	const rowBySlug = new Map<string, FieldDiscoveryRow>();

package/src/menus/index.ts

@@ -14,15 +14,23 @@ 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,
 	resolveLocaleChain,
 } from "../i18n/resolve.js";
 import { getDb } from "../loader.js";
-import { cachedQuery, CacheNamespace } from "../object-cache/index.js";
+import {
+	cachedQueryWithEpochs,
+	CacheNamespace,
+	contentCacheNamespaces,
+	isObjectCacheActive,
+} from "../object-cache/index.js";
 import type { CacheHint } from "../query.js";
 import { requestCached } from "../request-cache.js";
+import { getRequestContext } from "../request-context.js";
 import { chunks, SQL_BATCH_SIZE } from "../utils/chunks.js";
 import { sanitizeHref } from "../utils/url.js";
 import type { Menu, MenuItem, MenuItemRow } from "./types.js";
@@ -35,6 +43,19 @@ export interface MenuQueryOptions {
 	trailingSlash?: "always" | "never" | "ignore";
 }
 
+/** Per isolate: the namespaces each resolved menu was last cached under. */
+const LAST_RESOLVED_NAMESPACES_KEY = Symbol.for("emdash:menu-resolved-namespaces");
+const lastResolvedNamespaces: Map<string, string[]> =
+	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- globalThis singleton pattern
+	((globalThis as Record<symbol, unknown>)[LAST_RESOLVED_NAMESPACES_KEY] as
+		| Map<string, string[]>
+		| undefined) ??
+	(() => {
+		const map = new Map<string, string[]>();
+		(globalThis as Record<symbol, unknown>)[LAST_RESOLVED_NAMESPACES_KEY] = map;
+		return map;
+	})();
+
 /**
  * Get a menu by name with resolved URLs.
  *
@@ -47,16 +68,72 @@ export interface MenuQueryOptions {
 export async function getMenu(name: string, options: MenuQueryOptions = {}): Promise<Menu | null> {
 	const locale = resolveLocale(options.locale);
 	const trailingSlash = options.trailingSlash ?? (await getHostTrailingSlash());
-	return requestCached(`menu:${name}:${locale ?? "*"}:${trailingSlash}`, () =>
-		cachedQuery({
-			namespace: CacheNamespace.MENUS,
-			key: `${name}:${locale ?? "*"}:${trailingSlash}`,
+	const key = `${name}:${locale ?? "*"}:${trailingSlash}`;
+	return requestCached(`menu:${key}`, async () => {
+		if (!(await isObjectCacheActive())) {
+			return getMenuWithDb(name, await getDb(), { locale, trailingSlash });
+		}
+		const readRows = async () => {
+			let epoch: number | undefined;
+			const rows = await cachedQueryWithEpochs({
+				namespace: CacheNamespace.MENUS,
+				key: `rows:${name}:${locale ?? "*"}`,
+				load: async () => loadMenuRows(name, await getDb(), locale),
+				onEpochs: ([menus]) => {
+					epoch = menus;
+				},
+			});
+			return { rows, epoch };
+		};
+		const remembered = lastResolvedNamespaces.get(key);
+		const earlyRead = remembered ? undefined : await readRows();
+		const namespaces =
+			remembered ?? (earlyRead?.rows && resolvedMenuNamespaces(earlyRead.rows.items));
+		if (!namespaces) return null;
+		let resolvedEpoch: number | undefined;
+		let loaded: string[] | undefined;
+		const menu = await cachedQueryWithEpochs<Menu | null>({
+			namespace: namespaces,
+			key,
+			onEpochs: ([menus]) => {
+				resolvedEpoch = menus;
+			},
+			// Rows read before this query captured its epochs are reused only if no menu
+			// edit landed in between; otherwise the old items would be stored as current.
 			load: async () => {
-				const db = await getDb();
-				return getMenuWithDb(name, db, { locale, trailingSlash });
+				const { rows } =
+					earlyRead && earlyRead.epoch === resolvedEpoch ? earlyRead : await readRows();
+				if (!rows) return null;
+				loaded = resolvedMenuNamespaces(rows.items);
+				return resolveMenu(rows, await getDb(), trailingSlash);
 			},
-		}),
-	);
+			cacheable: (value) => value !== null && sameNamespaces(loaded, namespaces),
+		});
+		if (menu) lastResolvedNamespaces.set(key, loaded ?? namespaces);
+		else lastResolvedNamespaces.delete(key);
+		return menu;
+	});
+}
+
+/**
+ * Object-cache namespaces for a resolved menu: the menu epoch plus the content
+ * epoch of every collection its items link to, and the taxonomy epoch when it
+ * links to terms. Which links resolve depends on those rows, so publishing,
+ * unpublishing, or trashing a linked entry invalidates the cached menu.
+ */
+function resolvedMenuNamespaces(items: MenuItemRow[]): string[] {
+	const namespaces: string[] = [CacheNamespace.MENUS];
+	for (const collection of collectContentReferences(items).keys()) {
+		namespaces.push(...contentCacheNamespaces(collection));
+	}
+	if (items.some((item) => item.type === "taxonomy" && item.reference_id)) {
+		namespaces.push(CacheNamespace.TAXONOMIES);
+	}
+	return namespaces;
+}
+
+function sameNamespaces(a: readonly string[] | undefined, b: readonly string[]): boolean {
+	return a !== undefined && a.length === b.length && a.every((namespace, i) => namespace === b[i]);
 }
 
 async function getHostTrailingSlash(): Promise<"always" | "never" | "ignore"> {
@@ -79,7 +156,21 @@ export async function getMenuWithDb(
 	db: Kysely<Database>,
 	options: MenuQueryOptions = {},
 ): Promise<Menu | null> {
-	const chain = resolveLocaleChain(options.locale);
+	const rows = await loadMenuRows(name, db, options.locale);
+	return rows && resolveMenu(rows, db, options.trailingSlash);
+}
+
+interface MenuRows {
+	menu: Omit<Menu, "items">;
+	items: MenuItemRow[];
+}
+
+async function loadMenuRows(
+	name: string,
+	db: Kysely<Database>,
+	requestedLocale: string | undefined,
+): Promise<MenuRows | null> {
+	const chain = resolveLocaleChain(requestedLocale);
 
 	let query = db
 		.selectFrom("_emdash_menus as m")
@@ -94,13 +185,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;
@@ -108,15 +205,26 @@ export async function getMenuWithDb(
 		(row): row is typeof row & MenuItemRow => row.m_id === menuId && row.id !== null,
 	);
 
-	const items = await buildMenuTree(itemRows, db, menuRow.m_locale, options.trailingSlash);
+	return {
+		menu: {
+			id: menuRow.m_id,
+			name: menuRow.m_name,
+			label: menuRow.m_label,
+			locale: menuRow.m_locale,
+			translationGroup: menuRow.m_translation_group,
+		},
+		items: itemRows,
+	};
+}
 
+async function resolveMenu(
+	rows: MenuRows,
+	db: Kysely<Database>,
+	trailingSlash: MenuQueryOptions["trailingSlash"],
+): Promise<Menu> {
 	return {
-		id: menuRow.m_id,
-		name: menuRow.m_name,
-		label: menuRow.m_label,
-		items,
-		locale: menuRow.m_locale,
-		translationGroup: menuRow.m_translation_group,
+		...rows.menu,
+		items: await buildMenuTree(rows.items, db, rows.menu.locale, trailingSlash),
 	};
 }
 
@@ -146,7 +254,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();
 }
 
@@ -198,6 +306,7 @@ async function buildMenuTree(
 
 	const itemMap = new Map<string, MenuItem & { children: MenuItem[] }>();
 	const rootItems: MenuItem[] = [];
+	const itemIds = new Set(items.map((item) => item.id));
 
 	for (const item of validItems) {
 		itemMap.set(item.id, { ...item, children: [] });
@@ -206,10 +315,8 @@ async function buildMenuTree(
 	for (const item of items) {
 		const menuItem = itemMap.get(item.id);
 		if (!menuItem) continue;
-		if (item.parent_id) {
-			const parent = itemMap.get(item.parent_id);
-			if (parent) parent.children.push(menuItem);
-			else rootItems.push(menuItem);
+		if (item.parent_id && itemIds.has(item.parent_id)) {
+			itemMap.get(item.parent_id)?.children.push(menuItem);
 		} else {
 			rootItems.push(menuItem);
 		}
@@ -371,6 +478,8 @@ interface ContentReferenceRow {
 	published_at: string | null;
 	locale: string;
 	translation_group: string;
+	status: string;
+	deleted_at: string | null;
 }
 
 interface ResolvedContentReference {
@@ -386,19 +495,27 @@ async function resolveContentReferences(
 	references: Map<string, Set<string>>,
 	locale: string,
 ): Promise<ContentReferenceLookup> {
+	// Edit mode renders drafts, so a menu link to one still leads somewhere there.
+	const editMode = getRequestContext()?.editMode === true;
+	const isVisible = (row: { status: string; deleted_at: string | null }) =>
+		row.deleted_at === null && (editMode || row.status === "published");
 	const entries = await Promise.all(
 		Array.from(references, async ([collection, referenceGroups]) => {
 			const lookup = new Map<string, ResolvedContentReference>();
 			const localized = new Map<string, ContentReferenceRow>();
+			const found = new Set<string>();
 			try {
 				validateIdentifier(collection, "menu item collection");
 				for (const batch of chunks([...referenceGroups], SQL_BATCH_SIZE)) {
 					const result = await sql<ContentReferenceRow>`
-						SELECT id, slug, published_at, locale, translation_group
+						SELECT id, slug, published_at, locale, translation_group, status, deleted_at
 						FROM ${sql.ref(`ec_${collection}`)}
 						WHERE translation_group IN (${sql.join(batch)})
 					`.execute(db);
 					for (const row of result.rows) {
+						// A hidden row still counts as found, so the legacy id lookup below is skipped.
+						found.add(row.translation_group);
+						if (!isVisible(row)) continue;
 						const existing = localized.get(row.translation_group);
 						if (shouldPreferLocalizedRow(row, existing, locale)) {
 							localized.set(row.translation_group, row);
@@ -409,13 +526,16 @@ async function resolveContentReferences(
 					lookup.set(referenceGroup, { id: row.id, slug: row.slug, publishedAt: row.published_at });
 				}
 
-				const unresolved = [...referenceGroups].filter((id) => !lookup.has(id));
+				const unresolved = [...referenceGroups].filter((id) => !found.has(id));
 				for (const batch of chunks(unresolved, SQL_BATCH_SIZE)) {
-					const result = await sql<Pick<ContentReferenceRow, "id" | "slug" | "published_at">>`
-						SELECT id, slug, published_at FROM ${sql.ref(`ec_${collection}`)}
+					const result = await sql<
+						Pick<ContentReferenceRow, "id" | "slug" | "published_at" | "status" | "deleted_at">
+					>`
+						SELECT id, slug, published_at, status, deleted_at FROM ${sql.ref(`ec_${collection}`)}
 						WHERE id IN (${sql.join(batch)})
 					`.execute(db);
 					for (const row of result.rows) {
+						if (!isVisible(row)) continue;
 						lookup.set(row.id, { id: row.id, slug: row.slug, publishedAt: row.published_at });
 					}
 				}
@@ -439,11 +559,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(),
 	})