@k2b/cloud 0.29.1 → 0.30.0

package/src/services/help/index.ts

@@ -1,6 +1,8 @@
 import { type SQL, sql } from "bun";
+import { appAudienceRoles, hasAnyAppRole } from "../../_internal/app-roles";
 import { getApp, listApps } from "../../_internal/registry";
 import type { AppRegistryEntry } from "../../contracts/registry";
+import type { RequestActor } from "../../contracts/shared";
 import { resolveAppPresentations } from "../../shared/app-presentation";
 import { helpLocaleChain } from "../../shared/help";
 import { logger } from "../logging";
@@ -12,8 +14,20 @@ export type { HelpArticle, HelpMatch, HelpMetadata, HelpReader, HelpReaderFactor
 
 const log = logger("help");
 
+/**
+ * Help follows the app's declared visibility: it needs a user (the person, or the user an API credential acts
+ * for), the app's navigation roles limit it, and an app reached only through the admin area is for admins.
+ * The app's routes still authorize the app itself.
+ */
+export const canReadAppHelp = (app: Pick<AppRegistryEntry, "nav">, viewer: RequestActor | undefined): boolean => {
+  const user = viewer?.kind === "user" ? viewer.user : (viewer?.delegatedUser ?? undefined);
+  return !!user && hasAnyAppRole(user, appAudienceRoles(app.nav));
+};
+
+/** Reads Help in one language for one viewer; apps the viewer may not see do not exist for this reader. */
 export const createHelpReader = (
   locale: string,
+  viewer: RequestActor | undefined,
   dependencies: {
     db?: SQL;
     listApps?: () => Promise<AppRegistryEntry[]>;
@@ -21,11 +35,10 @@ export const createHelpReader = (
   } = {},
 ): HelpReader => {
   const db = dependencies.db ?? sql;
+  const visible = (app: AppRegistryEntry | null): app is AppRegistryEntry => app !== null && canReadAppHelp(app, viewer);
   const select = async (appId?: string): Promise<HelpSelection[]> => {
-    const apps = appId
-      ? [await (dependencies.getApp ?? getApp)(appId)].filter((app): app is AppRegistryEntry => app !== null)
-      : await (dependencies.listApps ?? listApps)();
-    return resolveAppPresentations(apps, locale).flatMap((app) =>
+    const apps = appId ? [await (dependencies.getApp ?? getApp)(appId)] : await (dependencies.listApps ?? listApps)();
+    return resolveAppPresentations(apps.filter(visible), locale).flatMap((app) =>
       app.help
         ? [
             {
@@ -41,7 +54,7 @@ export const createHelpReader = (
   return {
     async manifest(appId) {
       const app = await (dependencies.getApp ?? getApp)(appId);
-      if (!app?.help) return null;
+      if (!visible(app) || !app.help) return null;
       const [corpus] = await db`SELECT 1 FROM help.corpora WHERE app_id=${app.id} AND manifest_hash=${app.help.manifestHash}`;
       if (!corpus) return null;
       const rows = await queryHelp(

package/src/services/help/types.ts

@@ -1,4 +1,5 @@
 import type { AppRegistryHelpSummary } from "../../contracts/registry";
+import type { RequestActor } from "../../contracts/shared";
 import type { HelpDocumentManifest } from "../../shared/help";
 
 export type HelpDocument = {
@@ -36,11 +37,11 @@ export type HelpSearchInput = { query: string; appId?: string; limit?: number };
 export type HelpReadInput = { appId: string; documentId: string };
 export type HelpManifestResult = AppRegistryHelpSummary & { locale: string; documents: readonly HelpDocumentManifest[] };
 
-/** One request's language; operations resolve the current published app versions. */
+/** One request's language and viewer; operations resolve the current published versions of the apps the viewer may see. */
 export type HelpReader = {
   manifest(appId: string): Promise<HelpManifestResult | null>;
   list(cursor?: string): Promise<HelpMetadata[]>;
   search(input: HelpSearchInput): Promise<HelpMatch[]>;
   read(input: HelpReadInput): Promise<HelpArticle | null>;
 };
-export type HelpReaderFactory = (locale: string) => HelpReader;
+export type HelpReaderFactory = (locale: string, viewer: RequestActor | undefined) => HelpReader;

package/src/services/identity/constants.ts

@@ -13,6 +13,8 @@ export const INVOCATION_CLOCK_TOLERANCE_SECONDS = 2;
 export const IDENTITY_JWKS_MAX_AGE_SECONDS = 5 * 60;
 export const IDENTITY_ACTIVATION_LEAD_MS = 10 * 60_000;
 export const IDENTITY_SIGNING_CACHE_MS = 60_000;
+/** Bounds a shared signer refresh or identity settings load; matches the default issuance deadline. */
+export const IDENTITY_REFRESH_TIMEOUT_MS = 30_000;
 export const IDENTITY_ROTATION_AGE_MS = 30 * 24 * 60 * 60_000;
 export const IDENTITY_ROLLOUT_MARGIN_MS = 10 * 60_000;
 export const IDENTITY_MAX_COMPACT_TOKEN_BYTES = 4 * 1024;

package/src/services/identity/key-ring.ts

@@ -6,6 +6,7 @@ import {
   CLOUD_IDENTITY_ALGORITHM,
   IDENTITY_ACTIVATION_LEAD_MS,
   IDENTITY_CLOCK_TOLERANCE_SECONDS,
+  IDENTITY_REFRESH_TIMEOUT_MS,
   IDENTITY_ROLLOUT_MARGIN_MS,
   IDENTITY_ROTATION_AGE_MS,
   IDENTITY_SIGNING_CACHE_MS,
@@ -76,6 +77,38 @@ const date = (value: Date | string): Date => (value instanceof Date ? value : ne
 const publicJwk = (value: JWK | string): JWK => (typeof value === "string" ? (JSON.parse(value) as JWK) : value);
 const serializedSize = (value: unknown): number => encoder.encode(JSON.stringify(value)).byteLength;
 
+const formatDuration = (ms: number): string => (ms % 1_000 === 0 ? `${ms / 1_000} s` : `${ms} ms`);
+
+/**
+ * Stops waiting for `work` once `signal` aborts. The work itself keeps running
+ * (a pooled query or a shared refresh cannot be cancelled from here), but the
+ * caller is released at its deadline instead of whenever the stall ends.
+ */
+const untilAborted = <V>(work: Promise<V>, signal: AbortSignal): Promise<V> => {
+  if (signal.aborted) {
+    work.catch(() => undefined);
+    return Promise.reject(signal.reason);
+  }
+  return new Promise<V>((resolve, reject) => {
+    const abort = () => reject(signal.reason);
+    signal.addEventListener("abort", abort, { once: true });
+    work.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+  });
+};
+
+const timeoutSignal = (ms: number, reason: () => DOMException): { signal: AbortSignal; clear: () => void } => {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(reason()), ms);
+  return { signal: controller.signal, clear: () => clearTimeout(timer) };
+};
+
+/**
+ * A JS deadline alone cannot cancel a blocked PostgreSQL query. Bound each
+ * statement (including lock waits) on this connection, transaction-local.
+ */
+const boundStatements = (db: typeof sql, deadline: number) =>
+  db`SELECT set_config('statement_timeout', ${`${Math.max(1, Math.floor(deadline - Date.now()))}ms`}, true)`;
+
 const assertRsaJwk = (value: JWK, privateRequired: boolean): void => {
   if (value.kty !== "RSA" || typeof value.n !== "string" || typeof value.e !== "string") {
     throw new Error("Cloud identity key is not an RSA JWK");
@@ -156,8 +189,8 @@ const importRow = async (row: SigningKeyRow, keys: IdentityKeyEncryptionConfig):
   return { kid: row.kid, key, signUntil: date(row.sign_until) };
 };
 
-const selectRows = async (purpose: SigningKeyPurpose): Promise<SigningKeyRow[]> =>
-  sql<SigningKeyRow[]>`
+const selectRows = async (db: typeof sql, purpose: SigningKeyPurpose): Promise<SigningKeyRow[]> =>
+  db<SigningKeyRow[]>`
     SELECT id, purpose, state, kid, alg, public_jwk, encrypted_private_jwk, encryption_key_id,
       created_at, activate_at, activated_at, sign_until, retired_at, verify_until, revoked_at
     FROM auth.signing_keys
@@ -188,9 +221,16 @@ const insertKey = async (
   `;
 };
 
-const maintainPurpose = async (purpose: SigningKeyPurpose): Promise<SigningKeyRow> => {
+/**
+ * Every statement ends by `deadline`, so a refresh that its callers already
+ * gave up on does not keep holding a pooled connection.
+ */
+const maintainPurpose = async (purpose: SigningKeyPurpose, deadline: number): Promise<SigningKeyRow> => {
   const keys = await readIdentityKeyEncryptionConfig();
-  const before = await selectRows(purpose);
+  const before = await sql.begin(async (tx) => {
+    await boundStatements(tx, deadline);
+    return selectRows(tx, purpose);
+  });
   const beforeActive = before.find((row) => row.state === "active");
   const beforePending = before.find((row) => row.state === "pending");
   const nowMs = Date.now();
@@ -205,6 +245,8 @@ const maintainPurpose = async (purpose: SigningKeyPurpose): Promise<SigningKeyRo
       ? await generateEncryptedKey(keys)
       : null;
   const active = await sql.begin(async (tx) => {
+    // Another replica's stuck rotation must not hold this refresh forever.
+    await boundStatements(tx, deadline);
     await tx`SELECT pg_advisory_xact_lock(hashtextextended(${`cloud:identity-keyring:${purpose}`}, 0))`;
     const rows = await tx<SigningKeyRow[]>`
       SELECT id, purpose, state, kid, alg, public_jwk, encrypted_private_jwk, encryption_key_id,
@@ -289,10 +331,24 @@ export const prepareIdentitySigner = async (purpose: SigningKeyPurpose): Promise
   return signerRefreshes.run(
     purpose,
     async () => {
+      // Every caller joins this refresh. Bound it, so one hung connection
+      // cannot hold back every later issuance until TCP gives up.
+      const deadline = Date.now() + IDENTITY_REFRESH_TIMEOUT_MS;
+      const bound = timeoutSignal(
+        IDENTITY_REFRESH_TIMEOUT_MS,
+        () =>
+          new DOMException(
+            `Cloud identity signer refresh did not finish within ${formatDuration(IDENTITY_REFRESH_TIMEOUT_MS)}`,
+            "TimeoutError",
+          ),
+      );
       try {
-        const keys = await readIdentityKeyEncryptionConfig();
-        const row = await maintainPurpose(purpose);
-        const signer = await importRow(row, keys);
+        const refresh = async () => {
+          const keys = await readIdentityKeyEncryptionConfig();
+          const row = await maintainPurpose(purpose, deadline);
+          return importRow(row, keys);
+        };
+        const signer = await untilAborted(refresh(), bound.signal);
         if (signer.signUntil.getTime() <= now) throw new Error(`Active ${purpose} signing key is past sign_until`);
         return signer;
       } catch (error) {
@@ -300,6 +356,8 @@ export const prepareIdentitySigner = async (purpose: SigningKeyPurpose): Promise
         log.error("Cloud identity signer refresh failed", { purpose, error: error instanceof Error ? error.message : String(error) });
         if (cached && cached.signer.signUntil.getTime() > now) return cached.signer;
         throw error;
+      } finally {
+        bound.clear();
       }
     },
     (signer) => {
@@ -313,6 +371,10 @@ export const prepareIdentitySigner = async (purpose: SigningKeyPurpose): Promise
  * The shared row lock makes emergency revocation wait for already-started
  * issuance and prevents replicas from releasing a new result under that key
  * after the revocation commits.
+ *
+ * `timeoutMs` bounds the whole call: signer refresh, identity settings, the
+ * wait for a connection and the key check. The caller is released at the
+ * deadline with a `TimeoutError` that names the step that stalled.
  */
 export const withActiveIdentitySigner = async <T>(
   purpose: SigningKeyPurpose,
@@ -322,42 +384,61 @@ export const withActiveIdentitySigner = async <T>(
   const timeoutMs = options.timeoutMs ?? 30_000;
   if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new Error("Identity issuance timeout must be positive");
   const deadline = Date.now() + timeoutMs;
-  const checkDeadline = () => {
-    options.signal?.throwIfAborted();
-    if (Date.now() >= deadline) throw new DOMException("Identity issuance deadline exceeded", "TimeoutError");
+  let step = "signer refresh";
+  const expired = () => new DOMException(`Identity service did not respond within ${formatDuration(timeoutMs)} (${step})`, "TimeoutError");
+  const bound = timeoutSignal(timeoutMs, expired);
+  const signal = options.signal ? AbortSignal.any([options.signal, bound.signal]) : bound.signal;
+  // The timer releases a waiting caller. The clock also catches a timer that a
+  // busy event loop delivers late, and a statement Postgres cancels first.
+  const check = () => {
+    signal.throwIfAborted();
+    if (Date.now() >= deadline) throw expired();
   };
-  // Preparation can refresh/rotate keys using the pool. Never do it while
-  // holding a caller's transaction: every issuance needs just one connection.
-  for (let attempt = 0; attempt < 2; attempt += 1) {
-    checkDeadline();
-    const signer = await prepareIdentitySigner(purpose);
-    const { issuer } = await getIdentityRuntimeConfig();
-    checkDeadline();
-    const run = async (db: typeof sql): Promise<{ active: false } | { active: true; result: T }> => {
-      checkDeadline();
-      // A JS deadline alone cannot cancel a blocked PostgreSQL query. Bound
-      // each statement (including lock waits) on this connection, transaction-local.
-      await db`SELECT set_config('statement_timeout', ${`${Math.max(1, Math.floor(deadline - Date.now()))}ms`}, true)`;
-      const [active] = await db<Array<{ kid: string }>>`
-        SELECT kid
-        FROM auth.signing_keys
-        WHERE kid = ${signer.kid}
-          AND purpose = ${purpose}
-          AND state = 'active'
-          AND sign_until > now()
-        FOR SHARE
-      `;
-      checkDeadline();
-      if (!active) return { active: false };
-      const result = await callback({ ...signer, issuer }, db);
-      return { active: true, result };
-    };
-    const checked = await (options.pool ?? sql).begin(run);
-    checkDeadline();
-    if (checked.active) return checked.result;
-    invalidateIdentitySignerCache(purpose, signer.kid);
+  const wait = <V>(name: string, work: () => Promise<V>): Promise<V> => {
+    check();
+    step = name;
+    return untilAborted(work(), signal);
+  };
+  try {
+    // Preparation can refresh/rotate keys using the pool. Never do it while
+    // holding a caller's transaction: every issuance needs just one connection.
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      const signer = await wait("signer refresh", () => prepareIdentitySigner(purpose));
+      const { issuer } = await wait("identity settings", getIdentityRuntimeConfig);
+      const run = async (db: typeof sql): Promise<{ active: false } | { active: true; result: T }> => {
+        // A caller released at its deadline must not sign once a connection frees up.
+        check();
+        step = "signing key check";
+        await boundStatements(db, deadline);
+        const [active] = await db<Array<{ kid: string }>>`
+          SELECT kid
+          FROM auth.signing_keys
+          WHERE kid = ${signer.kid}
+            AND purpose = ${purpose}
+            AND state = 'active'
+            AND sign_until > now()
+          FOR SHARE
+        `;
+        check();
+        if (!active) return { active: false };
+        step = "signing";
+        const result = await callback({ ...signer, issuer }, db);
+        // Roll back what the callback wrote instead of committing a result the caller never gets.
+        check();
+        return { active: true, result };
+      };
+      const checked = await wait("database connection", () => (options.pool ?? sql).begin(run));
+      check();
+      if (checked.active) return checked.result;
+      invalidateIdentitySignerCache(purpose, signer.kid);
+    }
+    throw new Error(`No active ${purpose} identity signer is available`);
+  } catch (error) {
+    check();
+    throw error;
+  } finally {
+    bound.clear();
   }
-  throw new Error(`No active ${purpose} identity signer is available`);
 };
 
 export const initializeIdentityAuthority = async (): Promise<void> => {
@@ -474,7 +555,7 @@ const maintainVerificationWindows = async (): Promise<void> => {
 };
 
 export const runIdentityKeyMaintenance = async (): Promise<void> => {
-  for (const purpose of SIGNING_KEY_PURPOSES) await maintainPurpose(purpose);
+  for (const purpose of SIGNING_KEY_PURPOSES) await maintainPurpose(purpose, Date.now() + IDENTITY_REFRESH_TIMEOUT_MS);
   await maintainVerificationWindows();
   await sql`
     DELETE FROM auth.session_families

package/src/services/identity/runtime-config.ts

@@ -1,7 +1,7 @@
 import { env } from "../../config/env";
 import { publicCloudOrigin } from "../../shared/app-url";
 import { get as getSetting } from "../settings";
-import { CLOUD_INVOCATION_JWKS_PATH, CLOUD_OAUTH_JWKS_PATH, CLOUD_SESSION_JWKS_PATH } from "./constants";
+import { CLOUD_INVOCATION_JWKS_PATH, CLOUD_OAUTH_JWKS_PATH, CLOUD_SESSION_JWKS_PATH, IDENTITY_REFRESH_TIMEOUT_MS } from "./constants";
 
 const RUNTIME_CONFIG_TTL_MS = 60_000;
 
@@ -73,7 +73,18 @@ export const getIdentityRuntimeConfig = async (): Promise<IdentityRuntimeConfig>
   const now = Date.now();
   if (cached && cached.expiresAt > now) return cached.value;
   if (loading) return loading;
-  loading = load()
+  // Every caller joins this load. Bound it like the signer refresh, so one hung
+  // settings read cannot hold back every later caller; the next one starts over.
+  loading = new Promise<IdentityRuntimeConfig>((resolve, reject) => {
+    const timer = setTimeout(
+      () =>
+        reject(new DOMException(`Cloud identity settings did not load within ${IDENTITY_REFRESH_TIMEOUT_MS / 1_000} s`, "TimeoutError")),
+      IDENTITY_REFRESH_TIMEOUT_MS,
+    );
+    load()
+      .then(resolve, reject)
+      .finally(() => clearTimeout(timer));
+  })
     .then((value) => {
       cached = { value, expiresAt: Date.now() + RUNTIME_CONFIG_TTL_MS };
       return value;

package/src/ssr/AppLaunchpadPanel.tsx

@@ -2,11 +2,11 @@ import { documentNavigate } from "@k2b/ssr/nav";
 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 { AppBadge, useAppBadgeDescription } from "./AppBadge";
 import { MobileProfileActions } from "./MobileProfileActions";
 import { platformMessages } from "./platform-messages";
-import { openRailEditor } from "./RailEditor";
 import { readRailContext } from "./rail-context";
 import { railMessages } from "./rail-messages";
 import { projectRailNavigation } from "./rail-navigation";
@@ -64,6 +64,7 @@ export const AppLaunchpadPanel = (
   const t = () => railMessages.resolve([locale()]).t;
   const rail = readRailContext();
   const [query, setQuery] = createSignal("");
+  const [editorLoading, setEditorLoading] = createSignal(false);
   const messages = () => platformMessages.resolve([locale()]).t;
   const matches = (label: string, description = "") =>
     `${label} ${description}`.toLocaleLowerCase(locale()).includes(query().trim().toLocaleLowerCase(locale()));
@@ -106,14 +107,22 @@ export const AppLaunchpadPanel = (
               label={t().customize}
               tooltip={t().customize}
               tooltipDelay={0}
+              aria-busy={editorLoading() ? "true" : undefined}
               onClick={async () => {
+                if (editorLoading()) return;
+                // The editor and its validation load only when someone customizes the app bar, while this panel
+                // stays open and shows that it is busy. The button stays enabled so it keeps focus.
+                setEditorLoading(true);
+                const editor = await importOnDemand(() => import("./RailEditor"));
+                setEditorLoading(false);
+                if (!editor) return;
                 if (props.beforeSelect) {
                   if (!(await props.beforeSelect())) return;
                 } else props.close();
-                openRailEditor(locale());
+                editor.openRailEditor(locale());
               }}
             >
-              <i class="ti ti-adjustments-horizontal" aria-hidden="true" />
+              <i class={editorLoading() ? "ti ti-loader-2 animate-spin" : "ti ti-adjustments-horizontal"} aria-hidden="true" />
             </IconButton>
           </div>
         </Show>

package/src/ssr/GlobalAnnouncements.island.tsx

@@ -4,10 +4,10 @@ import {
   ANNOUNCEMENTS_COOKIE,
   ANNOUNCEMENTS_COOKIE_MAX_AGE_SECONDS,
   type AnnouncementCookieState,
-  type AnnouncementDisplayEntry,
   mergeAnnouncementCookieState,
   serializeAnnouncementCookieState,
-} from "../contracts/announcements";
+} from "../contracts/announcement-cookie";
+import type { AnnouncementDisplayEntry } from "../contracts/announcements";
 import { platformMessages } from "./platform-messages";
 
 type Props = {

package/src/ssr/GlobalSearchDialog.tsx

@@ -1,5 +1,5 @@
 import { query } from "@k2b/stdlib/solid";
-import { type DialogRender, dialogCore, toast, useLocale } from "@k2b/ui";
+import { type DialogRender, toast, useLocale } from "@k2b/ui";
 import { createEffect, createSignal, For, onCleanup, onMount } from "solid-js";
 import type { SearchItem } from "../api/search/schemas";
 import CloudResourceSearch from "../browser/CloudResourceSearch";
@@ -7,7 +7,6 @@ import { COMMANDS_CHANGED, collectContextAwareCommands } from "../browser/comman
 import { contextCommandsWithShortcuts } from "../browser/command-shortcuts";
 import { openCommand, runContextAwareCommand } from "../browser/commands";
 import type { NavigationSearchItem } from "../browser/navigation-search";
-import { resourceSearchDialogOptions } from "../browser/resource-search-dialog";
 import { resourceSearchMessages } from "../browser/resource-search-messages";
 import { type GlobalSearchOptions, requestSearchNavigation } from "../browser/search-bridge";
 import { loadSearchCommands, type PaletteCommand } from "../browser/search-commands";
@@ -139,44 +138,3 @@ export default function GlobalSearchDialog(props: GlobalSearchDialogProps) {
     </div>
   );
 }
-
-/** Owned by the layout island; neither dialog state nor callbacks cross SSR props. */
-export const createGlobalSearchHost = (searchLinks: () => NavigationSearchItem[], searchResources = true) => {
-  const [request, setRequest] = createSignal<GlobalSearchOptions>({});
-  let controller: AbortController | undefined;
-  return {
-    open: (options: GlobalSearchOptions) => {
-      setRequest({ ...options });
-      if (controller) {
-        document.querySelector<HTMLInputElement>(".cloud-global-search input[role=combobox]")?.focus();
-        return;
-      }
-      const current = new AbortController();
-      controller = current;
-      const locale = document.documentElement.lang || "en";
-      void dialogCore
-        .open<void>(
-          (close, context) => (
-            <GlobalSearchDialog
-              request={request()}
-              searchLinks={searchLinks()}
-              searchResources={searchResources}
-              close={close}
-              context={context}
-            />
-          ),
-          { ...resourceSearchDialogOptions(resourceSearchMessages.resolve([locale]).t.searchCloudResources), signal: current.signal },
-        )
-        .catch(() => {
-          toast.error(resourceSearchMessages.resolve([locale]).t.searchFailed);
-        })
-        .finally(() => {
-          if (controller === current) controller = undefined;
-        });
-    },
-    dispose: () => {
-      controller?.abort();
-      controller = undefined;
-    },
-  };
-};

package/src/ssr/GlobalSearchTrigger.island.tsx

@@ -1,11 +1,12 @@
 import { IconButton, Tooltip, useLocale } from "@k2b/ui";
 import { createEffect, onCleanup, onMount } from "solid-js";
+import { registerContextAwareCommand } from "../browser/command-bridge";
 import { attachCommandShortcuts } from "../browser/command-shortcuts";
-import { registerContextAwareCommand, runContextAwareCommand } from "../browser/commands";
 import type { NavigationSearchItem } from "../browser/navigation-search";
+import { importOnDemand } from "../browser/reload";
 import { openGlobalSearch } from "../browser/search";
 import { registerGlobalSearchHost } from "../browser/search-bridge";
-import { createGlobalSearchHost } from "./GlobalSearchDialog";
+import { createGlobalSearchHost } from "./global-search-host";
 import { platformMessages } from "./platform-messages";
 
 type GlobalSearchTriggerProps = {
@@ -26,7 +27,15 @@ export default function GlobalSearchTrigger(props: GlobalSearchTriggerProps) {
     onMount(() => {
       onCleanup(registerGlobalSearchHost(host.open, host.dispose));
     });
-    onMount(() => onCleanup(attachCommandShortcuts((command) => void runContextAwareCommand(command))));
+    // Commands, their schemas and the capability client load on the first shortcut, not with every page.
+    onMount(() =>
+      onCleanup(
+        attachCommandShortcuts(
+          (command) =>
+            void importOnDemand(() => import("../browser/commands")).then((commands) => commands?.runContextAwareCommand(command)),
+        ),
+      ),
+    );
     createEffect(() =>
       onCleanup(
         registerContextAwareCommand({

package/src/ssr/LayoutHelpTrigger.island.tsx

@@ -1,6 +1,6 @@
 import { IconButton, Tooltip, useLocale } from "@k2b/ui";
 import { createEffect, onCleanup } from "solid-js";
-import { registerContextAwareCommand } from "../browser/commands";
+import { registerContextAwareCommand } from "../browser/command-bridge";
 import type { GlobalSearchHelpApp } from "./GlobalSearchHelpDialog";
 import { openLayoutHelpDialog } from "./LayoutHelp";
 import { platformMessages } from "./platform-messages";

package/src/ssr/PwaRuntime.island.tsx

@@ -1,7 +1,7 @@
 import { observeMobileShell, syncThemeColor, type ToastHandle, toast, useLocale } from "@k2b/ui";
 import { onCleanup, onMount } from "solid-js";
 import { renewAppSession } from "../browser/app-session";
-import { PWA_SCOPE, PWA_SERVICE_WORKER_PATH } from "../contracts/pwa";
+import { PWA_SCOPE, PWA_SERVICE_WORKER_PATH } from "../contracts/pwa-paths";
 import { pwaMessages } from "./pwa-messages";
 
 /** Set once per browsing session, so the first page renews and later navigations do not. */

package/src/ssr/app-navigation.ts

@@ -1,6 +1,7 @@
+import { hasAnyAppRole } from "../_internal/app-roles";
 import type { RuntimeAppMeta } from "../contracts/app";
-import { isPwaPartId } from "../contracts/pwa";
-import { hasRole, type Role, type User } from "../contracts/shared";
+import { isPwaPartId } from "../contracts/pwa-paths";
+import type { User } from "../contracts/shared";
 import { resolveAppPresentation } from "../shared/app-presentation";
 
 export type VisibleNavigationApp = RuntimeAppMeta & {
@@ -27,14 +28,11 @@ export const hasDedicatedRuntimeRoute = (apps: readonly RuntimeAppMeta[], pathna
   return !!match && match.app.id !== currentAppId;
 };
 
-const hasAnyRole = (user: User | undefined, roles: readonly Role[] | undefined): boolean =>
-  !roles || (!!user && roles.some((role) => (role === "guest" ? user.profile === "guest" : hasRole(user, role))));
-
 /** Apps rendered in the navigation for a given authenticated user. */
 export const visibleNavigationApps = (apps: readonly RuntimeAppMeta[], user: User | undefined): VisibleNavigationApp[] =>
   apps.filter(
     (app): app is VisibleNavigationApp =>
-      !!app.nav && app.nav.section !== "hidden" && (!app.nav.requiresAuth || !!user) && hasAnyRole(user, app.nav.requiresRoles),
+      !!app.nav && app.nav.section !== "hidden" && (!app.nav.requiresAuth || !!user) && hasAnyAppRole(user, app.nav.requiresRoles),
   );
 
 export type VisiblePwaPart = RuntimeAppMeta & { pwa: NonNullable<RuntimeAppMeta["pwa"]> };
@@ -49,7 +47,7 @@ export const visiblePwaParts = (apps: readonly RuntimeAppMeta[], user: User | un
   return apps
     .filter(
       (app): app is VisiblePwaPart =>
-        !!app.pwa && isPwaPartId(app.id) && app.routes.includes(app.pwa.href) && hasAnyRole(user, app.pwa.requiresRoles),
+        !!app.pwa && isPwaPartId(app.id) && app.routes.includes(app.pwa.href) && hasAnyAppRole(user, app.pwa.requiresRoles),
     )
     .map((app) => resolveAppPresentation(app, locale))
     .sort((a, b) => a.name.localeCompare(b.name, locale) || a.id.localeCompare(b.id));

package/src/ssr/global-search-host.tsx

@@ -0,0 +1,55 @@
+import { dialogCore, toast } from "@k2b/ui";
+import { createSignal } from "solid-js";
+import type { NavigationSearchItem } from "../browser/navigation-search";
+import { importOnDemand } from "../browser/reload";
+import { resourceSearchDialogOptions } from "../browser/resource-search-dialog";
+import { resourceSearchMessages } from "../browser/resource-search-messages";
+import type { GlobalSearchOptions } from "../browser/search-bridge";
+
+/**
+ * Owned by the layout island; neither dialog state nor callbacks cross SSR props. The dialog with search, commands
+ * and their schemas loads on first open, so no page pays for it before someone searches.
+ */
+export const createGlobalSearchHost = (searchLinks: () => NavigationSearchItem[], searchResources = true) => {
+  const [request, setRequest] = createSignal<GlobalSearchOptions>({});
+  let controller: AbortController | undefined;
+  return {
+    open: (options: GlobalSearchOptions) => {
+      setRequest({ ...options });
+      if (controller) {
+        document.querySelector<HTMLInputElement>(".cloud-global-search input[role=combobox]")?.focus();
+        return;
+      }
+      const current = new AbortController();
+      controller = current;
+      const locale = document.documentElement.lang || "en";
+      void importOnDemand(() => import("./GlobalSearchDialog"))
+        .then((loaded) => {
+          if (!loaded || current.signal.aborted) return;
+          const GlobalSearchDialog = loaded.default;
+          return dialogCore.open<void>(
+            (close, context) => (
+              <GlobalSearchDialog
+                request={request()}
+                searchLinks={searchLinks()}
+                searchResources={searchResources}
+                close={close}
+                context={context}
+              />
+            ),
+            { ...resourceSearchDialogOptions(resourceSearchMessages.resolve([locale]).t.searchCloudResources), signal: current.signal },
+          );
+        })
+        .catch(() => {
+          toast.error(resourceSearchMessages.resolve([locale]).t.searchFailed);
+        })
+        .finally(() => {
+          if (controller === current) controller = undefined;
+        });
+    },
+    dispose: () => {
+      controller?.abort();
+      controller = undefined;
+    },
+  };
+};

package/src/ssr/help.ts

@@ -10,14 +10,14 @@ const manifests = new WeakMap<object, HelpManifestResult | null>();
 const log = logger("help:ssr");
 export const getLayoutHelp = (c: object): HelpManifestResult | null => manifests.get(c) ?? null;
 
-/** Explicit Help pages also work anonymously; automatic layout loading requires a user. */
+/** Help metadata for the current or an explicit app; `null` without a user or when the user may not see the app. */
 export const preloadLayoutHelp = async (c: Context, appId?: string): Promise<HelpManifestResult | null> => {
   if (manifests.has(c)) return getLayoutHelp(c);
-  if (!c.get("runtime") || (!appId && !c.get("user"))) return null;
+  if (!c.get("runtime") || !c.get("user")) return null;
   const id = appId ?? resolveCurrentApp(getRuntimeContext(c).apps, c.req.path)?.id;
   if (!id) return null;
   try {
-    const manifest = await createHelpReader(getLocale(c)).manifest(id);
+    const manifest = await createHelpReader(getLocale(c), c.get("actor")).manifest(id);
     manifests.set(c, manifest);
     return manifest;
   } catch (error) {