From 62f7934fbd73015d92e5aaf2251397048e92f08f Mon Sep 17 00:00:00 2001
From: Christian Touoyim <touoyim14christian@gmail.com>
Date: Mon, 31 Aug 2026 23:49:08 +0100
Subject: [PATCH 1/3] feat: implement startup splash screen and loading
 behavior

---
 app/index.html             | 108 +++++++++++++++++++++++++++++++++++++
 app/src/App.spec.ts        |  10 ++--
 app/src/App.vue            |  31 ++---------
 app/src/bootSplash.spec.ts |  34 ++++++++++++
 app/src/bootSplash.ts      |  16 ++++++
 app/src/main.ts            |   9 +++-
 app/tsconfig.node.json     |   1 +
 app/vite.config.web.ts     |   3 +-
 8 files changed, 179 insertions(+), 33 deletions(-)
 create mode 100644 app/src/bootSplash.spec.ts
 create mode 100644 app/src/bootSplash.ts

diff --git a/app/index.html b/app/index.html
index 254ef5a809..2ca0f4b245 100644
--- a/app/index.html
+++ b/app/index.html
@@ -24,6 +24,99 @@
             content="#0f172a"
             media="(prefers-color-scheme: dark)"
         />
+
+        <!-- boot-splash:start -->
+        <!-- The splash in App.vue can only appear once Vue mounts, which is the second-to-last
+             step of Startup() — so the slow part of the boot (database open, auth) has nothing on
+             screen. This copy is plain HTML/CSS so it paints on first parse, and main.ts removes it
+             once the app is ready. Colours and metrics mirror App.vue + LoadingBar.vue; Tailwind is
+             unavailable this early, so they are written out longhand. -->
+        <script>
+            // Resolve the theme the way globalConfig does, before first paint, so the splash
+            // below is not white for a dark-mode user.
+            try {
+                var bootTheme = localStorage.getItem("theme");
+                if (
+                    bootTheme === "dark" ||
+                    (bootTheme !== "light" &&
+                        window.matchMedia("(prefers-color-scheme: dark)").matches)
+                ) {
+                    document.documentElement.classList.add("dark");
+                }
+            } catch (e) {
+                /* Storage can be unavailable (private mode); light is a safe default. */
+            }
+        </script>
+        <style>
+            #bootSplash {
+                position: fixed;
+                inset: 0;
+                z-index: 9999;
+                display: flex;
+                align-items: center;
+                justify-content: center;
+                background: #ffffff;
+                font-family:
+                    system-ui,
+                    -apple-system,
+                    sans-serif;
+            }
+            #bootSplash > div {
+                display: flex;
+                width: 100%;
+                flex-direction: column;
+                align-items: center;
+                gap: 1rem;
+            }
+            #bootSplash img {
+                width: 18rem;
+                max-width: 80%;
+            }
+            #bootSplash .bs-label {
+                font-size: 1.25rem;
+                font-weight: 600;
+                color: #71717a;
+            }
+            #bootSplash .bs-track {
+                position: relative;
+                height: 0.75rem;
+                width: 80%;
+                max-width: 28rem;
+                overflow: hidden;
+                border-radius: 9999px;
+                background: #e4e4e7;
+            }
+            #bootSplash .bs-slug {
+                position: absolute;
+                top: 0;
+                bottom: 0;
+                width: 40%;
+                border-radius: 9999px;
+                background: #71717a;
+                animation: bs-running-slug 1.2s linear infinite;
+            }
+            html.dark #bootSplash {
+                background: #0f172a;
+            }
+            html.dark #bootSplash .bs-label {
+                color: #94a3b8;
+            }
+            html.dark #bootSplash .bs-track {
+                background: #334155;
+            }
+            html.dark #bootSplash .bs-slug {
+                background: #94a3b8;
+            }
+            @keyframes bs-running-slug {
+                0% {
+                    left: -40%;
+                }
+                100% {
+                    left: 100%;
+                }
+            }
+        </style>
+        <!-- boot-splash:end -->
     </head>
     <body
         class="overscroll-none bg-white text-slate-900 dark:bg-slate-900 dark:text-slate-50"
@@ -33,6 +126,21 @@
         "
     >
         <div id="app"></div>
+        <!-- boot-splash:start -->
+        <!-- Served from public/, so the URL resolves from any route depth. -->
+        <div id="bootSplash">
+            <div>
+                <img
+                    src="/logo.svg"
+                    alt=""
+                />
+                <div class="bs-label">Loading...</div>
+                <div class="bs-track">
+                    <div class="bs-slug"></div>
+                </div>
+            </div>
+        </div>
+        <!-- boot-splash:end -->
         <script
             type="module"
             src="/src/main.ts"
diff --git a/app/src/App.spec.ts b/app/src/App.spec.ts
index 114ac2d16f..f1ca83d628 100644
--- a/app/src/App.spec.ts
+++ b/app/src/App.spec.ts
@@ -11,7 +11,6 @@ import { isConnected } from "luminary-shared";
 import { resolveNotificationText, useNotificationStore } from "./stores/notification";
 import { mockEnglishContentDto } from "./tests/mockdata";
 import { isAppLoading, theme } from "./globalConfig";
-import LoadingBar from "@/components/LoadingBar.vue";
 import { createMemoryHistory, createRouter } from "vue-router";
 import HomePage from "@/pages/HomePage.vue";
 import ExplorePage from "@/pages/ExplorePage.vue";
@@ -45,7 +44,9 @@ describe("App", () => {
         isAppLoading.value = true;
     });
 
-    describe("Splash screen", () => {
+    // The startup splash itself lives in index.html (see bootSplash.spec.ts); what this
+    // component owns is withholding the app until startup has finished.
+    describe("Startup gate", () => {
         beforeEach(() => {
             (auth as any).useAuth.mockReturnValue({
                 isLoading: ref(false),
@@ -53,12 +54,12 @@ describe("App", () => {
             });
         });
 
-        it("displays the splash screen while the app is loading", () => {
+        it("withholds the app content while the app is loading", () => {
             isAppLoading.value = true;
 
             const wrapper = mount(App, { shallow: true });
 
-            expect(wrapper.findComponent(LoadingBar).exists()).toBe(true);
+            expect(wrapper.find("router-view-stub").exists()).toBe(false);
         });
 
         it("displays the app content once loading is complete", () => {
@@ -66,7 +67,6 @@ describe("App", () => {
 
             const wrapper = mount(App, { shallow: true });
 
-            expect(wrapper.findComponent(LoadingBar).exists()).toBe(false);
             expect(wrapper.find("router-view-stub").exists()).toBe(true);
         });
     });
diff --git a/app/src/App.vue b/app/src/App.vue
index 88413d87e0..ba44f74a20 100644
--- a/app/src/App.vue
+++ b/app/src/App.vue
@@ -2,14 +2,7 @@
 import { RouterView } from "vue-router";
 import { computed, onErrorCaptured, onMounted, watch } from "vue";
 import { isConnected } from "luminary-shared";
-import {
-    appName,
-    isAppLoading,
-    userPreferencesAsRef,
-    mediaQueue,
-    localCacheVersion,
-} from "./globalConfig";
-import LoadingBar from "@/components/LoadingBar.vue";
+import { isAppLoading, userPreferencesAsRef, mediaQueue, localCacheVersion } from "./globalConfig";
 import { useNotificationStore } from "./stores/notification";
 import { ArrowLeftEndOnRectangleIcon, SignalSlashIcon } from "@heroicons/vue/20/solid";
 import * as Sentry from "@sentry/vue";
@@ -24,12 +17,9 @@ import { useAuthWithPrivacyPolicy } from "@/composables/useAuthWithPrivacyPolicy
 import { showProviderSelectionModal } from "@/auth";
 import AuthProviderSelectionModal from "@/components/authProvider/AuthProviderSelectionModal.vue";
 import { useI18n } from "vue-i18n";
-import defaultLogo from "@/assets/logo.svg?url";
 import { usePwaUpdate } from "@/composables/usePwaUpdate";
 import { useHydrated } from "@/composables/useHydrated";
 
-const LOGO = import.meta.env.VITE_LOGO || defaultLogo;
-
 const { t } = useI18n();
 const { needRefresh, reload } = usePwaUpdate();
 
@@ -172,22 +162,11 @@ onErrorCaptured((err) => {
 </script>
 
 <template>
+    <!-- The startup splash is plain HTML in index.html, so it can paint before this
+         component (or any module) exists. This gate only withholds the app until
+         startup finishes; index.html's copy is what covers the wait. -->
     <div
-        v-if="isAppLoading"
-        class="absolute flex h-full w-full items-center justify-center"
-    >
-        <div class="flex flex-col items-center gap-4">
-            <img
-                class="w-72"
-                :src="LOGO"
-                :alt="appName"
-            />
-            <LoadingBar />
-        </div>
-    </div>
-
-    <div
-        v-else
+        v-if="!isAppLoading"
         class="absolute bottom-0 left-0 right-0 top-0 flex w-full flex-col overflow-hidden"
     >
         <div class="flex-1 overflow-y-scroll scrollbar-hide">
diff --git a/app/src/bootSplash.spec.ts b/app/src/bootSplash.spec.ts
new file mode 100644
index 0000000000..7cb7ff6e6e
--- /dev/null
+++ b/app/src/bootSplash.spec.ts
@@ -0,0 +1,34 @@
+import { describe, it, expect } from "vitest";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { BOOT_SPLASH_ID, stripBootSplash } from "./bootSplash";
+
+const read = (relative: string) =>
+    readFileSync(fileURLToPath(new URL(relative, import.meta.url)), "utf8");
+
+const indexHtml = read("../index.html");
+
+// The splash is spread across index.html, main.ts and the web build's HTML transform, with
+// nothing at runtime that would fail loudly if one of the three drifted from the others.
+describe("boot splash", () => {
+    it("is present in index.html under the id main.ts removes", () => {
+        expect(indexHtml).toContain(`id="${BOOT_SPLASH_ID}"`);
+        expect(read("./main.ts")).toContain(`getElementById(BOOT_SPLASH_ID)`);
+    });
+
+    it("paints before the module entry, so it covers the whole boot", () => {
+        expect(indexHtml.indexOf(BOOT_SPLASH_ID)).toBeLessThan(indexHtml.indexOf('type="module"'));
+    });
+
+    it("references the logo by a root-absolute path, which resolves at any route depth", () => {
+        expect(indexHtml).toContain('src="/logo.svg"');
+    });
+
+    it("is stripped in full for the web build, leaving the rest of the page intact", () => {
+        const stripped = stripBootSplash(indexHtml);
+
+        expect(stripped).not.toMatch(/bootSplash|boot-splash|bs-slug|bs-track|bs-label/);
+        expect(stripped).toContain('<div id="app"></div>');
+        expect(stripped).toContain('type="module"');
+    });
+});
diff --git a/app/src/bootSplash.ts b/app/src/bootSplash.ts
new file mode 100644
index 0000000000..a5e18b5ed2
--- /dev/null
+++ b/app/src/bootSplash.ts
@@ -0,0 +1,16 @@
+/**
+ * The startup splash is plain HTML in `index.html` so it can paint before any module runs.
+ * `main.ts` removes it by this id once the app is ready; the marked block is what
+ * `stripBootSplash` drops.
+ */
+export const BOOT_SPLASH_ID = "bootSplash";
+
+const BOOT_SPLASH_BLOCK = /[ \t]*<!-- boot-splash:start -->[\s\S]*?<!-- boot-splash:end -->\n?/g;
+
+/**
+ * Remove the splash from an `index.html`. The web build ships already-rendered HTML, so it has
+ * no blank boot to cover and would otherwise bake a full-screen overlay into every static page.
+ */
+export function stripBootSplash(html: string): string {
+    return html.replace(BOOT_SPLASH_BLOCK, "");
+}
diff --git a/app/src/main.ts b/app/src/main.ts
index 80137642ac..8e1d74fca4 100644
--- a/app/src/main.ts
+++ b/app/src/main.ts
@@ -1,5 +1,5 @@
 import "./assets/main.css";
-import { createApp, watch } from "vue";
+import { createApp, nextTick, watch } from "vue";
 import { createPinia } from "pinia";
 import App from "./App.vue";
 import router from "./router";
@@ -23,6 +23,7 @@ import { APP_DOCS_INDEX } from "./docsIndex";
 import { initSentry, Sentry } from "@/util/initSentry";
 import { markAppReady, markAppError } from "@/util/renderState";
 import { initLivePublishClock } from "@/util/livePublishClock";
+import { BOOT_SPLASH_ID } from "./bootSplash";
 
 export const app = createApp(App);
 
@@ -130,6 +131,12 @@ async function Startup() {
     initSync();
 
     isAppLoading.value = false;
+
+    // Drop the pre-Vue splash from index.html only after the flag above has been rendered,
+    // so the app is already painted underneath and uncovering it can't expose a blank frame.
+    await nextTick();
+    document.getElementById(BOOT_SPLASH_ID)?.remove();
+
     initAppTitle(i18n);
     initAnalytics();
     markAppReady();
diff --git a/app/tsconfig.node.json b/app/tsconfig.node.json
index 12dc1ca603..9a71a2161d 100644
--- a/app/tsconfig.node.json
+++ b/app/tsconfig.node.json
@@ -7,6 +7,7 @@
         "vitest.config.*",
         "src/authStorage.ts",
         "src/themeStorage.ts",
+        "src/bootSplash.ts",
         "src/util/sessionNow.ts",
         "src/ssg/facetKeys.ts",
         "src/ssg/ssrChains.ts",
diff --git a/app/vite.config.web.ts b/app/vite.config.web.ts
index 34d126ef44..01608a2069 100644
--- a/app/vite.config.web.ts
+++ b/app/vite.config.web.ts
@@ -21,6 +21,7 @@ import {
     LEGACY_AUTH0_CACHE_PREFIX,
     OIDC_USER_PREFIX,
 } from "./src/authStorage";
+import { stripBootSplash } from "./src/bootSplash";
 import { releaseSsrChain } from "./src/ssg/ssrChains";
 import { takeRenderIssues, type RenderIssue } from "./src/ssg/renderDiagnostics";
 import { setSessionNow } from "./src/util/sessionNow";
@@ -462,7 +463,7 @@ const rewriteWebEntry = (): Plugin => ({
     name: "ssg-web-entry",
     transformIndexHtml: {
         order: "pre",
-        handler: (html) => html.replace("/src/main.ts", "/src/main.web.ts"),
+        handler: (html) => stripBootSplash(html.replace("/src/main.ts", "/src/main.web.ts")),
     },
 });
 

From 5ed5d71349af4545226becca176952613fe18230 Mon Sep 17 00:00:00 2001
From: Christian Touoyim <touoyim14christian@gmail.com>
Date: Wed, 2 Sep 2026 15:49:09 +0100
Subject: [PATCH 2/3] feat: implement boot splash screen with timeout handling
 and error reporting

---
 app/index.html                                | 108 ------------
 app/src/bootSplash.spec.ts                    |  83 +++++++--
 app/src/bootSplash.ts                         | 166 +++++++++++++++++-
 app/src/globalConfig.ts                       |  21 ++-
 app/src/initLanguage.spec.ts                  |  44 +++++
 app/src/main.ts                               |  28 ++-
 app/vite-plugins/bootSplash.ts                |  42 +++++
 app/vite.config.ts                            |   2 +
 app/vite.config.web.ts                        |   3 +-
 .../app/flows/boot-recovery.spec.ts           | 112 ++++++++++++
 shared/src/db/database.ts                     |  74 +++++---
 shared/src/db/dbOpenFailure.spec.ts           |  75 ++++++++
 12 files changed, 591 insertions(+), 167 deletions(-)
 create mode 100644 app/src/initLanguage.spec.ts
 create mode 100644 app/vite-plugins/bootSplash.ts
 create mode 100644 playwright-tests/app/flows/boot-recovery.spec.ts
 create mode 100644 shared/src/db/dbOpenFailure.spec.ts

diff --git a/app/index.html b/app/index.html
index 2ca0f4b245..254ef5a809 100644
--- a/app/index.html
+++ b/app/index.html
@@ -24,99 +24,6 @@
             content="#0f172a"
             media="(prefers-color-scheme: dark)"
         />
-
-        <!-- boot-splash:start -->
-        <!-- The splash in App.vue can only appear once Vue mounts, which is the second-to-last
-             step of Startup() — so the slow part of the boot (database open, auth) has nothing on
-             screen. This copy is plain HTML/CSS so it paints on first parse, and main.ts removes it
-             once the app is ready. Colours and metrics mirror App.vue + LoadingBar.vue; Tailwind is
-             unavailable this early, so they are written out longhand. -->
-        <script>
-            // Resolve the theme the way globalConfig does, before first paint, so the splash
-            // below is not white for a dark-mode user.
-            try {
-                var bootTheme = localStorage.getItem("theme");
-                if (
-                    bootTheme === "dark" ||
-                    (bootTheme !== "light" &&
-                        window.matchMedia("(prefers-color-scheme: dark)").matches)
-                ) {
-                    document.documentElement.classList.add("dark");
-                }
-            } catch (e) {
-                /* Storage can be unavailable (private mode); light is a safe default. */
-            }
-        </script>
-        <style>
-            #bootSplash {
-                position: fixed;
-                inset: 0;
-                z-index: 9999;
-                display: flex;
-                align-items: center;
-                justify-content: center;
-                background: #ffffff;
-                font-family:
-                    system-ui,
-                    -apple-system,
-                    sans-serif;
-            }
-            #bootSplash > div {
-                display: flex;
-                width: 100%;
-                flex-direction: column;
-                align-items: center;
-                gap: 1rem;
-            }
-            #bootSplash img {
-                width: 18rem;
-                max-width: 80%;
-            }
-            #bootSplash .bs-label {
-                font-size: 1.25rem;
-                font-weight: 600;
-                color: #71717a;
-            }
-            #bootSplash .bs-track {
-                position: relative;
-                height: 0.75rem;
-                width: 80%;
-                max-width: 28rem;
-                overflow: hidden;
-                border-radius: 9999px;
-                background: #e4e4e7;
-            }
-            #bootSplash .bs-slug {
-                position: absolute;
-                top: 0;
-                bottom: 0;
-                width: 40%;
-                border-radius: 9999px;
-                background: #71717a;
-                animation: bs-running-slug 1.2s linear infinite;
-            }
-            html.dark #bootSplash {
-                background: #0f172a;
-            }
-            html.dark #bootSplash .bs-label {
-                color: #94a3b8;
-            }
-            html.dark #bootSplash .bs-track {
-                background: #334155;
-            }
-            html.dark #bootSplash .bs-slug {
-                background: #94a3b8;
-            }
-            @keyframes bs-running-slug {
-                0% {
-                    left: -40%;
-                }
-                100% {
-                    left: 100%;
-                }
-            }
-        </style>
-        <!-- boot-splash:end -->
     </head>
     <body
         class="overscroll-none bg-white text-slate-900 dark:bg-slate-900 dark:text-slate-50"
@@ -126,21 +33,6 @@
         "
     >
         <div id="app"></div>
-        <!-- boot-splash:start -->
-        <!-- Served from public/, so the URL resolves from any route depth. -->
-        <div id="bootSplash">
-            <div>
-                <img
-                    src="/logo.svg"
-                    alt=""
-                />
-                <div class="bs-label">Loading...</div>
-                <div class="bs-track">
-                    <div class="bs-slug"></div>
-                </div>
-            </div>
-        </div>
-        <!-- boot-splash:end -->
         <script
             type="module"
             src="/src/main.ts"
diff --git a/app/src/bootSplash.spec.ts b/app/src/bootSplash.spec.ts
index 7cb7ff6e6e..9e609ae040 100644
--- a/app/src/bootSplash.spec.ts
+++ b/app/src/bootSplash.spec.ts
@@ -1,34 +1,83 @@
 import { describe, it, expect } from "vitest";
 import { readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
-import { BOOT_SPLASH_ID, stripBootSplash } from "./bootSplash";
+import {
+    BOOT_SPLASH_ID,
+    BOOT_SPLASH_OFF_CLASS,
+    DEFAULT_BOOT_LOGO,
+    bootSplashMarkup,
+    bootSplashPrePaintScript,
+    bootSplashStyle,
+    resolveBootLogo,
+} from "./bootSplash";
 
 const read = (relative: string) =>
     readFileSync(fileURLToPath(new URL(relative, import.meta.url)), "utf8");
 
-const indexHtml = read("../index.html");
-
-// The splash is spread across index.html, main.ts and the web build's HTML transform, with
-// nothing at runtime that would fail loudly if one of the three drifted from the others.
+// The splash is spread across this module, the Vite plugin that injects it, and main.ts's
+// removal, with nothing at runtime that would fail loudly if one drifted from the others.
 describe("boot splash", () => {
-    it("is present in index.html under the id main.ts removes", () => {
-        expect(indexHtml).toContain(`id="${BOOT_SPLASH_ID}"`);
-        expect(read("./main.ts")).toContain(`getElementById(BOOT_SPLASH_ID)`);
+    it("is injected by the SPA build only, never the web build", () => {
+        expect(read("../vite.config.ts")).toContain("bootSplash(env.VITE_LOGO)");
+        expect(read("../vite.config.web.ts")).not.toContain("bootSplash");
+        // Nothing inline in the template, so the web build cannot inherit it by accident.
+        expect(read("../index.html")).not.toContain(BOOT_SPLASH_ID);
+    });
+
+    it("uses the id main.ts removes once the app has rendered", () => {
+        expect(bootSplashMarkup()).toContain(`id="${BOOT_SPLASH_ID}"`);
+        expect(read("./main.ts")).toContain("getElementById(BOOT_SPLASH_ID)?.remove()");
     });
 
-    it("paints before the module entry, so it covers the whole boot", () => {
-        expect(indexHtml.indexOf(BOOT_SPLASH_ID)).toBeLessThan(indexHtml.indexOf('type="module"'));
+    it("switches to an error panel on the render state a failed startup sets", () => {
+        const style = bootSplashStyle();
+
+        expect(style).toContain(
+            `html[data-render-state="error"] #${BOOT_SPLASH_ID} .boot-splash-loading { display: none; }`,
+        );
+        expect(style).toContain(
+            `html[data-render-state="error"] #${BOOT_SPLASH_ID} .boot-splash-error { display: flex; }`,
+        );
+        expect(bootSplashMarkup()).toContain('id="boot-splash-reload"');
+        // markAppError() is what sets that attribute, and it must stay on the failure path.
+        expect(read("./main.ts")).toContain("markAppError()");
+    });
+
+    it("honours the ?nosplash opt-out that isAppLoading also honours", () => {
+        expect(bootSplashPrePaintScript()).toContain('has("nosplash")');
+        expect(bootSplashPrePaintScript()).toContain(BOOT_SPLASH_OFF_CLASS);
+        expect(bootSplashStyle()).toContain(
+            `html.${BOOT_SPLASH_OFF_CLASS} #${BOOT_SPLASH_ID} { display: none; }`,
+        );
+        expect(read("./globalConfig.ts")).toContain('has("nosplash")');
+    });
+
+    it("resolves the theme before paint, so an explicit choice beats the OS preference", () => {
+        const script = bootSplashPrePaintScript();
+
+        expect(script).toContain('theme === "dark"');
+        expect(script).toContain('theme !== "light"');
+        expect(script).toContain("prefers-color-scheme: dark");
+        expect(bootSplashStyle()).toContain(`html.dark #${BOOT_SPLASH_ID}`);
     });
 
-    it("references the logo by a root-absolute path, which resolves at any route depth", () => {
-        expect(indexHtml).toContain('src="/logo.svg"');
+    it("keeps a configured logo only when the browser can resolve it from any route", () => {
+        expect(resolveBootLogo("https://cdn.example.org/brand.svg")).toBe(
+            "https://cdn.example.org/brand.svg",
+        );
+        expect(resolveBootLogo("//cdn.example.org/brand.svg")).toBe("//cdn.example.org/brand.svg");
+        expect(resolveBootLogo("/brand.svg")).toBe("/brand.svg");
+        // The .env.example default: relative to the source tree, and never emitted by the build.
+        expect(resolveBootLogo("../src/assets/logo.svg")).toBe(DEFAULT_BOOT_LOGO);
+        expect(resolveBootLogo(undefined)).toBe(DEFAULT_BOOT_LOGO);
     });
 
-    it("is stripped in full for the web build, leaving the rest of the page intact", () => {
-        const stripped = stripBootSplash(indexHtml);
+    it("stays legible and still, for the readers who need it", () => {
+        const style = bootSplashStyle();
 
-        expect(stripped).not.toMatch(/bootSplash|boot-splash|bs-slug|bs-track|bs-label/);
-        expect(stripped).toContain('<div id="app"></div>');
-        expect(stripped).toContain('type="module"');
+        // Light-mode text at #d4d4d8 on white is 1.48:1 — below the threshold of perception.
+        expect(style).toContain("--boot-splash-fg: #71717a;");
+        expect(style).toContain("@media (prefers-reduced-motion: reduce)");
+        expect(bootSplashMarkup()).toContain('role="status"');
     });
 });
diff --git a/app/src/bootSplash.ts b/app/src/bootSplash.ts
index a5e18b5ed2..8063a40004 100644
--- a/app/src/bootSplash.ts
+++ b/app/src/bootSplash.ts
@@ -1,16 +1,164 @@
 /**
- * The startup splash is plain HTML in `index.html` so it can paint before any module runs.
- * `main.ts` removes it by this id once the app is ready; the marked block is what
- * `stripBootSplash` drops.
+ * The startup splash, as plain HTML/CSS/JS injected into `index.html` by
+ * `vite-plugins/bootSplash.ts`. The app mounts only after the data layer and auth have
+ * initialised, so without this everything before mount paints an empty `#app`.
+ *
+ * It sits outside `#app` rather than inside it, so it survives `app.mount()` and covers the
+ * wait for `initLanguage()` too; `main.ts` removes it by `BOOT_SPLASH_ID` once the app has
+ * rendered. Tailwind is not loaded this early, so the colours and metrics that mirror
+ * `LoadingBar.vue` are written out longhand.
  */
-export const BOOT_SPLASH_ID = "bootSplash";
+export const BOOT_SPLASH_ID = "boot-splash";
 
-const BOOT_SPLASH_BLOCK = /[ \t]*<!-- boot-splash:start -->[\s\S]*?<!-- boot-splash:end -->\n?/g;
+/** Mirrors the `?nosplash` opt-out `isAppLoading` honours, applied before first paint. */
+export const BOOT_SPLASH_OFF_CLASS = "boot-splash-off";
+
+/** Shipped in `public/`, so this URL resolves from any route depth. */
+export const DEFAULT_BOOT_LOGO = "/logo.svg";
 
 /**
- * Remove the splash from an `index.html`. The web build ships already-rendered HTML, so it has
- * no blank boot to cover and would otherwise bake a full-screen overlay into every static page.
+ * A configured logo is only usable here if the browser can resolve it from any route and the
+ * build actually publishes it. A path into the source tree (the `.env.example` default) meets
+ * neither, so it falls back to the copy in `public/`.
  */
-export function stripBootSplash(html: string): string {
-    return html.replace(BOOT_SPLASH_BLOCK, "");
+export function resolveBootLogo(configured?: string): string {
+    if (!configured) return DEFAULT_BOOT_LOGO;
+    const usable = /^(?:https?:)?\/\//.test(configured) || configured.startsWith("/");
+    return usable ? configured : DEFAULT_BOOT_LOGO;
+}
+
+const escapeAttribute = (value: string) =>
+    value.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+
+/**
+ * The error panel is driven purely by the `data-render-state` attribute `renderState.ts`
+ * already writes, so a failed boot needs no teardown coordination in `main.ts` — which never
+ * reaches its removal call on that path.
+ */
+export function bootSplashStyle(): string {
+    return `
+#${BOOT_SPLASH_ID} {
+    --boot-splash-bg: #ffffff;
+    --boot-splash-fg: #71717a;
+    --boot-splash-track: #e4e4e7;
+    --boot-splash-slug: #71717a;
+    position: fixed;
+    inset: 0;
+    z-index: 9999;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: var(--boot-splash-bg);
+    font-family: ui-sans-serif, system-ui, sans-serif;
+}
+html.dark #${BOOT_SPLASH_ID} {
+    --boot-splash-bg: #0f172a;
+    --boot-splash-fg: #94a3b8;
+    --boot-splash-track: #334155;
+    --boot-splash-slug: #94a3b8;
+}
+html.${BOOT_SPLASH_OFF_CLASS} #${BOOT_SPLASH_ID} { display: none; }
+#${BOOT_SPLASH_ID} .boot-splash-panel {
+    display: flex;
+    width: 100%;
+    flex-direction: column;
+    align-items: center;
+    gap: 1rem;
+    padding: 0 1rem;
+}
+#${BOOT_SPLASH_ID} .boot-splash-logo { width: 18rem; max-width: 80%; }
+#${BOOT_SPLASH_ID} .boot-splash-label {
+    margin: 0;
+    font-size: 1.25rem;
+    font-weight: 600;
+    color: var(--boot-splash-fg);
+    text-align: center;
+}
+#${BOOT_SPLASH_ID} .boot-splash-track {
+    position: relative;
+    height: 0.75rem;
+    width: 80%;
+    max-width: 28rem;
+    overflow: hidden;
+    border-radius: 9999px;
+    background: var(--boot-splash-track);
+}
+#${BOOT_SPLASH_ID} .boot-splash-slug {
+    position: absolute;
+    top: 0;
+    bottom: 0;
+    width: 40%;
+    border-radius: 9999px;
+    background: var(--boot-splash-slug);
+    animation: boot-splash-slug 1.2s linear infinite;
+}
+@keyframes boot-splash-slug {
+    0% { left: -40%; }
+    100% { left: 100%; }
+}
+@media (prefers-reduced-motion: reduce) {
+    #${BOOT_SPLASH_ID} .boot-splash-slug { animation: none; left: 30%; }
+}
+#${BOOT_SPLASH_ID} button {
+    border-radius: 0.375rem;
+    border: 1px solid var(--boot-splash-slug);
+    background: transparent;
+    padding: 0.5rem 1.25rem;
+    font-size: 1rem;
+    color: var(--boot-splash-fg);
+    cursor: pointer;
+}
+#${BOOT_SPLASH_ID} .boot-splash-error { display: none; }
+html[data-render-state="error"] #${BOOT_SPLASH_ID} .boot-splash-loading { display: none; }
+html[data-render-state="error"] #${BOOT_SPLASH_ID} .boot-splash-error { display: flex; }
+`.trim();
+}
+
+/**
+ * Both strings are hardcoded English: the splash paints long before i18n, whose messages come
+ * from Language documents fetched at runtime.
+ */
+export function bootSplashMarkup(configuredLogo?: string): string {
+    const logo = escapeAttribute(resolveBootLogo(configuredLogo));
+    return `<div id="${BOOT_SPLASH_ID}" role="status" aria-live="polite">
+    <div class="boot-splash-panel boot-splash-loading">
+        <img class="boot-splash-logo" src="${logo}" alt="" />
+        <p class="boot-splash-label">Loading...</p>
+        <div class="boot-splash-track"><div class="boot-splash-slug"></div></div>
+    </div>
+    <div class="boot-splash-panel boot-splash-error">
+        <p class="boot-splash-label">The app could not be started.</p>
+        <button type="button" id="boot-splash-reload">Reload</button>
+    </div>
+</div>`;
+}
+
+/**
+ * Runs during head parse, before the splash paints. The theme resolution mirrors
+ * `globalConfig`'s, so an explicit light/dark choice wins over the OS preference — a
+ * `prefers-color-scheme` media query alone would paint the wrong theme for those users.
+ */
+export function bootSplashPrePaintScript(): string {
+    return `(function () {
+    var el = document.documentElement;
+    try {
+        var theme = localStorage.getItem("theme");
+        if (theme === "dark" || (theme !== "light" && window.matchMedia("(prefers-color-scheme: dark)").matches)) {
+            el.classList.add("dark");
+        }
+    } catch (e) {}
+    try {
+        if (new URLSearchParams(window.location.search).has("nosplash")) {
+            el.classList.add("${BOOT_SPLASH_OFF_CLASS}");
+        }
+    } catch (e) {}
+})();`;
+}
+
+/** The only route out of the error panel, which `main.ts` cannot reach to wire up itself. */
+export function bootSplashReloadScript(): string {
+    return `(function () {
+    var button = document.getElementById("boot-splash-reload");
+    if (button) button.addEventListener("click", function () { window.location.reload(); });
+})();`;
 }
diff --git a/app/src/globalConfig.ts b/app/src/globalConfig.ts
index a32b767678..603fb1430a 100644
--- a/app/src/globalConfig.ts
+++ b/app/src/globalConfig.ts
@@ -274,8 +274,27 @@ export const appLanguageAsRef = computed(() => appLanguagesPreferredAsRef.value[
 /**
  * Initialize the language settings. If no user preferred language is set, the browser preferred language is used if it is supported. Otherwise, the CMS default language is used.
  */
+/**
+ * Language docs arrive only through sync, which is gated on the socket connecting, so a
+ * client that starts offline with an empty database would otherwise wait here forever —
+ * stranding the splash, sync startup and analytics behind it.
+ */
+const LANGUAGE_BOOT_TIMEOUT_MS = 5_000;
+
 export const initLanguage = () => {
     return new Promise<void>((resolve) => {
+        let settled = false;
+        const settle = () => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(bootTimeout);
+            resolve();
+        };
+
+        // Let boot continue without languages. The watcher below is deliberately left
+        // live in that case, so a later sync still normalizes the preferred/synced sets.
+        const bootTimeout = setTimeout(settle, LANGUAGE_BOOT_TIMEOUT_MS);
+
         // Language is a fully-synced type, so this HybridQuery reads from IndexedDB
         // only. Constructed at app scope (never disposed) — its output ref feeds the
         // shared cmsLanguages list.
@@ -342,7 +361,7 @@ export const initLanguage = () => {
                 );
 
                 unwatchCmsLanguages();
-                resolve();
+                settle();
             },
             { deep: true },
         );
diff --git a/app/src/initLanguage.spec.ts b/app/src/initLanguage.spec.ts
new file mode 100644
index 0000000000..b0bcf9562d
--- /dev/null
+++ b/app/src/initLanguage.spec.ts
@@ -0,0 +1,44 @@
+import "fake-indexeddb/auto";
+import { describe, it, expect, afterEach } from "vitest";
+import { db } from "luminary-shared";
+import { appLanguageIdsAsRef, initLanguage } from "@/globalConfig";
+import { mockLanguageDtoEng } from "./tests/mockdata";
+import waitForExpect from "wait-for-expect";
+
+/**
+ * `initLanguage()` is awaited in main.ts between `app.mount()` and
+ * `isAppLoading.value = false`, so a promise that never settles here leaves the app on
+ * the splash with sync, analytics and `markAppReady()` all stranded behind it. Language
+ * docs arrive only through sync, which is gated on the socket, so an offline cold start
+ * has no way to satisfy it.
+ */
+
+const settledWithin = (promise: Promise<unknown>, ms: number) =>
+    Promise.race([
+        promise.then(() => "settled" as const),
+        new Promise<"pending">((resolve) => setTimeout(() => resolve("pending"), ms)),
+    ]);
+
+describe("initLanguage", () => {
+    afterEach(async () => {
+        await db.docs.clear();
+    });
+
+    it("resolves without Language docs so an offline cold start still boots", async () => {
+        await db.docs.clear();
+
+        expect(await settledWithin(initLanguage(), 15_000)).toBe("settled");
+    });
+
+    it("still normalizes the preferred languages once a later sync delivers them", async () => {
+        await db.docs.clear();
+
+        await initLanguage();
+        await db.docs.bulkPut([mockLanguageDtoEng]);
+
+        // The watcher is left live when boot continued without languages.
+        await waitForExpect(() => {
+            expect(appLanguageIdsAsRef.value).toContain(mockLanguageDtoEng._id);
+        });
+    });
+});
diff --git a/app/src/main.ts b/app/src/main.ts
index 8e1d74fca4..9554f59398 100644
--- a/app/src/main.ts
+++ b/app/src/main.ts
@@ -33,6 +33,19 @@ app.use(createPinia());
 
 initSentry(app);
 
+/**
+ * Backstop for a startup that stalls instead of failing. Nothing below rejects on a
+ * promise that simply never settles, so without this the user sits on the boot splash
+ * and nothing is reported. Comfortably above the ~30s worst case of a slow silent
+ * token refresh so a slow-but-working boot is not flagged.
+ */
+const BOOT_TIMEOUT_MS = 45_000;
+
+const bootWatchdog = setTimeout(() => {
+    markAppError();
+    Sentry?.captureMessage(`App boot did not complete within ${BOOT_TIMEOUT_MS}ms`, "error");
+}, BOOT_TIMEOUT_MS);
+
 /**
  * Content sync window. Installed (standalone) sessions sync the full corpus (no
  * cutoff). Browser-tab sessions sync only the last ~1 month; content with
@@ -63,9 +76,6 @@ async function Startup() {
         contentPublishDateCutoff: installedStandalone
             ? undefined // no cutoff → full corpus
             : Date.now() - BROWSER_CONTENT_SYNC_WINDOW_MS,
-    }).catch((err) => {
-        console.error(err);
-        Sentry?.captureException(err);
     });
 
     // Keep the CMS-managed default-affinity baseline/config in sync with the local
@@ -101,7 +111,9 @@ async function Startup() {
     watch(serverError, (error) => {
         if (error) {
             serverError.value = null;
-            console.error(`Server error: ${error.status}${error.message ? ` ${error.message}` : ""}`);
+            console.error(
+                `Server error: ${error.status}${error.message ? ` ${error.message}` : ""}`,
+            );
             if (serverErrorTimeout) return;
             Sentry?.captureMessage(
                 `Server error: ${error.status}${error.message ? ` ${error.message}` : ""}`,
@@ -132,17 +144,21 @@ async function Startup() {
 
     isAppLoading.value = false;
 
-    // Drop the pre-Vue splash from index.html only after the flag above has been rendered,
-    // so the app is already painted underneath and uncovering it can't expose a blank frame.
+    // Drop the boot splash only after the flag above has been rendered, so the app is already
+    // painted underneath and uncovering it can't expose a blank frame. A failed startup never
+    // reaches this line, which is deliberate: markAppError() below leaves the splash up and
+    // switches it to its error panel rather than stranding the user on an animating bar.
     await nextTick();
     document.getElementById(BOOT_SPLASH_ID)?.remove();
 
     initAppTitle(i18n);
     initAnalytics();
+    clearTimeout(bootWatchdog);
     markAppReady();
 }
 
 Startup().catch((err) => {
+    clearTimeout(bootWatchdog);
     console.error(err);
     Sentry?.captureException(err);
     markAppError();
diff --git a/app/vite-plugins/bootSplash.ts b/app/vite-plugins/bootSplash.ts
new file mode 100644
index 0000000000..2fae711a39
--- /dev/null
+++ b/app/vite-plugins/bootSplash.ts
@@ -0,0 +1,42 @@
+import type { Plugin } from "vite";
+import {
+    bootSplashMarkup,
+    bootSplashPrePaintScript,
+    bootSplashReloadScript,
+    bootSplashStyle,
+} from "../src/bootSplash";
+
+/**
+ * Injects the startup splash into `index.html`. Wired into `vite.config.ts` only — the web build
+ * ships already-rendered HTML, so it has no blank boot to cover and would otherwise bake a
+ * full-screen overlay into every static page.
+ */
+export function bootSplash(configuredLogo?: string): Plugin {
+    return {
+        name: "boot-splash",
+        transformIndexHtml: {
+            order: "pre",
+            handler: (html) => ({
+                // After `#app`, so the splash is a sibling the app renders behind rather than
+                // content `app.mount()` would discard.
+                html: html.replace(
+                    '<div id="app"></div>',
+                    `<div id="app"></div>\n        ${bootSplashMarkup(configuredLogo)}`,
+                ),
+                tags: [
+                    { tag: "style", injectTo: "head" as const, children: bootSplashStyle() },
+                    {
+                        tag: "script",
+                        injectTo: "head" as const,
+                        children: bootSplashPrePaintScript(),
+                    },
+                    {
+                        tag: "script",
+                        injectTo: "body" as const,
+                        children: bootSplashReloadScript(),
+                    },
+                ],
+            }),
+        },
+    };
+}
diff --git a/app/vite.config.ts b/app/vite.config.ts
index 0532699592..6ad3ecd056 100644
--- a/app/vite.config.ts
+++ b/app/vite.config.ts
@@ -7,6 +7,7 @@ import { VitePWA } from "vite-plugin-pwa";
 // @ts-expect-error - JavaScript module without type declarations
 import movePreloadScriptsToBody from "./src/assets/vite-plugins/movePreloadScriptsToBody.js";
 import { buildTargetVirtuals } from "./vite-plugins/buildTargetVirtuals";
+import { bootSplash } from "./vite-plugins/bootSplash";
 
 const env = loadEnv("", process.cwd());
 
@@ -55,6 +56,7 @@ export default defineConfig({
     plugins: [
         blockGeneratedOutput(),
         buildTargetVirtuals(),
+        bootSplash(env.VITE_LOGO),
         visualizer({ open: false }), // Open visualiser when reviewing build bundle size
         vue(),
         viteStaticCopy({
diff --git a/app/vite.config.web.ts b/app/vite.config.web.ts
index 01608a2069..34d126ef44 100644
--- a/app/vite.config.web.ts
+++ b/app/vite.config.web.ts
@@ -21,7 +21,6 @@ import {
     LEGACY_AUTH0_CACHE_PREFIX,
     OIDC_USER_PREFIX,
 } from "./src/authStorage";
-import { stripBootSplash } from "./src/bootSplash";
 import { releaseSsrChain } from "./src/ssg/ssrChains";
 import { takeRenderIssues, type RenderIssue } from "./src/ssg/renderDiagnostics";
 import { setSessionNow } from "./src/util/sessionNow";
@@ -463,7 +462,7 @@ const rewriteWebEntry = (): Plugin => ({
     name: "ssg-web-entry",
     transformIndexHtml: {
         order: "pre",
-        handler: (html) => stripBootSplash(html.replace("/src/main.ts", "/src/main.web.ts")),
+        handler: (html) => html.replace("/src/main.ts", "/src/main.web.ts"),
     },
 });
 
diff --git a/playwright-tests/app/flows/boot-recovery.spec.ts b/playwright-tests/app/flows/boot-recovery.spec.ts
new file mode 100644
index 0000000000..0ded0b776b
--- /dev/null
+++ b/playwright-tests/app/flows/boot-recovery.spec.ts
@@ -0,0 +1,112 @@
+import type { Page } from "@playwright/test";
+import { appTest as test, expect } from "../../fixtures/test";
+
+/**
+ * The app mounts only after the database, sync and auth have initialised, so everything
+ * before mount paints an empty `#app` unless the build injects a splash — and a boot that
+ * stalls in that window leaves the user with nothing reported at all. These cover the
+ * splash and the recovery paths it reports through: bounded database opens, and a
+ * language wait that gives up.
+ */
+
+/**
+ * Replaces the IndexedDB open the boot path starts with. `blocked` is what a browser
+ * reports when another connection still holds the database; `silent` never answers at
+ * all, which is the case no event can rescue.
+ */
+async function breakIndexedDbOpen(page: Page, mode: "blocked" | "silent") {
+  await page.addInitScript((stubMode) => {
+    Object.defineProperty(window.indexedDB, "open", {
+      configurable: true,
+      value: () => {
+        const request: Record<string, unknown> = {};
+        if (stubMode === "blocked") {
+          setTimeout(() => {
+            (request.onblocked as (() => void) | undefined)?.();
+          }, 0);
+        }
+        return request;
+      },
+    });
+  }, mode);
+}
+
+test.describe("App boot recovery", () => {
+  test("serves the boot splash alongside #app", async ({ page }) => {
+    // Asserted against the raw HTML because the splash is injected by a string
+    // replace on `<div id="app"></div>`, which no-ops silently if that markup
+    // ever changes — leaving the pre-mount window blank again.
+    const html = await (await page.request.get("/")).text();
+
+    expect(html).toMatch(/<div id="app"><\/div>\s*<div id="boot-splash"/);
+  });
+
+  test("removes the boot splash once the app mounts", async ({ page }) => {
+    await page.goto("/");
+
+    await expect(page.getByRole("main")).toBeVisible();
+    await expect(page.locator("#boot-splash")).toHaveCount(0);
+  });
+
+  test.describe("before scripts run", () => {
+    // Approximates the pre-mount window: the splash has to stand on its own markup
+    // and CSS, with no help from the bundle.
+    test.use({ javaScriptEnabled: false });
+
+    test("covers the viewport", async ({ page }) => {
+      await page.goto("/");
+
+      await expect(page.locator("#boot-splash")).toBeVisible();
+      await expect(page.locator("#boot-splash")).toContainText("Loading");
+    });
+  });
+
+  test("reports an error when the database open is blocked", async ({
+    page,
+  }) => {
+    await breakIndexedDbOpen(page, "blocked");
+    await page.goto("/");
+
+    await expect(page.locator("#boot-splash .boot-splash-error")).toBeVisible({
+      timeout: 20_000,
+    });
+    await expect(page.getByRole("button", { name: "Reload" })).toBeVisible();
+    await expect(page.locator("html")).toHaveAttribute(
+      "data-render-state",
+      "error",
+    );
+  });
+
+  test("does not strand the splash when the socket never connects", async ({
+    page,
+  }) => {
+    // Only the socket is blocked — REST stays reachable. Language docs are a
+    // fully-synced type whose sync is gated on `isConnected`, so a client that
+    // cannot open a socket never receives them, and `initLanguage()` is awaited
+    // between mount and the splash being cleared.
+    await page.route("**/socket.io/**", (route) => route.abort());
+    await page.goto("/");
+
+    // Mounted: the static splash is gone, so the boot path got past app.mount().
+    await expect(page.locator("#boot-splash")).toHaveCount(0);
+
+    // The app must still become usable offline rather than sitting on the splash.
+    await expect(page.getByRole("main")).toBeVisible({ timeout: 30_000 });
+  });
+
+  test("reports an error when the database open never answers", async ({
+    page,
+  }) => {
+    await breakIndexedDbOpen(page, "silent");
+    await page.goto("/");
+
+    // Bounded by the boot-path open timeout rather than waiting forever.
+    await expect(page.locator("#boot-splash .boot-splash-error")).toBeVisible({
+      timeout: 30_000,
+    });
+    await expect(page.locator("html")).toHaveAttribute(
+      "data-render-state",
+      "error",
+    );
+  });
+});
diff --git a/shared/src/db/database.ts b/shared/src/db/database.ts
index 5d9567f96d..5ec67ff5c6 100644
--- a/shared/src/db/database.ts
+++ b/shared/src/db/database.ts
@@ -874,30 +874,47 @@ class Database extends Dexie {
 
 export let db: Database;
 
+/**
+ * IndexedDB gives no answer at all when an open is blocked by another connection, so
+ * every open in the boot path is bounded.
+ */
+const DB_OPEN_TIMEOUT_MS = 10_000;
+
+function withDbTimeout<T>(promise: Promise<T>, action: string): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+        const timeout = setTimeout(
+            () => reject(new Error(`Timed out trying to ${action}`)),
+            DB_OPEN_TIMEOUT_MS,
+        );
+        promise.then(
+            (value) => {
+                clearTimeout(timeout);
+                resolve(value);
+            },
+            (error) => {
+                clearTimeout(timeout);
+                reject(error);
+            },
+        );
+    });
+}
+
 export async function initDatabase() {
     const _v: number = await getDbVersion();
     db = new Database(_v, config.docsIndex);
 
-    // Open the database and wait for it to be ready
-    await new Promise<void>((resolve) => {
-        if (db.isOpen()) {
-            resolve();
-            return;
-        }
-
-        db.on("ready", () => {
-            resolve();
-        });
-
-        if (!db.isOpen()) {
-            db.open();
-        }
-    });
-
+    // Registered before open(): a blocked upgrade is what this reports, and it is
+    // raised during the open, not after it.
     db.on("blocked", () => {
         console.error("Database blocked");
     });
 
+    // Awaiting open() rather than the "ready" event means a rejected open is raised
+    // as a boot error instead of leaving this promise unsettled.
+    if (!db.isOpen()) {
+        await withDbTimeout(db.open(), "open the database");
+    }
+
     // Compute FTS corpus stats on startup.
     // Uses setTimeout(0) to avoid Dexie PSD zone deadlocks during initialization.
     setTimeout(() => {
@@ -979,13 +996,21 @@ async function resetGroupSyncListForRecovery() {
 }
 
 /**
- * Get IndexDB version before DB class is initialized
+ * Get IndexDB version before DB class is initialized. Rejects rather than staying
+ * unsettled when the open is blocked or fails, because this runs before the app is
+ * mounted and an unsettled promise here strands the user on the boot screen.
  * @returns IndexDB Version
  */
-export const getDbVersion = async () => {
-    const request = indexedDB.open(dbName);
-    return new Promise((resolve) => {
+export const getDbVersion = () =>
+    new Promise<number>((resolve, reject) => {
+        const request = indexedDB.open(dbName);
+        const timeout = setTimeout(
+            () => reject(new Error("Timed out reading the database version")),
+            DB_OPEN_TIMEOUT_MS,
+        );
+
         request.onsuccess = (event: any) => {
+            clearTimeout(timeout);
             const db = event.target.result;
             const version: number = (db && db.version) || 0;
             db.addEventListener("close", () => {});
@@ -993,13 +1018,14 @@ export const getDbVersion = async () => {
             resolve(version);
         };
         request.onblocked = () => {
-            console.error("Database blocked");
+            clearTimeout(timeout);
+            reject(new Error("Database blocked while reading the database version"));
         };
         request.onerror = () => {
-            console.error("Database error");
+            clearTimeout(timeout);
+            reject(new Error("Database error while reading the database version"));
         };
-    }) as unknown as Promise<number>;
-};
+    });
 
 /**
  * Concatenate Shared Library index with the external index, to avoid having duplicate indexes
diff --git a/shared/src/db/dbOpenFailure.spec.ts b/shared/src/db/dbOpenFailure.spec.ts
new file mode 100644
index 0000000000..c859f15727
--- /dev/null
+++ b/shared/src/db/dbOpenFailure.spec.ts
@@ -0,0 +1,75 @@
+import "fake-indexeddb/auto";
+import { describe, it, expect, afterEach, vi } from "vitest";
+import Dexie from "dexie";
+import { getDbVersion, initDatabase } from "./database";
+import { initConfig } from "../config";
+
+// The boot-path database opens run before the app is mounted, so a promise that never
+// settles here strands the user on the boot splash with nothing reported.
+const originalIndexedDb = globalThis.indexedDB;
+
+function stubOpen(fire: "onsuccess" | "onblocked" | "onerror" | "never") {
+    const request: Record<string, ((event?: unknown) => void) | undefined> = {};
+    (globalThis as any).indexedDB = {
+        open: () => {
+            if (fire !== "never") {
+                setTimeout(() => {
+                    if (fire === "onsuccess") {
+                        request.onsuccess?.({
+                            target: { result: { version: 70, addEventListener() {}, close() {} } },
+                        });
+                    } else {
+                        request[fire]?.();
+                    }
+                }, 0);
+            }
+            return request;
+        },
+    };
+}
+
+describe("getDbVersion", () => {
+    afterEach(() => {
+        vi.useRealTimers();
+        (globalThis as any).indexedDB = originalIndexedDb;
+    });
+
+    it("resolves the version when the open succeeds", async () => {
+        stubOpen("onsuccess");
+        await expect(getDbVersion()).resolves.toBe(70);
+    });
+
+    it("rejects when the open is blocked by another connection", async () => {
+        stubOpen("onblocked");
+        await expect(getDbVersion()).rejects.toThrow(/blocked/i);
+    });
+
+    it("rejects when the open errors", async () => {
+        stubOpen("onerror");
+        await expect(getDbVersion()).rejects.toThrow(/error/i);
+    });
+
+    it("rejects when the open never answers at all", async () => {
+        vi.useFakeTimers();
+        stubOpen("never");
+
+        const assertion = expect(getDbVersion()).rejects.toThrow(/timed out/i);
+        await vi.advanceTimersByTimeAsync(10_000);
+        await assertion;
+    });
+});
+
+describe("initDatabase", () => {
+    afterEach(() => vi.restoreAllMocks());
+
+    it("rejects when the database open fails", async () => {
+        initConfig({
+            cms: false,
+            docsIndex: "[type+postType]",
+            apiUrl: "http://localhost:12345",
+        });
+        vi.spyOn(Dexie.prototype, "open").mockRejectedValue(new Error("VersionError"));
+
+        await expect(initDatabase()).rejects.toThrow("VersionError");
+    });
+});

From 536453bc921cbeaa0e323085ac8a4dd56c17b99f Mon Sep 17 00:00:00 2001
From: Christian Touoyim <touoyim14christian@gmail.com>
Date: Thu, 3 Sep 2026 13:23:34 +0100
Subject: [PATCH 3/3] feat: enhance app loading behavior with improved language
 sync handling and timeout removal

---
 app/src/globalConfig.ts                       |  51 ++++----
 app/src/initLanguage.spec.ts                  |  54 ++++++--
 app/src/main.ts                               |  15 ---
 .../app/flows/boot-recovery.spec.ts           |  51 ++++----
 shared/src/db/database.ts                     |  75 ++++++-----
 shared/src/db/dbOpenFailure.spec.ts           | 118 +++++++++++++-----
 6 files changed, 222 insertions(+), 142 deletions(-)

diff --git a/app/src/globalConfig.ts b/app/src/globalConfig.ts
index 603fb1430a..7fa921a539 100644
--- a/app/src/globalConfig.ts
+++ b/app/src/globalConfig.ts
@@ -1,11 +1,13 @@
 import {
     DocType,
     HybridQuery,
+    isConnected,
+    syncActive,
     type LanguageDto,
     type Uuid,
     type ContentDto,
 } from "luminary-shared";
-import { computed, ref, watch } from "vue";
+import { computed, ref, watch, watchEffect, type WatchStopHandle } from "vue";
 import { loadFallbackImageUrls } from "./util/loadFallbackImages";
 
 export const appName = import.meta.env.VITE_APP_NAME;
@@ -274,27 +276,9 @@ export const appLanguageAsRef = computed(() => appLanguagesPreferredAsRef.value[
 /**
  * Initialize the language settings. If no user preferred language is set, the browser preferred language is used if it is supported. Otherwise, the CMS default language is used.
  */
-/**
- * Language docs arrive only through sync, which is gated on the socket connecting, so a
- * client that starts offline with an empty database would otherwise wait here forever —
- * stranding the splash, sync startup and analytics behind it.
- */
-const LANGUAGE_BOOT_TIMEOUT_MS = 5_000;
-
 export const initLanguage = () => {
     return new Promise<void>((resolve) => {
-        let settled = false;
-        const settle = () => {
-            if (settled) return;
-            settled = true;
-            clearTimeout(bootTimeout);
-            resolve();
-        };
-
-        // Let boot continue without languages. The watcher below is deliberately left
-        // live in that case, so a later sync still normalizes the preferred/synced sets.
-        const bootTimeout = setTimeout(settle, LANGUAGE_BOOT_TIMEOUT_MS);
-
+        let booted = false;
         // Language is a fully-synced type, so this HybridQuery reads from IndexedDB
         // only. Constructed at app scope (never disposed) — its output ref feeds the
         // shared cmsLanguages list.
@@ -361,10 +345,35 @@ export const initLanguage = () => {
                 );
 
                 unwatchCmsLanguages();
-                settle();
+                booted = true;
+                resolve();
             },
             { deep: true },
         );
+
+        // Languages arrive only through sync, so a client that starts offline with an empty
+        // database has nothing to wait for. Rather than giving the wait a deadline, boot on
+        // the conditions that mean none are coming: no connection to deliver them, or a sync
+        // pass that has run to completion and left the local set empty. The watcher above is
+        // deliberately left live either way, so a later sync still normalizes the
+        // preferred/synced sets.
+        let sawSyncRun = false;
+        let stopBootGate: WatchStopHandle = () => {};
+        stopBootGate = watchEffect(() => {
+            if (booted) return stopBootGate();
+            if (syncActive.value) sawSyncRun = true;
+
+            // Still a chance of languages: the local read is in flight, or some arrived.
+            if (languagesQuery.isFetching.value) return;
+            if (cmsLanguages.value.length > 0) return;
+
+            const syncPassFinished = sawSyncRun && !syncActive.value;
+            if (isConnected.value && !syncPassFinished) return;
+
+            booted = true;
+            resolve();
+            stopBootGate();
+        });
     });
 };
 
diff --git a/app/src/initLanguage.spec.ts b/app/src/initLanguage.spec.ts
index b0bcf9562d..2578670c12 100644
--- a/app/src/initLanguage.spec.ts
+++ b/app/src/initLanguage.spec.ts
@@ -1,16 +1,16 @@
 import "fake-indexeddb/auto";
 import { describe, it, expect, afterEach } from "vitest";
-import { db } from "luminary-shared";
-import { appLanguageIdsAsRef, initLanguage } from "@/globalConfig";
+import { db, isConnected, syncActive } from "luminary-shared";
+import { appLanguageIdsAsRef, cmsLanguages, initLanguage } from "@/globalConfig";
 import { mockLanguageDtoEng } from "./tests/mockdata";
 import waitForExpect from "wait-for-expect";
 
 /**
  * `initLanguage()` is awaited in main.ts between `app.mount()` and
- * `isAppLoading.value = false`, so a promise that never settles here leaves the app on
- * the splash with sync, analytics and `markAppReady()` all stranded behind it. Language
- * docs arrive only through sync, which is gated on the socket, so an offline cold start
- * has no way to satisfy it.
+ * `isAppLoading.value = false`, so a promise that never settles here leaves the app on the
+ * splash with sync, analytics and `markAppReady()` all stranded behind it. Language docs
+ * arrive only through sync, so it resolves early on the conditions that mean none are
+ * coming — no connection, or a sync pass that finished empty — rather than on a deadline.
  */
 
 const settledWithin = (promise: Promise<unknown>, ms: number) =>
@@ -22,16 +22,50 @@ const settledWithin = (promise: Promise<unknown>, ms: number) =>
 describe("initLanguage", () => {
     afterEach(async () => {
         await db.docs.clear();
+        cmsLanguages.value.length = 0;
+        isConnected.value = false;
+        syncActive.value = false;
     });
 
-    it("resolves without Language docs so an offline cold start still boots", async () => {
-        await db.docs.clear();
+    it("boots offline, where sync can never deliver languages", async () => {
+        isConnected.value = false;
+
+        expect(await settledWithin(initLanguage(), 500)).toBe("settled");
+    });
+
+    it("keeps waiting while a connection could still deliver them", async () => {
+        isConnected.value = true;
+        syncActive.value = true;
 
-        expect(await settledWithin(initLanguage(), 15_000)).toBe("settled");
+        // Nothing has ruled languages out yet, so boot must not continue without them.
+        expect(await settledWithin(initLanguage(), 500)).toBe("pending");
+    });
+
+    it("boots once a sync pass has run and left the set empty", async () => {
+        isConnected.value = true;
+        syncActive.value = true;
+
+        const pending = initLanguage();
+        expect(await settledWithin(pending, 200)).toBe("pending");
+
+        // The pass completes having delivered no Language docs: none are coming.
+        syncActive.value = false;
+
+        expect(await settledWithin(pending, 500)).toBe("settled");
+    });
+
+    it("resolves as soon as languages arrive", async () => {
+        isConnected.value = true;
+        syncActive.value = true;
+
+        const pending = initLanguage();
+        await db.docs.bulkPut([mockLanguageDtoEng]);
+
+        expect(await settledWithin(pending, 2_000)).toBe("settled");
     });
 
     it("still normalizes the preferred languages once a later sync delivers them", async () => {
-        await db.docs.clear();
+        isConnected.value = false;
 
         await initLanguage();
         await db.docs.bulkPut([mockLanguageDtoEng]);
diff --git a/app/src/main.ts b/app/src/main.ts
index 9554f59398..6891a5f00d 100644
--- a/app/src/main.ts
+++ b/app/src/main.ts
@@ -33,19 +33,6 @@ app.use(createPinia());
 
 initSentry(app);
 
-/**
- * Backstop for a startup that stalls instead of failing. Nothing below rejects on a
- * promise that simply never settles, so without this the user sits on the boot splash
- * and nothing is reported. Comfortably above the ~30s worst case of a slow silent
- * token refresh so a slow-but-working boot is not flagged.
- */
-const BOOT_TIMEOUT_MS = 45_000;
-
-const bootWatchdog = setTimeout(() => {
-    markAppError();
-    Sentry?.captureMessage(`App boot did not complete within ${BOOT_TIMEOUT_MS}ms`, "error");
-}, BOOT_TIMEOUT_MS);
-
 /**
  * Content sync window. Installed (standalone) sessions sync the full corpus (no
  * cutoff). Browser-tab sessions sync only the last ~1 month; content with
@@ -153,12 +140,10 @@ async function Startup() {
 
     initAppTitle(i18n);
     initAnalytics();
-    clearTimeout(bootWatchdog);
     markAppReady();
 }
 
 Startup().catch((err) => {
-    clearTimeout(bootWatchdog);
     console.error(err);
     Sentry?.captureException(err);
     markAppError();
diff --git a/playwright-tests/app/flows/boot-recovery.spec.ts b/playwright-tests/app/flows/boot-recovery.spec.ts
index 0ded0b776b..5f62a6f7e4 100644
--- a/playwright-tests/app/flows/boot-recovery.spec.ts
+++ b/playwright-tests/app/flows/boot-recovery.spec.ts
@@ -11,20 +11,19 @@ import { appTest as test, expect } from "../../fixtures/test";
 
 /**
  * Replaces the IndexedDB open the boot path starts with. `blocked` is what a browser
- * reports when another connection still holds the database; `silent` never answers at
- * all, which is the case no event can rescue.
+ * reports while another connection still holds an older version open — a wait that clears
+ * itself. `error` is an open that genuinely cannot succeed.
  */
-async function breakIndexedDbOpen(page: Page, mode: "blocked" | "silent") {
+async function breakIndexedDbOpen(page: Page, mode: "blocked" | "error") {
   await page.addInitScript((stubMode) => {
     Object.defineProperty(window.indexedDB, "open", {
       configurable: true,
       value: () => {
         const request: Record<string, unknown> = {};
-        if (stubMode === "blocked") {
-          setTimeout(() => {
-            (request.onblocked as (() => void) | undefined)?.();
-          }, 0);
-        }
+        setTimeout(() => {
+          const handler = stubMode === "blocked" ? "onblocked" : "onerror";
+          (request[handler] as (() => void) | undefined)?.();
+        }, 0);
         return request;
       },
     });
@@ -61,15 +60,27 @@ test.describe("App boot recovery", () => {
     });
   });
 
-  test("reports an error when the database open is blocked", async ({
+  test("keeps waiting, not failing, while the database open is blocked", async ({
     page,
   }) => {
+    // Another connection holding an older version open is a state that clears itself when
+    // that connection closes, so the boot waits on the splash rather than declaring failure.
     await breakIndexedDbOpen(page, "blocked");
     await page.goto("/");
 
-    await expect(page.locator("#boot-splash .boot-splash-error")).toBeVisible({
-      timeout: 20_000,
-    });
+    await expect(page.locator("#boot-splash")).toBeVisible();
+    await expect(page.locator("#boot-splash .boot-splash-error")).toBeHidden();
+    await expect(page.locator("html")).not.toHaveAttribute(
+      "data-render-state",
+      "error",
+    );
+  });
+
+  test("reports an error when the database open fails", async ({ page }) => {
+    await breakIndexedDbOpen(page, "error");
+    await page.goto("/");
+
+    await expect(page.locator("#boot-splash .boot-splash-error")).toBeVisible();
     await expect(page.getByRole("button", { name: "Reload" })).toBeVisible();
     await expect(page.locator("html")).toHaveAttribute(
       "data-render-state",
@@ -93,20 +104,4 @@ test.describe("App boot recovery", () => {
     // The app must still become usable offline rather than sitting on the splash.
     await expect(page.getByRole("main")).toBeVisible({ timeout: 30_000 });
   });
-
-  test("reports an error when the database open never answers", async ({
-    page,
-  }) => {
-    await breakIndexedDbOpen(page, "silent");
-    await page.goto("/");
-
-    // Bounded by the boot-path open timeout rather than waiting forever.
-    await expect(page.locator("#boot-splash .boot-splash-error")).toBeVisible({
-      timeout: 30_000,
-    });
-    await expect(page.locator("html")).toHaveAttribute(
-      "data-render-state",
-      "error",
-    );
-  });
 });
diff --git a/shared/src/db/database.ts b/shared/src/db/database.ts
index 5ec67ff5c6..b8492a4a7f 100644
--- a/shared/src/db/database.ts
+++ b/shared/src/db/database.ts
@@ -15,7 +15,7 @@ import {
     Uuid,
 } from "../types";
 import { scheduleCorpusStatsRecompute } from "../fts/ftsIndexer";
-import { toRaw, watch } from "vue";
+import { ref, toRaw, watch } from "vue";
 import { DateTime } from "luxon";
 import { v4 as uuidv4 } from "uuid";
 import { filterAsync, someAsync } from "../util/asyncArray";
@@ -875,45 +875,44 @@ class Database extends Dexie {
 export let db: Database;
 
 /**
- * IndexedDB gives no answer at all when an open is blocked by another connection, so
- * every open in the boot path is bounded.
+ * Raised when another tab holds an older version of the database open and this one is
+ * waiting to upgrade. The wait resolves on its own once that tab closes its connection,
+ * so this is a state to surface, not an error — the app binds a notification to it.
  */
-const DB_OPEN_TIMEOUT_MS = 10_000;
-
-function withDbTimeout<T>(promise: Promise<T>, action: string): Promise<T> {
-    return new Promise<T>((resolve, reject) => {
-        const timeout = setTimeout(
-            () => reject(new Error(`Timed out trying to ${action}`)),
-            DB_OPEN_TIMEOUT_MS,
-        );
-        promise.then(
-            (value) => {
-                clearTimeout(timeout);
-                resolve(value);
-            },
-            (error) => {
-                clearTimeout(timeout);
-                reject(error);
-            },
-        );
-    });
-}
+export const dbUpgradeBlocked = ref(false);
 
 export async function initDatabase() {
     const _v: number = await getDbVersion();
     db = new Database(_v, config.docsIndex);
 
-    // Registered before open(): a blocked upgrade is what this reports, and it is
-    // raised during the open, not after it.
+    // Registered before open(): a blocked upgrade is raised during the open, not after it.
+    // This is a waiting state — the other connection closing unblocks it and `open()` then
+    // resolves on its own — so it is surfaced rather than treated as a failure.
     db.on("blocked", () => {
-        console.error("Database blocked");
+        dbUpgradeBlocked.value = true;
     });
 
-    // Awaiting open() rather than the "ready" event means a rejected open is raised
-    // as a boot error instead of leaving this promise unsettled.
+    // Dexie's own `versionchange` default closes this connection so the other tab's upgrade
+    // can proceed, and it has to: holding on would block that tab for as long as this one
+    // lives. Subscribers run before the default, so this adds to it rather than replacing it.
+    //
+    // Closing is enough for a hidden tab, which reopens on next use. A visible one is running
+    // code built for the old schema, so it reloads onto the new version instead of carrying
+    // on against a database it can no longer use. Reloading only the visible tab keeps this
+    // to the page someone is actually looking at.
+    db.on("versionchange", () => {
+        if (typeof document === "undefined" || typeof window === "undefined") return;
+        if (document.visibilityState !== "visible") return;
+        window.location.reload();
+    });
+
+    // Awaiting open() rather than the "ready" event means a rejected open is raised as a
+    // boot error instead of leaving this promise unsettled. A blocked open is not rejected:
+    // it stays pending until the blocking connection closes, which is what we want.
     if (!db.isOpen()) {
-        await withDbTimeout(db.open(), "open the database");
+        await db.open();
     }
+    dbUpgradeBlocked.value = false;
 
     // Compute FTS corpus stats on startup.
     // Uses setTimeout(0) to avoid Dexie PSD zone deadlocks during initialization.
@@ -996,33 +995,29 @@ async function resetGroupSyncListForRecovery() {
 }
 
 /**
- * Get IndexDB version before DB class is initialized. Rejects rather than staying
- * unsettled when the open is blocked or fails, because this runs before the app is
- * mounted and an unsettled promise here strands the user on the boot screen.
+ * Get IndexDB version before DB class is initialized. Rejects on error rather than only
+ * logging, because this runs before the app is mounted and a promise that never settles
+ * here strands the user on the boot screen with nothing reported.
  * @returns IndexDB Version
  */
 export const getDbVersion = () =>
     new Promise<number>((resolve, reject) => {
         const request = indexedDB.open(dbName);
-        const timeout = setTimeout(
-            () => reject(new Error("Timed out reading the database version")),
-            DB_OPEN_TIMEOUT_MS,
-        );
 
         request.onsuccess = (event: any) => {
-            clearTimeout(timeout);
             const db = event.target.result;
             const version: number = (db && db.version) || 0;
             db.addEventListener("close", () => {});
             db.close();
+            dbUpgradeBlocked.value = false;
             resolve(version);
         };
+        // Not an error: another connection holds an older version open. The request stays
+        // pending and fires `onsuccess` once that connection closes.
         request.onblocked = () => {
-            clearTimeout(timeout);
-            reject(new Error("Database blocked while reading the database version"));
+            dbUpgradeBlocked.value = true;
         };
         request.onerror = () => {
-            clearTimeout(timeout);
             reject(new Error("Database error while reading the database version"));
         };
     });
diff --git a/shared/src/db/dbOpenFailure.spec.ts b/shared/src/db/dbOpenFailure.spec.ts
index c859f15727..f86dc92de1 100644
--- a/shared/src/db/dbOpenFailure.spec.ts
+++ b/shared/src/db/dbOpenFailure.spec.ts
@@ -1,36 +1,36 @@
 import "fake-indexeddb/auto";
-import { describe, it, expect, afterEach, vi } from "vitest";
+import { describe, it, expect, afterEach, beforeEach, vi } from "vitest";
 import Dexie from "dexie";
-import { getDbVersion, initDatabase } from "./database";
+import { db, dbUpgradeBlocked, getDbVersion, initDatabase } from "./database";
 import { initConfig } from "../config";
 
-// The boot-path database opens run before the app is mounted, so a promise that never
-// settles here strands the user on the boot splash with nothing reported.
+// The boot-path database opens run before the app is mounted, so a failure that is only
+// logged strands the user on the boot splash with nothing reported. A *blocked* open is
+// not a failure: it clears itself when the other connection closes.
 const originalIndexedDb = globalThis.indexedDB;
 
-function stubOpen(fire: "onsuccess" | "onblocked" | "onerror" | "never") {
+function stubOpen(fire: "onsuccess" | "onblocked" | "onerror") {
     const request: Record<string, ((event?: unknown) => void) | undefined> = {};
     (globalThis as any).indexedDB = {
         open: () => {
-            if (fire !== "never") {
-                setTimeout(() => {
-                    if (fire === "onsuccess") {
-                        request.onsuccess?.({
-                            target: { result: { version: 70, addEventListener() {}, close() {} } },
-                        });
-                    } else {
-                        request[fire]?.();
-                    }
-                }, 0);
-            }
+            setTimeout(() => {
+                if (fire === "onsuccess") {
+                    request.onsuccess?.({
+                        target: { result: { version: 70, addEventListener() {}, close() {} } },
+                    });
+                } else {
+                    request[fire]?.();
+                }
+            }, 0);
             return request;
         },
     };
+    return request;
 }
 
 describe("getDbVersion", () => {
     afterEach(() => {
-        vi.useRealTimers();
+        dbUpgradeBlocked.value = false;
         (globalThis as any).indexedDB = originalIndexedDb;
     });
 
@@ -39,23 +39,32 @@ describe("getDbVersion", () => {
         await expect(getDbVersion()).resolves.toBe(70);
     });
 
-    it("rejects when the open is blocked by another connection", async () => {
-        stubOpen("onblocked");
-        await expect(getDbVersion()).rejects.toThrow(/blocked/i);
-    });
-
     it("rejects when the open errors", async () => {
         stubOpen("onerror");
         await expect(getDbVersion()).rejects.toThrow(/error/i);
     });
 
-    it("rejects when the open never answers at all", async () => {
-        vi.useFakeTimers();
-        stubOpen("never");
+    it("treats a blocked open as a wait, not a failure", async () => {
+        const request = stubOpen("onblocked");
+        let settled = false;
+        const pending = getDbVersion().then((v) => {
+            settled = true;
+            return v;
+        });
+
+        await new Promise((r) => setTimeout(r, 5));
+
+        // Still waiting on the other connection, and saying so rather than throwing.
+        expect(settled).toBe(false);
+        expect(dbUpgradeBlocked.value).toBe(true);
+
+        // The other connection closes; the browser then completes the same request.
+        request.onsuccess?.({
+            target: { result: { version: 70, addEventListener() {}, close() {} } },
+        });
 
-        const assertion = expect(getDbVersion()).rejects.toThrow(/timed out/i);
-        await vi.advanceTimersByTimeAsync(10_000);
-        await assertion;
+        await expect(pending).resolves.toBe(70);
+        expect(dbUpgradeBlocked.value).toBe(false);
     });
 });
 
@@ -73,3 +82,56 @@ describe("initDatabase", () => {
         await expect(initDatabase()).rejects.toThrow("VersionError");
     });
 });
+
+// Dexie's own versionchange default closes the connection so the other tab can upgrade.
+// That is enough for a background tab; the one the user is looking at is running code built
+// for the old schema, so it reloads onto the new version.
+describe("versionchange", () => {
+    const originalLocation = window.location;
+    let reload: ReturnType<typeof vi.fn>;
+
+    const setVisibility = (value: "visible" | "hidden") =>
+        Object.defineProperty(document, "visibilityState", { value, configurable: true });
+
+    beforeEach(() => {
+        reload = vi.fn();
+        // jsdom's own location.reload throws "not implemented", and is not configurable.
+        Object.defineProperty(window, "location", { configurable: true, value: { reload } });
+    });
+
+    afterEach(() => {
+        Object.defineProperty(window, "location", {
+            configurable: true,
+            value: originalLocation,
+        });
+        setVisibility("visible");
+        vi.restoreAllMocks();
+    });
+
+    async function openDb() {
+        initConfig({ cms: false, docsIndex: "[type+postType]", apiUrl: "http://localhost:12345" });
+        await initDatabase();
+    }
+
+    it("closes without reloading a hidden tab", async () => {
+        await openDb();
+        const close = vi.spyOn(db, "close");
+        setVisibility("hidden");
+
+        db.on("versionchange").fire({ newVersion: 99 });
+
+        expect(close).toHaveBeenCalled();
+        expect(reload).not.toHaveBeenCalled();
+    });
+
+    it("reloads the visible tab onto the new version", async () => {
+        await openDb();
+        const close = vi.spyOn(db, "close");
+        setVisibility("visible");
+
+        db.on("versionchange").fire({ newVersion: 99 });
+
+        expect(close).toHaveBeenCalled();
+        expect(reload).toHaveBeenCalled();
+    });
+});