@k2b/cloud 0.32.0 → 0.34.0

package/src/ssr/WorkspaceNavigationProvider.tsx

@@ -5,12 +5,31 @@ import { provideWorkspaceNavigation } from "./workspace-navigation";
 export default function WorkspaceNavigationProvider(props: { navigation: NavigationController; label: string }) {
   let owner!: HTMLScriptElement;
   provideWorkspaceNavigation(props.navigation, { label: () => props.label, owner: () => owner });
+  const snapshot = () => {
+    const switcher = props.navigation.switcher?.();
+    return {
+      label: props.label,
+      items: props.navigation.items(),
+      ...(switcher
+        ? {
+            switcher: {
+              currentId: switcher.currentId,
+              label: switcher.label,
+              description: switcher.description,
+              icon: switcher.icon,
+              color: switcher.color,
+              switchLabel: switcher.switchLabel,
+            },
+          }
+        : {}),
+    };
+  };
   return (
     <script
       ref={owner}
       type="application/json"
       data-cloud-workspace-navigation
-      innerHTML={JSON.stringify({ label: props.label, items: props.navigation.items() }).replace(/</g, "\\u003c")}
+      innerHTML={JSON.stringify(snapshot()).replace(/</g, "\\u003c")}
     />
   );
 }

package/src/ssr/announcements-dialog.tsx

@@ -0,0 +1,66 @@
+import { Button, dialogCore, MarkdownView, PanelDialog, panelDialogOptions, useLocale } from "@k2b/ui";
+import { For } from "solid-js";
+import {
+  ANNOUNCEMENTS_COOKIE,
+  ANNOUNCEMENTS_COOKIE_MAX_AGE_SECONDS,
+  mergeAnnouncementCookieState,
+  parseAnnouncementCookieHeader,
+  serializeAnnouncementCookieState,
+} from "../contracts/announcement-cookie";
+import type { AnnouncementDisplayEntry } from "../contracts/announcements";
+import { platformMessages } from "./platform-messages";
+
+function AnnouncementsPanel(props: { entries: AnnouncementDisplayEntry[]; close: () => void }) {
+  const locale = useLocale();
+  const t = () => platformMessages.resolve([locale()]).t;
+  return (
+    <PanelDialog>
+      <PanelDialog.Header
+        title={t().announcements}
+        subtitle={t().latestPlatformUpdates}
+        icon="ti ti-speakerphone text-blue-500"
+        close={props.close}
+      />
+      <PanelDialog.Body>
+        <For each={props.entries}>
+          {(entry) => (
+            <article class="panel-dialog-section rounded-[var(--ui-radius-surface)] p-4">
+              <div class="mb-3 flex items-start justify-between gap-3">
+                <div class="min-w-0">
+                  <h2 class="text-base font-semibold text-primary">{entry.title}</h2>
+                  <p class="mt-0.5 text-xs text-dimmed">
+                    {new Date(entry.publishedAt).toLocaleDateString(locale(), {
+                      year: "numeric",
+                      month: "short",
+                      day: "numeric",
+                    })}
+                  </p>
+                </div>
+                <span class="rounded bg-zinc-100 px-1.5 py-0.5 text-[10px] font-medium text-dimmed dark:bg-zinc-800">v{entry.version}</span>
+              </div>
+              <MarkdownView trustedHtml={entry.bodyHtml} />
+            </article>
+          )}
+        </For>
+      </PanelDialog.Body>
+      <PanelDialog.Footer>
+        <span />
+        <Button size="sm" onClick={props.close}>
+          {t().gotIt}
+        </Button>
+      </PanelDialog.Footer>
+    </PanelDialog>
+  );
+}
+
+/** Shows the announcements the person has not seen yet, and records them as seen once the dialog closes. */
+export function openAnnouncementsDialog(props: { entries: AnnouncementDisplayEntry[]; latestVersion: number }) {
+  void dialogCore
+    .open<void>((close) => <AnnouncementsPanel entries={props.entries} close={() => close()} />, panelDialogOptions)
+    .then(() => {
+      const next = mergeAnnouncementCookieState(parseAnnouncementCookieHeader(document.cookie), {
+        seenAnnouncementVersion: props.latestVersion,
+      });
+      document.cookie = `${ANNOUNCEMENTS_COOKIE}=${serializeAnnouncementCookieState(next)}; Path=/; Max-Age=${ANNOUNCEMENTS_COOKIE_MAX_AGE_SECONDS}; SameSite=Lax`;
+    });
+}

package/src/ssr/app-appearance.ts

@@ -1,5 +1,6 @@
 import type { AppAppearance } from "../contracts/app";
 import { resolveRuntimeRoute } from "./app-navigation";
+import { helpPageAppId } from "./layout-help-url";
 import type { RuntimeContext } from "./runtime";
 
 const isHexColor = (value: string | undefined): value is `#${string}` => /^#[0-9a-f]{6}$/i.test(value ?? "");
@@ -20,4 +21,8 @@ export const appAppearanceStyle = (appearance: AppAppearance | undefined): strin
 export const appAccentStyle = (accent: string | undefined): string | undefined =>
   isHexColor(accent) ? `--app-accent:${accent}` : undefined;
 
-export const resolveCurrentApp = (apps: RuntimeContext["apps"], pathname: string) => resolveRuntimeRoute(apps, pathname)?.app;
+/** Core's full-page Help of an app belongs to that app. */
+export const resolveCurrentApp = (apps: RuntimeContext["apps"], pathname: string) => {
+  const helpAppId = helpPageAppId(pathname);
+  return apps.find((app) => app.id === helpAppId) ?? resolveRuntimeRoute(apps, pathname)?.app;
+};

package/src/ssr/{AppLaunchpad.island.tsx → app-launchpad.tsx}

@@ -1,11 +1,12 @@
-import { type AppLaunchpadApp, type AppLaunchpadContext, type AppLaunchpadLegalLink, AppLaunchpadPanel } from "./AppLaunchpadPanel";
-import { openCloudMobileMenu } from "./MobileNavigation";
-
-export type { AppLaunchpadApp, AppLaunchpadLegalLink } from "./AppLaunchpadPanel";
-
-import { dialogCore, IconButton, Tooltip, useLocale } from "@k2b/ui";
+import { IconButton, Tooltip, useLocale } from "@k2b/ui";
 import { createEffect } from "solid-js";
+import { importOnDemand } from "../browser/reload";
+import type { AppLaunchpadApp, AppLaunchpadContext, AppLaunchpadLegalLink } from "./AppLaunchpadPanel";
+import { createBusyAction } from "./busy-action";
 import { platformMessages } from "./platform-messages";
+import { readShellData } from "./shell-data";
+
+export type { AppLaunchpadApp, AppLaunchpadLegalLink } from "./AppLaunchpadPanel";
 
 declare global {
   interface Window {
@@ -17,29 +18,15 @@ declare global {
 }
 
 const readEmbeddedContext = (): AppLaunchpadContext | undefined => {
-  if (typeof document === "undefined") return undefined;
-  const element = document.getElementById("cloud-app-launchpad-data");
-  const text = element?.textContent;
-  if (!text) return undefined;
-
-  try {
-    const parsed = JSON.parse(text) as Partial<AppLaunchpadContext>;
-    if (!Array.isArray(parsed.apps)) return undefined;
-    return {
-      apps: parsed.apps,
-      profile:
-        parsed.profile?.name && (parsed.profile.theme === "dark" || parsed.profile.theme === "light")
-          ? {
-              name: parsed.profile.name,
-              theme: parsed.profile.theme,
-              ...(parsed.profile.appHref === "/me/app" ? { appHref: parsed.profile.appHref } : {}),
-            }
-          : undefined,
-      legalLinks: Array.isArray(parsed.legalLinks) ? parsed.legalLinks : [],
-    };
-  } catch {
-    return undefined;
-  }
+  const data = readShellData();
+  if (!data) return undefined;
+  return {
+    apps: data.apps,
+    profile: data.profile
+      ? { name: data.profile.name, theme: data.theme, ...(data.profile.appHref === "/me/app" ? { appHref: data.profile.appHref } : {}) }
+      : undefined,
+    legalLinks: data.legalLinks,
+  };
 };
 
 export function setAppLaunchpadContext(
@@ -55,20 +42,20 @@ export function setAppLaunchpadContext(
   };
 }
 
+/** Every caller of the public opener shares one load, so a double click opens one dialog. */
+let launchpadPending: Promise<void> | undefined;
+
 export function openAppLaunchpad(apps?: AppLaunchpadApp[], legalLinks?: AppLaunchpadLegalLink[], profile?: AppLaunchpadContext["profile"]) {
-  if (typeof window === "undefined") return;
+  if (typeof window === "undefined" || launchpadPending) return;
   const context = apps ? { apps, legalLinks: legalLinks ?? [], profile } : (window.__cloudAppLaunchpad ?? readEmbeddedContext());
   if (!context) return;
   window.__cloudAppLaunchpad = context;
-  if (window.matchMedia("(max-width: 767px)").matches) {
-    void openCloudMobileMenu(context);
-    return;
-  }
-  void dialogCore.open<void>((close) => <AppLaunchpadPanel apps={context.apps} legalLinks={context.legalLinks} close={close} />, {
-    panelClassName: "k2b-dialog k2b-dialog--large is-bare",
-    contentClassName: "k2b-dialog__viewport is-bare",
-    initialFocus: (dialog) => dialog.querySelector<HTMLAnchorElement>("a[href]"),
-  });
+  launchpadPending = importOnDemand(() => import("./launchpad-surface"))
+    .then((loaded) => loaded?.openLaunchpadSurface(context))
+    .finally(() => {
+      launchpadPending = undefined;
+    });
+  return launchpadPending;
 }
 
 export function AppLaunchpadProvider(props: AppLaunchpadContext) {
@@ -82,7 +69,16 @@ export function AppLaunchpadProvider(props: AppLaunchpadContext) {
 export function AppLaunchpadButton(props: AppLaunchpadContext & { variant: "rail" | "header" | "menu"; label?: string }) {
   const locale = useLocale();
   const t = () => platformMessages.resolve([locale()]).t;
-  const open = () => openAppLaunchpad(props.apps, props.legalLinks, props.profile);
+  const action = createBusyAction();
+  const open = () =>
+    action.run(
+      () => importOnDemand(() => import("./launchpad-surface")),
+      (loaded) => {
+        const context = { apps: props.apps, legalLinks: props.legalLinks, profile: props.profile };
+        window.__cloudAppLaunchpad = context;
+        loaded.openLaunchpadSurface(context);
+      },
+    );
 
   if (props.variant === "rail") {
     return (
@@ -95,16 +91,17 @@ export function AppLaunchpadButton(props: AppLaunchpadContext & { variant: "rail
         delay={0}
         aria-label={props.label ?? t().openApps}
         onClick={open}
+        aria-busy={action.busy() ? "true" : undefined}
       >
-        <i class="ti ti-grid-dots text-base" aria-hidden="true" />
+        <i class={`${action.busy() ? "ti ti-loader-2 animate-spin" : "ti ti-grid-dots"} text-base`} aria-hidden="true" />
       </Tooltip.Trigger>
     );
   }
 
   if (props.variant === "header") {
     return (
-      <IconButton label={props.label ?? t().openApps} onClick={open}>
-        <i class="ti ti-grid-dots text-lg" />
+      <IconButton label={props.label ?? t().openApps} onClick={open} aria-busy={action.busy() ? "true" : undefined}>
+        <i class={`${action.busy() ? "ti ti-loader-2 animate-spin" : "ti ti-grid-dots"} text-lg`} />
       </IconButton>
     );
   }
@@ -114,27 +111,10 @@ export function AppLaunchpadButton(props: AppLaunchpadContext & { variant: "rail
       type="button"
       class="flex w-full items-center gap-3 px-4 py-2 text-sm transition-colors hover:bg-white/30 dark:hover:bg-white/10 text-zinc-700 dark:text-zinc-300"
       onClick={open}
+      aria-busy={action.busy() ? "true" : undefined}
     >
-      <i class="ti ti-grid-dots" />
+      <i class={action.busy() ? "ti ti-loader-2 animate-spin" : "ti ti-grid-dots"} />
       <span>{props.label ?? t().apps}</span>
     </button>
   );
 }
-
-export function AppLaunchpad(props: AppLaunchpadContext & { variant?: "provider" | "rail" | "header" | "menu"; label?: string }) {
-  if (!props.variant || props.variant === "provider") {
-    return <AppLaunchpadProvider apps={props.apps} legalLinks={props.legalLinks} profile={props.profile} />;
-  }
-
-  return (
-    <AppLaunchpadButton
-      apps={props.apps}
-      legalLinks={props.legalLinks}
-      profile={props.profile}
-      variant={props.variant}
-      label={props.label}
-    />
-  );
-}
-
-export default AppLaunchpad;

package/src/ssr/busy-action.ts

@@ -0,0 +1,19 @@
+import { createSignal } from "solid-js";
+
+/** Keep the trigger focused and ignore repeated clicks while its code loads. */
+export function createBusyAction() {
+  const [busy, setBusy] = createSignal(false);
+  return {
+    busy,
+    async run<T>(load: () => Promise<T | undefined>, open: (loaded: T) => void) {
+      if (busy()) return;
+      setBusy(true);
+      try {
+        const loaded = await load();
+        if (loaded !== undefined) open(loaded);
+      } finally {
+        setBusy(false);
+      }
+    },
+  };
+}

package/src/ssr/islands/index.ts

@@ -3,13 +3,16 @@ export { default as WorkspaceNavigationProvider } from "../WorkspaceNavigationPr
 export { provideWorkspaceNavigation } from "../workspace-navigation";
 export { default as SearchBar } from "./SearchBar";
 
-import { AppLaunchpadButton, AppLaunchpadProvider } from "../AppLaunchpad.island";
-import { LayoutHelpDocuments, LayoutHelpPage } from "../LayoutHelp";
+import { AppLaunchpadButton, AppLaunchpadProvider } from "../app-launchpad";
+import { LayoutHelpPage } from "../LayoutHelp";
+import { LayoutHelpDocuments } from "../layout-help-registry";
 
-export type { AppLaunchpadApp, AppLaunchpadLegalLink } from "../AppLaunchpad.island";
-export { AppLaunchpadButton, AppLaunchpadProvider, openAppLaunchpad, setAppLaunchpadContext } from "../AppLaunchpad.island";
-export type { LayoutHelpDocumentsProps, LayoutHelpPageProps } from "../LayoutHelp";
-export { LayoutHelpDocuments, LayoutHelpPage, openLayoutHelpDialog } from "../LayoutHelp";
+export type { AppLaunchpadApp, AppLaunchpadLegalLink } from "../app-launchpad";
+export { AppLaunchpadButton, AppLaunchpadProvider, openAppLaunchpad, setAppLaunchpadContext } from "../app-launchpad";
+export type { LayoutHelpPageProps } from "../LayoutHelp";
+export { LayoutHelpPage, openLayoutHelpDialog } from "../LayoutHelp";
+export type { LayoutHelpDocumentsProps } from "../layout-help-registry";
+export { LayoutHelpDocuments } from "../layout-help-registry";
 
 export const Layout = {
   HelpDocuments: LayoutHelpDocuments,

package/src/ssr/launchpad-surface.tsx

@@ -0,0 +1,15 @@
+import { dialogCore } from "@k2b/ui";
+import { type AppLaunchpadContext, AppLaunchpadPanel } from "./AppLaunchpadPanel";
+import { openCloudMobileMenu } from "./MobileNavigation";
+
+export function openLaunchpadSurface(context: AppLaunchpadContext) {
+  if (window.matchMedia("(max-width: 767px)").matches) {
+    void openCloudMobileMenu(context);
+    return;
+  }
+  void dialogCore.open<void>((close) => <AppLaunchpadPanel apps={context.apps} legalLinks={context.legalLinks} close={close} />, {
+    panelClassName: "k2b-dialog k2b-dialog--large is-bare",
+    contentClassName: "k2b-dialog__viewport is-bare",
+    initialFocus: (dialog) => dialog.querySelector<HTMLAnchorElement>("a[href]"),
+  });
+}

package/src/ssr/layout-help-registry.tsx

@@ -0,0 +1,60 @@
+import type { HelpDocumentManifest } from "@k2b/cloud/shared";
+import { type JSX, onCleanup, onMount } from "solid-js";
+
+type HelpTopicBase = {
+  id: string;
+  title: string;
+  icon?: string;
+  description?: string;
+  order?: number;
+};
+
+export type LayoutHelpDocumentsProps = {
+  documents: readonly HelpDocumentManifest[];
+  /** Canonical standalone Help route owned by the current app. */
+  pageBase: string;
+};
+export type HelpTopic = (HelpTopicBase & { kind: "content"; children: JSX.Element }) | (HelpDocumentManifest & { kind: "document" });
+
+export const HELP_TOPICS_EVENT = "cloud:layout-help-topics";
+
+declare global {
+  interface Window {
+    __cloudLayoutHelpTopics?: Map<string, HelpTopic>;
+    __cloudLayoutHelpPageBase?: string;
+  }
+}
+
+export const registry = () => {
+  if (typeof window === "undefined") return null;
+  window.__cloudLayoutHelpTopics ??= new Map<string, HelpTopic>();
+  return window.__cloudLayoutHelpTopics;
+};
+
+const emitTopicsChanged = () => window.dispatchEvent(new Event(HELP_TOPICS_EVENT));
+const registerTopic = (topic: HelpTopic) => {
+  const topics = registry();
+  if (!topics) return () => {};
+  topics.set(topic.id, topic);
+  emitTopicsChanged();
+  return () => {
+    if (topics.get(topic.id) !== topic) return;
+    topics.delete(topic.id);
+    emitTopicsChanged();
+  };
+};
+
+/** Register an app's server-prepared Markdown manifest with the shared help UI. */
+export function LayoutHelpDocuments(props: LayoutHelpDocumentsProps) {
+  onMount(() => {
+    // Cleanup runs while this unmounts, when a parent `<Show>` may already have dropped the props' source.
+    const pageBase = props.pageBase;
+    window.__cloudLayoutHelpPageBase = pageBase;
+    const disposers = props.documents.map((document) => registerTopic({ ...document, kind: "document" }));
+    onCleanup(() => {
+      disposers.forEach((dispose) => dispose());
+      if (window.__cloudLayoutHelpPageBase === pageBase) delete window.__cloudLayoutHelpPageBase;
+    });
+  });
+  return null;
+}

package/src/ssr/layout-help-url.ts

@@ -3,3 +3,42 @@ export const layoutHelpTopicHref = (pageBase: string, topicId: string | null) =>
   const base = pageBase.endsWith("/") ? pageBase.slice(0, -1) : pageBase;
   return topicId ? `${base}/${encodeURIComponent(topicId)}` : base;
 };
+
+/** The app named by Core's exact full-page Help route. */
+export const helpPageAppId = (pathname: string): string | null => {
+  const match = /^\/help\/apps\/([^/]+)(?:\/[^/]+)?\/?$/.exec(pathname);
+  if (!match?.[1]) return null;
+  try {
+    return decodeURIComponent(match[1]);
+  } catch {
+    return null;
+  }
+};
+
+type HelpLinkTarget = { kind: "section"; hash: string } | { kind: "topic"; topicId: string | null; hash: string };
+
+/** Same-app Help links that the reader can open in place. */
+export const helpLinkTarget = (href: string, current: string, help: { appId?: string; pageBase?: string }): HelpLinkTarget | null => {
+  try {
+    if (href.startsWith("#")) {
+      const hash = decodeURIComponent(href.slice(1));
+      return hash ? { kind: "section", hash } : null;
+    }
+    const source = new URL(current);
+    const target = new URL(href, source);
+    if (target.origin !== source.origin || target.search) return null;
+    const bases = [help.pageBase?.replace(/\/$/, ""), help.appId ? `/help/apps/${encodeURIComponent(help.appId)}` : undefined];
+    const hash = decodeURIComponent(target.hash.slice(1));
+    for (const base of bases) {
+      if (!base) continue;
+      const path = target.pathname.replace(/\/$/, "");
+      if (path === base) return { kind: "topic", topicId: null, hash };
+      if (!path.startsWith(`${base}/`)) continue;
+      const segment = path.slice(base.length + 1);
+      if (segment && !segment.includes("/")) return { kind: "topic", topicId: decodeURIComponent(segment), hash };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+};

package/src/ssr/mobile-navigation.browser-harness.tsx

@@ -0,0 +1,20 @@
+import { createNavigation } from "@k2b/ui";
+import { render } from "solid-js/web";
+import { openCloudMobileMenu } from "./MobileNavigation";
+import { provideWorkspaceNavigation } from "./workspace-navigation";
+
+const owner = document.getElementById("workspace")!;
+render(() => {
+  const navigation = createNavigation({
+    items: () => [{ id: "notes", label: "Notes", href: "#notes", active: true }],
+    switcher: () => ({
+      currentId: "work",
+      label: "Work",
+      icon: "ti-notebook",
+      switchLabel: "Switch notebook",
+      options: [{ id: "work", label: "Work", href: "#work" }],
+    }),
+  });
+  provideWorkspaceNavigation(navigation, { label: () => "Workspace", owner: () => owner });
+  return <button onClick={() => void openCloudMobileMenu({ apps: [], legalLinks: [] })}>Open menu</button>;
+}, owner);

package/src/ssr/platform-messages.ts

@@ -56,10 +56,6 @@ export const platformMessages = i18n.define({
       latestPlatformUpdates: "Latest platform updates",
       gotIt: "Got it",
       dismissBanner: "Dismiss banner",
-      searchTags: "Search tags",
-      searchTagsDescription: ({ tag }: { tag: string }) => `Use ${tag} to narrow your search. You can combine text and multiple tags.`,
-      tags: "Tags",
-      noAppSearchTags: "No app-specific search tags are available.",
       openGlobalSearch: "Open global search",
       globalSearchDescription: "Search across apps, pages, files, and items.",
       searchShortcut: "Search (⌘/Ctrl+K)",
@@ -127,10 +123,6 @@ export const platformMessages = i18n.define({
       latestPlatformUpdates: "Neuigkeiten zur Plattform",
       gotIt: "Verstanden",
       dismissBanner: "Banner ausblenden",
-      searchTags: "Such-Tags",
-      searchTagsDescription: ({ tag }) => `Verwende ${tag} für eine gezieltere Suche. Text und mehrere Tags lassen sich kombinieren.`,
-      tags: "Tags",
-      noAppSearchTags: "Keine app-spezifischen Such-Tags verfügbar.",
       openGlobalSearch: "Globale Suche öffnen",
       globalSearchDescription: "Apps, Seiten, Dateien und weitere Inhalte durchsuchen.",
       searchShortcut: "Suchen (⌘/Strg+K)",

package/src/ssr/preference-controller.ts

@@ -1,44 +1,87 @@
-import type { DropdownItem } from "@k2b/ui";
+import type { DropdownAction, DropdownItem } from "@k2b/ui";
 import { createMemo, createSignal, onCleanup, onMount } from "solid-js";
 import { profilePreferenceLocale, setLocalePreference } from "../shared/locale-preference";
-import { type CloudTheme, getCurrentThemePreference, setThemePreference } from "../shared/theme";
+import { type CloudThemePreference, getCurrentThemePreference, setThemePreference } from "../shared/theme";
 import { profilePreferencesMessages } from "./profile-preferences-messages";
 
 const THEME_PREFERENCE_EVENT = "cloud:theme-preference";
+export const THEME_CYCLE = ["system", "light", "dark"] as const satisfies readonly CloudThemePreference[];
+const THEME_ICONS: Record<CloudThemePreference, string> = { light: "ti ti-sun-high", dark: "ti ti-moon", system: "ti ti-device-laptop" };
 
-export const createPreferenceController = (initialTheme: CloudTheme, locale: () => string) => {
-  const [theme, setTheme] = createSignal(initialTheme);
+export const nextThemePreference = (current: CloudThemePreference): CloudThemePreference =>
+  THEME_CYCLE[(THEME_CYCLE.indexOf(current) + 1) % THEME_CYCLE.length]!;
+
+export const createPreferenceController = (initialTheme: CloudThemePreference, locale: () => string) => {
+  const [theme, updateTheme] = createSignal(initialTheme);
+  const [announcedTheme, setAnnouncedTheme] = createSignal<CloudThemePreference>();
   const messages = () => profilePreferencesMessages.resolve([locale()]).t;
   const language = () => profilePreferenceLocale(locale());
   const nextLanguage = () => (language() === "de" ? "en" : "de");
-  const themeLabel = () => (theme() === "light" ? messages().switchToDark : messages().switchToLight);
   const languageLabel = () => (nextLanguage() === "de" ? messages().switchToGerman : messages().switchToEnglish);
 
-  const toggleTheme = () => {
-    setTheme(setThemePreference(theme() === "dark" ? "light" : "dark"));
+  const setTheme = (mode: CloudThemePreference) => {
+    updateTheme(setThemePreference(mode));
     window.dispatchEvent(new Event(THEME_PREFERENCE_EVENT));
   };
   const toggleLanguage = () => setLocalePreference(nextLanguage());
 
   onMount(() => {
-    const syncTheme = () => setTheme(getCurrentThemePreference());
+    const syncTheme = () => {
+      const syncedTheme = updateTheme(getCurrentThemePreference());
+      if (syncedTheme !== announcedTheme()) setAnnouncedTheme(undefined);
+    };
     syncTheme();
     window.addEventListener(THEME_PREFERENCE_EVENT, syncTheme);
     onCleanup(() => window.removeEventListener(THEME_PREFERENCE_EVENT, syncTheme));
   });
 
-  const items = createMemo<DropdownItem[]>(() => [
-    {
-      action: toggleTheme,
-      icon: theme() === "light" ? "ti ti-moon" : "ti ti-sun-high",
-      label: themeLabel(),
+  const themeOption = (value: CloudThemePreference) => ({
+    value,
+    icon: THEME_ICONS[value],
+    label: { light: messages().themeLight, dark: messages().themeDark, system: messages().themeSystem }[value],
+  });
+  const cycleTheme = () => {
+    const next = nextThemePreference(theme());
+    setTheme(next);
+    setAnnouncedTheme(next);
+  };
+  const themeCycleLabel = () =>
+    messages().themeCycle({
+      current: themeOption(theme()).label,
+      next: themeOption(nextThemePreference(theme())).label,
+    });
+  const themeAnnouncement = () => {
+    const current = announcedTheme();
+    return current === undefined ? "" : messages().themeChanged({ current: themeOption(current).label });
+  };
+  const appearanceItem: DropdownAction = {
+    get icon() {
+      return themeOption(theme()).icon;
     },
-    {
-      action: toggleLanguage,
-      icon: "ti ti-language",
-      label: languageLabel(),
+    get label() {
+      return themeOption(theme()).label;
     },
-  ]);
+    get ariaLabel() {
+      return themeCycleLabel();
+    },
+    closeOnSelect: false,
+    action: cycleTheme,
+  };
+  const languageItem = (): DropdownAction => ({ action: toggleLanguage, icon: "ti ti-language", label: languageLabel() });
+  const items = createMemo<DropdownItem[]>(() => [appearanceItem, languageItem()]);
 
-  return { items, language, languageLabel, messages, theme, themeLabel, toggleLanguage, toggleTheme };
+  return {
+    items,
+    appearanceItem,
+    languageItem,
+    themeOption,
+    language,
+    languageLabel,
+    messages,
+    theme,
+    cycleTheme,
+    themeCycleLabel,
+    themeAnnouncement,
+    toggleLanguage,
+  };
 };

package/src/ssr/profile-actions.ts

@@ -1,18 +1,24 @@
 import { type DropdownItem, toast, useLocale } from "@k2b/ui";
 import { createMemo, createSignal } from "solid-js";
-import { browserNotificationClient } from "../browser/notifications";
-import { apiClient } from "../clients/core";
-import type { CloudTheme } from "../shared/theme";
+import { importOnDemand } from "../browser/reload";
+import type { CloudThemePreference } from "../shared/theme";
 import { createPreferenceController } from "./preference-controller";
 
 /** `appHref` is set while the installation offers the mobile app; the item then leads to `/me/app`. */
-export function createProfileActions(initialTheme: CloudTheme, appHref?: string) {
+export function createProfileActions(initialTheme: CloudThemePreference, appHref?: string) {
   const locale = useLocale();
   const preferences = createPreferenceController(initialTheme, locale);
   const [signingOut, setSigningOut] = createSignal(false);
   const signOut = async () => {
     if (signingOut()) return;
     setSigningOut(true);
+    // The API client and the push client load with the first sign-out, not with every page.
+    const loaded = await importOnDemand(() => Promise.all([import("../browser/notifications"), import("../clients/core")]));
+    if (!loaded) {
+      setSigningOut(false);
+      return;
+    }
+    const [{ browserNotificationClient }, { apiClient }] = loaded;
     try {
       await browserNotificationClient.disable().catch(() => undefined);
       const response = await apiClient.auth.logout.$post();
@@ -25,7 +31,8 @@ export function createProfileActions(initialTheme: CloudTheme, appHref?: string)
   };
 
   const items = createMemo<DropdownItem[]>(() => [
-    ...preferences.items(),
+    preferences.appearanceItem,
+    preferences.languageItem(),
     {
       href: "/me",
       icon: "ti ti-user-circle",

package/src/ssr/profile-preferences-messages.ts

@@ -12,8 +12,11 @@ export const profilePreferencesMessages = i18n.define({
       app: "App",
       signOut: "Sign out",
       signOutFailed: "Sign out failed. Please try again.",
-      switchToDark: "Dark mode",
-      switchToLight: "Light mode",
+      themeLight: "Light",
+      themeDark: "Dark",
+      themeSystem: "Automatic",
+      themeCycle: ({ current, next }: { current: string; next: string }) => `Appearance: ${current}. Switches to ${next}.`,
+      themeChanged: ({ current }: { current: string }) => `Appearance: ${current}`,
       switchToGerman: "Deutsch",
       switchToEnglish: "English",
     },
@@ -26,8 +29,11 @@ export const profilePreferencesMessages = i18n.define({
       app: "App",
       signOut: "Abmelden",
       signOutFailed: "Abmelden fehlgeschlagen. Bitte versuche es erneut.",
-      switchToDark: "Dunkler Modus",
-      switchToLight: "Heller Modus",
+      themeLight: "Hell",
+      themeDark: "Dunkel",
+      themeSystem: "Automatisch",
+      themeCycle: ({ current, next }) => `Darstellung: ${current}. Wechselt zu ${next}.`,
+      themeChanged: ({ current }) => `Darstellung: ${current}`,
       switchToGerman: "Deutsch",
       switchToEnglish: "English",
     },