@k2b/cloud 0.32.0 → 0.33.0

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/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/preference-controller.ts

@@ -1,44 +1,53 @@
-import type { DropdownItem } from "@k2b/ui";
+import type { DropdownAction, DropdownItem, DropdownSection } 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";
+const THEME_PREFERENCES = ["light", "dark", "system"] as const satisfies readonly CloudThemePreference[];
+const THEME_ICONS: Record<CloudThemePreference, string> = { light: "ti ti-sun-high", dark: "ti ti-moon", system: "ti ti-sun-moon" };
 
-export const createPreferenceController = (initialTheme: CloudTheme, locale: () => string) => {
-  const [theme, setTheme] = createSignal(initialTheme);
+export const createPreferenceController = (initialTheme: CloudThemePreference, locale: () => string) => {
+  const [theme, updateTheme] = createSignal(initialTheme);
   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 = () => updateTheme(getCurrentThemePreference());
     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(),
-    },
-    {
-      action: toggleLanguage,
-      icon: "ti ti-language",
-      label: languageLabel(),
-    },
-  ]);
+  const themeOption = (value: CloudThemePreference) => ({
+    value,
+    icon: THEME_ICONS[value],
+    label: { light: messages().themeLight, dark: messages().themeDark, system: messages().themeSystem }[value],
+  });
+  const themeOptions = () => THEME_PREFERENCES.map(themeOption);
+  const appearance = (): DropdownSection => ({
+    sectionLabel: messages().appearance,
+    layout: "row",
+    items: themeOptions().map(({ value, label, icon }) => ({
+      label,
+      icon,
+      choice: "radio",
+      checked: () => theme() === value,
+      closeOnSelect: false,
+      action: () => setTheme(value),
+    })),
+  });
+  const languageItem = (): DropdownAction => ({ action: toggleLanguage, icon: "ti ti-language", label: languageLabel() });
+  const items = createMemo<DropdownItem[]>(() => [appearance(), { items: [languageItem()] }]);
 
-  return { items, language, languageLabel, messages, theme, themeLabel, toggleLanguage, toggleTheme };
+  return { items, appearance, languageItem, themeOption, themeOptions, language, languageLabel, messages, theme, setTheme, 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,18 +31,23 @@ export function createProfileActions(initialTheme: CloudTheme, appHref?: string)
   };
 
   const items = createMemo<DropdownItem[]>(() => [
-    ...preferences.items(),
-    {
-      href: "/me",
-      icon: "ti ti-user-circle",
-      label: preferences.messages().profileSettings,
-    },
-    ...(appHref ? [{ href: appHref, icon: "ti ti-device-mobile", label: preferences.messages().app }] : []),
+    preferences.appearance(),
     {
-      action: signOut,
-      icon: "ti ti-logout",
-      label: preferences.messages().signOut,
-      disabled: signingOut(),
+      items: [
+        preferences.languageItem(),
+        {
+          href: "/me",
+          icon: "ti ti-user-circle",
+          label: preferences.messages().profileSettings,
+        },
+        ...(appHref ? [{ href: appHref, icon: "ti ti-device-mobile", label: preferences.messages().app }] : []),
+        {
+          action: signOut,
+          icon: "ti ti-logout",
+          label: preferences.messages().signOut,
+          disabled: signingOut(),
+        },
+      ],
     },
   ]);
 

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

@@ -12,8 +12,10 @@ export const profilePreferencesMessages = i18n.define({
       app: "App",
       signOut: "Sign out",
       signOutFailed: "Sign out failed. Please try again.",
-      switchToDark: "Dark mode",
-      switchToLight: "Light mode",
+      appearance: "Appearance",
+      themeLight: "Light",
+      themeDark: "Dark",
+      themeSystem: "Automatic",
       switchToGerman: "Deutsch",
       switchToEnglish: "English",
     },
@@ -26,8 +28,10 @@ export const profilePreferencesMessages = i18n.define({
       app: "App",
       signOut: "Abmelden",
       signOutFailed: "Abmelden fehlgeschlagen. Bitte versuche es erneut.",
-      switchToDark: "Dunkler Modus",
-      switchToLight: "Heller Modus",
+      appearance: "Darstellung",
+      themeLight: "Hell",
+      themeDark: "Dunkel",
+      themeSystem: "Automatisch",
       switchToGerman: "Deutsch",
       switchToEnglish: "English",
     },

package/src/ssr/rail-context.ts

@@ -1,26 +1,22 @@
 import type { RailPreferences, RailSnapshot } from "../contracts/rail-preferences";
 import type { RailApp } from "./rail-navigation";
+import { readShellData } from "./shell-data";
 
 export type RailContext = { apps: RailApp[]; settings: RailSnapshot };
 export const RAIL_PREFERENCES_EVENT = "cloud:rail-preferences";
 
 export const readRailContext = (): RailContext | undefined => {
-  if (typeof document === "undefined") return undefined;
-  const text = document.getElementById("cloud-rail-data")?.textContent;
-  if (!text) return undefined;
-  // Framework-generated, escaped SSR data; never loaded from localStorage. The server validates the snapshot when
-  // it reads it, so the shell does not load the schemas on every page.
-  const value: RailContext = JSON.parse(text);
-  return { apps: value.apps, settings: value.settings };
+  const data = readShellData();
+  return data?.rail ? { apps: data.apps, settings: data.rail } : undefined;
 };
 
 export const publishRailPreferences = (settings: RailPreferences) => {
-  const context = readRailContext();
-  const element = document.getElementById("cloud-rail-data");
-  if (context && element)
+  const data = readShellData();
+  const element = document.getElementById("cloud-shell-data");
+  if (data?.rail && element)
     element.textContent = JSON.stringify({
-      ...context,
-      settings: { ...settings, managedShortcuts: context.settings.managedShortcuts },
+      ...data,
+      rail: { ...settings, managedShortcuts: data.rail.managedShortcuts },
     }).replace(/</g, "\\u003c");
   window.dispatchEvent(new CustomEvent(RAIL_PREFERENCES_EVENT));
 };

package/src/ssr/shell-data.tsx

@@ -0,0 +1,48 @@
+import { createContext, type JSX, useContext } from "solid-js";
+import type { AppSearchLink } from "../contracts/app";
+import type { RailSnapshot } from "../contracts/rail-preferences";
+import type { CloudThemePreference } from "../shared/theme";
+import type { AppLaunchpadLegalLink } from "./app-launchpad";
+import type { GlobalSearchHelpApp } from "./GlobalSearchHelpDialog";
+import type { RailApp } from "./rail-navigation";
+
+export type ShellData = {
+  /** The authorized navigation catalog, sorted for the request locale: the rail, the app grid and the phone menu show it. */
+  apps: RailApp[];
+  /** Signed-in pages: the person's rail preferences. */
+  rail?: RailSnapshot;
+  legalLinks: AppLaunchpadLegalLink[];
+  /** Signed-in pages: the person, for the profile menu and the phone menu's profile actions. */
+  profile?: { name: string; avatarSrc?: string; appHref?: string };
+  theme: CloudThemePreference;
+  /** The current app's accent, for the Help dialog and the phone menu, which open outside the app canvas. */
+  accent?: string;
+  /** The search destinations of each app in `apps`, by app id in registry order; the search host expands them into rows. */
+  searchLinks: Record<string, readonly AppSearchLink[]>;
+  searchHelpApps: GlobalSearchHelpApp[];
+};
+
+const ShellDataContext = createContext<() => ShellData>();
+
+export function ShellDataProvider(props: { data: ShellData; children: JSX.Element }) {
+  return (
+    <ShellDataContext.Provider value={() => props.data}>
+      <script id="cloud-shell-data" type="application/json" innerHTML={JSON.stringify(props.data).replace(/</g, "\\u003c")} />
+      {props.children}
+    </ShellDataContext.Provider>
+  );
+}
+
+export function readShellData(): ShellData | undefined {
+  if (typeof document === "undefined") return undefined;
+  const text = document.getElementById("cloud-shell-data")?.textContent;
+  if (!text) return undefined;
+  // Framework-generated, escaped SSR data; never loaded from localStorage. The server validates the rail snapshot when
+  // it reads it, so the shell does not load the schemas on every page.
+  const data: ShellData = JSON.parse(text);
+  return data;
+}
+
+export function useShellData(): ShellData | undefined {
+  return useContext(ShellDataContext)?.() ?? readShellData();
+}

package/src/ssr/timezone-cookie.ts

@@ -0,0 +1,22 @@
+import { cookies } from "@k2b/stdlib/browser";
+import { TIMEZONE_COOKIE } from "../shared/time";
+
+/**
+ * Stores the browser's timezone for server-rendered times. With `reload`, a
+ * changed timezone reloads the page once, so it shows times in that zone.
+ */
+export const syncTimezoneCookie = (reload: boolean) => {
+  const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  const current = cookies.readCookie(TIMEZONE_COOKIE);
+  if (!timeZone || current === timeZone) return;
+  cookies.writeCookie(TIMEZONE_COOKIE, timeZone);
+  if (!reload) return;
+  try {
+    if (sessionStorage.getItem("cloud.timezone.reload") !== timeZone) {
+      sessionStorage.setItem("cloud.timezone.reload", timeZone);
+      window.location.reload();
+    }
+  } catch {
+    // Cookie persistence still succeeds; the next navigation will render with the browser timezone.
+  }
+};

package/src/ssr/workspace-navigation.ts

@@ -1,4 +1,4 @@
-import { createNavigation, type NavigationController, type NavigationItem } from "@k2b/ui";
+import { type AppWorkspaceSidebarSwitcherProps, createNavigation, type NavigationController, type NavigationItem } from "@k2b/ui";
 import { createEffect, onCleanup, onMount } from "solid-js";
 
 export type WorkspaceNavigationState = { navigation: NavigationController; label: string; owner: Element };
@@ -44,6 +44,28 @@ function validItems(value: unknown): value is NavigationItem[] {
   );
 }
 
+function readSwitcher(value: unknown): AppWorkspaceSidebarSwitcherProps | undefined {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    !("currentId" in value) ||
+    typeof value.currentId !== "string" ||
+    !("label" in value) ||
+    typeof value.label !== "string" ||
+    !("icon" in value) ||
+    typeof value.icon !== "string" ||
+    !("switchLabel" in value) ||
+    typeof value.switchLabel !== "string"
+  )
+    return;
+  const description = "description" in value ? value.description : undefined;
+  const color = "color" in value ? value.color : undefined;
+  if (description !== undefined && typeof description !== "string") return;
+  if (color !== undefined && typeof color !== "string") return;
+  // The snapshot carries only the head; options and actions wait for the owning island.
+  return { currentId: value.currentId, label: value.label, icon: value.icon, switchLabel: value.switchLabel, description, color };
+}
+
 export function readWorkspaceNavigation(): WorkspaceNavigationState | undefined {
   if (typeof window === "undefined") return;
   const current = window.__cloudWorkspaceNavigation;
@@ -67,10 +89,11 @@ export function readWorkspaceNavigation(): WorkspaceNavigationState | undefined
         ...(item.inlineActions ? { inlineActions: item.inlineActions.map((action) => ({ ...action, disabled: true })) } : {}),
       }));
     const items = links(value.items);
+    const switcher = "switcher" in value ? readSwitcher(value.switcher) : undefined;
     return {
       owner,
       label: "label" in value && typeof value.label === "string" ? value.label : "",
-      navigation: createNavigation({ items: () => items }),
+      navigation: createNavigation({ items: () => items, ...(switcher ? { switcher: () => switcher } : {}) }),
     };
   } catch {
     return;