refactor: resolve() internal links instead of plain hrefs

Type-checks every link against the real route tree. Caught a dead one: the
book page linked tags to /tag/{id}, a route that has never existed.

frontend/eslint.config.js

@@ -29,6 +29,12 @@ export default defineConfig(
 			'no-undef': 'off'
 		}
 	},
+	{
+		// Generated shadcn components take href as a prop and cannot resolve it —
+		// that is the caller's job. Editing them here would be lost on regeneration.
+		files: ['src/lib/components/ui/**'],
+		rules: { 'svelte/no-navigation-without-resolve': 'off' }
+	},
 	{
 		files: ['**/*.svelte', '**/*.svelte.ts', '**/*.svelte.js'],
 		languageOptions: {

frontend/src/lib/components/forms/books-upload.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+	import { resolve } from '$app/paths';
 	import * as Dialog from '$lib/components/ui/dialog/index.js';
 	import * as Field from '$lib/components/ui/field/index.js';
 	import { Button } from '$lib/components/ui/button';
@@ -36,8 +37,8 @@
 
 	const onUpload: FileDropZoneProps['onUpload'] = async (uploadedFiles) => {
 		// Rename files to use webkitRelativePath so directory structure is preserved through form submission
-		const renamedFiles = uploadedFiles.map(f =>
+		const renamedFiles = uploadedFiles.map(
-			new File([f], f.webkitRelativePath || f.name, { type: f.type })
+			(f) => new File([f], f.webkitRelativePath || f.name, { type: f.type })
 		);
 		uploadBooks.fields.files.set([...Array.from(files), ...renamedFiles]);
 		if (autoUploadOnDrop && files.length > 0) {
@@ -55,9 +56,12 @@
 		let libraryId = books.items[0].library_id;
 		libraryState.setActive(libraryId);
 		if (books.items.length === 1) {
-			goto(`/book/${books.items[0].id}`);
+			goto(resolve('/(root)/(library)/book/[bookId]', { bookId: String(books.items[0].id) }));
 		} else {
-			goto(`/library/${libraryId}/view?orderBy=created_at&sortOrder=desc`);
+			// The path is resolved; the query string is what the rule cannot see past.
+			const view = resolve('/(root)/(library)/library/[libraryId]/view', { libraryId: String(libraryId) });
+			// eslint-disable-next-line svelte/no-navigation-without-resolve
+			goto(`${view}?orderBy=created_at&sortOrder=desc`);
 		}
 	}
 </script>
@@ -88,8 +92,10 @@
 						}
 
 						// Update library book count
-						const count = uploadBooks.result.total
+						const count = uploadBooks.result.total;
-						libraryState.libraries.find(lib => uploadBooks.fields.library_id.value() == lib.id.toString())!.total += count
+						libraryState.libraries.find(
+							(lib) => uploadBooks.fields.library_id.value() == lib.id.toString()
+						)!.total += count;
 
 						// Reset the files field
 						uploadBooks.fields.files.set([]);

frontend/src/lib/components/layout/app-sidebar.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+	import { resolve } from '$app/paths';
 	import { Separator } from '$lib/components/ui/separator/index.js';
 
 	import ChitaiMark from '$lib/components/icons/chitai-mark.svelte';
@@ -27,7 +28,7 @@
 	// directly in the markup keeps it static.
 	const header = $derived({
 		title: 'chitai',
-		url: `/library/${libraryState.activeLibrary!.id}`
+		url: resolve('/(root)/(library)/library/[libraryId]', { libraryId: String(libraryState.activeLibrary!.id) })
 	});
 </script>
 
@@ -40,6 +41,8 @@
 		-->
 		<Sidebar.MenuButton class="mt-1 -ml-1.5">
 			{#snippet child({ props })}
+				<!-- header.url is built with resolve(); the rule cannot trace the variable. -->
+				<!-- eslint-disable-next-line svelte/no-navigation-without-resolve -->
 				<a href={header.url} {...props}>
 					<ChitaiMark class="mr-3 size-7!" />
 					<span class="font-serif text-xl tracking-tight">{header.title}</span>

frontend/src/lib/components/layout/nav-main.svelte

@@ -1,8 +1,9 @@
 <script lang="ts">
+	import { resolve } from '$app/paths';
 	import { page } from '$app/state';
 	import * as Collapsible from '$lib/components/ui/collapsible/index.js';
 	import * as Sidebar from '$lib/components/ui/sidebar/index.js';
-    import { Badge } from "$lib/components/ui/badge/index.js";
+	import { Badge } from '$lib/components/ui/badge/index.js';
 	import { useSidebar } from '$lib/components/ui/sidebar/index.js';
 	import { getBookshelfState } from '$lib/state/bookshelf.svelte';
 	import { getLibraryState } from '$lib/state/library.svelte';
@@ -22,10 +23,25 @@
 	// rebuilt on every navigation the icons would remount, flashing and shifting
 	// layout. Only the url and active state need to be reactive, so they are
 	// computed per-item in the markup instead.
+	//
+	// Active state is matched on route id rather than pathname. resolve() returns
+	// an absolute path on the client but a relative one during SSR, so comparing
+	// it to page.url.pathname would be false on the server and true after
+	// hydration — the highlight would flash in.
 	const items = [
-        { title: 'Home', icon: House, path: (id?: number) => `/library/${id}` },
+		{
-        { title: 'Library', icon: LibraryBig, path: (id?: number) => `/library/${id}/view` },
+			title: 'Home',
-        { title: 'Shelves', icon: Rows3, path: () => '#', shelves: [] }
+			icon: House,
+			routeId: '/(root)/(library)/library/[libraryId]',
+			path: (id?: number) => resolve('/(root)/(library)/library/[libraryId]', { libraryId: String(id ?? '') })
+		},
+		{
+			title: 'Library',
+			icon: LibraryBig,
+			routeId: '/(root)/(library)/library/[libraryId]/view',
+			path: (id?: number) => resolve('/(root)/(library)/library/[libraryId]/view', { libraryId: String(id ?? '') })
+		},
+		{ title: 'Shelves', icon: Rows3, routeId: null, path: () => '#', shelves: [] }
 	];
 </script>
 
@@ -41,7 +57,7 @@
 	<Sidebar.Menu>
 		{#each items as item (item.title)}
 			{@const url = item.path(libraryState.activeLibrary?.id)}
-            {@const isActive = page.url.pathname === url}
+			{@const isActive = item.routeId !== null && page.route.id === item.routeId}
 			{#if 'shelves' in item}
 				<Collapsible.Root bind:open={shelvesOpen} class="group/collapsible">
 					{#snippet child({ props })}
@@ -78,17 +94,18 @@
 											<Sidebar.MenuSubButton>
 												{#snippet child({ props })}
 													<a
-                                                            href={`/library/${libraryState.activeLibrary!.id}/view?shelves=${shelf.id}`}
+														href="{resolve('/(root)/(library)/library/[libraryId]/view', {
+															libraryId: String(libraryState.activeLibrary!.id)
+														})}?shelves={shelf.id}"
 														{...props}
 													>
 														<Badge
 															variant="outline"
-                                                            class="scale-90 font-semibold bg-sidebar-primary text-sidebar-primary-foreground mr-1">
+															class="mr-1 scale-90 bg-sidebar-primary font-semibold text-sidebar-primary-foreground"
+														>
 															{shelf.total}
 														</Badge>
 														<span>{shelf.title}</span>
-                                                            
-                                                            
 													</a>
 												{/snippet}
 											</Sidebar.MenuSubButton>
@@ -101,8 +118,10 @@
 				</Collapsible.Root>
 			{:else}
 				<Sidebar.MenuItem>
-                    <Sidebar.MenuButton isActive={isActive} tooltipContent={item.title} class="h-10">
+					<Sidebar.MenuButton {isActive} tooltipContent={item.title} class="h-10">
 						{#snippet child({ props })}
+							<!-- item.path() calls resolve(); the rule cannot trace the variable. -->
+							<!-- eslint-disable-next-line svelte/no-navigation-without-resolve -->
 							<a href={url} {...props}>
 								{#if item.icon}
 									<item.icon class="scale-125" />

frontend/src/lib/components/layout/nav-user.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+	import { resolve } from '$app/paths';
 	import * as Avatar from '$lib/components/ui/avatar/index.js';
 	import * as DropdownMenu from '$lib/components/ui/dropdown-menu/index.js';
 	import * as Sidebar from '$lib/components/ui/sidebar/index.js';
@@ -31,13 +32,16 @@
 						class="data-[state=open]:bg-sidebar-accent data-[state=open]:text-sidebar-accent-foreground"
 					>
 						<Avatar.Root class="size-8 rounded-lg">
-							<Avatar.Fallback class="rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
+							<Avatar.Fallback
+								class="rounded-lg bg-sidebar-primary text-sidebar-primary-foreground"
+							>
 								{initials}
 							</Avatar.Fallback>
 						</Avatar.Root>
 						<div class="grid flex-1 text-left text-sm leading-tight">
 							<span class="truncate font-semibold">{handle}</span>
-							<span class="truncate font-mono text-[11px] text-muted-foreground">{user?.email}</span>
+							<span class="truncate font-mono text-[11px] text-muted-foreground">{user?.email}</span
+							>
 						</div>
 						<ChevronsUpDownIcon class="ml-auto size-4" />
 					</Sidebar.MenuButton>
@@ -53,13 +57,16 @@
 				<DropdownMenu.Label class="p-0 font-normal">
 					<div class="flex items-center gap-2 px-1 py-1.5 text-left text-sm">
 						<Avatar.Root class="size-8 rounded-lg">
-							<Avatar.Fallback class="rounded-lg bg-sidebar-primary text-sidebar-primary-foreground">
+							<Avatar.Fallback
+								class="rounded-lg bg-sidebar-primary text-sidebar-primary-foreground"
+							>
 								{initials}
 							</Avatar.Fallback>
 						</Avatar.Root>
 						<div class="grid flex-1 text-left text-sm leading-tight">
 							<span class="truncate font-semibold">{handle}</span>
-							<span class="truncate font-mono text-[11px] text-muted-foreground">{user?.email}</span>
+							<span class="truncate font-mono text-[11px] text-muted-foreground">{user?.email}</span
+							>
 						</div>
 					</div>
 				</DropdownMenu.Label>
@@ -67,11 +74,11 @@
 				<DropdownMenu.Separator />
 
 				<DropdownMenu.Group>
-					<DropdownMenu.Item onSelect={() => goto('/settings/account')}>
+					<DropdownMenu.Item onSelect={() => goto(resolve('/settings/account'))}>
 						<SettingsIcon class="size-4" />
 						Settings
 					</DropdownMenu.Item>
-					<DropdownMenu.Item onSelect={() => goto('/settings/appearance')}>
+					<DropdownMenu.Item onSelect={() => goto(resolve('/settings/appearance'))}>
 						<PaletteIcon class="size-4" />
 						Appearance
 					</DropdownMenu.Item>
@@ -82,7 +89,7 @@
 				<DropdownMenu.Item
 					onSelect={async () => {
 						await logout();
-						await goto('/login');
+						await goto(resolve('/login'));
 					}}
 				>
 					<LogOutIcon class="size-4" />

frontend/src/lib/components/layout/search-form.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+	import { resolve } from '$app/paths';
 	import * as Command from '$lib/components/ui/command/index';
 	import * as Kbd from '$lib/components/ui/kbd/index.js';
 	import * as InputGroup from '$lib/components/ui/input-group/index.js';
@@ -97,7 +98,7 @@
 						<Command.Item
 							value={String(book.id)}
 							onSelect={() => {
-								goto(`/book/${book.id}`);
+								goto(resolve('/(root)/(library)/book/[bookId]', { bookId: String(book.id) }));
 								open = false;
 							}}
 							class="cursor-pointer"
@@ -115,7 +116,9 @@
 											by
 											{#each book.authors as author}
 												<a
-													href="/library/{libraryState.activeLibrary!.id}/view?authors={author.id}"
+													href="{resolve('/(root)/(library)/library/[libraryId]/view', {
+														libraryId: String(libraryState.activeLibrary!.id)
+													})}?authors={author.id}"
 													class="cs-list hover:underline">{author.name}</a
 												> &thinsp;
 											{/each}

frontend/src/lib/components/reader/epub-reader.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+	import { resolve } from '$app/paths';
 	import { onMount, untrack } from 'svelte';
 
 	import {
@@ -25,14 +26,14 @@
 	import ReaderToc from './reader-toc.svelte';
 
 	let {
-		bookUrl,
+		fileUrl,
 		bookId,
 		filename,
 		title = '',
 		initialProgress = 0,
 		initialEpubLoc = null
 	}: {
-		bookUrl: string;
+		fileUrl: string;
 		bookId: string | number;
 		filename: string;
 		title?: string;
@@ -78,7 +79,7 @@
 		file = undefined;
 
 		try {
-			const response = await fetch(bookUrl);
+			const response = await fetch(fileUrl);
 			if (!response.ok) throw new Error(`The server returned ${response.status} for this file.`);
 
 			file = new File([await response.blob()], filename, { type: 'application/epub+zip' });
@@ -135,7 +136,7 @@
 			</Tooltip.Provider>
 
 			<a
-				href="/book/{bookId}"
+				href={resolve('/(root)/(library)/book/[bookId]', { bookId: String(bookId) })}
 				class="min-w-0 flex-1 truncate font-serif text-sm hover:underline"
 				{title}
 			>
@@ -178,7 +179,10 @@
 							<RotateCcw class="size-4" />
 							Try again
 						</Button>
-						<a href="/book/{bookId}" class={buttonVariants({ variant: 'outline' })}>
+						<a
+							href={resolve('/(root)/(library)/book/[bookId]', { bookId: String(bookId) })}
+							class={buttonVariants({ variant: 'outline' })}
+						>
 							Back to book
 						</a>
 					</div>

frontend/src/lib/components/view/book-rows.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+	import { resolve } from '$app/paths';
 	import BookCover from './book-cover.svelte';
 	import BookActionsMenu from './book-actions-menu.svelte';
 	import * as Tooltip from '$lib/components/ui/tooltip/index';
@@ -120,7 +121,7 @@
 				? 'cursor-pointer'
 				: ''}"
 		>
-			<a href="/book/{book.id}" class="shrink-0">
+			<a href={resolve('/(root)/(library)/book/[bookId]', { bookId: String(book.id) })} class="shrink-0">
 				<BookCover {book} height={110} />
 			</a>
 
@@ -128,7 +129,7 @@
 				<div class="flex items-start gap-2">
 					<div class="min-w-0 flex-1">
 						<a
-							href="/book/{book.id}"
+							href={resolve('/(root)/(library)/book/[bookId]', { bookId: String(book.id) })}
 							class="line-clamp-2 font-serif text-sm leading-snug hover:underline"
 						>
 							{book.title}
@@ -166,7 +167,9 @@
 					{#each book.tags.slice(0, TAG_LIMIT) as tag (tag.id)}
 						<a
 							data-row-control
-							href="/library/{libraryState.activeLibrary?.id}/view?tags={tag.id}"
+							href="{resolve('/(root)/(library)/library/[libraryId]/view', {
+								libraryId: String(libraryState.activeLibrary?.id ?? '')
+							})}?tags={tag.id}"
 							class={badgeVariants({ variant: 'secondary' })}>{tag.name}</a
 						>
 					{/each}

frontend/src/lib/components/view/book-table.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+	import { resolve } from '$app/paths';
 	import * as Table from '$lib/components/ui/table/index';
 	import * as DropdownMenu from '$lib/components/ui/dropdown-menu/index';
 	import * as Tooltip from '$lib/components/ui/tooltip/index';
@@ -52,7 +53,9 @@
 
 	const visible = $derived(columns.filter((c) => c.on));
 
-	const allSelected = $derived(books.length > 0 && books.every((b) => selectionState.isSelected(b.id)));
+	const allSelected = $derived(
+		books.length > 0 && books.every((b) => selectionState.isSelected(b.id))
+	);
 
 	/** What a record is lacking — the reason this view exists. */
 	function missing(book: Book) {
@@ -208,19 +211,26 @@
 						/>
 					</Table.Cell>
 					<Table.Cell>
-						<a href="/book/{book.id}"><BookCover {book} height={36} /></a>
+						<a href={resolve('/(root)/(library)/book/[bookId]', { bookId: String(book.id) })}
+							><BookCover {book} height={36} /></a
+						>
 					</Table.Cell>
 
 					{#each visible as column (column.key)}
 						{#if column.key === 'title'}
 							<Table.Cell class="max-w-[280px] truncate font-serif">
-								<a href="/book/{book.id}" class="hover:underline">{book.title}</a>
+								<a
+									href={resolve('/(root)/(library)/book/[bookId]', { bookId: String(book.id) })}
+									class="hover:underline">{book.title}</a
+								>
 							</Table.Cell>
 						{:else if column.key === 'authors'}
 							<Table.Cell class="max-w-[180px] truncate">
 								{#each book.authors as author (author.id)}
 									<a
-										href="/library/{libraryState.activeLibrary?.id}/view?authors={author.id}"
+										href="{resolve('/(root)/(library)/library/[libraryId]/view', {
+											libraryId: String(libraryState.activeLibrary?.id ?? '')
+										})}?authors={author.id}"
 										class="cs-list hover:underline">{author.name}</a
 									> &thinsp;
 								{/each}
@@ -248,7 +258,7 @@
 								{formatFileSize(totalSize(book))}
 							</Table.Cell>
 						{:else if column.key === 'added'}
-							<Table.Cell class="font-mono text-xs tabular-nums text-muted-foreground">
+							<Table.Cell class="font-mono text-xs text-muted-foreground tabular-nums">
 								{addedOn(book)}
 							</Table.Cell>
 						{:else if column.key === 'progress'}
@@ -263,7 +273,7 @@
 												style="width: {Math.round(book.progress.percentage * 100)}%;"
 											></span>
 										</span>
-										<span class="font-mono text-xs tabular-nums text-muted-foreground">
+										<span class="font-mono text-xs text-muted-foreground tabular-nums">
 											{Math.round(book.progress.percentage * 100)}%
 										</span>
 									</span>

frontend/src/lib/components/view/book-thumbnail.svelte

@@ -1,11 +1,12 @@
 <script lang="ts">
+	import { resolve } from '$app/paths';
 	import BookImage from './book-image.svelte';
 	import { Progress } from '$lib/components/ui/progress/index';
 	import { getLibraryState } from '$lib/state/library.svelte';
 	import { getBookSelectionState } from '$lib/state/bookSelection.svelte';
 	import type { Book } from '$lib/schema';
 
-	let { book, class: className = '', ...rest }: { book: Book, class?: string} = $props();
+	let { book, class: className = '', ...rest }: { book: Book; class?: string } = $props();
 
 	const selectionState = getBookSelectionState();
 	const libraryState = getLibraryState();
@@ -24,7 +25,7 @@
 <div class="flex w-full flex-shrink-0 flex-col gap-1 {className}">
 	<!-- Book Cover -->
 	<a
-		href="/book/{book.id}"
+		href={resolve('/(root)/(library)/book/[bookId]', { bookId: String(book.id) })}
 		class="group relative aspect-9/12 w-full overflow-hidden rounded-sm shadow-lg drop-shadow-lg transition-all duration-200 {selected
 			? 'ring-2 ring-star'
 			: ''}"
@@ -51,7 +52,9 @@
 	</a>
 
 	<!-- Book Title -->
-	<a href="/book/{book.id}" class="text-base-content mt-1 line-clamp-2 w-full font-serif text-sm hover:underline"
+	<a
+		href={resolve('/(root)/(library)/book/[bookId]', { bookId: String(book.id) })}
+		class="text-base-content mt-1 line-clamp-2 w-full font-serif text-sm hover:underline"
 		>{book.title}</a
 	>
 
@@ -59,7 +62,9 @@
 	<p class="line-clamp-1 w-full text-xs text-muted-foreground">
 		{#each book.authors as author}
 			<a
-				href="/library/{libraryState.activeLibrary?.id}/view?authors={author.id}"
+				href="{resolve('/(root)/(library)/library/[libraryId]/view', {
+					libraryId: String(libraryState.activeLibrary?.id ?? '')
+				})}?authors={author.id}"
 				class="cs-list hover:underline">{author.name}</a
 			> &thinsp;
 		{/each}

frontend/src/lib/state/bookCollection.svelte.ts

@@ -99,6 +99,9 @@ export class BookCollectionState {
 
 		const url = new URL(page.url);
 		url.searchParams.set('view', next);
+		// Not a route to resolve — this is the current URL with one query param
+		// changed, so it is already fully qualified.
+		// eslint-disable-next-line svelte/no-navigation-without-resolve
 		replaceState(url, page.state);
 	}
 
@@ -137,7 +140,8 @@ export class BookCollectionState {
 		url.searchParams.set('orderBy', this.orderBy);
 		url.searchParams.set('sortOrder', this.sortOrder);
 
-		// pushState(url.toString(), {})
+		// Same as setView: the current URL with sort params rewritten, not a route.
+		// eslint-disable-next-line svelte/no-navigation-without-resolve
 		goto(url.toString());
 
 		this.loadNewBooks();
@@ -285,9 +289,7 @@ export class BookCollectionState {
 
 		return wanted.every(([key, values]) => {
 			const current = this.filters[key] ?? [];
-			return (
+			return current.length === values.length && values.every((value) => current.includes(value));
-				current.length === values.length && values.every((value) => current.includes(value))
-			);
 		});
 	}
 

frontend/src/lib/state/library.svelte.ts

@@ -1,3 +1,4 @@
+import { resolve } from '$app/paths';
 import { browser } from '$app/environment';
 import { goto, invalidate } from '$app/navigation';
 import { page } from '$app/state';
@@ -31,7 +32,9 @@ export class LibraryState {
 		this.activeLibrary = this.libraries.find((lib) => lib.id === libraryId) || this.libraries[0];
 		if (browser) {
 			localStorage.setItem('previousLibraryId', this.activeLibrary.id.toString());
-			await goto(`/library/${libraryId}/view`, { invalidate: ['app:libraries'] });
+			await goto(resolve('/(root)/(library)/library/[libraryId]/view', { libraryId: String(libraryId) }), {
+				invalidate: ['app:libraries']
+			});
 		}
 	}
 

frontend/src/routes/(root)/(library)/book/[bookId]/+page.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+	import { resolve } from '$app/paths';
 	import { Badge, badgeVariants } from '$lib/components/ui/badge/index.js';
 	import { CollapsibleText } from '$lib/components/ui/collapsible-text/index.js';
 	import * as DropdownMenu from '$lib/components/ui/dropdown-menu/index';
@@ -17,12 +18,7 @@
 		PlusIcon,
 		Trash2
 	} from '@lucide/svelte';
-	import {
+	import { describeIdentifier, formatFileSize, getFileType, sortIdentifiers } from '$lib/utils.js';
-		describeIdentifier,
-		formatFileSize,
-		getFileType,
-		sortIdentifiers
-	} from '$lib/utils.js';
 	import { getBookOperationsState } from '$lib/state/bookOperations.svelte.js';
 	import { getBookshelfState } from '$lib/state/bookshelf.svelte.js';
 	import { getLibraryState } from '$lib/state/library.svelte.js';
@@ -65,12 +61,24 @@
 				: 'Read'
 	);
 
+	// window.open is outside the lint rule's reach, but the paths need resolving
+	// just the same — they would break under a non-empty base path.
 	function openBookInReader(file: BookFile) {
+		const params = { bookId: String(book.id), fileId: String(file.id) };
+
 		if (getFileType(file.filename) === 'EPUB')
-			window.open(`/book/${book.id}/read/epub/${file.id}`, '_blank', 'noopener,noreferrer');
+			window.open(
+				resolve('/(root)/(library)/book/[bookId]/read/epub/[fileId]', params),
+				'_blank',
+				'noopener,noreferrer'
+			);
 
 		if (getFileType(file.filename) === 'PDF')
-			window.open(`/book/${book.id}/read/pdf/${file.id}`, '_blank', 'noopener,noreferrer');
+			window.open(
+				resolve('/(root)/(library)/book/[bookId]/read/pdf/[fileId]', params),
+				'_blank',
+				'noopener,noreferrer'
+			);
 	}
 
 	// On the band, the accent is the ground — invert the buttons against it.
@@ -101,7 +109,7 @@
 				</h1>
 
 				{#if book.subtitle}
-					<p class="mt-1 font-serif text-lg italic text-primary-foreground/75">{book.subtitle}</p>
+					<p class="mt-1 font-serif text-lg text-primary-foreground/75 italic">{book.subtitle}</p>
 				{/if}
 
 				{#if book.series}
@@ -115,7 +123,9 @@
 						By
 						{#each book.authors as author (author.id)}
 							<a
-								href="/library/{libraryState.activeLibrary!.id}/view?authors={author.id}"
+								href="{resolve('/(root)/(library)/library/[libraryId]/view', {
+									libraryId: String(libraryState.activeLibrary!.id)
+								})}?authors={author.id}"
 								class="cs-list hover:underline">{author.name}</a
 							> &thinsp;
 						{/each}
@@ -169,7 +179,11 @@
 							</DropdownMenu.Content>
 						</DropdownMenu.Root>
 					{:else if book.files.length === 1}
-						<button type="button" class={bandPrimary} onclick={() => openBookInReader(book.files[0])}>
+						<button
+							type="button"
+							class={bandPrimary}
+							onclick={() => openBookInReader(book.files[0])}
+						>
 							<BookOpenText class="size-4" />
 							{readLabel}
 						</button>
@@ -184,7 +198,6 @@
 							Download
 						</button>
 					{/if}
-
 				</div>
 			</div>
 		</div>
@@ -267,10 +280,11 @@
 							</dt>
 							<dd class="m-0 font-mono break-all tabular-nums">
 								{#if id.href}
+									<!-- Always an absolute URL off-site: openlibrary, doi.org or amazon. -->
 									<a
 										href={id.href}
 										target="_blank"
-									rel="noopener noreferrer"
+										rel="external noopener noreferrer"
 										class="hover:text-primary hover:underline">{value}</a
 									>
 								{:else}
@@ -288,7 +302,14 @@
 						</h2>
 						<div class="flex flex-wrap gap-1.5">
 							{#each book.tags as tag (tag.id)}
-							<a href="/tag/{tag.id}" class={badgeVariants({ variant: 'default' })}>{tag.name}</a>
+								<!-- Was /tag/{id}, a route that has never existed — these badges 404'd.
+							     Filter the library view, as the tag links in the list views do. -->
+								<a
+									href="{resolve('/(root)/(library)/library/[libraryId]/view', {
+										libraryId: String(libraryState.activeLibrary!.id)
+									})}?tags={tag.id}"
+									class={badgeVariants({ variant: 'default' })}>{tag.name}</a
+								>
 							{/each}
 						</div>
 					</div>
@@ -302,7 +323,9 @@
 						<div class="flex flex-wrap gap-1.5">
 							{#each book.lists as shelf (shelf.id)}
 								<a
-								href="/library/{libraryState.activeLibrary!.id}/view?shelves={shelf.id}"
+									href="{resolve('/(root)/(library)/library/[libraryId]/view', {
+										libraryId: String(libraryState.activeLibrary!.id)
+									})}?shelves={shelf.id}"
 									class={badgeVariants({ variant: 'outline' })}>{shelf.title}</a
 								>
 							{/each}
@@ -462,7 +485,10 @@
 											<Table.Cell class="font-mono text-xs tabular-nums">
 												{formatFileSize(file.size)}
 											</Table.Cell>
-										<Table.Cell><span class="font-mono text-xs">{getFileType(file.filename)}</span></Table.Cell>
+											<Table.Cell
+												><span class="font-mono text-xs">{getFileType(file.filename)}</span
+												></Table.Cell
+											>
 											<Table.Cell class="text-right">
 												<div class="flex justify-end gap-1">
 													{#if getFileType(file.filename) === 'EPUB' || getFileType(file.filename) === 'PDF'}

frontend/src/routes/(root)/(library)/book/[bookId]/read/epub/[fileId]/+page.svelte

@@ -8,11 +8,11 @@
 	const bookId = page.params.bookId!;
 
 	// Fetched by the browser through the proxy, which attaches the auth header
-	const bookUrl = `/api/books/download/${bookId}/${fileId}`;
+	const fileUrl = `/api/books/download/${bookId}/${fileId}`;
 </script>
 
 <EpubReader
-	{bookUrl}
+	{fileUrl}
 	{bookId}
 	title={data.title}
 	filename={data.filename}

frontend/src/routes/(root)/(library)/book/[bookId]/read/pdf/[fileId]/+page.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+	import { resolve } from '$app/paths';
 	import { page } from '$app/state';
 	import { Button, buttonVariants } from '$lib/components/ui/button/index.js';
 	import { Spinner } from '$lib/components/ui/spinner/index';
@@ -55,7 +56,7 @@
 	<!-- Same chrome as the EPUB reader, so leaving works the same way in both -->
 	<header class="flex h-12 shrink-0 items-center gap-2 border-b px-3">
 		<a
-			href="/book/{bookId}"
+			href={resolve('/(root)/(library)/book/[bookId]', { bookId: String(bookId) })}
 			class="min-w-0 flex-1 truncate font-serif text-sm hover:underline"
 			title={data?.title}
 		>
@@ -76,7 +77,10 @@
 							<RotateCcw class="size-4" />
 							Try again
 						</Button>
-						<a href="/book/{bookId}" class={buttonVariants({ variant: 'outline' })}>
+						<a
+							href={resolve('/(root)/(library)/book/[bookId]', { bookId: String(bookId) })}
+							class={buttonVariants({ variant: 'outline' })}
+						>
 							Back to book
 						</a>
 					</div>

frontend/src/routes/(root)/settings/+layout.svelte

@@ -1,25 +1,19 @@
 <script lang="ts">
 	import { page } from '$app/state';
+	import { resolve } from '$app/paths';
+
 	let { children } = $props();
 
+	// Route ids rather than paths: resolve() is called in the markup so it stays a
+	// direct call the lint rule can see, and the active check compares route ids.
+	// A pathname comparison would miss during SSR, where resolve() returns a
+	// relative path, and only settle after hydration.
 	const items = [
-		{
+		{ title: 'Account', routeId: '/(root)/settings/account' },
-			title: 'Account',
+		{ title: 'Appearance', routeId: '/(root)/settings/appearance' },
-			url: '/settings/account'
+		{ title: 'Libraries', routeId: '/(root)/settings/libraries' },
-		},
+		{ title: 'Devices', routeId: '/(root)/settings/devices' }
-		{
+	] as const;
-			title: 'Appearance',
-			url: '/settings/appearance'
-		},
-		{
-			title: 'Libraries',
-			url: '/settings/libraries'
-		},
-		{
-			title: 'Devices',
-			url: '/settings/devices'
-		}
-	];
 </script>
 
 <div class="flex h-[calc(100vh-var(--header-height)-2rem)] flex-col">
@@ -28,8 +22,9 @@
 		<nav class="flex w-48 shrink-0 flex-col gap-1">
 			{#each items as item}
 				<a
-					href={item.url}
+					href={resolve(item.routeId)}
-					class="rounded-md px-3 py-2 text-sm font-medium transition-colors hover:bg-muted {page.url.pathname.endsWith(item.url)
+					class="rounded-md px-3 py-2 text-sm font-medium transition-colors hover:bg-muted {page
+						.route.id === item.routeId
 						? 'bg-muted'
 						: 'text-muted-foreground'}"
 				>

frontend/src/routes/(root)/settings/account/+page.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+	import { resolve } from '$app/paths';
 	import { goto } from '$app/navigation';
 	import { logout } from '$lib/api';
 	import { Button } from '$lib/components/ui/button/index.js';
@@ -12,7 +13,7 @@
 	<Button
 		onclick={async () => {
 			await logout();
-			goto('/login');
+			goto(resolve('/login'));
 		}}
 		variant="outline"
 		class="w-32"

frontend/src/routes/(root)/settings/libraries/+page.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+	import { resolve } from '$app/paths';
 	import * as Table from '$lib/components/ui/table/index.js';
 	import * as Card from '$lib/components/ui/card/index.js';
 	import { getLibraryState } from '$lib/state/library.svelte';
@@ -36,7 +37,10 @@
 							>{library.name[0]}</Table.Cell
 						>
 						<Table.Cell class="font-medium">
-							<a href={`/library/${library.id}`} class="hover:underline">{library.name}</a>
+							<a
+								href={resolve('/(root)/(library)/library/[libraryId]', { libraryId: String(library.id) })}
+								class="hover:underline">{library.name}</a
+							>
 						</Table.Cell>
 						<Table.Cell class="w-16 text-center">
 							<EllipsisVertical class="scale-75" />

frontend/src/routes/login/+layout@.svelte

@@ -1,4 +1,5 @@
 <script lang="ts">
+	import { resolve } from '$app/paths';
 	import '../../app.css';
 	import favicon from '$lib/assets/favicon.svg';
 	import ThemeToggle from '$lib/components/layout/theme-toggle.svelte';
@@ -10,12 +11,11 @@
 	<link rel="icon" href={favicon} />
 </svelte:head>
 
-
 <div class="flex h-screen min-h-screen flex-col">
 	<!-- Header -->
 	<div class="flex items-center gap-4 pt-4 pl-6">
 		<p class="text-3xl">📚</p>
-		<a href="/" class="text-2xl font-semibold">chitai</a>
+		<a href={resolve('/')} class="text-2xl font-semibold">chitai</a>
 
 		<ThemeToggle class="mr-4 ml-auto" />
 	</div>