@k2b/cloud 0.38.0 → 0.39.0

package/src/ssr/compact-shell.browser-harness.ts

@@ -0,0 +1,431 @@
+import { afterAll, beforeAll, setDefaultTimeout, spyOn } 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 tailwind from "bun-plugin-tailwind";
+import type { Browser, BrowserContext, Page } from "playwright";
+import { createComponent } from "solid-js";
+import type { launchBrowser } from "../../../ui/test/browser";
+
+// The shell's geometry at every width — which chrome exists, where the app
+// area ends, which edges draw lines — is decided by real layout, so a real
+// engine loads the server-rendered Layout with the global stylesheet and the
+// shared workspace controller, as Cloud serves them.
+const root = mkdtempSync(resolve(tmpdir(), "cloud-compact-shell-browser-"));
+const { plugin } = createConfig({ dev: true, rootDir: root });
+Bun.plugin(plugin());
+process.once("exit", () => rmSync(root, { recursive: true, force: true }));
+
+const { Hono } = await import("hono");
+const { AppWorkspace, Button, ScrollArea } = await import("@k2b/ui");
+const { defineApp } = await import("../_internal/define-app");
+const { person } = await import("../_internal/define-app.test-fixture");
+const railSnapshot = await import("../services/rail-snapshot");
+const settingsMiddleware = await import("../server/middleware/settings");
+const { defaultRailPreferences } = await import("../contracts/rail-preferences");
+const { default: WorkspaceNavigation } = await import("./WorkspaceNavigation.island");
+const { default: Layout } = await import("./Layout");
+
+const probe = defineApp({
+  id: "compact-shell-probe",
+  name: "Compact shell probe",
+  icon: "ti ti-layout",
+  description: "Shell geometry probe",
+  baseUrl: "http://compact-shell-probe:3000",
+  routes: ["/app/mail"],
+});
+const extraApps = ["Amber", "Birch", "Cedar", "Dune", "Elm"].map((name) => ({
+  id: name.toLowerCase(),
+  name,
+  icon: "ti ti-box",
+  description: `${name} demo`,
+  routes: [`/app/${name.toLowerCase()}`],
+  nav: { href: `/app/${name.toLowerCase()}`, section: "primary" },
+}));
+const apps = [
+  {
+    id: "mail",
+    name: "Mail",
+    icon: "ti ti-mail",
+    description: "Read and write mail",
+    routes: ["/app/mail"],
+    nav: { href: "/app/mail", section: "primary" },
+  },
+  {
+    id: "pwa",
+    name: "Phone app",
+    icon: "ti ti-device-mobile",
+    description: "Phone app",
+    routes: ["/pwa"],
+    nav: { href: "/pwa", section: "hidden" },
+  },
+];
+
+type LayoutContextArg = Parameters<typeof Layout>[0]["c"];
+
+/** A mail-like workspace: navigation, a list pane beside the reader, and a detail panel. Invented content. */
+const workspace = (selected: string) =>
+  createComponent(AppWorkspace, {
+    mobileSurface: "flush",
+    class: "min-h-0 flex-1",
+    get children() {
+      return [
+        createComponent(AppWorkspace.Sidebar, {
+          id: "mail-navigation",
+          label: "Mailboxes",
+          get children() {
+            return createComponent(AppWorkspace.SidebarDesktop, {
+              get children() {
+                return createComponent(AppWorkspace.SidebarBody, {
+                  get children() {
+                    return ["inbox", "archive", "sent"].map((id) =>
+                      createComponent(AppWorkspace.SidebarItem, {
+                        href: `#${id}`,
+                        icon: "ti ti-inbox",
+                        active: id === selected,
+                        children: id[0]!.toUpperCase() + id.slice(1),
+                      }),
+                    );
+                  },
+                });
+              },
+            });
+          },
+        }),
+        createComponent(AppWorkspace.Content, {
+          get children() {
+            return [
+              createComponent(AppWorkspace.Main, {
+                get children() {
+                  return [
+                    createComponent(AppWorkspace.MainPane, { id: "messages", label: "Messages", children: "Quarterly numbers" }),
+                    `Reader for ${selected}`,
+                  ];
+                },
+              }),
+              createComponent(AppWorkspace.Detail, { id: "message-detail", open: true, width: "sm", children: "Sender details" }),
+            ];
+          },
+        }),
+      ];
+    },
+  });
+
+/**
+ * A task-list page: a long list in Main and an open detail that the server renders with its own close
+ * control, as Contacts and Capabilities do. Invented content.
+ */
+const listWorkspace = () =>
+  createComponent(AppWorkspace, {
+    class: "min-h-0 flex-1",
+    get children() {
+      return createComponent(AppWorkspace.Content, {
+        get children() {
+          return [
+            createComponent(AppWorkspace.Main, {
+              get children() {
+                return Array.from({ length: 80 }, (_, index) =>
+                  createComponent(Button, { class: "list-row", align: "start", children: `Task ${index + 1}` }),
+                );
+              },
+            }),
+            createComponent(AppWorkspace.Detail, {
+              id: "task-detail",
+              open: true,
+              get children() {
+                return createComponent(Button, { "data-workspace-detail-close": "", children: "Close task" });
+              },
+            }),
+          ];
+        },
+      });
+    },
+  });
+
+/** A sidebar-first overview that is the page itself, as Mail and Notebooks render. Invented content. */
+const overviewWorkspace = () =>
+  createComponent(AppWorkspace, {
+    mobileSurface: "flush",
+    flat: true,
+    resizable: false,
+    get children() {
+      return [
+        createComponent(AppWorkspace.Sidebar, {
+          id: "overview-navigation",
+          label: "Mailboxes",
+          get children() {
+            return createComponent(AppWorkspace.SidebarDesktop, {
+              get children() {
+                return createComponent(AppWorkspace.SidebarBody, {
+                  get children() {
+                    return ["Personal", "Projects", "Support"].map((name) =>
+                      createComponent(AppWorkspace.SidebarItem, { href: `#${name.toLowerCase()}`, children: name }),
+                    );
+                  },
+                });
+              },
+            });
+          },
+        }),
+        createComponent(AppWorkspace.Content, {
+          get children() {
+            return createComponent(AppWorkspace.Main, {
+              get children() {
+                return Array.from({ length: 80 }, (_, index) =>
+                  createComponent(Button, { class: "overview-row", align: "start", children: `Message ${index + 1}` }),
+                );
+              },
+            });
+          },
+        }),
+      ];
+    },
+  });
+
+const server = new Hono()
+  .get(
+    "/",
+    async (c, next) => {
+      c.set("runtime" as never, { apps } as never);
+      c.set("user" as never, person as never);
+      await next();
+    },
+    ...probe.ssr((c) => () => createComponent(Layout, { c: c as unknown as LayoutContextArg, title: "Start", children: "Start content" })),
+  )
+  .get(
+    "/app/mail/:folder",
+    async (c, next) => {
+      // `?name=` renames Mail, for a long app name in the phone header.
+      const name = c.req.query("name");
+      const catalog = c.req.query("catalog") ? [...extraApps, ...apps] : apps;
+      c.set("runtime" as never, { apps: name ? catalog.map((app) => (app.id === "mail" ? { ...app, name } : app)) : catalog } as never);
+      // A missing last name shows the profile notice above the app.
+      c.set("user" as never, (c.req.query("notice") ? { ...person, sn: "" } : person) as never);
+      await next();
+    },
+    ...probe.ssr((c) => {
+      const folder = c.req.param("folder") ?? "inbox";
+      const title = folder[0]!.toUpperCase() + folder.slice(1);
+      if (c.req.query("navigation"))
+        return () =>
+          createComponent(Layout, {
+            c: c as unknown as LayoutContextArg,
+            title: [{ title: "Home", href: "/" }, { title: "Mail" }],
+            get children() {
+              return [
+                createComponent(WorkspaceNavigation, { label: "Mail", items: [{ id: "inbox", label: "Inbox", href: "/app/mail/inbox" }] }),
+                overviewWorkspace(),
+              ];
+            },
+          });
+      // `?overview=` keeps regular Layout props, including its page scroller's gutter.
+      if (c.req.query("overview"))
+        return () =>
+          createComponent(Layout, {
+            c: c as unknown as LayoutContextArg,
+            title: [{ title: "Home", href: "/" }, { title: "Mail" }],
+            get children() {
+              return overviewWorkspace();
+            },
+          });
+      // `?plain=` renders a regular page without a workspace or scroll area: `main` is its page scroller.
+      if (c.req.query("plain"))
+        return () =>
+          createComponent(Layout, {
+            c: c as unknown as LayoutContextArg,
+            title: [{ title: "Home", href: "/" }, { title: "Settings" }],
+            get children() {
+              return Array.from({ length: 60 }, (_, index) =>
+                createComponent(Button, { class: "plain-row w-full", align: "start", children: `Setting ${index + 1}` }),
+              );
+            },
+          });
+      // `?cards=` renders a page without a workspace that scrolls its content in a ScrollArea, as
+      // Capabilities and Weather do.
+      if (c.req.query("cards"))
+        return () =>
+          createComponent(Layout, {
+            c: c as unknown as LayoutContextArg,
+            fullWidth: true,
+            title: [{ title: "Home", href: "/" }, { title: "Capabilities" }],
+            get children() {
+              return createComponent(ScrollArea, {
+                class: "min-h-0 min-w-0 flex-1",
+                get children() {
+                  return Array.from({ length: 60 }, (_, index) =>
+                    createComponent(Button, { class: "card-row w-full", align: "start", children: `App ${index + 1}` }),
+                  );
+                },
+              });
+            },
+          });
+      // `?list=` renders the task list: `scroll` in a page that grows with its content, `page` in a full page.
+      const list = c.req.query("list");
+      if (list)
+        return () =>
+          createComponent(Layout, {
+            c: c as unknown as LayoutContextArg,
+            fullWidth: true,
+            fullPage: list === "page",
+            title: [{ title: "Home", href: "/" }, { title: "Tasks" }],
+            get children() {
+              return listWorkspace();
+            },
+          });
+      return () =>
+        createComponent(Layout, {
+          c: c as unknown as LayoutContextArg,
+          fullWidth: true,
+          fullPage: true,
+          title: [{ title: "Home", href: "/" }, { title: "Mail", href: "/app/mail" }, { title }],
+          get children() {
+            return workspace(folder);
+          },
+        });
+    }),
+  )
+  .get(
+    "/public",
+    async (c, next) => {
+      c.set("runtime" as never, { apps } as never);
+      await next();
+    },
+    ...probe.ssr(
+      (c) => () =>
+        createComponent(Layout, {
+          c: c as unknown as LayoutContextArg,
+          title: [{ title: "Home", href: "/" }, { title: c.req.query("title") ?? "Public tools" }],
+          get children() {
+            if (c.req.query("cards"))
+              return createComponent(ScrollArea, {
+                get children() {
+                  return Array.from({ length: 60 }, (_, index) =>
+                    createComponent(Button, { class: "card-row", children: `App ${index + 1}` }),
+                  );
+                },
+              });
+            return c.req.query("overview") ? overviewWorkspace() : "Public content";
+          },
+        }),
+    ),
+  );
+
+let browser: Browser;
+let css: string;
+let controller: string;
+const spies: { mockRestore(): void }[] = [];
+// Register hooks in each importing test file; Bun caches this module across files.
+// Keeping hooks at module scope would leave the second file with a closed browser.
+/**
+ * Each suite passes `launchBrowser` from packages/ui/test/browser itself, so the test runner and the
+ * browser-launch check find it as a browser suite and the gate also runs it in WebKit.
+ */
+export function installCompactShellHarness(launch: typeof launchBrowser) {
+  // Several tests walk every device, each in a fresh browser context. Bun scopes the default timeout to
+  // the test file that sets it, and this module runs once per process, so each suite sets it here.
+  setDefaultTimeout(30_000);
+  beforeAll(async () => {
+    spies.push(
+      spyOn(railSnapshot, "readRailSnapshot").mockResolvedValue(defaultRailPreferences()),
+      spyOn(settingsMiddleware, "preloadLayoutAnnouncements").mockResolvedValue(undefined),
+    );
+    const build = await Bun.build({ entrypoints: [resolve(import.meta.dir, "../../../../styles.css")], plugins: [tailwind] });
+    if (!build.success) throw new AggregateError(build.logs, "Could not compile the global stylesheet.");
+    css = await build.outputs[0]!.text();
+    // Cloud installs the shared workspace controller once for the document; the
+    // test installs the same export from the shipped browser build.
+    const entry = resolve(import.meta.dir, "compact-shell.controller.ts");
+    const bundle = await Bun.build({
+      entrypoints: [entry],
+      files: {
+        [entry]: `import { installAppWorkspaceController } from ${JSON.stringify(resolve(import.meta.dir, "../../../ui/dist/browser/index.js"))};
+window.installController = () => installAppWorkspaceController();`,
+      },
+      target: "browser",
+      format: "iife",
+    });
+    if (!bundle.success) throw new AggregateError(bundle.logs, "Could not bundle the workspace controller.");
+    controller = await bundle.outputs[0]!.text();
+    browser = await launch();
+  }, 60_000);
+  afterAll(async () => {
+    for (const spy of spies.splice(0)) spy.mockRestore();
+    await browser?.close();
+  });
+}
+
+export type Device = { name: string; width: number; height: number; touch: boolean };
+export const phone: Device = { name: "phone", width: 390, height: 844, touch: true };
+export const ipadSplitView: Device = { name: "iPad Split View", width: 694, height: 834, touch: true };
+export const ipadPortrait: Device = { name: "iPad portrait", width: 834, height: 1194, touch: true };
+export const smallLaptop: Device = { name: "small laptop", width: 1024, height: 768, touch: false };
+export const ipadLandscape: Device = { name: "iPad landscape", width: 1194, height: 834, touch: true };
+export const laptop: Device = { name: "laptop", width: 1440, height: 900, touch: false };
+export const desktop: Device = { name: "desktop", width: 1920, height: 1080, touch: false };
+export const devices = [phone, ipadSplitView, ipadPortrait, smallLaptop, ipadLandscape, laptop, desktop];
+export const tabletBoundary: Device = { name: "tablet boundary", width: 1023, height: 768, touch: false };
+
+// The signed-in card's spacing and radius in whole pixels: 4 and 10 px at 1024 px, 8 and 14 px from 1440 px.
+export const cardInset = (width: number) => Math.round(Math.min(8, Math.max(4, 4 + (width - 1024) / 104)));
+export const cardRadius = (width: number) => Math.round(Math.min(14, Math.max(10, 10 + (width - 1024) / 104)));
+
+export type Options = {
+  language?: "en" | "de";
+  theme?: "light" | "dark";
+  notice?: boolean;
+  style?: string;
+  insets?: Partial<Record<"top" | "right" | "bottom" | "left", number>>;
+};
+// Match the existing app-canvas safe-area fixture: engines cannot override env().
+export const withInsets = (stylesheet: string, insets: Options["insets"] = {}) => {
+  for (const [side, inset] of Object.entries(insets)) {
+    const pattern = new RegExp(`env\\(\\s*safe-area-inset-${side}\\s*(?:,\\s*0px\\s*)?\\)`, "g");
+    if (!pattern.test(stylesheet)) throw new Error(`Missing safe-area-inset-${side}`);
+    stylesheet = stylesheet.replace(pattern, `${inset}px`);
+  }
+  return stylesheet;
+};
+export const html = async (path: string, options: Options = {}) => {
+  const headers = {
+    "Accept-Language": options.language ?? "en",
+    Cookie: `theme=${options.theme ?? "light"}`,
+  };
+  const markup = await (await server.request(path, { headers })).text();
+  const clean = new HTMLRewriter()
+    .on('script[src], script[type="module"]', { element: (element) => void element.remove() })
+    .on('link[rel="stylesheet"], link[rel="preload"], link[rel="modulepreload"]', { element: (element) => void element.remove() })
+    .transform(markup);
+  return clean.replace(
+    "</head>",
+    `<style>${withInsets(css, options.insets)}</style><style>*,*::before,*::after{transition:none!important;animation:none!important}${options.style ?? ""}</style></head>`,
+  );
+};
+
+/** Attaches the controller as Cloud's island does after the first paint, and lets its first frame run. */
+export const attach = async (page: Page) => {
+  await page.addScriptTag({ content: controller });
+  await page.evaluate(async () => {
+    (window as unknown as { installController: () => void }).installController();
+    await new Promise((settle) => requestAnimationFrame(() => requestAnimationFrame(settle)));
+  });
+};
+
+export const open = async (
+  device: Device,
+  path: string,
+  options: Options & { attached?: boolean } = {},
+): Promise<{ context: BrowserContext; page: Page }> => {
+  // iPads and phones report a coarse pointer without hover, as Safari does. A page set from markup has
+  // no cookies in WebKit, so the theme script follows the system scheme; it matches the requested theme.
+  const context = await browser.newContext({
+    viewport: { width: device.width, height: device.height },
+    hasTouch: device.touch,
+    isMobile: device.touch,
+    colorScheme: options.theme ?? "light",
+  });
+  const page = await context.newPage();
+  await page.setContent(await html(path, options));
+  if (options.attached !== false) await attach(page);
+  return { context, page };
+};

package/src/ssr/index.ts

@@ -4,9 +4,11 @@
 export { default as AdminLayout } from "./AdminLayout";
 export {
   hasDedicatedRuntimeRoute,
+  type PanelProvider,
   resolveRuntimeRoute,
   type VisiblePwaPart,
   visibleNavigationApps,
+  visiblePanelProviders,
   visiblePwaParts,
 } from "./app-navigation";
 export { default as Layout } from "./Layout";
@@ -15,6 +17,7 @@ export {
   type MinimalLayoutPreferencePosition,
   type MinimalLayoutProps,
 } from "./MinimalLayout";
+export { default as PanelLayout, type PanelLayoutProps } from "./PanelLayout";
 export { default as PwaLayout, type PwaLayoutProps } from "./PwaLayout";
 export { requestPath } from "./request-path";
 export { getLocalizedRuntimeContext, getRuntimeContext, type RuntimeContext } from "./runtime";

package/src/ssr/panel-slot.browser-harness.tsx

@@ -0,0 +1,110 @@
+import { AppWorkspace } from "@k2b/ui";
+import { Hono } from "hono";
+import { defineApp } from "../_internal/define-app";
+import { person } from "../_internal/define-app.test-fixture";
+import type { RuntimeAppMeta } from "../contracts/app";
+import type { User } from "../contracts/shared";
+import Layout from "./Layout";
+import PanelLayout from "./PanelLayout";
+import type { RuntimeContext } from "./runtime";
+
+const apps: RuntimeAppMeta[] = ["fixture", "second"].map((id) => ({
+  id,
+  name: id === "fixture" ? "Fixture" : "Second",
+  icon: "ti ti-box",
+  description: "Panel browser fixture",
+  routes: [`/app/${id}`],
+  nav: { href: `/app/${id}`, section: "primary" },
+  panel: { href: `/app/${id}/panel`, label: id === "fixture" ? "Fixture" : "Second", icon: "ti ti-box" },
+}));
+const probe = defineApp({
+  id: "fixture",
+  name: "Fixture",
+  icon: "ti ti-box",
+  description: "Panel browser fixture",
+  baseUrl: "http://fixture:3000",
+  routes: ["/app/fixture", "/app/second"],
+});
+type Environment = { Variables: { runtime: RuntimeContext; user: User } };
+export const server = new Hono<Environment>()
+  .use(async (c, next) => {
+    c.set("runtime", { apps });
+    c.set("user", person);
+    await next();
+  })
+  .get(
+    "/app/:provider/panel",
+    ...probe.ssr<Environment>((c) => () => (
+      <PanelLayout c={c} title="Fixture panel">
+        <label>
+          Panel input
+          <input aria-label="Panel input" />
+        </label>
+        <button type="button" id="prevent-escape">
+          Keep Escape
+        </button>
+        <a href="/app/fixture/next" id="leave-panel">
+          Open in the app
+        </a>
+      </PanelLayout>
+    )),
+  )
+  .get(
+    "/app/fixture/long",
+    ...probe.ssr<Environment>((c) => () => (
+      <Layout c={c} title="Long fixture">
+        <button type="button" id="open-panel">
+          Open fixture
+        </button>
+        <button type="button" id="open-silent-panel">
+          Open silent fixture
+        </button>
+        <div style="height:150vh">Long content</div>
+        <p id="last-row">Last row</p>
+      </Layout>
+    )),
+  )
+  .get(
+    "/app/fixture/:page?",
+    ...probe.ssr<Environment>((c) => () => (
+      <Layout c={c} fullWidth fullPage title="Panel fixture">
+        <AppWorkspace mobileSurface="flush" class="min-h-0 flex-1">
+          <AppWorkspace.Sidebar id="panel-navigation" label="Navigation">
+            <AppWorkspace.SidebarDesktop>
+              <AppWorkspace.SidebarItem href="/app/fixture" active>
+                Workspace
+              </AppWorkspace.SidebarItem>
+            </AppWorkspace.SidebarDesktop>
+          </AppWorkspace.Sidebar>
+          <AppWorkspace.Content>
+            <AppWorkspace.Main>
+              <button type="button" id="open-panel">
+                Open fixture
+              </button>
+              <button type="button" id="open-silent-panel">
+                Open silent fixture
+              </button>
+              <a href="/app/fixture/next" id="next-page">
+                Next page
+              </a>
+              <textarea aria-label="App editor" />
+            </AppWorkspace.Main>
+            <AppWorkspace.Detail id="panel-fixture-detail" width="lg" open>
+              <h2>Selected item</h2>
+              <button type="button" data-workspace-detail-close>
+                Close detail
+              </button>
+            </AppWorkspace.Detail>
+          </AppWorkspace.Content>
+        </AppWorkspace>
+      </Layout>
+    )),
+  );
+
+/** Runs inline during parsing and again immediately after mounting the real runtime. */
+export function panelGeometry() {
+  return [".layout-shell-content", "#cloud-panel", ".k2b-app-workspace"].map((selector) => {
+    const rect = document.querySelector(selector)?.getBoundingClientRect();
+    return rect && { x: rect.x, y: rect.y, width: rect.width, height: rect.height };
+  });
+}

package/src/ssr/platform-messages.ts

@@ -4,6 +4,21 @@ export const platformMessages = i18n.define({
   baseLocale: "en",
   messages: {
     en: {
+      panel: "Panel",
+      panels: "Panels",
+      openPanel: "Open panel",
+      closePanel: "Close panel",
+      togglePanel: "Open or close the panel",
+      togglePanelDescription: "Shows a panel beside the app.",
+      panelShortcut: ({ mod }: { mod: string }) => `Panel (${mod}J)`,
+      resizePanel: "Resize panel",
+      releaseClosesPanel: "Release to close the panel",
+      panelLoadFailed: "The panel did not load",
+      panelNotResponding: ({ label }: { label: string }) => `${label} is not responding.`,
+      retry: "Try again",
+      panelLoading: ({ label }: { label: string }) => `${label} is loading`,
+      enlargePanel: "Enlarge panel",
+      shrinkPanel: "Shrink panel",
       printFallbackTitle: "This view does not print well.",
       printFallbackHint: "Open the item you want to print, or use the app's export.",
       admin: "Admin",
@@ -78,6 +93,21 @@ export const platformMessages = i18n.define({
       clearSearch: "Clear search",
     },
     de: {
+      panel: "Panel",
+      panels: "Panels",
+      openPanel: "Panel öffnen",
+      closePanel: "Panel schließen",
+      togglePanel: "Panel öffnen oder schließen",
+      togglePanelDescription: "Zeigt ein Panel neben der App.",
+      panelShortcut: ({ mod }: { mod: string }) => `Panel (${mod}J)`,
+      resizePanel: "Panelbreite ändern",
+      releaseClosesPanel: "Loslassen schließt das Panel",
+      panelLoadFailed: "Das Panel lädt nicht",
+      panelNotResponding: ({ label }: { label: string }) => `${label} antwortet nicht.`,
+      retry: "Erneut versuchen",
+      panelLoading: ({ label }: { label: string }) => `${label} lädt`,
+      enlargePanel: "Panel vergrößern",
+      shrinkPanel: "Panel verkleinern",
       printFallbackTitle: "Diese Ansicht lässt sich nicht gut drucken.",
       printFallbackHint: "Öffne den Eintrag, den du drucken möchtest, oder nutze den Export der App.",
       admin: "Administration",

package/src/ssr/rail-navigation.ts

@@ -1,3 +1,4 @@
+import type { TabBarItem } from "@k2b/ui";
 import type { RailPreferences, RailSnapshot } from "../contracts/rail-preferences";
 import { helpPageAppId } from "./layout-help-url";
 
@@ -66,3 +67,46 @@ export const railLinkActive = (link: RailLink, currentPath: string): boolean =>
     (target.pathname !== "/" && current.pathname.startsWith(`${target.pathname.replace(/\/$/, "")}/`))
   );
 };
+
+/**
+ * The phone bar's apps: the rail's links in the person's order, at most `limit`. The current page's link stays in the
+ * bar; when it comes later in the rail, it takes the last place, so the bar always marks where the person is.
+ */
+export const phoneBarLinks = (navigation: { shortcuts: RailLink[]; apps: RailLink[] }, currentPath: string, limit: number): RailLink[] => {
+  const links = [...navigation.shortcuts, ...navigation.apps];
+  const current = links.findIndex((link) => railLinkActive(link, currentPath));
+  if (current < limit) return links.slice(0, limit);
+  return [...links.slice(0, limit - 1), links[current]!];
+};
+
+/** Start and four apps fill the phone bar's five places. */
+const PHONE_BAR_APPS = 4;
+
+const underPath = (pathname: string, path: string) => pathname === path || pathname.startsWith(`${path.replace(/\/$/, "")}/`);
+
+/**
+ * The phone bar: Home, then the person's first apps in their rail order. Home leads to `/`, which opens the
+ * installation's start page (`home`), so it is the open item on `/` and on that start page, unless an app in the bar
+ * is open there.
+ */
+export const phoneBarItems = (
+  navigation: { shortcuts: RailLink[]; apps: RailLink[] },
+  currentPath: string,
+  home: { label: string; path: string },
+): TabBarItem[] => {
+  const links = phoneBarLinks(navigation, currentPath, PHONE_BAR_APPS);
+  const items = links.map((link) => ({
+    id: link.id,
+    label: link.label,
+    icon: link.iconClass,
+    href: link.href,
+    current: railLinkActive(link, currentPath),
+  }));
+  const pathname = new URL(currentPath, "https://cloud.invalid").pathname;
+  const start = new URL(home.path, "https://cloud.invalid").pathname;
+  const atHome = pathname === "/" || (!items.some((item) => item.current) && underPath(pathname, start));
+  return [
+    { id: "home", label: home.label, icon: "ti ti-home", href: "/", current: atHome },
+    ...items.map((item) => ({ ...item, current: !atHome && item.current })),
+  ];
+};

package/src/ssr/shell-data.tsx

@@ -4,13 +4,17 @@ import type { AppSearchLink } from "../contracts/app";
 import type { RailSnapshot } from "../contracts/rail-preferences";
 import type { CloudThemePreference } from "../shared/theme";
 import type { AppLaunchpadLegalLink } from "./app-launchpad";
+import type { PanelProvider } from "./app-navigation";
 import type { RailApp } from "./rail-navigation";
 
 export type ShellData = {
+  panel?: { providers: PanelProvider[]; provider?: string };
   /** The authorized navigation catalog, sorted for the request locale: the rail, the app grid and the phone menu show it. */
   apps: RailApp[];
   /** Signed-in pages: the person's rail preferences. */
   rail?: RailSnapshot;
+  /** Signed-in pages: the start page that `/` opens, for the phone bar's Home. */
+  home?: string;
   legalLinks: AppLaunchpadLegalLink[];
   /** Signed-in pages: the person, for the profile menu and the phone menu's profile actions. */
   profile?: { name: string; avatarSrc?: string; appHref?: string };