+ );
+}
+
+interface AppShellSkeletonProps {
+ surface: SkeletonSurface;
+ /** The page's own "Loading" string (common.loading). */
+ label?: string;
+ /** Rail item drawn as current. */
+ active?: RailApp;
+ /**
+ * Below which width the vertical rail gives way to the bottom bar: mail and
+ * settings switch at 64rem, calendar, contacts, files and plugin pages at 48rem.
+ */
+ railBelow: "md" | "lg";
+ labels?: RailLabels;
+ /** Whether the Mountain View top bar holds the search field (mail does). */
+ mvSearch?: boolean;
+ /** Extra classes for the row under the top bar (Mountain View card margins etc.). */
+ rowClassName?: string;
+ children: ReactNode;
+}
+
+/**
+ * Page root plus frame. `children` go in the row next to the rail: the page's
+ * own sidebar, list and panes.
+ *
+ * When nothing is stored that could sign the visitor back in, the boot script
+ * marks the page `data-boot-auth="out"` and the login card is drawn instead:
+ * that is where the app is about to send them.
+ */
+export function AppShellSkeleton({
+ surface,
+ label,
+ active,
+ railBelow,
+ labels,
+ mvSearch = false,
+ rowClassName,
+ children,
+}: AppShellSkeletonProps) {
+ return (
+ <>
+
+
+
+
+
+
+
+ {children}
+
+
+
+
+ );
+}
diff --git a/components/layout/navigation-rail.tsx b/components/layout/navigation-rail.tsx
index e6016a1d0..71653b1d8 100644
--- a/components/layout/navigation-rail.tsx
+++ b/components/layout/navigation-rail.tsx
@@ -34,6 +34,7 @@ import { toUnicodeEmail } from "@/lib/idn";
import { usePluginPages, pluginPageHref, isPluginPageActive } from "@/hooks/use-plugin-pages";
import { NotificationBell } from "@/components/notifications/notification-center";
import { useBottomControls } from "@/hooks/use-bottom-controls";
+import { writeRailHints, type RailHint } from "@/lib/boot-skeleton/hints";
interface NavItem {
id: string;
@@ -348,6 +349,22 @@ export function NavigationRail({
const visibleItems = navItems.filter((item) => !item.hidden);
+ // Leave the next page load's skeleton a note of what this rail shows
+ // (lib/boot-skeleton/hints.ts). Only once a session is up: before that the
+ // rail is still missing the apps the server offers.
+ const quotaShown = !!quota && quota.total > 0;
+ useEffect(() => {
+ if (!client) return;
+ const items: RailHint[] = [];
+ for (const item of navItems) if (item.id !== 'mail' && !item.hidden) items.push(item.id as RailHint);
+ if (isStalwartAdmin) items.push('admin');
+ if (showAccessibilityButton) items.push('a11y');
+ if (quotaShown) items.push('quota');
+ writeRailHints(items);
+ // navItems is rebuilt every render; its inputs are listed instead.
+ // eslint-disable-next-line react-hooks/exhaustive-deps
+ }, [client, supportsCalendar, calendarEnabled, supportsContacts, contactsEnabled, supportsFiles, filesEnabled, isStalwartAdmin, showAccessibilityButton, quotaShown]);
+
const getIsActive = (href: string, itemId: string) => {
if (activeAppId) return false;
if (onNavigate) {
diff --git a/components/providers/__tests__/intl-provider-lite.test.tsx b/components/providers/__tests__/intl-provider-lite.test.tsx
index 25b06cc7d..56a6efeb2 100644
--- a/components/providers/__tests__/intl-provider-lite.test.tsx
+++ b/components/providers/__tests__/intl-provider-lite.test.tsx
@@ -5,10 +5,16 @@ import { useTranslations } from 'next-intl';
import { IntlProvider } from '../intl-provider';
import { useLocaleStore } from '@/stores/locale-store';
+const nav = vi.hoisted(() => ({ pathname: null as string | null }));
+vi.mock('next/navigation', async (importOriginal) => ({
+ ...(await importOriginal()),
+ usePathname: () => nav.pathname,
+}));
+
// The Lite export leaves the catalog out of the [locale] layout, because the
// prop was baked into every exported page and pushed the Stalwart zip past its
// size limit. The provider then loads the catalog itself and must render
-// nothing until it has it: English text would flash on a German page, and the
+// no text until it has it (only the page's skeleton, which has none): English text would flash on a German page, and the
// prerendered HTML has to match the client's first render.
vi.unmock('next-intl');
@@ -20,12 +26,22 @@ function Cancel() {
describe('IntlProvider without server messages (Lite)', () => {
afterEach(() => {
useLocaleStore.setState({ locale: '' });
+ nav.pathname = null;
});
it('prerenders nothing for a non-English locale', () => {
expect(renderToString()).toBe('');
});
+ it('prerenders the page skeleton, without any text, while the catalog is missing', () => {
+ nav.pathname = '/de/calendar';
+ const html = renderToString();
+ expect(html).toContain('data-boot-skeleton="calendar"');
+ expect(html).toContain('aria-busy="true"');
+ expect(html).not.toContain('Cancel');
+ expect(html).not.toContain('role="status"');
+ });
+
it('prerenders English straight away from the bundled catalog', () => {
expect(renderToString()).toContain('Cancel');
});
diff --git a/components/providers/intl-provider.tsx b/components/providers/intl-provider.tsx
index 9b3b564fb..ace1f1018 100644
--- a/components/providers/intl-provider.tsx
+++ b/components/providers/intl-provider.tsx
@@ -2,6 +2,10 @@
import { useEffect, useMemo, useRef, useState } from 'react';
import { NextIntlClientProvider } from 'next-intl';
+import { usePathname } from 'next/navigation';
+import { RouteSkeleton } from '@/components/boot-skeleton/route-skeleton';
+import { surfaceFromPath } from '@/lib/boot-skeleton/surfaces';
+import { locales } from '@/i18n/routing';
import { useLocaleStore } from '@/stores/locale-store';
import { useSettingsStore } from '@/stores/settings-store';
import { getBrowserTimeZone, resolveTimeZone } from '@/lib/timezone';
@@ -67,6 +71,7 @@ export function IntlProvider({ locale: initialLocale, messages: initialMessages,
const timeZoneSetting = useSettingsStore((state) => state.timeZone);
const timeZone = resolveTimeZone(timeZoneSetting, browserTimeZone);
const plainLanguage = useSettingsStore((state) => state.plainLanguage);
+ const pathname = usePathname();
// The catalog currently in use. Seeded with the server-provided messages for
// the SSR-resolved locale, so the first render needs no async work and
@@ -159,7 +164,13 @@ export function IntlProvider({ locale: initialLocale, messages: initialMessages,
[baseMessages, plainMessages]
);
- if (!catalog) return null;
+ if (!catalog) {
+ // Lite without this locale's catalog yet: no text can be drawn, but the
+ // page's skeleton can (it takes no translations), so the prerendered HTML
+ // still shows the page's shape instead of a blank screen.
+ const surface = pathname ? surfaceFromPath(pathname, locales) : null;
+ return surface ? : null;
+ }
return (
{
+ it('every target the connector can resolve has a skeleton surface', () => {
+ for (const name of TARGET_NAMES) expect(CONNECTOR_SURFACES[name], name).toBeTruthy();
+ expect(Object.keys(CONNECTOR_SURFACES).sort()).toEqual([...TARGET_NAMES].sort());
+ });
+
+ it('the surface matches where the target resolves to', () => {
+ const firstSegment: Record = { '': 'mail' };
+ for (const name of TARGET_NAMES) {
+ const target = getTarget(name)!;
+ const params: Record = {};
+ for (const [key, spec] of Object.entries(target.params ?? {})) {
+ if (!spec.required) continue;
+ params[key] = spec.type === 'enum' ? spec.values![0] : 'x';
+ }
+ const { path } = target.resolve(params);
+ const seg = path.split('/').filter(Boolean)[0] ?? '';
+ expect(CONNECTOR_SURFACES[name], `${name} -> ${path}`).toBe(firstSegment[seg] ?? seg);
+ }
+ });
+});
+
+describe('surfaceFromPath', () => {
+ it.each([
+ ['/', 'mail'],
+ ['/en', 'mail'],
+ ['/de/mail/folder/inbox', 'mail'],
+ ['/en/calendar/week/2026-11-04', 'calendar'],
+ ['/ar/contacts/abc', 'contacts'],
+ ['/en/files/de', 'files'],
+ ['/en/apps/p/q', 'apps'],
+ ['/en/settings/filters', 'settings'],
+ ['/en/pro', 'pro'],
+ ['/en/login', 'login'],
+ ['/admin', 'admin'],
+ ['/admin/logs', 'admin'],
+ ['/admin/login', 'admin-login'],
+ ['/setup', 'setup'],
+ ['/connector/calendar', 'calendar'],
+ ['/connector/admin_auth', 'admin'],
+ ['/connector/nope', null],
+ ['/protocol/mailto', 'mail'],
+ ['/protocol/webcal', 'calendar'],
+ ['/webmail/de/calendar', 'calendar'],
+ ['/en/auth/callback', null],
+ ['/en/plugins/oauth/callback', null],
+ ])('%s -> %s', (path, surface) => {
+ expect(surfaceFromPath(path, locales)).toBe(surface);
+ });
+});
+
+describe('rail hints', () => {
+ beforeEach(() => {
+ localStorage.clear();
+ resetRailHintsMemo();
+ });
+
+ it('stores the rail items with mail first', () => {
+ writeRailHints(['calendar', 'quota']);
+ expect(JSON.parse(localStorage.getItem(BOOT_HINTS_KEY)!)).toEqual({ v: 1, rail: ['mail', 'calendar', 'quota'] });
+ });
+
+ it('skips writing the same value twice', () => {
+ writeRailHints(['files']);
+ localStorage.removeItem(BOOT_HINTS_KEY);
+ writeRailHints(['files']);
+ expect(localStorage.getItem(BOOT_HINTS_KEY)).toBeNull();
+ writeRailHints(['files', 'admin']);
+ expect(JSON.parse(localStorage.getItem(BOOT_HINTS_KEY)!).rail).toEqual(['mail', 'files', 'admin']);
+ });
+});
diff --git a/lib/boot-skeleton/hints.ts b/lib/boot-skeleton/hints.ts
new file mode 100644
index 000000000..cc93fdac9
--- /dev/null
+++ b/lib/boot-skeleton/hints.ts
@@ -0,0 +1,28 @@
+import { BOOT_HINTS_KEY } from './keys';
+
+/**
+ * What the rail showed, for the next page load's skeleton: the apps and the
+ * optional footer items whose presence depends on the server (capabilities,
+ * admin rights, quota), which nothing else keeps across a reload. The boot
+ * script turns it into `data-boot-rail` (lib/boot-skeleton/boot-script.ts).
+ */
+export type RailHint = 'calendar' | 'contacts' | 'files' | 'admin' | 'a11y' | 'quota';
+
+let lastWritten: string | null = null;
+
+export function writeRailHints(items: RailHint[]): void {
+ const rail = ['mail', ...items];
+ const value = JSON.stringify({ v: 1, rail });
+ if (value === lastWritten) return;
+ lastWritten = value;
+ try {
+ localStorage.setItem(BOOT_HINTS_KEY, value);
+ } catch {
+ /* storage full or blocked: the next skeleton draws every app */
+ }
+}
+
+/** For tests. */
+export function resetRailHintsMemo(): void {
+ lastWritten = null;
+}