feat: user-selectable featured images for note card headers

Images are hidden from card thumbnails by default. Users explicitly
feature images via a star toggle in the upload panel, and only featured
images appear in the card header strip.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/lib/components/ImageUpload.svelte

@@ -1,5 +1,6 @@
 <script lang="ts">
 	import XIcon from 'lucide-svelte/icons/x';
+	import Star from 'lucide-svelte/icons/star';
 	import RefreshCw from 'lucide-svelte/icons/refresh-cw';
 	import ImageLightbox from './ImageLightbox.svelte';
 	import type { Attachment } from '$lib/types/index.js';
@@ -12,9 +13,10 @@
 		attachments: Attachment[];
 		onUpload: (attachment: Attachment) => void;
 		onRemove: (attachmentId: string) => void;
+		onToggleFeatured?: (attachmentId: string, featured: boolean) => void;
 	}
 
-	let { noteId, attachments = [], onUpload, onRemove }: Props = $props();
+	let { noteId, attachments = [], onUpload, onRemove, onToggleFeatured }: Props = $props();
 
 	let uploading = $state(false);
 	let optimizing = $state(false);
@@ -123,6 +125,15 @@
 						<div class="absolute bottom-0.5 left-0.5 rounded-sm bg-black/50 p-0.5" title="Pending sync">
 							<RefreshCw class="h-3 w-3 text-white" />
 						</div>
+					{:else if onToggleFeatured}
+						<button
+							onclick={() => onToggleFeatured(attachment.id, !attachment.featured)}
+							class="absolute bottom-0.5 right-0.5 rounded-full bg-black/50 p-0.5 {attachment.featured ? 'block' : 'hidden group-hover:block'}"
+							aria-label={attachment.featured ? 'Unfeature image' : 'Feature image'}
+							data-testid="toggle-featured"
+						>
+							<Star class="h-3 w-3 {attachment.featured ? 'fill-[var(--primary)] text-[var(--primary)]' : 'text-white'}" />
+						</button>
 					{/if}
 					<button
 						onclick={() => onRemove(attachment.id)}

src/lib/components/NoteCard.svelte

@@ -48,6 +48,8 @@
 	const doneChecklistItems = $derived(checklistItems.filter(i => i.checked));
 	const sortedChecklistItems = $derived([...activeChecklistItems, ...doneChecklistItems]);
 
+	const featuredAttachments = $derived((note.attachments ?? []).filter(a => a.featured));
+
 	function stop(fn: () => void) {
 		return (e: Event) => {
 			e.stopPropagation();
@@ -81,10 +83,10 @@
 	data-testid="note-card"
 	data-note-id={note.id}
 >
-	<!-- Thumbnail strip -->
-	{#if note.attachments && note.attachments.length > 0}
+	<!-- Thumbnail strip (featured images only) -->
+	{#if featuredAttachments.length > 0}
 		<div class="-mx-4 -mt-4 mb-3 flex overflow-hidden rounded-t-sm" data-testid="card-thumbnails">
-			{#each note.attachments.slice(0, 3) as attachment}
+			{#each featuredAttachments.slice(0, 3) as attachment}
 				<div class="relative min-w-0 flex-1">
 					<!-- svelte-ignore a11y_no_noninteractive_element_interactions a11y_click_events_have_key_events -->
 					<img
@@ -97,9 +99,9 @@
 					/>
 				</div>
 			{/each}
-			{#if note.attachments.length > 3}
+			{#if featuredAttachments.length > 3}
 				<div class="absolute right-1 top-1 rounded-sm bg-black/60 px-1.5 py-0.5 text-xs font-medium text-white" data-testid="card-thumbnail-count">
-					+{note.attachments.length - 3}
+					+{featuredAttachments.length - 3}
 				</div>
 			{/if}
 		</div>

src/lib/components/NoteEditor.svelte

@@ -66,6 +66,24 @@
 		attachmentsList = [...attachmentsList, attachment];
 	}
 
+	async function handleToggleFeatured(attachmentId: string, featured: boolean) {
+		if (!noteId) return;
+		try {
+			const res = await fetch(`/api/notes/${noteId}/attachments?attachmentId=${attachmentId}`, {
+				method: 'PATCH',
+				headers: { 'Content-Type': 'application/json' },
+				body: JSON.stringify({ featured })
+			});
+			if (res.ok) {
+				attachmentsList = attachmentsList.map((a) =>
+					a.id === attachmentId ? { ...a, featured } : a
+				);
+			}
+		} catch (err) {
+			console.error('Failed to toggle featured:', err);
+		}
+	}
+
 	async function handleAttachmentRemove(attachmentId: string) {
 		if (!noteId) return;
 		try {
@@ -200,6 +218,7 @@
 					attachments={attachmentsList}
 					onUpload={handleAttachmentUpload}
 					onRemove={handleAttachmentRemove}
+					onToggleFeatured={handleToggleFeatured}
 				/>
 			</div>
 		{:else if noteId && attachmentsList.length > 0}

src/lib/server/attachments.ts

@@ -86,6 +86,15 @@ export async function getAttachmentsByNote(noteId: string) {
 	return db.select().from(attachments).where(eq(attachments.noteId, noteId));
 }
 
+export async function updateAttachment(id: string, data: { featured: boolean }) {
+	const [updated] = await db
+		.update(attachments)
+		.set({ featured: data.featured })
+		.where(eq(attachments.id, id))
+		.returning();
+	return updated ?? null;
+}
+
 export async function deleteAttachment(id: string) {
 	const attachment = await getAttachment(id);
 	if (attachment) {

src/lib/server/db/index.ts

@@ -85,5 +85,12 @@ sqlite.exec(`
 	CREATE INDEX IF NOT EXISTS sync_log_timestamp_idx ON sync_log(timestamp);
 `);
 
+// Idempotent migration: add featured column to attachments
+try {
+	sqlite.exec(`ALTER TABLE attachments ADD COLUMN featured INTEGER NOT NULL DEFAULT 0;`);
+} catch {
+	// Column already exists
+}
+
 export const db = drizzle(sqlite, { schema });
 export { sqlite };

src/lib/server/db/schema.ts

@@ -72,6 +72,7 @@ export const attachments = sqliteTable('attachments', {
 	size: integer('size').notNull(),
 	path: text('path').notNull(),
 	thumbnailPath: text('thumbnail_path'),
+	featured: integer('featured', { mode: 'boolean' }).default(false).notNull(),
 	createdAt: integer('created_at', { mode: 'timestamp' }).notNull()
 });
 

src/lib/types/index.ts

@@ -43,6 +43,7 @@ export interface Attachment {
 	size: number;
 	path: string;
 	thumbnailPath?: string | null;
+	featured: boolean;
 	createdAt: Date;
 }
 

src/routes/api/notes/[id]/attachments/+server.ts

@@ -1,6 +1,6 @@
 import { json, error } from '@sveltejs/kit';
 import type { RequestHandler } from './$types.js';
-import { saveAttachment, getAttachmentsByNote, getAttachment, deleteAttachment } from '$lib/server/attachments.js';
+import { saveAttachment, getAttachmentsByNote, getAttachment, deleteAttachment, updateAttachment } from '$lib/server/attachments.js';
 import { readFile } from 'fs/promises';
 
 export const GET: RequestHandler = async ({ params, url }) => {
@@ -50,6 +50,19 @@ export const POST: RequestHandler = async ({ params, request }) => {
 	return json(attachment, { status: 201 });
 };
 
+export const PATCH: RequestHandler = async ({ url, request }) => {
+	const attachmentId = url.searchParams.get('attachmentId');
+	if (!attachmentId) throw error(400, 'attachmentId required');
+
+	const body = await request.json();
+	if (typeof body.featured !== 'boolean') throw error(400, 'featured (boolean) required');
+
+	const updated = await updateAttachment(attachmentId, { featured: body.featured });
+	if (!updated) throw error(404, 'Attachment not found');
+
+	return json(updated);
+};
+
 export const DELETE: RequestHandler = async ({ url }) => {
 	const attachmentId = url.searchParams.get('attachmentId');
 	if (!attachmentId) throw error(400, 'attachmentId required');

tests/e2e/attachments.spec.ts

@@ -49,21 +49,69 @@ test.describe('Image Attachments', () => {
 		await expect(page.getByTestId('note-editor').locator('img')).toBeVisible();
 	});
 
-	test('Scenario: Image thumbnail appears on the note card', async ({ authenticatedPage: page }) => {
+	test('Scenario: Uploaded images are hidden from card header by default', async ({ authenticatedPage: page }) => {
 		// Given a note with an uploaded image exists
-		await createAndReopenNote(page, 'Card Thumb Test');
+		await createAndReopenNote(page, 'Hidden Default Test');
 		await page.getByTestId('image-toggle').click();
 		await page.getByTestId('file-input').setInputFiles(TEST_IMAGE_PATH);
 		await expect(page.getByTestId('attachment-thumbnail')).toBeVisible();
 
-		// When the user closes the editor
+		// When the user closes the editor without featuring the image
 		await page.getByTestId('close-editor-btn').click();
 
-		// Then a thumbnail strip appears on the note card
-		const card = noteCard(page, 'Card Thumb Test');
+		// Then the card does NOT show a thumbnail strip
+		const card = noteCard(page, 'Hidden Default Test');
+		await expect(card).toBeVisible();
+		await expect(card.getByTestId('card-thumbnails')).not.toBeVisible();
+	});
+
+	test('Scenario: Featuring an image makes it appear on the card header', async ({ authenticatedPage: page }) => {
+		// Given a note with an uploaded image exists
+		await createAndReopenNote(page, 'Feature Test');
+		await page.getByTestId('image-toggle').click();
+		await page.getByTestId('file-input').setInputFiles(TEST_IMAGE_PATH);
+		await expect(page.getByTestId('attachment-thumbnail')).toBeVisible();
+
+		// When the user features the image by clicking the star
+		await page.getByTestId('attachment-thumbnail').hover();
+		await page.getByTestId('toggle-featured').click();
+
+		// And closes the editor
+		await page.getByTestId('close-editor-btn').click();
+
+		// Then the card shows the featured image in its header
+		const card = noteCard(page, 'Feature Test');
+		await expect(card.getByTestId('card-thumbnails')).toBeVisible();
 		await expect(card.getByTestId('card-thumbnail')).toBeVisible();
 	});
 
+	test('Scenario: Unfeaturing an image removes it from the card header', async ({ authenticatedPage: page }) => {
+		// Given a note with a featured image exists
+		await createAndReopenNote(page, 'Unfeature Test');
+		await page.getByTestId('image-toggle').click();
+		await page.getByTestId('file-input').setInputFiles(TEST_IMAGE_PATH);
+		await expect(page.getByTestId('attachment-thumbnail')).toBeVisible();
+
+		// Feature the image
+		await page.getByTestId('attachment-thumbnail').hover();
+		await page.getByTestId('toggle-featured').click();
+		await page.getByTestId('close-editor-btn').click();
+
+		const card = noteCard(page, 'Unfeature Test');
+		await expect(card.getByTestId('card-thumbnails')).toBeVisible();
+
+		// When the user unfeatures the image
+		await card.getByText('Unfeature Test').click();
+		await expect(page.getByTestId('note-editor')).toBeVisible();
+		await page.getByTestId('image-toggle').click();
+		await page.getByTestId('attachment-thumbnail').hover();
+		await page.getByTestId('toggle-featured').click();
+		await page.getByTestId('close-editor-btn').click();
+
+		// Then the card no longer shows the thumbnail strip
+		await expect(card.getByTestId('card-thumbnails')).not.toBeVisible();
+	});
+
 	test('Scenario: Removed image disappears from editor and card', async ({ authenticatedPage: page }) => {
 		// Given a note with an uploaded image exists
 		await createAndReopenNote(page, 'Remove Test');