@k2b/cloud 0.31.0 → 0.33.0

package/src/ssr/MinimalLayoutPreferences.island.tsx

@@ -1,21 +1,15 @@
-import { Button, Dropdown, useLocale } from "@k2b/ui";
+import { Dropdown, useLocale } from "@k2b/ui";
 import { canonicalLocale } from "../shared/locale";
 import { type ProfilePreferenceLocale, profilePreferenceLocale, setLocalePreference } from "../shared/locale-preference";
-import type { CloudTheme } from "../shared/theme";
+import type { CloudThemePreference } from "../shared/theme";
 import { createPreferenceController } from "./preference-controller";
 
-/**
- * Labeled language and theme controls for the MinimalLayout footer. The
- * language trigger names the current language; the theme button names the
- * mode it switches to, like every other Cloud preference menu. Below `md` both
- * are compact, the language code and the theme icon with the full names as
- * accessible labels, so they fit next to the legal links on a phone. CSS picks
- * the form, so the server response is already final.
- */
-export default function MinimalLayoutPreferences(props: { initialTheme: CloudTheme }) {
+/** Both menus name the current choice; compact triggers keep accessible names below md. */
+export default function MinimalLayoutPreferences(props: { initialTheme: CloudThemePreference }) {
   const locale = useLocale();
   const preferences = createPreferenceController(props.initialTheme, locale);
   const t = preferences.messages;
+  const currentTheme = () => preferences.themeOption(preferences.theme());
   const language = () => profilePreferenceLocale(locale());
   const languageName = () => (language() === "de" ? t().switchToGerman : t().switchToEnglish);
   // Keep a regional locale such as en-GB when its language is chosen again,
@@ -43,10 +37,13 @@ export default function MinimalLayoutPreferences(props: { initialTheme: CloudThe
           <i class="ti ti-chevron-down hidden md:inline" aria-hidden="true" />
         </Dropdown.Trigger>
       </Dropdown.Root>
-      <Button aria-label={preferences.themeLabel()} onClick={preferences.toggleTheme} size="sm" variant="ghost">
-        <i class={preferences.theme() === "light" ? "ti ti-moon" : "ti ti-sun-high"} aria-hidden="true" />
-        <span class="hidden md:inline">{preferences.themeLabel()}</span>
-      </Button>
+      <Dropdown.Root label={t().appearance} position="top-right" width="12rem" items={preferences.appearance().items}>
+        <Dropdown.Trigger label={`${t().appearance}: ${currentTheme().label}`} size="sm" tooltip={false} variant="ghost">
+          <i class={currentTheme().icon} aria-hidden="true" />
+          <span class="hidden md:inline">{currentTheme().label}</span>
+          <i class="ti ti-chevron-down hidden md:inline" aria-hidden="true" />
+        </Dropdown.Trigger>
+      </Dropdown.Root>
     </div>
   );
 }

package/src/ssr/MobileNavigation.tsx

@@ -1,8 +1,10 @@
 import { BottomSheet, Navigation, SegmentedControl, useLocale } from "@k2b/ui";
 import { createSignal, onCleanup, Show } from "solid-js";
 import { type AppLaunchpadContext, AppLaunchpadPanel } from "./AppLaunchpadPanel";
+import { appAccentStyle } from "./app-appearance";
 import { openMobileMenu } from "./mobile-menu-history";
 import { platformMessages } from "./platform-messages";
+import { readShellData } from "./shell-data";
 import { observeWorkspaceNavigation, readWorkspaceNavigation } from "./workspace-navigation";
 
 export function openCloudMobileMenu(apps: AppLaunchpadContext) {
@@ -58,14 +60,17 @@ function MobileNavigation(props: {
           when={workspace() && tab() === "app"}
           fallback={<AppLaunchpadPanel surface="sheet" {...props.apps} close={props.close} beforeSelect={props.beforeSelect} />}
         >
-          <Navigation
-            navigation={workspace()!.navigation}
-            label={workspace()!.label || t().appMenu}
-            beforeSelect={async () => {
-              const owner = workspace()?.owner;
-              return (await props.beforeSelect()) && Boolean(owner?.isConnected && readWorkspaceNavigation()?.owner === owner);
-            }}
-          />
+          {/* The sheet opens outside the app canvas, so the app menu takes the app's accent here, as the canvas does. */}
+          <div class="app-accent-scope" style={appAccentStyle(readShellData()?.accent)}>
+            <Navigation
+              navigation={workspace()!.navigation}
+              label={workspace()!.label || t().appMenu}
+              beforeSelect={async () => {
+                const owner = workspace()?.owner;
+                return (await props.beforeSelect()) && Boolean(owner?.isConnected && readWorkspaceNavigation()?.owner === owner);
+              }}
+            />
+          </div>
         </Show>
       </BottomSheet.Body>
     </BottomSheet>

package/src/ssr/MobileProfileActions.tsx

@@ -1,10 +1,10 @@
 import { documentNavigate } from "@k2b/ssr/nav";
-import { Button, ButtonLink } from "@k2b/ui";
-import type { CloudTheme } from "../shared/theme";
+import { Button, ButtonLink, SegmentedControl } from "@k2b/ui";
+import type { CloudThemePreference } from "../shared/theme";
 import { createProfileActions } from "./profile-actions";
 
 export function MobileProfileActions(props: {
-  profile: { name: string; theme: CloudTheme; appHref?: string };
+  profile: { name: string; theme: CloudThemePreference; appHref?: string };
   beforeSelect: () => Promise<boolean>;
 }) {
   const { preferences, signingOut, signOut } = createProfileActions(props.profile.theme, props.profile.appHref);
@@ -17,6 +17,13 @@ export function MobileProfileActions(props: {
   };
   return (
     <section class="cloud-mobile-profile" aria-label={preferences.messages().menuLabel}>
+      <SegmentedControl
+        class="cloud-mobile-profile__appearance"
+        ariaLabel={preferences.messages().appearance}
+        options={preferences.themeOptions()}
+        value={preferences.theme}
+        onValueChange={preferences.setTheme}
+      />
       <ButtonLink href="/me" variant="ghost" onClick={navigate("/me")}>
         <i class="ti ti-user-circle" aria-hidden="true" />
         {preferences.messages().profileSettings}
@@ -27,10 +34,6 @@ export function MobileProfileActions(props: {
           {preferences.messages().app}
         </ButtonLink>
       )}
-      <Button variant="ghost" onClick={preferences.toggleTheme}>
-        <i class={`ti ${preferences.theme() === "light" ? "ti-moon" : "ti-sun-high"}`} aria-hidden="true" />
-        {preferences.themeLabel()}
-      </Button>
       <Button
         variant="ghost"
         onClick={async () => {

package/src/ssr/PageTrailRow.tsx

@@ -0,0 +1,14 @@
+import { PageTitle, type PageTrailState } from "@k2b/ui";
+
+/**
+ * The shell's own place for the way up, above pages without a workspace. It
+ * shows only on a page with a page above it, and steps back when the page
+ * renders a workspace (whose head shows it) or its own `PageTrail`.
+ */
+export default function PageTrailRow(props: { trail: PageTrailState }) {
+  return (
+    <div class="layout-page-head" data-trail={props.trail.ancestors.length ? "up" : "title"}>
+      <PageTitle trail={props.trail} as="p" fallback />
+    </div>
+  );
+}

package/src/ssr/{ProfilePreferences.island.tsx → ProfilePreferences.tsx}

@@ -1,12 +1,12 @@
-import { Avatar, Dropdown } from "@k2b/ui";
-import type { CloudTheme } from "../shared/theme";
+import { Avatar, Dropdown, SegmentedControl } from "@k2b/ui";
+import type { CloudThemePreference } from "../shared/theme";
 import { createProfileActions } from "./profile-actions";
 
 type ProfilePreferencesProps = {
   /** Set while the installation offers the mobile app. */
   appHref?: string;
   avatarSrc?: string;
-  initialTheme: CloudTheme;
+  initialTheme: CloudThemePreference;
   name: string;
 };
 
@@ -26,10 +26,15 @@ export default function ProfilePreferences(props: ProfilePreferencesProps) {
         {avatar()}
       </button>
       <div class="layout-profile-preferences__panel dropdown-menu-surface">
-        <button type="button" class="menu-item" onClick={preferences.toggleTheme}>
-          <i class={`ti ${preferences.theme() === "light" ? "ti-moon" : "ti-sun-high"}`} aria-hidden="true" />
-          <span>{preferences.themeLabel()}</span>
-        </button>
+        <div class="layout-profile-preferences__appearance">
+          <SegmentedControl
+            size="sm"
+            ariaLabel={preferences.messages().appearance}
+            options={preferences.themeOptions().map(({ value, label }) => ({ value, label }))}
+            value={preferences.theme}
+            onValueChange={preferences.setTheme}
+          />
+        </div>
         <button type="button" class="menu-item" onClick={preferences.toggleLanguage}>
           <i class="ti ti-language" aria-hidden="true" />
           <span>{preferences.languageLabel()}</span>

package/src/ssr/PwaLayout.tsx

@@ -2,7 +2,6 @@ import { LocaleProvider, MobileShell, TabBar, type TabBarItem } from "@k2b/ui";
 import type { JSX } from "solid-js";
 import { PWA_SCOPE } from "../contracts/pwa";
 import { getLocale } from "../server/locale";
-import { readThemeFromCookieHeader } from "../shared/theme";
 import { visiblePwaParts } from "./app-navigation";
 import type { LayoutContext } from "./layout-context";
 import PwaRuntime from "./PwaRuntime.island";
@@ -37,7 +36,6 @@ export default function PwaLayout(props: PwaLayoutProps) {
   const user = c.get("user");
   const cloud = c.get("settings")?.app?.name || "Cloud";
   const page = c.get("page");
-  page.theme = readThemeFromCookieHeader(c.req.raw.headers.get("Cookie"));
   page.title = props.title;
   page.pwa = { name: cloud };
   // No app page may be framed, and none leaks its address to another site.

package/src/ssr/PwaRuntime.island.tsx

@@ -7,7 +7,7 @@ import { pwaMessages } from "./pwa-messages";
 /** Set once per browsing session, so the first page renews and later navigations do not. */
 const RENEWED_MARKER = "cloud.pwa.renewed";
 const KEEPALIVE_INTERVAL_MS = 60 * 60 * 1000;
-/** Matches `cloud:theme-preference` in the preference controller. */
+/** Fires for preference changes and system scheme changes from the head script. */
 const THEME_PREFERENCE_EVENT = "cloud:theme-preference";
 
 export type PwaRuntimeProps = {

package/src/ssr/{RailApps.island.tsx → RailApps.tsx}

@@ -10,7 +10,7 @@ import { projectRailNavigation, type RailApp, type RailLink, railLinkActive } fr
 function RailIcon(props: { link: RailLink; currentPath: string }) {
   let target: HTMLAnchorElement | undefined;
   const active = () => railLinkActive(props.link, props.currentPath);
-  const badge = useAppBadgeDescription(() => props.link.badge);
+  const badge = useAppBadgeDescription(() => ({ endpoint: props.link.badge, appId: props.link.appId }));
   return (
     <>
       <a
@@ -23,7 +23,7 @@ function RailIcon(props: { link: RailLink; currentPath: string }) {
       >
         <i class={`${props.link.iconClass} text-base`} aria-hidden="true" />
         <span class="sr-only">{props.link.label}</span>
-        <AppBadge endpoint={props.link.badge} />
+        <AppBadge endpoint={props.link.badge} appId={props.link.appId} />
       </a>
       <Tooltip target={() => target} content={props.link.label} placement="right" delay={0} />
     </>

package/src/ssr/ShellRuntime.island.tsx

@@ -0,0 +1,170 @@
+import type { HelpDocumentManifest } from "@k2b/cloud/shared";
+import {
+  followPageTrail,
+  installAppWorkspaceController,
+  installPageTitleController,
+  serializeAppWorkspaceLayoutState,
+  useLocale,
+} from "@k2b/ui";
+import { createEffect, onCleanup, onMount } from "solid-js";
+import { appWorkspaceCookieName, readAppWorkspaceLayoutCookie } from "../_internal/app-workspace-state";
+import { registerContextAwareCommand } from "../browser/command-bridge";
+import { attachCommandShortcuts } from "../browser/command-shortcuts";
+import { navigationSearchItems } from "../browser/navigation-search";
+import { importOnDemand } from "../browser/reload";
+import { registerGlobalSearchHost } from "../browser/search-bridge";
+import {
+  ANNOUNCEMENTS_COOKIE,
+  ANNOUNCEMENTS_COOKIE_MAX_AGE_SECONDS,
+  mergeAnnouncementCookieState,
+  parseAnnouncementCookieHeader,
+  serializeAnnouncementCookieState,
+} from "../contracts/announcement-cookie";
+import type { AnnouncementDisplayEntry } from "../contracts/announcements";
+import { createGlobalSearchHost } from "./global-search-host";
+import { LayoutHelpDocuments } from "./layout-help-registry";
+import { installPageTrailRuntime } from "./page-trail-runtime";
+import { platformMessages } from "./platform-messages";
+import { readShellData } from "./shell-data";
+import { syncTimezoneCookie } from "./timezone-cookie";
+
+export type ShellRuntimeProps = {
+  /** Layout pages outside focus mode: keep the current app's workspace layout in its cookie. */
+  workspace?: { appId?: string };
+  /** Layout pages: page titles, the way up (Alt+Up) and its per-tab memory. */
+  pageTrail?: boolean;
+  /** The current app's Help documents. */
+  help?: { documents: readonly HelpDocumentManifest[]; pageBase: string };
+  /** Layout pages outside focus mode: the search host, Cmd/Ctrl+K, the Help command (Shift+/) and command shortcuts. */
+  commands?: { searchResources: boolean };
+  /** Signed-in pages: refresh this browser's push endpoint. */
+  push?: boolean;
+  /** Announcements the person has not seen yet; a dialog shows them once. */
+  announcements?: { entries: AnnouncementDisplayEntry[]; latestVersion: number };
+  /** Banners rendered by Layout: their dismiss buttons record the dismissal. */
+  banners?: boolean;
+};
+
+/** The search rows of the shell's destinations; the page carries each link once, without the fields a row repeats. */
+const searchItems = () => {
+  const data = readShellData();
+  if (!data) return [];
+  const apps = Object.entries(data.searchLinks).flatMap(([id, searchLinks]) => {
+    const app = data.apps.find((candidate) => candidate.id === id);
+    return app ? [{ id, name: app.label, icon: app.iconClass, searchLinks }] : [];
+  });
+  return navigationSearchItems(
+    apps,
+    apps.map((app) => app.id),
+  );
+};
+
+export default function ShellRuntime(props: ShellRuntimeProps) {
+  const locale = useLocale();
+  const t = () => platformMessages.resolve([locale()]).t;
+  onMount(() => syncTimezoneCookie(true));
+
+  if (props.workspace) {
+    onMount(() => {
+      const appId = props.workspace?.appId;
+      onCleanup(
+        installAppWorkspaceController({
+          readState: () => readAppWorkspaceLayoutCookie(document.cookie, appId),
+          writeState: (state) => {
+            if (!appId) return;
+            const secure = window.location.protocol === "https:" ? "; Secure" : "";
+            document.cookie = `${appWorkspaceCookieName(appId)}=${serializeAppWorkspaceLayoutState(state)}; Path=/; Max-Age=31536000; SameSite=Lax${secure}`;
+          },
+        }),
+      );
+    });
+  }
+  if (props.pageTrail) {
+    onMount(() => {
+      const messages = t();
+      const disposeTitles = installPageTitleController(document);
+      const disposeFollow = followPageTrail(document);
+      const disposeRuntime = installPageTrailRuntime((page) => ({
+        title: messages.pageUp({ page }),
+        description: messages.pageUpDescription,
+      }));
+      onCleanup(() => {
+        disposeTitles();
+        disposeFollow();
+        disposeRuntime();
+      });
+    });
+  }
+  if (props.commands) {
+    const host = createGlobalSearchHost(searchItems, props.commands.searchResources);
+    onMount(() => onCleanup(registerGlobalSearchHost(host.open, host.dispose)));
+    // Command schemas and the capability client load with the first shortcut.
+    onMount(() =>
+      onCleanup(
+        attachCommandShortcuts(
+          (command) =>
+            void importOnDemand(() => import("../browser/commands")).then((commands) => commands?.runContextAwareCommand(command)),
+        ),
+      ),
+    );
+    createEffect(() =>
+      onCleanup(
+        registerContextAwareCommand({
+          id: "cloud.search",
+          title: t().openGlobalSearch,
+          description: t().globalSearchDescription,
+          icon: "ti ti-search",
+          shortcut: "mod+k",
+          action: { search: {} },
+        }),
+      ),
+    );
+    createEffect(() =>
+      onCleanup(
+        registerContextAwareCommand({
+          id: "cloud.help",
+          title: t().openShortcutHelp,
+          description: t().shortcutHelpDescription,
+          icon: "ti ti-help-circle",
+          shortcut: "shift+/",
+          // Returning the load keeps the Command busy until the dialog is open; a second press opens no second dialog.
+          action: () =>
+            importOnDemand(() => import("./LayoutHelp")).then((help) => {
+              const data = readShellData();
+              help?.openLayoutHelpDialog(data?.searchHelpApps ?? [], data?.accent);
+            }),
+        }),
+      ),
+    );
+  }
+  onMount(() => {
+    if (props.push) {
+      void import("../browser/notifications")
+        .then(({ browserNotificationClient }) => browserNotificationClient.refreshExisting())
+        .catch((error) => {
+          console.warn("[notifications] Failed to refresh the browser endpoint", error);
+        });
+    }
+    if (props.announcements?.entries.length) {
+      const announcements = props.announcements;
+      void importOnDemand(() => import("./announcements-dialog")).then((loaded) => loaded?.openAnnouncementsDialog(announcements));
+    }
+    if (props.banners) {
+      const dismiss = (event: MouseEvent) => {
+        if (!(event.target instanceof Element)) return;
+        const button = event.target.closest<HTMLButtonElement>("[data-cloud-announcement-dismiss]");
+        if (!button) return;
+        const version = Number(button.dataset.cloudAnnouncementDismiss);
+        const next = mergeAnnouncementCookieState(parseAnnouncementCookieHeader(document.cookie), { dismissedBannerVersions: [version] });
+        document.cookie = `${ANNOUNCEMENTS_COOKIE}=${serializeAnnouncementCookieState(next)}; Path=/; Max-Age=${ANNOUNCEMENTS_COOKIE_MAX_AGE_SECONDS}; SameSite=Lax`;
+        const banner = button.closest(".cloud-announcement");
+        const list = banner?.parentElement;
+        banner?.remove();
+        if (list && !list.querySelector(".cloud-announcement")) list.remove();
+      };
+      document.addEventListener("click", dismiss);
+      onCleanup(() => document.removeEventListener("click", dismiss));
+    }
+  });
+  return props.help ? <LayoutHelpDocuments documents={props.help.documents} pageBase={props.help.pageBase} /> : null;
+}

package/src/ssr/TimezoneCookie.island.tsx

@@ -1,29 +1,13 @@
-import { cookies } from "@k2b/stdlib/browser";
 import { onMount } from "solid-js";
-import { TIMEZONE_COOKIE } from "../shared/time";
+import { syncTimezoneCookie } from "./timezone-cookie";
 
 export type TimezoneCookieProps = {
   /** Reload once after a timezone change, so the page shows times in the browser's zone. Defaults to `true`. */
   reload?: boolean;
 };
 
+/** The timezone cookie for layouts without the shell runtime: `MinimalLayout` and `PwaLayout`. */
 export default function TimezoneCookie(props: TimezoneCookieProps) {
-  onMount(() => {
-    const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
-    const current = cookies.readCookie(TIMEZONE_COOKIE);
-    if (timeZone && current !== timeZone) {
-      cookies.writeCookie(TIMEZONE_COOKIE, timeZone);
-      if (props.reload === false) 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.
-      }
-    }
-  });
-
+  onMount(() => syncTimezoneCookie(props.reload !== false));
   return null;
 }

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-badges.ts

@@ -1,5 +1,7 @@
 import { createSignal } from "solid-js";
 import { APP_BADGES_REFRESH_EVENT } from "../browser/app-badges";
+import { APPROVAL_COUNTS_PATH } from "../contracts/approval-paths";
+import type { ApprovalCounts } from "../contracts/approvals";
 
 /**
  * Shortest time between two scheduled reads in one tab, and the longest one
@@ -13,8 +15,20 @@ export const APP_BADGE_INTERVAL_MS = 60_000;
 // count. Only the browser ever writes it; server renders always see no badge.
 const [counts, setCounts] = createSignal<ReadonlyMap<string, number>>(new Map());
 
-/** The count for a declared `nav.badge` endpoint; 0 until the browser has read it. */
-export const appBadgeCount = (endpoint: string | undefined): number => (endpoint ? (counts().get(endpoint) ?? 0) : 0);
+const [approvalCounts, setApprovalCounts] = createSignal<ApprovalCounts | null>(null);
+
+/** Retain an SSR count until the first browser read; a failed read still resolves to zero. */
+export const liveApprovalCount = (appId?: string): number | null => {
+  const current = approvalCounts();
+  if (!current) return null;
+  if (appId === undefined) return current.total;
+  return Object.hasOwn(current.apps, appId) ? (current.apps[appId] ?? 0) : 0;
+};
+export const approvalCount = (appId?: string): number => liveApprovalCount(appId) ?? 0;
+
+/** Endpoint and approval counts for one app; 0 until the browser has read them. */
+export const appBadgeCount = (input: { endpoint?: string; appId?: string }): number =>
+  (input.endpoint ? (counts().get(input.endpoint) ?? 0) : 0) + (input.appId ? approvalCount(input.appId) : 0);
 
 /** A positive safe integer from an `AppNavBadge` body, else 0. */
 export const parseAppBadge = (body: unknown): number => {
@@ -33,6 +47,33 @@ const readBadge = async (endpoint: string, signal: AbortSignal): Promise<number>
   }
 };
 
+const isCount = (value: unknown, minimum: number): value is number =>
+  typeof value === "number" && Number.isSafeInteger(value) && value >= minimum;
+
+/** What `ApprovalCountsSchema` accepts from a JSON body, without loading validators into the shell; a test compares both. */
+export const parseApprovalCounts = (body: unknown): ApprovalCounts | null => {
+  if (typeof body !== "object" || body === null || Array.isArray(body)) return null;
+  if (Object.keys(body).length !== 2 || !("total" in body) || !("apps" in body)) return null;
+  const { total, apps } = body;
+  if (!isCount(total, 0) || typeof apps !== "object" || apps === null || Array.isArray(apps)) return null;
+  // Like Zod's record, ignore a `__proto__` key that JSON.parse keeps as an own property.
+  const entries = Object.entries(apps).filter(([app]) => app !== "__proto__");
+  return entries.every(([, count]) => isCount(count, 1)) ? { total, apps: Object.fromEntries(entries) } : null;
+};
+
+const readApprovalCounts = async (signal: AbortSignal): Promise<ApprovalCounts> => {
+  try {
+    const response = await fetch(APPROVAL_COUNTS_PATH, { credentials: "same-origin", headers: { accept: "application/json" }, signal });
+    if (response.status === 200) {
+      const parsed = parseApprovalCounts(await response.json());
+      if (parsed) return parsed;
+    }
+  } catch {
+    // A failing read clears approval counts just like an app badge.
+  }
+  return { total: 0, apps: {} };
+};
+
 let watching = false;
 
 /**
@@ -45,8 +86,8 @@ let watching = false;
  * read still running after the interval gives up. Returns a disposer.
  */
 export const watchAppBadges = (endpoints: readonly string[]): (() => void) => {
-  const unique = [...new Set(endpoints)];
-  if (typeof window === "undefined" || unique.length === 0 || watching) return () => {};
+  const unique = [...new Set([...endpoints, APPROVAL_COUNTS_PATH])];
+  if (typeof window === "undefined" || watching) return () => {};
   watching = true;
   const stopped = new AbortController();
   // Endpoints with a read in flight, mapped to whether one more read waits for it.
@@ -60,9 +101,12 @@ export const watchAppBadges = (endpoints: readonly string[]): (() => void) => {
       return;
     }
     running.set(endpoint, false);
-    void readBadge(endpoint, AbortSignal.any([stopped.signal, AbortSignal.timeout(APP_BADGE_INTERVAL_MS)])).then((count) => {
+    const signal = AbortSignal.any([stopped.signal, AbortSignal.timeout(APP_BADGE_INTERVAL_MS)]);
+    const result = endpoint === APPROVAL_COUNTS_PATH ? readApprovalCounts(signal) : readBadge(endpoint, signal);
+    void result.then((count) => {
       if (stopped.signal.aborted) return;
-      setCounts((previous) => new Map(previous).set(endpoint, count));
+      if (typeof count === "number") setCounts((previous) => new Map(previous).set(endpoint, count));
+      else setApprovalCounts(count);
       const queued = running.get(endpoint);
       running.delete(endpoint);
       if (queued && document.visibilityState !== "hidden") read(endpoint);