@k2b/cloud 0.6.0-rc.0

package/src/ssr/GlobalAnnouncements.island.tsx

@@ -0,0 +1,142 @@
+import { Button, dialogCore, MarkdownView, PanelDialog, panelDialogOptions, useLocale } from "@k2b/ui";
+import { createSignal, For, onMount, Show } from "solid-js";
+import {
+  ANNOUNCEMENTS_COOKIE,
+  ANNOUNCEMENTS_COOKIE_MAX_AGE_SECONDS,
+  type AnnouncementCookieState,
+  type AnnouncementDisplayEntry,
+  mergeAnnouncementCookieState,
+  serializeAnnouncementCookieState,
+} from "../contracts/announcements";
+import { platformMessages } from "./platform-messages";
+
+type Props = {
+  banners: AnnouncementDisplayEntry[];
+  announcements: AnnouncementDisplayEntry[];
+  latestAnnouncementVersion: number;
+  cookieState: AnnouncementCookieState;
+};
+
+const writeCookieState = (state: AnnouncementCookieState) => {
+  document.cookie = `${ANNOUNCEMENTS_COOKIE}=${serializeAnnouncementCookieState(state)}; Path=/; Max-Age=${ANNOUNCEMENTS_COOKIE_MAX_AGE_SECONDS}; SameSite=Lax`;
+};
+
+const toneClass = (tone: AnnouncementDisplayEntry["tone"]) => {
+  if (tone === "success")
+    return "border-emerald-200 bg-emerald-50 text-emerald-900 dark:border-emerald-900/60 dark:bg-emerald-950/40 dark:text-emerald-100";
+  if (tone === "warning")
+    return "border-amber-200 bg-amber-50 text-amber-950 dark:border-amber-900/60 dark:bg-amber-950/40 dark:text-amber-100";
+  if (tone === "danger") return "border-red-200 bg-red-50 text-red-950 dark:border-red-900/60 dark:bg-red-950/40 dark:text-red-100";
+  return "border-blue-200 bg-blue-50 text-blue-950 dark:border-blue-900/60 dark:bg-blue-950/40 dark:text-blue-100";
+};
+
+const toneIcon = (tone: AnnouncementDisplayEntry["tone"]) => {
+  if (tone === "success") return "ti ti-circle-check";
+  if (tone === "warning") return "ti ti-alert-triangle";
+  if (tone === "danger") return "ti ti-alert-circle";
+  return "ti ti-info-circle";
+};
+
+export default function GlobalAnnouncements(props: Props) {
+  const locale = useLocale();
+  const t = () => platformMessages.resolve([locale()]).t;
+  const [cookieState, setCookieState] = createSignal(props.cookieState);
+  const [banners, setBanners] = createSignal(props.banners);
+
+  const dismissBanner = (version: number) => {
+    const next = mergeAnnouncementCookieState(cookieState(), { dismissedBannerVersions: [version] });
+    setCookieState(next);
+    writeCookieState(next);
+    setBanners((items) => items.filter((item) => item.version !== version));
+  };
+
+  const closeAnnouncements = () => {
+    const next = mergeAnnouncementCookieState(cookieState(), {
+      seenAnnouncementVersion: props.latestAnnouncementVersion,
+    });
+    setCookieState(next);
+    writeCookieState(next);
+  };
+
+  onMount(() => {
+    if (props.announcements.length === 0) return;
+
+    void dialogCore
+      .open<void>(
+        (close) => (
+          <PanelDialog>
+            <PanelDialog.Header
+              title={t().announcements}
+              subtitle={t().latestPlatformUpdates}
+              icon="ti ti-speakerphone text-blue-500"
+              close={() => close()}
+            />
+            <PanelDialog.Body>
+              <For each={props.announcements}>
+                {(entry) => (
+                  <article class="panel-dialog-section rounded-[var(--ui-radius-surface)] p-4">
+                    <div class="mb-3 flex items-start justify-between gap-3">
+                      <div class="min-w-0">
+                        <h2 class="text-base font-semibold text-primary">{entry.title}</h2>
+                        <p class="mt-0.5 text-xs text-dimmed">
+                          {new Date(entry.publishedAt).toLocaleDateString(locale(), {
+                            year: "numeric",
+                            month: "short",
+                            day: "numeric",
+                          })}
+                        </p>
+                      </div>
+                      <span class="rounded bg-zinc-100 px-1.5 py-0.5 text-[10px] font-medium text-dimmed dark:bg-zinc-800">
+                        v{entry.version}
+                      </span>
+                    </div>
+                    <MarkdownView trustedHtml={entry.bodyHtml} />
+                  </article>
+                )}
+              </For>
+            </PanelDialog.Body>
+            <PanelDialog.Footer>
+              <span />
+              <Button size="sm" onClick={() => close()}>
+                {t().gotIt}
+              </Button>
+            </PanelDialog.Footer>
+          </PanelDialog>
+        ),
+        panelDialogOptions,
+      )
+      .then(closeAnnouncements);
+  });
+
+  return (
+    <Show when={banners().length > 0}>
+      <div class="flex shrink-0 flex-col gap-1">
+        <For each={banners()}>
+          {(banner) => (
+            <section
+              class={`flex max-h-[min(40vh,14rem)] items-start gap-2 rounded-lg border px-3 py-2 text-xs shadow-sm ${toneClass(banner.tone)}`}
+            >
+              <i class={`${toneIcon(banner.tone)} mt-0.5 shrink-0`} />
+              <div class="min-h-0 min-w-0 flex-1">
+                <p class="font-semibold">{banner.title}</p>
+                <MarkdownView
+                  trustedHtml={banner.bodyHtml}
+                  headingScale="compact"
+                  class="mt-1 max-h-36 overflow-y-auto overscroll-contain pr-1 [&_p]:my-0"
+                />
+              </div>
+              <button
+                type="button"
+                class="ml-auto inline-flex h-6 w-6 shrink-0 items-center justify-center rounded-md opacity-70 hover:bg-black/5 hover:opacity-100 dark:hover:bg-white/10"
+                aria-label={t().dismissBanner}
+                onClick={() => dismissBanner(banner.version)}
+              >
+                <i class="ti ti-x" />
+              </button>
+            </section>
+          )}
+        </For>
+      </div>
+    </Show>
+  );
+}

package/src/ssr/GlobalSearchDialog.behavior.test.tsx

@@ -0,0 +1,96 @@
+import { describe, expect, test } from "bun:test";
+import { isServer, render } from "solid-js/web";
+import { createDomTestHarness } from "../../../ui/test/dom";
+
+const deferred = <T,>() => {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((nextResolve) => {
+    resolve = nextResolve;
+  });
+  return { promise, resolve };
+};
+
+const waitFor = async (condition: () => boolean, label: string) => {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    if (condition()) return;
+    await Bun.sleep(10);
+  }
+  throw new Error(`Timed out waiting for ${label}`);
+};
+
+const searchResponse = (title: string) =>
+  Response.json({
+    query: title.toLowerCase(),
+    count: 1,
+    apps: [{ id: "notebooks", name: "Notebooks", icon: "ti ti-notebook" }],
+    items: [
+      {
+        appId: "notebooks",
+        appName: "Notebooks",
+        appIcon: "ti ti-notebook",
+        readable: true,
+        ref: { type: "notebooks.note", id: title.toLowerCase() },
+        title,
+        href: `/app/notebooks/${title.toLowerCase()}`,
+        preview: `${title} preview`,
+      },
+    ],
+  });
+
+const catalogResponse = () =>
+  Response.json({
+    query: "",
+    count: 0,
+    apps: [{ id: "notebooks", name: "Notebooks", icon: "ti ti-notebook" }],
+    items: [],
+  });
+
+describe("GlobalSearchDialog query lifecycle", () => {
+  if (isServer) {
+    test.skip("runs with browser export conditions", () => {});
+    return;
+  }
+
+  test("keeps last-good results during refresh and renders one loading indicator", async () => {
+    const dom = createDomTestHarness();
+    const originalFetch = globalThis.fetch;
+    const requests: Array<{ signal: AbortSignal; response: ReturnType<typeof deferred<Response>> }> = [];
+    globalThis.fetch = ((_input: string | URL | Request, init?: RequestInit) => {
+      const response = deferred<Response>();
+      requests.push({ signal: init?.signal as AbortSignal, response });
+      return response.promise;
+    }) as typeof fetch;
+
+    const { default: GlobalSearchDialog } = await import("./GlobalSearchDialog");
+    const dispose = render(() => <GlobalSearchDialog close={() => {}} helpApps={[]} />, dom.root);
+
+    try {
+      const input = dom.root.querySelector<HTMLInputElement>('[aria-label="Search Cloud resources"]')!;
+      await waitFor(() => requests.length === 1, "the app catalog request");
+      requests[0]!.response.resolve(catalogResponse());
+
+      input.value = "alpha";
+      input.dispatchEvent(new dom.window.Event("input", { bubbles: true }) as unknown as Event);
+      await waitFor(() => requests.length === 2, "the first debounced search");
+      requests[1]!.response.resolve(searchResponse("Alpha"));
+      await waitFor(() => dom.root.textContent?.includes("Alpha preview") ?? false, "the first result");
+
+      input.value = "beta";
+      input.dispatchEvent(new dom.window.Event("input", { bubbles: true }) as unknown as Event);
+      await waitFor(() => requests.length === 3, "the refreshed search");
+
+      expect(dom.root.textContent).toContain("Alpha preview");
+      const spinners = dom.root.querySelectorAll(".ti-loader-2.animate-spin");
+      expect(spinners).toHaveLength(1);
+      expect(spinners[0]?.closest("label")).not.toBeNull();
+
+      requests[2]!.response.resolve(searchResponse("Beta"));
+      await waitFor(() => dom.root.textContent?.includes("Beta preview") ?? false, "the refreshed result");
+      expect(dom.root.textContent).not.toContain("Alpha preview");
+    } finally {
+      dispose();
+      globalThis.fetch = originalFetch;
+      dom.cleanup();
+    }
+  });
+});

package/src/ssr/GlobalSearchDialog.tsx

@@ -0,0 +1,35 @@
+import { dialogCore, useLocale } from "@k2b/ui";
+import type { SearchItem } from "../api/search/schemas";
+import CloudResourceSearch from "../browser/CloudResourceSearch";
+import { type GlobalSearchHelpApp, openGlobalSearchHelpDialog } from "./GlobalSearchHelpDialog";
+
+type GlobalSearchDialogProps = {
+  close: () => void;
+  helpApps: GlobalSearchHelpApp[];
+};
+
+export default function GlobalSearchDialog(props: GlobalSearchDialogProps) {
+  const locale = useLocale();
+  const openHelp = () => {
+    props.close();
+    queueMicrotask(() => openGlobalSearchHelpDialog(props.helpApps, locale()));
+  };
+
+  const openItem = (item: SearchItem) => {
+    props.close();
+    window.location.href = item.href;
+  };
+
+  return <CloudResourceSearch helpApps={props.helpApps} onHelp={openHelp} onSelect={openItem} />;
+}
+
+export const openGlobalSearchDialog = (helpApps: GlobalSearchHelpApp[] = []) => {
+  if (dialogCore.isOpen()) return;
+
+  void dialogCore.open<void>((close) => <GlobalSearchDialog close={close} helpApps={helpApps} />, {
+    panelClassName:
+      "fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 m-0 h-[var(--spotlight-dialog-height)] w-[min(var(--ui-dialog-available-width),72rem)] [--spotlight-dialog-height:min(50vh,var(--ui-dialog-available-height))] overflow-hidden overscroll-y-contain rounded-2xl border-0 bg-white/92 p-0 text-zinc-900 shadow-xl ring-1 ring-inset ring-zinc-300/60 backdrop:bg-black/35 backdrop:backdrop-blur-sm dark:bg-zinc-950/92 dark:text-zinc-100 dark:ring-zinc-700/60 [@media(min-height:1100px)]:[--spotlight-dialog-height:min(33vh,var(--ui-dialog-available-height))]",
+    contentClassName: "h-full min-h-0",
+    initialFocus: "none",
+  });
+};

package/src/ssr/GlobalSearchHelpDialog.tsx

@@ -0,0 +1,104 @@
+import { prompts, ScrollArea, useLocale } from "@k2b/ui";
+import { createMemo, For, Show } from "solid-js";
+import { platformMessages } from "./platform-messages";
+
+export type GlobalSearchHelpApp = {
+  appId: string;
+  appName: string;
+  appIcon: string;
+  tags: string[];
+  help?: string;
+  tagHelp?: Array<{ tag: string; help: string }>;
+};
+
+type GlobalSearchHelpDialogProps = { apps: GlobalSearchHelpApp[] };
+
+export default function GlobalSearchHelpDialog(props: GlobalSearchHelpDialogProps) {
+  const locale = useLocale();
+  const t = () => platformMessages.resolve([locale()]).t;
+  const apps = createMemo(() =>
+    props.apps
+      .filter((app) => app.tags.length > 0)
+      .map((app) => ({
+        ...app,
+        help: app.help?.trim() || undefined,
+        tags: [...new Set(app.tags.map((tag) => tag.toLowerCase()))].sort(),
+        tagHelp: [...new Map((app.tagHelp ?? []).map((entry) => [entry.tag.trim().toLowerCase(), entry.help.trim()])).entries()]
+          .filter(([tag, help]) => tag.length > 0 && help.length > 0)
+          .map(([tag, help]) => ({ tag, help })),
+      }))
+      .sort((a, b) => a.appName.localeCompare(b.appName)),
+  );
+
+  return (
+    <div class="flex max-h-[min(42rem,var(--ui-dialog-available-height))] min-h-0 flex-col gap-4 text-zinc-900 dark:text-zinc-100">
+      <div class="flex items-start justify-between gap-3">
+        <div>
+          <p class="text-sm text-dimmed">{t().searchTagsDescription({ tag: "#tag" })}</p>
+        </div>
+      </div>
+
+      <ScrollArea class="min-h-0 flex-1 pr-1">
+        <div class="flex flex-col gap-2">
+          <For each={apps()}>
+            {(app) => (
+              <section class="rounded-lg ring-1 ring-inset ring-zinc-200 dark:ring-zinc-800 p-3 bg-zinc-50/50 dark:bg-zinc-900/35">
+                <header class="flex items-center gap-2 text-sm">
+                  <i class={app.appIcon} />
+                  <span>{app.appName}</span>
+                </header>
+                <Show when={app.help}>
+                  <p class="mt-1 text-xs text-dimmed">{app.help}</p>
+                </Show>
+                <Show
+                  when={(app.tagHelp?.length ?? 0) > 0}
+                  fallback={
+                    <p class="mt-1 text-xs text-dimmed">
+                      {t().tags}:{" "}
+                      <For each={app.tags}>
+                        {(tag, index) => (
+                          <>
+                            <code>#{tag}</code>
+                            <Show when={index() < app.tags.length - 1}>, </Show>
+                          </>
+                        )}
+                      </For>
+                    </p>
+                  }
+                >
+                  <div class="mt-2 space-y-1 text-xs">
+                    <For each={app.tagHelp}>
+                      {(entry) => (
+                        <div class="grid grid-cols-[6rem_minmax(0,1fr)] gap-2">
+                          <code>#{entry.tag}</code>
+                          <span class="text-dimmed">{entry.help}</span>
+                        </div>
+                      )}
+                    </For>
+                  </div>
+                </Show>
+              </section>
+            )}
+          </For>
+          <Show when={apps().length === 0}>
+            <div class="rounded-lg ring-1 ring-inset ring-zinc-200 dark:ring-zinc-800 p-3 text-xs text-dimmed bg-zinc-50/50 dark:bg-zinc-900/35">
+              {t().noAppSearchTags}
+            </div>
+          </Show>
+        </div>
+      </ScrollArea>
+    </div>
+  );
+}
+
+export const openGlobalSearchHelpDialog = (
+  apps: GlobalSearchHelpApp[],
+  locale = typeof document === "undefined" ? "en" : document.documentElement.lang || "en",
+) => {
+  const t = platformMessages.resolve([locale]).t;
+  void prompts.dialog<void>(() => <GlobalSearchHelpDialog apps={apps} />, {
+    title: t.searchTags,
+    icon: "ti ti-help-circle",
+    size: "large",
+  });
+};

package/src/ssr/GlobalSearchTrigger.island.tsx

@@ -0,0 +1,55 @@
+import { hotkeys } from "@k2b/stdlib/solid";
+import { IconButton, Tooltip, useLocale } from "@k2b/ui";
+import { openGlobalSearchDialog } from "./GlobalSearchDialog";
+import type { GlobalSearchHelpApp } from "./GlobalSearchHelpDialog";
+import { platformMessages } from "./platform-messages";
+
+type GlobalSearchTriggerProps = {
+  variant: "header" | "rail";
+  class?: string;
+  registerHotkey?: boolean;
+  searchHelpApps?: GlobalSearchHelpApp[];
+};
+
+/** Opens the spotlight-style global search dialog from nav/header trigger points. */
+export default function GlobalSearchTrigger(props: GlobalSearchTriggerProps) {
+  const locale = useLocale();
+  const t = () => platformMessages.resolve([locale()]).t;
+  const searchHelpApps = props.searchHelpApps ?? [];
+
+  if (props.registerHotkey) {
+    hotkeys.create(() => ({
+      "mod+k": {
+        label: t().openGlobalSearch,
+        desc: t().globalSearchDescription,
+        run: () => openGlobalSearchDialog(searchHelpApps),
+      },
+    }));
+  }
+
+  if (props.variant === "rail")
+    return (
+      <Tooltip.Trigger
+        type="button"
+        class={`rail-item text-blue-500 hover:bg-blue-500/10 hover:text-blue-600 dark:text-blue-400 dark:hover:bg-blue-500/15 dark:hover:text-blue-300 ${props.class ?? ""}`}
+        onClick={() => openGlobalSearchDialog(searchHelpApps)}
+        aria-label={t().openGlobalSearch}
+        placement="right"
+        delay={0}
+        content={t().searchShortcut}
+      >
+        <i class="ti ti-search text-base" />
+      </Tooltip.Trigger>
+    );
+
+  return (
+    <IconButton
+      class={props.class}
+      onClick={() => openGlobalSearchDialog(searchHelpApps)}
+      label={t().openGlobalSearch}
+      title={t().searchShortcut}
+    >
+      <i class="ti ti-search text-base" />
+    </IconButton>
+  );
+}

package/src/ssr/HotkeysHelpRail.island.tsx

@@ -0,0 +1,55 @@
+import { hotkeys } from "@k2b/stdlib/solid";
+import { IconButton, Tooltip, useLocale } from "@k2b/ui";
+import type { GlobalSearchHelpApp } from "./GlobalSearchHelpDialog";
+import { openLayoutHelpDialog } from "./LayoutHelp";
+import { platformMessages } from "./platform-messages";
+
+type HotkeysHelpTriggerProps = {
+  variant: "header" | "rail";
+  class?: string;
+  registerHotkey?: boolean;
+  searchHelpApps?: GlobalSearchHelpApp[];
+  accent?: string;
+};
+
+/** Opens end-user help from either the desktop rail or the compact header. */
+export default function HotkeysHelpRail(props: HotkeysHelpTriggerProps) {
+  const locale = useLocale();
+  const t = () => platformMessages.resolve([locale()]).t;
+  const searchHelpApps = props.searchHelpApps ?? [];
+
+  const openHelp = () => {
+    openLayoutHelpDialog(searchHelpApps, props.accent);
+  };
+
+  if (props.registerHotkey) {
+    hotkeys.create(() => ({
+      "shift+/": {
+        label: t().openShortcutHelp,
+        desc: t().shortcutHelpDescription,
+        run: openHelp,
+      },
+    }));
+  }
+
+  if (props.variant === "rail")
+    return (
+      <Tooltip.Trigger
+        type="button"
+        class={`rail-item text-blue-500 hover:bg-blue-500/10 hover:text-blue-600 dark:text-blue-400 dark:hover:bg-blue-500/15 dark:hover:text-blue-300 ${props.class ?? ""}`}
+        onClick={openHelp}
+        aria-label={t().openHelp}
+        placement="right"
+        delay={0}
+        content={t().helpShortcut}
+      >
+        <i class="ti ti-help-circle text-base" />
+      </Tooltip.Trigger>
+    );
+
+  return (
+    <IconButton class={props.class} onClick={openHelp} label={t().openHelp} title={t().helpShortcut}>
+      <i class="ti ti-help-circle text-base" />
+    </IconButton>
+  );
+}

package/src/ssr/Layout.render.test.tsx

@@ -0,0 +1,148 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { createConfig } from "@k2b/ssr";
+import { Hono } from "hono";
+import { createComponent } from "solid-js";
+
+const root = mkdtempSync(resolve(tmpdir(), "cloud-layout-render-tests-"));
+const { plugin } = createConfig({ dev: true, rootDir: root });
+Bun.plugin(plugin());
+process.once("exit", () => rmSync(root, { recursive: true, force: true }));
+
+const { defineApp } = await import("../_internal/define-app");
+const { default: Layout } = await import("./Layout");
+const { default: MinimalLayout } = await import("./MinimalLayout");
+const { default: AdminLayout } = await import("./AdminLayout");
+
+const app = defineApp({
+  id: "layout-render-probe",
+  name: "Layout render probe",
+  icon: "ti ti-layout",
+  description: "Anonymous and minimal layout render probe",
+  baseUrl: "http://layout-render-probe:3000",
+  routes: ["/layout", "/minimal"],
+});
+
+type LayoutContextArg = Parameters<typeof Layout>[0]["c"];
+type MinimalLayoutContextArg = Parameters<typeof MinimalLayout>[0]["c"];
+type PreferencePosition = Exclude<Parameters<typeof MinimalLayout>[0]["preferences"], false | undefined>;
+const preferencePositions: PreferencePosition[] = ["top-left", "top-right", "bottom-left", "bottom-right"];
+
+const server = new Hono()
+  .use("*", async (c, next) => {
+    c.set("runtime" as never, { apps: [] } as never);
+    await next();
+  })
+  .get(
+    "/admin",
+    ...app.ssr(
+      (c) => () =>
+        createComponent(AdminLayout, {
+          c,
+          title: "Settings",
+          scroll: c.req.query("scroll") !== "false",
+          children: "Admin content",
+        }),
+    ),
+  )
+  .get(
+    "/layout",
+    ...app.ssr(
+      (c) => () =>
+        createComponent(Layout, {
+          c: c as unknown as LayoutContextArg,
+          fullPage: true,
+          title: "Public tools",
+          children: "Anonymous content",
+        }),
+    ),
+  )
+  .get(
+    "/minimal/:position",
+    ...app.ssr((c) => {
+      const requested = c.req.param("position");
+      const preferences = preferencePositions.find((position) => position === requested) ?? false;
+      return () =>
+        createComponent(MinimalLayout, {
+          c: c as unknown as MinimalLayoutContextArg,
+          preferences,
+          children: "Minimal content",
+        });
+    }),
+  );
+
+describe("Cloud layouts SSR", () => {
+  test("admin shell is viewport-bound and delegates scrolling only when requested", async () => {
+    const ordinary = await (await server.request("/admin")).text();
+    const bounded = await (await server.request("/admin?scroll=false")).text();
+    for (const html of [ordinary, bounded]) {
+      expect(html).toContain("h-dvh overflow-hidden");
+      expect(html).toContain("Admin content");
+      expect(html).toContain('data-scroll-preserve="admin-sidebar"');
+    }
+    expect(ordinary).not.toMatch(/k2b-app-workspace__main[^>]+data-scroll="false"/);
+    expect(bounded).toMatch(/k2b-app-workspace__main[^>]+data-scroll="false"/);
+    expect(bounded).not.toContain("p-[var(--ui-space-shell)]");
+  });
+  test("keeps anonymous login and preferences visible without rendering the application rail", async () => {
+    const response = await server.request("/layout", {
+      headers: { Cookie: "theme=dark", "Accept-Language": "de-CH" },
+    });
+    const html = await response.text();
+
+    expect(response.status).toBe(200);
+    expect(html).toContain('<html lang="de-CH" class="dark"');
+    expect(html).toContain("layout-header");
+    expect(html).toContain('href="/auth/login"');
+    expect(html).toContain("Anmelden");
+    expect(html).toContain("Darstellung und Sprache");
+    expect(html).toContain("Heller Modus");
+    expect(html).toContain("English");
+    expect(html).not.toContain("layout-rail-navigation");
+    expect(html).not.toContain('data-layout-authenticated="true"');
+    expect(html).not.toContain('href="/me"');
+  });
+
+  test("positions minimal preferences in every supported corner without adding Cloud chrome", async () => {
+    const expectedMenuPositions = {
+      "top-left": "bottom-right",
+      "top-right": "bottom-left",
+      "bottom-left": "top-right",
+      "bottom-right": "top-left",
+    } as const;
+
+    for (const position of preferencePositions) {
+      const response = await server.request(`/minimal/${position}`, { headers: { "Accept-Language": "en" } });
+      const html = await response.text();
+      expect(response.status).toBe(200);
+      expect(html).toContain(`minimal-layout-preferences--${position}`);
+      expect(html).toContain(`data-position="${expectedMenuPositions[position]}"`);
+      expect(html).toContain("Appearance and language");
+      expect(html).toContain("Minimal content");
+      expect(html).not.toContain("cloud-app-canvas");
+      expect(html).not.toContain("layout-header");
+      expect(html).not.toContain("layout-rail");
+    }
+  });
+
+  test("can disable the minimal preference control completely", async () => {
+    const response = await server.request("/minimal/off");
+    const html = await response.text();
+
+    expect(response.status).toBe(200);
+    expect(html).toContain("Minimal content");
+    expect(html).not.toContain("minimal-layout-preferences");
+    expect(html).not.toContain("Appearance and language");
+  });
+
+  test("keeps every corner safe-area aware", async () => {
+    const css = await Bun.file(new URL("../styles/utilities-navigation.css", import.meta.url)).text();
+    for (const position of preferencePositions) expect(css).toContain(`.minimal-layout-preferences--${position}`);
+    expect(css).toContain("env(safe-area-inset-top)");
+    expect(css).toContain("env(safe-area-inset-right)");
+    expect(css).toContain("env(safe-area-inset-bottom)");
+    expect(css).toContain("env(safe-area-inset-left)");
+  });
+});