@k2b/cloud 0.38.0 → 0.39.0

package/src/services/settings/store.ts

@@ -1,7 +1,7 @@
 /**
  * Settings store — Redis cache-aside read/write primitives.
  *
- * Pattern: each key is cached in Redis with a 5-minute TTL. Reads try Redis
+ * Pattern: each key is cached in Redis with a 5-minute TTL. Value reads try Redis
  * first, fall back to DB on miss, and populate Redis. Writes update DB and
  * delete the Redis key (next reader repopulates with fresh DB state).
  *
@@ -27,6 +27,19 @@ const REDIS_KEY = (k: string) => `settings:${k}`;
 
 type SqlClient = typeof sql;
 
+export type StoredSettingState = "none" | "readable" | "unreadable";
+export type SettingRead = { value: unknown; stored: StoredSettingState };
+
+export class SettingUnreadableError extends HTTPException {
+  readonly code = "setting_unreadable" as const;
+
+  constructor(readonly key: string) {
+    const message = `The stored value of setting "${key}" cannot be read by this application. Replace it with a new value or reset it to the default.`;
+    super(409, { message, res: Response.json({ code: "setting_unreadable", message }, { status: 409 }) });
+    this.name = "SettingUnreadableError";
+  }
+}
+
 /**
  * Forget cached values so every container re-reads on next access.
  *
@@ -70,6 +83,12 @@ const resolveFallback = (def: SettingDef | undefined): unknown => {
  */
 export const readKey = async (key: string): Promise<unknown> => (await bulkRead([key])).get(key);
 
+export const readKeyState = async (key: string): Promise<SettingRead> => {
+  const state = (await readStates([key])).get(key);
+  if (!state) throw new Error(`Missing read state for setting "${key}"`);
+  return state;
+};
+
 /** One warm MGET; missing rows are cached independently of local env/defaults. */
 export const bulkRead = async (keys: readonly string[]): Promise<Map<string, unknown>> => {
   const result = new Map<string, unknown>();
@@ -131,6 +150,32 @@ export const bulkRead = async (keys: readonly string[]): Promise<Map<string, unk
   return result;
 };
 
+/**
+ * Stored state is per process (APP_SECRET), but the plaintext cache is shared.
+ * State reads go directly to Postgres without reading or filling the cache;
+ * value reads (`get`, snapshot) keep using the cache.
+ */
+export const readStates = async (keys: readonly string[]): Promise<Map<string, SettingRead>> => {
+  const result = new Map<string, SettingRead>();
+  if (keys.length === 0) return result;
+  const rows = await sql<StoredRow[]>`SELECT key, value FROM settings.entries WHERE key = ANY(${toPgTextArray([...keys])}::text[])`;
+  const byKey = new Map(rows.map((row) => [row.key, row]));
+  for (const key of keys) {
+    const row = byKey.get(key);
+    const def = SETTINGS_MAP.get(key);
+    result.set(key, { stored: row ? "unreadable" : "none", value: resolveFallback(def) });
+    if (!row) continue;
+    try {
+      const value = await decryptValue(row.value);
+      const validated = def ? validateSettingValue(def, value) : { ok: true as const, value };
+      if (validated.ok) result.set(key, { stored: "readable", value: validated.value });
+    } catch {
+      // Keep this process's fallback without changing the stored row or cache.
+    }
+  }
+  return result;
+};
+
 /**
  * Get every known setting key (across all registered defs).
  * Used by snapshot loader to determine what to bulk-read.
@@ -184,11 +229,12 @@ export const deleteLegacyKeys = async (extraKnownKeys: readonly string[] = []):
 /**
  * Encrypt the value, upsert the DB row, invalidate the Redis key.
  *
- * Validation is the caller's responsibility — the typed wrapper API
- * (createSettingsAPI) validates against the declared SettingDef before reaching
- * here. Direct callers must ensure the value matches the setting's kind.
+ * Validate new values and refuse to overwrite unreadable stored rows unless
+ * the caller explicitly replaces them. The row check and write share a transaction.
+ * Lock with a no-op UPDATE so ROW EXCLUSIVE is acquired before the row lock,
+ * preserving lock order with table-level SHARE locks (#1303 review).
  */
-export const writeKey = async (key: string, value: unknown, db?: SqlClient): Promise<void> => {
+export const writeKey = async (key: string, value: unknown, db?: SqlClient, options?: { replaceUnreadable?: boolean }): Promise<void> => {
   const def = SETTINGS_MAP.get(key);
   if (!def) throw new Error(`Unknown setting: ${key}`);
   const validated = validateSettingValue(def, value);
@@ -197,12 +243,38 @@ export const writeKey = async (key: string, value: unknown, db?: SqlClient): Pro
   const storedValue =
     def.kind === "image" && typeof validated.value === "string" ? stripImageDataUrlMetadata(validated.value) : validated.value;
   const encrypted = await encryptValue(storedValue);
-  await (db ?? sql)`
-    INSERT INTO settings.entries (key, value, updated_at)
-    VALUES (${key}, ${encrypted}, now())
-    ON CONFLICT (key)
-    DO UPDATE SET value = ${encrypted}, updated_at = now()
-  `;
+  const write = async (tx: SqlClient) => {
+    for (let attempt = 0; attempt < 3; attempt++) {
+      let [row] = await tx<{ value: string }[]>`UPDATE settings.entries SET value = value WHERE key = ${key} RETURNING value`;
+      if (!row) {
+        const inserted = await tx<{ key: string }[]>`
+          INSERT INTO settings.entries (key, value, updated_at)
+          VALUES (${key}, ${encrypted}, now())
+          ON CONFLICT (key) DO NOTHING RETURNING key
+        `;
+        if (inserted.length > 0) return;
+        // A concurrent insert can win after the missing-row read; lock and check its value before updating.
+        [row] = await tx<{ value: string }[]>`UPDATE settings.entries SET value = value WHERE key = ${key} RETURNING value`;
+        if (!row) continue;
+      }
+      if (options?.replaceUnreadable !== true) {
+        let readable = false;
+        try {
+          readable = validateSettingValue(def, await decryptValue(row.value)).ok;
+        } catch {
+          // Only the key is exposed by the recovery error.
+        }
+        if (!readable) throw new SettingUnreadableError(key);
+      }
+      await tx`
+        UPDATE settings.entries SET value = ${encrypted}, updated_at = now() WHERE key = ${key}
+      `;
+      return;
+    }
+    throw new Error(`Could not write setting "${key}" after 3 attempts`);
+  };
+  if (db) await write(db);
+  else await sql.begin(write);
 
   // Passing a transaction means the caller owns invalidation, because the row
   // is not visible to anyone else until they commit.

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

@@ -59,7 +59,7 @@ Most replies need no offer. Make at most one offer, in the last sentence of the
 {%- if memoryToolEnabled %}
 - The user corrected the tone of a result, such as a mail that is too formal, without stating a lasting rule: offer to remember it as their preference. Memory keeps only the user's own words, so a plain yes cannot be saved: suggest a one-line rule they can send back, such as "Always write mails casually and briefly".
 {%- endif %}
-- The user says the request recurs (again, every week, like last time, always), pastes a long reusable instruction, or a workflow default covers it: offer to save it as a {% if skillOffers %}Skill or {% endif %}scheduled task.
+- The user says the request recurs (again, every week, like last time, always), pastes a long reusable instruction, or a workflow default covers it: offer to save it as a {% if skillOffers %}Skill or {% endif %}routine.
 - A concrete next step clearly saves the user real work they may not know you can do: offer it, such as a manual follow-up the user mentioned, drafting the reply, or turning findings into Space tasks.
 Offer only what the Skills, tool hints, and apps in this prompt support. Do not search mail, chats, or other data only to justify an offer, and do not claim how often something happened unless the user said it or this chat shows it. Do not start the offered work until the user agrees.
 {%- if skillOffers %}

package/src/shared/app-presentation.ts

@@ -65,6 +65,7 @@ export const resolveAppPresentation = <T extends AppMeta>(app: T, requestedLocal
   return {
     ...app,
     ...resolveAppIdentityPresentation(app, requestedLocale),
+    ...(app.panel ? { panel: { ...app.panel, label: translation.panelLabel ?? app.panel.label } } : {}),
     adminNav: app.adminNav?.map((group) => ({
       ...group,
       label: (group.id && translation.adminGroups?.[group.id]) || group.label,

package/src/shared/redirect.ts

@@ -17,6 +17,18 @@ export const normalizeRedirectTo = (value: string | null | undefined): string |
   }
 };
 
+/** Default landing page when no valid home path is configured. */
+export const DEFAULT_HOME_PATH = "/app/dashboard";
+
+/** Resolve a local home path, falling back for root, auth, admin, or invalid targets. */
+export const resolveHomePath = (value: unknown): string => {
+  const path = typeof value === "string" ? normalizeRedirectTo(value) : undefined;
+  if (!path || path === "/" || path === "/auth" || path.startsWith("/auth/") || path === "/admin" || path.startsWith("/admin/")) {
+    return DEFAULT_HOME_PATH;
+  }
+  return path;
+};
+
 /** Extract a safe post-login redirect target from an incoming request URL. */
 export const redirectPathFromRequestUrl = (requestUrl: string): string => {
   const url = new URL(requestUrl);

package/src/ssr/CloudShell.island.tsx

@@ -1,30 +1,85 @@
-import { useLocale } from "@k2b/ui";
-import { createEffect } from "solid-js";
+import { TabBar, useLocale } from "@k2b/ui";
+import { createEffect, createMemo, createSignal, onCleanup, onMount, Show } from "solid-js";
+import { isServer, Portal } from "solid-js/web";
 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 PanelTrigger from "./PanelTrigger";
 import ProfilePreferences from "./ProfilePreferences";
 import { platformMessages } from "./platform-messages";
 import RailApps from "./RailApps";
+import { RAIL_PREFERENCES_EVENT, readRailContext } from "./rail-context";
+import { phoneBarItems, projectRailNavigation } from "./rail-navigation";
 import ShellFocusToggle from "./ShellFocusToggle";
 import { useShellData } from "./shell-data";
 
 type CloudShellProps =
-  | { slot: "rail"; currentPath: string }
-  | { slot: "header"; authenticated: boolean; title?: string; launchpad: boolean; breadcrumbs?: LayoutBreadcrumb[] };
+  | { slot: "rail"; currentPath: string; panelOpen?: boolean }
+  | { slot: "header"; authenticated: boolean; title?: string; launchpad: boolean; breadcrumbs?: LayoutBreadcrumb[]; panelOpen?: boolean };
 
 /**
  * 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} />;
+  return props.slot === "rail" ? (
+    <RailNavigation currentPath={props.currentPath} panelOpen={props.panelOpen} />
+  ) : (
+    <HeaderControls {...props} />
+  );
+}
+
+/**
+ * The phone bar's live copy, mounted with the rail's island so the shell adds no island instance. It renders nothing
+ * while the server's bar is current, so mounting moves and refocuses nothing. When the saved rail preferences or the
+ * URL (a fragment, Back and Forward, an in-page navigation) change what the bar shows, it renders the new bar into the
+ * bar's row, and CSS hides the server's.
+ */
+function BarNavigation(props: { currentPath: string }) {
+  if (isServer) return null;
+  const data = useShellData();
+  const locale = useLocale();
+  const t = () => platformMessages.resolve([locale()]).t;
+  const initial = data?.rail;
+  if (!data || !initial) return null;
+  const [settings, setSettings] = createSignal(initial);
+  const [currentPath, setCurrentPath] = createSignal(props.currentPath);
+  const itemsFor = (rail: typeof initial, path: string) =>
+    phoneBarItems(projectRailNavigation(data.apps, rail, locale()), path, { label: t().home, path: data.home ?? "/" });
+  const served = JSON.stringify(itemsFor(initial, props.currentPath));
+  const items = createMemo(() => itemsFor(settings(), currentPath()));
+  onMount(() => {
+    const sync = () => setSettings(readRailContext()?.settings ?? initial);
+    const syncLocation = () => setCurrentPath(`${window.location.pathname}${window.location.search}${window.location.hash}`);
+    syncLocation();
+    window.addEventListener(RAIL_PREFERENCES_EVENT, sync);
+    window.addEventListener("popstate", syncLocation);
+    window.addEventListener("hashchange", syncLocation);
+    // In-page navigation (`@k2b/ssr/nav`) commits with pushState or replaceState, which only the Navigation API
+    // reports; where a browser lacks it, the bar follows at the next page load.
+    window.navigation?.addEventListener("currententrychange", syncLocation);
+    onCleanup(() => {
+      window.removeEventListener(RAIL_PREFERENCES_EVENT, sync);
+      window.removeEventListener("popstate", syncLocation);
+      window.removeEventListener("hashchange", syncLocation);
+      window.navigation?.removeEventListener("currententrychange", syncLocation);
+    });
+  });
+  const row = document.querySelector<HTMLElement>(".cloud-tab-bar__row");
+  if (!row) return null;
+  return (
+    <Show when={JSON.stringify(items()) !== served}>
+      <Portal mount={row}>
+        <TabBar variant="floating" class="cloud-tab-bar__live" label={t().apps} items={items()} />
+      </Portal>
+    </Show>
+  );
 }
 
-function RailNavigation(props: { currentPath: string }) {
+function RailNavigation(props: { currentPath: string; panelOpen?: boolean }) {
   const data = useShellData();
   const locale = useLocale();
   const t = () => platformMessages.resolve([locale()]).t;
@@ -36,7 +91,9 @@ function RailNavigation(props: { currentPath: string }) {
       <ShellFocusToggle variant="rail" />
       <RailApps apps={data.apps} settings={data.rail} currentPath={props.currentPath} />
       <AppLaunchpadButton profile={profile} apps={data.apps} legalLinks={data.legalLinks} variant="rail" label={t().openApps} />
+      <BarNavigation currentPath={props.currentPath} />
       <div class="mt-auto shrink-0 flex flex-col items-center gap-1">
+        {(data.panel?.providers.length ?? 0) > 1 && <PanelTrigger variant="rail" open={props.panelOpen} />}
         <GlobalSearchTrigger variant="rail" />
         <LayoutHelpTrigger variant="rail" />
         <ProfilePreferences
@@ -51,7 +108,13 @@ function RailNavigation(props: { currentPath: string }) {
 }
 
 /** 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[] }) {
+function HeaderControls(props: {
+  authenticated: boolean;
+  title?: string;
+  launchpad: boolean;
+  breadcrumbs?: LayoutBreadcrumb[];
+  panelOpen?: boolean;
+}) {
   const data = useShellData();
   const locale = useLocale();
   const t = () => platformMessages.resolve([locale()]).t;
@@ -65,13 +128,27 @@ function HeaderControls(props: { authenticated: boolean; title?: string; launchp
           </div>
         )}
         <div class="flex min-w-0 items-center lg:hidden">
-          <span class="truncate font-semibold">{props.title}</span>
+          <span class="layout-header-title truncate font-semibold">{props.title}</span>
+          {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="title"
+              label={props.title}
+            />
+          )}
         </div>
       </div>
       <div class="flex shrink-0 items-center gap-1">
         <div class="flex items-center gap-1 lg:hidden">
-          <LayoutHelpTrigger variant="header" />
+          {(data.panel?.providers.length ?? 0) > 1 && <PanelTrigger variant="header" open={props.panelOpen} />}
           {props.authenticated && <GlobalSearchTrigger variant="header" />}
+          <LayoutHelpTrigger variant="header" />
           {props.launchpad && (
             <AppLaunchpadButton
               profile={

package/src/ssr/Layout.tsx

@@ -2,6 +2,7 @@ import type { DateContext } from "@k2b/stdlib";
 import { AppWorkspace, appWorkspaceLayoutStyle, keyboardPlatform, LocaleProvider, NoticeCard, PageTrailProvider } from "@k2b/ui";
 import type { JSX } from "solid-js/jsx-runtime";
 import { readAppWorkspaceLayoutCookie, resolveAppWorkspaceLayoutForSidebar } from "../_internal/app-workspace-state";
+import { readPanelCookie } from "../_internal/panel-cookie";
 import { readShellFocusCookie } from "../_internal/shell-focus";
 import { resolveNavMatch } from "../contracts/app"; // ==========================
 import { isPwaShellAvailable } from "../contracts/pwa";
@@ -9,19 +10,21 @@ import { defaultRailPreferences } from "../contracts/rail-preferences";
 import { hasRole, type User } from "../contracts/shared";
 import { getLocale } from "../server/locale";
 import { getDateConfig } from "../server/time";
-import { dates } from "../shared";
+import { dates, resolveHomePath } from "../shared";
 import { readThemePreferenceFromCookieHeader } from "../shared/theme";
 import AnnouncementBanners from "./AnnouncementBanners";
 import { appAppearanceStyle, resolveCurrentApp } from "./app-appearance";
-import { resolveRuntimeRoute, visibleNavigationApps } from "./app-navigation";
+import { resolveRuntimeRoute, visibleNavigationApps, visiblePanelProviders } from "./app-navigation";
 import { getLayoutHelp, layoutHelpFailed } from "./help";
 import LayoutFooter from "./LayoutFooter";
 import LayoutHeader from "./LayoutHeader";
 import LayoutRail, { type LayoutAppLink } from "./LayoutRail";
+import LayoutTabBar from "./LayoutTabBar";
 import type { LayoutContext } from "./layout-context";
 import { HELP_VIEW_LIMIT } from "./layout-help-start";
 import type { LayoutBreadcrumb } from "./layout-runtime";
 import PageTrailRow from "./PageTrailRow";
+import PanelSlot from "./PanelSlot";
 import { derivePageTrail } from "./page-trail";
 import { platformMessages } from "./platform-messages";
 import { sortRailApps } from "./rail-navigation";
@@ -41,6 +44,8 @@ type LayoutProps = {
   help?: readonly string[];
   fullPage?: boolean /** Keep the shell viewport-bound and suppress its footer. */;
   fullWidth?: boolean /** Delegate scrolling and clipping to the page's work surface. */;
+  /** Hide the panel slot on this page (sign-in, print, presentation, public pages). */
+  panel?: false;
   focusMode?: boolean /** Render only the app canvas and content for dedicated editors or pop-out windows. */;
   flushCanvas?: boolean /** Remove app-canvas spacing for edge-to-edge focus surfaces such as pop-out windows. */;
   /** Final localized app-specific export or printing guidance, shown when no data-print-region exists. */
@@ -155,6 +160,12 @@ export default function Layout(props: LayoutProps) {
   const lang = getLocale(c);
   const t = platformMessages.resolve([lang]).t;
   const user = c.get("user");
+  const providers = user && props.panel !== false ? visiblePanelProviders(runtime.apps, user, lang) : [];
+  const panelState = readPanelCookie(
+    providers.length ? cookie : undefined,
+    providers.map((provider) => provider.id),
+  );
+  const panel = providers.length ? { providers, provider: panelState.provider ?? providers[0]?.id } : undefined;
   const pathname = new URL(c.req.raw.url).pathname;
   const currentRoute = resolveRuntimeRoute(runtime.apps, pathname);
   const currentApp = resolveCurrentApp(runtime.apps, pathname);
@@ -207,19 +218,29 @@ export default function Layout(props: LayoutProps) {
   // keeps short and long pages at the same width where scrollbars take space.
   const mainLayoutClass = fullPage || fullWidth ? "flex flex-col" : "md:overflow-auto md:[scrollbar-gutter:stable]";
   const canvasStyle =
-    [appAppearanceStyle(currentApp?.appearance), appWorkspaceLayoutStyle(workspaceLayout), focusMode && flushCanvas ? "padding:0" : ""]
+    [
+      appAppearanceStyle(currentApp?.appearance),
+      appWorkspaceLayoutStyle(workspaceLayout),
+      panelState.widthRem !== undefined ? `--cloud-panel-width-set:${panelState.widthRem}rem` : "",
+      focusMode && flushCanvas ? "padding:0" : "",
+    ]
       .filter(Boolean)
       .join(";") || undefined;
   const appLabel = currentApp?.name ?? (pathname.startsWith("/admin") ? t.admin : undefined);
   const helpIds = new Set(registeredHelp?.documents.map((topic) => topic.id));
   const viewHelp = [...new Set(props.help)].filter((id) => helpIds.has(id)).slice(0, HELP_VIEW_LIMIT);
   const shellData: ShellData = {
+    ...(panel ? { panel } : {}),
     platform: keyboardPlatform(c.req.raw.headers.get("User-Agent") ?? ""),
     ...(viewHelp.length ? { help: viewHelp } : {}),
     ...(layoutHelpFailed(c) ? { helpFailed: true as const } : {}),
     apps: allApps,
     ...(user
-      ? { rail: c.get("railPreferences") ?? defaultRailPreferences(), profile: { name: profileName, avatarSrc: profileAvatarSrc, appHref } }
+      ? {
+          rail: c.get("railPreferences") ?? defaultRailPreferences(),
+          home: resolveHomePath(settings?.app?.home_path),
+          profile: { name: profileName, avatarSrc: profileAvatarSrc, appHref },
+        }
       : {}),
     legalLinks,
     theme,
@@ -231,20 +252,27 @@ export default function Layout(props: LayoutProps) {
     return (
       <LocaleProvider locale={lang}>
         <div
-          class="cloud-app-canvas flex h-dvh w-full overflow-hidden"
+          class="cloud-app-canvas relative flex h-dvh w-full overflow-hidden"
           style={canvasStyle}
+          data-panel-transient=""
           data-app-id={currentApp?.id}
           data-app-base={currentRoute?.prefix}
           data-page-trail-title-only=""
           data-layout-full-page="true"
           data-workspace-sidebar-collapsed={workspaceLayout?.sidebarCollapsed ? "true" : undefined}
         >
-          <ShellRuntime pageTrail help={runtimeHelp} />
+          <ShellRuntime pageTrail help={runtimeHelp} panel={panel ? true : undefined} />
           <PageTrailProvider trail={pageTrail}>
-            <main class="min-h-0 min-w-0 flex-1">
+            <main class="min-h-0 min-w-0 flex-1" data-cloud-app-area="">
               <AppWorkspace.LayoutStateProvider state={workspaceLayout}>{props.children}</AppWorkspace.LayoutStateProvider>
             </main>
           </PageTrailProvider>
+          {/* Focus pages carry shell data only for their panel providers. */}
+          {panel && (
+            <ShellDataProvider data={{ panel, platform: shellData.platform, theme, apps: [], legalLinks: [], searchLinks: {} }}>
+              <PanelSlot panel={panel} state={{ ...panelState, open: false }} platform={shellData.platform} />
+            </ShellDataProvider>
+          )}
           <div data-print-fallback="">
             <p>{t.printFallbackTitle}</p>
             <p>{props.printHint ?? t.printFallbackHint}</p>
@@ -261,6 +289,7 @@ export default function Layout(props: LayoutProps) {
       <div
         class={`cloud-app-canvas relative flex w-full ${fullPage ? "h-dvh overflow-hidden" : "min-h-dvh md:h-dvh md:overflow-hidden"}`}
         style={canvasStyle}
+        data-panel={panelState.open ? "open" : undefined}
         data-app-id={currentApp?.id}
         data-app-base={currentRoute?.prefix}
         data-page-trail-title-only={titleOnly ? "" : undefined}
@@ -270,6 +299,7 @@ export default function Layout(props: LayoutProps) {
         data-workspace-sidebar-collapsed={workspaceLayout?.sidebarCollapsed ? "true" : undefined}
       >
         <ShellRuntime
+          panel={panel ? true : undefined}
           workspace={{ appId: currentApp?.id }}
           pageTrail
           focus={showRail}
@@ -284,11 +314,12 @@ export default function Layout(props: LayoutProps) {
           banners={user && announcements?.banners.length ? true : undefined}
         />
         <ShellDataProvider data={shellData}>
-          {showRail && <LayoutRail currentPath={requestPath(c)} />}
+          {showRail && <LayoutRail currentPath={requestPath(c)} panelOpen={panel ? panelState.open : undefined} />}
           {showRail && <ShellFocusToggle variant="float" />}
           {showRail && <div class="cloud-shell-reveal" data-cloud-shell-reveal="" aria-hidden="true" />}
-          <div class="layout-shell-content flex min-h-0 min-w-0 flex-1 flex-col">
+          <div class="layout-shell-content flex min-h-0 min-w-0 flex-1 flex-col" data-cloud-app-area="">
             <LayoutHeader
+              panelOpen={panel ? panelState.open : undefined}
               authenticated={showRail}
               title={appLabel ?? breadcrumbs.at(-1)?.title}
               launchpad={!!(user || appLabel)}
@@ -305,6 +336,8 @@ export default function Layout(props: LayoutProps) {
             </PageTrailProvider>
             {!fullPage && !showRail && <LayoutFooter appName={settings?.app?.copyright || appName} legalLinks={legalLinks} />}
           </div>
+          {panel && <PanelSlot panel={panel} state={panelState} platform={shellData.platform} />}
+          {showRail && <LayoutTabBar currentPath={requestPath(c)} />}
         </ShellDataProvider>
         <div data-print-fallback="">
           <p>{t.printFallbackTitle}</p>

package/src/ssr/LayoutHeader.tsx

@@ -5,6 +5,7 @@ import { platformMessages } from "./platform-messages";
 
 type LayoutHeaderProps = {
   authenticated: boolean;
+  panelOpen?: boolean;
   title?: string;
   launchpad: boolean;
   breadcrumbs?: LayoutBreadcrumb[];
@@ -14,10 +15,12 @@ type LayoutHeaderProps = {
  * Phones (below `md`) always get this header. From `md` it remains only on
  * anonymous pages; signed-in people reach Home, search, help, the app grid,
  * 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.
+ * On a signed-in phone it is the title row on the app gradient: Home moves to
+ * the bottom bar's Start, so the row holds the title, search, help, and the
+ * app menu. Anonymous pages have no rail: up to `lg` their header keeps Home,
+ * 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();
@@ -29,13 +32,16 @@ export default function LayoutHeader(props: LayoutHeaderProps) {
     >
       {/* 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>
+      {!props.authenticated && (
+        <div class="flex shrink-0">
+          <IconButtonLink href="/" label={t().home}>
+            <img src="/branding/logo" alt="" class="h-6 w-6" />
+          </IconButtonLink>
+        </div>
+      )}
       <CloudShell
         slot="header"
+        panelOpen={props.panelOpen}
         authenticated={props.authenticated}
         title={props.title}
         launchpad={props.launchpad}

package/src/ssr/LayoutHelp.tsx

@@ -101,7 +101,7 @@ const StartShortcuts = (props: { appName?: string }) => {
   const locale = useLocale();
   const t = () => helpMessages.resolve([locale()]).t;
   const shell = useShellData();
-  const seed: HelpShortcutCommand[] = shell ? shellShortcuts(platformMessages.resolve([locale()]).t) : [];
+  const seed: HelpShortcutCommand[] = shell ? shellShortcuts(platformMessages.resolve([locale()]).t, { panel: !!shell.panel }) : [];
   const read = (): HelpShortcutCommand[] => {
     const commands = contextCommandsWithShortcuts();
     return [...seed.filter((command) => !commands.some((other) => other.id === command.id)), ...commands];

package/src/ssr/LayoutRail.tsx

@@ -5,7 +5,7 @@ import type { RailApp } from "./rail-navigation";
 export type LayoutAppLink = RailApp;
 
 /** The rail frame and Home stay server markup; only the navigation is interactive. */
-export default function LayoutRail(props: { currentPath: string }) {
+export default function LayoutRail(props: { currentPath: string; panelOpen?: boolean }) {
   const locale = useLocale();
   const t = () => platformMessages.resolve([locale()]).t;
   return (
@@ -15,7 +15,7 @@ export default function LayoutRail(props: { currentPath: string }) {
           <img src="/branding/logo" alt="Logo" class="h-5 w-5" />
         </a>
       </div>
-      <CloudShell slot="rail" currentPath={props.currentPath} />
+      <CloudShell slot="rail" currentPath={props.currentPath} panelOpen={props.panelOpen} />
     </aside>
   );
 }

package/src/ssr/LayoutTabBar.tsx

@@ -0,0 +1,29 @@
+import { TabBar, useLocale } from "@k2b/ui";
+import { platformMessages } from "./platform-messages";
+import { phoneBarItems, projectRailNavigation } from "./rail-navigation";
+import { useShellData } from "./shell-data";
+
+/**
+ * The signed-in phone's bottom bar: Home and the person's first apps in their rail order, floating on the app
+ * gradient above the content card. It is server markup, so it stands in its final place before any island mounts and
+ * a link focused early keeps its focus. The rail's island takes over only when the bar's content changes in the
+ * browser: after the person saves their rail preferences, or when the URL changes in the page. The
+ * place of the app's primary action beside it stays free. From 768 px the rail takes over and the bar is hidden.
+ */
+export default function LayoutTabBar(props: { currentPath: string }) {
+  const data = useShellData();
+  const locale = useLocale();
+  if (!data?.rail) return null;
+  const t = platformMessages.resolve([locale()]).t;
+  const items = phoneBarItems(projectRailNavigation(data.apps, data.rail, locale()), props.currentPath, {
+    label: t.home,
+    path: data.home ?? "/",
+  });
+  return (
+    <div class="cloud-tab-bar">
+      <div class="cloud-tab-bar__row">
+        <TabBar variant="floating" label={t.apps} items={items} />
+      </div>
+    </div>
+  );
+}

package/src/ssr/PanelLayout.tsx

@@ -0,0 +1,27 @@
+import { LocaleProvider } from "@k2b/ui";
+import type { JSX } from "solid-js";
+import { canonicalRoute } from "../_internal/app-path";
+import { getLocale } from "../server/locale";
+import { resolveRuntimeRoute } from "./app-navigation";
+import type { MinimalLayoutContext } from "./layout-context";
+import PanelRuntime from "./PanelRuntime.island";
+import { getRuntimeContext } from "./runtime";
+
+export type PanelLayoutProps = { c: MinimalLayoutContext; title: string; children: JSX.Element };
+
+/** A provider page embedded in the shell's same-origin panel. */
+export default function PanelLayout(props: PanelLayoutProps) {
+  const runtime = getRuntimeContext(props.c);
+  // The provider owns this path by the canonical prefixes its panel declaration was checked against.
+  const apps = runtime.apps.map((entry) => ({ ...entry, routes: entry.routes.map(canonicalRoute) }));
+  const app = resolveRuntimeRoute(apps, new URL(props.c.req.raw.url).pathname)?.app;
+  props.c.get("page").title = props.title;
+  return (
+    <LocaleProvider locale={getLocale(props.c)}>
+      <div class="cloud-panel-page" data-cloud-panel-page="" data-panel-provider={app?.id}>
+        <PanelRuntime provider={app?.id} scope={app?.panel ? new URL(app.panel.href, props.c.req.raw.url).pathname : undefined} />
+        {props.children}
+      </div>
+    </LocaleProvider>
+  );
+}