@k2b/cloud 0.32.0 → 0.33.0

package/src/ssr/AppLaunchpadPanel.tsx

@@ -3,7 +3,7 @@ import { IconButton, ScrollArea, TextInput, useLocale } from "@k2b/ui";
 import { createSignal, For, type JSX, Show } from "solid-js";
 import { Dynamic } from "solid-js/web";
 import { importOnDemand } from "../browser/reload";
-import type { CloudTheme } from "../shared/theme";
+import type { CloudThemePreference } from "../shared/theme";
 import { AppBadge, useAppBadgeDescription } from "./AppBadge";
 import { MobileProfileActions } from "./MobileProfileActions";
 import { platformMessages } from "./platform-messages";
@@ -29,7 +29,7 @@ export type AppLaunchpadLegalLink = {
 };
 
 export type AppLaunchpadContext = {
-  profile?: { name: string; theme: CloudTheme; appHref?: string };
+  profile?: { name: string; theme: CloudThemePreference; appHref?: string };
   apps: AppLaunchpadApp[];
   legalLinks: AppLaunchpadLegalLink[];
 };

package/src/ssr/CloudShell.island.tsx

@@ -0,0 +1,91 @@
+import { useLocale } from "@k2b/ui";
+import { createEffect } from "solid-js";
+import { AppLaunchpadButton, setAppLaunchpadContext } from "./app-launchpad";
+import GlobalSearchTrigger from "./GlobalSearchTrigger";
+import LayoutBreadcrumbs from "./LayoutBreadcrumbs";
+import LayoutHelpTrigger from "./LayoutHelpTrigger";
+import LayoutPreferences from "./LayoutPreferences";
+import type { LayoutBreadcrumb } from "./layout-runtime";
+import ProfilePreferences from "./ProfilePreferences";
+import { platformMessages } from "./platform-messages";
+import RailApps from "./RailApps";
+import { useShellData } from "./shell-data";
+
+type CloudShellProps =
+  | { slot: "rail"; currentPath: string }
+  | { slot: "header"; authenticated: boolean; title?: string; launchpad: boolean; breadcrumbs?: LayoutBreadcrumb[] };
+
+/**
+ * The interactive part of the shell chrome. `LayoutRail` and `LayoutHeader`
+ * own the frame and the plain links around it as server markup.
+ */
+export default function CloudShell(props: CloudShellProps) {
+  return props.slot === "rail" ? <RailNavigation currentPath={props.currentPath} /> : <HeaderControls {...props} />;
+}
+
+function RailNavigation(props: { currentPath: string }) {
+  const data = useShellData();
+  const locale = useLocale();
+  const t = () => platformMessages.resolve([locale()]).t;
+  if (!data?.rail || !data.profile) return null;
+  const profile = { name: data.profile.name, theme: data.theme, ...(data.profile.appHref ? { appHref: data.profile.appHref } : {}) };
+  createEffect(() => setAppLaunchpadContext(data.apps, data.legalLinks, profile));
+  return (
+    <nav class="layout-rail-navigation flex min-h-0 flex-1 flex-col items-center gap-1" aria-label={t().apps}>
+      <RailApps apps={data.apps} settings={data.rail} currentPath={props.currentPath} />
+      <AppLaunchpadButton profile={profile} apps={data.apps} legalLinks={data.legalLinks} variant="rail" label={t().openApps} />
+      <div class="mt-auto shrink-0 flex flex-col items-center gap-1">
+        <GlobalSearchTrigger variant="rail" />
+        <LayoutHelpTrigger variant="rail" />
+        <ProfilePreferences
+          appHref={data.profile.appHref}
+          avatarSrc={data.profile.avatarSrc}
+          initialTheme={data.theme}
+          name={data.profile.name}
+        />
+      </div>
+    </nav>
+  );
+}
+
+/** The header's title and controls, between the server-rendered Home and Sign in. */
+function HeaderControls(props: { authenticated: boolean; title?: string; launchpad: boolean; breadcrumbs?: LayoutBreadcrumb[] }) {
+  const data = useShellData();
+  const locale = useLocale();
+  const t = () => platformMessages.resolve([locale()]).t;
+  if (!data) return null;
+  return (
+    <>
+      <div class="ml-2 flex min-w-0 flex-1 items-center">
+        {!props.authenticated && (
+          <div class="hidden min-w-0 items-center lg:flex">
+            <LayoutBreadcrumbs breadcrumbs={props.breadcrumbs ?? []} />
+          </div>
+        )}
+        <div class="flex min-w-0 items-center lg:hidden">
+          <span class="truncate font-semibold">{props.title}</span>
+        </div>
+      </div>
+      <div class="flex shrink-0 items-center gap-1">
+        <div class="flex items-center gap-1 lg:hidden">
+          <LayoutHelpTrigger variant="header" />
+          {props.authenticated && <GlobalSearchTrigger variant="header" />}
+          {props.launchpad && (
+            <AppLaunchpadButton
+              profile={
+                data.profile
+                  ? { name: data.profile.name, theme: data.theme, ...(data.profile.appHref ? { appHref: data.profile.appHref } : {}) }
+                  : undefined
+              }
+              apps={data.apps}
+              legalLinks={data.legalLinks}
+              variant="header"
+              label={t().openApps}
+            />
+          )}
+        </div>
+        {!props.authenticated && <LayoutPreferences initialTheme={data.theme} position="bottom-left" />}
+      </div>
+    </>
+  );
+}

package/src/ssr/GlobalSearchTrigger.tsx

@@ -0,0 +1,51 @@
+import { IconButton, Tooltip, useLocale } from "@k2b/ui";
+import { importOnDemand } from "../browser/reload";
+import { openGlobalSearch } from "../browser/search";
+import { createBusyAction } from "./busy-action";
+import { platformMessages } from "./platform-messages";
+
+type GlobalSearchTriggerProps = {
+  variant: "header" | "rail";
+  class?: string;
+};
+
+/** Opens the spotlight-style global search dialog from nav/header trigger points. */
+export default function GlobalSearchTrigger(props: GlobalSearchTriggerProps) {
+  const locale = useLocale();
+  const t = () => platformMessages.resolve([locale()]).t;
+
+  const action = createBusyAction();
+  const open = () =>
+    action.run(
+      () => importOnDemand(() => import("./GlobalSearchDialog")),
+      () => openGlobalSearch(),
+    );
+
+  if (props.variant === "rail")
+    return (
+      <Tooltip.Trigger
+        type="button"
+        class={`rail-item text-blue-500 hover:bg-blue-500/10 hover:text-blue-600 dark:text-blue-400 dark:hover:bg-blue-500/15 dark:hover:text-blue-300 ${props.class ?? ""}`}
+        onClick={open}
+        aria-busy={action.busy() ? "true" : undefined}
+        aria-label={t().openGlobalSearch}
+        placement="right"
+        delay={0}
+        content={t().searchShortcut}
+      >
+        <i class={`${action.busy() ? "ti ti-loader-2 animate-spin" : "ti ti-search"} text-base`} />
+      </Tooltip.Trigger>
+    );
+
+  return (
+    <IconButton
+      class={props.class}
+      onClick={open}
+      aria-busy={action.busy() ? "true" : undefined}
+      label={t().openGlobalSearch}
+      title={t().searchShortcut}
+    >
+      <i class={`${action.busy() ? "ti ti-loader-2 animate-spin" : "ti ti-search"} text-base`} />
+    </IconButton>
+  );
+}

package/src/ssr/Layout.tsx

@@ -2,7 +2,6 @@ import type { DateContext } from "@k2b/stdlib";
 import { AppWorkspace, appWorkspaceLayoutStyle, LocaleProvider, NoticeCard, PageTrailProvider } from "@k2b/ui";
 import type { JSX } from "solid-js/jsx-runtime";
 import { readAppWorkspaceLayoutCookie, resolveAppWorkspaceLayoutForSidebar } from "../_internal/app-workspace-state";
-import { navigationSearchItems } from "../browser/navigation-search";
 import { resolveNavMatch } from "../contracts/app"; // ==========================
 import { isPwaShellAvailable } from "../contracts/pwa";
 import { defaultRailPreferences } from "../contracts/rail-preferences";
@@ -10,13 +9,10 @@ import { hasRole, type User } from "../contracts/shared";
 import { getLocale } from "../server/locale";
 import { getDateConfig } from "../server/time";
 import { dates } from "../shared";
-import { readThemeFromCookieHeader } from "../shared/theme";
-import type { AppLaunchpadApp } from "./AppLaunchpad.island";
-import AppWorkspaceController from "./AppWorkspaceController.island";
+import { readThemePreferenceFromCookieHeader } from "../shared/theme";
+import AnnouncementBanners from "./AnnouncementBanners";
 import { appAppearanceStyle } from "./app-appearance";
 import { resolveRuntimeRoute, visibleNavigationApps } from "./app-navigation";
-import BrowserPushRegistration from "./BrowserPushRegistration.island";
-import GlobalAnnouncements from "./GlobalAnnouncements.island";
 import type { GlobalSearchHelpApp } from "./GlobalSearchHelpDialog";
 import { getLayoutHelp } from "./help";
 import LayoutFooter from "./LayoutFooter";
@@ -24,15 +20,14 @@ import LayoutHeader from "./LayoutHeader";
 import LayoutRail, { type LayoutAppLink } from "./LayoutRail";
 import type { LayoutContext } from "./layout-context";
 import type { LayoutBreadcrumb } from "./layout-runtime";
-import PageTrailRow from "./PageTrailRow.island";
-import PageTrailRuntime from "./PageTrailRuntime.island";
+import PageTrailRow from "./PageTrailRow";
 import { derivePageTrail } from "./page-trail";
 import { platformMessages } from "./platform-messages";
-import RegisteredHelpDocuments from "./RegisteredHelpDocuments.island";
 import { sortRailApps } from "./rail-navigation";
 import { requestPath } from "./request-path";
 import { getLocalizedRuntimeContext, type RuntimeContext } from "./runtime";
-import TimezoneCookie from "./TimezoneCookie.island";
+import ShellRuntime from "./ShellRuntime.island";
+import { type ShellData, ShellDataProvider } from "./shell-data";
 
 // Types
 type Breadcrumb = LayoutBreadcrumb;
@@ -146,8 +141,7 @@ export default function Layout(props: LayoutProps) {
   const { c, title, fullPage, fullWidth, focusMode, flushCanvas, workspaceSidebarCollapsible } = props;
   const runtime = getLocalizedRuntimeContext(c);
   const cookie = c.req.raw.headers.get("Cookie") ?? "";
-  const theme = readThemeFromCookieHeader(cookie);
-  c.get("page").theme = theme;
+  const theme = readThemePreferenceFromCookieHeader(cookie);
   // One request-scoped locale drives <html lang>, the LocaleProvider below,
   // and date formatting. The SSR seam and this component both resolve through
   // the same canonical getLocale(c), so pages cannot diverge the three seams.
@@ -159,24 +153,16 @@ export default function Layout(props: LayoutProps) {
   const currentRoute = resolveRuntimeRoute(runtime.apps, pathname);
   const currentApp = currentRoute?.app;
   const registeredHelp = getLayoutHelp(c);
+  const runtimeHelp = registeredHelp ? { documents: registeredHelp.documents, pageBase: registeredHelp.pageBase } : undefined;
   const workspaceLayout = resolveAppWorkspaceLayoutForSidebar(
     readAppWorkspaceLayoutCookie(cookie, currentApp?.id),
     workspaceSidebarCollapsible,
   );
   const { primary: primaryApps, more: moreApps } = buildNavLinks(runtime.apps, user, lang);
   const allApps = sortRailApps([...primaryApps, ...moreApps], lang);
-  const launchpadApps: AppLaunchpadApp[] = allApps.map((app) => ({
-    id: app.id,
-    iconClass: app.iconClass,
-    label: app.label,
-    href: app.href,
-    description: app.description,
-    accent: app.accent,
-    badge: app.badge,
-  }));
-  const searchLinks = navigationSearchItems(
-    runtime.apps,
-    allApps.map((app) => app.id),
+  const visibleAppIds = new Set(allApps.map((app) => app.id));
+  const searchLinks = Object.fromEntries(
+    runtime.apps.flatMap((app) => (visibleAppIds.has(app.id) && app.searchLinks?.length ? [[app.id, app.searchLinks] as const] : [])),
   );
   const searchHelpApps: GlobalSearchHelpApp[] = runtime.apps
     .filter((app) => (app.searchTags?.length ?? 0) > 0)
@@ -227,6 +213,18 @@ export default function Layout(props: LayoutProps) {
     [appAppearanceStyle(currentApp?.appearance), appWorkspaceLayoutStyle(workspaceLayout), focusMode && flushCanvas ? "padding:0" : ""]
       .filter(Boolean)
       .join(";") || undefined;
+  const appLabel = currentApp?.name ?? (pathname.startsWith("/admin") ? t.admin : undefined);
+  const shellData: ShellData = {
+    apps: allApps,
+    ...(user
+      ? { rail: c.get("railPreferences") ?? defaultRailPreferences(), profile: { name: profileName, avatarSrc: profileAvatarSrc, appHref } }
+      : {}),
+    legalLinks,
+    theme,
+    accent: currentApp?.appearance?.accent,
+    searchLinks,
+    searchHelpApps,
+  };
   if (focusMode) {
     return (
       <LocaleProvider locale={lang}>
@@ -239,10 +237,8 @@ export default function Layout(props: LayoutProps) {
           data-layout-full-page="true"
           data-workspace-sidebar-collapsed={workspaceLayout?.sidebarCollapsed ? "true" : undefined}
         >
-          <TimezoneCookie />
-          {registeredHelp && <RegisteredHelpDocuments documents={registeredHelp.documents} pageBase={registeredHelp.pageBase} />}
+          <ShellRuntime pageTrail help={runtimeHelp} />
           <PageTrailProvider trail={pageTrail}>
-            <PageTrailRuntime />
             <main class="min-h-0 min-w-0 flex-1">
               <AppWorkspace.LayoutStateProvider state={workspaceLayout}>{props.children}</AppWorkspace.LayoutStateProvider>
             </main>
@@ -266,65 +262,40 @@ export default function Layout(props: LayoutProps) {
         data-layout-authenticated={showRail ? "true" : undefined}
         data-workspace-sidebar-collapsed={workspaceLayout?.sidebarCollapsed ? "true" : undefined}
       >
-        <TimezoneCookie />
-        {registeredHelp && <RegisteredHelpDocuments documents={registeredHelp.documents} pageBase={registeredHelp.pageBase} />}
-        <AppWorkspaceController appId={currentApp?.id} />
-        {user && <BrowserPushRegistration />}
-        {showRail && (
-          <LayoutRail
-            accent={currentApp?.appearance?.accent}
-            appHref={appHref}
-            appsLabel={t.apps}
-            homeLabel={t.home}
-            launchpadApps={launchpadApps}
-            legalLinks={legalLinks}
-            openAppsLabel={t.openApps}
-            apps={allApps}
-            railSettings={c.get("railPreferences") ?? defaultRailPreferences()}
-            currentPath={requestPath(c)}
-            profileAvatarSrc={profileAvatarSrc}
-            profileName={profileName}
-            searchHelpApps={searchHelpApps}
-            searchLinks={searchLinks}
-            theme={theme}
-          />
-        )}
-        <div class="layout-shell-content flex min-h-0 min-w-0 flex-1 flex-col">
-          <LayoutHeader
-            appHref={appHref}
-            appLabel={currentApp?.name ?? (pathname.startsWith("/admin") ? t.admin : undefined)}
-            accent={currentApp?.appearance?.accent}
-            authenticated={showRail}
-            breadcrumbs={breadcrumbs}
-            homeLabel={t.home}
-            launchpadApps={launchpadApps}
-            legalLinks={legalLinks}
-            openAppsLabel={t.openApps}
-            profileName={profileName}
-            searchHelpApps={searchHelpApps}
-            searchLinks={searchLinks}
-            signInLabel={t.signIn}
-            theme={theme}
-          />
-          {user && announcements && (
-            <GlobalAnnouncements
-              banners={announcements.banners}
-              announcements={announcements.announcements}
-              latestAnnouncementVersion={announcements.latestAnnouncementVersion}
-              cookieState={announcements.cookieState}
+        <ShellRuntime
+          workspace={{ appId: currentApp?.id }}
+          pageTrail
+          help={runtimeHelp}
+          commands={{ searchResources: !!user }}
+          push={!!user}
+          announcements={
+            user && announcements?.announcements.length
+              ? { entries: announcements.announcements, latestVersion: announcements.latestAnnouncementVersion }
+              : undefined
+          }
+          banners={user && announcements?.banners.length ? true : undefined}
+        />
+        <ShellDataProvider data={shellData}>
+          {showRail && <LayoutRail currentPath={requestPath(c)} />}
+          <div class="layout-shell-content flex min-h-0 min-w-0 flex-1 flex-col">
+            <LayoutHeader
+              authenticated={showRail}
+              title={appLabel ?? breadcrumbs.at(-1)?.title}
+              launchpad={!!(user || appLabel)}
+              breadcrumbs={user ? undefined : breadcrumbs}
             />
-          )}
-          {user && <ProfileWarnings user={user} locale={lang} />}
-          {user && <ExpiryWarnings user={user} dateConfig={dateConfig} locale={lang} />}
-          <PageTrailProvider trail={pageTrail}>
-            <PageTrailRuntime />
-            <PageTrailRow />
-            <main class={`layout-content-main min-h-0 min-w-0 flex-1 ${mainLayoutClass}`}>
-              <AppWorkspace.LayoutStateProvider state={workspaceLayout}>{props.children}</AppWorkspace.LayoutStateProvider>
-            </main>
-          </PageTrailProvider>
-          {!fullPage && !showRail && <LayoutFooter appName={settings?.app?.copyright || appName} legalLinks={legalLinks} />}
-        </div>
+            {user && announcements && <AnnouncementBanners banners={announcements.banners} />}
+            {user && <ProfileWarnings user={user} locale={lang} />}
+            {user && <ExpiryWarnings user={user} dateConfig={dateConfig} locale={lang} />}
+            <PageTrailProvider trail={pageTrail}>
+              <PageTrailRow trail={pageTrail} />
+              <main class={`layout-content-main min-h-0 min-w-0 flex-1 ${mainLayoutClass}`}>
+                <AppWorkspace.LayoutStateProvider state={workspaceLayout}>{props.children}</AppWorkspace.LayoutStateProvider>
+              </main>
+            </PageTrailProvider>
+            {!fullPage && !showRail && <LayoutFooter appName={settings?.app?.copyright || appName} legalLinks={legalLinks} />}
+          </div>
+        </ShellDataProvider>
       </div>
     </LocaleProvider>
   );

package/src/ssr/LayoutHeader.tsx

@@ -1,30 +1,13 @@
-import { ButtonLink, IconButtonLink } from "@k2b/ui";
-import type { NavigationSearchItem } from "../browser/navigation-search";
-import type { CloudTheme } from "../shared/theme";
-import AppLaunchpad, { type AppLaunchpadApp } from "./AppLaunchpad.island";
-import type { GlobalSearchHelpApp } from "./GlobalSearchHelpDialog";
-import GlobalSearchTrigger from "./GlobalSearchTrigger.island";
-import LayoutBreadcrumbs from "./LayoutBreadcrumbs.island";
-import LayoutHelpTrigger from "./LayoutHelpTrigger.island";
-import LayoutPreferences from "./LayoutPreferences.island";
+import { ButtonLink, IconButtonLink, useLocale } from "@k2b/ui";
+import CloudShell from "./CloudShell.island";
 import type { LayoutBreadcrumb } from "./layout-runtime";
+import { platformMessages } from "./platform-messages";
 
 type LayoutHeaderProps = {
-  accent?: string;
-  /** Set while the installation offers the mobile app. */
-  appHref?: string;
-  appLabel?: string;
   authenticated: boolean;
-  breadcrumbs: LayoutBreadcrumb[];
-  homeLabel: string;
-  launchpadApps: AppLaunchpadApp[];
-  legalLinks: Array<{ label: string; href: string; icon?: string }>;
-  openAppsLabel: string;
-  profileName: string;
-  searchHelpApps: GlobalSearchHelpApp[];
-  searchLinks?: NavigationSearchItem[];
-  signInLabel: string;
-  theme: CloudTheme;
+  title?: string;
+  launchpad: boolean;
+  breadcrumbs?: LayoutBreadcrumb[];
 };
 
 /**
@@ -33,68 +16,39 @@ type LayoutHeaderProps = {
  * and their profile through the rail, so the app area starts at the top edge.
  * Anonymous pages have no rail: up to `lg` their header keeps the app name,
  * help, search, and the app grid, and from `lg` it shows the breadcrumbs.
+ * Home and Sign in stay server markup, so focus on them survives the shell's
+ * mount; the shell renders the title and the controls between them.
  */
 export default function LayoutHeader(props: LayoutHeaderProps) {
+  const locale = useLocale();
+  const t = () => platformMessages.resolve([locale()]).t;
   return (
     <header
-      class={`layout-header paper flex min-h-[2.875rem] shrink-0 items-center justify-between px-2 py-1.5 md:px-3 md:py-2 ${props.authenticated ? "md:hidden" : ""}`}
+      class={`layout-header paper flex min-h-[2.875rem] shrink-0 items-center px-2 py-1.5 md:px-3 md:py-2 ${props.authenticated ? "md:hidden" : ""}`}
       style="box-shadow: var(--ui-shadow-surface)"
     >
-      <div class="flex min-w-0 items-center gap-2">
-        {/* A long title must not squeeze the button; `shrink-0` sits on a wrapper because the button's own
-            styles would win over a utility on the link. */}
-        <div class="flex shrink-0">
-          <IconButtonLink href="/" label={props.homeLabel}>
-            <img src="/branding/logo" alt="" class={props.authenticated ? "h-4 w-4" : "h-6 w-6"} />
-          </IconButtonLink>
-        </div>
-        {!props.authenticated && (
-          <div class="hidden min-w-0 items-center lg:flex">
-            <LayoutBreadcrumbs breadcrumbs={props.breadcrumbs} />
-          </div>
-        )}
-        <div class="flex min-w-0 items-center lg:hidden">
-          <span class="truncate font-semibold">{props.appLabel ?? props.breadcrumbs.at(-1)?.title}</span>
-        </div>
+      {/* A long title must not squeeze the button; `shrink-0` sits on a wrapper because the button's own
+          styles would win over a utility on the link. */}
+      <div class="flex shrink-0">
+        <IconButtonLink href="/" label={t().home}>
+          <img src="/branding/logo" alt="" class={props.authenticated ? "h-4 w-4" : "h-6 w-6"} />
+        </IconButtonLink>
       </div>
-      <div class="flex shrink-0 items-center gap-1">
-        <div class="flex items-center gap-1 lg:hidden">
-          <LayoutHelpTrigger
-            variant="header"
-            registerCommand={!props.authenticated}
-            searchHelpApps={props.searchHelpApps}
-            accent={props.accent}
-          />
-          <GlobalSearchTrigger
-            variant={props.authenticated ? "header" : "host"}
-            registerCommand
-            searchLinks={props.searchLinks}
-            searchResources={props.authenticated}
-          />
-          {(props.authenticated || props.appLabel) && (
-            <AppLaunchpad
-              profile={
-                props.authenticated
-                  ? { name: props.profileName, theme: props.theme, ...(props.appHref ? { appHref: props.appHref } : {}) }
-                  : undefined
-              }
-              apps={props.launchpadApps}
-              legalLinks={props.legalLinks}
-              variant="header"
-              label={props.openAppsLabel}
-            />
-          )}
+      <CloudShell
+        slot="header"
+        authenticated={props.authenticated}
+        title={props.title}
+        launchpad={props.launchpad}
+        breadcrumbs={props.breadcrumbs}
+      />
+      {!props.authenticated && (
+        <div class="ml-1 flex shrink-0">
+          <ButtonLink href="/auth/login" size="sm" variant="primary">
+            <i class="ti ti-login" aria-hidden="true" />
+            {t().signIn}
+          </ButtonLink>
         </div>
-        {!props.authenticated && (
-          <>
-            <LayoutPreferences initialTheme={props.theme} position="bottom-left" />
-            <ButtonLink href="/auth/login" size="sm" variant="primary">
-              <i class="ti ti-login" aria-hidden="true" />
-              {props.signInLabel}
-            </ButtonLink>
-          </>
-        )}
-      </div>
+      )}
     </header>
   );
 }

package/src/ssr/LayoutHelp.tsx

@@ -1,29 +1,17 @@
 import type { HelpDocumentManifest, HelpDocumentPayload, HelpSearchPayload } from "@k2b/cloud/shared";
 import { clipboard } from "@k2b/stdlib/solid";
 import { Button, IconButton, IconButtonLink, MarkdownView, NoticeCard, Placeholder, prompts, ScrollArea, useLocale } from "@k2b/ui";
-import { createEffect, createMemo, createSignal, For, type JSX, onCleanup, onMount, Show } from "solid-js";
+import { createEffect, createMemo, createSignal, For, onCleanup, onMount, Show } from "solid-js";
 import { COMMANDS_CHANGED, contextCommandsWithShortcuts, shortcutLabel } from "../browser/command-shortcuts";
 import { appAccentStyle } from "./app-appearance";
 import { type GlobalSearchHelpApp, openGlobalSearchHelpDialog } from "./GlobalSearchHelpDialog";
 import { helpMessages } from "./help-messages";
 import { formatHelpBundleMarkdown, formatHelpDocumentMarkdown } from "./layout-help-markdown";
 import { adjacentHelpDocuments, focusHelpArticleHeading, resetHelpArticleScroll } from "./layout-help-navigation";
+import { HELP_TOPICS_EVENT, type HelpTopic, registry } from "./layout-help-registry";
 import { searchHelpTopics } from "./layout-help-search";
 import { layoutHelpTopicHref } from "./layout-help-url";
 
-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 LayoutHelpPageProps = {
   documents: readonly HelpDocumentManifest[];
   initialTopic?: string;
@@ -35,7 +23,6 @@ export type LayoutHelpPageProps = {
   pageBase?: string;
 };
 
-type HelpTopic = (HelpTopicBase & { kind: "content"; children: JSX.Element }) | (HelpDocumentManifest & { kind: "document" });
 type HelpView = "hub" | "search" | "article";
 type HelpSession = {
   view: HelpView;
@@ -51,23 +38,8 @@ type HelpSection = {
   title: string;
 };
 
-const HELP_TOPICS_EVENT = "cloud:layout-help-topics";
 const LAST_TOPIC_KEY = "cloud.layoutHelp.activeTopic";
 
-declare global {
-  interface Window {
-    __cloudLayoutHelpTopics?: Map<string, HelpTopic>;
-    __cloudLayoutHelpPageBase?: string;
-  }
-}
-
-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 iconClass = (icon?: string) => (icon?.startsWith("ti ") ? icon : `ti ${icon ?? "ti-circle"}`);
 const legacyTopicContent = (topic: HelpTopic) => (topic.kind === "content" ? topic.children : null);
 const sortedTopics = () =>
@@ -80,33 +52,6 @@ const mergeTopics = (registered: readonly HelpTopic[], documents: readonly HelpD
   return [...topics.values()].sort((a, b) => (a.order ?? 100) - (b.order ?? 100) || a.title.localeCompare(b.title));
 };
 
-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;
-}
-
 const Shortcuts = (props: { openSearchHelp: () => void }) => {
   const locale = useLocale();
   const t = () => helpMessages.resolve([locale()]).t;

package/src/ssr/LayoutHelpTrigger.tsx

@@ -0,0 +1,51 @@
+import { IconButton, Tooltip, useLocale } from "@k2b/ui";
+import { importOnDemand } from "../browser/reload";
+import { createBusyAction } from "./busy-action";
+import { platformMessages } from "./platform-messages";
+import { useShellData } from "./shell-data";
+
+type LayoutHelpTriggerProps = {
+  variant: "header" | "rail";
+  class?: string;
+};
+
+/** Opens end-user help from either the desktop rail or the compact header. */
+export default function LayoutHelpTrigger(props: LayoutHelpTriggerProps) {
+  const locale = useLocale();
+  const t = () => platformMessages.resolve([locale()]).t;
+  const data = useShellData();
+  const action = createBusyAction();
+  const openHelp = () =>
+    action.run(
+      () => importOnDemand(() => import("./LayoutHelp")),
+      (help) => help.openLayoutHelpDialog(data?.searchHelpApps ?? [], data?.accent),
+    );
+
+  if (props.variant === "rail")
+    return (
+      <Tooltip.Trigger
+        type="button"
+        class={`rail-item text-blue-500 hover:bg-blue-500/10 hover:text-blue-600 dark:text-blue-400 dark:hover:bg-blue-500/15 dark:hover:text-blue-300 ${props.class ?? ""}`}
+        onClick={openHelp}
+        aria-busy={action.busy() ? "true" : undefined}
+        aria-label={t().openHelp}
+        placement="right"
+        delay={0}
+        content={t().helpShortcut}
+      >
+        <i class={`${action.busy() ? "ti ti-loader-2 animate-spin" : "ti ti-help-circle"} text-base`} />
+      </Tooltip.Trigger>
+    );
+
+  return (
+    <IconButton
+      class={props.class}
+      onClick={openHelp}
+      aria-busy={action.busy() ? "true" : undefined}
+      label={t().openHelp}
+      title={t().helpShortcut}
+    >
+      <i class={`${action.busy() ? "ti ti-loader-2 animate-spin" : "ti ti-help-circle"} text-base`} />
+    </IconButton>
+  );
+}