fix(core): hydrate byline avatar LQIP placeholder fields (emdash-cms#1457) (emdash-cms#1553)

Content byline credits fold in the avatar's storage key and alt via the
media join, but dropped the blurhash/dominant_color LQIP columns, so
author avatars couldn't render a low-quality placeholder despite the
media row storing one.

Carry m.blurhash/m.dominant_color through the same media join in
getContentBylines, getContentBylinesMany, and findByUserIds, surface
them as BylineSummary.avatarBlurhash/avatarDominantColor (and in the
byline API response schema), and default to null on finders that don't
join media. Purely additive, mirroring the existing avatarStorageKey
pattern.

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: marcusbellamyshaw-cell

.changeset/fix-byline-avatar-lqip.md

@@ -0,0 +1,5 @@
+---
+"emdash": patch
+---
+
+Byline avatar hydration now includes the media LQIP placeholder fields (#1457). Content byline credits already folded in the avatar's `avatarStorageKey` and `avatarAlt` via the media join, but dropped the `blurhash`/`dominant_color` placeholder columns, so author avatars couldn't render a low-quality image placeholder while loading even though the media stored one. `BylineSummary` now also carries `avatarBlurhash` and `avatarDominantColor`, populated by `getContentBylines`, `getContentBylinesMany`, and `findByUserIds` (and surfaced in the byline API response), so themes can paint a blurhash/dominant-colour placeholder for byline avatars exactly as they can for other media.

packages/core/src/api/schemas/bylines.ts

@@ -19,6 +19,14 @@ export const bylineSummarySchema = z
 		 */
 		avatarStorageKey: z.string().nullish(),
 		avatarAlt: z.string().nullish(),
+		/**
+		 * Avatar media LQIP placeholder (blurhash + dominant colour, migration
+		 * 024), from the same media join. Lets clients render a placeholder
+		 * while the avatar loads. Null under the same conditions as
+		 * `avatarStorageKey`.
+		 */
+		avatarBlurhash: z.string().nullish(),
+		avatarDominantColor: z.string().nullish(),
 		websiteUrl: z.string().nullable(),
 		userId: z.string().nullable(),
 		isGuest: z.boolean(),

packages/core/src/database/repositories/byline.ts

@@ -37,6 +37,8 @@ type BylineRow = Selectable<BylineTable>;
 type BylineRowWithAvatar = BylineRow & {
 	avatar_storage_key?: string | null;
 	avatar_alt?: string | null;
+	avatar_blurhash?: string | null;
+	avatar_dominant_color?: string | null;
 };
 
 export interface CreateBylineInput {
@@ -113,6 +115,8 @@ function rowToByline(row: BylineRowWithAvatar): BylineSummary {
 		avatarMediaId: row.avatar_media_id,
 		avatarStorageKey: row.avatar_storage_key ?? null,
 		avatarAlt: row.avatar_alt ?? null,
+		avatarBlurhash: row.avatar_blurhash ?? null,
+		avatarDominantColor: row.avatar_dominant_color ?? null,
 		websiteUrl: row.website_url,
 		userId: row.user_id,
 		isGuest: row.is_guest === 1,
@@ -944,6 +948,8 @@ export class BylineRepository {
 				"b.avatar_media_id as avatar_media_id",
 				"m.storage_key as avatar_storage_key",
 				"m.alt as avatar_alt",
+				"m.blurhash as avatar_blurhash",
+				"m.dominant_color as avatar_dominant_color",
 				"b.website_url as website_url",
 				"b.user_id as user_id",
 				"b.is_guest as is_guest",
@@ -971,6 +977,8 @@ export class BylineRepository {
 			avatar_media_id: row.avatar_media_id,
 			avatar_storage_key: row.avatar_storage_key,
 			avatar_alt: row.avatar_alt,
+			avatar_blurhash: row.avatar_blurhash,
+			avatar_dominant_color: row.avatar_dominant_color,
 			website_url: row.website_url,
 			user_id: row.user_id,
 			is_guest: row.is_guest,
@@ -1080,6 +1088,8 @@ export class BylineRepository {
 					"b.avatar_media_id as avatar_media_id",
 					"m.storage_key as avatar_storage_key",
 					"m.alt as avatar_alt",
+					"m.blurhash as avatar_blurhash",
+					"m.dominant_color as avatar_dominant_color",
 					"b.website_url as website_url",
 					"b.user_id as user_id",
 					"b.is_guest as is_guest",
@@ -1104,6 +1114,8 @@ export class BylineRepository {
 				avatar_media_id: row.avatar_media_id,
 				avatar_storage_key: row.avatar_storage_key,
 				avatar_alt: row.avatar_alt,
+				avatar_blurhash: row.avatar_blurhash,
+				avatar_dominant_color: row.avatar_dominant_color,
 				website_url: row.website_url,
 				user_id: row.user_id,
 				is_guest: row.is_guest,
@@ -1182,6 +1194,8 @@ export class BylineRepository {
 					"b.avatar_media_id as avatar_media_id",
 					"m.storage_key as avatar_storage_key",
 					"m.alt as avatar_alt",
+					"m.blurhash as avatar_blurhash",
+					"m.dominant_color as avatar_dominant_color",
 					"b.website_url as website_url",
 					"b.user_id as user_id",
 					"b.is_guest as is_guest",

packages/core/src/database/repositories/types.ts

@@ -78,6 +78,19 @@ export interface BylineSummary {
 	avatarStorageKey?: string | null;
 	/** Avatar media alt text, from the same media join. Null when not joined. */
 	avatarAlt?: string | null;
+	/**
+	 * Avatar media blurhash (LQIP placeholder, migration 024), folded in by the
+	 * same media join as `avatarStorageKey`. Lets a renderer paint a blurred
+	 * placeholder while the full avatar loads, with no extra media lookup.
+	 * Null when the byline has no avatar, the media row has no blurhash, or the
+	 * byline was loaded through a finder that doesn't join media.
+	 */
+	avatarBlurhash?: string | null;
+	/**
+	 * Avatar media dominant colour (LQIP placeholder, migration 024), from the
+	 * same media join. Null under the same conditions as `avatarBlurhash`.
+	 */
+	avatarDominantColor?: string | null;
 	websiteUrl: string | null;
 	userId: string | null;
 	isGuest: boolean;

packages/core/tests/unit/database/repositories/byline.test.ts

@@ -149,7 +149,8 @@ describe("BylineRepository", () => {
 	});
 
 	it("hydrates avatar storage key and alt via the media join", async () => {
-		// A media row standing in for an uploaded avatar.
+		// A media row standing in for an uploaded avatar, including the LQIP
+		// placeholder columns (migration 024) so the hydration carries them.
 		await db
 			.insertInto("media")
 			.values({
@@ -159,6 +160,8 @@ describe("BylineRepository", () => {
 				storage_key: "media-avatar-1.png",
 				status: "ready",
 				alt: "Jane Doe headshot",
+				blurhash: "LEHV6nWB2yk8pyo0adR*.7kCMdnj",
+				dominant_color: "#aabbcc",
 			})
 			.execute();
 
@@ -189,16 +192,25 @@ describe("BylineRepository", () => {
 		expect(avatared.byline.avatarMediaId).toBe("media-avatar-1");
 		expect(avatared.byline.avatarStorageKey).toBe("media-avatar-1.png");
 		expect(avatared.byline.avatarAlt).toBe("Jane Doe headshot");
-		// No avatar -> storage key and alt are null, not undefined.
+		// The LQIP placeholder columns ride along the same media join so a
+		// renderer can paint a blurhash/dominant-colour placeholder while the
+		// full avatar loads.
+		expect(avatared.byline.avatarBlurhash).toBe("LEHV6nWB2yk8pyo0adR*.7kCMdnj");
+		expect(avatared.byline.avatarDominantColor).toBe("#aabbcc");
+		// No avatar -> storage key, alt, and LQIP columns are null, not undefined.
 		expect(plain.byline.avatarStorageKey).toBeNull();
 		expect(plain.byline.avatarAlt).toBeNull();
+		expect(plain.byline.avatarBlurhash).toBeNull();
+		expect(plain.byline.avatarDominantColor).toBeNull();
 
 		// Batch hydration path (the list-page case) resolves the same data
 		// without a per-byline media lookup.
 		const batch = await bylineRepo.getContentBylinesMany("post", [content.id]);
 		const batchCredit = batch.get(content.id)!.find((c) => c.byline.id === withAvatar.id)!;
 		expect(batchCredit.byline.avatarStorageKey).toBe("media-avatar-1.png");
 		expect(batchCredit.byline.avatarAlt).toBe("Jane Doe headshot");
+		expect(batchCredit.byline.avatarBlurhash).toBe("LEHV6nWB2yk8pyo0adR*.7kCMdnj");
+		expect(batchCredit.byline.avatarDominantColor).toBe("#aabbcc");
 	});
 
 	it("hydrates avatar storage key for author-inferred bylines via findByUserIds", async () => {
@@ -211,6 +223,8 @@ describe("BylineRepository", () => {
 				storage_key: "media-avatar-3.png",
 				status: "ready",
 				alt: "User avatar",
+				blurhash: "L6PZfSi_.AyE_3t7t7R**0o#DgR4",
+				dominant_color: "#112233",
 			})
 			.execute();
 		await db
@@ -237,6 +251,8 @@ describe("BylineRepository", () => {
 		const resolved = map.get("user-123");
 		expect(resolved?.avatarStorageKey).toBe("media-avatar-3.png");
 		expect(resolved?.avatarAlt).toBe("User avatar");
+		expect(resolved?.avatarBlurhash).toBe("L6PZfSi_.AyE_3t7t7R**0o#DgR4");
+		expect(resolved?.avatarDominantColor).toBe("#112233");
 	});
 
 	it("leaves avatar storage key null on the plain byline finders", async () => {