# TRUEREF-0016 — Web UI: Search Explorer

**Priority:** P2
**Status:** Pending
**Depends On:** TRUEREF-0010, TRUEREF-0015
**Blocks:** —

---

## Overview

An interactive search interface within the web UI that lets users test the documentation retrieval system directly from the browser. Mirrors the two-step context7 flow: first resolve a library ID, then query documentation. Results are displayed with syntax highlighting. Useful for validating indexing quality and demonstrating the system to stakeholders.

---

## Acceptance Criteria

- [ ] Search page at `/search` with two-step workflow
- [ ] Step 1: Library name input → displays matching libraries with IDs and scores
- [ ] Step 2: Click library → query input → displays ranked snippets
- [ ] Syntax-highlighted code blocks (using a lightweight highlighter)
- [ ] Snippet type badge (code vs info)
- [ ] Breadcrumb display per snippet
- [ ] Token count per snippet and total
- [ ] "Copy as Markdown" button for the full response
- [ ] Library switcher (return to step 1 without full page reload)
- [ ] URL reflects current state (`/search?lib=/facebook/react&q=useState`)
- [ ] No server-side rendering needed for this page (can be client-side)

---

## Page Layout

```
/search
├── Header: "Search Documentation"
├── Step 1: Library Search
│   ├── Input: "Library name..." + Search button
│   └── Results list: library cards with ID, description, snippet count, trust score
│       └── [Click to select]
├── Step 2: Documentation Query (shown after library selected)
│   ├── Selected library badge + "Change" button
│   ├── Input: "What would you like to know?" + Search button
│   └── Results:
│       ├── Token count summary
│       ├── "Copy as Markdown" button
│       └── Snippet list:
│           ├── Code snippets: syntax-highlighted code block
│           └── Info snippets: formatted markdown
└── (loading states + empty states throughout)
```

---

## Component: LibrarySearchResult

```svelte
<!-- src/lib/components/search/LibraryResult.svelte -->
<script lang="ts">
	let { result, onSelect } = $props<{
		result: {
			id: string;
			title: string;
			description: string;
			totalSnippets: number;
			trustScore: number;
		};
		onSelect: (id: string) => void;
	}>();
</script>

<button
	onclick={() => onSelect(result.id)}
	class="w-full rounded-xl border border-gray-200 bg-white p-4 text-left shadow-sm transition-all hover:border-blue-300 hover:shadow-md"
>
	<div class="flex items-center justify-between">
		<span class="font-semibold text-gray-900">{result.title}</span>
		<span class="text-xs text-gray-400">Trust {result.trustScore.toFixed(1)}/10</span>
	</div>
	<p class="font-mono text-xs text-gray-400">{result.id}</p>
	{#if result.description}
		<p class="mt-1.5 line-clamp-2 text-sm text-gray-600">{result.description}</p>
	{/if}
	<p class="mt-2 text-xs text-gray-400">{result.totalSnippets.toLocaleString()} snippets</p>
</button>
```

---

## Component: SnippetCard

```svelte
<!-- src/lib/components/search/SnippetCard.svelte -->
<script lang="ts">
	import type { Snippet } from '$lib/types';

	let { snippet } = $props<{ snippet: Snippet }>();
</script>

<div class="overflow-hidden rounded-xl border border-gray-200 bg-white">
	<div class="flex items-center justify-between border-b border-gray-100 px-4 py-2.5">
		<div class="flex items-center gap-2">
			{#if snippet.type === 'code'}
				<span class="rounded bg-purple-100 px-1.5 py-0.5 text-xs text-purple-700">code</span>
			{:else}
				<span class="rounded bg-blue-100 px-1.5 py-0.5 text-xs text-blue-700">info</span>
			{/if}
			{#if snippet.title}
				<span class="text-sm font-medium text-gray-800">{snippet.title}</span>
			{/if}
		</div>
		<span class="text-xs text-gray-400">{snippet.tokenCount} tokens</span>
	</div>

	{#if snippet.breadcrumb}
		<p class="bg-gray-50 px-4 py-1.5 text-xs text-gray-500 italic">{snippet.breadcrumb}</p>
	{/if}

	<div class="p-4">
		{#if snippet.type === 'code'}
			<pre class="overflow-x-auto rounded bg-gray-950 p-4 text-sm text-gray-100"><code
					>{snippet.content}</code
				></pre>
		{:else}
			<div class="prose prose-sm max-w-none text-gray-700">{snippet.content}</div>
		{/if}
	</div>
</div>
```

---

## Search Page Logic

```svelte
<!-- src/routes/search/+page.svelte -->
<script lang="ts">
	import { page } from '$app/stores';
	import { goto } from '$app/navigation';

	let libraryName = $state('');
	let selectedLibraryId = $state<string | null>(null);
	let query = $state('');
	let libraryResults = $state<LibrarySearchResult[]>([]);
	let snippets = $state<Snippet[]>([]);
	let loadingLibraries = $state(false);
	let loadingSnippets = $state(false);

	async function searchLibraries() {
		loadingLibraries = true;
		const res = await fetch(
			`/api/v1/libs/search?libraryName=${encodeURIComponent(libraryName)}&query=${encodeURIComponent(query)}`
		);
		const data = await res.json();
		libraryResults = data.results;
		loadingLibraries = false;
	}

	async function searchDocs() {
		if (!selectedLibraryId) return;
		loadingSnippets = true;
		const url = new URL('/api/v1/context', window.location.origin);
		url.searchParams.set('libraryId', selectedLibraryId);
		url.searchParams.set('query', query);
		const res = await fetch(url);
		const data = await res.json();
		snippets = data.snippets;
		loadingSnippets = false;

		// Update URL
		goto(`/search?lib=${encodeURIComponent(selectedLibraryId)}&q=${encodeURIComponent(query)}`, {
			replaceState: true,
			keepFocus: true
		});
	}
</script>
```

---

## Syntax Highlighting

Use a minimal, zero-dependency approach for v1 — wrap code blocks in `<pre><code>` with a CSS-based theme. Optionally integrate `highlight.js` (lightweight) as an enhancement:

```typescript
// Optional: lazy-load highlight.js only when code snippets are present
async function highlightCode(code: string, language: string): Promise<string> {
	const hljs = await import('highlight.js/lib/core');
	// Register only needed languages
	return hljs.highlight(code, { language }).value;
}
```

---

## Files to Create

- `src/routes/search/+page.svelte`
- `src/lib/components/search/LibraryResult.svelte`
- `src/lib/components/search/SnippetCard.svelte`
- `src/lib/components/search/SearchInput.svelte`
- `src/lib/utils/copy-to-clipboard.ts`