frontend.md

# Frontend Architecture

Biblioteka's frontend is a single-page application (SPA) built with **Svelte 5**, **TypeScript**, and **Tailwind CSS 3**. It is bundled by **Vite** and served as static assets embedded in the Go binary.

## Directory layout

```
frontend/
  index.html          HTML entry point; loads favicon, web manifest, and main.ts
  public/             Static assets served at the root URL (copied verbatim by Vite)
    favicon.ico             Default favicon
    favicon-16x16.png       16 × 16 PNG favicon
    favicon-32x32.png       32 × 32 PNG favicon
    apple-touch-icon.png    iOS home-screen icon
    android-chrome-192x192.png  Android home-screen icon (192 × 192)
    android-chrome-512x512.png  Android home-screen icon (512 × 512)
    site.webmanifest        PWA web app manifest (name, icons, theme colour)
  src/
    App.svelte          Root component: auth gate + shell layout + routing; includes skip-to-main-content link (WCAG 2.4.1) and dynamic document title updates (WCAG 2.4.2)
    main.ts             Entry point; mounts App and initialises the theme
    index.css           Tailwind CSS directives
    types/              Domain-scoped TypeScript interfaces for API entities
      annotation.ts       Book annotation types
      audit.ts            Audit log types
      auth.ts             User, auth, and API key types
      book.ts             Book, BookFile, BookSummary, and book-related types
      calibre.ts          Calibre import preview types
      config.ts           Server configuration types (OIDC, SMTP, LLM)
      library.ts          Library types and organization type constants
      metadata.ts         AI enrichment and metadata-fetch types
      reading.ts          Reading progress, reading list, and reading group types
      index.ts            Barrel re-export of all domain type modules
    components/         Page-level Svelte components (PascalCase)
      Auth.svelte         Login and signup page shell; owns tab-switching state and delegates form rendering to `LoginForm.svelte` and `SignupForm.svelte`; wraps all form content in a `<main>` landmark (WCAG 1.3.6); the Login/Sign Up toggle uses the ARIA tablist/tab/tabpanel pattern with roving tabindex and keyboard navigation (WCAG 4.1.2); calls `fetchAuthFeatureFlags` on mount to enable or disable OIDC, signup, and passkey flows
      auth/               Sub-components for the login and signup page forms
        LoginForm.svelte    Email + password login form; implements `role="tabpanel"` with `aria-labelledby="login-tab"`; accepts `$bindable` props (`email`, `password`, `emailInvalid`, `passwordInvalid`, `error`, `loading`) for reactive two-way binding with `Auth.svelte`; renders an `AlertBanner` when `errorVisible` is true; fields carry `aria-required`, `aria-invalid`, and `aria-describedby` linked to the error banner (WCAG 3.3.1)
        SignupForm.svelte   Name + email + password registration form; implements `role="tabpanel"` with `aria-labelledby="signup-tab"`; accepts `$bindable` props (`name`, `email`, `password`, `nameInvalid`, `emailInvalid`, `passwordInvalid`, `error`, `loading`) for reactive two-way binding with `Auth.svelte`; fields carry `aria-required`, `aria-invalid`, and `aria-describedby` (WCAG 3.3.1)
      Books.svelte        Book listing and detail view; includes a debounced search input that persists the search term in the URL hash query string (`#books?query=tolkien`); reads `initialOffset` from the URL and writes page changes back via `routerStore.setQueryParam`
      NotFound.svelte     404 page rendered when the router encounters an unknown hash path
      Dashboard.svelte    Home screen; shows an empty-state onboarding card only after libraries are loaded and the list is empty; otherwise renders four content areas: (1) a two-card stats grid (Total Books, Libraries); (2) a downloads-per-month histogram (via `DownloadsHistogram.svelte`); (3) a Reading Activity section showing KOSync reading streaks, finished-books count, and in-progress books with per-book progress bars and estimated time remaining — falls back to a "Welcome to Biblioteka" prose panel while stats are loading or a KOSync nudge when no reading data exists; (4) a Year in Books card (`data-testid="year-in-books-card"`) showing books finished, longest streak, days reading, and total downloads for the current calendar year — hidden when all counts are zero; followed by a `Recommendations.svelte` "You Might Also Like" panel; all four data sets (total books count, downloads, reading stats, year-in-books) are fetched concurrently in `onMount` with a cancellation guard that prevents stale writes after unmount; each fetch surfaces errors independently via `AlertBanner` so a failure in one section does not block the others; Total Books shows "…" while in flight and falls back to `0` on error; Libraries reflects the live `libraryStore.libraries.length`; each stat card uses a `<dl>/<dt>/<dd>` description-list structure so that screen readers can announce the label–value relationship correctly (WCAG 1.3.1)
      Groups.svelte       Reading Groups top-level view; renders either a group list with an inline create form (when no sub-path is active) or `GroupDetail` for a specific group; supports the sub-path `"new"` to open the create form via `routerStore`; delegates entirely to `GroupDetail` when `routerStore.subPath` is a group ID
      Libraries.svelte    Library management view; dispatches to sub-components based on `routerStore.subPath`: `"new"` → `LibraryForm` (create mode), `"edit/{id}"` → `LibraryForm` (edit mode), `"setup"` → `FirstLibraryWizard` (first-library onboarding wizard), `"{id}"` → `LibraryView`, or empty → list / empty state; a `$effect` redirects away from `"setup"` automatically if the user already has at least one library
      MyLibrary.svelte    Placeholder for a planned per-user personal library feature; currently shows an empty state
      Recommendations.svelte  "You Might Also Like" panel rendered at the bottom of the Dashboard; fetches up to 10 book recommendations via `getRecommendations(limit)` using a `$effect`; shows skeleton cards while loading; renders an inline error message when the fetch fails (and logs the error to the console) and renders an empty-state message with a link to `#settings/kobo` when the result set is empty; book cards link to `#books/{id}` via `routerStore.navigate`
      Settings.svelte     Settings shell; owns shared admin state; renders one tab at a time
      Sidebar.svelte      Navigation sidebar; fetches and displays the running server version; uses `<a href>` anchor links for all navigation items; the brand name is rendered as `<p>` (not `<h1>`) to avoid duplicate top-level headings (WCAG 1.3.1); icon-only action links (Create library, Library settings) carry `aria-label`, and the Create-library icon explicitly carries `aria-hidden="true"` (WCAG 4.1.2); the Library-settings link aria-label includes the library name (e.g. "Library settings for Fiction") so each link has a unique, descriptive name (WCAG 2.4.6); the Library-settings link uses a contrast-safe resting color (`text-ink-500`) and switches to `text-accent-400` on hover/focus-within to preserve affordance while meeting WCAG 1.4.11; nav link clusters are wrapped in `role="group"` containers labelled by `<h2>` group headings (WCAG 1.3.1)
      books/              Sub-components for book detail and editing
        AIEnrichmentPanel.svelte  Review panel for a pending AI enrichment; fetches the pending `ai_enrichments` record via `getPendingAIEnrichment`; renders nothing when no pending enrichment exists (404 is treated as the normal empty state); displays suggested tags, reading level, and generated description when a pending enrichment is present; **Apply** button calls `applyAIEnrichment` and invokes the `onApplied` callback on success; **Reject** button calls `rejectAIEnrichment` and invokes the `onRejected` callback on success; both buttons are disabled while an action is in progress; aborts the in-flight request and resets state when `bookId` changes (prevents stale results from a previous book appearing on the newly selected book)
        BookDetail.svelte    Book detail view; displays cover image, metadata, author/series associations, file attachments, and download links; includes `AIEnrichmentPanel` in the detail view and reloads book data on apply via the panel's `onApplied` callback
        BookEdit.svelte      Book edit page; fetches book data, manages form state, and coordinates the `BookEditForm` and `MetadataFetchPanel` sub-components
        BookEditForm.svelte  Book metadata edit form; required fields carry `aria-required={true}` and a visible legend ("Fields marked with an asterisk are required") uses `aria-hidden` on the visual `*` and a `sr-only` span for the spoken label (WCAG 3.3.2); when a Cover Image URL is entered, a live preview thumbnail renders below the field — the image is hidden automatically via an `onerror` handler if the URL fails to load
        MetadataComparison.svelte   Side-by-side comparison of current and fetched remote metadata; lets the user selectively apply individual fields
        MetadataFetchPanel.svelte   Panel that triggers a remote metadata fetch, streams progress events, and renders `MetadataComparison` once results arrive
      groups/             Sub-components for the Reading Groups detail view
        GroupDetail.svelte       Detail view shell for a single reading group; fetches the group from `groupStore` by ID; derives `isOwner` from `authStore.user.id`; composes `GroupEditHeader`, `GroupMembers`, and `GroupSharedLists`
        GroupEditHeader.svelte   Group title, description, and owner-only edit / delete controls; inline name + description edit form; delete action uses an inline two-step confirmation guard
        GroupMembers.svelte      Member list with add-member and remove-member controls; fetches members via `listGroupMembers` on mount and after each successful mutation; owner can add members by user ID; only owners can remove members
        GroupSharedLists.svelte  Shared reading lists panel; fetches shared lists via `listGroupReadingLists`; members can share one of their own lists via a dropdown; group owners can unshare any shared list, and list owners can unshare their own shared list — both with a two-step inline confirmation
      libraries/          Reusable sub-components for the Libraries view
        FirstLibraryWizard.svelte  Four-step onboarding wizard shown at `#libraries/setup` when the user has no libraries; guides the user through naming the library (step 1), choosing folder paths (step 2), selecting file-organization type and monitoring toggle (step 3), and reviewing settings before creation (step 4); a "Skip for now" button in the header calls `onboardingStore.skip()` and navigates to the dashboard; the step progress bar uses a `role="group"` container with an `aria-label` of `"Progress: step N of 4"` and a `role="status"` live region below it so screen readers announce the current step title without moving focus (WCAG 4.1.3); name and folder inputs carry `aria-invalid` and `aria-describedby` wired to inline `role="alert"` error messages (WCAG 1.3.1, 3.3.1); the monitor toggle uses `role="switch"` with explicit `aria-checked` (WCAG 4.1.2)
        LibraryForm.svelte   Create / edit library form; required fields carry `aria-required={true}` and a visible legend ("Fields marked with an asterisk are required") uses `aria-hidden` on the visual `*` and a `sr-only` span for the spoken label (WCAG 3.3.2); the "Monitor for new content" toggle uses `role="switch"` and explicit `aria-checked` to communicate on/off state to assistive technologies (WCAG 4.1.2); delete library action uses the `DeleteConfirmation` component for an accessible inline confirmation with keyboard-focus management and Escape-to-dismiss (WCAG 4.1.2)
        LibraryView.svelte   Library detail with book listing
      settings/           Tab sub-components for the Settings page (see Settings component architecture below)
        AccountTab.svelte       Account management: view email, edit display name, change password, and link OIDC account
        APIKeysTab.svelte       Create and revoke long-lived API keys (`bib_` prefix); delete actions use an inline `role="alertdialog"` confirmation with keyboard-focus management and Escape-to-dismiss instead of `window.confirm()` (WCAG 4.1.2)
        KoboTab.svelte          Kobo sync token management; displays setup instructions; delete actions use an inline `role="alertdialog"` confirmation with keyboard-focus management and Escape-to-dismiss instead of `window.confirm()` (WCAG 4.1.2)
        OidcTab.svelte          Admin: OIDC / SSO provider configuration
        PreferencesTab.svelte   Display theme selection; announces the new theme to screen readers via a `role="status"` live region so assistive technologies are notified without moving focus (WCAG 4.1.3)
        SmtpTab.svelte          Admin: SMTP mail server configuration
        UsersTab.svelte         Admin: user list and admin-role toggling; all `<th>` column headers carry `scope="col"` (WCAG 1.3.1); the role-toggle button carries an action-oriented `aria-label` describing the operation it will perform (WCAG 4.1.2)
        WatchFolderTab.svelte   Admin: watch-folder path and target-library configuration; scans every minute for new `.epub`, `.mobi`, `.pdf`, `.azw3` files; a Clear button disables the watch folder without deleting any files
        CalibreImportTab.svelte Admin: three-step import wizard (upload or server path → preview → result); supports both file-upload and server-side `metadata.db` path import modes; shows per-book import counts (imported, skipped, errors); library selection is optional
        SearchIndexTab.svelte   Admin: triggers `POST /api/admin/search/reindex` to rebuild the SQLite FTS5 full-text search index in the background; displays a success or error banner; on PostgreSQL the endpoint completes immediately and no rebuild is needed
      ui/                 Generic reusable UI components
        AlertBanner.svelte   Dismissible alert / error banner
        BookCard.svelte      Card widget displaying a single book summary
        BookList.svelte      Paginated book list with grid / table view toggle; accepts a `fetchBooks` callback; supports optional polling for scan-aware empty states; table view uses native `<a>` links for keyboard navigation (WCAG 2.1.1); the current page position is announced to screen readers via an `aria-live="polite"` live region (WCAG 4.1.3)
        Button.svelte        Reusable button with `primary`, `secondary`, and `danger` variants and two sizes (`sm`, `md`); renders as `inline-flex items-center justify-center` with built-in padding per size
        DeleteConfirmation.svelte  Accessible inline delete-confirmation dialog (`role="alertdialog"`, Escape-to-dismiss, autofocus on open); encapsulates the standard pattern for accessible destructive-action confirmations (WCAG 4.1.2)
        DownloadsHistogram.svelte  Bar chart showing monthly download counts; visual bars are `aria-hidden` and paired with a screen-reader-only data table (`Month` + `Downloads`) as the accessible equivalent; count tooltip uses `text-ink-600 dark:text-ink-200` and month labels use `text-ink-600 dark:text-ink-400` to meet the WCAG 1.4.3 Contrast Minimum (Level AA)
        EmailBookModal.svelte      Modal dialog for emailing a book file to an address; implements full focus trapping (Tab / Shift+Tab wrap-around), Escape-to-dismiss, and autofocus on the Close button (WCAG 2.1.1, 2.1.2)
        TextInput.svelte     Reusable text input; forwards all standard `<input>` HTML attributes; placeholder text in dark mode uses `dark:placeholder:text-ink-300` to meet the minimum contrast ratio for non-active UI text (WCAG 1.4.3); border uses `border-ink-400 dark:border-ink-400` to meet the Non-text Contrast minimum (WCAG 1.4.11); uses `focus-visible:outline-none` (not `outline-none`) so the global `*:focus-visible` outline is suppressed when the control matches `:focus-visible` (typically keyboard focus or other UA-determined cases where focus should be visibly indicated), while the component's `focus:ring-*` styles provide the visible focus indicator and avoid a double ring (WCAG 2.4.7)
    stores/             Reactive state modules (lowercase, *.svelte.ts)
    lib/
      actions.ts              Svelte action utilities (`autofocusFirstButton`)
      authErrors.ts           Field-level ARIA invalid-state helpers for the auth page; `getLoginFieldInvalidState` and `getSignupFieldInvalidState` parse server error messages to decide which form fields should carry `aria-invalid={true}`
      authErrors.test.ts      Unit tests for `authErrors.ts`; covers ambiguous, field-specific, and credential error messages
      authFeatureFlags.ts     `fetchAuthFeatureFlags` function and `AuthFeatureFlags` interface; concurrently resolves OIDC, signup, and passkey availability from the server via `Promise.allSettled` and returns an aggregate result even when individual requests fail
      authFormValidation.ts   Client-side form validation for the auth page; `validateAuthForm` runs email, minLength, and required rules via `validation.ts` helpers and returns field validity flags plus a single error string; exports `AuthFormValidationInput` and `AuthFormValidationResult` interfaces
      authFormValidation.test.ts  Unit tests for `authFormValidation.ts`
      authRequiredErrors.ts   Human-readable required-field error generators; `getLoginRequiredFieldError` and `getSignupRequiredFieldError` produce accessible error strings for missing fields, used by `authFormValidation.ts`
      api.ts                  Barrel re-export; re-exports every symbol from `api/` sub-modules
      api.test.ts             API client unit tests; imports from the barrel and covers core, auth, config, admin, credentials, and SMTP sub-modules
      api/                    Domain-specific API sub-modules
        core.ts               Token storage, `ApiError`, `request`, `requestFormData`, `getVersion`
        auth.ts               `signup`, `login`, `logout`, `getMe`, OIDC helpers, `changePassword`
        config.ts             OIDC + SMTP server configuration
        admin.ts              User management and audit logs
        credentials.ts        OPDS + KOSync credentials
        libraries.ts          Library CRUD + paginated book listing
        authors.ts            Author CRUD + author–book relationships
        series.ts             Series CRUD + series–book relationships
        books.ts              Book CRUD, associations, and file management
        tokens.ts             API keys, Kobo tokens
      autoDismissTimer.svelte.ts  `AutoDismissTimer` class — temporary visibility state with auto-dismiss timeout
      autoDismissTimer.test.ts    Unit tests for `AutoDismissTimer`
      clipboard.ts            Async clipboard helper with `execCommand` fallback
      clipboard.test.ts       Clipboard helper unit tests
      copyTimeout.svelte.ts   `CopyTimeoutState` class — auto-resetting copied-ID feedback state
      copyTimeout.test.ts     Unit tests for `CopyTimeoutState`
      timeoutState.svelte.ts  `TimeoutState<T>` base class — shared timer infrastructure for `AutoDismissTimer` and `CopyTimeoutState`
      timeoutState.test.ts    Unit tests for `TimeoutState<T>`
      tokenList.svelte.ts     `TokenListState<T>` class — load/delete lifecycle for token-like lists
      tokenList.test.ts       Unit tests for `TokenListState`
      validation.ts           Composable form-validation rule functions
      validation.test.ts      Form-validation unit tests
  vite.config.ts      Vite configuration: build output, dev proxy, Vitest setup, and the restoreGitkeep plugin
```

## Reactive stores

All global state is managed through **Svelte 5 reactive class stores** in `frontend/src/stores/`. Each store is a class whose properties are declared with `$state` (for scalar values and nullable objects) or `$state.raw` (for array properties that are replaced wholesale on fetch), and a singleton instance is exported for use throughout the application.

### Pattern

Most stores that manage a list of entities (authors, series, etc.) extend the generic `CrudStore<T, TInput>` base class defined in `frontend/src/stores/crudStore.svelte.ts`. This base class provides the common `load`, `add`, `edit`, and `remove` operations so individual stores only need to supply the API wiring and any domain-specific accessors.

```ts
// frontend/src/stores/crudStore.svelte.ts — the shared base class
export interface CrudOps<T, TInput> {
  list:   () => Promise<T[]>;
  create: (input: TInput) => Promise<T>;
  update: (id: string, input: TInput) => Promise<T>;
  delete: (id: string) => Promise<void>;
}

export class CrudStore<T extends { id: string }, TInput> {
  items: T[] = $state.raw([]);
  loading = $state(false);
  loaded  = $state(false);
  error: string | null = $state(null);

  private readonly ops: CrudOps<T, TInput>;

  constructor(ops: CrudOps<T, TInput>) { this.ops = ops; }

  async load():                             Promise<void> { … }
  async add(input: TInput):                 Promise<T>    { … }
  async edit(id: string, input: TInput):    Promise<T>    { … }
  async remove(id: string):                 Promise<void> { … }
}
```

The `error` field is set when `load()` fails and cleared before each operation. If the rejection value is an `Error` instance, its `message` is used; otherwise the fallback string `"Failed to load"` is stored. Because `loaded` remains `false` after a failed `load()`, the idempotency guard allows a retry — callers can re-invoke `load()` after displaying the error and the store will attempt the fetch again.

**Displaying load errors from a `CrudStore`-based store:**

```svelte
<script lang="ts">
  import { authorStore } from "../stores/authors.svelte";

  $effect(() => { authorStore.load(); });
</script>

{#if authorStore.error}
  <p role="alert" class="text-danger-600">{authorStore.error}</p>
{/if}

{#if authorStore.loading}
  <p>Loading…</p>
{:else}
  {#each authorStore.authors as author}
    <p>{author.name}</p>
  {/each}
{/if}
```

A concrete store extends `CrudStore` and passes the relevant API functions to the constructor:

```ts
// frontend/src/stores/authors.svelte.ts
import type { Author, AuthorInput } from "../types";
import * as api from "../lib/api";
import { CrudStore } from "./crudStore.svelte";

class AuthorStore extends CrudStore<Author, AuthorInput> {
  constructor() {
    super({
      list:   api.listAuthors,
      create: api.createAuthor,
      update: api.updateAuthor,
      delete: api.deleteAuthor,
    });
  }

  // Named accessor keeps call sites readable: authorStore.authors
  get authors(): Author[] { return this.items; }
  set authors(v: Author[]) { this.items = v; }
}

export const authorStore = new AuthorStore();
```

For stores with additional state beyond basic CRUD (e.g. scan tracking in `libraryStore`), the store may need a fully hand-rolled class instead. `libraryStore` is an example of a store that is currently implemented that way because its `add` flow also maintains scan-tracking state and behavior beyond the base CRUD pattern. If your domain-specific state fits naturally alongside the base CRUD operations, extend `CrudStore` (as `seriesStore` does); otherwise, implement the class directly with `$state` fields.

> **When NOT to extend `CrudStore`**: Use a plain class with `$state` directly for stores that are not entity-list stores (e.g. `authStore`, `routerStore`, `themeStore`).

> **Why classes instead of writable stores?**  
> Svelte 5 introduces fine-grained reactivity via `$state` runes. Using a class groups related state and methods together and makes the reactive surface explicit. It is the idiomatic Svelte 5 approach and replaces the `writable`/`readable` store API from Svelte 4.

> **`$state` vs `$state.raw`**  
> Use `$state` for scalar values (booleans, strings, numbers) and nullable object references (e.g. `user: User | null = $state(null)`). Use `$state.raw` for array properties that are replaced wholesale on every fetch — `$state.raw` tracks only the reference, not the contents of the array. This prevents Svelte from creating a deep reactive proxy over the list items, which avoids unnecessary overhead and eliminates the _"state mutated outside a reactive context"_ console warning that would appear when assigning a new array to a `$state`-annotated property from inside an `async` method.

### Available stores

| File | Export | Purpose |
|------|--------|---------|
| `auth.svelte.ts` | `authStore` | Current user, sign-in/up/out, OIDC token initialisation |
| `router.svelte.ts` | `routerStore` | Hash-based navigation; current view and sub-path |
| `theme.svelte.ts` | `themeStore` | Light / dark / auto theme preference; persisted to `localStorage` |
| `libraries.svelte.ts` | `libraryStore` | Library CRUD; cached after first load; tracks background scan state via `scanningIds` and `isScanning` |
| `authors.svelte.ts` | `authorStore` | Author CRUD; cached after first load |
| `series.svelte.ts` | `seriesStore` | Series CRUD; cached after first load |
| `reading-lists.svelte.ts` | `readingListStore` | Reading list CRUD and book membership; cached after first load |
| `groups.svelte.ts` | `groupStore` | Reading group CRUD; cached after first load |
| `onboarding.svelte.ts` | `onboardingStore` | Tracks whether the first-library setup wizard has been dismissed per user; persisted to `localStorage` |

### `libraryStore` — scanning state API

When a library is added, the backend scans it asynchronously. `libraryStore` tracks in-progress scans so components can show real-time feedback without polling on their own.

| Member | Type | Description |
|--------|------|-------------|
| `scanningIds` | `SvelteSet<string>` | Reactive set of library IDs whose background scan is in progress. Add a `$derived` check against this set to drive per-library UI. |
| `isScanning` | `boolean` (derived) | `true` when at least one library is currently scanning (`scanningIds.size > 0`). Useful for driving aggregate UI like the all-books view. |
| `clearScanning(id)` | `void` | Removes the given library ID from `scanningIds` and cancels its auto-clear timer. Call this from `BookList`'s `onBooksFound` callback once the scan has completed. |
| `clearAllScanning()` | `void` | Removes all library IDs from `scanningIds` and cancels all timers. Useful in tests or when the user navigates away. |

`add()` automatically marks the newly created library as scanning and schedules an auto-clear after 5 minutes as a safety net (in case the frontend misses the signal). `remove()` calls `clearScanning` for the deleted library so stale scanning state is not left behind.

**Deriving per-library scanning state:**

```svelte
<script lang="ts">
  import { libraryStore } from "../../stores/libraries.svelte";

  let { libraryId }: { libraryId: string } = $props();

  // Reactive: true while this library's scan is in progress
  let scanning = $derived(libraryStore.scanningIds.has(libraryId));
</script>
```

### `readingListStore` — reading list and book membership API

`readingListStore` manages the authenticated user's reading lists. It is a hand-rolled store class (not based on `CrudStore`) because the book-membership operations require extra server round-trips to keep `book_count` accurate.

| Member | Type | Description |
|--------|------|-------------|
| `lists` | `ReadingList[]` (`$state.raw`) | Current list of reading lists, sorted alphabetically by name |
| `loading` | `boolean` | `true` while the initial fetch is in progress |
| `loaded` | `boolean` | `true` once the initial fetch has completed (even on error) |
| `loadError` | `string \| null` | Error message from the most recent failed `load()` call |
| `load()` | `Promise<void>` | Fetches all reading lists; idempotent (no-ops if already loading or loaded) |
| `reload()` | `Promise<void>` | Forces a fresh fetch regardless of `loaded` state |
| `create(input)` | `Promise<ReadingList>` | Creates a new list and inserts it into `lists` in sorted order |
| `update(id, input)` | `Promise<ReadingList>` | Updates a list in-place and re-sorts `lists` |
| `remove(id)` | `Promise<void>` | Deletes a list and removes it from `lists` |
| `addBook(listId, bookId)` | `Promise<void>` | Adds a book to a list and reloads to refresh `book_count` |
| `removeBook(listId, bookId)` | `Promise<void>` | Removes a book from a list and reloads to refresh `book_count` |

Both `addBook` and `removeBook` call `reload()` after the backend write to keep `book_count` in sync — the backend add/remove operations are idempotent so an extra reload is always safe.

**Typical usage:**

```svelte
<script lang="ts">
  import { readingListStore } from "../stores/reading-lists.svelte";

  $effect(() => {
    if (!readingListStore.loaded && !readingListStore.loading) {
      void readingListStore.load();
    }
  });
</script>

{#each readingListStore.lists as list}
  <p>{list.name} — {list.book_count} books</p>
{/each}
```

### `onboardingStore` — first-library wizard skip state

`onboardingStore` tracks whether the user has dismissed the first-library setup wizard. The skip flag is stored in `localStorage` under a per-user key (`biblioteka_onboarding_skipped_{userId}`) so the wizard does not reappear after a page reload.

| Member | Signature | Description |
|--------|-----------|-------------|
| `isSkipped(userId)` | `(userId: string \| undefined) => boolean` | Returns `true` when the wizard has been dismissed for the given user. Returns `false` while `userId` is `undefined` (e.g. during auth initialisation). Reactive: callers re-evaluate when `skip()` or `clearSkip()` is called. |
| `skip(userId)` | `(userId: string \| undefined) => void` | Persists the skip flag for this user. Called by `FirstLibraryWizard` when the user clicks "Skip for now". Silently ignores `localStorage` errors (e.g. in private-browsing mode). |
| `clearSkip(userId)` | `(userId: string \| undefined) => void` | Removes the skip flag. Called after the user successfully creates their first library so the wizard can resurface if they later remove all libraries. |

**Usage in `Dashboard.svelte`:**

`Dashboard.svelte` conditionally renders onboarding cards when the user has no libraries. It does **not** auto-redirect to the wizard; instead it shows inline UI:

- **Not skipped:** a prominent "Get started with Biblioteka" card with an "Add Your First Library" button linking to the wizard.
- **Skipped:** a subtle reminder card ("You skipped the setup wizard") with a button to re-enter setup.

```svelte
<script lang="ts">
  import { onboardingStore } from "../stores/onboarding.svelte";
  import { authStore } from "../stores/auth.svelte";
  import { libraryStore } from "../stores/libraries.svelte";
</script>

{#if libraryStore.loaded && libraryStore.libraries.length === 0}
  {#if onboardingStore.isSkipped(authStore.user?.id)}
    <!-- subtle reminder card with "Set up" button -->
  {:else}
    <!-- prominent onboarding card with "Add Your First Library" button -->
  {/if}
{/if}
```

### Using a store in a component

Stores are plain class instances — no special `$` prefix import is needed for their reactive properties when used inside `.svelte` files with the runes compiler:

```svelte
<script lang="ts">
  import { libraryStore } from "../stores/libraries.svelte";

  $effect(() => {
    libraryStore.load();
  });
</script>

{#each libraryStore.libraries as lib}
  <p>{lib.name}</p>
{/each}
```

> **Prefer `$effect` for one-time initial data fetching in Svelte 5 runes-mode components.** Store `load()` methods on `CrudStore`-based stores include an idempotency guard (`if (this.loading || this.loaded) return;`), so calling `load()` from a bare `$effect` is safe — the guard prevents duplicate requests even if the effect re-runs. `TokenListState.load()` has no such guard, but is equally safe because it performs no synchronous `$state` reads, so Svelte never registers a reactive dependency and the effect runs only once. For non-idempotent initialization that must run exactly once regardless of reactive dependencies, use a non-reactive boolean guard variable:
>
> ```svelte
> let initialized = false;
> $effect(() => {
>   if (!initialized) {
>     initialized = true;
>     void doOneTimeSetup();
>   }
> });
> ```
>
> `onMount` and `onDestroy` are not used in new components. Use `$effect` for all initialization and side effects. For cleanup (such as canceling timers or subscriptions), return a cleanup function from `$effect` instead of calling `onDestroy`.

## Routing

Client-side routing uses the browser's URL hash (`#`). No router library is needed.

`routerStore` exposes:

| Property / Method | Type | Description |
|-------------------|------|-------------|
| `hash` | `string` | Raw hash value (e.g. `"books"`) |
| `currentView` | `AppView` | Top-level view segment (`"dashboard"` \| `"books"` \| `"my-library"` \| `"libraries"` \| `"settings"`) |
| `subPath` | `string` | Sub-path after the first segment (e.g. `"account"`) |
| `queryParams` | `SvelteURLSearchParams` | Reactive map of query parameters embedded in the hash (e.g. `?offset=48`). Read with `.get(key)`. |
| `isKnownView` | `boolean` | `true` when `hash` matches a registered view; `false` for unknown routes (triggers the 404 page) |
| `pageTitle` | `string` | Human-readable page title for the current view (e.g. `"Dashboard – biblioteka"`); used to update `document.title` on every navigation |
| `navigate(path, params?)` | `void` | Sets the hash and optionally populates initial query parameters. `params` is a `Record<string, string>`. |
| `setQueryParam(key, value \| null)` | `void` | Updates a single query parameter in the hash via `history.replaceState` without pushing a history entry. Pass `null` to remove the key. |

**Navigating programmatically:**

```ts
import { routerStore } from "../stores/router.svelte";

// Navigate to a view
routerStore.navigate("settings/account");

// Navigate with initial query params
routerStore.navigate("books", { offset: "48" });
```

### 404 handling

When the URL hash does not match any registered view, `routerStore.isKnownView` is `false`. `App.svelte` checks this condition before the view switch and renders `NotFound.svelte` instead of silently falling back to the dashboard. The document title is set to `"Page Not Found – biblioteka"` in this case.

### URL-synced pagination

The `Books` view keeps its pagination offset in the URL hash query string so that the page survives a refresh and can be bookmarked or shared.

- Navigating directly to `#books?offset=48` opens the correct page immediately.
- Turning pages updates the URL in place via `routerStore.setQueryParam("offset", …)` without creating a browser history entry.
- Setting offset back to `0` removes the `offset` parameter from the URL entirely.

**Reading a query parameter:**

```ts
const raw = routerStore.queryParams.get("offset") ?? "0";
const offset = parseInt(raw, 10) || 0;
```

**Writing a query parameter on page change:**

```ts
function handlePageChange(offset: number) {
  routerStore.setQueryParam("offset", offset === 0 ? null : String(offset));
}
```

### Sub-path routing

Views that need their own internal navigation use `routerStore.subPath`. The convention is: `routerStore.hash` holds the normalized fragment without any leading `#/`, it is split on `/`, the first segment becomes the view (`currentView`), and the remaining segments (joined with `/`) form `subPath`, which each view component interprets as it needs.

| View | Sub-path pattern | Meaning |
|------|------------------|---------|
| `libraries` | *(empty)* | List / empty state |
| `libraries` | `new` | Create-library form |
| `libraries` | `setup` | First-library setup wizard (redirects away if libraries exist) |
| `libraries` | `{id}` | View a library's books |
| `libraries` | `edit/{id}` | Edit-library form |
| `reading-lists` | *(empty)* | List all reading lists + create form |
| `reading-lists` | `{id}` | Detail / edit / delete view for a single list |
| `groups` | *(empty)* | Group list + inline create form |
| `groups` | `new` | Opens the inline creation form |
| `groups` | `{id}` | Detail view for a specific group |
| `settings` | `account` | Account settings tab |
| `settings` | `oidc` | OIDC / SSO settings tab |
| `settings` | `smtp` | SMTP mail configuration tab (admin) |
| `settings` | `users` | User management tab (admin) |
| `settings` | `preferences` | Appearance preferences tab |
| `settings` | `api-keys` | API keys management tab (all users) |
| `settings` | `kobo` | Kobo sync token management tab (all users) |
| `settings` | `llm` | LLM provider configuration tab (admin) |
| `settings` | `watch-folder` | Watch folder configuration tab (admin) |
| `settings` | `calibre-import` | Calibre library import wizard tab (admin) |
| `settings` | `search-index` | Full-text search index rebuild tab (admin) |

**Example — navigating to a library's book list:**

```ts
// After creating a library, navigate to its detail view
routerStore.navigate(`libraries/${lib.id}`);

// Inside Libraries.svelte, derive the mode from subPath
let mode = $derived.by(() => {
  const sp = routerStore.subPath;
  if (sp === "new")              return "create";
  if (sp.startsWith("edit/"))   return "edit";
  if (sp === "setup")            return "setup";   // first-library wizard
  if (sp !== "")                return "view";   // {id} → show books
  return "empty";
});
```

When a view component renders, it reads `routerStore.subPath` as a `$derived` value so it re-renders reactively whenever navigation occurs — no lifecycle hook is needed for the navigation itself.

## API client

All HTTP calls go through `frontend/src/lib/api.ts`, which is a barrel re-export of domain-specific sub-modules under `frontend/src/lib/api/`. The barrel preserves all existing import paths so no call-site changes are required when the internal structure evolves.

### Module overview

| Sub-module | Contents |
|------------|----------|
| `api/core.ts` | Token storage (`setToken`, `clearToken`, `hasToken`, `getToken`), `ApiError`, the `request` and `requestFormData` helpers, `getVersion` |
| `api/auth.ts` | `signup`, `login`, `logout`, `getMe`, OIDC helpers, `changePassword` |
| `api/config.ts` | OIDC + SMTP server configuration |
| `api/admin.ts` | User management (`listUsers`, `setUserAdmin`) and audit logs (`getAuditLogs`) |
| `api/credentials.ts` | OPDS and KOSync credential operations |
| `api/libraries.ts` | Library CRUD + paginated book listing |
| `api/authors.ts` | Author CRUD + author–book relationships |
| `api/series.ts` | Series CRUD + series–book relationships |
| `api/books.ts` | Book CRUD, associations, and file management |
| `api/tokens.ts` | API key and Kobo token management |
| `api/reading-lists.ts` | Reading list CRUD, book membership, and per-book list lookup |
| `api/reading-progress.ts` | Reading progress statistics (streak, in-progress documents) |
| `api/annotations.ts` | Book annotation CRUD (`listBookAnnotations`, `createAnnotation`, `updateAnnotation`, `deleteAnnotation`) |
| `api/calibre.ts` | Calibre `metadata.db` import — file-upload (`previewCalibreImport`, `confirmCalibreImport`) and server-path (`previewCalibreImportFromPath`, `confirmCalibreImportFromPath`) variants |
| `api/groups.ts` | Reading group CRUD, member management, shared-list operations, and per-member progress |
| `api/metadata.ts` | Goodreads metadata fetch/apply/reject (`fetchMetadata`, `getMetadata`, `applyMetadata`, `rejectMetadata`) and AI enrichment fetch/apply/reject (`fetchAIEnrichment`, `getPendingAIEnrichment`, `applyAIEnrichment`, `rejectAIEnrichment`); also exposes `subscribeToMetadataEvents` to open the SSE progress stream |
| `api/passkeys.ts` | WebAuthn passkey registration and login flows (`beginPasskeyRegistration`, `finishPasskeyRegistration`, `beginPasskeyLogin`, `finishPasskeyLogin`), credential list/delete, and base64url ↔ `ArrayBuffer` conversion helpers used by the browser WebAuthn API |
| `api/recommendations.ts` | `getRecommendations(limit, signal)` — scored book suggestions ranked by author overlap, series continuation, publisher match, and download popularity |
| `api/stats.ts` | `getDownloadsPerMonth(months)` and `getYearInBooks(year)` — per-user download histogram and annual reading statistics |
| `api/tags.ts` | Tag CRUD (`listTags`, `getTag`, `createTag`, `updateTag`, `deleteTag`) |
| `api/pagination.ts` | `listEntityBooks(entityPath, limit, offset)` — shared paginated-book helper used by author and series sub-resource views |

Each sub-module imports `request` (and `setToken` where needed) from `./core`; there are no circular dependencies.

### Core module

`api/core.ts` contains the building blocks used by all other sub-modules:

- **Token storage** — Stores the JWT in an in-memory module variable (not `localStorage`) to prevent XSS from leaking credentials. The server sets an `HttpOnly` cookie (`biblioteka_token`) for session persistence across page reloads. Use `setToken`, `clearToken`, `hasToken`, and `getToken` to manage the in-memory token.
- **`ApiError`** — A typed subclass of `Error` that carries a numeric `status` field (the HTTP status code). Catch `ApiError` when you need to branch on a specific status code.
- **`request<T>`** — The shared fetch wrapper. It attaches the `Authorization: Bearer` header when a token is stored and throws `ApiError` on any non-2xx response.
- **`getVersion`** — Fetches the server version from `GET /api/version`.

### Usage

Import from the barrel (`../lib/api`) — not from the individual sub-modules — so that call sites do not depend on the internal file layout:

```ts
// Example usage inside a store method
import * as api from "../lib/api";

const book = await api.createBook({ title: "Dune", … });
```

Never call `fetch` directly from components or stores — always go through the API modules.

### `ApiError` handling

```ts
import { ApiError, login } from "../lib/api";

try {
  await login(email, password);
} catch (err) {
  if (err instanceof ApiError && err.status === 401) {
    // handle wrong credentials
  } else {
    throw err;
  }
}
```

## Utility modules

Several utility modules live in `frontend/src/lib/` alongside `api.ts`.

### `validation.ts`

Composable form-validation helpers. Each exported function returns a `ValidationRule` — a function `(value: string) => string | null` that returns an error message or `null` when the value passes.

| Export | Signature | Description |
|--------|-----------|-------------|
| `ValidationRule` | `type` | A validation rule function |
| `required` | `(message?: string) => ValidationRule` | Fails when the trimmed value is empty |
| `minLength` | `(min: number, message?: string) => ValidationRule` | Fails when the value is shorter than `min` characters |
| `matches` | `(other: string, message?: string) => ValidationRule` | Fails when the value does not equal `other` |
| `validate` | `(value: string, rules: ValidationRule[]) => string \| null` | Runs rules in order; returns the first error or `null` |

**Usage:**

```ts
import { validate, required, minLength, matches } from "../lib/validation";

const passwordError = validate(password, [
  required("Password is required"),
  minLength(8, "Password must be at least 8 characters"),
]);

const confirmError = validate(confirm, [
  required("Please confirm your password"),
  matches(password, "Passwords do not match"),
]);
```

Store the result in a `$state` variable and bind it to a `TextInput` with `aria-invalid` and `aria-describedby` to surface inline errors accessibly (see [Form accessibility](#form-accessibility)).

### `clipboard.ts`

`frontend/src/lib/clipboard.ts` exports a single async function, `copyToClipboard`, that provides a cross-browser interface for writing text to the system clipboard.

```ts
import { copyToClipboard } from "../lib/clipboard";

await copyToClipboard(apiKey);
```

`copyToClipboard` uses the modern async Clipboard API (`navigator.clipboard.writeText`) when available. In environments where the Clipboard API is absent, it falls back to `document.execCommand('copy')` using a hidden `<textarea>`.

> **Note:** The fallback is selected by *availability*, not by failure. If the Clipboard API is present but the browser rejects it (e.g. due to a missing `clipboard-write` permission), the error propagates immediately — the `execCommand` path is not attempted in that case.

It throws an `Error` if the active path fails:
- The Clipboard API rejects (e.g. the user denied the `clipboard-write` permission).
- The `execCommand` fallback returns `false` (the browser blocked the copy command).

> **Guidance:** Always surface copy failures to the user — for example, by displaying an error banner. Do not silently swallow the thrown error.

Use `copyToClipboard` whenever a component needs to copy text (tokens, sync URLs, share links, etc.) to the clipboard. Do **not** inline `navigator.clipboard.writeText` calls in components, as the fallback path would not be covered.

### `autoDismissTimer.svelte.ts`

`frontend/src/lib/autoDismissTimer.svelte.ts` exports `AutoDismissTimer`, a Svelte 5 class that extends `TimeoutState<boolean>` and tracks whether a transient message (success, error, or informational) should be visible and automatically hides it after a configurable duration.

**Constructor:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `duration` | `number` | `3000` | Time in milliseconds before `visible` auto-resets to `false` |

**Reactive public fields:**

| Field | Type | Description |
|-------|------|-------------|
| `visible` | `boolean` | `true` while the message should be displayed; `false` otherwise |

**Methods:**

| Method | Description |
|--------|-------------|
| `show()` | Sets `visible` to `true`, cancels any running timer, and starts a new auto-reset timer |
| `clear()` | Cancels the pending timer and sets `visible` to `false` immediately |

Call `clear()` from the `$effect` cleanup return function to prevent timer leaks when the component unmounts before the timeout fires.

**Usage:**

```svelte
<script lang="ts">
  import { AutoDismissTimer } from "../lib/autoDismissTimer.svelte";

  const successTimer = new AutoDismissTimer(); // auto-hides after 3 s

  $effect(() => {
    return () => successTimer.clear();
  });

  async function handleSave() {
    await saveSettings();
    successTimer.show();
  }
</script>

<button onclick={() => void handleSave()}>Save</button>

{#if successTimer.visible}
  <p role="status">Settings saved.</p>
{/if}
```

Use `AutoDismissTimer` whenever a component shows a transient success or informational message that should disappear automatically. Avoid inlining `setTimeout` calls in components for this pattern, because they are easy to duplicate and easy to forget to clean up; prefer `AutoDismissTimer` for consistency and safe cancellation via `clear()`.

### `tokenList.svelte.ts`

`frontend/src/lib/tokenList.svelte.ts` exports the generic `TokenListState<T extends { id: string }>` class, which manages the load/delete lifecycle for lists of token-like resources (API keys, Kobo tokens, etc.). It encapsulates loading state, inline delete-confirmation flow, and error state using Svelte 5 `$state` runes. The type parameter must include an `id: string` field, because the class uses `item.id` to identify and remove deleted entries from the in-memory list.

**`TokenListOps<T extends { id: string }>` interface** — passed to the constructor:

| Field | Type | Description |
|-------|------|-------------|
| `load` | `() => Promise<T[]>` | Fetches the full list of items; each item must have an `id: string` field |
| `delete` | `(id: string) => Promise<void>` | Deletes the item with the given ID |
| `loadError` | `string` | Fallback error message shown when `load` rejects without an `Error` object |
| `deleteError` | `string` | Fallback error message shown when `delete` rejects without an `Error` object |

**Reactive public fields:**

| Field | Type | Description |
|-------|------|-------------|
| `items` | `T[]` | The loaded list; replaced wholesale on each `load` call and filtered after a successful delete |
| `loading` | `boolean` | `true` while `load()` is in progress |
| `error` | `string \| null` | Load or delete error message; `null` when no error is present |
| `pendingDelete` | `{ id: string; name: string } \| null` | The item currently awaiting confirmation; `null` when no delete is in progress |
| `copy` | `CopyTimeoutState` | Integrated copy-to-clipboard feedback state; use `tokenList.copy.set(id)` after a clipboard write, check `tokenList.copy.copiedId` to drive per-row "Copied!" feedback, and call `tokenList.copy.clear()` from the `$effect` cleanup function |

**Methods:**

| Method | Description |
|--------|-------------|
| `load()` | Fetches items; sets `loading = true` and clears `error` before the call |
| `handleDelete(id, name)` | Begins the confirmation flow by setting `pendingDelete` |
| `cancelDelete(onAfterClear?)` | Clears `pendingDelete`, waits for a DOM tick, then calls the optional `onAfterClear` callback |
| `cancelDeleteWithFocus()` | Clears `pendingDelete` and returns keyboard focus to the trigger button (`[data-delete-trigger="${id}"]`) |
| `confirmDelete()` | Clears `pendingDelete` immediately (closes the dialog), then calls `ops.delete`; on success removes the item from `items`, on failure sets `error` |

Components that render a delete confirmation dialog should add `data-delete-trigger="${item.id}"` to the Delete button so that `cancelDeleteWithFocus` can restore focus when the user dismisses the dialog.

**Usage:**

```svelte
<script lang="ts">
  import { TokenListState } from "../lib/tokenList.svelte";
  import { listAPIKeys, deleteAPIKey } from "../lib/api";
  import { copyToClipboard } from "../lib/clipboard";
  import type { APIKey } from "../types";

  const tokenList = new TokenListState<APIKey>({
    load: listAPIKeys,
    delete: deleteAPIKey,
    loadError: "Failed to load API keys",
    deleteError: "Failed to delete API key",
  });

  $effect(() => {
    void tokenList.load();
    // Clear copy timers when the component unmounts to prevent leaks
    return () => {
      tokenList.copy.clear();
    };
  });

  async function handleCopy(id: string, value: string) {
    try {
      await copyToClipboard(value);
      tokenList.copy.set(id);
    } catch (err) {
      tokenList.error =
        err instanceof Error ? err.message : "Failed to copy to clipboard";
    }
  }
</script>

{#if tokenList.error}
  <AlertBanner variant="error">{tokenList.error}</AlertBanner>
{/if}

{#each tokenList.items as key}
  <button onclick={() => void handleCopy(key.id, key.key_prefix)}>
    {tokenList.copy.copiedId === key.id ? "Copied!" : "Copy"}
  </button>
  <button
    data-delete-trigger={key.id}
    onclick={() => tokenList.handleDelete(key.id, key.name)}
  >
    Delete
  </button>
{/each}

{#if tokenList.pendingDelete}
  <div
    role="alertdialog"
    aria-modal="true"
    aria-labelledby={`delete-api-key-title-${tokenList.pendingDelete.id}`}
    tabindex="-1"
    onkeydown={(event) =>
      event.key === "Escape" && tokenList.cancelDeleteWithFocus()}
  >
    <p id={`delete-api-key-title-${tokenList.pendingDelete.id}`}>
      Delete "{tokenList.pendingDelete.name}"?
    </p>
    <button autofocus onclick={() => tokenList.cancelDeleteWithFocus()}>Cancel</button>
    <button onclick={() => tokenList.confirmDelete()}>Confirm</button>
  </div>
{/if}
```

Use `TokenListState` whenever a settings tab manages a list of user-owned tokens. Do **not** re-implement the load/delete/confirmation flow inline in components. The `copy` field is already composed in — there is no need to create a separate `CopyTimeoutState` for per-row clipboard feedback.

### `copyTimeout.svelte.ts`

`frontend/src/lib/copyTimeout.svelte.ts` exports `CopyTimeoutState`, a class that extends `TimeoutState<string | null>` and manages the "copied" UI feedback state — tracking which item was most recently copied to the clipboard and automatically clearing that state after a configurable duration.

**Constructor:**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `duration` | `number` | `2000` | Time in milliseconds before `copiedId` auto-resets to `null` |

**Reactive public fields:**

| Field | Type | Description |
|-------|------|-------------|
| `copiedId` | `string \| null` | ID of the most recently copied item; `null` when no copy feedback is active |

**Methods:**

| Method | Description |
|--------|-------------|
| `set(id)` | Marks `id` as copied, cancels any running timer, and starts a new auto-reset timer |
| `clear()` | Cancels the pending timer and resets `copiedId` to `null` immediately |

Call `clear()` from the `$effect` cleanup return function to prevent timer leaks when the component unmounts before the timeout fires.

**Usage:**

```svelte
<script lang="ts">
  import { CopyTimeoutState } from "../lib/copyTimeout.svelte";
  import { copyToClipboard } from "../lib/clipboard";

  const copyState = new CopyTimeoutState(); // auto-resets after 2 s
  let copyError: string | null = $state(null);

  $effect(() => {
    return () => copyState.clear();
  });

  async function handleCopy(id: string, value: string) {
    try {
      copyError = null;
      await copyToClipboard(value);
      copyState.set(id);
    } catch {
      copyError = "Could not copy to clipboard. Please try again.";
    }
  }
</script>

{#if copyError}
  <p role="alert" class="text-sm text-red-600">{copyError}</p>
{/if}

{#each items as item}
  <button onclick={() => { void handleCopy(item.id, item.token); }}>
    {copyState.copiedId === item.id ? "Copied!" : "Copy"}
  </button>
{/each}
```

Use `CopyTimeoutState` whenever a component shows per-item "Copied!" feedback after a clipboard write. Do **not** manage copy timers inline with `setTimeout` in components.

### `timeoutState.svelte.ts`

`frontend/src/lib/timeoutState.svelte.ts` exports `TimeoutState<T>`, the shared base class for `AutoDismissTimer` and `CopyTimeoutState`. It manages a protected reactive `value` that reverts to an `idleValue` after a configurable `duration`. Subclasses expose domain-specific public getters and trigger methods on top of this shared timer infrastructure.

**Constructor:**

| Parameter | Type | Description |
|-----------|------|-------------|
| `idleValue` | `T` | The value `value` reverts to after the timeout fires or `clear()` is called |
| `duration` | `number` | Time in milliseconds before `value` resets to `idleValue` |

**Protected API (for subclasses):**

| Member | Description |
|--------|-------------|
| `value` | The reactive `$state` field; exposed as a domain-specific public getter in each subclass |
| `activate(activeValue)` | Sets `value` to `activeValue`, cancels any running timer, and starts a new auto-reset timer |

**Public API:**

| Method | Description |
|--------|-------------|
| `clear()` | Cancels any pending timeout and resets `value` to `idleValue` immediately |

Call `clear()` from the `$effect` cleanup return function to prevent timer leaks. Both `AutoDismissTimer` and `CopyTimeoutState` inherit this method — components using either class call the same `clear()` API.

Do **not** use `TimeoutState` directly in components. Extend it in a new subclass when you need auto-resetting reactive state with a different `T`. For boolean visibility (`true`/`false`) use `AutoDismissTimer`; for string-or-null item tracking use `CopyTimeoutState`.

## TypeScript types

Shared TypeScript interfaces for API entities live in `frontend/src/types/`, organized into domain-scoped modules:

| Module | Domain |
|--------|--------|
| `annotation.ts` | Book annotation types |
| `audit.ts` | Audit log types |
| `auth.ts` | User, auth response, and API key types |
| `book.ts` | `Book`, `BookFile`, `BookSummary`, and related book types |
| `calibre.ts` | Calibre import preview types |
| `config.ts` | Server configuration types (`ConfigStatus`, `OIDCConfig`, SMTP, LLM) |
| `library.ts` | `Library` type and `LIBRARY_ORGANIZATION_TYPES` constants |
| `metadata.ts` | AI enrichment and metadata-fetch types |
| `reading.ts` | Reading progress, reading list, and reading group types |
| `index.ts` | Barrel re-export — `export * from` every module above |

All public types are re-exported through `frontend/src/types/index.ts`, so every component, store, and API module imports from the same path:

```ts
import type { BookSummary, Library, ReadingList } from "../types";
```

Individual sub-modules under `frontend/src/lib/api/` may still define small module-local helper types for their own internal use.

Never inline types directly in `.svelte` component files or `*.svelte.ts` store files. Add any new shared or reusable type to the appropriate domain module under `frontend/src/types/`.

**Reading list types:**

```ts
interface ReadingList {
  id: string;
  name: string;
  description: string | null;
  book_count: number;
  created_at: string;
  updated_at: string;
}

interface ReadingListInput {
  name: string;
  description?: string | null;
}
```

**Reading progress types:**

```ts
interface ReadingProgressItem {
  document: string;
  percentage: number;
  device?: string | null;
  last_synced: string;
  estimated_minutes_remaining?: number | null;
}

interface ReadingProgressStats {
  current_streak: number;
  total_tracked: number;
  total_finished: number;
  in_progress: ReadingProgressItem[];
}
```

### Nullable optional fields in input types

Input interfaces (e.g. `AuthorInput`, `SeriesInput`, `BookInput`, `BookFileInput`) use `?: string | null` for optional nullable fields, mirroring their counterpart response types. The current PUT update handlers decode both key-omission and explicit `null` into a nil `*string`, which writes `NULL` to the database column — there is no distinction between "leave unchanged" and "clear this field":

```ts
// Both of these result in goodreads_id being set to NULL in the database:
const input: AuthorInput = { name: "Ursula K. Le Guin" };                       // key omitted
const input: AuthorInput = { name: "Ursula K. Le Guin", goodreads_id: null };    // explicit null
```

> **Note:** The `?: string | null` typing mirrors the response type's nullability and keeps the door open for future PATCH-style handling where `undefined` ("no-op") would be distinguishable from `null` ("clear"). That distinction would require changes to the Go backend (e.g., a custom JSON unmarshaler or a wrapper type). Until then, omission and `null` behave identically.

When adding a new input interface, always match the nullability of the corresponding response interface — if the response field is `string | null`, the input field should be `?: string | null`.

## Adding a new API function

1. Identify the right sub-module in `frontend/src/lib/api/`. Use the module overview table above as your guide (e.g., a new book endpoint goes in `books.ts`; a new auth endpoint goes in `auth.ts`).
2. Add the exported function to that sub-module. Import `request` from `./core`:

   ```ts
   // frontend/src/lib/api/books.ts
   import { request } from "./core";

   export async function archiveBook(id: string): Promise<void> {
     await request<void>("POST", `/api/books/${id}/archive`);
   }
   ```

3. The barrel (`api.ts`) already re-exports every symbol from every sub-module via `export * from "./api/<module>"`, so the new function is immediately available to all existing import sites — **no changes to `api.ts` are needed**.
4. Add a test in `frontend/src/lib/api.test.ts` covering the new function.

> **Do not add new functions directly to `api.ts`** — that file is a barrel only. Adding logic there breaks the modular structure.

## Adding a new store

1. Create `frontend/src/stores/<name>.svelte.ts`.
2. Define a class with `$state` / `$state.raw` properties. Use `$state.raw` for array properties and `$state` for scalars and nullable objects (see the [`$state` vs `$state.raw`](#reactive-stores) note above).
3. If the store fetches data from the API, implement `load()` with the idempotency guard: `if (this.loading || this.loaded) return;`. This ensures that calling `load()` from multiple `$effect` blocks never issues a duplicate request.
4. Export a singleton: `export const myStore = new MyStore();`.
5. Add an entry for the new store in the table above.

## Adding a new view

1. Create `frontend/src/components/MyView.svelte`.
2. Add the new route identifier to the `AppView` union type in `router.svelte.ts`.
3. Add the route to the `valid` array in `RouterStore.currentView`.
4. Import and render `<MyView />` in `App.svelte` inside the `{#if … }` routing block.
5. Add a navigation entry in `Sidebar.svelte`.

## UI components

The reusable components in `frontend/src/components/ui/` are shared across multiple page-level components. They accept only typed props — no global store access — and are safe to use in any context.

### `AlertBanner.svelte`

Displays a dismissible inline alert in either an error or success style.

**Props:**

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `variant` | `"error" \| "success"` | ✓ | — | Visual style and implicit ARIA role |
| `children` | `Snippet` | ✓ | — | Content rendered inside the banner |
| `role` | `string` | | `"alert"` for errors, `"status"` for success | Overrides the implicit ARIA role |
| `testId` | `string` | | — | Sets `data-testid` for test selection |
| `class` | `string` | | — | Additional Tailwind classes appended to the wrapper |

**Usage:**

```svelte
<script lang="ts">
  import AlertBanner from "./ui/AlertBanner.svelte";
  let errorMessage = $state<string | null>(null);
</script>

{#if errorMessage}
  <AlertBanner variant="error">{errorMessage}</AlertBanner>
{/if}
```

The `variant` value controls both the colour scheme and the default ARIA `role`: `"error"` maps to `role="alert"` (announces immediately in screen readers) and `"success"` maps to `role="status"` (polite announcement). Override with the `role` prop when the default is not appropriate.

---

### `Button.svelte`

A styled button with three visual variants and two size options. Renders as `inline-flex items-center justify-center` with built-in padding and text size controlled by the `size` prop.

**Props:**

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `variant` | `"primary" \| "secondary" \| "danger"` | | `"primary"` | Visual style |
| `size` | `"sm" \| "md"` | | `"md"` | Button size; controls padding and text size |
| `type` | `"button" \| "submit" \| "reset"` | | `"button"` | HTML button type |
| `disabled` | `boolean` | | `false` | Disables the button and applies reduced-opacity styling |
| `class` | `string` | | — | Additional Tailwind classes appended to the button (e.g. `w-full`, `gap-2`) |
| `onclick` | `(e: MouseEvent) => void` | | — | Click handler |
| `children` | `Snippet` | ✓ | — | Button label content |

**Sizes:**

| Size | Padding | Text size | When to use |
|------|---------|-----------|-------------|
| `md` (default) | `px-4 py-2.5` | `text-sm` | Standard form submit buttons, primary actions |
| `sm` | `px-3 py-1.5` | `text-xs` | Compact inline actions, toolbar buttons |

**Usage:**

```svelte
<script lang="ts">
  import Button from "./ui/Button.svelte";
</script>

<Button variant="primary" type="submit">Save</Button>
<Button variant="secondary" onclick={cancel}>Cancel</Button>
<Button variant="danger" onclick={deleteItem}>Delete</Button>
<Button size="sm" variant="secondary" onclick={dismiss}>Dismiss</Button>
```

---

### `DownloadsHistogram.svelte`

A pure-CSS bar-chart component that renders monthly download counts fetched from `GET /api/stats/downloads-per-month`. Used by `Dashboard.svelte` to display the authenticated user's download history.

**Props:**

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `data` | `MonthlyDownloads[]` | ✓ | — | Array of `{ month: "YYYY-MM", count: number }` objects ordered oldest-first |
| `title` | `string` | | `"Downloads per month"` | Label rendered as an `<h3>` above the chart and used as the caption for the screen-reader-only data table |

**Accessibility:**

- The visual chart container is `aria-hidden="true"` so assistive technologies do not read duplicate chart markup.
- A screen-reader-only `<table>` exposes the same data semantically with a caption (`title`), `Month` column, and `Downloads` column.
- A count tooltip (`aria-hidden="true"`) appears above each bar on hover — decorative only.
- When all counts are zero, an empty-state `<p>` with `aria-live="polite"` is shown instead of the chart.

**Usage:**

```svelte
<script lang="ts">
  import DownloadsHistogram from "./ui/DownloadsHistogram.svelte";
  import { getDownloadsPerMonth } from "../lib/api";
  import type { MonthlyDownloads } from "../types";

  let data = $state<MonthlyDownloads[]>([]);
  $effect(() => {
    getDownloadsPerMonth(12)
      .then((d) => (data = d))
      .catch((err) => {
        console.error("Failed to fetch download stats:", err);
      });
  });
</script>

{#if data.length > 0}
  <DownloadsHistogram {data} title="Downloads per month" />
{/if}
```

---

### `TextInput.svelte`

A styled text input with focus ring, dark-mode support, disabled styling, and ARIA attribute forwarding. In dark mode, placeholder text uses `dark:placeholder:text-ink-300` to maintain sufficient contrast against the dark background (WCAG 1.4.3 Contrast Minimum, Level AA). Form control borders use `border-ink-400 dark:border-ink-400` to meet the WCAG 1.4.11 Non-text Contrast minimum of 3:1. When `aria-invalid="true"` is present, the input applies `aria-invalid:border-danger-500` and danger-colored focus styles to provide a visible error cue for sighted users while preserving the ARIA semantics. The active state class string uses `focus-visible:outline-none` (not `outline-none`) to suppress the browser's default outline when `:focus-visible` matches (keyboard-initiated focus), so the component's explicit `focus:ring-*` accent ring is the sole visible indicator — avoiding a double ring while still meeting WCAG 2.4.7 Focus Visible (Level AA).

**Props:**

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `string` | | `""` | Bindable input value (`$bindable()`). Supports both `bind:value` and controlled (`value` + `oninput`) patterns. |
| `type` | `"text" \| "email" \| "password" \| "url"` | | `"text"` | Input type — only these four HTML input types are accepted |
| `disabled` | `boolean` | | `false` | Disables the input with muted colors and `cursor-not-allowed` |
| `class` | `string` | | — | Additional Tailwind classes |
| `...restProps` | `HTMLInputAttributes` | | — | Any standard `<input>` attributes (`aria-required`, `aria-invalid`, `aria-describedby`, `placeholder`, `maxlength`, etc.) are forwarded to the underlying element |

**Usage — bind pattern:**

```svelte
<script lang="ts">
  import TextInput from "./ui/TextInput.svelte";
  let name = $state("");
</script>

<TextInput bind:value={name} placeholder="Enter name" aria-required="true" />
```

**Usage — controlled pattern:**

```svelte
<TextInput
  value={name}
  oninput={(e) => (name = e.currentTarget.value)}
  aria-invalid={name.length === 0}
/>
```

---

### `BookCard.svelte`

Renders a single book as a card tile: cover art if available, falling back to a placeholder icon, with the title and publisher below.

**Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `book` | `BookSummary` | ✓ | The book object to display (imported from `src/types`) |

**Usage:**

```svelte
<script lang="ts">
  import BookCard from "./ui/BookCard.svelte";
  import type { BookSummary } from "../types";

  let book: BookSummary = …;
</script>

<BookCard {book} />
```

`BookCard` is a pure display component — it emits no events and holds no internal state. Use it inside a grid or list layout; `BookList` composes `BookCard` internally.

---

### `BookList.svelte`

A self-contained paginated book browser. It fetches a page of books via a caller-supplied callback, then renders them as either a grid of `BookCard` tiles or a compact table. Navigation between pages is handled internally.

**Props:**

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `fetchBooks` | `(limit: number, offset: number, query?: string) => Promise<PaginatedBooks>` | ✓ | — | Called whenever the page, page size, or search query changes. Use `api.listBooks` or wrap `api.listLibraryBooks` in an arrow function. The optional `query` argument is forwarded from the `query` prop. |
| `query` | `string` | | — | Optional search query forwarded as the third argument to `fetchBooks` on every load. Changing this prop resets `offset` to `0` automatically. |
| `pageSize` | `number` | | `24` | Number of books per page. Clamped to `[1, 200]` at runtime. |
| `initialOffset` | `number` | | `0` | Starting page offset read **once** on mount. Use this to restore a bookmarked page (e.g., from the URL query string). Changes after mount are ignored. |
| `onPageChange` | `(offset: number) => void` | | — | Called after each page turn (not on the initial mount). Use this to write the new offset back to the URL via `routerStore.setQueryParam`. |
| `pollingInterval` | `number` | | — | When set, `BookList` re-fetches silently at this interval (in ms) while `total === 0`. Polling stops automatically once books appear. Use this to show a "Scanning library..." spinner while the backend scans a newly added library. |
| `onBooksFound` | `() => void` | | — | Called exactly once the first time a poll or fetch reports `total > 0`. Use this to clear scanning state in the parent (e.g., `() => libraryStore.clearScanning(libraryId)`). |

**Internal state exposed to the template (not props):**

| Name | Type | Description |
|------|------|-------------|
| `books` | `BookSummary[]` | Current page of book objects |
| `total` | `number` | Total books across all pages (from the API) |
| `loading` | `boolean` | `true` while a fetch is in flight |
| `error` | `string \| null` | Error message from the most recent failed fetch |
| `viewMode` | `"grid" \| "table"` | User-selected display mode; toggle buttons are rendered by the component |

**Usage — all books with search:**

```svelte
<script lang="ts">
  import BookList from "./ui/BookList.svelte";
  import * as api from "../lib/api";

  let raw = $state("");
  let query = $state("");

  // Debounce search input to avoid excessive API calls (see Books.svelte for the production pattern)
  $effect(() => {
    const timeout = window.setTimeout(() => {
      query = raw;
    }, 300);

    return () => window.clearTimeout(timeout);
  });
</script>

<input bind:value={raw} placeholder="Search books…" />
<BookList fetchBooks={api.listBooks} {query} />
```

**Usage — all books (no search):**

```svelte
<script lang="ts">
  import BookList from "./ui/BookList.svelte";
  import * as api from "../lib/api";
</script>

<BookList fetchBooks={api.listBooks} />
```

**Usage — books within a specific library:**

```svelte
<script lang="ts">
  import BookList from "../ui/BookList.svelte";
  import * as api from "../../lib/api";

  let { libraryId }: { libraryId: string } = $props();
</script>

<BookList fetchBooks={(limit, offset) => api.listLibraryBooks(libraryId, limit, offset)} />
```

> **Tip:** When binding a library-scoped `fetchBooks`, wrap `api.listLibraryBooks` in an arrow function so that `libraryId` is captured by the closure. `BookList` resets to page 1 whenever the `fetchBooks` prop reference changes, so switching libraries automatically resets pagination.

#### Pagination behaviour

- On mount and whenever `fetchBooks`, `pageSize`, or `query` changes, `offset` resets to `0` and a fresh fetch is triggered.
- If items are deleted and the current page becomes empty (but earlier pages still have items), `BookList` automatically clamps back to the last valid page.
- Stale responses from superseded fetches are silently discarded via an internal request-ID counter.

#### Scan-aware polling

When `pollingInterval` is set and `total === 0`, `BookList` enters a polling mode: instead of showing the generic "No books yet." empty state, it renders a spinner with the message "Scanning library...". A `setTimeout`-based loop (not `setInterval`) re-fetches silently at the given interval, suppressing the loading overlay so the spinner stays visible. Polling stops as soon as `total > 0` or the component unmounts. On the first fetch that reports `total > 0`, `onBooksFound` fires exactly once, giving the parent an opportunity to clear scanning state (see `libraryStore.clearScanning` below).

```svelte
<script lang="ts">
  import BookList from "../ui/BookList.svelte";
  import * as api from "../../lib/api";
  import { libraryStore } from "../../stores/libraries.svelte";

  let { libraryId }: { libraryId: string } = $props();

  let scanning = $derived(libraryStore.scanningIds.has(libraryId));
</script>

<BookList
  fetchBooks={(limit, offset) => api.listLibraryBooks(libraryId, limit, offset)}
  pollingInterval={scanning ? 3000 : undefined}
  onBooksFound={scanning ? () => libraryStore.clearScanning(libraryId) : undefined}
/>
```

> **Note:** `BookList` cannot identify *which* library finished scanning, so when embedding the all-books view (`Books.svelte`) alongside a scan in progress, pass `pollingInterval` derived from `libraryStore.isScanning` but **omit** `onBooksFound` — the aggregate view cannot safely call `clearScanning` without knowing the specific library ID. Polling stops naturally once `total > 0`.

#### Table view keyboard navigation

**WCAG criterion:** [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html) (Level A)

In table view, navigation is provided by a native title link (`<a>`) in the first cell. The row (`<tr>`) is not turned into a custom interactive control.

`BookList.svelte` follows this pattern:

- Keep `<tr>` semantic-only (no `onclick`, `onkeydown`, `tabindex`, or `aria-label`).
- Keep the title `<a href="#books/{id}">` in the natural tab order (no `tabindex="-1"`).
- Style the link for discoverability (`hover:underline`, focus ring classes) while preserving native link behavior (Tab focus, link shortcuts, open-in-new-tab behavior).

This preserves table semantics while ensuring keyboard and assistive-technology users interact with a real link, not a simulated row-level control.

```svelte
<tr class="...">
  <td>
    <a href={`#books/${book.id}`} class="... hover:underline focus:ring-2 ...">
      {book.title}
    </a>
  </td>
  <!-- other cells -->
</tr>
```

> **Rule:** In data tables, keep navigation on native links inside cells. Do not make `<tr>` elements keyboard-focusable controls.

---

### `Button.svelte`

A styled button with three visual variants and two size options. Use this instead of a raw `<button>` element whenever a button appears in the application UI, so styling is consistent. The component renders as `inline-flex items-center justify-center` — callers do not need to add flex or padding classes for standard use.

**Props:**

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `variant` | `"primary" \| "secondary" \| "danger"` | | `"primary"` | Visual style |
| `size` | `"sm" \| "md"` | | `"md"` | Button size; controls padding and text size |
| `type` | `"button" \| "submit" \| "reset"` | | `"button"` | HTML button type |
| `disabled` | `boolean` | | `false` | Disables the button and applies reduced-opacity styling |
| `class` | `string` | | — | Additional Tailwind classes appended to the button (e.g. `w-full`, `gap-2`, `flex-1`) |
| `onclick` | `(e: MouseEvent) => void` | | — | Click handler |
| `children` | `Snippet` | ✓ | — | Button label rendered as slot content |

**Variants:**

| Variant | When to use |
|---------|-------------|
| `primary` | Primary call-to-action; accent-colored gradient background |
| `secondary` | Secondary action; transparent background with a subtle border |
| `danger` | Destructive actions such as delete or revoke; red background |

**Sizes:**

| Size | Padding | Text size | When to use |
|------|---------|-----------|-------------|
| `md` (default) | `px-4 py-2.5` | `text-sm` | Standard form submit buttons, primary actions |
| `sm` | `px-3 py-1.5` | `text-xs` | Compact inline actions, toolbar buttons, side-by-side button pairs |

**Usage:**

```svelte
<script lang="ts">
  import Button from "./ui/Button.svelte";

  function handleSave() { … }
  function handleCancel() { … }
  function handleDelete() { … }
</script>

<Button onclick={handleSave}>Save</Button>
<Button variant="secondary" onclick={handleCancel}>Cancel</Button>
<Button variant="danger" onclick={handleDelete}>Delete</Button>

<!-- Small size for compact contexts -->
<Button size="sm" variant="secondary" onclick={handleCancel}>Dismiss</Button>
```

When adding an icon alongside the button label, pass `class="gap-2"` to space the icon and text:

```svelte
<Button class="gap-2"><SaveIcon aria-hidden="true" />Save changes</Button>
```

---

### `DeleteConfirmation.svelte`

An accessible inline delete-confirmation dialog that replaces the current item's Delete button with a two-button (`Delete` / `Cancel`) confirmation row. Use this whenever a destructive action requires a user confirmation step. It implements the full accessible pattern — `role="alertdialog"`, autofocus on open, and Escape-to-dismiss — so consumers do not need to repeat any of that boilerplate.

**Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `itemId` | `string` | ✓ | Unique ID of the item being deleted. Used to generate a stable `aria-labelledby` value. |
| `itemName` | `string` | ✓ | Human-readable name shown in the `"Delete "{itemName}"?"` label. |
| `onConfirm` | `() => void` | ✓ | Called when the user clicks **Delete**. |
| `onCancel` | `() => void` | ✓ | Called when the user clicks **Cancel** or presses Escape. Should restore focus to the original trigger button. |
| `class` | `string` | | Additional Tailwind classes appended to the wrapper. |

**Behavior:**

- Renders a `role="alertdialog"` container (not `role="dialog"`) so screen readers announce its content immediately.
- Uses `use:autofocusFirstButton` to move keyboard focus into the dialog when it mounts.
- An `onkeydown` Escape handler calls `onCancel` to dismiss the dialog.

**Usage:**

```svelte
<script lang="ts">
  import { tick } from "svelte";
  import DeleteConfirmation from "./ui/DeleteConfirmation.svelte";

  // These come from your component's props or local state:
  const itemId = "item-123";
  const item = { name: "Example item" };
  const api = {
    async deleteItem(id: string) { /* your delete logic */ }
  };

  let showDeleteConfirm = $state(false);
  let deleteButtonEl: HTMLButtonElement | null = $state(null);

  async function handleDelete() {
    await api.deleteItem(itemId);
    showDeleteConfirm = false;
  }

  async function cancelDelete() {
    showDeleteConfirm = false;
    await tick(); // wait for Svelte to re-mount the trigger button
    deleteButtonEl?.focus(); // restore focus to the trigger
  }
</script>

{#if showDeleteConfirm}
  <DeleteConfirmation
    {itemId}
    itemName={item.name}
    onConfirm={handleDelete}
    onCancel={cancelDelete}
  />
{:else}
  <button
    bind:this={deleteButtonEl}
    data-delete-trigger={itemId}
    onclick={() => (showDeleteConfirm = true)}
  >Delete</button>
{/if}
```

`LibraryForm.svelte`, `APIKeysTab.svelte`, and `KoboTab.svelte` are canonical reference implementations.

---

### `DownloadsHistogram.svelte`

A bar chart that visualises monthly download counts for a book or the library. Each bar is sized proportionally to the highest count in the dataset. An empty-state message is shown when all counts are zero. The visual bars are marked `aria-hidden`, and the same data is exposed to assistive technology through a screen-reader-only table so the chart remains usable without a pointing device or visual display.

**Props:**

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `data` | `MonthlyDownloads[]` | ✓ | — | Array of `{ month: string; count: number }` objects. `month` is in `"YYYY-MM"` format. |
| `title` | `string` | | `"Downloads per month"` | Heading rendered above the chart and used as the caption for the screen-reader-only data table. |

**Usage:**

```svelte
<script lang="ts">
  import DownloadsHistogram from "./ui/DownloadsHistogram.svelte";
  import type { MonthlyDownloads } from "../types";

  let monthlyDownloads: MonthlyDownloads[] = $state([]);
</script>

<DownloadsHistogram data={monthlyDownloads} />
```

**Accessibility:**

- The visual bar area is `aria-hidden="true"` and paired with a screen-reader-only table that provides the equivalent data (`Month` + `Downloads`) and a caption (`title`).
- The count tooltip (shown on hover) and month axis labels use `text-ink-600` (light mode) to satisfy the WCAG 1.4.3 Contrast Minimum of 4.5:1. The count tooltip additionally uses `dark:text-ink-200` in dark mode to maintain contrast against the `accent-500` bar background. Month axis labels use `dark:text-ink-300` in dark mode.
- The month label row and the count tooltip are `aria-hidden="true"` because the equivalent information is already conveyed by the accessible table.
- The empty-state message uses `aria-live="polite"`; note that the element is conditionally rendered inside `{#if isEmpty}`, so announcements may not fire reliably in all screen readers (NVDA and JAWS sometimes skip announcements when a live region is inserted with text already populated).

---

### `EmailBookModal.svelte`

A modal dialog that lets users email a book file to an email address. It fetches the book's file list on mount, then presents a file picker (when the book has more than one file), an email address field, and a Send button. Focus is trapped within the dialog while it is open; the backdrop click and Escape key both dismiss it.

**Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `bookId` | `string` | ✓ | ID of the book whose files should be offered for emailing. |
| `onClose` | `() => void` | ✓ | Called when the dialog should be dismissed (backdrop click, close button, or Escape key). |

**Usage:**

```svelte
<script lang="ts">
  import EmailBookModal from "./ui/EmailBookModal.svelte";

  let showEmailModal = $state(false);
  let selectedBookId = $state("");
</script>

{#if showEmailModal}
  <EmailBookModal
    bookId={selectedBookId}
    onClose={() => (showEmailModal = false)}
  />
{/if}
```

**Accessibility:**

- The dialog root uses `role="dialog"` with `aria-modal="true"` and `aria-labelledby` pointing to the modal's `<h2>` title element (WCAG 4.1.2).
- On mount, focus moves to the dialog container via `$effect` so assistive technologies announce the dialog title first and keyboard users are immediately inside the dialog (WCAG 2.1.2).
- Tab and Shift+Tab wrap around the set of focusable elements inside the dialog, preventing focus from escaping to the page behind the modal (WCAG 2.1.1).
- Pressing Escape calls `onClose` to dismiss the dialog (WCAG 2.1.2).
- The backdrop has `aria-hidden="true"` so screen readers are not aware of the decorative overlay.
- Loading and success states use `role="status"` for polite announcements; error states use `role="alert"` for immediate announcements.

---

### `TextInput.svelte`

A styled text input that forwards all standard HTML `<input>` attributes. Use this instead of a raw `<input>` element so focus-ring, border, dark-mode, and disabled styles are consistent. In dark mode, placeholder text uses `dark:placeholder:text-ink-300` (not `dark:placeholder:text-ink-500`) to satisfy the WCAG 1.4.3 Contrast Minimum (Level AA) for non-active UI text. The border uses `border-ink-400 dark:border-ink-400` to satisfy the WCAG 1.4.11 Non-text Contrast minimum of 3:1 in both light and dark modes. When `aria-invalid="true"` is set, the input also uses danger border/focus styling so error fields are visually identifiable.

**Props:**

| Prop | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| `value` | `string` | | `""` | Bindable current value (`$bindable()`). Supports both `bind:value` and controlled (`value` + `oninput`) patterns. |
| `type` | `"text" \| "email" \| "password" \| "url"` | | `"text"` | Input type — only these four HTML input types are accepted. |
| `disabled` | `boolean` | | `false` | Disables the input with muted colors and `cursor-not-allowed` |
| `class` | `string` | | — | Additional Tailwind classes |
| `...restProps` | `HTMLInputAttributes` | | — | Any standard `<input>` attributes (`aria-required`, `aria-invalid`, `aria-describedby`, `placeholder`, `maxlength`, etc.) are forwarded to the underlying element |

**Usage — controlled (bind):**

```svelte
<script lang="ts">
  import TextInput from "./ui/TextInput.svelte";
  let email = $state("");
</script>

<TextInput bind:value={email} type="email" placeholder="you@example.com" />
```

**Usage — uncontrolled (no initial value needed):**

```svelte
<TextInput type="password" aria-label="Password" />
```

For inline validation errors, pass `aria-invalid` and `aria-describedby` through `restProps` and wire them to your validation state (see [Form accessibility](#form-accessibility)).

---

## Reading Lists components

The reading lists feature lets users create and manage named collections of books. It is composed of two components: a top-level list view and a detail view for an individual list.

### `ReadingLists.svelte`

**Location:** `frontend/src/components/ReadingLists.svelte`

Top-level page component rendered when the router's `currentView` is `"reading-lists"`. It displays all reading lists owned by the authenticated user and handles list creation.

| Sub-path | Behavior |
|----------|-----------|
| `(empty)` | Shows the list of reading lists plus an inline creation form |
| `{id}` | Renders `ReadingListDetail` for the list with that ID |

**Behavior:**

- On mount calls `readingListStore.load()` (idempotent — safe to call on every render).
- Displays an error banner when `readingListStore.loadError` is set.
- Shows an inline create form (name + optional description) when the **New list** button is clicked.
- On successful creation, navigates to `reading-lists/{newId}` via `routerStore.navigate`.

**Dependencies:** `readingListStore`, `routerStore`, `AlertBanner`, `Button`, `TextInput`, `ReadingListDetail`.

---

### `ReadingListDetail.svelte`

**Location:** `frontend/src/components/reading-lists/ReadingListDetail.svelte`

Detail page for a single reading list. Receives the `listId` prop from `ReadingLists.svelte`.

**Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `listId` | `string` | ✓ | ID of the reading list to display |

**Features:**

- Derives the `ReadingList` object from `readingListStore.lists` — no separate API fetch.
- Inline name/description editing with save and cancel controls.
- Delete with an inline confirmation guard; on success navigates back to `#reading-lists`.
- Paginated book list rendered via `BookList`, using `listReadingListBooks` for data fetching.

**Dependencies:** `readingListStore`, `routerStore`, `listReadingListBooks`, `AlertBanner`, `Button`, `TextInput`, `BookList`.

---

## Reading Groups components

The reading groups feature lets users create collaborative groups, manage members, and share reading lists for group-level visibility. The feature is composed of a top-level entry component, a `GroupDetail.svelte` detail shell, and three focused sub-components that together form the group detail view.

### `Groups.svelte`

**Location:** `frontend/src/components/Groups.svelte`

Top-level page component rendered when the router's `currentView` is `"groups"`. It displays the list of groups the authenticated user belongs to and handles group creation.

| Sub-path | Behavior |
|----------|-----------|
| `(empty)` | Shows the group list plus a **New Group** button; clicking the button reveals an inline creation form |
| `new` | Opens the inline creation form |
| `{id}` | Renders `GroupDetail` for the group with that ID |

**Behavior:**

- On mount calls `groupStore.load()` (idempotent — safe to call on every render).
- Displays an error banner when `groupStore.loadError` is set.
- Empty state with a **Create Your First Group** CTA when the user belongs to no groups.
- On successful creation, navigates to `groups/{newId}` via `routerStore.navigate`.

**Dependencies:** `groupStore`, `routerStore`, `AlertBanner`, `Button`, `TextInput`, `GroupDetail`.

---

### `GroupDetail.svelte`

**Location:** `frontend/src/components/groups/GroupDetail.svelte`

Detail view shell for a single reading group. Receives the `groupId` prop from `Groups.svelte`.

**Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `groupId` | `string` | ✓ | ID of the reading group to display |

**Behavior:**

- Derives the `ReadingGroup` object from `groupStore.groups` — no separate API fetch.
- Derives `isOwner` by comparing `authStore.user.id` with `group.owner_id`.
- Shows an error banner when the group is not found after the store has loaded.
- Composes `GroupEditHeader`, `GroupMembers`, and `GroupSharedLists` as focused sub-components.

**Dependencies:** `groupStore`, `authStore`, `AlertBanner`, `GroupEditHeader`, `GroupMembers`, `GroupSharedLists`.

---

### `GroupEditHeader.svelte`

**Location:** `frontend/src/components/groups/GroupEditHeader.svelte`

Renders the group title, description, and — for group owners — inline edit and delete controls.

**Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `group` | `ReadingGroup` | ✓ | The group object to display |
| `groupId` | `string` | ✓ | Current group ID (used to guard stale async operations after navigation) |
| `isOwner` | `boolean` | ✓ | Whether the authenticated user owns the group |
| `onDeleteError` | `(message: string) => void` | | Callback invoked when a delete operation fails; allows the parent to surface the error |

**Behavior:**

- In view mode shows the group name, member count, description, and (owners only) **Edit** and **Delete** buttons.
- **Edit** toggles an inline form pre-filled with the current name and description; **Save** calls `groupStore.update`; **Cancel** discards changes.
- **Delete** requires a two-step inline confirmation. On success navigates to `#groups`; on failure calls `onDeleteError` so the parent can show a banner.
- A `$effect` resets all local state whenever `groupId` changes, preventing stale UI when navigating between groups.

**Dependencies:** `groupStore`, `routerStore`, `AlertBanner`, `Button`, `TextInput`.

---

### `GroupMembers.svelte`

**Location:** `frontend/src/components/groups/GroupMembers.svelte`

Member list with add and remove controls.

**Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `groupId` | `string` | ✓ | ID of the group whose members to display |
| `isOwner` | `boolean` | ✓ | Whether the authenticated user owns the group |
| `currentUserId` | `string` | ✓ | The authenticated user's ID (used to prevent owners from removing themselves) |

**Behavior:**

- Fetches members via `listGroupMembers(groupId)` on mount; re-fetches after every successful add or remove.
- Owners see an **Add Member** form that accepts a user ID and calls `addGroupMember`.
- Only owners can remove members (via `removeGroupMember`); non-owner members cannot leave themselves. To leave a group, a non-owner member must ask the group owner to remove them.
- Each remove action uses a two-step inline confirmation before calling the API.
- A `$effect` resets all local state and re-fetches when `groupId` changes.

**Dependencies:** `groupStore`, `listGroupMembers`, `addGroupMember`, `removeGroupMember`, `AlertBanner`, `Button`, `TextInput`.

---

### `GroupSharedLists.svelte`

**Location:** `frontend/src/components/groups/GroupSharedLists.svelte`

Displays the reading lists shared with the group, allows members to share their own lists, allows group owners to unshare any shared list, and allows any member to unshare a list they personally shared.

**Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `groupId` | `string` | ✓ | ID of the group |
| `isOwner` | `boolean` | ✓ | Whether the authenticated user owns the group; grants owners permission to unshare any shared list (members can only unshare their own shared lists) |

**Behavior:**

- Fetches shared lists via `listGroupReadingLists(groupId)` on mount.
- Loads the user's own reading lists from `readingListStore` (calls `readingListStore.load()` if not yet loaded) to populate the share dropdown.
- Sharing a list calls `shareListWithGroup(groupId, listId)` and re-fetches shared lists on success.
- Unsharing uses a two-step inline confirmation before calling `unshareListFromGroup`. The unshare button is visible to group owners (for any list) and to any member who personally shared the list.
- A `$effect` resets all local state and re-fetches when `groupId` changes.

**Dependencies:** `readingListStore`, `listGroupReadingLists`, `shareListWithGroup`, `unshareListFromGroup`, `AlertBanner`, `Button`.

---

## Auth page components

The unauthenticated login and signup page is built from three layers:

1. **`Auth.svelte`** — page shell; owns ARIA tab state, passkey/OIDC feature flags, and form submission logic.
2. **`auth/LoginForm.svelte`** and **`auth/SignupForm.svelte`** — focused form panels; receive all field state via `$bindable` props and emit a single `onsubmit` callback.
3. **Auth lib modules** — reusable utilities for validation, error interpretation, and feature-flag fetching (see [Utility modules](#utility-modules)).

### `LoginForm.svelte`

**Location:** `frontend/src/components/auth/LoginForm.svelte`

Renders the email + password login form inside a `role="tabpanel"` element, composing the ARIA tab widget owned by `Auth.svelte`.

**Props (`$bindable` unless noted):**

| Prop | Type | Default | Notes |
|------|------|---------|-------|
| `email` | `string` | `""` | Bound to the email input |
| `password` | `string` | `""` | Bound to the password input |
| `emailInvalid` | `boolean` | `false` | Sets `aria-invalid` on the email field |
| `passwordInvalid` | `boolean` | `false` | Sets `aria-invalid` on the password field |
| `error` | `string \| null` | `null` | Error message shown in `AlertBanner` |
| `errorVisible` | `boolean` | `false` | Read-only; controls whether `AlertBanner` renders |
| `loading` | `boolean` | `false` | Disables inputs and changes button label |
| `hidden` | `boolean` | `false` | Passed to the `role="tabpanel"` `hidden` attribute |
| `onsubmit` | `(SubmitEvent) => void` | required | Called when the form is submitted |

**Accessibility:**

- Each field carries `aria-required={true}` and `aria-invalid` tied to the corresponding prop.
- `aria-describedby` on invalid fields points to the `AlertBanner` (`id="login-auth-error"`), linking the error announcement to the fields that caused it (WCAG 3.3.1).
- `autocomplete="email"` and `autocomplete="current-password"` are set on the respective inputs (WCAG 1.3.5).

**Dependencies:** `AlertBanner`, `Button`, `TextInput`.

### `SignupForm.svelte`

**Location:** `frontend/src/components/auth/SignupForm.svelte`

Renders the name + email + password registration form inside a `role="tabpanel"` element.

**Props (`$bindable` unless noted):**

| Prop | Type | Default | Notes |
|------|------|---------|-------|
| `name` | `string` | `""` | Bound to the display name input |
| `email` | `string` | `""` | Bound to the email input |
| `password` | `string` | `""` | Bound to the password input |
| `nameInvalid` | `boolean` | `false` | Sets `aria-invalid` on the name field |
| `emailInvalid` | `boolean` | `false` | Sets `aria-invalid` on the email field |
| `passwordInvalid` | `boolean` | `false` | Sets `aria-invalid` on the password field |
| `error` | `string \| null` | `null` | Error message shown in `AlertBanner` |
| `errorVisible` | `boolean` | `false` | Read-only; controls whether `AlertBanner` renders |
| `loading` | `boolean` | `false` | Disables inputs and changes button label |
| `hidden` | `boolean` | `false` | Passed to the `role="tabpanel"` `hidden` attribute |
| `onsubmit` | `(SubmitEvent) => void` | required | Called when the form is submitted |

**Accessibility:**

- All three fields carry `aria-required={true}` and `aria-invalid` tied to the corresponding props.
- `aria-describedby` on invalid fields points to the `AlertBanner` (`id="signup-auth-error"`) (WCAG 3.3.1).
- `autocomplete="name"`, `autocomplete="email"`, and `autocomplete="new-password"` are set (WCAG 1.3.5).

**Dependencies:** `AlertBanner`, `Button`, `TextInput`.

---

## Settings component architecture

`Settings.svelte` is a shell that owns shared state (admin flag, OIDC config) and renders one tab at a time. Each tab is a standalone sub-component in `frontend/src/components/settings/`.

| Component | Route | Visibility | Responsibility |
|-----------|-------|------------|----------------|
| `AccountTab.svelte` | `settings/account` | All users | View email; edit display name via `PUT /api/auth/me`; change password; link OIDC account |
| `APIKeysTab.svelte` | `settings/api-keys` | All users | Create and revoke long-lived API keys (`bib_` prefix); uses inline `role="alertdialog"` confirmations for delete actions |
| `KoboTab.svelte` | `settings/kobo` | All users | Create and revoke Kobo sync tokens; copy device sync URL; uses inline `role="alertdialog"` confirmations for delete actions |
| `PreferencesTab.svelte` | `settings/preferences` | All users | Choose light / dark / auto theme; announces the selected theme via a `role="status"` live region (WCAG 4.1.3) |
| `OidcTab.svelte` | `settings/oidc` | Admins only | Configure OIDC / SSO provider |
| `SmtpTab.svelte` | `settings/smtp` | Admins only | Configure SMTP mail server |
| `UsersTab.svelte` | `settings/users` | Admins only | List users; toggle admin role |
| `LLMTab.svelte` | `settings/llm` | Admins only | Configure LLM provider for AI metadata enrichment |
| `WatchFolderTab.svelte` | `settings/watch-folder` | Admins only | Configure the watch folder for automatic book file import |
| `CalibreImportTab.svelte` | `settings/calibre-import` | Admins only | Import a Calibre library via file upload or server-side path |
| `SearchIndexTab.svelte` | `settings/search-index` | Admins only | Trigger a full rebuild of the full-text search index |

`Settings.svelte` passes data down as props and receives updates via callback props (`onOidcSaved`, `onUsersLoaded`), keeping each tab stateless with respect to shared data.

### SmtpTab (`settings/smtp`)

`SmtpTab.svelte` renders a form for configuring the outgoing mail server. It is only shown to admin users.

**Form fields:**

| Field | Required | Notes |
|-------|----------|-------|
| Host | Yes | Hostname or IP of the SMTP server |
| Port | Yes | Defaults to `587` |
| TLS Mode | Yes | Dropdown: `STARTTLS` (default), `TLS`, or `None`. Authenticated SMTP without TLS is blocked for non-loopback servers |
| Username | No | Leave empty for unauthenticated relay |
| Password | Conditional | Required when Username is set. Leave blank on update to keep the existing password |
| From Address | Yes | Envelope `From` address; must be a valid email |

**Key behaviours:**

- **Status badge** — Shows *Configured* (green) or *Not configured* (grey) based on whether a complete SMTP config exists in the database.
- **Test Email button** — Visible only when the server is configured. Sends a test message to the authenticated user's email address. Subject to rate-limiting (one send per minute).
- **Environment-variable override banner** — When `SMTP_HOST` is set as a server environment variable, a blue informational banner replaces the form: *"SMTP is configured via environment variables and cannot be changed here."* The tab becomes read-only. To use the UI instead, unset `SMTP_HOST` from the environment and restart the server.
- **Password preservation** — On save, leaving the password field blank preserves the existing stored credential; fill it only to change it.

### LLMTab (`settings/llm`)

`LLMTab.svelte` lets admins configure the LLM provider used for AI-powered metadata enrichment. It is only shown to admin users.

**Form fields:**

| Field | Required | Notes |
|-------|----------|-------|
| Enabled | — | Toggle to enable or disable LLM enrichment |
| Provider | When enabled | Dropdown; currently only `"ollama"` is supported |
| Endpoint | When enabled | Base URL of the LLM server (e.g. `http://ollama.internal:11434`) |
| Model | When enabled | Name of the model to use (e.g. `llama3`) |

**Key behaviours:**

- **Status badge** — Shows *Enabled* (green) or *Disabled* (grey) based on whether LLM is enabled and both endpoint and model are set.
- **Restart-required banner** — After a successful save, a warning banner is shown: *"A server restart is required for this change to take effect."* LLM configuration is read at startup; the running server is not updated until it is restarted.
- **Client-side validation** — When the toggle is enabled, endpoint and model fields are required before the form is submitted. Toggling LLM off clears the validation requirement.
- **Idempotent load** — On mount, the tab fetches the current config via `GET /api/config/llm` and populates the form. If the fetch fails, the form starts empty.
- **API endpoints** — `GET /api/config/llm` (load) and `PUT /api/config/llm` (save); see [GET LLM config](api/config.md#get-apiconfigllm--admin--jwt-only) and [PUT LLM config](api/config.md#put-apiconfigllm--admin--jwt-only) in the API reference.

### WatchFolderTab (`settings/watch-folder`)

`WatchFolderTab.svelte` lets admins configure a server-side directory that the server monitors every minute for new book files. It is only shown to admin users.

**Form fields:**

| Field | Required | Notes |
|-------|----------|-------|
| Folder Path | Yes | Absolute path to a directory on the server (validated by the API) |
| Target Library | Yes | Library to import new files into; populated from `GET /api/libraries` on mount |

**Key behaviours:**

- **Save / Update** — `PUT /api/config/watch-folder` with `path` and `library_id`; the API validates that the path exists and is a directory.
- **Clear button** — Shown when a watch folder is configured; sends `PUT /api/config/watch-folder` with an empty `path`, which disables monitoring without deleting any files.
- **Idempotent load** — On mount the tab fetches current config via `GET /api/config/watch-folder` and fetches the library list via `GET /api/libraries`. If either fetch fails, the form starts empty.

### CalibreImportTab (`settings/calibre-import`)

`CalibreImportTab.svelte` is a three-step import wizard for loading a Calibre library into Biblioteka. It is only shown to admin users.

**Steps:**

| Step | Label | Description |
|------|-------|-------------|
| 1 | Upload | Choose import source: upload a `metadata.db` file from your local machine, or specify a server-side absolute path to a `metadata.db` file |
| 2 | Preview | Displays a summary of books, authors, and series that will be imported; allows optionally selecting a target library |
| 3 | Done | Shows per-book import counts: total books, imported, skipped (already present), and errors |

**Key behaviours:**

- **Dual import modes** — *Upload* mode sends the `metadata.db` as a multipart form to `POST /api/admin/calibre/preview` (then `POST /api/admin/calibre/confirm`). *Server path* mode posts the path string to `POST /api/admin/calibre/preview/path` (then `POST /api/admin/calibre/confirm/path`). Both flows follow the same preview → confirm sequence.
- **Library selection** — Optional; when omitted, books are imported without a library association. The library list is fetched from `GET /api/libraries` on mount.
- **Idempotent import** — Books already indexed by file path are skipped, not duplicated.
- **Start over** — After a completed import, a **Start Over** button resets the wizard to step 1.

### SearchIndexTab (`settings/search-index`)

`SearchIndexTab.svelte` lets admins trigger a full rebuild of the full-text search index. It is only shown to admin users.

**Key behaviours:**

- **Rebuild button** — Calls `POST /api/admin/search/reindex`. On SQLite, this starts an asynchronous background rebuild of the `books_fts` FTS5 table; the response (`202 Accepted`) arrives immediately and the rebuild continues in the background. On PostgreSQL, the endpoint returns `200 OK` immediately because pg_trgm indexes are maintained automatically.
- **Success / error banner** — Shown after each rebuild attempt. A success message confirms the rebuild has started; an error message surfaces API failures inline.
- **When to use** — Useful after bulk imports (Calibre import, library scan) that may temporarily leave the index stale, or after running `VACUUM` on the SQLite database file outside normal server operation. See [Manual rebuild](administration.md#manual-rebuild) in the Administration guide.



Some settings tabs receive initial values from `Settings.svelte` as props and then manage those values as **local state** for the duration of the tab's lifetime. Because the values are not expected to react to future prop changes (the parent passes them once at mount), the tabs use `$state(initialProp)` to seed local state:

```svelte
<script lang="ts">
  interface Props {
    initialIssuerUrl?: string;
    // …
  }
  let { initialIssuerUrl = "" }: Props = $props();

  // One-time initialisation – this prop is not expected to change after mount.
  // svelte-ignore state_referenced_locally
  let issuerUrl = $state(initialIssuerUrl);
</script>
```

Svelte 5 emits a `state_referenced_locally` warning for this pattern because the resulting `$state` variable does not track updates to the prop — it captures the value at creation time only. The `// svelte-ignore state_referenced_locally` comment suppresses the warning when this one-time seeding is **intentional**. Do not use this suppression for state that should reactively follow a prop; use `$derived` or `$effect` instead.

### Adding a new settings tab

1. Create `frontend/src/components/settings/MyTab.svelte`.
2. Define an `interface Props { … }` and use `$props()` for any data the tab needs from `Settings.svelte`.
3. Add `"my-tab"` to the `SettingsTab` union type and `validTabs` array in `Settings.svelte`.
4. Import and render `<MyTab />` inside the `{#if activeTab === "my-tab"}` block in `Settings.svelte`.
5. Add a navigation `<a href="#settings/my-tab">` link in `Settings.svelte`'s sidebar `<nav>`, wrapped in `{#if isAdmin}` if the tab is admin-only.
6. Add `"my-tab"` to the `SettingsSubPath` union type **and** the `settingsSubTitles` record in `frontend/src/stores/router.svelte.ts`. This ensures the browser tab title is set correctly (e.g., `My Tab – biblioteka`). If you skip this step, the title falls back to the top-level `Settings – biblioteka`.
7. Update the tables above and in the [Page titles](#page-titles) section.

## Accessibility Patterns

Biblioteka's frontend follows [WCAG 2.1](https://www.w3.org/TR/WCAG21/) guidelines. This section documents the accessibility patterns used across the app and how to maintain them when making changes.

### Skip-to-main-content link

**WCAG criterion:** [2.4.1 Bypass Blocks](https://www.w3.org/WAI/WCAG21/Understanding/bypass-blocks.html) (Level A)

The authenticated app shell (`App.svelte`) includes a skip link as the **first focusable element** in the DOM. It allows keyboard and screen-reader users to jump past the persistent navigation sidebar directly to the main content area without tabbing through every nav item on every page load.

**Implementation in `App.svelte`:**

```svelte
<!-- First focusable element inside the authenticated shell -->
<a
  href="#main-content"
  onclick={(e: MouseEvent) => {
    e.preventDefault();
    document.getElementById("main-content")?.focus();
  }}
  class="sr-only focus:not-sr-only focus:absolute focus:left-4 focus:top-4 focus:z-[100]
         focus:rounded-xl focus:bg-accent-600 focus:px-4 focus:py-2 focus:font-semibold focus:text-white"
>
  Skip to main content
</a>

<!-- … Sidebar … -->

<main id="main-content" tabindex="-1" class="md:ml-64 p-4 md:p-8">
  <!-- page content -->
</main>
```

Key details:

| Element | Attribute / class | Purpose |
|---------|-------------------|---------|
| `<a href="#main-content">` | — | Standard skip link; navigates to the `main` landmark |
| `<a>` | `onclick` handler | Calls `focus()` programmatically so the browser moves keyboard focus, not just scroll position |
| `<a>` | `sr-only focus:not-sr-only` | Visually hidden at rest; fully visible when focused — keeps the default chrome clean while remaining reachable by keyboard |
| `<main>` | `id="main-content"` | Stable anchor target for the skip link |
| `<main>` | `tabindex="-1"` | Allows `element.focus()` to land on the `<main>` element even though it is not natively focusable |

**DOM ordering rule:** The skip link must be rendered **before** `<Sidebar />` in the template so it is the first element reached by the Tab key. Do not move it below the sidebar.

### Page title on navigation

**WCAG criterion:** [2.4.2 Page Titled](https://www.w3.org/WAI/WCAG21/Understanding/page-titled.html) (Level A)

In a single-page application the browser does not perform a real page load on navigation, so `document.title` stays unchanged unless the application updates it explicitly. Screen readers and browser history both rely on meaningful, descriptive page titles to help users understand where they are.

`routerStore` exposes a reactive `pageTitle` property derived from the current view and settings sub-path. `App.svelte` writes it to `document.title` via a Svelte `$effect`:

```svelte
<!-- App.svelte -->
$effect(() => {
  document.title = routerStore.pageTitle;
});
```

`pageTitle` is built from two lookup tables defined in `router.svelte.ts`:

| View / sub-path | Title |
|-----------------|-------|
| `dashboard` | `Dashboard – biblioteka` |
| `books` | `All Books – biblioteka` |
| `my-library` | `My Library – biblioteka` |
| `libraries` | `Libraries – biblioteka` |
| `libraries/{id}` | `{library name} – biblioteka` (set via `setPageTitle`) |
| `settings` (no sub-path) | `Settings – biblioteka` |
| `settings/account` | `Account Settings – biblioteka` |
| `settings/preferences` | `Preferences – biblioteka` |
| `settings/oidc` | `SSO Settings – biblioteka` |
| `settings/smtp` | `Email Settings – biblioteka` |
| `settings/users` | `User Management – biblioteka` |
| `settings/api-keys` | `API Keys – biblioteka` |
| `settings/kobo` | `Kobo Sync – biblioteka` |
| Unknown hash | `Page Not Found – biblioteka` |

**Dynamic page titles** — Views that display a named resource (such as a specific library) can call `routerStore.setPageTitle(title)` to override the default view title. The override is automatically cleared on navigation. For example, `LibraryView.svelte` sets the title to the library name when the library prop resolves.

**When adding a new view or settings tab**, update both the corresponding union type (`AppView` or `SettingsSubPath`) and the matching title lookup table in `router.svelte.ts`. If you skip the lookup entry, `pageTitle` falls back to the top-level view title, which may be insufficiently descriptive.

### Focus management on SPA navigation

**WCAG criterion:** [2.4.3 Focus Order](https://www.w3.org/WAI/WCAG21/Understanding/focus-order.html) (Level A)

In a standard multi-page website the browser automatically returns keyboard focus to the top of the document after each page load. Single-page applications do not perform real page loads on navigation, so without explicit focus management keyboard-only and screen-reader users remain focused on whichever element they last interacted with — typically a sidebar navigation link — instead of landing on the new page content.

`App.svelte` addresses this by programmatically moving keyboard focus to `<main id="main-content">` after each route change:

```svelte
<!-- App.svelte -->
let focusEffectMounted = false;
$effect(() => {
  void routerStore.hash; // register hash as a reactive dependency
  if (!focusEffectMounted) {
    focusEffectMounted = true;
    return; // skip initial mount — avoids stealing focus from browser UI on hard refresh
  }
  if (authStore.user) {
    void tick().then(() => {
      document.getElementById("main-content")?.focus();
    });
  }
});
```

Key details:

| Detail | Purpose |
|--------|---------|
| `void routerStore.hash` | Registers `routerStore.hash` as a reactive dependency so the effect re-runs on every navigation |
| `focusEffectMounted` guard | Skips the very first execution so a hard refresh does not steal focus from the browser address bar or other browser UI |
| `tick().then(…)` | Defers `focus()` until after Svelte has flushed DOM updates for the incoming view, so the element is in its final state when focus lands |
| `tabindex="-1"` on `<main>` | Makes `<main>` programmatically focusable even though it is not a natively interactive element |

**When adding a new view,** no additional changes are required — the focus effect fires automatically whenever `routerStore.hash` changes, regardless of which view component is rendered.

### Non-text contrast + focus visible — Library settings link (`Sidebar.svelte`)

**WCAG criteria:**
- [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) (Level AA) — default-state icon contrast
- [2.4.7 Focus Visible](https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html) (Level AA) — keyboard focus indicator
- [2.4.6 Headings and Labels](https://www.w3.org/WAI/WCAG21/Understanding/headings-and-labels.html) (Level AA) — the unique `aria-label` per library

Interactive elements must have enough contrast in their resting state and a visible focus indicator for keyboard users. The library-settings gear icon link in the sidebar is a subtle secondary action that should not visually dominate the sidebar, but it still needs to remain discoverable.

The link now uses `text-ink-500` in the resting state (3.08:1 contrast against `bg-ink-950`, meeting WCAG 1.4.11's 3:1 minimum) and switches to `text-accent-400` on hover or when the parent row is focus-within. This preserves subtle styling while keeping the icon legible by default:

```svelte
<a
  href={`#libraries/edit/${lib.id}`}
  class="text-ink-500 group-hover:text-accent-400 group-focus-within:text-accent-400 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent-400 rounded transition-all p-0.5 flex-shrink-0"
  aria-label={`Library settings for ${lib.name}`}
  onclick={onClose}
>
  <Settings2 class="w-3.5 h-3.5" />
</a>
```

Key details:

| Class / attribute | Purpose |
|-------------------|---------|
| `text-ink-500` | Resting state with sufficient contrast against sidebar background (3.08:1, WCAG 1.4.11) |
| `group-hover:text-accent-400` / `group-focus-within:text-accent-400` | Increases prominence on hover and keyboard focus-within |
| `focus-visible:ring-2 focus-visible:ring-accent-400` | Provides an explicit focus ring for keyboard navigation |
| `rounded` | Ensures the focus ring follows the element's shape |
| `aria-label={...lib.name...}` | Unique, descriptive label per library (WCAG 2.4.6) |

**Rule:** Do not rely on low opacity for icon-button resting states on dark backgrounds. Use a contrast-safe resting color and reserve hover/focus states for emphasis.

### Dark-mode placeholder contrast (`TextInput.svelte`)

**WCAG criterion:** [1.4.3 Contrast (Minimum)](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) (Level AA)

Placeholder text is a visual hint; it is not required for understanding the form, but it must still be readable. WCAG 1.4.3 requires a contrast ratio of at least 4.5:1 for normal-weight text below 18 pt (or 3:1 for large / bold text). In dark mode, the background of `TextInput` is `dark:bg-ink-800`. Using `dark:placeholder:text-ink-500` produced a contrast ratio below 4.5:1 against that background — a Level AA violation. The fix uses `dark:placeholder:text-ink-300` instead, which meets the required ratio.

The relevant `$derived` class string in `TextInput.svelte`:

```svelte
const stateClasses = $derived(
  disabled
    ? "bg-ink-50 dark:bg-ink-800 text-ink-500 dark:text-ink-400 cursor-not-allowed"
    : "bg-white text-ink-900 focus:ring-2 focus:ring-accent-500 focus:border-transparent focus-visible:outline-none dark:bg-ink-800 dark:text-cream-100 placeholder:text-ink-500 dark:placeholder:text-ink-300",
);
```

| Token | Mode | Role |
|-------|------|------|
| `placeholder:text-ink-500` | Light | Placeholder text on `bg-white` — sufficient contrast |
| `dark:placeholder:text-ink-300` | Dark | Placeholder text on `dark:bg-ink-800` — meets 4.5:1 minimum (WCAG 1.4.3) |

**Rule:** When using placeholder text on a dark background, always use `dark:placeholder:text-ink-300` (or lighter). Never use `dark:placeholder:text-ink-500` or darker on `dark:bg-ink-800` — the resulting contrast ratio is insufficient.

### Form control border contrast (`TextInput.svelte`)

**WCAG criterion:** [1.4.11 Non-text Contrast](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html) (Level AA)

The visible boundary of a form control (e.g. the border of a text input or a bordered button) must have a contrast ratio of at least 3:1 against the adjacent background. WCAG 1.4.11 covers all states of UI components: default, hover, focus, and disabled.

`TextInput.svelte` uses `border-ink-400` in both light and dark modes. In light mode (`bg-white`), `ink-400` provides sufficient contrast against the white background. In dark mode (`dark:bg-ink-800`), the same `dark:border-ink-400` class is applied explicitly — overriding Tailwind's default dark-mode cascade — to ensure the border remains perceivable.

The border class on `TextInput.svelte`:

```svelte
<input
  class="px-4 border border-ink-400 dark:border-ink-400 rounded-xl transition-all {stateClasses} ..."
/>
```

The same `border-ink-400 dark:border-ink-400` pattern must be applied to any inline form control (`<input>`, `<select>`, bordered `<button>`, etc.) that does not use the reusable `TextInput` component — for example, the TLS Mode `<select>` in `SmtpTab.svelte`, the File Organization `<select>` in `LibraryForm.svelte`, and bordered pagination buttons (Previous/Next) in `BookList.svelte`.

| Class | Mode | Adjacent background | Requirement |
|-------|------|---------------------|-------------|
| `border-ink-400` | Light | `bg-white` | Meets WCAG 1.4.11 ≥ 3:1 |
| `dark:border-ink-400` | Dark | `dark:bg-ink-800` | Meets WCAG 1.4.11 ≥ 3:1 |

**Rule:** All form inputs and bordered interactive elements must use `border-ink-400 dark:border-ink-400` (or a higher-contrast token) for their default border. In light mode, do not use `border-ink-200` on `bg-white`; in dark mode, do not use `dark:border-ink-700` on `dark:bg-ink-800` — those are the low-contrast combinations that fail the 3:1 non-text contrast requirement.

### Focus ring on form inputs (`TextInput.svelte` and inline inputs)

**WCAG criterion:** [2.4.7 Focus Visible](https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html) (Level AA)

Keyboard users must be able to see which element currently has focus. Applying `outline-none` unconditionally suppresses the browser's native focus indicator entirely — a direct WCAG 2.4.7 violation. The correct fix is `focus-visible:outline-none`, which targets the `:focus-visible` pseudo-class and removes the browser default outline **only when keyboard-initiated focus is detected** (`:focus-visible` matches when the UA determines focus should be visually indicated, typically keyboard navigation).

The `focus:ring-2 focus:ring-accent-500 focus:border-transparent` classes on form inputs provide an explicit accent-colored focus ring for all focus states. `focus-visible:outline-none` suppresses the *additional* browser-default outline when `:focus-visible` matches, so keyboard users see the styled accent ring instead of a double indicator. The net effect is a clean, consistent focus indicator for both pointer and keyboard users.

The active-state class string in `TextInput.svelte`:

```svelte
const stateClasses = $derived(
  disabled
    ? "bg-ink-50 dark:bg-ink-800 text-ink-500 dark:text-ink-400 cursor-not-allowed"
    : "bg-white text-ink-900 focus:ring-2 focus:ring-accent-500 focus:border-transparent focus-visible:outline-none dark:bg-ink-800 dark:text-cream-100 placeholder:text-ink-500 dark:placeholder:text-ink-300",
);
```

The same class pattern appears on inline `<input>` and `<textarea>` elements in components that do not use `TextInput`:

```html
class="... focus:ring-2 focus:ring-accent-500 focus:border-transparent focus-visible:outline-none ..."
```

Affected components (as of PR #2060): `TextInput.svelte`, `BookEditForm.svelte`, `FirstLibraryWizard.svelte`, `LibraryForm.svelte`, `CalibreImportTab.svelte`, `SmtpTab.svelte`, `WatchFolderTab.svelte`, and `EmailBookModal.svelte`.

**Rule:** Never use `outline-none` on a focusable form element. Always use `focus-visible:outline-none` instead. The `focus-visible:outline-none` class must be combined with explicit `focus:ring-*` classes so that keyboard users see a styled focus indicator rather than the browser default.

### Live region for theme change announcements (`PreferencesTab.svelte`)

**WCAG criterion:** [4.1.3 Status Messages](https://www.w3.org/WAI/WCAG21/Understanding/status-messages.html) (Level AA)

When a user selects a new theme (light, dark, or auto), the UI updates visually but no element receives focus. Without an explicit live region, screen-reader users receive no feedback that their action succeeded. `PreferencesTab.svelte` uses a `role="status"` element — an implicit `aria-live="polite"` live region — to announce the change in a non-intrusive way.

**Implementation in `PreferencesTab.svelte`:**

```svelte
<script lang="ts">
  import { themeStore, type ThemePreference } from "../../stores/theme.svelte";

  let themeAnnouncement = $state("");

  function setTheme(t: ThemePreference) {
    themeStore.set(t);
    themeAnnouncement = "";           // reset first so the same message re-triggers
    const label = t === "auto" ? "follow system settings" : t;
    setTimeout(() => {
      themeAnnouncement = `Theme changed to ${label}`;
    }, 0);                            // defer one macrotask so the DOM reset is flushed
  }
</script>

<!-- Visually hidden; content is announced politely by screen readers -->
<span role="status" class="sr-only">{themeAnnouncement}</span>
```

Key details:

| Element / technique | Purpose |
|---|---|
| `role="status"` | Declares an implicit `aria-live="polite"` live region; screen readers announce its content after the current interaction completes without interrupting ongoing speech |
| `class="sr-only"` | Hides the element visually (absolute position, 1 px × 1 px) while keeping it in the accessibility tree |
| `themeAnnouncement = ""` then `setTimeout(..., 0)` | Resetting the text before setting it again ensures repeated selections of the same theme still trigger a fresh announcement; the 0 ms timeout flushes the Svelte reactivity cycle so the empty string reaches the DOM before the new message |
| `"follow system settings"` for `auto` | Human-readable label; `"auto"` alone would be ambiguous to a screen-reader user unfamiliar with the UI option names |

**Rule:** Whenever a user action produces a transient status change that is not communicated by focus movement or a visible heading update, add a `role="status"` live region with `class="sr-only"`. Use `role="alert"` (assertive) only for urgent errors that must interrupt the user immediately. Reset the live-region text to `""` before updating it to guarantee re-announcement when the same message is emitted twice in a row.

### Reduced-motion support (`index.css`)

**WCAG criterion:** [2.3.3 Animation from Interactions](https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions.html) (Level AAA) — also a widely adopted best practice for users with vestibular disorders even below AAA compliance.

`frontend/src/index.css` applies a global `@media (prefers-reduced-motion: reduce)` rule that overrides all CSS animations, transitions, and scroll behaviour for users who have enabled the "reduce motion" accessibility preference in their operating system or browser:

```css
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-delay: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    transition-delay: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}
```

Setting durations to `0.01ms` (instead of `0`) avoids edge cases in some browsers where zero-duration animations never fire `animationend` events, which can leave UI state stuck. The `!important` declarations ensure no component-level Tailwind or inline style can accidentally override the user's preference.

**Rule:** Do not add CSS animations that cannot be suppressed by `prefers-reduced-motion`. Every animation class (e.g. `animate-fade-in`, `animate-spin`) is automatically suppressed by this global rule, as is any animation applied by a Svelte component `<style>` block, because the `!important` declarations override all non-`!important` `animation-*` and `transition-*` properties site-wide. The main exceptions are motion driven outside normal CSS rules — for example JavaScript/Web Animations API animations — or unusual inline `!important` overrides. Adding a component-level `@media (prefers-reduced-motion: reduce)` guard is optional belt-and-suspenders practice, not a requirement.

### Live regions in `BookList.svelte`

`BookList.svelte` uses three distinct live-region techniques to keep screen-reader users informed of page state changes without moving keyboard focus:

1. **Loading state** — The initial-load `<p role="status">Loading books...</p>` uses `role="status"` (implicit `aria-live="polite"`) so assistive technologies announce the loading message after any current speech completes. No explicit `aria-live` attribute is needed because `role="status"` already implies it.

2. **Scan-in-progress** — The "Scanning library…" message carries `aria-live="polite"` and `aria-atomic="true"`. `aria-atomic="true"` ensures the entire text string is re-read as a unit when the message updates, rather than announcing only the changed characters.

3. **Page position** — The "Page N of M" indicator inside the pagination controls carries `aria-live="polite"` and `aria-atomic="true"`. Whenever the user navigates to a new page, screen readers announce the updated position (e.g. "Page 2 of 5") without requiring focus to move to the pagination controls. `aria-atomic="true"` ensures the full string is read rather than just the changed digit. The Previous and Next buttons also carry descriptive `aria-label` attributes that identify the target page (e.g. "Previous page, page 1 of 5") so users know their destination before activating the control.

**Rule:** Use `role="status"` for state messages that appear on initial render and that you own via markup (`role` implies the live region). Use explicit `aria-live="polite"` with `aria-atomic="true"` for messages whose text content changes dynamically in-place (e.g. a count or progress string that updates repeatedly).

### Keyboard navigation in BookList table view (`BookList.svelte`)

**WCAG criterion:** [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html) (Level A)

BookList table navigation uses a native link in the title cell, not an interactive `<tr>`.

The book list table in `BookList.svelte` uses the following pattern:

| Attribute / handler | Value | Purpose |
|---|---|---|
| Title link | `<a href="#books/{id}">` | Provides native keyboard and screen-reader navigation |
| Link tabindex | not set | Keeps the link in the natural tab order |
| Row interactivity | none | Preserves table row semantics |
| Focus styles | `focus:ring-*` on `<a>` | Shows a visible focus indicator on the interactive element |

This preserves links-list discoverability and expected browser link behavior (including open-in-new-tab shortcuts).

### ARIA landmarks

The app uses semantic HTML5 landmark elements so screen readers can navigate by region.

#### Authenticated app shell (`App.svelte`)

| Landmark | Element | Notes |
|----------|---------|-------|
| Main navigation | `<aside>` (inside `Sidebar.svelte`) | Desktop persistent sidebar |
| Primary content | `<main id="main-content">` | Target of the skip link |
| Mobile header | `<div>` + hamburger `<button>` | Not a landmark; sits above `<main>` only on small screens |

#### Login / signup page (`Auth.svelte`)

The unauthenticated page renders without the app shell, so it provides its own `<main>` landmark:

```svelte
<div class="min-h-screen …">
  <!-- Decorative background elements (no landmark role) -->
  <div class="absolute inset-0 overflow-hidden pointer-events-none">…</div>

  <main class="w-full max-w-md …">
    <!-- logo, heading, login/signup form -->
  </main>
</div>
```

| Landmark | Element | Notes |
|----------|---------|-------|
| Primary content | `<main>` (in `Auth.svelte`) | Wraps the entire login/signup card; ensures screen readers have a `<main>` landmark before authentication |

**Why this matters:** The WCAG [1.3.6 Identify Purpose](https://www.w3.org/WAI/WCAG21/Understanding/identify-purpose.html) guideline and best practice require every page to expose its primary content inside a `<main>` landmark so assistive-technology users can jump directly to it. Without `<main>`, the login page would be a flat, undifferentiated document from a screen reader's perspective.

> **Rule:** Every page — authenticated or not — must contain exactly one `<main>` landmark. For the authenticated shell, `<main id="main-content">` lives in `App.svelte`. For the pre-auth login page, `<main>` lives in `Auth.svelte`.

#### ARIA tab widget — Login/Sign Up toggle (`Auth.svelte`)

**WCAG criterion:** [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html) (Level A)

The Login/Sign Up toggle implements the [ARIA tab widget pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) so that screen readers announce it as a labelled tab bar, not a pair of plain buttons.

```svelte
<!-- Tab bar: groups and labels the widget -->
<div
  role="tablist"
  aria-label="Authentication method"
  onkeydown={handleTabKeydown}
>
  <button
    id="login-tab"
    role="tab"
    aria-selected={isLogin}
    aria-controls="login-panel"
    tabindex={isLogin ? 0 : -1}
  >Login</button>

  <button
    id="signup-tab"
    role="tab"
    aria-selected={!isLogin}
    aria-controls="signup-panel"
    tabindex={!isLogin ? 0 : -1}
  >Sign Up</button>
</div>

<!-- Panels: one per tab (no tabindex — each panel contains focusable form elements) -->
<div id="login-panel"  role="tabpanel" aria-labelledby="login-tab"  hidden={!isLogin}>
  <!-- login form rendered by LoginForm.svelte -->
</div>
<div id="signup-panel" role="tabpanel" aria-labelledby="signup-tab" hidden={isLogin}>
  <!-- signup form rendered by SignupForm.svelte -->
</div>
```

**Key attributes:**

| Attribute | Element | Purpose |
|-----------|---------|---------|
| `role="tablist"` | Container `<div>` | Groups tab buttons into a single widget |
| `aria-label="Authentication method"` | Container `<div>` | Gives the tablist an accessible name announced by screen readers |
| `role="tab"` | Each `<button>` | Declares the button as a tab control |
| `aria-selected` | Each tab | `true` on the active tab; `false` on inactive tabs |
| `aria-controls` | Each tab | Associates the tab with its panel via the panel's `id` |
| `tabindex={isActive ? 0 : -1}` | Each tab | Implements the **roving tabindex** (see below) |
| `role="tabpanel"` | Each form panel | Declares the container as a tab panel |
| `aria-labelledby` | Each panel | Links the panel back to its controlling tab |
| `hidden` | Inactive panel | Hides the inactive panel from both display and the accessibility tree |

> **Note on `tabindex` for tabpanels:** These panels intentionally omit `tabindex="0"`. Each panel contains natively focusable elements (inputs and buttons), so adding `tabindex="0"` would create a redundant extra tab stop on the panel container before the first form control. Only panels with *no* focusable descendants should add `tabindex="0"` to remain reachable via keyboard. See [WAI-ARIA Authoring Practices — Tabs pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/).

**Roving tabindex:**
Only the active tab sits in the natural tab order (`tabindex="0"`); inactive tabs are removed from it (`tabindex="-1"`) but remain focusable programmatically. When the user tabs away from the active tab, focus moves to the first focusable element inside the active panel — inactive tabs are skipped, matching the expected [APG tab pattern](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) behaviour.

**Keyboard navigation (`handleTabKeydown`):**

| Key | Action |
|-----|--------|
| `ArrowRight` / `ArrowLeft` | Move focus to the next / previous tab and activate it |
| `Home` | Move focus and activation to the first tab (Login) |
| `End` | Move focus and activation to the last tab (Sign Up) |

**Why `hidden` instead of Svelte `{#if}`:**
The `hidden` HTML attribute is used on inactive panels rather than Svelte's `{#if}` block. Both panels stay in the DOM, so `aria-controls` references always point to a valid element. Removing a panel with `{#if}` would leave a dangling `aria-controls` reference and break the ARIA association.

### Page heading hierarchy

**WCAG criterion:** [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html) (Level A) · [2.4.6 Headings and Labels](https://www.w3.org/WAI/WCAG21/Understanding/headings-and-labels.html) (Level AA)

Each page should contain exactly one visible `<h1>` when displaying primary content. In the authenticated app shell, the `<h1>` is owned by the active view component — not by any persistent shell element such as the sidebar.

```
App.svelte (shell)
├── Sidebar.svelte — brand name rendered as <p>, not <h1>
└── <main id="main-content">
    └── Dashboard.svelte (or Books.svelte, Libraries.svelte, …)
        └── <h1>Dashboard</h1>   ← the page's only <h1>
```

**Composite views:** Some view components delegate to sub-components that render their own heading hierarchy. For example, `Libraries.svelte` delegates to `LibraryView.svelte` (which contains the `<h1>`) or `LibraryForm.svelte` (which uses `<h2>` as the top heading within a card). Empty or transitional states (e.g., "Select a library") may omit the `<h1>` when there is no meaningful page title to display.

The sidebar brand name ("biblioteka") is styled to look prominent but uses a `<p>` element so the document outline contains exactly one `<h1>` per view:

```svelte
<!-- Sidebar.svelte — brand name -->
<p class="text-lg font-display font-bold tracking-tight">biblioteka</p>
```

Using `<h1>` here would create a second top-level heading on every authenticated page, corrupting the document outline seen by screen readers and automated accessibility tools.

**Heading levels in use:**

| Level | Where | Element / role |
|-------|-------|----------------|
| `h1` | Active view component (`Dashboard.svelte`, `Books.svelte`, etc.) | Native `<h1>` |
| `h2` | Sidebar navigation group labels | Native `<h2>` |
| `h2` and below | Content-area section headers | Native `<h2>`, `<h3>`, etc. |

**When adding a new page view**, the top-level heading for that page must be a native `<h1>`. Do not add an `<h1>` inside persistent shell elements (sidebar, header bar, footer).

### `aria-current` on active navigation links

**WCAG criterion:** [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html) (Level A)

Navigation links that represent the currently active view must carry `aria-current="page"`. Without this attribute, keyboard and screen-reader users have no programmatic way to determine which section is active — they can only infer it from visual styling, which is inaccessible.

#### Sidebar navigation (`Sidebar.svelte`)

Each top-level navigation link receives `aria-current` dynamically based on the `currentView` prop:

```svelte
<a
  href="#dashboard"
  aria-current={currentView === "dashboard" ? "page" : undefined}
  class="…"
  onclick={onClose}
>
  <LayoutDashboard class="w-5 h-5" />
  Dashboard
</a>
```

- Set `aria-current="page"` when the link represents the currently displayed view.
- Pass `undefined` (not `false`) for inactive links — `undefined` omits the attribute entirely, which is the correct behaviour. Using `aria-current="false"` is valid but adds noise and can confuse some assistive technologies.

#### Settings tab navigation (`Settings.svelte`)

The same pattern applies to settings sub-tabs, where the active tab is determined from the current `settingsSubPath`:

```svelte
<a
  href="#settings/account"
  aria-current={isActive ? "page" : undefined}
  class="…"
>
  Account
</a>
```

#### Rule for new navigation elements

Whenever you add a navigation link that points to a distinct view or sub-page, apply `aria-current={isActive ? "page" : undefined}`. Do **not** rely solely on CSS class changes to convey the active state.

### Labelled navigation groups (`Sidebar.svelte`)

**WCAG criterion:** [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html) (Level A)

The navigation sidebar groups its links into named clusters (currently **Home** and **Libraries**). Without explicit semantics, these group labels are purely visual — assistive technologies see only a list of links and cannot determine which links belong to which group.

Each cluster is wrapped in a `role="group"` container labelled by a native `<h2>` heading. The heading is given a stable `id` so the group references it via `aria-labelledby`:

```svelte
<!-- Home group -->
<div role="group" aria-labelledby="sidebar-home-heading">
  <h2
    id="sidebar-home-heading"
    class="px-3 mb-2 text-[10px] font-semibold uppercase tracking-[0.15em] text-ink-500"
  >
    Home
  </h2>
  <div class="space-y-0.5">
    <a href="#dashboard" …>Dashboard</a>
    <a href="#books"     …>All Books</a>
  </div>
</div>

<!-- Libraries group -->
<div role="group" aria-labelledby="sidebar-libraries-heading">
  <div class="flex items-center justify-between px-3 mb-2">
    <h2
      id="sidebar-libraries-heading"
      class="text-[10px] font-semibold uppercase tracking-[0.15em] text-ink-500"
    >
      Libraries
    </h2>
    …
  </div>
  …library links…
</div>
```

**Why `role="group"` instead of `<nav>`?** The outer `<nav aria-label="Primary navigation">` already provides the landmark for the whole sidebar. Adding a second `<nav>` per cluster would inflate the number of navigation landmarks, making landmark-based navigation noisier. A `role="group"` groups the links semantically without creating extra landmarks.

**When adding a new navigation group:**

1. Wrap the cluster in `<div role="group" aria-labelledby="sidebar-<name>-heading">`.
2. Add an `<h2 id="sidebar-<name>-heading">` as the visual group label.
3. Add a test assertion in `Sidebar.test.ts` that `screen.getByRole("heading", { name: "<Name>", level: 2 })` is visible.

### Accessible labels for icon-only controls

**WCAG criterion:** [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html) / [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html) (Level A)

Buttons and links that render only an icon (no visible text) and form inputs that cannot be paired with a visible `<label>` element — for example, inputs inside dynamically repeated rows — must have an explicit accessible name.

#### Icon-only links and buttons

Use `aria-label` on any `<a>` or `<button>` whose only child is an icon component. Add `aria-hidden="true"` on the icon element itself so screen readers announce only the control's label and do not also read out the SVG's internal title or path description:

```svelte
<!-- Sidebar: "Create library" — navigates to the new-library form -->
<a
  href="#libraries/new"
  aria-label="Create library"
  onclick={onClose}
>
  <Plus class="w-4 h-4" aria-hidden="true" />
</a>

<!-- Close button: renders only the X icon -->
<button
  onclick={navigateBack}
  aria-label="Close form"
>
  <X class="w-5 h-5" aria-hidden="true" />
</button>

<!-- Remove-folder button in a repeated list -->
<button
  type="button"
  onclick={() => { formPaths = formPaths.filter((_, idx) => idx !== i); }}
  aria-label="Remove folder"
  disabled={saving}
>
  <X class="w-4 h-4" aria-hidden="true" />
</button>
```

Without `aria-label`, screen readers announce these controls only by their SVG title or nothing at all, giving users no meaningful description of the action. Without `aria-hidden="true"` on the icon, some screen readers may announce both the control label **and** the SVG's internal title, causing a duplicate or confusing announcement.

#### Inputs in dynamic lists

When a form field is repeated (e.g., a list of folder paths), there may be no single `<label>` element that can be associated with every input via `for`/`id`. Use `aria-label` directly on the `<input>` with a distinguishing index when there are multiple items:

```svelte
<input
  type="text"
  aria-label={formPaths.length === 1 ? "Folder path" : `Folder path ${i + 1}`}
  bind:value={entry.value}
/>
```

When there is only one input in the list, omit the index to keep the label natural. When there are multiple inputs, append the 1-based position so screen reader users can distinguish them.

#### Checklist

- Every `<button>` or `<a>` that renders only an icon must have `aria-label` or `aria-labelledby`.
- Icon elements inside labeled controls must carry `aria-hidden="true"` to prevent duplicate announcements.
- Every `<input>` and `<select>` must have either a linked `<label for="...">` or an `aria-label` / `aria-labelledby`.
- `title` attributes are not a substitute for `aria-label`; they are advisory only and are not reliably announced.

### Decorative icons alongside visible text

**WCAG criterion:** [1.1.1 Non-text Content](https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html) (Level A)

When a Lucide icon appears next to a visible text label — for example, a nav link "Dashboard" with a `<LayoutDashboard>` icon, or a page heading "Books" with a `<BookOpen>` icon — the icon is purely **decorative**: the adjacent text already conveys the meaning to the user. Unless hidden, the SVG node is exposed to the accessibility tree as an unlabelled image node, causing screen readers to announce noise like "image" or the SVG's internal title alongside the text.

Add `aria-hidden="true"` to the icon element to remove it from the accessibility tree and prevent the redundant announcement:

```svelte
<!-- Nav link: icon is decorative; the text "Dashboard" is the accessible label -->
<a href="#dashboard">
  <LayoutDashboard class="w-5 h-5" aria-hidden="true" />
  Dashboard
</a>

<!-- Page heading: icon is decorative; the h1 text provides the heading -->
<h1>
  <BookOpen class="w-6 h-6" aria-hidden="true" />
  Books
</h1>

<!-- Standalone decorative illustration (purely decorative exception, WCAG 1.1.1):
     no adjacent text; icon adds no information, so hide it from the accessibility tree / assistive technologies via aria-hidden="true". -->
<Library class="w-16 h-16 text-ink-300" aria-hidden="true" />
```

This pattern applies in either of the following situations:

**Situation A — Icon alongside visible text (all of the following must hold):**

1. An icon appears alongside a visible text label in the same element or immediately adjacent.
2. The visible text already fully communicates the meaning to a sighted user.
3. The icon adds no information beyond what the text conveys.

**Situation B — Standalone decorative illustration (both of the following must hold):**

1. The icon is a purely decorative standalone graphic (e.g., an empty-state illustration) with no adjacent text.
2. It conveys no information by itself.

If the icon conveys information that the text does not (e.g., a warning triangle icon next to a plain number indicating an error count), it is **not** decorative — give it an accessible name with `aria-label` or `aria-labelledby` (typically with `role="img"`), or include a `<title>` element inside the `<svg>` to provide an accessible description.

#### Affected components

The following components apply this pattern. When you add icons to any of these components or create a new component that matches the pattern above, follow the same convention:

| Component | Icons hidden |
|---|---|
| `Auth.svelte` | `BookCheck` (app logo alongside the app name heading) |
| `Sidebar.svelte` | `BookCheck`, `LayoutDashboard`, `BookOpen`, `Library`, `SettingsIcon`, `LogOut` (nav-link icons alongside their text labels) |
| `Dashboard.svelte` | `LayoutDashboard`, `Library`, `Plus`, `ArrowRight`, `Flame`, `BookOpen`, `CheckCheck`, `CalendarDays`, `Download` |
| `Books.svelte` | `BookOpen` (page-heading icon) |
| `Libraries.svelte` | `LibraryIcon` (empty-state illustration), `Plus` (button with visible text) |
| `MyLibrary.svelte` | `Library` (page-heading icon and empty-state illustration) |
| `Recommendations.svelte` | `Sparkles` (page-heading icon and decorative cover placeholder) |
| `settings/AccountTab.svelte` | `Mail`, `User`, `Link` ×2, `Lock` (section-heading icons) |
| `settings/APIKeysTab.svelte` | `KeyRound` (section-heading icon), `Copy`, `Trash2` (buttons with adjacent text) |
| `settings/PreferencesTab.svelte` | `Palette` (section-heading icon) |
| `settings/OidcTab.svelte` | `Shield` (section-heading icon) |
| `settings/KoboTab.svelte` | `BookOpen` (section-heading icon), `Trash2`, `Copy` |
| `settings/SmtpTab.svelte` | `Send`, `Mail` |
| `settings/UsersTab.svelte` | `Users` (section-heading icon) |
| `ui/BookCard.svelte` | `BookOpen` (decorative cover placeholder) |
| `ui/BookList.svelte` | `BookOpen` ×2, `LayoutGrid`, `List`, `ChevronLeft`, `ChevronRight` |
| `libraries/LibraryView.svelte` | `LibraryIcon` (heading alongside visible library name) |
| `libraries/LibraryForm.svelte` | `FolderOpen`, `Plus` (add folder), `Trash2` (delete) |

### Maintaining accessibility

When editing the app shell or adding new persistent navigation elements:

1. Keep the skip link as the **first** child of the authenticated shell `<div>`.
2. If you add a new persistent region that users must bypass, add an additional skip link or update the existing one.
3. Every page — authenticated or not — must contain exactly one `<main>` landmark. For the authenticated shell this is `<main id="main-content">` in `App.svelte`; for the pre-auth login/signup page this is `<main>` in `Auth.svelte`. Do not remove or replace these elements with a generic `<div>`.
4. All interactive elements that are not natively focusable must have `tabindex="-1"` (receive focus programmatically only) or `tabindex="0"` (enter the natural tab order). Never use `tabindex` values greater than `0`.
5. Do not remove the `tabindex="-1"` attribute from `<main id="main-content">`. It is required by both the skip link (WCAG 2.4.1) and the SPA navigation focus effect (WCAG 2.4.3). Without it, `element.focus()` silently no-ops in most browsers.
6. Every icon-only link or button must have `aria-label`; the icon element inside the control must carry `aria-hidden="true"` to suppress redundant announcements; every unlabelled input must have `aria-label` or `aria-labelledby`. See [Accessible labels for icon-only controls](#accessible-labels-for-icon-only-controls) above.
7. Navigation links that represent the active view must carry `aria-current={isActive ? "page" : undefined}`. Tab-style buttons should use `aria-selected` instead (see item 9). See [`aria-current` on active navigation links](#aria-current-on-active-navigation-links) above.
8. Toggle switches (`<input type="checkbox">` styled as a switch) must carry `role="switch"` **and** an explicit `aria-checked` attribute, with an explicit `for`/`id` label association. See [`role="switch"` on toggle inputs](#roleswitch-on-toggle-inputs) below.
9. Tab-style navigation widgets (a set of buttons that show/hide panels) must use the ARIA tablist/tab/tabpanel pattern with roving tabindex and keyboard navigation (Arrow keys, Home, End). See [ARIA tab widget — Login/Sign Up toggle](#aria-tab-widget--loginsign-up-toggle-authsvelte) for the reference implementation.
10. Data tables must have `scope="col"` (or `scope="row"`) on every `<th>`. Visual-only columns (e.g., "Actions") must have an `sr-only` text label inside their `<th>`. State-toggle buttons in table rows must use action-oriented `aria-label` values. Keep navigation on native links inside cells, and do not make `<tr>` elements keyboard-focusable controls (WCAG 2.1.1). See [Table accessibility](#table-accessibility) below.
11. Sidebar navigation groups must use `role="group"` with `aria-labelledby` pointing to a native `<h2>` heading so screen readers announce the section name. See [Labelled navigation groups](#labelled-navigation-groups-sidebarsvelte) above.
12. Page view components should include a native `<h1>` for their primary content state. Composite views that delegate to sub-components (e.g., `Libraries.svelte` → `LibraryView.svelte`) may have the `<h1>` in the sub-component; empty or transitional states may omit it. Persistent shell elements (sidebar, header, footer) must never contain an `<h1>`. See [Page heading hierarchy](#page-heading-hierarchy) above.
13. Never apply `opacity-0` to an element that can receive keyboard focus. Use `opacity-30` (or higher) as the minimum resting opacity so the element is visible when focused. When the action is context-sensitive (e.g. per-library settings links), include the context in the `aria-label` so each link has a unique, descriptive name. See [Focus visible — Library settings link](#focus-visible--library-settings-link-sidebarsvelte) above.
14. When using `TextInput` (or any input) with a `placeholder` on a dark background, use `dark:placeholder:text-ink-300` or lighter — never `dark:placeholder:text-ink-500` or darker on `dark:bg-ink-800`. See [Dark-mode placeholder contrast](#dark-mode-placeholder-contrast-textinputsvelte) above.
15. All form inputs and bordered interactive elements must use `border-ink-400 dark:border-ink-400` (or a higher-contrast token) for their default border. In light mode, do not use `border-ink-200` on `bg-white`; in dark mode, do not use `dark:border-ink-700` on `dark:bg-ink-800`. See [Form control border contrast](#form-control-border-contrast-textinputsvelte) above.
16. Run `pnpm run check` — `svelte-check` will surface missing `alt` attributes and other common issues.
17. Every icon that appears alongside visible text must carry `aria-hidden="true"` to suppress redundant screen-reader announcements. See [Decorative icons alongside visible text](#decorative-icons-alongside-visible-text) above.
18. Whenever a user action produces a transient status change without a focus move (e.g. selecting a theme, saving settings), add a `role="status"` `class="sr-only"` `<span>` live region to announce the outcome to screen readers (WCAG 4.1.3). Reset the text to `""` before setting the new message so repeated identical actions still trigger an announcement. See [Live region for theme change announcements](#live-region-for-theme-change-announcements-preferencestabsvelte) above.
19. Do not add animations or transitions that cannot be suppressed by the global `prefers-reduced-motion` rule in `index.css`. Tailwind animation utilities (e.g. `animate-fade-in`, `animate-spin`) and ordinary CSS animations, including custom `@keyframes` used from component `<style>` blocks, are suppressible via that global override. Add a component-level `@media (prefers-reduced-motion: reduce)` guard only when motion is driven outside normal CSS animation/transition rules (for example, via JavaScript) or when local `!important` styles would otherwise bypass the global override. See [Reduced-motion support](#reduced-motion-support-indexcss) above.
20. Never use `outline-none` on a focusable form input — always use `focus-visible:outline-none` combined with explicit `focus:ring-*` classes. `outline-none` removes the native focus ring for **all** interaction modes including keyboard, violating WCAG 2.4.7 Focus Visible. `focus-visible:outline-none` suppresses the browser-default outline when `:focus-visible` matches (keyboard-initiated focus), leaving the explicit `focus:ring-*` accent ring as the sole visible indicator for keyboard users. See [Focus ring on form inputs](#focus-ring-on-form-inputs-textinputsvelte-and-inline-inputs) above.

### Form accessibility

All form inputs must be programmatically associated with a visible label or carry a descriptive `aria-label`. `LibraryForm.svelte` serves as the canonical reference for these patterns.

#### Explicit `<label for>` / `id` pairing

Use an explicit `for`/`id` association for text inputs that have a visible label. This is the strongest and most broadly supported technique.

```svelte
<label for="lib-name" class="block text-sm font-medium …">Name</label>
<input id="lib-name" type="text" bind:value={formName} … />
```

Screen readers will announce the label text whenever the input receives focus.

#### Dynamic `aria-label` for repeated inputs

When a form contains a variable-length list of inputs of the same type (e.g. multiple folder-path fields), use a dynamic `aria-label` that includes the item's position so screen-reader users can distinguish them.

```svelte
{#each formPaths as entry, i}
  <input
    aria-label={formPaths.length === 1 ? "Folder path" : `Folder path ${i + 1}`}
    …
  />
{/each}
```

- Use the singular label (e.g. `"Folder path"`) when there is only one item — the ordinal is unnecessary and adds noise.
- Use a 1-based counter (e.g. `"Folder path 1"`, `"Folder path 2"`) when there are multiple items.

#### `aria-label` on icon-only controls

Links and buttons whose visible content is solely an icon (SVG) must carry an `aria-label` so assistive technologies announce an intelligible action name. The icon itself must also carry `aria-hidden="true"` to prevent screen readers from reading both the control label and the SVG's internal title.

```svelte
<!-- Close / cancel button -->
<button aria-label="Close form" onclick={navigateBack}>
  <X class="w-5 h-5" aria-hidden="true" />
</button>

<!-- Remove item button inside a list -->
<button aria-label="Remove folder" …>
  <X class="w-4 h-4" aria-hidden="true" />
</button>
```

When you add a new icon-only link or button, always supply both `aria-label` on the element and `aria-hidden="true"` on the icon component. `svelte-check` does **not** automatically detect missing labels or missing `aria-hidden`, so this must be reviewed manually.

#### `autocomplete` on credential inputs

**WCAG criterion:** [1.3.5 Identify Input Purpose](https://www.w3.org/WAI/WCAG21/Understanding/identify-input-purpose.html) (Level AA)

Password inputs must carry a valid `autocomplete` token so that password managers and autofill implementations can correctly identify the field's purpose. Without `autocomplete`, browsers may misclassify the fields, offer to save them as plain text, or fail to auto-fill them — degrading both usability and security.

`settings/AccountTab.svelte` uses three password fields with the following tokens:

```svelte
<!-- Current/existing password -->
<input type="password" autocomplete="current-password" … />

<!-- New password (set or confirm) -->
<input type="password" autocomplete="new-password" … />
<input type="password" autocomplete="new-password" … />
```

| Token | When to use |
|-------|-------------|
| `current-password` | The user's existing credential (used for verification before allowing a change) |
| `new-password` | A newly chosen password the user is setting or confirming |

**Do not** leave `type="password"` inputs without `autocomplete`. Browsers may still infer the purpose, but the explicit attribute is required by WCAG 1.3.5 and ensures reliable cross-browser behaviour.

#### `fieldset` and `legend` for grouped inputs

**WCAG criterion:** [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html) (Level A)

When a form contains a group of related inputs that share a common heading (e.g., a set of folder paths that all belong to "Folders"), wrap them in a `<fieldset>` with a `<legend>` instead of a plain `<div>` with a visual label. Screen readers announce the group's legend when focus enters any field inside it, giving users the context they need to understand the relationship.

```svelte
<fieldset class="border-none p-0 m-0">
  <legend class="block text-sm font-medium …">
    Folders <span aria-hidden="true">*</span>
  </legend>
  <div class="space-y-2">
    {#each formPaths as entry, i (entry.id)}
      <input
        type="text"
        aria-label={formPaths.length === 1 ? "Folder path" : `Folder path ${i + 1}`}
        …
      />
    {/each}
  </div>
</fieldset>
```

- The `<legend>` text becomes the accessible name for the entire group; all inputs inside are announced in context of it.
- Use `class="border-none p-0 m-0"` (or equivalent) to remove the browser's default `<fieldset>` border and padding while preserving the semantic grouping.
- The required-field asterisk (`*`) should carry `aria-hidden="true"` on its containing `<span>` so screen readers do not announce "asterisk" mid-sentence — mark required fields with `aria-required="true"` on the `<input>` instead.

#### `aria-describedby` for inline validation errors

**WCAG criterion:** [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html) / [3.3.1 Error Identification](https://www.w3.org/WAI/WCAG21/Understanding/error-identification.html) (Level A)

When an input has an associated error message that appears inline below it, use `aria-describedby` to link the input to the error element. Without this link, screen reader users hear the input's label but not the error — they must navigate to the error paragraph separately.

```svelte
<input
  id="lib-name"
  type="text"
  bind:value={formName}
  aria-required="true"
  aria-invalid={nameError ? true : undefined}
  aria-describedby={nameError ? "lib-name-error" : undefined}
/>
{#if nameError}
  <p id="lib-name-error" role="alert" class="text-sm text-danger-600 …">
    {nameError}
  </p>
{/if}
```

**Key points:**

| Attribute | Element | When to set |
|-----------|---------|-------------|
| `aria-invalid="true"` | `<input>` | When the field has a validation error |
| `aria-describedby="<error-id>"` | `<input>` | When the error element is visible |
| `id="<error-id>"` | Error `<p>` | Always — must match `aria-describedby` |
| `role="alert"` | Error `<p>` | Makes the error message announce immediately when it appears |

- Set `aria-invalid` and `aria-describedby` conditionally — only when the error is present. Passing `undefined` removes the attribute; passing `false` for `aria-invalid` is valid but adds noise and may confuse some screen readers.
- For grouped inputs (e.g., folder paths sharing a single error), point every input's `aria-describedby` to the shared error element's `id`.

#### `role="switch"` on toggle inputs

**WCAG criterion:** [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html) (Level A)

A visually styled toggle switch implemented with `<input type="checkbox">` does not automatically communicate its "switch" semantics to assistive technologies. Screen readers announce it as a plain checkbox, which is misleading when the control represents a binary on/off state rather than a multi-select option.

Add `role="switch"` **and** `aria-checked` to any `<input type="checkbox">` that renders as a toggle. `role="switch"` alone is insufficient — some assistive technologies cannot reliably infer the current state from the native `checked` property when the element has an overriding ARIA role; `aria-checked` makes the state explicit.

Use an explicit `for`/`id` association between the `<label>` and the input alongside `role="switch"` (supplementing any implicit wrapper-label approach) to maximize cross-browser screen reader compatibility:

```svelte
<label for="lib-monitored" class="…">Monitor for new content</label>
<input
  id="lib-monitored"
  type="checkbox"
  role="switch"
  aria-checked={formMonitored}
  bind:checked={formMonitored}
  class="sr-only peer"
/>
```

In Svelte 5 (runes mode), binding a boolean to `aria-checked` is correct: Svelte serializes `aria-*` attributes to their string representation (`"true"` / `"false"`) rather than removing them, so `aria-checked={false}` renders as `aria-checked="false"` as required by the ARIA spec.

With `role="switch"` and `aria-checked`, assistive technologies announce the control as a _switch_ and report its state as _on_ or _off_ (rather than _checked_ or _unchecked_), which is the semantically correct announcement for a toggle.

**Why `aria-checked` must be set explicitly**

`bind:checked` keeps the underlying `checked` DOM property in sync, but some screen reader and browser combinations do not reliably derive the `aria-checked` value from the DOM property when `role="switch"` is present. Setting `aria-checked` explicitly as an attribute ensures the state is always exposed correctly to the accessibility tree.

**Guidelines:**

- Apply `role="switch"` and `aria-checked={booleanState}` whenever a `<input type="checkbox">` is styled to look like a toggle switch.
- Always set `aria-checked` explicitly as an attribute bound to the same reactive variable as `bind:checked` (e.g. `aria-checked={myState}`). Do **not** rely solely on `bind:checked` to expose state, as some browser/screen reader combinations do not derive `aria-checked` from the DOM `checked` property when `role="switch"` is present.
- Use an explicit `<label for="…">` / `id="…"` association in addition to any implicit wrapper label.
- The control must still have an accessible name — either via a paired `<label>` element (preferred) or `aria-label`.
- Do **not** use `role="switch"` on checkboxes that genuinely represent a tri-state or multi-select option; use plain `type="checkbox"` there.

`LibraryForm.svelte` is the canonical reference implementation.

#### Checklist for new forms

When adding or editing a form component:

1. Every `<input>`, `<select>`, and `<textarea>` has either a `<label for="…">` or an `aria-label`.
2. `<label for>` values match the corresponding `id` exactly — a mismatch silently breaks the association.
3. Related inputs that share a common heading are wrapped in a `<fieldset>` with a `<legend>`. See [`fieldset` and `legend` for grouped inputs](#fieldset-and-legend-for-grouped-inputs) above.
4. Icon-only buttons (`<button>` with SVG content and no text) carry an `aria-label`.
5. Repeated inputs in `{#each}` blocks use a dynamic, positionally-distinct `aria-label`.
6. Inputs with inline validation errors set `aria-invalid="true"` and `aria-describedby="<error-id>"` when the error is visible. See [`aria-describedby` for inline validation errors](#aria-describedby-for-inline-validation-errors) above.
7. Password inputs (`type="password"`) carry `autocomplete="current-password"` or `autocomplete="new-password"` as appropriate.
8. Toggle switches (`<input type="checkbox">` styled as a switch) carry both `role="switch"` and `aria-checked={booleanState}`. Use an explicit `for`/`id` label association. See [`role="switch"` on toggle inputs](#roleswitch-on-toggle-inputs) above.
9. Tab-style widgets that show/hide panels use the ARIA tablist/tab/tabpanel pattern with roving tabindex, `aria-selected`, `aria-controls`/`aria-labelledby`, and keyboard navigation (Arrow keys, Home, End). See [ARIA tab widget — Login/Sign Up toggle](#aria-tab-widget--loginsign-up-toggle-authsvelte) for the reference implementation.
10. Form inputs use `border-ink-400 dark:border-ink-400` for their border — in light mode, avoid `border-ink-200` on `bg-white`; in dark mode, avoid `dark:border-ink-700` on `dark:bg-ink-800`. Prefer the reusable `TextInput` component; when writing an inline `<input>` directly, apply this class manually. See [Form control border contrast](#form-control-border-contrast-textinputsvelte) above.
11. Run `pnpm run check` after your changes — `svelte-check` will catch missing `alt` on images and some label issues.

### Inline confirmation dialogs for destructive actions

**WCAG criterion:** [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html) / [2.1.1 Keyboard](https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html) / [3.3.4 Error Prevention](https://www.w3.org/WAI/WCAG21/Understanding/error-prevention-legal-financial-data.html) (Level A / AA)

Destructive actions such as deleting an API key or Kobo sync token must not use `window.confirm()`. The browser's native confirm dialog has no ARIA role, no focus management, is not styleable, and produces inconsistent screen reader behaviour across browsers. Instead, render an inline `role="alertdialog"` directly in the component.

#### Pattern

Use a piece of reactive state (`pendingDeleteKey`, `pendingDeleteToken`, etc.) to track which item is pending deletion. When the user clicks the initial delete trigger, set that state; the row or card swaps its delete button for an inline confirmation:

```svelte
<script lang="ts">
  import { tick } from "svelte";
  import { autofocusFirstButton } from "../../lib/actions";

  let pendingDeleteItem: { id: string; name: string } | null = $state(null);

  function handleDeleteItem(id: string, name: string) {
    pendingDeleteItem = { id, name };
  }

  async function confirmDeleteItem() {
    if (!pendingDeleteItem) return;
    const { id } = pendingDeleteItem;
    pendingDeleteItem = null;
    await deleteItem(id); // your API call
    // filter item from list…
  }

  async function cancelDeleteItem() {
    const id = pendingDeleteItem?.id; // capture id BEFORE clearing state
    pendingDeleteItem = null;
    await tick();
    // Return focus to the trigger button after cancellation
    document.querySelector<HTMLElement>(`[data-delete-trigger="${id}"]`)?.focus();
  }
</script>

{#if pendingDeleteItem?.id === item.id}
  <div
    role="alertdialog"
    aria-modal="false"
    aria-labelledby={`confirm-label-${item.id}`}
    tabindex="-1"
    use:autofocusFirstButton
    onkeydown={(e: KeyboardEvent) => { if (e.key === "Escape") cancelDeleteItem(); }}
  >
    <span id={`confirm-label-${item.id}`}>Delete "{item.name}"?</span>
    <button onclick={confirmDeleteItem}>Delete</button>
    <button onclick={cancelDeleteItem}>Cancel</button>
  </div>
{:else}
  <button
    data-delete-trigger={item.id}
    onclick={() => handleDeleteItem(item.id, item.name)}
    aria-label={`Delete ${item.name}`}
  >Delete</button>
{/if}
```

**Preferred approach:** Use the [`DeleteConfirmation.svelte`](#deleteconfirmationsvelte) UI component — it encapsulates the `role="alertdialog"`, autofocus, and Escape-to-dismiss boilerplate so you only need to supply `itemId`, `itemName`, `onConfirm`, and `onCancel`. `LibraryForm.svelte`, `APIKeysTab.svelte`, and `KoboTab.svelte` are the canonical reference implementations.

If you cannot use `DeleteConfirmation` (e.g., the confirmation UI needs a non-standard layout), implement the inline pattern manually using the code skeleton above as a starting point.

#### `autofocusFirstButton` Svelte action (`lib/actions.ts`)

`autofocusFirstButton` is a Svelte action that moves keyboard focus to the first `<button>` inside a container after the next microtask, ensuring child elements have rendered before focus is requested:

```ts
import { autofocusFirstButton } from "../../lib/actions"; // adjust path to match your component's depth

// In a template:
// <div use:autofocusFirstButton>…</div>
```

Apply `use:autofocusFirstButton` to the confirmation dialog container so focus is moved into it automatically when it mounts. This satisfies the keyboard-focus management requirement for modal and inline dialog patterns.

**Note:** `autofocusFirstButton` focuses the first `<button>` in DOM order. If you want focus to land on the safer Cancel option, place Cancel before Delete in the DOM. The current implementations focus the Delete button first; this is a known P2 issue.

#### Guidelines

- Never use `window.confirm()` for destructive confirmations.
- Use `role="alertdialog"` (not `role="dialog"`) for inline confirmations — `alertdialog` causes screen readers to announce its content immediately.
- Always capture the pending item's `id` into a local variable **before** clearing the pending state in cancel handlers; clearing state first causes `querySelector` to search for `[data-delete-trigger="undefined"]` and silently drops focus.
- Add `use:autofocusFirstButton` to the dialog container so keyboard focus enters the dialog when it opens.
- Add an `onkeydown` Escape handler to dismiss the dialog; call the cancel function.
- Add `data-delete-trigger` on the original trigger button so focus can be restored on cancel (WCAG 2.4.3 Focus Order).
- Keep only one confirmation dialog open at a time — the pending state should be a single nullable value, not an array.

### Table accessibility

**WCAG criterion:** [1.3.1 Info and Relationships](https://www.w3.org/WAI/WCAG21/Understanding/info-and-relationships.html) (Level A)

Data tables must programmatically associate each header cell with the data cells it describes. Without this association, screen readers announce cell contents as isolated values with no column or row context.

#### `scope` attribute on column headers

Add `scope="col"` to every `<th>` that acts as a column header:

```svelte
<thead>
  <tr>
    <th scope="col">Title</th>
    <th scope="col">Publisher</th>
    <th scope="col">Language</th>
    <th scope="col">Pages</th>
  </tr>
</thead>
```

When a `<th>` spans rows instead of columns (a row header), use `scope="row"`. For most flat, non-hierarchical tables in Biblioteka, `scope="col"` is sufficient.

`UsersTab.svelte` is the canonical reference implementation: its "Name", "Email", "Type", "Role", and "Joined" headers all carry `scope="col"`.

#### Accessible label for visual-only header cells

An "Actions" column typically has no visible heading — its purpose is implied by the buttons in each row. A blank `<th>` is still announced by screen readers (often as an empty cell), which can be confusing. Use an `sr-only` span to provide a descriptive label that sighted users cannot see:

```svelte
<th scope="col">
  <span class="sr-only">Actions</span>
</th>
```

- Do **not** leave a `<th>` completely empty. An empty header cell gives screen-reader users no context for the column.
- `sr-only` is a Tailwind utility (equivalent to `position: absolute; width: 1px; height: 1px; overflow: hidden; …`) that hides the text visually while keeping it in the accessibility tree.

#### Checklist for new tables

When adding a data table component:

1. Every column `<th>` has `scope="col"`.
2. Columns whose purpose is visually implied (e.g., "Actions") have `<span class="sr-only">Actions</span>` inside their `<th>`.
3. If a `<th>` spans rows, it has `scope="row"`.
4. Do not use `<td>` for header cells — use `<th scope="…">` so the relationship is semantically clear.
5. Inline state-toggle buttons (whose visible text reflects the current state) must carry an action-oriented `aria-label` so screen-reader users hear what the button will *do*, not just what the current state *is*. See [Action-oriented labels for state-toggle buttons](#action-oriented-labels-for-state-toggle-buttons) below.
6. If a row includes navigation, keep it on native links inside cells. Do not make `<tr>` itself interactive with `tabindex`, `onclick`, or keyboard handlers. Use visible `focus:*` styles on the link (WCAG 2.1.1). See [Keyboard navigation in BookList table view](#keyboard-navigation-in-booklist-table-view-booklistsvelte) above.

#### Action-oriented labels for state-toggle buttons

**WCAG criterion:** [4.1.2 Name, Role, Value](https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html) (Level A)

When a table row contains a button whose visible text describes the *current state* of the row (e.g. "Admin" / "User"), screen-reader users hear only the state — they cannot tell what action the button will perform. Use `aria-label` to give the button an *action-oriented* accessible name that names both the operation and its target.

```svelte
<button
  onclick={() => toggleAdmin(u)}
  aria-label={u.is_admin
    ? `Remove admin role from ${u.name || u.email}`
    : `Grant admin role to ${u.name || u.email}`}
>
  {u.is_admin ? "Admin" : "User"}
</button>
```

Key points:

- The visible button text keeps its **state-description** role for sighted users.
- The `aria-label` overrides the accessible name with the **action** the button will perform and the **target** it will affect (by name, falling back to email if the display name is absent).
- Use `u.name || u.email` (not just `u.name`) so the label remains meaningful for accounts that have no display name.
- After the toggle completes, Svelte reactively recomputes `u.is_admin`, so the `aria-label` automatically switches to the opposite operation on the next render — no manual state management is required.

`UsersTab.svelte` is the canonical reference implementation: its role-toggle button uses exactly this pattern.

**Do not** use the current-state text alone as the accessible name:

```svelte
<!-- ✗ Announces "Admin" — tells the user the state, not the action -->
<button onclick={() => toggleAdmin(u)}>
  {u.is_admin ? "Admin" : "User"}
</button>
```

**Do** add an action-oriented `aria-label`:

```svelte
<!-- ✓ Announces "Remove admin role from Alice" — tells the user what will happen -->
<button
  onclick={() => toggleAdmin(u)}
  aria-label={u.is_admin
    ? `Remove admin role from ${u.name || u.email}`
    : `Grant admin role to ${u.name || u.email}`}
>
  {u.is_admin ? "Admin" : "User"}
</button>
```

### Accessibility tests

Accessibility regressions are locked in by dedicated test files. Keep all of these tests green. If you restructure a component, update its test to match.

#### `App.test.ts`

`frontend/src/App.test.ts` verifies the authenticated shell:

- `document.title` is set from `routerStore.pageTitle` on mount (WCAG 2.4.2).
- The skip link exists and has the label _"Skip to main content"_.
- The `<main>` landmark has `id="main-content"`.
- The skip link appears **before** the sidebar in DOM order.
- Clicking the skip link moves keyboard focus to `<main>`.
- Keyboard focus is **not** moved to `<main>` on initial mount — the `focusEffectMounted` guard prevents the focus effect from running on first render so a hard refresh does not steal focus from the browser UI (WCAG 2.4.3).

#### `Auth.test.ts`

`frontend/src/components/Auth.test.ts` verifies the ARIA tab widget on the login/signup page (WCAG 4.1.2). It uses `@testing-library/user-event` to simulate real browser interactions and `await tick()` to flush Svelte 5 reactivity before asserting. Three tests are included:

1. **`has a main landmark region`** — asserts the login page exposes a `<main>` landmark (WCAG 1.3.6).
2. **`renders tab buttons with correct ARIA attributes`** — asserts the `role="tablist"` container is present and that each tab carries the correct `aria-selected` and `aria-controls` attributes on initial render.
3. **`renders tab panels with correct ARIA attributes`** — asserts both `role="tabpanel"` elements (including the hidden one) carry the correct `aria-labelledby` back-reference.
4. **`switches ARIA state when the Sign Up tab is clicked`** — simulates a user click on the Sign Up tab and verifies that `aria-selected` values update reactively and the Sign Up panel loses its `hidden` attribute.

> **Testing note:** Each test wraps `render(Auth)` in an `async renderAuth()` helper that calls `await tick()` after mounting. This is necessary because Svelte 5 defers reactive updates; without the tick the DOM may not reflect the initial `$state` values when the first `expect` runs. The `afterEach(cleanup)` guard ensures the JSDOM is cleared between tests to prevent state bleed.

#### `Sidebar.test.ts`

`frontend/src/components/Sidebar.test.ts` verifies that the navigation sidebar uses semantic `<a>` anchor links (not `<button>` elements) for in-app navigation, that `aria-current` state is applied correctly (WCAG 4.1.2), and that library-settings links meet accessibility requirements (WCAG 2.4.6, 2.4.7). Eight tests are included:

1. **`renders Dashboard, All Books, and Settings as links with correct hrefs`** — asserts that the three primary nav items are rendered as `role="link"` elements with the correct hash `href` values (`#dashboard`, `#books`, `#settings`).
2. **`renders Logout as a button, not a link`** — asserts that Logout is a `role="button"` element, which is semantically correct because it triggers an action (sign-out) rather than navigating to a URL.
3. **`sets aria-current='page' on the active navigation link`** — renders with `currentView="settings"` and asserts that the Settings link carries `aria-current="page"` while Dashboard does not.
4. **`sets aria-current='page' on the active library link`** — renders with `currentView="libraries"` and `subPath="1"` and asserts that only the matching library entry link receives `aria-current="page"`.
5. **`library settings links include the library name in aria-label (WCAG 2.4.6)`** — renders with two mock libraries and asserts each Library-settings link has a unique `aria-label` that includes the library name (e.g., "Library settings for Fiction") so screen readers can distinguish between them (WCAG 2.4.6 Headings and Labels).
6. **`library settings links are not fully transparent by default (WCAG 2.4.7)`** — asserts that the Library-settings link does not carry `opacity-0` and instead carries `opacity-30`, ensuring the element is perceivable when focused by keyboard (WCAG 2.4.7 Focus Visible).
7. **`renders navigation group labels as headings`** — renders with `currentView="dashboard"` and asserts that the "Home" and "Libraries" group labels are exposed as `role="heading"` elements at level 2 (WCAG 1.3.1).
8. **`does not render the app name as a heading`** — asserts that the brand name ("Biblioteka") is rendered as a `<p>` element, not an `<h1>`, so it does not create a duplicate top-level heading (WCAG 1.3.1).

> **Mocking note:** The test file mocks `authStore`, `libraryStore`, `api.getVersion`, and all `lucide-svelte` icon components. The icon mocks are necessary because Lucide icons are ESM-only packages that cannot render in JSDOM; replacing them with no-ops keeps the test focused on DOM structure. `afterEach(cleanup)` prevents DOM leakage between tests.

#### `Dashboard.test.ts`

`frontend/src/components/Dashboard.test.ts` verifies the behavior and accessibility of the home screen, covering the onboarding empty state, the stats grid, the Reading Activity section, and the Year in Books section. Thirty-two tests in one `Dashboard` describe block (with a nested `Year in Books` describe block):

1. **`renders the Dashboard heading`** — asserts a `<h1>` heading with text `"Dashboard"` is present on mount.
2. **`shows the onboarding card when libraries are loaded and empty`** — seeds `libraryStore.loaded = true` with no libraries; asserts the `"Get started with Biblioteka"` heading is rendered.
3. **`shows 'Add Your First Library' button in empty state`** — same setup; asserts the onboarding call-to-action button is visible.
4. **`navigates to libraries/setup when the onboarding button is clicked`** — clicks the button; asserts `routerStore.navigate` is called with `"libraries/setup"`.
5. **`shows stats grid when libraries exist`** — seeds one library; asserts "Total Books" and "Libraries" stat labels appear and no unexpected stats are rendered.
6. **`does not show the onboarding card when libraries exist`** — seeds one library; asserts the "Get started" heading is absent.
7. **`uses semantic dl/dt/dd structure for stat cards`** — asserts each stat uses a `<dl>/<dt>/<dd>` description-list structure so screen readers can announce the label–value pairs correctly (WCAG 1.3.1).
8. **`shows the library count in the stats grid`** — seeds two libraries; asserts the numeric value `"2"` is rendered in the stats grid.
9. **`triggers libraryStore.load() when libraries are not yet loaded`** — mounts with `libraryStore.loaded = false`; asserts `libraryStore.load` is called.
10. **`shows loading placeholder while total books is being fetched`** — `getTotalBooksCount` never resolves; asserts the placeholder text `"…"` is visible while the request is in flight.
11. **`shows the real total books count after fetching`** — `getTotalBooksCount` resolves to `500`; asserts the value `"500"` appears in the stats grid and `getTotalBooksCount` was called.
12. **`shows the downloads histogram when data is available`** — `getDownloadsPerMonth` resolves with two data points; asserts the `data-testid="downloads-histogram-card"` element appears in the DOM.
13. **`shows a downloads error banner when the stats fetch fails`** — `getDownloadsPerMonth` rejects with `Error("network error")`; asserts the error message `"network error"` is rendered in an `AlertBanner`.

**Reading Activity section — nine tests:**

14. **`shows Reading Activity heading when stats load`** — seeds one library; `getReadingProgressStats` resolves with a zeroed stats object; asserts the `"Reading Activity"` heading is present after stats load.
15. **`shows KOSync nudge when total_tracked is 0`** — `getReadingProgressStats` resolves with `total_tracked: 0`; asserts the `"No reading activity recorded yet"` nudge text is rendered.
16. **`shows streak badge when current_streak > 0`** — `getReadingProgressStats` resolves with `current_streak: 5`; asserts the `"5-day streak"` badge is visible.
17. **`shows finished books badge when total_finished > 0`** — `getReadingProgressStats` resolves with `total_finished: 2`; asserts the `"2 books finished"` badge is visible.
18. **`uses accessible contrast classes for tracked documents text`** — `getReadingProgressStats` resolves with `total_tracked: 2`; asserts the tracked-documents count element carries `text-ink-500` and `dark:text-ink-300` Tailwind classes (WCAG 1.4.3).
19. **`shows Currently Reading list with document names`** — `getReadingProgressStats` resolves with one in-progress item (`document: "my-great-book"`, `percentage: 0.42`, `device: "KOReader"`); asserts the document name, `"42%"`, and `"KOReader"` are all rendered.
20. **`shows estimated time remaining when provided`** — `getReadingProgressStats` resolves with `estimated_minutes_remaining: 45`; asserts the `"~45m left"` label is rendered.
21. **`does not show reading activity section while stats are still loading`** — `getReadingProgressStats` never resolves; asserts the `"Reading Activity"` heading is absent and the welcome fallback is shown instead.
22. **`shows a reading stats error banner when the fetch fails`** — `getReadingProgressStats` rejects with `Error("reading stats unavailable")`; asserts the error message is rendered in an `AlertBanner` and the `"Welcome to Biblioteka"` fallback heading is **not** shown alongside it.

**Year in Books — five tests (test #23 at top-level; tests 24–27 in nested `describe("Year in Books")`):**
23. **`shows a year-in-books error banner when the fetch fails`** — `getYearInBooks` rejects with `Error("year in books unavailable")`; asserts the error message is rendered in an `AlertBanner`.
24. **`does not show year-in-books card when all stats are zero`** — `getYearInBooks` resolves with all-zero stats; asserts `data-testid="year-in-books-card"` is absent.
25. **`shows year-in-books card when there are books finished`** — `getYearInBooks` resolves with `books_finished: 3, active_days: 20, longest_streak: 5, total_downloads: 8`; asserts the `"2026 in Books"` heading, the counts, and the `"books finished"` / `"days reading"` labels are all rendered.
26. **`shows year-in-books card when there are downloads only`** — `getYearInBooks` resolves with `books_finished: 0, active_days: 0, total_downloads: 5`; asserts the card renders (non-zero downloads trigger display).
27. **`uses singular 'book' when exactly one book is finished`** — `getYearInBooks` resolves with `books_finished: 1`; asserts the label reads `"book finished"` (singular).

**Onboarding skipped-state — five tests:**

28. **`shows 'Add Your First Library' button when libraries are empty and not skipped`** — `onboardingStore.isSkipped` returns `false`; asserts the "Get started with Biblioteka" wizard entry card and the "Add Your First Library" button are rendered.
29. **`shows 'No libraries yet' heading when libraries are empty and skipped`** — `onboardingStore.isSkipped` returns `true`; asserts the subtle `"No libraries yet"` heading appears instead of the wizard card.
30. **`shows 'Set up your first library' button in skipped state`** — skipped state; asserts the `"Set up your first library"` secondary action button is rendered.
31. **`navigates to libraries/setup from the skipped-state button`** — skipped state; clicks the secondary button; asserts `routerStore.navigate` is called with `"libraries/setup"`.
32. **`does not show the 'Get started' wizard card in skipped state`** — skipped state; asserts the prominent `"Get started with Biblioteka"` card is absent.

> **Mocking note:** `libraryStore` (from `../stores/libraries.svelte`), `routerStore` (from `../stores/router.svelte`), `onboardingStore` (from `../stores/onboarding.svelte`), `authStore` (from `../stores/auth.svelte`), `getTotalBooksCount`, `getDownloadsPerMonth`, `getReadingProgressStats`, `getYearInBooks`, and `getRecommendations` (all from `../lib/api`) and all `lucide-svelte` icons are mocked. `beforeEach` resets `libraryStore.loaded` and `libraries`, and resets the API mocks to their default resolved values. `afterEach` calls `cleanup()` and `vi.clearAllMocks()` to prevent state leakage between tests.

#### `LibraryForm.test.ts`

`frontend/src/components/libraries/LibraryForm.test.ts` verifies the accessibility attributes on the library create/edit form (WCAG 1.3.1, 3.3.1, 4.1.2). Tests are organised in three `describe` blocks.

**"LibraryForm accessibility" — six tests:**

1. **`marks the name input as aria-required`** — asserts the `#lib-name` text input carries `aria-required="true"`.
2. **`marks folder path inputs as aria-required`** — asserts the folder path input carries `aria-required="true"`.
3. **`shows required indicator (*) on Name and Folders labels`** — asserts both the `<label for="lib-name">` and the `<fieldset>` legend contain a `<span aria-hidden="true">` with text `*`, so the required indicator is visible but not read aloud by screen readers (the `aria-required` attribute serves as the machine-readable signal instead).
4. **`shows inline name error with aria-invalid when submitting empty name`** — submits the form with no name, then asserts the name input is marked `aria-invalid="true"`, references the error via `aria-describedby="lib-name-error"`, and that the error element carries `role="alert"` so it is announced immediately by assistive technologies.
5. **`shows inline folder error with aria-invalid when submitting empty paths`** — fills in the name (to pass name validation) then submits with no folder paths; asserts the folder input becomes `aria-invalid="true"` with `aria-describedby="lib-folders-error"` and the error element carries `role="alert"`.
6. **`does not show aria-invalid or error messages before submission`** — asserts that neither `aria-invalid` nor the error message elements are present on initial render, preventing premature error announcements.
7. **`associates the switch input with its label via for/id`** — asserts that the monitor toggle input has `id="lib-monitored"` and that a `<label>` element with `for="lib-monitored"` is present, verifying the explicit label association required by WCAG 1.3.1.
8. **`has aria-checked reflecting the unchecked state by default`** — asserts the monitor toggle carries `aria-checked="false"` on initial render (formMonitored defaults to `false`).
9. **`updates aria-checked when toggled`** — simulates a click on the monitor toggle and asserts `aria-checked` updates to `"true"`, verifying that the attribute stays in sync with the bound state.
10. **`renders the organization type dropdown`** — asserts a `<select>` element for the file organization setting is present in the form.
11. **`has three options with correct values`** — asserts the organization dropdown contains exactly the three options `book_per_folder`, `book_per_file`, and `none`.
12. **`defaults to book_per_folder in create mode`** — asserts the organization dropdown defaults to `book_per_folder` when the form is used to create a new library.
13. **`has a label with text File Organization`** — asserts the organization dropdown is paired with a visible label containing the text "File Organization".

**"LibraryForm monitor toggle switch" — three tests:**

1. **`associates the switch input with its label via for/id`** — asserts the `#lib-monitored` checkbox is linked to its visible label by the `for`/`id` pairing and carries `role="switch"`.
2. **`has aria-checked reflecting the unchecked state by default`** — asserts the unchecked toggle exposes `aria-checked="false"` as a DOM attribute (not just the `checked` property).
3. **`updates aria-checked when toggled`** — fires a click on the input; asserts both `input.checked` becomes `true` and `aria-checked` updates to `"true"`.

**"LibraryForm organization type dropdown" — four tests:** verify that the file-organization `<select>` renders with the correct options, defaults to `book_per_folder` in create mode, and is associated with a visible label.

> **Testing note:** Each test calls `await tick()` after `render()` to flush Svelte 5 reactive state before asserting. `afterEach(cleanup)` removes the rendered component from JSDOM between tests.

#### `FirstLibraryWizard.test.ts`

`frontend/src/components/libraries/FirstLibraryWizard.test.ts` verifies the step-by-step flow, validation, accessibility, and skip behavior of the first-library setup wizard. Tests are organized in five `describe` blocks.

**"FirstLibraryWizard – step 1 (name)" — eight tests:**

1. **`renders the wizard with data-testid`** — asserts the root element carries `data-testid="first-library-wizard"`.
2. **`renders step 1 heading 'Name your library'`** — asserts the `<h1>` heading text matches the step title.
3. **`renders the 'Skip for now' button on step 1`** — asserts the skip button is visible on the first step.
4. **`renders a 'Next' button on step 1`** — asserts the Next navigation button is present.
5. **`does not render a 'Back' button on step 1`** — asserts Back is absent on the first step (no previous step).
6. **`'Next' on step 1 with empty name shows a validation error`** — clicks Next with an empty name field; asserts the inline error message is rendered.
7. **`name input carries aria-invalid when validation fails`** — after a failed Next click, asserts `aria-invalid="true"` on the name input so screen readers surface the error.
8. **`'Next' with a valid name advances to step 2`** — types a name, clicks Next; asserts the step-2 heading `"Choose folders"` appears.

**"FirstLibraryWizard – step 2 (paths)" — four tests:**

1. **`renders the folder path input on step 2`** — asserts a text input labelled `"Folder path"` is present.
2. **`'Next' on step 2 with no paths shows a validation error`** — submits an empty path; asserts the `"At least one folder is required"` error.
3. **`'Back' returns to step 1`** — clicks Back; asserts the step-1 heading reappears.
4. **`'Next' with a valid path advances to step 3`** — types a path, clicks Next; asserts the step-3 heading `"Configure options"` appears.

**"FirstLibraryWizard – step 3 (options)" — three tests:**

1. **`renders the organization type select on step 3`** — asserts the file-organization `<select>` is present.
2. **`renders the monitor toggle on step 3`** — asserts the "Monitor for new content" toggle input is present.
3. **`'Next' on step 3 advances to step 4 (review)`** — clicks Next; asserts the step-4 heading `"Review & create"` appears.

**"FirstLibraryWizard – step 4 (review & create)" — eight tests:**

1. **`shows the review step heading`** — asserts the `"Review & create"` `<h1>` is present.
2. **`shows the library name in the review`** — asserts the entered name is rendered in the review `<dl>`.
3. **`shows the folder path in the review`** — asserts the entered path is rendered.
4. **`shows the 'Create Library' button`** — asserts the Create Library submit button is visible.
5. **`does not show a 'Next' button on step 4`** — asserts Next is absent on the last step.
6. **`calls libraryStore.add with the correct args on create`** — clicks Create Library; asserts `libraryStore.add` is called with `{ name, paths, organization_type, monitored }`.
7. **`navigates to the new library after successful creation`** — `libraryStore.add` resolves with a fixture library; asserts `routerStore.navigate` is called with `"libraries/lib-new"`.
8. **`shows an error banner and stays on step 4 when creation fails`** — `libraryStore.add` rejects with `Error("server error")`; asserts an `AlertBanner` with the error text is rendered and the step does not advance.

**"FirstLibraryWizard – skip" — two tests:**

1. **`'Skip for now' calls onboardingStore.skip with the userId`** — clicks Skip; asserts `onboardingStore.skip` is called with `"user-1"`.
2. **`'Skip for now' navigates to dashboard`** — clicks Skip; asserts `routerStore.navigate` is called with `"dashboard"`.

> **Mocking note:** The test file mocks `libraryStore`, `routerStore`, `authStore` (user with `id: "user-1"`), `onboardingStore`, and all `lucide-svelte` icon components. `afterEach(cleanup)` prevents DOM leakage between tests.

#### `ReadingListDetail.test.ts`

`frontend/src/components/reading-lists/ReadingListDetail.test.ts` verifies the full lifecycle of reading list detail interactions: display, editing, deletion, error surfacing, and pagination. Eight tests in one `ReadingListDetail` describe block:

1. **`renders the reading list from the store`** — seeds `readingListStore.lists` with a fixture list; asserts the `<h1>` heading shows the list name, the book count `"26 books"` is rendered, and the description text appears.
2. **`loads lists when the store is not loaded`** — mounts with `readingListStore.loaded = false`; asserts `readingListStore.load` is called once.
3. **`saves edits through the reading list store`** — clicks Edit, types an updated name and description (with surrounding whitespace), clicks Save; asserts `readingListStore.update` is called with the trimmed values.
4. **`surfaces save API errors in the edit form`** — `readingListStore.update` rejects with `Error("Name already taken")`; clicks Save; asserts a `role="alert"` element shows the error and the `"Edit Reading List"` heading remains visible (form stays open).
5. **`cancels editing and restores original values when editing is restarted`** — types a temporary name change, clicks Cancel, then clicks Edit again; asserts the name input has reverted to the original value.
6. **`shows delete confirmation and deletes the list on confirm`** — clicks Delete; asserts the `"Delete this list?"` confirmation text appears and the confirm button receives focus; clicks `"Yes, delete"`; asserts `readingListStore.remove` is called with the list ID and `routerStore.navigate` is called with `"reading-lists"`.
7. **`surfaces delete API errors in the component error state`** — `readingListStore.remove` rejects with `Error("Delete failed")`; clicks Delete and confirms; asserts a `role="alert"` element shows the error and the confirmation dialog is dismissed.
8. **`renders paginated books and requests the next page`** — `listReadingListBooks` returns a total of 50 books; asserts the first page book appears; clicks Next; asserts `listReadingListBooks` is called with `offset=24`.

> **Mocking note:** The test file mocks `listReadingListBooks` (from `../lib/api`), `readingListStore` (from `../stores/reading-lists.svelte`), `routerStore` (from `../stores/router.svelte`), and all `lucide-svelte` icon components. `beforeEach` seeds `readingListStore.lists` with a fixture list and resets mock state. `afterEach` calls `cleanup()` and `vi.clearAllMocks()`.

#### `TextInput.test.ts`

`frontend/src/components/ui/TextInput.test.ts` verifies ARIA forwarding and accessibility-critical styling on the reusable text input (WCAG 1.4.3, 4.1.2). The key accessibility test:

1. **`uses ink-300 for dark-mode placeholder contrast (WCAG 1.4.3)`** — renders `TextInput` without a `disabled` prop and asserts the class string of the underlying `<input>` contains `dark:placeholder:text-ink-300` and does **not** contain `dark:placeholder:text-ink-500`. This pins the contrast fix introduced in PR #1512 and prevents regressions.

2. **`forwards placeholder attribute`** — asserts a `placeholder` prop is applied to the underlying element.
3. **`forwards aria-describedby attribute`** — asserts the ARIA attribute reaches the underlying element, enabling inline error association patterns.
4. **`forwards id attribute`** — asserts `id` forwarding so explicit `<label for>` associations work correctly.

> **Testing note:** `afterEach(cleanup)` removes rendered components between tests.

#### `Button.test.ts`

`frontend/src/components/ui/Button.test.ts` verifies rendering, variant classes, size classes, and interaction behavior of the reusable button component. Sixteen tests in one `Button` describe block:

1. **`renders a button element`** — asserts the component renders a `<button>` in the DOM.
2. **`renders children content`** — asserts the `children` snippet is rendered inside the button.
3. **`defaults to type='button'`** — asserts the `type` attribute is `"button"` when not specified.
4. **`forwards the type prop to the button element`** — renders with `type="submit"` and asserts the attribute reaches the underlying element.
5. **`applies primary variant gradient classes by default`** — asserts the button carries `bg-gradient-to-r` and `from-accent-600` classes when no `variant` is passed.
6. **`applies secondary variant classes`** — renders with `variant="secondary"`; asserts `border` is present and `bg-gradient-to-r` is absent.
7. **`applies danger variant classes`** — renders with `variant="danger"`; asserts the button carries `bg-danger-600`.
8. **`is not disabled by default`** — asserts the button is not disabled without the `disabled` prop.
9. **`disables the button when disabled prop is true`** — renders with `disabled={true}`; asserts the button element is disabled.
10. **`includes the disabled cursor Tailwind variant class`** — asserts the button's class string contains `disabled:cursor-not-allowed`. The class is always present in the markup, but the `disabled:` Tailwind variant means it only takes effect when the button is actually disabled.
11. **`calls onclick handler when clicked`** — attaches a `vi.fn()` handler; fires a click; asserts the handler was called once.
12. **`does not fire onclick when button is disabled (userEvent respects disabled)`** — renders with `disabled={true}`; uses `userEvent.setup().click()`; asserts the handler was **not** called, confirming that `userEvent` respects the native disabled state.
13. **`appends the extra class string to the button`** — renders with `class="my-extra-class"`; asserts the class appears on the button element.
14. **`applies md size classes by default`** — asserts the button carries `px-4`, `py-2.5`, and `text-sm` when no `size` prop is passed.
15. **`applies sm size classes when size='sm'`** — renders with `size="sm"`; asserts the button carries `px-3`, `py-1.5`, and `text-xs`.
16. **`includes justify-center for centered content`** — asserts the button's class string contains `justify-center`, confirming that icon-and-label content is centered horizontally.

> **Testing note:** `afterEach(cleanup)` removes rendered components between tests.

#### `APIKeysTab.test.ts`

`frontend/src/components/settings/APIKeysTab.test.ts` verifies the inline destructive confirmation dialog in the API keys settings tab (WCAG 2.1.1, 3.3.4, 4.1.2). Seven tests in the **"APIKeysTab delete confirmation"** `describe` block:

1. **`does not call deleteAPIKey when Delete button is clicked (shows confirmation instead)`** — clicks the delete trigger for an API key and asserts `deleteAPIKey` is **not** called, confirming that no deletion occurs until the user confirms.
2. **`shows inline confirmation dialog when Delete is clicked`** — clicks the delete trigger and asserts the `role="alertdialog"` confirmation panel appears in the DOM.
3. **`dismisses confirmation dialog when Cancel is clicked`** — opens the confirmation, then clicks Cancel; asserts the dialog is removed from the DOM.
4. **`calls deleteAPIKey after confirming deletion`** — opens the confirmation, clicks the confirm Delete button, and asserts `deleteAPIKey` is called with the correct key ID.
5. **`only shows confirmation for the clicked key, not all keys`** — seeds two API keys, clicks delete on the first, and asserts the dialog appears only for that key while the second key row remains unaffected.
6. **`dismisses confirmation dialog when Escape is pressed`** — opens the confirmation dialog, dispatches a `keydown` event with `key="Escape"`, and asserts the dialog is removed.
7. **`moves focus to the Delete confirm button when dialog opens`** — opens the confirmation dialog and asserts the Delete button inside the `alertdialog` receives focus, verifying the `autofocusFirstButton` action is working.

> **Mocking note:** The test file mocks `api.listAPIKeys` (returns two pre-seeded keys), `api.createAPIKey`, `api.deleteAPIKey` (resolves immediately), `clipboard.copyToClipboard`, and all `lucide-svelte` icon components. `afterEach` calls `cleanup()` and `vi.clearAllMocks()` to prevent state leakage between tests.

#### `KoboTab.test.ts`

`frontend/src/components/settings/KoboTab.test.ts` verifies the inline destructive confirmation dialog in the Kobo token settings tab (WCAG 2.1.1, 3.3.4, 4.1.2). Seven tests in the **"KoboTab delete confirmation"** `describe` block, mirroring the structure of `APIKeysTab.test.ts`:

1. **`does not call deleteKoboToken when Delete button is clicked (shows confirmation instead)`** — asserts deletion does not fire on the first click.
2. **`shows inline confirmation dialog when Delete is clicked`** — asserts the `role="alertdialog"` panel appears.
3. **`dismisses confirmation dialog when Cancel is clicked`** — asserts Cancel hides the dialog.
4. **`calls deleteKoboToken after confirming deletion`** — asserts `deleteKoboToken` is called with the correct token ID after confirmation.
5. **`only shows confirmation for the clicked token, not all tokens`** — asserts only the target token's row shows the dialog.
6. **`dismisses confirmation dialog when Escape is pressed`** — asserts the Escape key closes the dialog.
7. **`moves focus to the Delete confirm button when dialog opens`** — asserts the Delete button inside the `alertdialog` receives focus.

> **Mocking note:** The test file mocks `api.listKoboTokens`, `api.createKoboToken`, `api.deleteKoboToken`, `clipboard.copyToClipboard`, and all `lucide-svelte` icon components. `afterEach` calls `cleanup()` and `vi.clearAllMocks()`.

#### `UsersTab.test.ts`

`frontend/src/components/settings/UsersTab.test.ts` verifies that the Users table in the admin settings panel meets accessibility requirements (WCAG 1.3.1, 4.1.2). Two tests are included:

1. **`marks each table header as a column header`** — seeds the component with one cached user to bypass the initial loading path, then asserts that each of the five `<th>` elements — **Name**, **Email**, **Type**, **Role**, and **Joined** — is exposed as a `role="columnheader"` and carries `scope="col"`.

2. **`gives toggle-admin buttons descriptive accessible names`** — seeds the component with three users (one matching the logged-in admin, one regular user, one additional admin), then asserts that the two role-toggle buttons carry action-oriented `aria-label` values: `"Grant admin role to Reader User"` for the non-admin entry and `"Remove admin role from Staff User"` for the admin entry. The logged-in user's row renders a non-interactive badge instead of a button, so it is excluded from these assertions.

> **Mocking note:** The test file mocks `authStore` (current admin user), `api.listUsers` (returns a resolved empty array to prevent uncaught-promise warnings), and all `lucide-svelte` icon components. `cachedUsers` is passed as a prop to seed the rendered table immediately, avoiding the need for async load completion. `afterEach(cleanup)` prevents DOM leakage between tests.

#### `APIKeysTab.test.ts`

`frontend/src/components/settings/APIKeysTab.test.ts` verifies the inline confirmation dialog pattern for API key deletion (WCAG 2.1.1, 4.1.2). Seven tests are included in the `APIKeysTab delete confirmation` describe block:

1. **`does not call deleteAPIKey when Delete button is clicked (shows confirmation instead)`** — clicks the delete trigger for an API key and asserts `deleteAPIKey` is **not** called, confirming that no deletion occurs until the user confirms.
2. **`shows inline confirmation dialog when Delete is clicked`** — clicks the delete trigger and asserts the `role="alertdialog"` confirmation panel appears in the DOM.
3. **`dismisses confirmation dialog when Cancel is clicked`** — opens the confirmation, then clicks Cancel; asserts the dialog is removed from the DOM.
4. **`calls deleteAPIKey after confirming deletion`** — opens the confirmation, clicks the confirm Delete button, and asserts `deleteAPIKey` is called with the correct key ID.
5. **`only shows confirmation for the clicked key, not all keys`** — seeds two API keys, clicks delete on the first, and asserts the dialog appears only for that key while the second key row remains unaffected.
6. **`dismisses confirmation dialog when Escape is pressed`** — opens the confirmation dialog, dispatches a `keydown` event with `key="Escape"`, and asserts the dialog is removed.
7. **`moves focus to the Delete confirm button when dialog opens`** — opens the confirmation dialog and asserts the Delete button inside the `alertdialog` receives focus, verifying the `autofocusFirstButton` action is working.

> **Mocking note:** The test file mocks `api.listAPIKeys` (returns two pre-seeded keys), `api.createAPIKey`, `api.deleteAPIKey` (resolves immediately), `clipboard.copyToClipboard`, and all `lucide-svelte` icon components. `afterEach` calls `cleanup()` and `vi.clearAllMocks()` to prevent state leakage between tests.

#### `KoboTab.test.ts`

`frontend/src/components/settings/KoboTab.test.ts` verifies the inline confirmation dialog pattern for Kobo sync token deletion (WCAG 2.1.1, 4.1.2). Seven tests are included in the `KoboTab delete confirmation` describe block, mirroring the structure of `APIKeysTab.test.ts`:

1. **`does not call deleteKoboToken when Delete button is clicked (shows confirmation instead)`** — asserts deletion does not fire on the first click.
2. **`shows inline confirmation dialog when Delete is clicked`** — asserts the `role="alertdialog"` panel appears.
3. **`dismisses confirmation dialog when Cancel is clicked`** — asserts Cancel hides the dialog.
4. **`calls deleteKoboToken after confirming deletion`** — asserts `deleteKoboToken` is called with the correct token ID after confirmation.
5. **`only shows confirmation for the clicked token, not all tokens`** — asserts only the target token's row shows the dialog.
6. **`dismisses confirmation dialog when Escape is pressed`** — asserts the Escape key closes the dialog.
7. **`moves focus to the Delete confirm button when dialog opens`** — asserts the Delete button inside the `alertdialog` receives focus.

> **Mocking note:** The test file mocks `api.listKoboTokens`, `api.createKoboToken`, `api.deleteKoboToken`, `clipboard.copyToClipboard`, and all `lucide-svelte` icon components. `afterEach` calls `cleanup()` and `vi.clearAllMocks()`.

#### `PreferencesTab.test.ts`

`frontend/src/components/settings/PreferencesTab.test.ts` verifies the theme selection controls and the screen-reader live region in the preferences settings tab (WCAG 4.1.2, 4.1.3). Eight tests are included in the `PreferencesTab` describe block:

1. **`renders all three theme buttons`** — asserts the three toggle buttons (light, dark, auto) are present in the DOM with the correct accessible names.
2. **`renders a fieldset with a Theme legend`** — asserts the theme buttons are grouped inside a `<fieldset>` with a `<legend>` whose text is "Theme", providing the group a programmatic label (WCAG 1.3.1).
3. **`sets aria-pressed='true' on the active theme button`** — seeds `themeStore.preference` as `"dark"` and asserts only the dark button carries `aria-pressed="true"` (WCAG 4.1.2).
4. **`sets aria-pressed='false' on inactive theme buttons`** — with the dark theme active, asserts the light and auto buttons carry `aria-pressed="false"`.
5. **`calls themeStore.set with the correct theme when a button is clicked`** — clicks the light button and asserts `themeStore.set` is called with `"light"`.
6. **`calls themeStore.set with 'dark' when the dark button is clicked`** — clicks the dark button and asserts `themeStore.set` is called with `"dark"`.
7. **`announces theme change to screen readers via a live region`** — uses fake timers, clicks the dark button, advances timers by 0 ms, then asserts the `role="status"` element contains the text `"Theme changed to dark"` (WCAG 4.1.3).
8. **`announces 'follow system settings' when auto theme is selected`** — clicks the auto button and asserts the live region text is `"Theme changed to follow system settings"`, verifying that the human-readable label is used instead of the raw `"auto"` value.

> **Testing note:** Tests 7 and 8 use `vi.useFakeTimers()` to control the `setTimeout(..., 0)` call inside `setTheme` and `await tick()` to flush Svelte 5 reactivity before asserting the live region text. `vi.useRealTimers()` is called in `afterEach` to restore the real clock after every test. The test file mocks `themeStore` and all `lucide-svelte` icon components; `afterEach` calls `cleanup()`, `vi.clearAllMocks()`, and `vi.useRealTimers()`.

---

## Unit tests

The following test suites cover reactive stores and the API client. Unlike the accessibility tests above, these tests verify logic and state management rather than DOM structure.

### `router.test.ts`

`frontend/src/stores/router.test.ts` exercises `routerStore`, the hash-based navigation store. Tests set `window.location.hash` and dispatch synthetic `hashchange` events, then assert the store's reactive properties. Fourteen tests across two `describe` blocks:

**Core routing:**

1. **`defaults to 'dashboard' when hash is empty`** — asserts `currentView` is `"dashboard"` and `subPath` is `""` on load.
2. **`parses 'books' from hash`** — sets `#books`; asserts `currentView` is `"books"` with empty `subPath`.
3. **`parses 'my-library' from hash`** — sets `#my-library`; asserts `currentView` is `"my-library"`.
4. **`parses 'settings' from hash`** — sets `#settings`; asserts `currentView` is `"settings"`.
5. **`defaults invalid hash segment to 'dashboard'`** — sets `#invalid-page`; asserts `currentView` falls back to `"dashboard"`.
6. **`extracts subPath from hash`** — sets `#settings/account`; asserts `currentView` is `"settings"` and `subPath` is `"account"`.
7. **`handles multi-segment subPath`** — sets `#settings/oidc/config`; asserts `subPath` is `"oidc/config"`.
8. **`navigate sets window.location.hash`** — calls `routerStore.navigate("books")`; asserts `window.location.hash` becomes `"#books"`.
9. **`responds to hashchange events`** — dispatches a `hashchange` event after changing the hash; asserts `routerStore.hash` updates reactively.
10. **`handles hash with leading slash`** — sets `#/books`; asserts the leading slash is stripped and `currentView` is `"books"`.

**`pageTitle` sub-suite:**

11. **Parameterised title tests** — asserts the correct page title string for each of the eleven known hash values (e.g. `#dashboard` → `"Dashboard – biblioteka"`, `#settings/account` → `"Account Settings – biblioteka"`).
12. **`falls back to 'Settings – biblioteka' for unknown settings sub-path`** — sets `#settings/unknown`; asserts `pageTitle` returns the top-level settings title.
13. **`falls back to 'biblioteka' for invalid hash`** — sets `#invalid-page`; asserts `pageTitle` is just `"biblioteka"`.

### `auth.test.ts`

`frontend/src/stores/auth.test.ts` exercises `authStore`, the authentication state store. All `api.*` calls are replaced with Vitest mocks so tests run without a real backend. Fourteen tests across four `describe` blocks:

**`init` (nine tests) — application startup authentication flow:**

1. **`sets loading to false when no token and no cookie`** — no in-memory token, `getMe()` returns 401; asserts `loading` is `false` and `user` is `null`.
2. **`fetches user when token exists`** — in-memory token set, `getMe()` resolves; asserts `user` is populated and `loading` is `false`.
3. **`clears token and retries when getMe returns 401 with token`** — stale token case; asserts `clearToken()` is called and `getMe()` is called twice.
4. **`clears stale token and authenticates via cookie on retry`** — first `getMe()` rejects with 401, second resolves with an OIDC user; asserts the user is set from the cookie session.
5. **`preserves token on transient network error`** — `getMe()` rejects with a generic `Error` (not `ApiError`); asserts `clearToken()` is **not** called.
6. **`authenticates via cookie on plain reload without token or URL marker`** — no token, no query params, `getMe()` resolves; asserts the user is set (HttpOnly cookie path).
7. **`authenticates via cookie after OIDC redirect`** — `?oidc_login=1` in the URL; asserts `getMe()` is called and the URL marker is cleaned up with `history.replaceState`.
8. **`sets oidcLinkError from URL params`** — `?oidc_link_error=account_already_linked`; asserts `authStore.oidcLinkError` is set.
9. **`redirects to settings on oidc_linked param`** — `?oidc_linked=true`; asserts `history.replaceState` redirects to `/#settings`.

**`signIn` (two tests):** asserts user is populated on success; asserts error is returned and user stays `null` on failure.

**`signUp` (two tests):** asserts user is populated on success; asserts error is returned on failure.

**`signOut` (one test):** asserts `clearToken()` and `logout()` are called and `user` is set to `null`.

> **Mocking note:** The `beforeEach` block manually resets `authStore.user`, `authStore.loading`, and `authStore.oidcLinkError` before each test. `window.location` is redefined as a writable property so query-param tests can control the URL without triggering real navigation.

### `api.test.ts`

`frontend/src/lib/api.test.ts` exercises the centralized API client. Because `api.ts` is now a barrel re-export of `frontend/src/lib/api/` sub-modules, the tests import from the barrel and cover the core, auth, config, admin, credentials, and SMTP sub-modules. `fetch` is replaced with a Vitest stub so no real HTTP requests are made. Tests are grouped into eleven `describe` blocks:

**`Token management` (five tests):** covers `setToken`, `clearToken`, `hasToken` — verifying in-memory token read/write semantics, including the edge case of an empty string being treated as "no token".

**`ApiError` (one test):** asserts the custom error class has the correct `name`, `message`, `status`, and prototype chain.

**`request` (seven tests):** exercises the shared `request()` helper (called indirectly through exported API functions):
- Asserts the `Authorization: Bearer <token>` header is included when a token is stored.
- Asserts the header is omitted when no token is present.
- Asserts POST requests serialize the body as JSON.
- Asserts a non-OK JSON response throws `ApiError` with the `error` field from the body.
- Asserts a non-OK plain-text response throws `ApiError` with the response body as the message.
- Asserts fallback to `statusText` when the JSON body contains no `error` field.
- Asserts graceful handling of a JSON parse failure (falls back to the raw response text as the error message).

**`Auth API functions` (six tests):** covers `signup`, `login`, `getOidcEnabled` (three edge cases: enabled, disabled, unexpected response), and `changePassword` — verifying the correct HTTP method, URL, and request body for each call.

**`Config API` (four tests):** covers `getConfigStatus`, `getOidcConfig`, `setOidcConfig`, and `createOidcLinkNonce`.

**`Admin API` (two tests):** covers `listUsers` and `setUserAdmin`.

**`Audit Logs API` (two tests):** covers `getAuditLogs` — verifying the default `limit=50&offset=0` query string and that custom limit/offset values are forwarded correctly.

**`OPDS Credentials API` (three tests):** covers `getOpdsCredential` (GET), `setOpdsCredential` (PUT with request body), and `deleteOpdsCredential` (DELETE resolves `void` on `204 No Content`).

**`KOSync Credentials API` (three tests):** covers `getKosyncCredential` (GET), `setKosyncCredential` (PUT with request body), and `deleteKosyncCredential` (DELETE resolves `void` on `204 No Content`).

**`Auth extended API` (three tests):** covers `updateProfile` (PUT `/api/auth/me`) — verifying the name field is sent in the request body and the updated user profile is returned; `logout` (POST `/api/auth/logout`) — verifying the correct URL is called; and a network-failure case asserting that `logout` resolves `void` even when the underlying request rejects.

**`SMTP Config API` (three tests):** covers `getSmtpConfig` (GET `/api/config/smtp`) — verifying the SMTP configuration object is returned; `setSmtpConfig` (PUT `/api/config/smtp` with config body) — verifying the full config is serialized and sent; and `testSmtpConfig` (POST `/api/config/smtp/test`) — verifying the test-send endpoint is called and the result is returned.

### `books.test.ts`

`frontend/src/lib/api/books.test.ts` exercises the `api/books.ts` sub-module end-to-end. `fetch` is replaced with a Vitest stub so no real HTTP requests are made. Eighteen tests across sixteen `describe` blocks inside a parent `Books API` block:

**`listBooks` (three tests):**
- Asserts `GET /api/books?limit=50&offset=0` is issued with default parameters and the paginated response is returned.
- Asserts custom `limit`, `offset`, and `query` values are forwarded as query-string parameters.
- Asserts the `query` parameter is omitted when the query string is empty.

**`getTotalBooksCount` (one test):** Asserts the helper issues `GET /api/books?limit=1&offset=0` and returns the `total` field from the response — confirming that the total count is derived from the cheapest possible paginated request.

**`getBook` (one test):** Asserts `GET /api/books/:id` is issued and the book object is returned.

**`createBook` (one test):** Asserts `POST /api/books` is issued with the input serialized as JSON and the created book is returned.

**`updateBook` (one test):** Asserts `PUT /api/books/:id` is issued with the updated fields and the updated book is returned.

**`deleteBook` (one test):** Asserts `DELETE /api/books/:id` is issued and the function resolves `undefined`.

**`getBookAuthors` (one test):** Asserts `GET /api/books/:id/authors` is issued and the authors array is returned.

**`setBookAuthors` (one test):** Asserts `PUT /api/books/:id/authors` is issued with `{ author_ids: [...] }` and the updated authors array is returned.

**`getBookSeries` (one test):** Asserts `GET /api/books/:id/series` is issued and the series entries array is returned.

**`setBookSeries` (one test):** Asserts `PUT /api/books/:id/series` is issued with `{ entries: [...] }` and the updated series entries are returned.

**`listBookFiles` (one test):** Asserts `GET /api/books/:id/files` is issued and the files array is returned.

**`createBookFile` (one test):** Asserts `POST /api/books/:id/files` is issued with the file input and the created file record is returned.

**`getBookFile` (one test):** Asserts `GET /api/book-files/:id` is issued and the file record is returned.

**`deleteBookFile` (one test):** Asserts `DELETE /api/book-files/:id` is issued and the function resolves `undefined`.

**`bookFileDownloadUrl` (one test):** Asserts the pure helper returns `/api/book-files/:id/download` without making any HTTP requests.

**`emailBookFile` (one test):** Asserts `POST /api/book-files/:id/email` is issued with `{ to: "..." }` in the request body and the `{ message: "..." }` response is returned.

> **Mocking note:** `fetch` is globally stubbed in `beforeEach` via `vi.stubGlobal("fetch", fetchMock)` and unset in `afterEach` with `vi.unstubAllGlobals()`. Shared helper utilities `mockFetchResponse` and `mockNoContentResponse` from `./testUtils` keep individual tests concise.

### `clipboard.test.ts`

`frontend/src/lib/clipboard.test.ts` exercises the `copyToClipboard` utility. Tests stub `navigator` and `document.execCommand` to isolate the function from real browser APIs. Tests are grouped in one `describe` block:

**`copyToClipboard` (four tests):**
- Asserts the async Clipboard API (`navigator.clipboard.writeText`) is used when available, and called with the correct text.
- Asserts the `execCommand` fallback path is taken when `navigator.clipboard` is absent, and that `document.execCommand('copy')` is invoked.
- Asserts an `Error` is thrown when `execCommand` returns `false`.
- Asserts errors thrown by the async Clipboard API are propagated to the caller.

> **Mocking note:** `beforeEach` captures the original `execCommand` property descriptor, and `afterEach` restores it alongside `vi.unstubAllGlobals()` and `vi.restoreAllMocks()`. This prevents global state leaking between tests.

---

### `libraries.test.ts`

`frontend/src/stores/libraries.test.ts` exercises `libraryStore`, the library state and scanning store. All `api.*` calls are replaced with Vitest mocks. Ten tests across five `describe` blocks:

**`load` (three tests):**
1. **`fetches libraries and sets loaded`** — mocks `listLibraries` to resolve with a fixture; asserts `libraries` is populated, `loaded` is `true`, and `loading` is `false`.
2. **`does not call API again after already loaded`** — calls `load()` twice; asserts `listLibraries` is called exactly once.
3. **`resets loading on API error`** — mocks `listLibraries` to reject; asserts `loading` and `loaded` are both `false` and `libraries` is empty.

**`add` (three tests):**
1. **`adds the created library to the store`** — mocks `createLibrary`; asserts the returned library is appended to `libraries`.
2. **`marks the newly added library as scanning`** — asserts `scanningIds` contains the new library's ID immediately after `add()`, and `isScanning` is `true`.
3. **`auto-clears scanning state after timeout`** — uses fake timers; asserts `scanningIds` is emptied after the 5-minute auto-clear timeout fires.

**`clearScanning` (two tests):**
1. **`removes the specified library ID from scanningIds`** — marks a library as scanning then calls `clearScanning(id)`; asserts `scanningIds` no longer contains it.
2. **`is a no-op when ID is not in scanningIds`** — calls `clearScanning` with an unknown ID; asserts no error and state is unchanged.

**`clearAllScanning` (one test):**
1. **`clears all scanning IDs`** — marks two libraries as scanning then calls `clearAllScanning()`; asserts `scanningIds` is empty and `isScanning` is `false`.

**`remove` (one test):**
1. **`removes the library from the store and clears its scanning state`** — adds and marks a library as scanning, then calls `remove(id)`; asserts the library is gone from `libraries` and `scanningIds`.

> **Setup:** `beforeEach` resets the store by setting `libraries = []`, `loading = false`, `loaded = false`, and calling `clearAllScanning()`. Fake timers are used to control the 5-minute scanning timeout without real waits.

---

### `onboarding.test.ts`

`frontend/src/stores/onboarding.test.ts` exercises `onboardingStore`, the per-user first-library wizard skip-state store. `localStorage` is stubbed globally by `test-setup.ts`; a `beforeEach` block calls `onboardingStore.clearSkip(userId)` to reset state. Tests are organized in a single `describe("onboardingStore")` block.

**`isSkipped` (three tests):**

1. **`returns false when userId is undefined`** — asserts `isSkipped(undefined)` returns `false` (safe default during auth initialisation).
2. **`returns false when localStorage has no entry for the user`** — asserts `isSkipped("user-1")` returns `false` on a clean store.
3. **`returns true after skip() is called for the user`** — calls `skip("user-1")` and asserts `isSkipped("user-1")` is `true`.

**`skip` (one test):**

1. **`persists the flag to localStorage`** — calls `skip("user-2")`; asserts `localStorage.getItem("biblioteka_onboarding_skipped_user-2")` equals `"1"`.

**`clearSkip` (one test):**

1. **`removes the flag from localStorage`** — calls `skip("user-3")` then `clearSkip("user-3")`; asserts `localStorage.getItem(...)` returns `null`.

---

### `DownloadsHistogram.test.ts`

`frontend/src/components/ui/DownloadsHistogram.test.ts` verifies the rendering and accessibility behavior of the `DownloadsHistogram` chart component. Eight tests in one `describe` block:

1. **`renders the default title`** — mounts with `data` containing downloads; asserts an `<h3>` heading with text `"Downloads per month"` is present.
2. **`renders a custom title`** — mounts with a `title` override; asserts the `<h3>` heading reflects the custom string.
3. **`shows the empty state message when all counts are zero`** — mounts with all-zero counts; asserts the "No downloads recorded yet." message is present and the `data-testid="histogram-bars"` container is absent.
4. **`renders bars when data has downloads`** — mounts with non-zero counts; asserts the histogram-bars container is present and the empty-state message is absent.
5. **`renders a bar element for each data point`** — mounts with three data points; asserts the histogram-bars container has exactly three child elements.
6. **`hides the visual chart from assistive technology`** — asserts no `list` or `listitem` roles are present and the histogram-bars container has `aria-hidden="true"`.
7. **`renders an accessible data table with month and download counts`** — asserts a `table` captioned "Downloads per month" exists with `Month` and `Downloads` column headers and one row header per data point.
8. **`generates unique ids for multiple instances`** — renders two instances with different titles; asserts their heading `id` attributes are distinct.

---

### `EmailBookModal.test.ts`

`frontend/src/components/ui/EmailBookModal.test.ts` verifies the loading, success, error, and accessibility behaviors of the `EmailBookModal` component. `fetch` is stubbed globally; `lucide-svelte` icons are mocked as no-ops (required for JSDOM). Eleven tests in one `describe` block:

1. **`shows loading state initially`** — `fetch` never resolves; asserts a `role="status"` element with text matching `/loading/i` is present.
2. **`moves focus to the dialog on mount`** — `fetch` never resolves; asserts the dialog container receives focus via `$effect` autofocus on mount so the dialog title is announced first (WCAG 2.1.2).
3. **`renders the dialog title`** — `fetch` resolves with a book; asserts an `<h2>` heading with text `"Email Book"` is present.
4. **`shows file name and email input after loading`** — `fetch` resolves; asserts the file name and the To address input are visible.
5. **`shows 'no files' message when book has no files`** — `fetch` resolves with a book that has an empty `files` array; asserts the "no files available" message appears.
6. **`shows an error message when book load fails`** — `fetch` rejects; asserts a `role="alert"` element contains the error text.
7. **`calls onClose when the close button is clicked`** — `fetch` resolves; simulates a click on the Close button; asserts the `onClose` prop was called once.
8. **`shows success message after sending`** — two-call fetch sequence (book load then send); fills the To field and clicks Send; asserts a `role="status"` element contains `"Email sent successfully"`.
9. **`shows error message when send fails`** — two-call fetch sequence (book load then 502 error); fills To and clicks Send; asserts a `role="alert"` element contains the API error text.
10. **`traps Tab focus within the dialog: Tab from last element wraps to first`** — focuses the Cancel button (last focusable element when Send is disabled); presses Tab; asserts focus wraps to the Close button (WCAG 2.1.1).
11. **`traps Shift+Tab focus within the dialog: Shift+Tab from first element wraps to last`** — focuses the Close button; presses Shift+Tab; asserts focus wraps to the Cancel button (WCAG 2.1.1).

---

### `BookList.test.ts`

`frontend/src/components/ui/BookList.test.ts` exercises `BookList.svelte`'s loading state, link accessibility, ARIA structure, pagination, polling, and empty-state behaviour. All `lucide-svelte` icons are mocked as no-ops (required for JSDOM). Thirteen tests across six `describe` blocks:

**`BookList loading state` (one test):**
1. **`exposes 'Loading books...' via role='status' while loading`** — asserts that a `role="status"` element with the text "Loading books..." is present while a fetch is in flight.

**`BookList table view link accessibility (WCAG 2.1.1)` (three tests):**
1. **`table rows are not interactive`** — switches to table view and asserts each `<tr>` has no `tabindex` and no row-level `aria-label`.
2. **`title link remains in the natural tab order`** — asserts the title `<a>` does not set `tabindex`.
3. **`title link points to the book route`** — asserts the title link keeps the expected hash `href`.

**`BookList table view accessibility` (one test):**
1. **`labels the book table with aria-label (WCAG 1.3.1)`** — switches to table view and asserts a `<table>` element with `aria-label="Books"` is present.

**`BookList pagination accessibility` (two tests):**
1. **`pagination counter has aria-atomic but no duplicate aria-live (WCAG 4.1.3)`** — asserts the "Page X of Y" counter carries `aria-atomic="true"` and does **not** carry `aria-live` (which would cause double-announcement alongside an ancestor live region).
2. **`pagination buttons have descriptive aria-label (WCAG 2.4.6)`** — asserts the Previous and Next buttons carry full-context labels including the target page number (e.g., `"Next page, page 2 of 25"`).

**`BookList empty state` (two tests):**
1. **`shows 'No books yet.' when no pollingInterval is set`** — renders with an empty `fetchBooks`; asserts the standard empty-state text appears.
2. **`shows 'Scanning library...' when pollingInterval is set and no books found`** — renders with `pollingInterval={3000}` and empty `fetchBooks`; asserts the scanning spinner text appears and the standard empty text does not.

**`BookList polling` (four tests):**
1. **`polls at the specified interval when total is 0`** — uses fake timers; advances time by 1 s (twice) and asserts `fetchBooks` is called again after each step (silent poll).
2. **`stops polling once books are found`** — `fetchBooks` returns books after the first poll; asserts polling stops and `fetchBooks` is not called again after further timer advancement.
3. **`calls onBooksFound when books appear for the first time`** — passes an `onBooksFound` spy; asserts it is called exactly once when books first appear.
4. **`does not poll when no pollingInterval is set`** — renders without `pollingInterval`; advances time and asserts `fetchBooks` is called only once (initial load).

> **Mocking note:** `afterEach(cleanup)` prevents DOM leakage between tests. Fake timers (`vi.useFakeTimers()`) are activated per-suite and restored in `afterEach` to avoid contaminating other test files.

### `AIEnrichmentPanel.test.ts`

`frontend/src/components/books/AIEnrichmentPanel.test.ts` verifies the loading, rendering, interaction, error, and race-condition behavior of the AI enrichment review panel. Thirteen tests in one `AIEnrichmentPanel` describe block:

1. **`shows a loading spinner initially`** — mounts with a never-resolving `getPendingAIEnrichment` mock; asserts a `role="status"` element containing "Checking for AI enrichment..." is rendered.
2. **`renders nothing when no pending enrichment exists (404)`** — mock rejects with `ApiError(404)`; asserts neither the panel container (`data-testid="ai-enrichment-panel"`) nor any `role="alert"` is rendered after loading completes.
3. **`renders enrichment data when pending enrichment exists`** — mock resolves with a full enrichment fixture; asserts the panel heading "AI Enrichment Review", suggested tag chips, reading-level value, generated-description text, and the provider/model attribution line are rendered.
4. **`renders Apply and Reject buttons`** — asserts both action buttons are present once enrichment data has loaded.
5. **`calls applyAIEnrichment and invokes onApplied callback on success`** — simulates clicking **Apply**; asserts `applyAIEnrichment` is called with the correct book ID, the panel disappears, and the `onApplied` spy is called.
6. **`calls rejectAIEnrichment and invokes onRejected callback on success`** — simulates clicking **Reject**; asserts `rejectAIEnrichment` is called with the correct book ID, the panel disappears, and the `onRejected` spy is called.
7. **`shows an error message when initial load fails with a non-404 error`** — mock rejects with a generic error; asserts an error message is rendered.
8. **`shows an error inside the panel when apply fails`** — mock rejects on `applyAIEnrichment`; asserts an inline `AlertBanner` appears while the enrichment data remains visible.
9. **`shows an error inside the panel when reject fails`** — mock rejects on `rejectAIEnrichment`; asserts an inline `AlertBanner` appears while the enrichment data remains visible.
10. **`disables both buttons while applying`** — clicks **Apply** against a stalled promise; asserts the Apply button shows "Applying..." and that the action buttons are disabled during the pending request.
11. **`disables both buttons while rejecting`** — clicks **Reject** against a stalled promise; asserts the Reject button shows "Rejecting..." and that the action buttons are disabled during the pending request.
12. **`renders nothing when enrichment has no suggested tags, reading level, or description`** — resolves with a minimal enrichment (empty tags, `null` reading level and description); asserts the panel still renders without showing optional enrichment content.
13. **`discards enrichment result when bookId changes before the request settles`** — stalls the first request for book `b1`, then re-renders with `bookId="b2"` before resolving; resolves the stale first request; asserts that `b1`'s enrichment does not appear (stale-result guard via the `bookId !== id` check in `loadEnrichment`; `AbortController` is also aborted but the mock resolves regardless).

> **Testing note:** `ApiError` (from `../../lib/api/core`) is manually mocked to expose a typed `status` field so the component's 404 suppression logic can be exercised in JSDOM. The `lucide-svelte` icon components are stubbed to avoid SVG rendering overhead.

### `BookEditForm.test.ts`

`frontend/src/components/books/BookEditForm.test.ts` verifies the rendering, validation, cover image preview behavior, and disabled state of the book metadata edit form. Seven tests in one `BookEditForm` describe block:

1. **`renders all 12 form fields with correct values`** — mounts the form with a fully populated `fields` prop and asserts that all twelve inputs render with the expected values.
2. **`displays the formError AlertBanner when title is blank and form is submitted`** — submits the form with an empty title; asserts that an `AlertBanner` with the validation message is rendered.
3. **`does not display an error banner initially`** — asserts that no error `AlertBanner` is present before the form is submitted.
4. **`shows cover image preview when coverImageUrl is set`** — mounts the form with a non-empty `coverImageUrl`; asserts that an `<img alt="Cover preview">` element is rendered and its `src` matches the supplied URL.
5. **`does not show cover image preview when coverImageUrl is empty`** — mounts the form with `coverImageUrl: ""`; asserts that no `<img alt="Cover preview">` element is present.
6. **`does not show cover image preview when coverImageUrl is whitespace only`** — mounts the form with `coverImageUrl: "   "`; asserts that no preview image appears (whitespace is treated as empty).
7. **`disables all inputs and buttons when saving is true`** — sets `saving={true}` and asserts that every input and button in the form carries the `disabled` attribute.

> **Testing note:** The cover image preview is rendered inside a `{#if fields.coverImageUrl?.trim()}` block, so tests 5 and 6 confirm that neither an empty string nor a whitespace-only string triggers a preview. The `onerror` handler that hides a broken-URL image is exercised at runtime; JSDOM does not fire load/error events for images so it is not covered here.

---

## Build configuration (`vite.config.ts`)

The frontend build is configured in `frontend/vite.config.ts`. Key settings:

| Setting | Value | Purpose |
|---------|-------|---------|
| `build.outDir` | `../internal/server/dist` | Output is written into the Go module so it can be embedded in the binary |
| `build.emptyOutDir` | `true` | Clears the output directory before each build to avoid stale assets |
| `server.proxy["/api"]` | `http://localhost:8080` | Forwards API requests to the Go backend during `pnpm run dev` |
| `test.environment` | `jsdom` | Vitest tests run in a browser-like DOM environment |

### `restoreGitkeep` plugin

`internal/server/dist/` is tracked by Git (via a `.gitkeep` file) so that the Go `//go:embed` directive always has a valid directory to embed — even on a clean checkout before the frontend has been built. Vite's `emptyOutDir: true` deletes the entire directory contents on each build, which would remove `.gitkeep` and break the embed on the next clean checkout.

The custom `restoreGitkeep()` Vite plugin, defined at the top of `vite.config.ts`, runs after the bundle is written (`closeBundle` hook) and recreates the empty `.gitkeep` file. This keeps Git happy without requiring a manual post-build step.

> **Do not remove** the `restoreGitkeep()` call from the `plugins` array. Without it, `go build` will fail on any checkout where the frontend has not been built, because the embedded directory will be missing.

## Linting and type-checking

```bash
# From the frontend/ directory
pnpm run lint     # ESLint
pnpm run check    # svelte-check (TypeScript + Svelte template types)
pnpm run test     # Vitest unit tests
pnpm run format   # Prettier
```

Run `lint` and `check` before every commit.