From 16cdec051ac1bbc8ab76f4353053e7d4b5a4d4a1 Mon Sep 17 00:00:00 2001
From: MechaCat02 <MechaCat02@example.com>
Date: Tue, 7 Jul 2026 07:18:43 +0200
Subject: [PATCH] feat: loading skeletons on the bookmarks and collections
 pages

Both loaders now stream the whole result (the single fetch is also the auth
gate) so the page shows a skeleton while it loads instead of the global nav
bar only: a ListRowSkeleton on bookmarks and a MangaGridSkeleton on the
collections grid, resolving to the sign-in / error / empty / list branches.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 backend/Cargo.lock                            |  2 +-
 backend/Cargo.toml                            |  2 +-
 frontend/e2e/bookmarks-skeleton.spec.ts       | 57 +++++++++++++++++++
 frontend/package.json                         |  2 +-
 .../src/lib/components/ListRowSkeleton.svelte | 49 ++++++++++++++++
 .../components/ListRowSkeleton.svelte.test.ts | 25 ++++++++
 frontend/src/routes/bookmarks/+page.svelte    | 34 +++++------
 frontend/src/routes/bookmarks/+page.ts        | 40 +++++++------
 frontend/src/routes/collections/+page.svelte  | 34 ++++++-----
 frontend/src/routes/collections/+page.ts      | 30 ++++++----
 10 files changed, 212 insertions(+), 63 deletions(-)
 create mode 100644 frontend/e2e/bookmarks-skeleton.spec.ts
 create mode 100644 frontend/src/lib/components/ListRowSkeleton.svelte
 create mode 100644 frontend/src/lib/components/ListRowSkeleton.svelte.test.ts

diff --git a/backend/Cargo.lock b/backend/Cargo.lock
index 0d51ccb..a56bb91 100644
--- a/backend/Cargo.lock
+++ b/backend/Cargo.lock
@@ -1558,7 +1558,7 @@ checksum = "c41e0c4fef86961ac6d6f8a82609f55f31b05e4fce149ac5710e439df7619ba4"
 
 [[package]]
 name = "mangalord"
-version = "0.119.0"
+version = "0.120.0"
 dependencies = [
  "anyhow",
  "argon2",
diff --git a/backend/Cargo.toml b/backend/Cargo.toml
index 0492bf5..ef2f1f7 100644
--- a/backend/Cargo.toml
+++ b/backend/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "mangalord"
-version = "0.119.0"
+version = "0.120.0"
 edition = "2021"
 default-run = "mangalord"
 
diff --git a/frontend/e2e/bookmarks-skeleton.spec.ts b/frontend/e2e/bookmarks-skeleton.spec.ts
new file mode 100644
index 0000000..d652e1c
--- /dev/null
+++ b/frontend/e2e/bookmarks-skeleton.spec.ts
@@ -0,0 +1,57 @@
+import { test, expect, type Page } from './fixtures';
+
+// The bookmarks page streams its list (the single fetch is also the auth
+// gate), so a row skeleton shows while it loads, then resolves to the list.
+
+async function mockCommon(page: Page) {
+    await page.route('**/api/v1/auth/config', (r) =>
+        r.fulfill({
+            status: 200,
+            contentType: 'application/json',
+            body: JSON.stringify({ self_register_enabled: true, private_mode: false })
+        })
+    );
+    await page.route('**/api/v1/auth/me', (r) =>
+        r.fulfill({
+            status: 200,
+            contentType: 'application/json',
+            body: JSON.stringify({ user: { id: 'u1', username: 'reader', created_at: '2026-01-01T00:00:00Z', is_admin: false } })
+        })
+    );
+    await page.route('**/api/v1/auth/me/preferences', (r) =>
+        r.fulfill({ status: 200, contentType: 'application/json', body: '{}' })
+    );
+    await page.route('**/api/v1/files/**', (r) => r.fulfill({ status: 200, body: '' }));
+}
+
+test('shows a row skeleton while bookmarks stream, then the list', async ({ page }) => {
+    await mockCommon(page);
+
+    let release: () => void = () => {};
+    const gate = new Promise<void>((resolve) => {
+        release = resolve;
+    });
+    await page.route('**/api/v1/me/bookmarks*', async (route) => {
+        await gate;
+        await route.fulfill({
+            status: 200,
+            contentType: 'application/json',
+            body: JSON.stringify({
+                items: [
+                    {
+                        id: 'bk1', user_id: 'u1', manga_id: 'm1', chapter_id: null, page: null,
+                        created_at: '2026-01-01T00:00:00Z', manga_title: 'Berserk', manga_cover_image_path: null
+                    }
+                ],
+                page: { limit: 50, offset: 0, total: 1 }
+            })
+        });
+    });
+
+    await page.goto('/bookmarks');
+    await expect(page.getByTestId('list-row-skeleton')).toBeVisible();
+
+    release();
+    await expect(page.getByText('Berserk')).toBeVisible();
+    await expect(page.getByTestId('list-row-skeleton')).toHaveCount(0);
+});
diff --git a/frontend/package.json b/frontend/package.json
index c2a54d9..246822a 100644
--- a/frontend/package.json
+++ b/frontend/package.json
@@ -1,6 +1,6 @@
 {
   "name": "mangalord-frontend",
-  "version": "0.119.0",
+  "version": "0.120.0",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/frontend/src/lib/components/ListRowSkeleton.svelte b/frontend/src/lib/components/ListRowSkeleton.svelte
new file mode 100644
index 0000000..a8444dd
--- /dev/null
+++ b/frontend/src/lib/components/ListRowSkeleton.svelte
@@ -0,0 +1,49 @@
+<script lang="ts">
+    import Skeleton from './Skeleton.svelte';
+
+    /**
+     * Placeholder for a cover + two-line row list (bookmarks, history, tagged
+     * pages). Reserves the list height so rows swap in without a shift.
+     */
+    let {
+        count = 6,
+        coverWidth = '64px',
+        testid = 'list-row-skeleton'
+    }: { count?: number; coverWidth?: string; testid?: string } = $props();
+</script>
+
+<ul class="list" data-testid={testid} aria-hidden="true">
+    {#each Array(count) as _}
+        <li class="row" style="grid-template-columns: {coverWidth} 1fr;">
+            <Skeleton width={coverWidth} aspectRatio="2 / 3" radius="sm" />
+            <div class="meta">
+                <Skeleton variant="text" width="55%" radius="sm" />
+                <Skeleton variant="text" width="35%" radius="sm" />
+            </div>
+        </li>
+    {/each}
+</ul>
+
+<style>
+    .list {
+        list-style: none;
+        padding: 0;
+        margin: 0;
+        display: flex;
+        flex-direction: column;
+        gap: var(--space-3);
+    }
+
+    .row {
+        display: grid;
+        gap: var(--space-3);
+        align-items: center;
+    }
+
+    .meta {
+        display: flex;
+        flex-direction: column;
+        gap: var(--space-2);
+        min-width: 0;
+    }
+</style>
diff --git a/frontend/src/lib/components/ListRowSkeleton.svelte.test.ts b/frontend/src/lib/components/ListRowSkeleton.svelte.test.ts
new file mode 100644
index 0000000..792ff22
--- /dev/null
+++ b/frontend/src/lib/components/ListRowSkeleton.svelte.test.ts
@@ -0,0 +1,25 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, screen, cleanup } from '@testing-library/svelte';
+import ListRowSkeleton from './ListRowSkeleton.svelte';
+
+afterEach(() => cleanup());
+
+describe('ListRowSkeleton', () => {
+    it('renders the requested number of rows', () => {
+        render(ListRowSkeleton, { props: { count: 5, testid: 'sk' } });
+        expect(screen.getByTestId('sk').querySelectorAll('.row').length).toBe(5);
+    });
+
+    it('defaults to 6 rows and is decorative', () => {
+        render(ListRowSkeleton, { props: { testid: 'sk' } });
+        const el = screen.getByTestId('sk');
+        expect(el.querySelectorAll('.row').length).toBe(6);
+        expect(el.getAttribute('aria-hidden')).toBe('true');
+    });
+
+    it('applies the cover width to the row template', () => {
+        render(ListRowSkeleton, { props: { coverWidth: '80px', testid: 'sk' } });
+        const row = screen.getByTestId('sk').querySelector('.row') as HTMLElement;
+        expect(row.style.gridTemplateColumns).toBe('80px 1fr');
+    });
+});
diff --git a/frontend/src/routes/bookmarks/+page.svelte b/frontend/src/routes/bookmarks/+page.svelte
index 571d615..2bf3a91 100644
--- a/frontend/src/routes/bookmarks/+page.svelte
+++ b/frontend/src/routes/bookmarks/+page.svelte
@@ -1,27 +1,29 @@
 <script lang="ts">
     import BookmarkList from '$lib/components/BookmarkList.svelte';
+    import ListRowSkeleton from '$lib/components/ListRowSkeleton.svelte';
 
     let { data } = $props();
-    const authenticated = $derived(data.authenticated);
-    const bookmarks = $derived(data.bookmarks);
-    const error = $derived(data.error);
 </script>
 
 <h1>Bookmarks</h1>
 
-{#if error}
-    <p class="error" role="alert" data-testid="bookmarks-error">
-        Couldn't load bookmarks: {error}
-    </p>
-{:else if !authenticated}
-    <p class="hint" data-testid="bookmarks-signin">
-        <a href="/login">Sign in</a> to see your bookmarks.
-    </p>
-{:else if bookmarks.length === 0}
-    <p class="hint" data-testid="bookmarks-empty">No bookmarks yet.</p>
-{:else}
-    <BookmarkList {bookmarks} />
-{/if}
+{#await data.result}
+    <ListRowSkeleton />
+{:then r}
+    {#if r.error}
+        <p class="error" role="alert" data-testid="bookmarks-error">
+            Couldn't load bookmarks: {r.error}
+        </p>
+    {:else if !r.authenticated}
+        <p class="hint" data-testid="bookmarks-signin">
+            <a href="/login">Sign in</a> to see your bookmarks.
+        </p>
+    {:else if r.bookmarks.length === 0}
+        <p class="hint" data-testid="bookmarks-empty">No bookmarks yet.</p>
+    {:else}
+        <BookmarkList bookmarks={r.bookmarks} />
+    {/if}
+{/await}
 
 <style>
     .error {
diff --git a/frontend/src/routes/bookmarks/+page.ts b/frontend/src/routes/bookmarks/+page.ts
index bd431ed..3609bff 100644
--- a/frontend/src/routes/bookmarks/+page.ts
+++ b/frontend/src/routes/bookmarks/+page.ts
@@ -5,21 +5,27 @@ import type { PageLoad } from './$types';
 export const ssr = false;
 
 export const load: PageLoad = async () => {
-    try {
-        const page = await listMyBookmarks();
-        return { bookmarks: page.items, authenticated: true, error: null };
-    } catch (e) {
-        if (e instanceof ApiError && e.status === 401) {
-            return { bookmarks: [], authenticated: false, error: null };
-        }
-        // Anything else (502 upstream_unavailable from a backend
-        // restart, 500 internal_error) is rendered inline rather than
-        // re-thrown — SvelteKit's generic error.html is not the right
-        // UX for a transient API blip and the user is already
-        // authenticated as far as we know.
-        if (e instanceof ApiError) {
-            return { bookmarks: [], authenticated: true, error: e.message };
-        }
-        throw e;
-    }
+    // Streamed (the load itself doesn't await) so the list shows a skeleton
+    // while the single fetch — which is also the auth gate — is in flight.
+    return {
+        result: (async () => {
+            try {
+                const page = await listMyBookmarks();
+                return { bookmarks: page.items, authenticated: true, error: null as string | null };
+            } catch (e) {
+                if (e instanceof ApiError && e.status === 401) {
+                    return { bookmarks: [], authenticated: false, error: null as string | null };
+                }
+                // Anything else (502 upstream_unavailable from a backend
+                // restart, 500 internal_error) is rendered inline rather than
+                // re-thrown — SvelteKit's generic error.html is not the right
+                // UX for a transient API blip and the user is already
+                // authenticated as far as we know.
+                if (e instanceof ApiError) {
+                    return { bookmarks: [], authenticated: true, error: e.message };
+                }
+                throw e;
+            }
+        })()
+    };
 };
diff --git a/frontend/src/routes/collections/+page.svelte b/frontend/src/routes/collections/+page.svelte
index 0c22da0..f588bd4 100644
--- a/frontend/src/routes/collections/+page.svelte
+++ b/frontend/src/routes/collections/+page.svelte
@@ -1,26 +1,30 @@
 <script lang="ts">
     import CollectionsGrid from '$lib/components/CollectionsGrid.svelte';
+    import MangaGridSkeleton from '$lib/components/MangaGridSkeleton.svelte';
 
     let { data } = $props();
-    const collections = $derived(data.collections);
 </script>
 
 <h1>Collections</h1>
 
-{#if !data.authenticated}
-    <p class="status">
-        <a href="/login">Sign in</a> to see and manage your collections.
-    </p>
-{:else if data.error}
-    <p class="error" role="alert">{data.error}</p>
-{:else if collections.length === 0}
-    <p class="status" data-testid="collections-empty">
-        You don't have any collections yet. Open any manga and use
-        <strong>Add to collection</strong> to start one.
-    </p>
-{:else}
-    <CollectionsGrid {collections} />
-{/if}
+{#await data.result}
+    <MangaGridSkeleton count={6} />
+{:then r}
+    {#if !r.authenticated}
+        <p class="status">
+            <a href="/login">Sign in</a> to see and manage your collections.
+        </p>
+    {:else if r.error}
+        <p class="error" role="alert">{r.error}</p>
+    {:else if r.collections.length === 0}
+        <p class="status" data-testid="collections-empty">
+            You don't have any collections yet. Open any manga and use
+            <strong>Add to collection</strong> to start one.
+        </p>
+    {:else}
+        <CollectionsGrid collections={r.collections} />
+    {/if}
+{/await}
 
 <style>
     .status {
diff --git a/frontend/src/routes/collections/+page.ts b/frontend/src/routes/collections/+page.ts
index f2b3c77..7076abf 100644
--- a/frontend/src/routes/collections/+page.ts
+++ b/frontend/src/routes/collections/+page.ts
@@ -5,16 +5,22 @@ import type { PageLoad } from './$types';
 export const ssr = false;
 
 export const load: PageLoad = async () => {
-    try {
-        const page = await listMyCollections({ limit: 200 });
-        return { collections: page.items, authenticated: true, error: null };
-    } catch (e) {
-        if (e instanceof ApiError && e.status === 401) {
-            return { collections: [], authenticated: false, error: null };
-        }
-        if (e instanceof ApiError) {
-            return { collections: [], authenticated: true, error: e.message };
-        }
-        throw e;
-    }
+    // Streamed so the grid shows a skeleton while the single fetch (also the
+    // auth gate) is in flight.
+    return {
+        result: (async () => {
+            try {
+                const page = await listMyCollections({ limit: 200 });
+                return { collections: page.items, authenticated: true, error: null as string | null };
+            } catch (e) {
+                if (e instanceof ApiError && e.status === 401) {
+                    return { collections: [], authenticated: false, error: null as string | null };
+                }
+                if (e instanceof ApiError) {
+                    return { collections: [], authenticated: true, error: e.message };
+                }
+                throw e;
+            }
+        })()
+    };
 };