feat: unified search with Cmd/Ctrl+K shortcut (#447)

* feat: unified search with Cmd/Ctrl+K shortcut

- add pg_trgm extension and GIN indexes for fuzzy search
- implement /search endpoint with trigram similarity scoring
- search across tracks, artists, albums, and tags
- create SearchModal component with keyboard navigation
- Cmd+K (Mac) / Ctrl+K (Windows/Linux) opens search
- arrow keys navigate, Enter selects, Esc closes
- results grouped by type with relevance scoring

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* refactor: improve search modal UX and styling

- use "Cmd+K" text instead of ⌘ symbol for clarity
- add client-side query length validation (max 100 chars)
- show clear error message when query exceeds limit
- apply glassmorphism styling to modal:
- frosted glass background with blur
- subtle border highlights
- refined hover/selected states
- consistent translucent elements

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

* feat: show artwork/avatars in search results

- display track artwork, artist avatars, album covers when available
- lazy loading with graceful fallback to icon on error
- image hidden on load failure, icon shown instead

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[e-mail]>

---------

Co-authored-by: Claude <[e-mail]>

backend/alembic/versions/2025_12_03_000235_0d634c0a7259_add_pg_trgm_extension_and_search_indexes.py

···
+"""add pg_trgm extension and search indexes
+
+Revision ID: 0d634c0a7259
+Revises: f60f46fb6014
+Create Date: 2025-12-03 00:02:35.608832
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "0d634c0a7259"
+down_revision: str | Sequence[str] | None = "f60f46fb6014"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    """enable pg_trgm and create search indexes."""
+    # enable pg_trgm extension for fuzzy/similarity search
+    op.execute("CREATE EXTENSION IF NOT EXISTS pg_trgm")
+
+    # trigram indexes for fuzzy matching
+    # note: not using CONCURRENTLY since tables are small (<100 rows)
+    # tracks: search by title
+    op.execute(
+        "CREATE INDEX IF NOT EXISTS ix_tracks_title_trgm "
+        "ON tracks USING GIN (title gin_trgm_ops)"
+    )
+
+    # artists: search by handle and display_name
+    op.execute(
+        "CREATE INDEX IF NOT EXISTS ix_artists_handle_trgm "
+        "ON artists USING GIN (handle gin_trgm_ops)"
+    )
+    op.execute(
+        "CREATE INDEX IF NOT EXISTS ix_artists_display_name_trgm "
+        "ON artists USING GIN (display_name gin_trgm_ops)"
+    )
+
+    # albums: search by title
+    op.execute(
+        "CREATE INDEX IF NOT EXISTS ix_albums_title_trgm "
+        "ON albums USING GIN (title gin_trgm_ops)"
+    )
+
+    # tags: search by name
+    op.execute(
+        "CREATE INDEX IF NOT EXISTS ix_tags_name_trgm "
+        "ON tags USING GIN (name gin_trgm_ops)"
+    )
+
+
+def downgrade() -> None:
+    """remove search indexes (keep extension)."""
+    op.execute("DROP INDEX IF EXISTS ix_tags_name_trgm")
+    op.execute("DROP INDEX IF EXISTS ix_albums_title_trgm")
+    op.execute("DROP INDEX IF EXISTS ix_artists_display_name_trgm")
+    op.execute("DROP INDEX IF EXISTS ix_artists_handle_trgm")
+    op.execute("DROP INDEX IF EXISTS ix_tracks_title_trgm")
+    # note: not dropping pg_trgm extension as other things may depend on it

backend/src/backend/api/search.py

···
 """search endpoints for relay."""
 
-from fastapi import APIRouter, Query
+from typing import Annotated, Literal
+
+from fastapi import APIRouter, Depends, Query
+from pydantic import BaseModel
+from sqlalchemy import func, select
+from sqlalchemy.ext.asyncio import AsyncSession
 
 from backend._internal.atproto.handles import search_handles
+from backend.models import Album, Artist, Tag, Track, TrackTag, get_db
 
 router = APIRouter(prefix="/search", tags=["search"])
 
 
+# response models
+class TrackSearchResult(BaseModel):
+    """track search result."""
+
+    type: Literal["track"] = "track"
+    id: int
+    title: str
+    artist_handle: str
+    artist_display_name: str
+    image_url: str | None
+    relevance: float
+
+
+class ArtistSearchResult(BaseModel):
+    """artist search result."""
+
+    type: Literal["artist"] = "artist"
+    did: str
+    handle: str
+    display_name: str
+    avatar_url: str | None
+    relevance: float
+
+
+class AlbumSearchResult(BaseModel):
+    """album search result."""
+
+    type: Literal["album"] = "album"
+    id: str
+    title: str
+    slug: str
+    artist_handle: str
+    artist_display_name: str
+    image_url: str | None
+    relevance: float
+
+
+class TagSearchResult(BaseModel):
+    """tag search result."""
+
+    type: Literal["tag"] = "tag"
+    id: int
+    name: str
+    track_count: int
+    relevance: float
+
+
+SearchResult = (
+    TrackSearchResult | ArtistSearchResult | AlbumSearchResult | TagSearchResult
+)
+
+
+class SearchResponse(BaseModel):
+    """unified search response."""
+
+    results: list[SearchResult]
+    counts: dict[str, int]
+
+
 @router.get("/handles")
 async def search_atproto_handles(
     q: str = Query(..., min_length=2, description="search query (handle prefix)"),
···
     """
     results = await search_handles(q, limit=limit)
     return {"results": results}
+
+
[e-mail]("/")
+async def unified_search(
+    db: Annotated[AsyncSession, Depends(get_db)],
+    q: str = Query(..., min_length=2, max_length=100, description="search query"),
+    type: str | None = Query(
+        None,
+        description="filter by type: tracks, artists, albums, tags (comma-separated for multiple)",
+    ),
+    limit: int = Query(20, ge=1, le=50, description="max results per type"),
+) -> SearchResponse:
+    """unified search across tracks, artists, albums, and tags.
+
+    uses pg_trgm for fuzzy matching with similarity scoring.
+    results are sorted by relevance within each type.
+    """
+    # parse types filter
+    if type:
+        types = {t.strip().lower() for t in type.split(",")}
+    else:
+        types = {"tracks", "artists", "albums", "tags"}
+
+    results: list[SearchResult] = []
+    counts: dict[str, int] = {"tracks": 0, "artists": 0, "albums": 0, "tags": 0}
+
+    # search tracks
+    if "tracks" in types:
+        track_results = await _search_tracks(db, q, limit)
+        results.extend(track_results)
+        counts["tracks"] = len(track_results)
+
+    # search artists
+    if "artists" in types:
+        artist_results = await _search_artists(db, q, limit)
+        results.extend(artist_results)
+        counts["artists"] = len(artist_results)
+
+    # search albums
+    if "albums" in types:
+        album_results = await _search_albums(db, q, limit)
+        results.extend(album_results)
+        counts["albums"] = len(album_results)
+
+    # search tags
+    if "tags" in types:
+        tag_results = await _search_tags(db, q, limit)
+        results.extend(tag_results)
+        counts["tags"] = len(tag_results)
+
+    # sort all results by relevance (highest first)
+    results.sort(key=lambda x: x.relevance, reverse=True)
+
+    return SearchResponse(results=results, counts=counts)
+
+
+async def _search_tracks(
+    db: AsyncSession, query: str, limit: int
+) -> list[TrackSearchResult]:
+    """search tracks by title using trigram similarity."""
+    # use pg_trgm similarity function for fuzzy matching
+    similarity = func.similarity(Track.title, query)
+
+    stmt = (
+        select(Track, Artist, similarity.label("relevance"))
+        .join(Artist, Track.artist_did == Artist.did)
+        .where(similarity > 0.1)  # minimum similarity threshold
+        .order_by(similarity.desc())
+        .limit(limit)
+    )
+
+    result = await db.execute(stmt)
+    rows = result.all()
+
+    return [
+        TrackSearchResult(
+            id=track.id,
+            title=track.title,
+            artist_handle=artist.handle,
+            artist_display_name=artist.display_name,
+            image_url=track.image_url,
+            relevance=round(relevance, 3),
+        )
+        for track, artist, relevance in rows
+    ]
+
+
+async def _search_artists(
+    db: AsyncSession, query: str, limit: int
+) -> list[ArtistSearchResult]:
+    """search artists by handle and display_name using trigram similarity."""
+    # combine similarity scores from handle and display_name (take max)
+    handle_sim = func.similarity(Artist.handle, query)
+    name_sim = func.similarity(Artist.display_name, query)
+    combined_sim = func.greatest(handle_sim, name_sim)
+
+    stmt = (
+        select(Artist, combined_sim.label("relevance"))
+        .where(combined_sim > 0.1)
+        .order_by(combined_sim.desc())
+        .limit(limit)
+    )
+
+    result = await db.execute(stmt)
+    rows = result.all()
+
+    return [
+        ArtistSearchResult(
+            did=artist.did,
+            handle=artist.handle,
+            display_name=artist.display_name,
+            avatar_url=artist.avatar_url,
+            relevance=round(relevance, 3),
+        )
+        for artist, relevance in rows
+    ]
+
+
+async def _search_albums(
+    db: AsyncSession, query: str, limit: int
+) -> list[AlbumSearchResult]:
+    """search albums by title using trigram similarity."""
+    similarity = func.similarity(Album.title, query)
+
+    stmt = (
+        select(Album, Artist, similarity.label("relevance"))
+        .join(Artist, Album.artist_did == Artist.did)
+        .where(similarity > 0.1)
+        .order_by(similarity.desc())
+        .limit(limit)
+    )
+
+    result = await db.execute(stmt)
+    rows = result.all()
+
+    return [
+        AlbumSearchResult(
+            id=album.id,
+            title=album.title,
+            slug=album.slug,
+            artist_handle=artist.handle,
+            artist_display_name=artist.display_name,
+            image_url=album.image_url,
+            relevance=round(relevance, 3),
+        )
+        for album, artist, relevance in rows
+    ]
+
+
+async def _search_tags(
+    db: AsyncSession, query: str, limit: int
+) -> list[TagSearchResult]:
+    """search tags by name using trigram similarity."""
+    similarity = func.similarity(Tag.name, query)
+
+    # count tracks per tag
+    track_count_subq = (
+        select(TrackTag.tag_id, func.count(TrackTag.track_id).label("track_count"))
+        .group_by(TrackTag.tag_id)
+        .subquery()
+    )
+
+    stmt = (
+        select(
+            Tag,
+            func.coalesce(track_count_subq.c.track_count, 0).label("track_count"),
+            similarity.label("relevance"),
+        )
+        .outerjoin(track_count_subq, Tag.id == track_count_subq.c.tag_id)
+        .where(similarity > 0.1)
+        .order_by(similarity.desc())
+        .limit(limit)
+    )
+
+    result = await db.execute(stmt)
+    rows = result.all()
+
+    return [
+        TagSearchResult(
+            id=tag.id,
+            name=tag.name,
+            track_count=track_count,
+            relevance=round(relevance, 3),
+        )
+        for tag, track_count, relevance in rows
+    ]

frontend/src/lib/components/SearchModal.svelte

···
+<script lang="ts">
+	import { goto } from '$app/navigation';
+	import { browser } from '$app/environment';
+	import { search, type SearchResult } from '$lib/search.svelte';
+	import { fade } from 'svelte/transition';
+	import { onMount, onDestroy } from 'svelte';
+
+	let inputRef: HTMLInputElement | null = $state(null);
+
+	// focus input when modal opens
+	$effect(() => {
+		if (search.isOpen && inputRef && browser) {
+			// small delay to ensure modal is rendered
+			window.requestAnimationFrame(() => {
+				inputRef?.focus();
+			});
+		}
+	});
+
+	function handleKeydown(event: KeyboardEvent) {
+		if (!search.isOpen) return;
+
+		switch (event.key) {
+			case 'Escape':
+				event.preventDefault();
+				search.close();
+				break;
+			case 'ArrowDown':
+				event.preventDefault();
+				search.selectNext();
+				break;
+			case 'ArrowUp':
+				event.preventDefault();
+				search.selectPrevious();
+				break;
+			case 'Enter': {
+				event.preventDefault();
+				const selected = search.getSelectedResult();
+				if (selected) {
+					navigateToResult(selected);
+				}
+				break;
+			}
+		}
+	}
+
+	function navigateToResult(result: SearchResult) {
+		const href = search.getResultHref(result);
+		search.close();
+		goto(href);
+	}
+
+	function handleBackdropClick(event: MouseEvent) {
+		if (event.target === event.currentTarget) {
+			search.close();
+		}
+	}
+
+	function getResultIcon(type: SearchResult['type']): string {
+		switch (type) {
+			case 'track':
+				return '♪';
+			case 'artist':
+				return '◉';
+			case 'album':
+				return '◫';
+			case 'tag':
+				return '#';
+		}
+	}
+
+	function getResultImage(result: SearchResult): string | null {
+		switch (result.type) {
+			case 'track':
+				return result.image_url;
+			case 'artist':
+				return result.avatar_url;
+			case 'album':
+				return result.image_url;
+			case 'tag':
+				return null;
+		}
+	}
+
+	function getResultTitle(result: SearchResult): string {
+		switch (result.type) {
+			case 'track':
+				return result.title;
+			case 'artist':
+				return result.display_name;
+			case 'album':
+				return result.title;
+			case 'tag':
+				return result.name;
+		}
+	}
+
+	function getResultSubtitle(result: SearchResult): string {
+		switch (result.type) {
+			case 'track':
+				return `by ${result.artist_display_name}`;
+			case 'artist':
+				return `@${result.handle}`;
+			case 'album':
+				return `by ${result.artist_display_name}`;
+			case 'tag':
+				return `${result.track_count} track${result.track_count === 1 ? '' : 's'}`;
+		}
+	}
+
+	function getShortcutHint(): string {
+		// detect platform - use text instead of symbols for clarity
+		if (browser && navigator.platform.toLowerCase().includes('mac')) {
+			return 'Cmd+K';
+		}
+		return 'Ctrl+K';
+	}
+
+	onMount(() => {
+		window.addEventListener('keydown', handleKeydown);
+	});
+
+	onDestroy(() => {
+		if (browser) {
+			window.removeEventListener('keydown', handleKeydown);
+		}
+	});
+</script>
+
+{#if search.isOpen}
+	<!-- svelte-ignore a11y_click_events_have_key_events a11y_no_static_element_interactions -->
+	<div
+		class="search-backdrop"
+		onclick={handleBackdropClick}
+		transition:fade={{ duration: 150 }}
+	>
+		<div class="search-modal" role="dialog" aria-modal="true" aria-label="search">
+			<div class="search-input-wrapper">
+				<svg class="search-icon" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+					<circle cx="11" cy="11" r="8"></circle>
+					<line x1="21" y1="21" x2="16.65" y2="16.65"></line>
+				</svg>
+				<input
+					bind:this={inputRef}
+					type="text"
+					class="search-input"
+					placeholder="search tracks, artists, albums, tags..."
+					value={search.query}
+					oninput={(e) => search.setQuery(e.currentTarget.value)}
+					autocomplete="off"
+					autocorrect="off"
+					autocapitalize="off"
+					spellcheck="false"
+				/>
+				{#if search.loading}
+					<div class="search-spinner"></div>
+				{:else}
+					<kbd class="search-shortcut">{getShortcutHint()}</kbd>
+				{/if}
+			</div>
+
+			{#if search.results.length > 0}
+				<div class="search-results">
+					{#each search.results as result, index (result.type + '-' + (result.type === 'track' ? result.id : result.type === 'artist' ? result.did : result.type === 'album' ? result.id : result.id))}
+						{@const imageUrl = getResultImage(result)}
+						<button
+							class="search-result"
+							class:selected={index === search.selectedIndex}
+							onclick={() => navigateToResult(result)}
+							onmouseenter={() => (search.selectedIndex = index)}
+						>
+							<span class="result-icon" data-type={result.type}>
+								{#if imageUrl}
+									<img
+										src={imageUrl}
+										alt=""
+										class="result-image"
+										loading="lazy"
+										onerror={(e) => ((e.currentTarget as HTMLImageElement).style.display = 'none')}
+									/>
+									<span class="result-icon-fallback">{getResultIcon(result.type)}</span>
+								{:else}
+									{getResultIcon(result.type)}
+								{/if}
+							</span>
+							<div class="result-content">
+								<span class="result-title">{getResultTitle(result)}</span>
+								<span class="result-subtitle">{getResultSubtitle(result)}</span>
+							</div>
+							<span class="result-type">{result.type}</span>
+						</button>
+					{/each}
+				</div>
+			{:else if search.query.length >= 2 && !search.loading}
+				<div class="search-empty">
+					no results for "{search.query}"
+				</div>
+			{:else if search.query.length === 0}
+				<div class="search-hints">
+					<p>start typing to search across all content</p>
+					<div class="hint-shortcuts">
+						<span><kbd>↑</kbd><kbd>↓</kbd> navigate</span>
+						<span><kbd>↵</kbd> select</span>
+						<span><kbd>esc</kbd> close</span>
+					</div>
+				</div>
+			{/if}
+
+			{#if search.error}
+				<div class="search-error">{search.error}</div>
+			{/if}
+		</div>
+	</div>
+{/if}
+
+<style>
+	.search-backdrop {
+		position: fixed;
+		inset: 0;
+		background: rgba(0, 0, 0, 0.6);
+		backdrop-filter: blur(4px);
+		-webkit-backdrop-filter: blur(4px);
+		z-index: 9999;
+		display: flex;
+		align-items: flex-start;
+		justify-content: center;
+		padding-top: 15vh;
+	}
+
+	.search-modal {
+		width: 100%;
+		max-width: 560px;
+		background: rgba(18, 18, 20, 0.85);
+		backdrop-filter: blur(20px) saturate(180%);
+		-webkit-backdrop-filter: blur(20px) saturate(180%);
+		border: 1px solid rgba(255, 255, 255, 0.08);
+		border-radius: 16px;
+		box-shadow:
+			0 24px 80px rgba(0, 0, 0, 0.5),
+			0 0 1px rgba(255, 255, 255, 0.1) inset;
+		overflow: hidden;
+		margin: 0 1rem;
+	}
+
+	.search-input-wrapper {
+		display: flex;
+		align-items: center;
+		gap: 0.75rem;
+		padding: 1rem 1.25rem;
+		border-bottom: 1px solid rgba(255, 255, 255, 0.06);
+		background: rgba(255, 255, 255, 0.02);
+	}
+
+	.search-icon {
+		color: var(--text-tertiary);
+		flex-shrink: 0;
+	}
+
+	.search-input {
+		flex: 1;
+		background: transparent;
+		border: none;
+		outline: none;
+		font-size: 1rem;
+		font-family: inherit;
+		color: var(--text-primary);
+	}
+
+	.search-input::placeholder {
+		color: var(--text-muted);
+	}
+
+	.search-shortcut {
+		font-size: 0.7rem;
+		padding: 0.25rem 0.5rem;
+		background: rgba(255, 255, 255, 0.06);
+		border: 1px solid rgba(255, 255, 255, 0.08);
+		border-radius: 5px;
+		color: var(--text-muted);
+		font-family: inherit;
+	}
+
+	.search-spinner {
+		width: 16px;
+		height: 16px;
+		border: 2px solid var(--border-default);
+		border-top-color: var(--accent);
+		border-radius: 50%;
+		animation: spin 0.6s linear infinite;
+	}
+
+	@keyframes spin {
+		to {
+			transform: rotate(360deg);
+		}
+	}
+
+	.search-results {
+		max-height: 400px;
+		overflow-y: auto;
+		padding: 0.5rem;
+	}
+
+	.search-result {
+		display: flex;
+		align-items: center;
+		gap: 0.75rem;
+		width: 100%;
+		padding: 0.75rem;
+		background: transparent;
+		border: none;
+		border-radius: 8px;
+		cursor: pointer;
+		text-align: left;
+		font-family: inherit;
+		color: var(--text-primary);
+		transition: background 0.1s;
+	}
+
+	.search-result:hover,
+	.search-result.selected {
+		background: rgba(255, 255, 255, 0.06);
+	}
+
+	.search-result.selected {
+		background: rgba(255, 255, 255, 0.08);
+		box-shadow: 0 0 0 1px rgba(var(--accent-rgb, 255, 107, 107), 0.3) inset;
+	}
+
+	.result-icon {
+		width: 32px;
+		height: 32px;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		background: rgba(255, 255, 255, 0.05);
+		border-radius: 8px;
+		font-size: 0.9rem;
+		flex-shrink: 0;
+		position: relative;
+		overflow: hidden;
+	}
+
+	.result-image {
+		position: absolute;
+		inset: 0;
+		width: 100%;
+		height: 100%;
+		object-fit: cover;
+		border-radius: 8px;
+	}
+
+	.result-icon-fallback {
+		/* shown behind image, visible if image fails */
+		position: relative;
+		z-index: 0;
+	}
+
+	.result-image + .result-icon-fallback {
+		/* hide fallback when image is present and loaded */
+		opacity: 0;
+	}
+
+	.result-icon[data-type='track'] {
+		color: var(--accent);
+	}
+
+	.result-icon[data-type='artist'] {
+		color: #a78bfa;
+	}
+
+	.result-icon[data-type='album'] {
+		color: #34d399;
+	}
+
+	.result-icon[data-type='tag'] {
+		color: #fbbf24;
+	}
+
+	.result-content {
+		flex: 1;
+		min-width: 0;
+		display: flex;
+		flex-direction: column;
+		gap: 0.15rem;
+	}
+
+	.result-title {
+		font-size: 0.9rem;
+		font-weight: 500;
+		white-space: nowrap;
+		overflow: hidden;
+		text-overflow: ellipsis;
+	}
+
+	.result-subtitle {
+		font-size: 0.75rem;
+		color: var(--text-secondary);
+		white-space: nowrap;
+		overflow: hidden;
+		text-overflow: ellipsis;
+	}
+
+	.result-type {
+		font-size: 0.6rem;
+		text-transform: uppercase;
+		letter-spacing: 0.03em;
+		color: var(--text-muted);
+		padding: 0.2rem 0.45rem;
+		background: rgba(255, 255, 255, 0.04);
+		border-radius: 4px;
+		flex-shrink: 0;
+	}
+
+	.search-empty {
+		padding: 2rem;
+		text-align: center;
+		color: var(--text-secondary);
+		font-size: 0.9rem;
+	}
+
+	.search-hints {
+		padding: 1.5rem 2rem;
+		text-align: center;
+	}
+
+	.search-hints p {
+		margin: 0 0 1rem 0;
+		color: var(--text-secondary);
+		font-size: 0.85rem;
+	}
+
+	.hint-shortcuts {
+		display: flex;
+		justify-content: center;
+		gap: 1.5rem;
+		color: var(--text-muted);
+		font-size: 0.75rem;
+	}
+
+	.hint-shortcuts span {
+		display: flex;
+		align-items: center;
+		gap: 0.25rem;
+	}
+
+	.hint-shortcuts kbd {
+		font-size: 0.65rem;
+		padding: 0.15rem 0.35rem;
+		background: rgba(255, 255, 255, 0.05);
+		border: 1px solid rgba(255, 255, 255, 0.08);
+		border-radius: 4px;
+		font-family: inherit;
+	}
+
+	.search-error {
+		padding: 1rem;
+		text-align: center;
+		color: var(--error);
+		font-size: 0.85rem;
+	}
+
+	/* mobile optimizations */
+	@media (max-width: 768px) {
+		.search-backdrop {
+			padding-top: 10vh;
+		}
+
+		.search-modal {
+			margin: 0 0.75rem;
+			max-height: 80vh;
+		}
+
+		.search-input-wrapper {
+			padding: 0.875rem 1rem;
+		}
+
+		.search-input {
+			font-size: 16px; /* prevents iOS zoom */
+		}
+
+		.search-results {
+			max-height: 60vh;
+		}
+
+		.hint-shortcuts {
+			flex-wrap: wrap;
+			gap: 1rem;
+		}
+	}
+
+	/* respect reduced motion */
+	@media (prefers-reduced-motion: reduce) {
+		.search-spinner {
+			animation: none;
+		}
+	}
+</style>

frontend/src/lib/search.svelte.ts

···
+// global search state using Svelte 5 runes
+import { API_URL } from '$lib/config';
+
+export type SearchResultType = 'track' | 'artist' | 'album' | 'tag';
+
+export interface TrackSearchResult {
+	type: 'track';
+	id: number;
+	title: string;
+	artist_handle: string;
+	artist_display_name: string;
+	image_url: string | null;
+	relevance: number;
+}
+
+export interface ArtistSearchResult {
+	type: 'artist';
+	did: string;
+	handle: string;
+	display_name: string;
+	avatar_url: string | null;
+	relevance: number;
+}
+
+export interface AlbumSearchResult {
+	type: 'album';
+	id: string;
+	title: string;
+	slug: string;
+	artist_handle: string;
+	artist_display_name: string;
+	image_url: string | null;
+	relevance: number;
+}
+
+export interface TagSearchResult {
+	type: 'tag';
+	id: number;
+	name: string;
+	track_count: number;
+	relevance: number;
+}
+
+export type SearchResult = TrackSearchResult | ArtistSearchResult | AlbumSearchResult | TagSearchResult;
+
+export interface SearchResponse {
+	results: SearchResult[];
+	counts: {
+		tracks: number;
+		artists: number;
+		albums: number;
+		tags: number;
+	};
+}
+
+const MAX_QUERY_LENGTH = 100;
+
+class SearchState {
+	isOpen = $state(false);
+	query = $state('');
+	results = $state<SearchResult[]>([]);
+	counts = $state<SearchResponse['counts']>({ tracks: 0, artists: 0, albums: 0, tags: 0 });
+	loading = $state(false);
+	error = $state<string | null>(null);
+	selectedIndex = $state(0);
+
+	// debounce timer
+	private searchTimeout: ReturnType<typeof setTimeout> | null = null;
+
+	open() {
+		this.isOpen = true;
+		this.query = '';
+		this.results = [];
+		this.counts = { tracks: 0, artists: 0, albums: 0, tags: 0 };
+		this.error = null;
+		this.selectedIndex = 0;
+	}
+
+	close() {
+		this.isOpen = false;
+		this.query = '';
+		this.results = [];
+		this.error = null;
+		if (this.searchTimeout) {
+			clearTimeout(this.searchTimeout);
+			this.searchTimeout = null;
+		}
+	}
+
+	toggle() {
+		if (this.isOpen) {
+			this.close();
+		} else {
+			this.open();
+		}
+	}
+
+	setQuery(value: string) {
+		this.query = value;
+		this.selectedIndex = 0;
+
+		// clear previous timeout
+		if (this.searchTimeout) {
+			clearTimeout(this.searchTimeout);
+		}
+
+		// validate length
+		if (value.length > MAX_QUERY_LENGTH) {
+			this.error = `query too long (max ${MAX_QUERY_LENGTH} characters)`;
+			this.results = [];
+			this.counts = { tracks: 0, artists: 0, albums: 0, tags: 0 };
+			return;
+		}
+
+		this.error = null;
+
+		// debounce search
+		if (value.length >= 2) {
+			this.searchTimeout = setTimeout(() => {
+				void this.search(value);
+			}, 150);
+		} else {
+			this.results = [];
+			this.counts = { tracks: 0, artists: 0, albums: 0, tags: 0 };
+		}
+	}
+
+	async search(query: string): Promise<void> {
+		if (query.length < 2) return;
+
+		this.loading = true;
+		this.error = null;
+
+		try {
+			const response = await fetch(
+				`${API_URL}/search/?q=${encodeURIComponent(query)}&limit=10`
+			);
+
+			if (!response.ok) {
+				throw new Error(`search failed: ${response.statusText}`);
+			}
+
+			const data: SearchResponse = await response.json();
+			this.results = data.results;
+			this.counts = data.counts;
+			this.selectedIndex = 0;
+		} catch (e) {
+			console.error('search error:', e);
+			this.error = e instanceof Error ? e.message : 'search failed';
+			this.results = [];
+		} finally {
+			this.loading = false;
+		}
+	}
+
+	selectNext() {
+		if (this.results.length > 0) {
+			this.selectedIndex = (this.selectedIndex + 1) % this.results.length;
+		}
+	}
+
+	selectPrevious() {
+		if (this.results.length > 0) {
+			this.selectedIndex = (this.selectedIndex - 1 + this.results.length) % this.results.length;
+		}
+	}
+
+	getSelectedResult(): SearchResult | null {
+		return this.results[this.selectedIndex] ?? null;
+	}
+
+	getResultHref(result: SearchResult): string {
+		switch (result.type) {
+			case 'track':
+				return `/track/${result.id}`;
+			case 'artist':
+				return `/u/${result.handle}`;
+			case 'album':
+				return `/u/${result.artist_handle}/album/${result.slug}`;
+			case 'tag':
+				return `/tag/${result.name}`;
+		}
+	}
+}
+
+export const search = new SearchState();

frontend/src/routes/+layout.svelte

···
 	import Player from '$lib/components/Player.svelte';
 	import Toast from '$lib/components/Toast.svelte';
 	import Queue from '$lib/components/Queue.svelte';
+	import SearchModal from '$lib/components/SearchModal.svelte';
 	import { onMount, onDestroy } from 'svelte';
 	import { page } from '$app/stores';
 	import { afterNavigate } from '$app/navigation';
 	import { auth } from '$lib/auth.svelte';
 	import { preferences } from '$lib/preferences.svelte';
 	import { player } from '$lib/player.svelte';
+	import { search } from '$lib/search.svelte';
 	import { browser } from '$app/environment';
 	import type { LayoutData } from './$types';
 
···
 		document.documentElement.style.setProperty('--queue-width', queueWidth);
 	});
 
-	function handleQueueShortcut(event: KeyboardEvent) {
-		// ignore modifier keys
+	function handleKeyboardShortcuts(event: KeyboardEvent) {
+		// Cmd/Ctrl+K: toggle search
+		if ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'k') {
+			event.preventDefault();
+			search.toggle();
+			return;
+		}
+
+		// ignore other modifier keys for remaining shortcuts
 		if (event.metaKey || event.ctrlKey || event.altKey) {
 			return;
 		}
···
 		}
 
 		// add keyboard listener for shortcuts
-		window.addEventListener('keydown', handleQueueShortcut);
+		window.addEventListener('keydown', handleKeyboardShortcuts);
 
 		// listen for system theme changes
 		const mediaQuery = window.matchMedia('(prefers-color-scheme: dark)');
···
 	onDestroy(() => {
 		// cleanup keyboard listener
 		if (browser) {
-			window.removeEventListener('keydown', handleQueueShortcut);
+			window.removeEventListener('keydown', handleKeyboardShortcuts);
 		}
 	});
 
···
 	<Player />
 {/if}
 <Toast />
+<SearchModal />
 
 <style>
 	:global(*),