feat(day-8): F742/F746/F751 activate semantic & hybrid search UI

Keyword/semantic/hybrid mode toggle now fully live in the ⌘⇧F overlay,
each calling /search?mode=; degraded-state banner when the embeddings
index is still building; per-result 'why?' score breakdown in hybrid
mode (explain). RelatedPanel gains a real 'similar by meaning' section
from /notes/:id/related/semantic. Embeddings coverage indicator with a
'build index' button that backfills and polls. 8 new tests; 1,518 total;
typecheck, lint, build, bundle all green.

https://claude.ai/code/session_01C8N8jgTF1MfofAu6t5CU1W

Author: claude

FEATURES.md

@@ -17,7 +17,7 @@ Your notes are the world. Your stories run on a compiler you own.
 6. Keep `pnpm test` and `pnpm build` green at every commit. Do not leave the tree broken at end of session.
 7. Update the **Status** line below at the end of every session.
 
-**Status:** Day 8 intelligence backend done: embeddings + vector + hybrid search (F721–F750) with graceful pure-JS degradation, no native deps. 1,510 tests green. Remaining Day 8: semantic UI activation (F754 backend done), ingestion/clipper/audio (F761–F790, later wave). Next: wire semantic/hybrid modes in web, then F761.
+**Status:** Day 8 search/semantic COMPLETE: keyword+semantic+hybrid search live in UI with degraded-state handling, explain breakdowns, semantic related-notes, embeddings index control. 1,518 tests green. Remaining Day 8: ingestion/clipper/audio (F761–F790, heavy-dep wave). Next: F761.
 
 ---
 

apps/web/src/api/client.ts

@@ -638,19 +638,29 @@ export const attachmentsApi = {
   },
 };
 
-/* ===== Search (F711–F720) ===== */
+/* ===== Search (F711–F720, F742, F746) ===== */
 
 export interface SearchHighlight {
   start: number;
   end: number;
 }
 
+/** Score breakdown from explain=true or scoreComponents in response (F746). */
+export interface ScoreComponents {
+  fts?: number;
+  vector?: number;
+  recency?: number;
+  links?: number;
+  [key: string]: number | undefined;
+}
+
 export interface SearchResult {
   id: string;
   title: string;
   snippet: string;
   highlights: SearchHighlight[];
   score: number;
+  scoreComponents?: ScoreComponents;
 }
 
 export interface SearchGroup {
@@ -664,6 +674,7 @@ export type SearchMode = 'keyword' | 'semantic' | 'hybrid';
 export interface SearchData {
   mode: SearchMode;
   query: string;
+  degraded?: boolean;
   groups: SearchGroup[];
 }
 
@@ -675,8 +686,10 @@ export interface SearchResponse {
 export interface SearchParams {
   q: string;
   types?: string;
+  mode?: SearchMode;
   limit?: number;
   cursor?: string;
+  explain?: boolean;
 }
 
 async function requestSearch(params: SearchParams): Promise<SearchResponse> {
@@ -700,6 +713,57 @@ export const searchApi = {
   search: (params: SearchParams) => requestSearch(params),
 };
 
+/* ===== Semantic related notes (F751/F754) ===== */
+
+export interface SemanticRelatedResult {
+  id: string;
+  title: string;
+  score: number;
+  snippet: string;
+  sourceType: string;
+}
+
+export interface SemanticRelatedData {
+  noteId: string;
+  degraded: boolean;
+  results: SemanticRelatedResult[];
+}
+
+export const relatedApi = {
+  semantic: (noteId: string, limit = 8) =>
+    api.get<SemanticRelatedData>(`/notes/${noteId}/related/semantic${qs({ limit })}`),
+};
+
+/* ===== Embeddings status + backfill (F742/embeddings indicator) ===== */
+
+export interface EmbeddingsProvider {
+  id: string;
+  dim: number;
+  available: boolean;
+}
+
+export interface EmbeddingsCoverage {
+  coveragePct: number;
+  [key: string]: unknown;
+}
+
+export interface EmbeddingsQueue {
+  queueDepth: number;
+  [key: string]: unknown;
+}
+
+export interface EmbeddingsStatus {
+  provider: EmbeddingsProvider;
+  coverage: EmbeddingsCoverage;
+  queue: EmbeddingsQueue;
+}
+
+export const embeddingsApi = {
+  status: () => api.get<EmbeddingsStatus>('/embeddings/status'),
+  backfill: () =>
+    request<{ message: string; provider: string }>('/embeddings/backfill', { method: 'POST' }),
+};
+
 /* ===== Insights (F791–F800) ===== */
 
 export interface InsightsOverview {

apps/web/src/api/hooks.ts

@@ -5,13 +5,15 @@
 import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
 import {
   attachmentsApi,
+  embeddingsApi,
   graphApi,
   importApi,
   insightsApi,
   linksApi,
   notebooksApi,
   notesApi,
   queryApi,
+  relatedApi,
   revisionsApi,
   savedQueriesApi,
   searchApi,
@@ -499,3 +501,36 @@ export function useRelatedByLinks(noteId: string | null, enabled = true) {
     staleTime: 30_000,
   });
 }
+
+/** Semantic nearest-neighbor related notes (F751/F754). */
+export function useRelatedBySemantic(noteId: string | null, limit = 8, enabled = true) {
+  return useQuery({
+    queryKey: ['related', 'semantic', noteId ?? 'none', limit],
+    queryFn: () => relatedApi.semantic(noteId as string, limit),
+    enabled: noteId !== null && enabled,
+    staleTime: 60_000,
+  });
+}
+
+/* ===== Embeddings status (F742 indicator) ===== */
+
+export function useEmbeddingsStatus(enabled = true) {
+  return useQuery({
+    queryKey: ['embeddings', 'status'],
+    queryFn: embeddingsApi.status,
+    enabled,
+    staleTime: 10_000,
+    refetchInterval: (query) => {
+      const depth = query.state.data?.queue.queueDepth ?? 0;
+      return depth > 0 ? 3000 : false;
+    },
+  });
+}
+
+export function useEmbeddingsBackfill() {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: embeddingsApi.backfill,
+    onSuccess: () => void qc.invalidateQueries({ queryKey: ['embeddings', 'status'] }),
+  });
+}

apps/web/src/related/RelatedPanel.test.tsx

@@ -0,0 +1,151 @@
+// @vitest-environment jsdom
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { createWrapper, mockFetchRoutes } from '../test-utils/wrappers.js';
+import { RelatedPanel } from './RelatedPanel.js';
+import type { NoteWithTags } from '../api/client.js';
+
+const mockNote: NoteWithTags = {
+  id: 'note-1',
+  notebookId: 'nb-1',
+  title: 'Test Note',
+  body: 'Some content',
+  pinned: false,
+  trashedAt: null,
+  createdAt: '2025-01-01T00:00:00Z',
+  updatedAt: '2025-01-01T00:00:00Z',
+  rev: 1,
+  tags: [],
+};
+
+const mockNoteWithTags: NoteWithTags = {
+  ...mockNote,
+  tags: [{ id: 't1', name: 'fiction', color: null, createdAt: '2025-01-01T00:00:00Z' }],
+};
+
+const onClose = vi.fn();
+
+const emptyGraph = {
+  data: { nodes: [], edges: [], stats: { nodes: 0, edges: 0, orphans: 0, communities: 0 } },
+};
+const emptyBacklinks = {
+  data: { noteId: 'note-1', total: 0, sources: [] },
+};
+
+describe('RelatedPanel semantic section (F751/F754)', () => {
+  it('renders "Similar by meaning" section with semantic results', async () => {
+    mockFetchRoutes([
+      { url: '/api/v1/notes/note-1/graph', body: emptyGraph },
+      { url: '/api/v1/notes/note-1/backlinks', body: emptyBacklinks },
+      {
+        url: '/api/v1/notes/note-1/related/semantic',
+        body: {
+          data: {
+            noteId: 'note-1',
+            degraded: false,
+            results: [
+              { id: 'note-2', title: 'Related Story', score: 0.87, snippet: 'About stories', sourceType: 'note' },
+              { id: 'note-3', title: 'Another Match', score: 0.72, snippet: 'More content', sourceType: 'note' },
+            ],
+          },
+        },
+      },
+    ]);
+
+    render(<RelatedPanel note={mockNote} onClose={onClose} />, { wrapper: createWrapper() });
+
+    await waitFor(
+      () => expect(screen.queryByText('Related Story')).not.toBeNull(),
+      { timeout: 3000 },
+    );
+    expect(screen.queryByText('Another Match')).not.toBeNull();
+    // Score rendered as percentage
+    expect(screen.queryByText('87%')).not.toBeNull();
+  });
+
+  it('shows "building index" badge when degraded=true', async () => {
+    mockFetchRoutes([
+      { url: '/api/v1/notes/note-1/graph', body: emptyGraph },
+      { url: '/api/v1/notes/note-1/backlinks', body: emptyBacklinks },
+      {
+        url: '/api/v1/notes/note-1/related/semantic',
+        body: {
+          data: {
+            noteId: 'note-1',
+            degraded: true,
+            results: [
+              { id: 'note-4', title: 'Linked Note', score: 0.5, snippet: 'A linked note', sourceType: 'note' },
+            ],
+          },
+        },
+      },
+    ]);
+
+    render(<RelatedPanel note={mockNote} onClose={onClose} />, { wrapper: createWrapper() });
+
+    await waitFor(
+      () => expect(screen.queryByText('building index')).not.toBeNull(),
+      { timeout: 3000 },
+    );
+    // Shows "linked" instead of percentage when degraded
+    expect(screen.queryByText('linked')).not.toBeNull();
+  });
+
+  it('shows empty state when no semantic results', async () => {
+    mockFetchRoutes([
+      { url: '/api/v1/notes/note-1/graph', body: emptyGraph },
+      { url: '/api/v1/notes/note-1/backlinks', body: emptyBacklinks },
+      {
+        url: '/api/v1/notes/note-1/related/semantic',
+        body: {
+          data: {
+            noteId: 'note-1',
+            degraded: false,
+            results: [],
+          },
+        },
+      },
+    ]);
+
+    render(<RelatedPanel note={mockNote} onClose={onClose} />, { wrapper: createWrapper() });
+
+    await waitFor(
+      () => expect(screen.queryByText('No similar notes found yet.')).not.toBeNull(),
+      { timeout: 3000 },
+    );
+  });
+
+  it('dismissing a semantic result removes it from view', async () => {
+    mockFetchRoutes([
+      { url: '/api/v1/notes/note-1/graph', body: emptyGraph },
+      { url: '/api/v1/notes/note-1/backlinks', body: emptyBacklinks },
+      {
+        url: '/api/v1/notes/note-1/related/semantic',
+        body: {
+          data: {
+            noteId: 'note-1',
+            degraded: false,
+            results: [
+              { id: 'note-5', title: 'Dismissable Note', score: 0.9, snippet: 'Content', sourceType: 'note' },
+            ],
+          },
+        },
+      },
+    ]);
+
+    render(<RelatedPanel note={mockNoteWithTags} onClose={onClose} />, { wrapper: createWrapper() });
+
+    await waitFor(
+      () => expect(screen.queryByText('Dismissable Note')).not.toBeNull(),
+      { timeout: 3000 },
+    );
+
+    const dismissBtn = screen.getByLabelText('Dismiss Dismissable Note');
+    fireEvent.click(dismissBtn);
+
+    await waitFor(
+      () => expect(screen.queryByText('Dismissable Note')).toBeNull(),
+      { timeout: 1000 },
+    );
+  });
+});