emdash 0.24.1 → 0.26.0

package/src/database/types.ts

@@ -60,6 +60,43 @@ export interface MediaTable {
 	author_id: string | null;
 }
 
+export interface MediaUsageSourceTable {
+	source_key: string;
+	source_type: string;
+	collection_slug: string | null;
+	content_id: string | null;
+	source_variant: string;
+	locale: string | null;
+	translation_group: string | null;
+	content_slug: string | null;
+	content_title: string | null;
+	content_status: string | null;
+	content_scheduled_at: string | null;
+	content_deleted_at: string | null;
+	revision_id: string | null;
+	current_generation: string;
+	schema_version: Generated<number>;
+	indexed_at: Generated<string>;
+	created_at: Generated<string>;
+	updated_at: Generated<string>;
+}
+
+export interface MediaUsageTable {
+	id: string;
+	source_key: string;
+	generation: string;
+	field_slug: string;
+	field_path: string;
+	occurrence_index: Generated<number>;
+	reference_type: string;
+	media_id: string | null;
+	provider: Generated<string>;
+	provider_asset_id: string;
+	media_kind: string | null;
+	mime_type: string | null;
+	created_at: Generated<string>;
+}
+
 export interface UserTable {
 	id: string;
 	email: string;
@@ -414,6 +451,8 @@ export interface Database {
 	content_taxonomies: ContentTaxonomyTable;
 	_emdash_taxonomy_defs: TaxonomyDefTable;
 	media: MediaTable;
+	_emdash_media_usage_sources: MediaUsageSourceTable;
+	_emdash_media_usage: MediaUsageTable;
 	users: UserTable;
 	credentials: CredentialTable;
 	auth_tokens: AuthTokenTable;

package/src/emdash-runtime.ts

@@ -2797,7 +2797,14 @@ export class EmDashRuntime {
 	}
 
 	async handleContentRestore(collection: string, id: string) {
-		return handleContentRestore(this.db, collection, id);
+		const result = await handleContentRestore(this.db, collection, id);
+
+		// Run afterRestore hooks (fire-and-forget)
+		if (result.success) {
+			this.runAfterRestoreHooks(contentItemToRecord(result.data.item), collection);
+		}
+
+		return result;
 	}
 
 	async handleContentPermanentDelete(collection: string, id: string) {
@@ -2850,11 +2857,25 @@ export class EmDashRuntime {
 	}
 
 	async handleContentSchedule(collection: string, id: string, scheduledAt: string) {
-		return handleContentSchedule(this.db, collection, id, scheduledAt);
+		const result = await handleContentSchedule(this.db, collection, id, scheduledAt);
+
+		// Run afterSchedule hooks (fire-and-forget)
+		if (result.success && result.data) {
+			this.runAfterScheduleHooks(contentItemToRecord(result.data.item), collection);
+		}
+
+		return result;
 	}
 
 	async handleContentUnschedule(collection: string, id: string) {
-		return handleContentUnschedule(this.db, collection, id);
+		const result = await handleContentUnschedule(this.db, collection, id);
+
+		// Run afterUnschedule hooks (fire-and-forget)
+		if (result.success && result.data) {
+			this.runAfterUnscheduleHooks(contentItemToRecord(result.data.item), collection);
+		}
+
+		return result;
 	}
 
 	async handleContentCountScheduled(collection: string) {
@@ -3313,14 +3334,41 @@ export class EmDashRuntime {
 		}
 	}
 
-	private runAfterPublishHooks(content: Record<string, unknown>, collection: string): void {
+	private runDeferredContentHook(
+		name:
+			| "content:afterPublish"
+			| "content:afterUnpublish"
+			| "content:afterRestore"
+			| "content:afterSchedule"
+			| "content:afterUnschedule",
+		content: Record<string, unknown>,
+		collection: string,
+	): void {
+		const label = name.slice("content:".length);
+
 		after(async () => {
 			// Trusted plugins
-			if (this.hooks.hasHooks("content:afterPublish")) {
+			if (this.hooks.hasHooks(name)) {
 				try {
-					await this.hooks.runContentAfterPublish(content, collection);
+					switch (name) {
+						case "content:afterPublish":
+							await this.hooks.runContentAfterPublish(content, collection);
+							break;
+						case "content:afterUnpublish":
+							await this.hooks.runContentAfterUnpublish(content, collection);
+							break;
+						case "content:afterRestore":
+							await this.hooks.runContentAfterRestore(content, collection);
+							break;
+						case "content:afterSchedule":
+							await this.hooks.runContentAfterSchedule(content, collection);
+							break;
+						case "content:afterUnschedule":
+							await this.hooks.runContentAfterUnschedule(content, collection);
+							break;
+					}
 				} catch (err) {
-					console.error("EmDash afterPublish hook error:", err);
+					console.error(`EmDash ${label} hook error:`, err);
 				}
 			}
 
@@ -3333,9 +3381,9 @@ export class EmDashRuntime {
 				tasks.push(
 					(async () => {
 						try {
-							await plugin.invokeHook("content:afterPublish", { content, collection });
+							await plugin.invokeHook(name, { content, collection });
 						} catch (err) {
-							console.error(`EmDash: Sandboxed plugin ${pluginId} afterPublish error:`, err);
+							console.error(`EmDash: Sandboxed plugin ${pluginId} ${label} error:`, err);
 						}
 					})(),
 				);
@@ -3344,25 +3392,24 @@ export class EmDashRuntime {
 		});
 	}
 
+	private runAfterPublishHooks(content: Record<string, unknown>, collection: string): void {
+		this.runDeferredContentHook("content:afterPublish", content, collection);
+	}
+
 	private runAfterUnpublishHooks(content: Record<string, unknown>, collection: string): void {
-		// Trusted plugins
-		if (this.hooks.hasHooks("content:afterUnpublish")) {
-			this.hooks
-				.runContentAfterUnpublish(content, collection)
-				.catch((err) => console.error("EmDash afterUnpublish hook error:", err));
-		}
+		this.runDeferredContentHook("content:afterUnpublish", content, collection);
+	}
 
-		// Sandboxed plugins
-		for (const [pluginKey, plugin] of this.sandboxedPlugins) {
-			const [pluginId] = pluginKey.split(":");
-			if (!pluginId || !this.isPluginEnabled(pluginId)) continue;
+	private runAfterRestoreHooks(content: Record<string, unknown>, collection: string): void {
+		this.runDeferredContentHook("content:afterRestore", content, collection);
+	}
 
-			plugin
-				.invokeHook("content:afterUnpublish", { content, collection })
-				.catch((err) =>
-					console.error(`EmDash: Sandboxed plugin ${pluginId} afterUnpublish error:`, err),
-				);
-		}
+	private runAfterScheduleHooks(content: Record<string, unknown>, collection: string): void {
+		this.runDeferredContentHook("content:afterSchedule", content, collection);
+	}
+
+	private runAfterUnscheduleHooks(content: Record<string, unknown>, collection: string): void {
+		this.runDeferredContentHook("content:afterUnschedule", content, collection);
 	}
 
 	private async handleSandboxedRoute(

package/src/index.ts

@@ -255,6 +255,9 @@ export type {
 	ContentHookEvent,
 	ContentDeleteEvent,
 	ContentPublishStateChangeEvent,
+	ContentRestoreStateChangeEvent,
+	ContentScheduleStateChangeEvent,
+	ContentStateChangeEvent,
 	MediaUploadEvent,
 	HookResult,
 	PluginRoute,

package/src/loader.ts

@@ -25,15 +25,23 @@ import { isMissingColumnError, isMissingTableError } from "./utils/db-errors.js"
 const FIELD_NAME_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
 
 /**
- * SEO columns joined in from `_emdash_seo` on the single-entry path, mapped to
- * aliased result keys. SEO lives in a side table, so a LEFT JOIN folds it into
- * the entry load at zero extra query cost; the result is surfaced as a nested
- * `data.seo` object (see extractSeo) rather than flat fields.
+ * SEO columns folded into the single-entry query as a single JSON column
+ * (`_emdash_seo` in the result set), then expanded onto the row under these
+ * aliases for `extractSeo()`. Surfacing SEO as one aggregated column keeps the
+ * result-set width bounded regardless of how many fields the collection has,
+ * which matters for D1: a flat `LEFT JOIN _emdash_seo` adds 5 alias columns to
+ * every row and pushes wide collections (common after WordPress / ACF imports)
+ * past D1's per-result-set column limit, surfacing as a silent null entry.
+ * One JSON column is one column, so the join stays safe at any schema width.
+ *
+ * The aliases mirror the strategy used by `foldedHydrationSelects` for byline
+ * and taxonomy hydration: aggregate in SQL, expand in JS. SEO is 1:1 with
+ * content, so the subquery uses `json_object` (not the array aggregator).
  *
  * The `_emdash_` prefix on the aliases guarantees they can never collide with
  * a content field. Field slugs must match `/^[a-z][a-z0-9_]*$/`, so a user can
- * legitimately define a `seo_title` field; selecting the joined column under
- * its bare name would shadow that field in the result set and drop the user's
+ * legitimately define a `seo_title` field; surfacing the SEO column under its
+ * bare name would shadow that field in the result set and drop the user's
  * value. The prefix (illegal as a leading slug char) sidesteps this entirely.
  */
 const SEO_COLUMN_ALIASES: Record<string, string> = {
@@ -47,6 +55,9 @@ const SEO_COLUMN_ALIASES: Record<string, string> = {
 /** Aliased SEO result keys — excluded from generic field mapping. */
 const SEO_ALIAS_COLUMNS = Object.values(SEO_COLUMN_ALIASES);
 
+/** Folded SEO JSON column name in the result set (expanded onto aliases in JS). */
+const SEO_FOLDED_COLUMN = "_emdash_seo";
+
 /**
  * System columns excluded from entry.data
  * Note: slug is intentionally NOT excluded - it's useful as data.slug in templates
@@ -67,15 +78,17 @@ const SYSTEM_COLUMNS = new Set([
 	"draft_revision_id",
 	"locale",
 	"translation_group",
-	// Aliased SEO columns joined from _emdash_seo on the single-entry path.
-	// Surfaced as a nested data.seo object (see extractSeo), never as flat
-	// fields. The aliases are _emdash_-prefixed so they can't shadow a user
-	// field named e.g. `seo_title`.
+	// Aliased SEO columns expanded from the folded _emdash_seo JSON column on
+	// the single-entry path. Surfaced as a nested data.seo object (see
+	// extractSeo), never as flat fields. The aliases are _emdash_-prefixed so
+	// they can't shadow a user field named e.g. `seo_title`.
 	...SEO_ALIAS_COLUMNS,
-	// Folded hydration JSON columns (see foldedHydrationSelects) — surfaced via
-	// the FOLDED_* markers, never as flat fields.
+	// Folded hydration JSON columns (see foldedHydrationSelects and
+	// foldedSeoSelect) — surfaced via the FOLDED_* markers or expanded onto
+	// SEO_ALIAS_COLUMNS, never as flat fields.
 	"_emdash_terms",
 	"_emdash_bylines",
+	SEO_FOLDED_COLUMN,
 ]);
 
 /** Markers for byline/taxonomy hydration folded into the content query. */
@@ -123,6 +136,62 @@ function foldedHydrationSelects(db: Kysely<any>, type: string, outer: string) {
 	return { terms, bylines };
 }
 
+/**
+ * Correlated JSON-object subquery that folds per-entry SEO into the content
+ * query without widening the result set: 1 row of `_emdash_seo` becomes 1 JSON
+ * column rather than 5 flat columns. The JSON column is expanded onto the row
+ * via {@link expandFoldedSeo} after the query runs, preserving the alias keys
+ * that {@link extractSeo} reads. Missing SEO row (no entry in `_emdash_seo`)
+ * yields NULL, which {@link expandFoldedSeo} treats as "no SEO" - identical to
+ * the prior LEFT JOIN miss behavior.
+ *
+ * Dialect-specific aggregation mirrors {@link foldedHydrationSelects}: SQLite
+ * `json_object` returns a JSON *string*, Postgres `json_build_object` returns
+ * parsed JSON; both branches are handled in expansion.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any -- any Kysely instance
+function foldedSeoSelect(db: Kysely<any>, type: string, outer: string) {
+	const o = sql.ref(outer);
+	const pg = isPostgres(db);
+	// Use raw column names (not aliases) as JSON keys: the JSON is expanded back
+	// onto SEO_COLUMN_ALIASES in JS, and keeping the keys matched to the
+	// underlying columns makes the SQL readable and the expansion 1-to-1.
+	const pairs =
+		"'seo_title', s.seo_title, 'seo_description', s.seo_description, 'seo_image', s.seo_image, 'seo_canonical', s.seo_canonical, 'seo_no_index', s.seo_no_index";
+	const obj = pg ? sql.raw(`json_build_object(${pairs})`) : sql.raw(`json_object(${pairs})`);
+	return sql`(SELECT ${obj} FROM ${sql.ref("_emdash_seo")} AS s WHERE s.collection = ${type} AND s.content_id = ${o}.id LIMIT 1) AS ${sql.ref(SEO_FOLDED_COLUMN)}`;
+}
+
+/**
+ * Expand the folded `_emdash_seo` JSON column onto the row using SEO_COLUMN_ALIASES,
+ * so {@link extractSeo} reads it transparently. SQLite returns a JSON string
+ * (parse it); Postgres returns already-parsed JSON. Missing/malformed/null is
+ * a no-op: {@link extractSeo} returns null when the aliases are absent.
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function expandFoldedSeo(row: Record<string, unknown>): void {
+	const raw = row[SEO_FOLDED_COLUMN];
+	delete row[SEO_FOLDED_COLUMN];
+	let parsed: Record<string, unknown> | null = null;
+	if (typeof raw === "string") {
+		try {
+			const candidate: unknown = JSON.parse(raw);
+			if (isPlainObject(candidate)) parsed = candidate;
+		} catch {
+			return; // malformed JSON: leave the row without SEO aliases (extractSeo returns null)
+		}
+	} else if (isPlainObject(raw)) {
+		parsed = raw;
+	}
+	if (!parsed) return;
+	for (const [col, alias] of Object.entries(SEO_COLUMN_ALIASES)) {
+		row[alias] = parsed[col] ?? null;
+	}
+}
+
 /**
  * Stash folded hydration JSON (non-enumerable) for the query.ts fast paths.
  * SQLite returns a JSON string (parse it); Postgres returns already-parsed JSON.
@@ -227,6 +296,18 @@ async function getTaxonomyNames(db: Kysely<Database>): Promise<Set<string>> {
 	}
 }
 
+/**
+ * Reset the module-scoped taxonomy-names cache.
+ *
+ * Called from `invalidateTaxonomyDefsCache()` so that creating or seeding a
+ * taxonomy definition is reflected within the current isolate instead of
+ * waiting for the isolate to recycle. Keeps this cache consistent with the
+ * isolate-wide taxonomy-defs cache in `taxonomies/index.ts`.
+ */
+export function resetTaxonomyNamesCache(): void {
+	taxonomyNames = null;
+}
+
 /**
  * System columns to include in data (mapped to camelCase where needed)
  */
@@ -879,11 +960,12 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 									taxonomyFilters.map(
 										(f) => sql`AND EXISTS (
 							SELECT 1 FROM content_taxonomies ct
-							INNER JOIN taxonomies t ON t.id = ct.taxonomy_id
+							INNER JOIN taxonomies t ON t.translation_group = ct.taxonomy_id
 							WHERE ct.collection = ${type}
 								AND ct.entry_id = ${sql.ref(tableName)}.id
 								AND t.name = ${f.name}
 								AND t.slug IN (${sql.join(f.slugs.map((s) => sql`${s}`))})
+							${locale ? sql`AND t.locale = ${locale}` : sql``}
 						)`,
 									),
 									sql` `,
@@ -1050,31 +1132,25 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 				// When locale is specified, prefer locale-scoped slug match,
 				// but IDs are globally unique so always check id without locale scope.
 				//
-				// LEFT JOIN _emdash_seo folds per-entry SEO (canonical, noindex,
-				// etc.) into this single query at zero extra round-trip cost. The
-				// joined columns are surfaced as a nested data.seo object via
-				// extractSeo() and excluded from the generic field mapping. SEO is
-				// 1:1 with content (PK on collection+content_id), so the join never
-				// multiplies rows.
-				const seoSelect = sql.join(
-					Object.entries(SEO_COLUMN_ALIASES).map(
-						([col, alias]) => sql`${sql.ref(`s.${col}`)} AS ${sql.ref(alias)}`,
-					),
-				);
-				// Fold byline + taxonomy hydration into the content query (see
-				// foldedHydrationSelects), removing the two separate hydration
-				// round trips per fetch.
+				// Byline + taxonomy hydration (foldedHydrationSelects) and per-entry
+				// SEO (foldedSeoSelect) are each surfaced as a single aggregated JSON
+				// column rather than flat columns. This keeps the result-set width
+				// bounded at any collection schema width: a flat `LEFT JOIN _emdash_seo`
+				// adds 5 alias columns to every row and pushes wide flat-schema
+				// collections (common after WordPress / ACF imports) past D1's
+				// per-result-set column limit, surfacing as a silent null entry. One
+				// JSON column is one column, so the join stays safe at any width and
+				// we keep the single round trip.
 				const { terms: termsSelect, bylines: bylinesSelect } = foldedHydrationSelects(
 					db,
 					type,
 					"c",
 				);
+				const seoSelect = foldedSeoSelect(db, type, "c");
 				const result = locale
 					? await sql<Record<string, unknown>>`
 							SELECT c.*, ${seoSelect}, ${termsSelect}, ${bylinesSelect}
 							FROM ${sql.ref(tableName)} AS c
-							LEFT JOIN ${sql.ref("_emdash_seo")} AS s
-								ON s.collection = ${type} AND s.content_id = c.id
 							WHERE c.deleted_at IS NULL
 							AND ((c.slug = ${id} AND c.locale = ${locale}) OR c.id = ${id})
 							LIMIT 1
@@ -1082,8 +1158,6 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 					: await sql<Record<string, unknown>>`
 							SELECT c.*, ${seoSelect}, ${termsSelect}, ${bylinesSelect}
 							FROM ${sql.ref(tableName)} AS c
-							LEFT JOIN ${sql.ref("_emdash_seo")} AS s
-								ON s.collection = ${type} AND s.content_id = c.id
 							WHERE c.deleted_at IS NULL
 							AND (c.slug = ${id} OR c.id = ${id})
 							LIMIT 1
@@ -1094,6 +1168,11 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 					return undefined;
 				}
 
+				// Expand the folded SEO JSON column onto SEO_COLUMN_ALIASES so
+				// extractSeo() reads it transparently. Missing/null SEO is a
+				// no-op: extractSeo() returns null when the aliases are absent.
+				expandFoldedSeo(row);
+
 				const i18nConfig = virtualConfig?.i18n;
 				const i18nEnabled = i18nConfig && i18nConfig.locales.length > 1;
 				const entrySlug = rowStr(row, "slug") || rowStr(row, "id");

package/src/media/enrich.ts

@@ -0,0 +1,78 @@
+/**
+ * Image Metadata Enrichment
+ *
+ * Single seam that derives image dimensions and LQIP placeholders (blurhash,
+ * dominant color) from raw image bytes. Every server-side media-creation path
+ * routes through this so records are populated consistently. Pure-JS and
+ * Workers-safe (image-size reads headers only; generatePlaceholder guards
+ * decode size).
+ */
+
+import { normalizeMime } from "./mime.js";
+import { generatePlaceholder, readDimensions } from "./placeholder.js";
+
+export interface EnrichedImageMetadata {
+	width?: number;
+	height?: number;
+	blurhash?: string;
+	dominantColor?: string;
+}
+
+/**
+ * Derive dimensions + LQIP placeholders from image bytes.
+ *
+ * - Non-image content types return `{}`.
+ * - `knownDimensions` (e.g. browser `naturalWidth/Height`) win over `image-size`
+ *   for the *stored record* because the browser applies EXIF orientation;
+ *   `image-size` reports raw header dimensions, which are swapped for
+ *   90°/270°-rotated JPEGs. They are NOT used for the decode OOM guard — see below.
+ * - The placeholder OOM guard uses only header dimensions read from the bytes
+ *   actually decoded. Caller-supplied `knownDimensions` are untrusted for the
+ *   guard: a client could claim a tiny size for a huge image to bypass the cap.
+ * - `placeholder` lets a caller decode a smaller thumbnail for the blurhash to
+ *   avoid OOM on large originals; dimensions still come from `bytes`.
+ * - Placeholders are jpeg/png only (the generator's supported formats); other
+ *   image types still get dimensions.
+ */
+export async function enrichImageMetadata(
+	bytes: Uint8Array,
+	contentType: string,
+	opts?: {
+		knownDimensions?: { width: number; height: number };
+		placeholder?: { bytes: Uint8Array; contentType: string };
+	},
+): Promise<EnrichedImageMetadata> {
+	const normalizedContentType = normalizeMime(contentType);
+	if (!normalizedContentType.startsWith("image/")) return {};
+
+	// Header dimensions are read once from the actual bytes. They feed the
+	// placeholder OOM guard, which must never trust caller-supplied dimensions:
+	// `knownDimensions` is decoupled from the buffer, so a client could claim a
+	// tiny size for a huge image and slip past the decoded-size cap, making the
+	// decoder allocate an unbounded RGBA buffer and OOM the runtime. Only dims
+	// read from the buffer that actually gets decoded can bound the decode.
+	const headerDims = readDimensions(bytes) ?? undefined;
+
+	// Dimensions published on the record prefer the caller's knownDimensions
+	// (e.g. browser naturalWidth/Height, which apply EXIF orientation) over the
+	// raw header dims, which are swapped for 90°/270°-rotated JPEGs.
+	const recordDims = opts?.knownDimensions ?? headerDims;
+
+	// When a smaller thumbnail override is supplied, decode that for the blurhash
+	// and let generatePlaceholder read the thumbnail's own header for the OOM
+	// guard (the override buffer is what actually gets decoded). On the common
+	// no-override path pass the header dims already read from this same buffer.
+	const override = opts?.placeholder;
+	const placeholder = await generatePlaceholder(
+		override ? override.bytes : bytes,
+		override ? normalizeMime(override.contentType) : normalizedContentType,
+		override ? undefined : headerDims,
+	);
+
+	return {
+		width: recordDims?.width,
+		height: recordDims?.height,
+		blurhash: placeholder?.blurhash,
+		dominantColor: placeholder?.dominantColor,
+	};
+}

package/src/media/index.ts

@@ -27,6 +27,7 @@ export type {
 export { mediaItemToValue } from "./types.js";
 export { normalizeMediaValue } from "./normalize.js";
 export { generatePlaceholder, type PlaceholderData } from "./placeholder.js";
+export { enrichImageMetadata, type EnrichedImageMetadata } from "./enrich.js";
 
 // Built-in providers
 export { localMedia, type LocalMediaConfig } from "./local.js";

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,
+					blurhash: item.blurhash ?? undefined,
+					dominantColor: item.dominantColor ?? undefined,
 					alt: item.alt ?? undefined,
 					previewUrl: `/_emdash/api/media/file/${item.storageKey}`,
 					meta: {
@@ -97,6 +99,8 @@ export const createMediaProvider: CreateMediaProviderFn<LocalMediaRuntimeConfig>
 				size: item.size ?? undefined,
 				width: item.width ?? undefined,
 				height: item.height ?? undefined,
+				blurhash: item.blurhash ?? undefined,
+				dominantColor: item.dominantColor ?? undefined,
 				alt: item.alt ?? undefined,
 				previewUrl: `/_emdash/api/media/file/${item.storageKey}`,
 				meta: {
@@ -148,6 +152,15 @@ export const createMediaProvider: CreateMediaProviderFn<LocalMediaRuntimeConfig>
 			const src = `/_emdash/api/media/file/${storageKey}`;
 			const mimeType = value.mimeType || "";
 
+			// Prefer the first-class fields; fall back to `meta` for legacy snapshots
+			// stored before LQIP was promoted off the provider-specific `meta` bag.
+			const blurhash =
+				value.blurhash ??
+				(typeof value.meta?.blurhash === "string" ? value.meta.blurhash : undefined);
+			const dominantColor =
+				value.dominantColor ??
+				(typeof value.meta?.dominantColor === "string" ? value.meta.dominantColor : undefined);
+
 			// Determine embed type based on MIME type
 			if (mimeType.startsWith("image/")) {
 				return {
@@ -155,6 +168,8 @@ export const createMediaProvider: CreateMediaProviderFn<LocalMediaRuntimeConfig>
 					src,
 					width: value.width,
 					height: value.height,
+					blurhash,
+					dominantColor,
 					alt: value.alt,
 				};
 			}
@@ -185,6 +200,8 @@ export const createMediaProvider: CreateMediaProviderFn<LocalMediaRuntimeConfig>
 				src,
 				width: value.width,
 				height: value.height,
+				blurhash,
+				dominantColor,
 				alt: value.alt,
 			};
 		},
@@ -221,6 +238,8 @@ export function repoItemToProviderItem(item: {
 		size: item.size ?? undefined,
 		width: item.width ?? undefined,
 		height: item.height ?? undefined,
+		blurhash: item.blurhash ?? undefined,
+		dominantColor: item.dominantColor ?? undefined,
 		alt: item.alt ?? undefined,
 		previewUrl: `/_emdash/api/media/file/${item.storageKey}`,
 		meta: {

package/src/media/normalize.ts

@@ -60,7 +60,14 @@ export async function normalizeMediaValue(
 	const needsDimensions = result.width == null || result.height == null;
 	const needsStorageKey = provider === "local" && !result.meta?.storageKey;
 	const needsFileInfo = !result.mimeType || !result.filename;
-	const needsLookup = needsDimensions || needsStorageKey || needsFileInfo;
+	// LQIP placeholders are immutable facts of the bytes: if an image record is
+	// missing them, the provider may have gained them since (e.g. content saved
+	// before LQIP backfill ran, or the row's blurhash was populated later). Pull
+	// them on every image lookup so the LQIP backfill in mergeProviderData runs.
+	const needsLqip =
+		(result.mimeType ?? "").startsWith("image/") &&
+		(result.blurhash == null || result.dominantColor == null);
+	const needsLookup = needsDimensions || needsStorageKey || needsFileInfo || needsLqip;
 
 	if (!needsLookup || !id) return result;
 
@@ -138,6 +145,8 @@ async function resolveInternalUrl(
 		mimeType: item.mimeType,
 		width: item.width,
 		height: item.height,
+		blurhash: item.blurhash,
+		dominantColor: item.dominantColor,
 		alt: item.alt,
 		meta: item.meta,
 	};
@@ -167,6 +176,8 @@ async function resolveLocalId(
 		mimeType: item.mimeType,
 		width: item.width,
 		height: item.height,
+		blurhash: item.blurhash,
+		dominantColor: item.dominantColor,
 		alt: item.alt,
 		meta: item.meta,
 	};
@@ -183,6 +194,12 @@ function mergeProviderData(existing: MediaValue, item: MediaProviderItem): Media
 	if (result.width == null && item.width != null) result.width = item.width;
 	if (result.height == null && item.height != null) result.height = item.height;
 
+	// Fill missing LQIP placeholders (immutable facts of the bytes; caller wins)
+	if (result.blurhash == null && item.blurhash != null) result.blurhash = item.blurhash;
+	if (result.dominantColor == null && item.dominantColor != null) {
+		result.dominantColor = item.dominantColor;
+	}
+
 	// Fill missing file info
 	if (!result.filename && item.filename) result.filename = item.filename;
 	if (!result.mimeType && item.mimeType) result.mimeType = item.mimeType;
@@ -217,6 +234,8 @@ 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;
+	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 (isRecord(obj.meta)) result.meta = obj.meta;
 	return result;