@k2b/cloud 0.35.0 → 0.37.0

package/src/ai/executor.ts

@@ -23,6 +23,7 @@ import { CODE_RUNTIME_TOOL_NAMES } from "./browser-code-contracts";
 import { type AiCapabilityCatalogEntry, createAiToolResolver, createRunToolStore } from "./capabilities";
 import { AiCapabilityExecutionError, executeAiCapability, resolveAiCapabilityActor, reviewAiCapability } from "./capability-execution";
 import { aiChatMessages } from "./chat/messages";
+import { isFailedTool } from "./chat/tool-groups";
 import { aiTurnErrorText } from "./chat/turn-error";
 import { AiChatTaskAuthorityError, aiChatTasks } from "./chat-tasks";
 import { createCloudCompactFn } from "./compaction";
@@ -134,6 +135,17 @@ const toolRoundState = (messages: AiStoredMessage[]): { issued: number; complete
   };
 };
 
+const lastToolRoundFailed = (messages: AiStoredMessage[], blocks: AiTurnBlock[]): boolean => {
+  const latest = messages.findLast(({ message }) => message.role === "assistant")?.message;
+  if (latest?.role !== "assistant") return false;
+  const callIds = new Set(latest.content.flatMap((block) => (block.type === "tool_call" ? [block.id] : [])));
+  // A worker may have stored a malformed call but crashed before its error result; load repairs that result without an event.
+  return (
+    [...callIds].some(isMalformedToolCallId) ||
+    blocks.some((block) => block.kind === "tool" && callIds.has(block.callId) && isFailedTool(block))
+  );
+};
+
 const indexConversationResources = async (input: Parameters<typeof aiConversations.indexConversationResources>[0]): Promise<void> => {
   try {
     await aiConversations.indexConversationResources(input);
@@ -1500,6 +1512,7 @@ export class AiTurnExecutor {
     const outcome = await this.driveChatLoop({
       loop,
       pipeline,
+      initialRoundFailed: lastToolRoundFailed(turnMessages, turnBlocks),
       conversationId,
       turnId,
       abortController,
@@ -1572,6 +1585,7 @@ export class AiTurnExecutor {
   private async driveChatLoop(input: {
     loop: NessiLoop;
     pipeline: StreamPipeline;
+    initialRoundFailed: boolean;
     conversationId: string;
     turnId: string;
     abortController: AbortController;
@@ -1613,6 +1627,10 @@ export class AiTurnExecutor {
     } = input;
     const stopHeartbeat = this.startHeartbeat(conversationId, turnId, abortController);
     let lastIssueMessage: string | null = null;
+    let lastResponse: AssistantMessage | undefined;
+    let roundFailed = input.initialRoundFailed;
+    let followedFailedRound = false;
+    const malformedCallIds = new Set<string>();
 
     try {
       for await (const event of loop) {
@@ -1672,6 +1690,7 @@ export class AiTurnExecutor {
             .noteToolCompleted({ turnId, callId: event.callId, isError: event.isError })
             .catch(() => log.warn("AI tool audit write failed", { code: "tool_audit_complete_failed", turnId, callId: event.callId }));
           const toolBlock = pipeline.blocks.find((block) => block.kind === "tool" && block.callId === event.callId);
+          if (toolBlock?.kind === "tool" && isFailedTool(toolBlock)) roundFailed = true;
           // The policy keys calls by the name the model called, as the persisted calls it seeds from.
           noteToolCall(
             toolBlock?.kind === "tool"
@@ -1687,20 +1706,44 @@ export class AiTurnExecutor {
             result: event.result,
             isError: event.isError === true,
           });
-        } else if (event.type === "turn_end" && !abortController.signal.aborted && isToolRound(event.message)) {
-          noteToolRound();
+        } else if (event.type === "turn_end") {
+          lastResponse = event.message;
+          followedFailedRound = roundFailed;
+          const calls = new Set(event.message.content.flatMap((block) => (block.type === "tool_call" ? [block.id] : [])));
+          // nessi closes a round after executing its tools. Malformed calls have stored failed blocks,
+          // but are added by Cloud's store wrapper, so they are absent from the event's message.
+          roundFailed = pipeline.blocks.some(
+            (block) => block.kind === "tool" && (calls.has(block.callId) || malformedCallIds.has(block.callId)) && isFailedTool(block),
+          );
+          malformedCallIds.clear();
+          if (!abortController.signal.aborted && isToolRound(event.message)) noteToolRound();
         } else if (event.type === "issue") {
+          if (event.issue.kind === "malformed_tool_call" && event.issue.callId) malformedCallIds.add(event.issue.callId);
           lastIssueMessage = event.issue.message;
           log.warn("AI turn issue", { conversationId, turnId, kind: event.issue.kind, message: event.issue.message });
         } else if (event.type === "loop_end") {
+          const stoppedAfterFailure =
+            event.reason === "stop" &&
+            !abortController.signal.aborted &&
+            followedFailedRound &&
+            lastResponse !== undefined &&
+            !lastResponse.content.some((block) => block.type === "tool_call" || (block.type === "text" && block.text.trim() !== ""));
+          const doneReason = stoppedAfterFailure ? "error" : event.reason;
           const aggregate = await withDurableTurnTiming(turnId, event.aggregate);
           if (aggregate.assistantMessageCount > 0) {
             await aiConversations
-              .setLatestAssistantLoopAggregate({ conversationId, loopId: turnId, aggregate, doneReason: event.reason })
+              .setLatestAssistantLoopAggregate({ conversationId, loopId: turnId, aggregate, doneReason })
               .catch(() => undefined);
           }
           const timing = aggregate.timing;
           if (event.reason === "aborted") return { kind: "finished", status: "aborted", failure: null, timing };
+          if (stoppedAfterFailure)
+            return {
+              kind: "finished",
+              status: "failed",
+              failure: { error: { code: "tool_failed" }, detail: "The model stopped without an answer after a failed tool call." },
+              timing,
+            };
           if (event.reason === "stop") return { kind: "finished", status: "completed", failure: null, timing };
           const detail = lastIssueMessage ?? `AI turn ended: ${event.reason}`;
           const reason: AiTurnFailureReason =

package/src/ai/types.ts

@@ -337,6 +337,7 @@ export type AiConversationTimelineEntry = {
 export type AiTurnErrorCode =
   | "model_unavailable"
   | "provider_stopped"
+  | "tool_failed"
   | "quota_exhausted"
   | "context_full"
   | "time_limit"

package/src/browser/reload.ts

@@ -9,11 +9,26 @@ import { type ToastHandle, toast } from "@k2b/ui";
  */
 export const AUTOMATIC_RELOAD_WINDOW_MS = 30_000;
 
+let reloadPending = false;
+/** One notice at a time: every deferred reload has the same remedy. */
+let pageChanged: ToastHandle | undefined;
+
+/**
+ * An open modal dialog holds the reload. A modeless window, such as global search moved aside, leaves the page
+ * usable and may stay open for long, so it does not: the page would otherwise stay stale without notice.
+ */
+const modalOpen = () => document.querySelector('dialog[open]:not([aria-modal="false"])') !== null;
+
 const storageKey = (key: string) => `cloud.reload.${key}`;
 
 /**
  * Reloads the page for an automatic reason (a live event, a failed live
  * subscription, a changed view) at most once per `key` and window in this tab.
+ * While a modal dialog is open, it does not reload: once the last one closes,
+ * it shows a notice with a reload action. The person may have confirmed work
+ * in that dialog whose request a reload would cancel, so only they reload.
+ * The call returns `true` in both cases; a dialog that shows live data says
+ * itself that it is stale.
  *
  * Returns `false` without reloading when the same key already reloaded within
  * the window, or when `sessionStorage` is unavailable and a repeat therefore
@@ -22,6 +37,7 @@ const storageKey = (key: string) => `cloud.reload.${key}`;
  * need this guard.
  */
 export const reloadOnce = (key: string, options: { windowMs?: number } = {}): boolean => {
+  if (reloadPending) return true;
   const windowMs = options.windowMs ?? AUTOMATIC_RELOAD_WINDOW_MS;
   const now = Date.now();
   try {
@@ -32,7 +48,20 @@ export const reloadOnce = (key: string, options: { windowMs?: number } = {}): bo
   } catch {
     return false;
   }
-  window.location.reload();
+  if (typeof document === "undefined" || !modalOpen()) {
+    window.location.reload();
+    return true;
+  }
+  reloadPending = true;
+  const observer = new MutationObserver(() => {
+    if (modalOpen()) return;
+    observer.disconnect();
+    reloadPending = false;
+    const t = reloadMessages.resolve([document.documentElement.lang || "en"]).t;
+    pageChanged?.dismiss();
+    pageChanged = toast(t.pageChanged, { duration: 0, action: { label: t.reload, onClick: () => window.location.reload() } });
+  });
+  observer.observe(document.documentElement, { subtree: true, childList: true, attributes: true, attributeFilter: ["open", "aria-modal"] });
   return true;
 };
 
@@ -41,10 +70,12 @@ const reloadMessages = i18n.define({
   messages: {
     en: {
       codeUnavailable: "Part of this page could not load. Reload the page and try again.",
+      pageChanged: "This page changed. Reload it to see the latest version.",
       reload: "Reload",
     },
     de: {
       codeUnavailable: "Ein Teil dieser Seite konnte nicht geladen werden. Lade die Seite neu und versuche es erneut.",
+      pageChanged: "Diese Seite hat sich geändert. Lade sie neu, um den aktuellen Stand zu sehen.",
       reload: "Neu laden",
     },
   },

package/src/browser/shell-focus.ts

@@ -0,0 +1,67 @@
+import { shellFocusCookie } from "../_internal/shell-focus";
+
+export const SHELL_FOCUS_CHANGE_EVENT = "cloud:shell-focus-change";
+
+const canvas = () => document.querySelector<HTMLElement>(".cloud-app-canvas[data-layout-authenticated]");
+
+export const readShellFocus = (): boolean => canvas()?.dataset.shellFocus === "true";
+
+export const setShellFocus = (hidden: boolean): void => {
+  const element = canvas();
+  if (!element) return;
+  const focused = document.activeElement;
+  document.cookie = shellFocusCookie(hidden, location.protocol === "https:");
+  if (hidden) element.dataset.shellFocus = "true";
+  else delete element.dataset.shellFocus;
+  window.dispatchEvent(new CustomEvent(SHELL_FOCUS_CHANGE_EVENT, { detail: { hidden } }));
+  if (
+    window.matchMedia("(min-width: 768px)").matches &&
+    (!focused ||
+      focused === document.body ||
+      focused.matches("[data-cloud-shell-focus-toggle]") ||
+      !focused.isConnected ||
+      focused.getClientRects().length === 0)
+  ) {
+    element.querySelector<HTMLElement>(`[data-cloud-shell-focus-toggle="${hidden ? "show" : "hide"}"]`)?.focus({ preventScroll: true });
+  }
+};
+
+export const toggleShellFocus = (): void => setShellFocus(!readShellFocus());
+
+/** Delegation also handles the server's buttons before their islands hydrate. */
+export const attachShellFocusControls = (): (() => void) => {
+  const click = (event: MouseEvent) => {
+    if (!(event.target instanceof Element)) return;
+    const button = event.target.closest<HTMLElement>("[data-cloud-shell-focus-toggle]");
+    if (button) setShellFocus(button.dataset.cloudShellFocusToggle === "hide");
+  };
+  let drag: { pointerId: number; x: number; y: number } | undefined;
+  const start = (event: PointerEvent) => {
+    if (event.pointerType === "mouse" || !(event.target instanceof Element) || !event.target.closest("[data-cloud-shell-reveal]")) return;
+    drag = { pointerId: event.pointerId, x: event.clientX, y: event.clientY };
+  };
+  const move = (event: PointerEvent) => {
+    if (!drag || event.pointerId !== drag.pointerId) return;
+    const dx = event.clientX - drag.x;
+    if (dx >= 40 && dx > Math.abs(event.clientY - drag.y)) {
+      drag = undefined;
+      setShellFocus(false);
+    }
+  };
+  const stop = (event: PointerEvent) => {
+    if (event.pointerId === drag?.pointerId) drag = undefined;
+  };
+  document.addEventListener("click", click);
+  document.addEventListener("pointerdown", start);
+  window.addEventListener("pointermove", move);
+  window.addEventListener("pointerup", stop);
+  window.addEventListener("pointercancel", stop);
+  return () => {
+    document.removeEventListener("click", click);
+    document.removeEventListener("pointerdown", start);
+    window.removeEventListener("pointermove", move);
+    window.removeEventListener("pointerup", stop);
+    window.removeEventListener("pointercancel", stop);
+    drag = undefined;
+  };
+};

package/src/cli/commands.ts

@@ -244,6 +244,8 @@ export const readCliInput = async (input: CliInputFlagValue, options: ReadCliInp
 
 export const defineCliCommands = (config: CliCommandsConfig): CloudCliModule => {
   const root = buildCommandTree(config.commands, config.groupSummaries);
+  // `cld <module> reference` prints the module's skill references instead.
+  if (root.children.has("reference")) throw new Error(`CLI module "${config.name}" must not declare the reserved command "reference"`);
   if (config.alias !== undefined && !isCloudCliAlias(config.alias, config.name)) {
     throw new Error("CLI alias must be a lowercase kebab-case name different from the module name");
   }

package/src/cli/plugin.ts

@@ -1,6 +1,6 @@
 /**
- * `cld` plugin contract shared by the applications that serve plugins and by
- * `cld`, which installs and loads them.
+ * Verified `cld` bundle contract shared by application-served plugins,
+ * package plugins, and `cld`, which installs and loads them.
  *
  * An application serves each declared CLI module under
  * `/cli/plugins/<name>/`: `manifest.json`, the bundled module `cli.js`, and
@@ -34,9 +34,9 @@ export type CloudCliPluginManifest = {
   apiVersion: number;
   /** Module name and plugin ID. */
   name: string;
-  /** ID of the application that serves the plugin. */
+  /** ID of the serving application, or name of the publishing package. */
   app: string;
-  /** Version of the serving application build. */
+  /** Application build or package version. */
   version: string;
   entry: typeof CLOUD_CLI_PLUGIN_ENTRY;
   /** SHA-512 over the file list; see {@link cloudCliPluginDigest}. */
@@ -88,7 +88,7 @@ export const isCloudCliShortcuts = (value: unknown, name: string, alias?: string
         .every((segment) => !segment.startsWith("-")),
   );
 
-/** Validate a served manifest, including its digest. Throws an `Error` naming the first problem. */
+/** Validate a bundle manifest, including its digest. Throws an `Error` naming the first problem. */
 export const parseCloudCliPluginManifest = (value: unknown): CloudCliPluginManifest => {
   if (!isRecord(value)) throw new Error("plugin manifest is not an object");
   const { apiVersion, name, app, version, entry, digest, files } = value;

package/src/services/index.ts

@@ -218,3 +218,12 @@ export type {
   MailPage,
   MailServiceError,
 } from "../contracts/outgoing-mail";
+
+export {
+  NetworkTargetBlockedError,
+  isNetworkTargetBlocked,
+  pinnedNetworkLookup,
+  resolvePublicNetworkAddresses,
+  resolveAllowedNetworkAddresses,
+} from "./network-security";
+export type { NetworkLookup, PublicNetworkAddress } from "./network-security";

package/src/services/network-security.ts

@@ -1,6 +1,14 @@
 import { lookup as dnsLookup } from "node:dns/promises";
 import type { LookupFunction } from "node:net";
-import { isUnsafeNetworkAddress, isUnsafeNetworkHostname, normalizeNetworkHostname, parseNetworkAddress } from "../shared/network-address";
+import {
+  EMPTY_NETWORK_ALLOWLIST,
+  isAllowlistedNetworkAddress,
+  isUnsafeNetworkAddress,
+  isUnsafeNetworkHostname,
+  type NetworkAllowlist,
+  normalizeNetworkHostname,
+  parseNetworkAddress,
+} from "../shared/network-address";
 
 export type PublicNetworkAddress = { address: string; family: 4 | 6 };
 export type NetworkLookup = (
@@ -15,12 +23,14 @@ export class NetworkTargetBlockedError extends Error {
   }
 }
 
-export const resolvePublicNetworkAddresses = async (
+export const resolveAllowedNetworkAddresses = async (
   rawHostname: string,
+  allowlist: NetworkAllowlist,
   lookup: NetworkLookup = (hostname) => dnsLookup(hostname, { all: true, verbatim: true }),
 ): Promise<PublicNetworkAddress[]> => {
   const hostname = normalizeNetworkHostname(rawHostname);
-  if (isUnsafeNetworkHostname(rawHostname)) throw new NetworkTargetBlockedError("Network target host is not allowed");
+  const trustedHost = allowlist.hosts.has(hostname);
+  if (!trustedHost && isUnsafeNetworkHostname(rawHostname)) throw new NetworkTargetBlockedError("Network target host is not allowed");
 
   const literal = parseNetworkAddress(rawHostname);
   const addresses = literal ? [literal] : await lookup(hostname, { all: true, verbatim: true });
@@ -33,12 +43,46 @@ export const resolvePublicNetworkAddresses = async (
     if (!literal || literal.family !== entry.family) throw new NetworkTargetBlockedError("Network target returned an invalid address");
     return literal;
   });
-  if (normalized.some((entry) => isUnsafeNetworkAddress(entry.address))) {
+  if (
+    !trustedHost &&
+    normalized.some((entry) => isUnsafeNetworkAddress(entry.address) && !isAllowlistedNetworkAddress(allowlist, entry.address))
+  ) {
     throw new NetworkTargetBlockedError("Network target resolved to a private or reserved address");
   }
   return normalized;
 };
 
+/** Save-time hint only: every request must still resolve, validate and pin its target. */
+export const isNetworkTargetBlocked = async (
+  hostname: string,
+  allowlist: NetworkAllowlist,
+  {
+    resolve = resolveAllowedNetworkAddresses,
+    timeoutMs = 5000,
+  }: {
+    resolve?: typeof resolveAllowedNetworkAddresses;
+    timeoutMs?: number;
+  } = {},
+): Promise<boolean> => {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    await Promise.race([
+      resolve(hostname, allowlist),
+      new Promise<void>((resolve) => {
+        timer = setTimeout(resolve, timeoutMs);
+      }),
+    ]);
+    return false;
+  } catch (error) {
+    return error instanceof NetworkTargetBlockedError;
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+export const resolvePublicNetworkAddresses = (rawHostname: string, lookup?: NetworkLookup): Promise<PublicNetworkAddress[]> =>
+  resolveAllowedNetworkAddresses(rawHostname, EMPTY_NETWORK_ALLOWLIST, lookup);
+
 /** Socket lookup using only addresses already checked by the public resolver. */
 export const pinnedNetworkLookup =
   (addresses: readonly PublicNetworkAddress[]): LookupFunction =>

package/src/shared/network-address.ts

@@ -106,3 +106,83 @@ export const isUnsafeNetworkHostname = (rawHostname: string): boolean => {
     ((endsInNumber(hostname) || hostname.includes(":")) && !parseNetworkAddress(hostname))
   );
 };
+
+/** Operator-owned exact DNS names and canonical IP networks. Never populate from person input. */
+export type NetworkAllowlist = {
+  readonly hosts: ReadonlySet<string>;
+  readonly networks: ReadonlyArray<Readonly<{ address: string; family: 4 | 6; bits: number }>>;
+};
+
+export const EMPTY_NETWORK_ALLOWLIST: NetworkAllowlist = { hosts: new Set(), networks: [] };
+
+export const parseNetworkAllowlist = (entries: readonly string[]): NetworkAllowlist => {
+  const hosts = new Set<string>();
+  const networks: Array<{ address: string; family: 4 | 6; bits: number }> = [];
+  for (const entry of entries) {
+    const invalid = (reason = "expected an exact host name, IP address or CIDR") =>
+      new Error(`Invalid network allowlist entry "${entry}": ${reason}`);
+    const parts = entry.split("/");
+    const raw = parts[0] ?? "";
+    const literal = parseNetworkAddress(raw);
+    if (literal) {
+      // Allowlist entries use strict IP notation, even though URL destinations may use legacy IPv4.
+      if (literal.family === 4 && ipv4ToNumber(raw) === null) throw invalid();
+      if (literal.family === 6 && raw.includes(".") && ipv4ToNumber(raw.replace(/\]$/, "").split(":").at(-1) ?? "") === null)
+        throw invalid();
+      const width = literal.family === 4 ? 32 : 128;
+      if (parts.length > 2 || (parts.length === 2 && !/^(0|[1-9]\d*)$/.test(parts[1] ?? ""))) throw invalid();
+      const bits = parts.length === 2 ? Number(parts[1]) : width;
+      if (bits > width) throw invalid();
+      if (bits === 0) throw invalid("a /0 network allows every address; list the internal hosts or ranges instead");
+      const value = literal.family === 4 ? BigInt(ipv4ToNumber(literal.address)!) : ipv6ToBigInt(literal.address);
+      const shift = BigInt(width - bits);
+      const base = (value >> shift) << shift;
+      if (base !== value) {
+        const address =
+          literal.family === 4
+            ? [24n, 16n, 8n, 0n].map((shift) => Number((base >> shift) & 255n)).join(".")
+            : parseNetworkAddress(
+                Array.from({ length: 8 }, (_, index) => ((base >> BigInt((7 - index) * 16)) & 65535n).toString(16)).join(":"),
+              )!.address;
+        throw invalid(`host bits are set; use ${address}/${bits}`);
+      }
+      networks.push({ ...literal, bits });
+      continue;
+    }
+    const hostname = normalizeNetworkHostname(raw);
+    if (
+      parts.length !== 1 ||
+      endsInNumber(hostname) ||
+      raw.includes(":") ||
+      hostname.length > 253 ||
+      !hostname.split(".").every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label))
+    )
+      throw invalid();
+    hosts.add(hostname);
+  }
+  return { hosts, networks };
+};
+
+/** Parse operator configuration with the variable name in startup errors. */
+export const parseNetworkAllowlistEnv = (variable: string, entries: readonly string[]): NetworkAllowlist => {
+  try {
+    return parseNetworkAllowlist(entries);
+  } catch (error) {
+    throw new Error(`${variable}: ${error instanceof Error ? error.message : "Invalid allowlist"}`);
+  }
+};
+
+export const isAllowlistedNetworkAddress = (allowlist: NetworkAllowlist, rawAddress: string): boolean => {
+  const literal = parseNetworkAddress(rawAddress);
+  if (!literal) return false;
+  if (literal.family === 6) {
+    const value = ipv6ToBigInt(literal.address);
+    // Only IPv4-mapped IPv6 reaches the embedded IPv4 host directly.
+    if (value >> 32n === 0xffffn) {
+      const ipv4 = [24n, 16n, 8n, 0n].map((shift) => Number((value >> shift) & 255n)).join(".");
+      if (isAllowlistedNetworkAddress(allowlist, ipv4)) return true;
+    }
+    return allowlist.networks.some((network) => network.family === 6 && ipv6InRange(value, ipv6ToBigInt(network.address), network.bits));
+  }
+  return allowlist.networks.some((network) => network.family === 4 && ipv4InRange(literal.address, network.address, network.bits));
+};

package/src/ssr/CloudShell.island.tsx

@@ -9,6 +9,7 @@ import type { LayoutBreadcrumb } from "./layout-runtime";
 import ProfilePreferences from "./ProfilePreferences";
 import { platformMessages } from "./platform-messages";
 import RailApps from "./RailApps";
+import ShellFocusToggle from "./ShellFocusToggle";
 import { useShellData } from "./shell-data";
 
 type CloudShellProps =
@@ -32,6 +33,7 @@ function RailNavigation(props: { currentPath: string }) {
   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}>
+      <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} />
       <div class="mt-auto shrink-0 flex flex-col items-center gap-1">

package/src/ssr/GlobalSearchTrigger.tsx

@@ -33,7 +33,7 @@ export default function GlobalSearchTrigger(props: GlobalSearchTriggerProps) {
         delay={0}
         content={t().searchShortcut}
       >
-        <i class={`${action.busy() ? "ti ti-loader-2 animate-spin" : "ti ti-search"} text-base`} />
+        <i class={`${action.busy() ? "ti ti-loader-2 animate-spin" : "ti ti-search"} text-xl`} />
       </Tooltip.Trigger>
     );
 

package/src/ssr/Layout.tsx

@@ -2,6 +2,7 @@ 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 { readShellFocusCookie } from "../_internal/shell-focus";
 import { resolveNavMatch } from "../contracts/app"; // ==========================
 import { isPwaShellAvailable } from "../contracts/pwa";
 import { defaultRailPreferences } from "../contracts/rail-preferences";
@@ -25,6 +26,7 @@ import { platformMessages } from "./platform-messages";
 import { sortRailApps } from "./rail-navigation";
 import { requestPath } from "./request-path";
 import { getLocalizedRuntimeContext, type RuntimeContext } from "./runtime";
+import ShellFocusToggle from "./ShellFocusToggle";
 import ShellRuntime from "./ShellRuntime.island";
 import { type ShellData, ShellDataProvider } from "./shell-data";
 
@@ -187,6 +189,8 @@ export default function Layout(props: LayoutProps) {
     ? { title: pageTitle, ancestors: [] }
     : derivePageTrail(title ?? appName, currentRoute?.prefix, appName, `${pathname}${new URL(c.req.raw.url).search}`);
   const showRail = !!user;
+  // The app bar and the app's navigation hidden with Cmd/Ctrl+\ or the sidebar buttons; phones ignore it in CSS.
+  const shellFocus = showRail && readShellFocusCookie(cookie);
   // The profile menu offers the mobile app only while the installation runs it.
   const appHref = user && isPwaShellAvailable(runtime.apps) ? "/me/app" : undefined;
   const profileName = user?.displayName || user?.uid || "?";
@@ -248,11 +252,13 @@ export default function Layout(props: LayoutProps) {
         data-page-trail-title-only={titleOnly ? "" : undefined}
         data-layout-full-page={fullPage ? "true" : undefined}
         data-layout-authenticated={showRail ? "true" : undefined}
+        data-shell-focus={shellFocus ? "true" : undefined}
         data-workspace-sidebar-collapsed={workspaceLayout?.sidebarCollapsed ? "true" : undefined}
       >
         <ShellRuntime
           workspace={{ appId: currentApp?.id }}
           pageTrail
+          focus={showRail}
           help={runtimeHelp}
           commands={{ searchResources: !!user }}
           push={!!user}
@@ -265,6 +271,8 @@ export default function Layout(props: LayoutProps) {
         />
         <ShellDataProvider data={shellData}>
           {showRail && <LayoutRail currentPath={requestPath(c)} />}
+          {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">
             <LayoutHeader
               authenticated={showRail}

package/src/ssr/LayoutHelpTrigger.tsx

@@ -31,7 +31,7 @@ export default function LayoutHelpTrigger(props: LayoutHelpTriggerProps) {
         delay={0}
         content={t().helpShortcut}
       >
-        <i class={`${action.busy() ? "ti ti-loader-2 animate-spin" : "ti ti-help-circle"} text-base`} />
+        <i class={`${action.busy() ? "ti ti-loader-2 animate-spin" : "ti ti-help-circle"} text-xl`} />
       </Tooltip.Trigger>
     );
 

package/src/ssr/LayoutRail.tsx

@@ -9,7 +9,7 @@ export default function LayoutRail(props: { currentPath: string }) {
   const locale = useLocale();
   const t = () => platformMessages.resolve([locale()]).t;
   return (
-    <aside class="layout-rail hidden w-10 shrink-0 flex-col md:flex">
+    <aside class="layout-rail hidden w-14 shrink-0 flex-col md:flex">
       <div class="layout-rail-logo flex h-[2.875rem] shrink-0 items-center justify-center">
         <a href="/" aria-label={t().home}>
           <img src="/branding/logo" alt="Logo" class="h-5 w-5" />

package/src/ssr/ProfilePreferences.tsx

@@ -18,7 +18,7 @@ type ProfilePreferencesProps = {
 export default function ProfilePreferences(props: ProfilePreferencesProps) {
   const { preferences, items, signOut, signingOut } = createProfileActions(props.initialTheme, props.appHref);
 
-  const avatar = () => <Avatar name={props.name} src={props.avatarSrc} size="xs" />;
+  const avatar = () => <Avatar name={props.name} src={props.avatarSrc} size="sm" />;
 
   return (
     <div class="layout-profile-preferences">

package/src/ssr/RailApps.tsx

@@ -21,7 +21,7 @@ function RailIcon(props: { link: RailLink; currentPath: string }) {
         aria-current={active() ? "page" : undefined}
         style={appAccentStyle(props.link.accent)}
       >
-        <i class={`${props.link.iconClass} text-base`} aria-hidden="true" />
+        <i class={`${props.link.iconClass} text-xl`} aria-hidden="true" />
         <span class="sr-only">{props.link.label}</span>
         <AppBadge endpoint={props.link.badge} appId={props.link.appId} />
       </a>

package/src/ssr/ShellFocusToggle.tsx

@@ -0,0 +1,43 @@
+import { IconButton, Tooltip, useLocale } from "@k2b/ui";
+import { platformMessages } from "./platform-messages";
+
+/**
+ * The two buttons of the shell's focus state. The app bar's button hides the
+ * app bar and the app's navigation; the floating one shows them again. Both
+ * are always rendered, and the canvas's `data-shell-focus` decides in CSS which
+ * one shows, so the server's first frame is final. `ShellRuntime` handles
+ * their clicks by `data-cloud-shell-focus-toggle`, so the floating button is
+ * plain server markup, with its shortcut in the native title, and needs no
+ * island of its own.
+ */
+export default function ShellFocusToggle(props: { variant: "rail" | "float" }) {
+  const locale = useLocale();
+  const t = () => platformMessages.resolve([locale()]).t;
+  if (props.variant === "rail")
+    return (
+      <Tooltip.Trigger
+        type="button"
+        class="rail-item"
+        data-cloud-shell-focus-toggle="hide"
+        aria-label={t().hideSidebar}
+        placement="right"
+        delay={0}
+        content={t().hideSidebarShortcut}
+      >
+        <i class="ti ti-layout-sidebar-left-collapse text-xl" aria-hidden="true" />
+      </Tooltip.Trigger>
+    );
+  return (
+    <div class="cloud-shell-show">
+      <IconButton
+        variant="secondary"
+        size="lg"
+        data-cloud-shell-focus-toggle="show"
+        label={t().showSidebar}
+        title={t().showSidebarShortcut}
+      >
+        <i class="ti ti-layout-sidebar-left-expand text-xl" aria-hidden="true" />
+      </IconButton>
+    </div>
+  );
+}