diff --git a/web/src/api/libraries.test.tsx b/web/src/api/libraries.test.tsx
new file mode 100644
index 0000000..37c0f43
--- /dev/null
+++ b/web/src/api/libraries.test.tsx
@@ -0,0 +1,111 @@
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { act, renderHook, waitFor } from '@testing-library/react'
+import type { ReactNode } from 'react'
+import { expect, test } from 'vitest'
+import { mockFetch } from '@/test/mockFetch'
+import { useAddLibrary, useLibraries, useRemoveLibrary, useScanStatus, useStartScan, useUpdateLibrary } from './libraries'
+
+function setup() {
+ const client = new QueryClient({ defaultOptions: { queries: { retry: false }, mutations: { retry: false } } })
+ const wrapper = ({ children }: { children: ReactNode }) => {children}
+ return { client, wrapper }
+}
+
+const lib = (id: number, name = `Lib ${id}`) => ({ id, name, path: `/music/${id}`, created_at: '2026-11-12T10:00:00Z' })
+const none = () => new Response(null, { status: 204 })
+
+test('the libraries are listed', async () => {
+ mockFetch({ 'GET /api/v1/libraries': () => ({ libraries: [lib(1), lib(2)] }) })
+ const { result } = renderHook(() => useLibraries(), { wrapper: setup().wrapper })
+ await waitFor(() => expect(result.current.data).toHaveLength(2))
+ expect(result.current.data?.[0].name).toBe('Lib 1')
+})
+
+test('adding sends the name and the folder, and the list is read again', async () => {
+ let libs = [lib(1)]
+ const { calls } = mockFetch({
+ 'GET /api/v1/libraries': () => ({ libraries: libs }),
+ 'POST /api/v1/libraries': ({ init }) => {
+ const body = JSON.parse(String(init.body))
+ libs = [...libs, { ...lib(2), ...body }]
+ return new Response(JSON.stringify(libs[1]), { status: 201, headers: { 'Content-Type': 'application/json' } })
+ },
+ })
+ const { wrapper } = setup()
+ const { result } = renderHook(() => ({ list: useLibraries(), add: useAddLibrary() }), { wrapper })
+ await waitFor(() => expect(result.current.list.data).toHaveLength(1))
+ await act(() => result.current.add.mutateAsync({ name: 'Jazz', path: '/music/jazz' }))
+ await waitFor(() => expect(result.current.list.data).toHaveLength(2))
+ expect(JSON.parse(String(calls.find((c) => c.key === 'POST /api/v1/libraries')?.init.body))).toEqual({ name: 'Jazz', path: '/music/jazz' })
+})
+
+test('renaming sends only the name, moving only the folder', async () => {
+ const { calls } = mockFetch({ 'PATCH /api/v1/libraries/3': () => lib(3), 'GET /api/v1/libraries': () => ({ libraries: [] }) })
+ const { result } = renderHook(() => useUpdateLibrary(), { wrapper: setup().wrapper })
+ await act(() => result.current.mutateAsync({ id: 3, name: 'New name' }))
+ await act(() => result.current.mutateAsync({ id: 3, path: '/music/new' }))
+ const bodies = calls.filter((c) => c.key === 'PATCH /api/v1/libraries/3').map((c) => JSON.parse(String(c.init.body)))
+ expect(bodies).toEqual([{ name: 'New name' }, { path: '/music/new' }])
+})
+
+test('removing asks the server to delete that library and the list is read again', async () => {
+ const { calls } = mockFetch({ 'DELETE /api/v1/libraries/3': none, 'GET /api/v1/libraries': () => ({ libraries: [] }) })
+ const { wrapper } = setup()
+ const { result } = renderHook(() => ({ list: useLibraries(), remove: useRemoveLibrary() }), { wrapper })
+ await waitFor(() => expect(result.current.list.isSuccess).toBe(true))
+ await act(() => result.current.remove.mutateAsync(3))
+ await waitFor(() => expect(calls.filter((c) => c.key === 'GET /api/v1/libraries')).toHaveLength(2))
+ expect(calls.map((c) => c.key)).toContain('DELETE /api/v1/libraries/3')
+})
+
+test('a scan of everything is a POST to /library/scan, and "full" is sent only when asked', async () => {
+ const { calls } = mockFetch({
+ 'POST /api/v1/library/scan': () => new Response(JSON.stringify({ status: 'started' }), { status: 202, headers: { 'Content-Type': 'application/json' } }),
+ 'GET /api/v1/library/scan': () => ({ running: true }),
+ })
+ const { result } = renderHook(() => useStartScan(), { wrapper: setup().wrapper })
+ await act(() => result.current.mutateAsync({ full: false }))
+ await act(() => result.current.mutateAsync({ full: true }))
+ const posts = calls.filter((c) => c.key === 'POST /api/v1/library/scan')
+ expect(posts[0].url.searchParams.has('full')).toBe(false)
+ expect(posts[1].url.searchParams.get('full')).toBe('true')
+})
+
+test('a scan of one library names it', async () => {
+ const { calls } = mockFetch({
+ 'POST /api/v1/libraries/3/scan': () => new Response(JSON.stringify({ status: 'started' }), { status: 202, headers: { 'Content-Type': 'application/json' } }),
+ 'GET /api/v1/library/scan': () => ({ running: true }),
+ })
+ const { result } = renderHook(() => useStartScan(), { wrapper: setup().wrapper })
+ await act(() => result.current.mutateAsync({ libraryId: 3, full: true }))
+ const post = calls.find((c) => c.key === 'POST /api/v1/libraries/3/scan')
+ expect(post?.url.searchParams.get('full')).toBe('true')
+})
+
+test('while a scan runs the status is read again and again, and it stops by itself when the scan ends', async () => {
+ let n = 0
+ const { calls } = mockFetch({ 'GET /api/v1/library/scan': () => (++n < 3 ? { running: true } : { running: false }) })
+ const { result } = renderHook(() => useScanStatus({ intervalMs: 20 }), { wrapper: setup().wrapper })
+ await waitFor(() => expect(result.current.data?.running).toBe(false), { timeout: 2000 })
+ const seen = calls.length
+ await new Promise((r) => setTimeout(r, 120))
+ expect(calls).toHaveLength(seen)
+ expect(seen).toBe(3)
+})
+
+test('starting a scan makes the status be read at once, so the page follows it', async () => {
+ let running = false
+ const { calls } = mockFetch({
+ 'GET /api/v1/library/scan': () => ({ running }),
+ 'POST /api/v1/library/scan': () => {
+ running = true
+ return new Response(JSON.stringify({ status: 'started' }), { status: 202, headers: { 'Content-Type': 'application/json' } })
+ },
+ })
+ const { wrapper } = setup()
+ const { result } = renderHook(() => ({ status: useScanStatus({ intervalMs: 20 }), start: useStartScan() }), { wrapper })
+ await waitFor(() => expect(result.current.status.data?.running).toBe(false))
+ await act(() => result.current.start.mutateAsync({ full: false }))
+ await waitFor(() => expect(result.current.status.data?.running).toBe(true))
+ expect(calls.filter((c) => c.key === 'GET /api/v1/library/scan').length).toBeGreaterThanOrEqual(2)
+})
diff --git a/web/src/api/libraries.ts b/web/src/api/libraries.ts
new file mode 100644
index 0000000..f021b18
--- /dev/null
+++ b/web/src/api/libraries.ts
@@ -0,0 +1,69 @@
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { api } from './client'
+import type { components } from './schema'
+
+export type Library = components['schemas']['Library']
+export type ScanStatus = components['schemas']['ScanStatus']
+export type ScanSummary = components['schemas']['ScanSummary']
+
+const LIBRARIES = ['libraries']
+const SCAN = ['library', 'scan']
+
+/** Every library, oldest first. Admins only. */
+export function useLibraries() {
+ return useQuery({
+ queryKey: LIBRARIES,
+ queryFn: () => api.get<{ libraries: Library[] }>('/libraries'),
+ select: (data) => data.libraries,
+ })
+}
+
+export function useAddLibrary() {
+ const client = useQueryClient()
+ return useMutation({
+ mutationFn: (body: { name: string; path: string }) => api.post('/libraries', body),
+ onSuccess: () => client.invalidateQueries({ queryKey: LIBRARIES }),
+ })
+}
+
+/** Rename, move, or both: only the fields given are sent. */
+export function useUpdateLibrary() {
+ const client = useQueryClient()
+ return useMutation({
+ mutationFn: ({ id, ...changes }: { id: number; name?: string; path?: string }) => api.patch(`/libraries/${id}`, changes),
+ onSuccess: () => client.invalidateQueries({ queryKey: LIBRARIES }),
+ })
+}
+
+/** Removes the library from Sonda; the tracks, the history and the music on disk stay. */
+export function useRemoveLibrary() {
+ const client = useQueryClient()
+ return useMutation({
+ mutationFn: (id: number) => api.del(`/libraries/${id}`),
+ onSuccess: () => client.invalidateQueries({ queryKey: LIBRARIES }),
+ })
+}
+
+/** Whether a scan runs and how the last one ended. While one runs it is read again every `intervalMs`. */
+export function useScanStatus({ intervalMs = 2000 }: { intervalMs?: number } = {}) {
+ return useQuery({
+ queryKey: SCAN,
+ queryFn: () => api.get('/library/scan'),
+ refetchInterval: (query) => (query.state.data?.running ? intervalMs : false),
+ })
+}
+
+/**
+ * Starts a scan in the background: of one library, or of all. `full` reads every file again. Whatever the
+ * answer (also "a scan is already running"), the status is read at once so the page follows the scan.
+ */
+export function useStartScan() {
+ const client = useQueryClient()
+ return useMutation({
+ mutationFn: ({ libraryId, full }: { libraryId?: number; full: boolean }) => {
+ const path = libraryId === undefined ? '/library/scan' : `/libraries/${libraryId}/scan`
+ return api.post<{ status: 'started' }>(full ? `${path}?full=true` : path)
+ },
+ onSettled: () => client.invalidateQueries({ queryKey: SCAN }),
+ })
+}