@k2b/cloud 0.32.0 → 0.34.0

package/src/services/pwa-devices.ts

@@ -1,6 +1,7 @@
 import { timingSafeEqual } from "node:crypto";
 import { type SQL, sql } from "bun";
 import type { Context } from "hono";
+import { lazySync } from "../_internal/process-sync";
 import { PWA_LIMITS as limits, type PwaDeviceView, type PwaErrorCode, type PwaPairingState, type PwaPlatform } from "../contracts/pwa";
 import { isAccountCategoryAllowed } from "./account-category-policy";
 import { audit } from "./audit";
@@ -30,6 +31,13 @@ const fail = (code: PwaErrorCode, status: PwaError["status"], attemptsLeft?: num
 
 /** The initiating web session of a pairing. */
 export type PwaWebActor = { userId: string; sid: string };
+/** Best-effort wake-ups for browsers waiting on a pairing claim. Postgres stays authoritative. */
+export type PwaPairingClaimHints = {
+  /** Call after the claim commits. Must not throw or delay the caller. */
+  publish(pairingId: string): void;
+  /** Settles on the first hint for this pairing, or when `signal` aborts. */
+  wait(pairingId: string, signal: AbortSignal): Promise<void>;
+};
 /** Administration of another account's phones needs current admin authority. */
 export type PwaDeviceAdministrator = { userId: string; admin: boolean };
 export type PwaRevocationReason = "user" | "unpaired" | "admin" | "replaced" | "account_expired";
@@ -87,6 +95,25 @@ type UserRow = {
 };
 
 const log = logger("pwa-devices");
+const claimTopic = lazySync((sync) =>
+  sync.topic<null>({
+    id: "cloud:pwa-pairing-claims",
+    owner: "cloud",
+    retention: { maxAgeMs: 120_000, maxBytes: 1_048_576 },
+    maxPayloadBytes: 2000,
+  }),
+);
+/** Core NATS broadcast reaches the waiting browser on any replica. */
+export const syncPairingClaimHints: PwaPairingClaimHints = {
+  publish: (pairingId) => {
+    void Promise.resolve()
+      .then(() => claimTopic().publish({ tenantId: pairingId, data: null }))
+      .catch((error) => log.warn("App pairing claim hint failed", { error: error instanceof Error ? error.name : "UnknownError" }));
+  },
+  wait: async (pairingId, signal) => {
+    for await (const _event of claimTopic().live({ tenantId: pairingId, signal })) return;
+  },
+};
 const iso = (value: Date | string) => new Date(value).toISOString();
 const passed = (value: Date | string) => new Date(value).getTime() <= Date.now();
 const DEVICE_KEY = /^([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.([A-Za-z0-9_-]{43})$/;
@@ -243,7 +270,7 @@ export type PwaCompletion =
   | { state: "paired"; credentials: PwaCredentials | null; platform: PwaPlatform }
   | { state: "waiting"; code: string; account: { name: string }; expiresAt: string };
 
-export const createPwaDeviceService = () => {
+export const createPwaDeviceService = (hints: PwaPairingClaimHints = syncPairingClaimHints) => {
   const appSession = (deviceId: string) => ({ ttlSeconds: limits.sessionSeconds, pwaDeviceId: deviceId, recordLogin: false });
 
   /**
@@ -334,21 +361,46 @@ export const createPwaDeviceService = () => {
     },
 
     /** Never returns the code: the person types what the phone shows. */
-    inspectPairing: async (actor: PwaWebActor, id: string) => {
-      const [p] = await sql<(PairingRow & { current_epoch: string })[]>`
-        SELECT p.*, u.auth_epoch AS current_epoch FROM auth.pwa_pairings p JOIN auth.users u ON u.id = p.user_id
-        WHERE p.id = ${id}::uuid AND p.user_id = ${actor.userId}::uuid AND p.initiator_sid = ${actor.sid}::uuid
-      `;
-      if (!p) return fail("NOT_FOUND", 404);
-      if (passed(p.expires_at) || p.current_epoch !== p.auth_epoch || (p.state === "pending" && passed(p.claim_until)))
-        return fail("EXPIRED", 410);
-      return {
-        state: p.state,
-        claimUntil: iso(p.claim_until),
-        expiresAt: iso(p.expires_at),
-        device: p.state === "pending" || !p.device_name || !p.platform ? null : { name: p.device_name, platform: p.platform },
-        attemptsLeft: Math.max(0, limits.confirmAttempts - p.failed_attempts),
+    inspectPairing: async (actor: PwaWebActor, id: string, hold?: { ms: number; signal?: AbortSignal }) => {
+      const read = async (validateInitiator = false) => {
+        const [p] = await sql<(PairingRow & { current_epoch: string })[]>`
+          SELECT p.*, u.auth_epoch AS current_epoch FROM auth.pwa_pairings p JOIN auth.users u ON u.id = p.user_id
+          WHERE p.id = ${id}::uuid AND p.user_id = ${actor.userId}::uuid AND p.initiator_sid = ${actor.sid}::uuid
+        `;
+        if (!p) return fail("NOT_FOUND", 404);
+        if (passed(p.expires_at) || p.current_epoch !== p.auth_epoch || (p.state === "pending" && passed(p.claim_until)))
+          return fail("EXPIRED", 410);
+        if (validateInitiator && !(await initiatorValid(sql, p))) return fail("EXPIRED", 410);
+        return {
+          state: p.state,
+          claimUntil: iso(p.claim_until),
+          expiresAt: iso(p.expires_at),
+          device: p.state === "pending" || !p.device_name || !p.platform ? null : { name: p.device_name, platform: p.platform },
+          attemptsLeft: Math.max(0, limits.confirmAttempts - p.failed_attempts),
+        };
       };
+      if (!hold) return read();
+      // Listen before the first read so a claim committed in between usually wakes this request.
+      // live() has no subscription-ready barrier, so the hint is best effort; the deadline re-read is the guarantee.
+      // The read after the hold also checks the initiating web session, which may have ended meanwhile.
+      const waiting = new AbortController();
+      const ended = new Promise((resolve) => waiting.signal.addEventListener("abort", resolve, { once: true }));
+      const stop = () => waiting.abort();
+      hold.signal?.addEventListener("abort", stop, { once: true });
+      if (hold.signal?.aborted) stop();
+      const hint = hints.wait(id, waiting.signal).catch(() => {});
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        const first = await read();
+        if (first.state !== "pending") return first;
+        timer = setTimeout(stop, Math.min(hold.ms, new Date(first.claimUntil).getTime() - Date.now()));
+        await Promise.race([hint, ended]);
+        return await read(true);
+      } finally {
+        clearTimeout(timer);
+        hold.signal?.removeEventListener("abort", stop);
+        stop();
+      }
     },
 
     confirmPairing: async (actor: PwaWebActor, id: string, code: string) => {
@@ -438,6 +490,7 @@ export const createPwaDeviceService = () => {
           WHERE id = ${p.id}::uuid`;
         return { account: { name: accountName(user) }, expiresAt: p.expires_at };
       });
+      hints.publish(snapshot.id);
       return { code, account: result.account, expiresAt: iso(result.expiresAt), completionSecret };
     },
 

package/src/shared/ai-platform-prompt.ts

@@ -105,10 +105,11 @@ Use the conversation file tools for this chat's files: the user's uploads are re
 {%- if memoryEnabled %}
 
 # Personalization rules
-Use the dated facts, preferences, and workflow defaults at the end naturally and judge how current they are. A workflow default may select a likely Cloud resource, but never grants access; resolve it through the current authorized capability before use.
+Apply the dated facts, preferences, and workflow defaults at the end only when one changes the answer, and judge how current it is. Do not mention or recite them unless the user asks or one is directly relevant. The current message wins over a conflicting memory. A workflow default may select a likely Cloud resource, but never grants access; resolve it through the current authorized capability before use.
 {%- if memoryToolEnabled %}
 - When the user explicitly asks you to remember or forget something, or clearly frames a lasting preference with phrases such as "from now on", "always", or "never", call memory before replying.
-- Without a direct request, save only a fact or preference the user clearly stated that is durable and likely useful in future conversations.
+- These limits apply to explicit requests too: never save facts, opinions, or health, relationship, or behavior details about other people, except a named person inside a working rule the user stated. Say what you did not save and offer Contacts or the Project instead.
+- Without a direct request, save only a fact or preference the user clearly stated about themselves that is durable and likely useful in future conversations.
 - Search before correcting an entry whose id is unknown, update contradictions instead of adding duplicates, and delete wrong or explicitly forgotten memories.
 - Say you remembered, noted, or forgot something only after the corresponding memory call succeeded.
 {%- endif %}

package/src/shared/app-presentation.ts

@@ -26,7 +26,22 @@ const mergedTranslation = (catalog: AppPresentationCatalog, requestedLocale: str
       widgets: Object.fromEntries(
         [...new Set([...Object.keys(current.widgets ?? {}), ...Object.keys(next.widgets ?? {})])].map((id) => [
           id,
-          { ...current.widgets?.[id], ...next.widgets?.[id] },
+          {
+            ...current.widgets?.[id],
+            ...next.widgets?.[id],
+            settings: Object.fromEntries(
+              [...new Set([...Object.keys(current.widgets?.[id]?.settings ?? {}), ...Object.keys(next.widgets?.[id]?.settings ?? {})])].map(
+                (name) => [
+                  name,
+                  {
+                    ...current.widgets?.[id]?.settings?.[name],
+                    ...next.widgets?.[id]?.settings?.[name],
+                    options: { ...current.widgets?.[id]?.settings?.[name]?.options, ...next.widgets?.[id]?.settings?.[name]?.options },
+                  },
+                ],
+              ),
+            ),
+          },
         ]),
       ),
     };
@@ -65,6 +80,39 @@ export const resolveAppPresentation = <T extends AppMeta>(app: T, requestedLocal
       ...widget,
       title: translation.widgets?.[widget.id]?.title ?? widget.title,
       description: translation.widgets?.[widget.id]?.description ?? widget.description,
+      ...(widget.settings && typeof widget.settings === "object" && !Array.isArray(widget.settings)
+        ? {
+            settings: Object.fromEntries(
+              Object.entries(widget.settings).map(([name, field]) => {
+                if (!field || typeof field !== "object") return [name, field];
+                const translated = translation.widgets?.[widget.id]?.settings?.[name];
+                return [
+                  name,
+                  {
+                    ...field,
+                    label: translated?.label ?? field.label,
+                    ...(field.kind === "text" ? { placeholder: translated?.placeholder ?? field.placeholder } : {}),
+                    ...(field.kind === "choice" && Array.isArray(field.options)
+                      ? {
+                          options: field.options.map((option) =>
+                            option && typeof option === "object"
+                              ? {
+                                  ...option,
+                                  label:
+                                    translated?.options && Object.hasOwn(translated.options, option.value)
+                                      ? (translated.options[option.value] ?? option.label)
+                                      : option.label,
+                                }
+                              : option,
+                          ),
+                        }
+                      : {}),
+                  },
+                ];
+              }),
+            ),
+          }
+        : {}),
     })),
   };
 };

package/src/shared/index.ts

@@ -44,6 +44,7 @@ export * from "./locale";
 export * from "./locale-preference";
 export * from "./login-method";
 export { markdown } from "./markdown";
+export { markdownCalloutSanitizeOptions } from "./markdown/callout-sanitizer";
 export type { ErrorCode, EvalContext, EvalError, EvalResult, EvalValue, ProgressValue } from "./markdown/formula";
 export { createProgressValue, evaluateFormula, formatValue, isFormula, isTotalRow, parseProgressValue } from "./markdown/formula";
 export type { MockCover, MockCoverIcon, MockCoverOptions, MockCoverTheme } from "./mock-cover";

package/src/shared/markdown/callout-sanitizer.ts

@@ -0,0 +1,37 @@
+import { MARKDOWN_CALLOUT_ICON_ATTRIBUTES } from "@k2b/ui";
+import type sanitizeHtml from "sanitize-html";
+
+/** Fresh sanitize-html options for one document: SVG is limited to fixed callout icons. */
+export const markdownCalloutSanitizeOptions = () => {
+  const elements: { inIcon: boolean; discard: boolean }[] = [];
+  let closed: { inIcon: boolean; discard: boolean } | undefined;
+  return {
+    allowedTags: ["svg", "path"],
+    allowedAttributes: { svg: Object.keys(MARKDOWN_CALLOUT_ICON_ATTRIBUTES), path: ["d"] },
+    // onOpenTag sees raw attributes before transforms; discarded SVG must keep ordinary HTML and text.
+    onOpenTag: (tag, attrs) => {
+      const parent = elements.at(-1);
+      elements.push({
+        inIcon: !!parent?.inIcon || (tag === "svg" && attrs.class === MARKDOWN_CALLOUT_ICON_ATTRIBUTES.class),
+        discard: !!parent?.discard || (!!parent?.inIcon && tag !== "path"),
+      });
+    },
+    // sanitize-html closes a tag before calling exclusiveFilter for that element.
+    onCloseTag: () => {
+      closed = elements.pop();
+    },
+    // excludeTag preserves ordinary content, including after an unclosed author SVG.
+    exclusiveFilter: ({ tag }) => closed?.discard || ((tag === "svg" || tag === "path") && !closed?.inIcon ? "excludeTag" : false),
+    textFilter: (text) => (elements.at(-1)?.inIcon ? "" : text),
+    transformTags: {
+      svg: (tagName) => ({
+        tagName,
+        attribs: { ...MARKDOWN_CALLOUT_ICON_ATTRIBUTES },
+      }),
+      path: (tagName, attrs) => ({
+        tagName,
+        attribs: Object.fromEntries(Object.entries(attrs).filter(([name]) => name === "d")),
+      }),
+    },
+  } satisfies sanitizeHtml.IOptions;
+};

package/src/shared/markdown/index.ts

@@ -8,6 +8,7 @@
 import { markdownInfoBlocks } from "@k2b/ui";
 import { Marked, type MarkedExtension } from "marked";
 import sanitizeHtml from "sanitize-html";
+import { markdownCalloutSanitizeOptions } from "./callout-sanitizer";
 import { markdownClient } from "./client";
 import { codeExtension, plainCodeExtension } from "./extensions/code";
 import { guidedHelpExtension } from "./extensions/guided-help";
@@ -73,8 +74,10 @@ export type MarkdownRenderOptions = {
   locale?: string;
 };
 
-const sanitizeRenderedHtml = (html: string): string =>
-  sanitizeHtml(html, {
+const sanitizeRenderedHtml = (html: string): string => {
+  const callouts = markdownCalloutSanitizeOptions();
+  return sanitizeHtml(html, {
+    ...callouts,
     allowedTags: [
       ...sanitizeHtml.defaults.allowedTags,
       "annotation",
@@ -101,6 +104,7 @@ const sanitizeRenderedHtml = (html: string): string =>
       "mtext",
       "semantics",
       "span",
+      ...callouts.allowedTags,
       "sub",
       "sup",
       "table",
@@ -129,6 +133,7 @@ const sanitizeRenderedHtml = (html: string): string =>
       input: ["checked", "class", "disabled", "type"],
       math: ["xmlns"],
       pre: ["class"],
+      ...callouts.allowedAttributes,
       span: ["aria-hidden", "class", "style", "title"],
     },
     allowedSchemes: ["http", "https", "mailto", "tel", "note", "attach"],
@@ -150,6 +155,7 @@ const sanitizeRenderedHtml = (html: string): string =>
       },
     },
   });
+};
 
 /**
  * Render markdown to HTML for server-side display.

package/src/shared/theme.ts

@@ -1,10 +1,13 @@
 export type CloudTheme = "light" | "dark";
+export type CloudThemePreference = CloudTheme | "system";
 
 const THEME_COOKIE = "theme";
 const COOKIE_MAX_AGE_SECONDS = 31536000;
 
 const isCloudTheme = (value: string): value is CloudTheme => value === "light" || value === "dark";
 
+const isCloudThemePreference = (value: string): value is CloudThemePreference => isCloudTheme(value) || value === "system";
+
 const decodeCookieValue = (value: string): string => {
   try {
     return decodeURIComponent(value);
@@ -13,28 +16,44 @@ const decodeCookieValue = (value: string): string => {
   }
 };
 
-/**
- * Resolve the persisted theme from a Cookie header.
- *
- * Browsers can send duplicate cookie names when legacy path-specific cookies
- * exist. RFC ordering puts more specific paths first, so the root preference
- * written by the current app is usually the last valid `theme` entry.
- */
-export const readThemeFromCookieHeader = (cookieHeader: string | null | undefined): CloudTheme => {
-  let resolved: CloudTheme = "light";
+/** More specific legacy paths arrive first; the root choice is the last valid entry. */
+const readCookieValue = <T extends string>(
+  cookieHeader: string | null | undefined,
+  name: string,
+  valid: (value: string) => value is T,
+): T | undefined => {
+  let result: T | undefined;
   for (const part of (cookieHeader ?? "").split(";")) {
     const trimmed = part.trim();
     const separatorIndex = trimmed.indexOf("=");
-    if (separatorIndex <= 0) continue;
-    if (trimmed.slice(0, separatorIndex) !== THEME_COOKIE) continue;
-
+    if (separatorIndex <= 0 || trimmed.slice(0, separatorIndex) !== name) continue;
     const value = decodeCookieValue(trimmed.slice(separatorIndex + 1));
-    if (isCloudTheme(value)) resolved = value;
+    if (valid(value)) result = value;
   }
-  return resolved;
+  return result;
 };
 
-export const themeBootstrapScript = `!function(){var e=document.documentElement;if(!e.hasAttribute("data-theme-fixed")){var t="light";document.cookie.split(";").forEach(function(e){var r=e.trim(),i=r.indexOf("=");if(i>0&&r.slice(0,i)==="theme"){var o;try{o=decodeURIComponent(r.slice(i+1))}catch(e){o=r.slice(i+1)}(o==="light"||o==="dark")&&(t=o)}});e.classList.remove("light","dark");e.classList.add(t)}}();`;
+/** The person's choice; a missing or invalid cookie means Automatic (`system`). */
+export const readThemePreferenceFromCookieHeader = (cookieHeader: string | null | undefined): CloudThemePreference =>
+  readCookieValue(cookieHeader, THEME_COOKIE, isCloudThemePreference) ?? "system";
+
+/**
+ * The resolved theme for server work such as the AI code runtime. For
+ * Automatic it is the scheme the browser last reported; browser code reads the
+ * `<html>` class instead.
+ */
+export const readThemeFromCookieHeader = (cookieHeader: string | null | undefined): CloudTheme => {
+  const preference = readThemePreferenceFromCookieHeader(cookieHeader);
+  return preference === "system" ? (readCookieValue(cookieHeader, "color-scheme", isCloudTheme) ?? "light") : preference;
+};
+
+/**
+ * Resolves the `<html>` class before first paint, because only the browser
+ * knows the device scheme, and follows scheme changes live. It also reports
+ * the scheme in the `color-scheme` cookie for the server. A constant, so a CSP
+ * hash of it stays valid.
+ */
+export const themeBootstrapScript = `!function(){var e=document.documentElement;if(e.hasAttribute("data-theme-fixed"))return;var m=matchMedia("(prefers-color-scheme: dark)");function r(n,s){var v;document.cookie.split(";").forEach(function(p){p=p.trim();var i=p.indexOf("=");if(i>0&&p.slice(0,i)===n){var t=p.slice(i+1);try{t=decodeURIComponent(t)}catch(e){}if(t==="light"||t==="dark"||s&&t==="system")v=t}});return v}function a(){var s=m.matches?"dark":"light";if(r("color-scheme")!==s)document.cookie="color-scheme="+s+"; path=/; max-age=31536000; SameSite=Lax"+(location.protocol==="https:"?"; Secure":"");var p=r("theme",true)||"system";e.classList.remove("light","dark");e.classList.add(p==="system"?s:p)}a();m.addEventListener("change",function(){a();window.dispatchEvent(new Event("cloud:theme-preference"))})}();`;
 
 const legacyThemeCookiePaths = (pathname: string): string[] => {
   const paths = new Set(["/", "/me", "/app", "/admin"]);
@@ -48,11 +67,13 @@ const legacyThemeCookiePaths = (pathname: string): string[] => {
   return [...paths];
 };
 
-export const setThemePreference = (mode: CloudTheme): CloudTheme => {
+export const setThemePreference = (mode: CloudThemePreference): CloudThemePreference => {
   if (typeof document === "undefined") return mode;
 
   document.documentElement.classList.remove("light", "dark");
-  document.documentElement.classList.add(mode);
+  document.documentElement.classList.add(
+    mode === "system" ? (window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light") : mode,
+  );
 
   const secure = location.protocol === "https:" ? "; Secure" : "";
   for (const path of legacyThemeCookiePaths(location.pathname)) {
@@ -62,7 +83,7 @@ export const setThemePreference = (mode: CloudTheme): CloudTheme => {
   return mode;
 };
 
-export const getCurrentThemePreference = (): CloudTheme => {
-  if (typeof document === "undefined") return "light";
-  return document.documentElement.classList.contains("dark") ? "dark" : "light";
+export const getCurrentThemePreference = (): CloudThemePreference => {
+  if (typeof document === "undefined") return "system";
+  return readThemePreferenceFromCookieHeader(document.cookie);
 };

package/src/ssr/AnnouncementBanners.tsx

@@ -0,0 +1,30 @@
+import { IconButton, MarkdownView, NoticeCard, useLocale } from "@k2b/ui";
+import { For } from "solid-js";
+import type { AnnouncementDisplayEntry } from "../contracts/announcements";
+import { platformMessages } from "./platform-messages";
+
+export default function AnnouncementBanners(props: { banners: AnnouncementDisplayEntry[] }) {
+  const locale = useLocale();
+  const t = () => platformMessages.resolve([locale()]).t;
+  if (props.banners.length === 0) return null;
+  return (
+    <div class="flex shrink-0 flex-col gap-1">
+      <For each={props.banners}>
+        {(banner) => (
+          <div class="cloud-announcement">
+            <NoticeCard tone={banner.tone} title={banner.title}>
+              <MarkdownView
+                trustedHtml={banner.bodyHtml}
+                headingScale="compact"
+                class="-mx-2 max-h-36 overflow-y-auto overscroll-contain pl-2 pr-3 [&_p]:my-0"
+              />
+            </NoticeCard>
+            <IconButton size="sm" label={t().dismissBanner} data-cloud-announcement-dismiss={banner.version}>
+              <i class="ti ti-x" aria-hidden="true" />
+            </IconButton>
+          </div>
+        )}
+      </For>
+    </div>
+  );
+}

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>
+  );
+}