@k2b/cloud 0.29.1 → 0.31.0

package/src/ssr/page-trail-runtime.ts

@@ -0,0 +1,313 @@
+/**
+ * The way up, in the browser: links in a page trail lead to the page above,
+ * as this tab left it. A plain up link would reset the list a person
+ * filtered, searched, and scrolled; this runtime remembers each page's last
+ * URL and scroll position per tab and returns there. The trail's links keep
+ * their canonical `href`, so a new tab, a copied link, or a reload still lead
+ * to the page itself. After returning, the row that led down is marked.
+ */
+
+import { PAGE_TRAIL_EVENT, readPageTrail } from "@k2b/ui";
+import { registerContextAwareCommand } from "../browser/command-bridge";
+import { PAGE_UP_EVENT, type PageUpDetail } from "./layout-runtime";
+
+const STORAGE_KEY = "cloud:page-trail";
+/**
+ * Recent pages per tab. A trail goes back through a few levels, often across
+ * a detour into another app; thirty distinct pages cover that with room to
+ * spare while the memory stays a few kilobytes of `sessionStorage`.
+ */
+const VISIT_LIMIT = 30;
+/** How long a returning page may take to render the regions and rows it restores, at one try per frame. */
+const RESTORE_FRAMES = 60;
+const TRAIL_LINK = "a[data-k2b-page-trail-link]";
+const MAIN = ".layout-content-main";
+
+type Region = { key: string; top: number; left: number };
+/** A page as this tab left it; `up` holds the links of the levels above it then. */
+type Visit = { url: string; regions: Region[]; up?: string[] };
+type Memory = { visits: Visit[]; returning?: { url: string; from: string } };
+
+/**
+ * `path` as a page of this origin, or nothing: read against the origin,
+ * `//host`, `@host`, or `javascript:` would lead elsewhere, and a path that
+ * parses to `//host`, such as `/..//host`, would once an island reads its
+ * pathname.
+ */
+const localPage = (path: string): URL | undefined => {
+  if (!path.startsWith("/")) return undefined;
+  try {
+    const url = new URL(path, location.origin);
+    return url.origin === location.origin && !url.pathname.startsWith("//") ? url : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
+const isRegion = (value: unknown): value is Region =>
+  typeof value === "object" &&
+  value !== null &&
+  "key" in value &&
+  typeof value.key === "string" &&
+  "top" in value &&
+  typeof value.top === "number" &&
+  "left" in value &&
+  typeof value.left === "number";
+
+/**
+ * The tab's storage is not trusted: a visit or a return counts only when its
+ * addresses are pages of this origin and the rest has the shape this runtime writes.
+ */
+const isVisit = (value: unknown): value is Visit =>
+  typeof value === "object" &&
+  value !== null &&
+  "url" in value &&
+  typeof value.url === "string" &&
+  localPage(value.url) !== undefined &&
+  "regions" in value &&
+  Array.isArray(value.regions) &&
+  value.regions.every(isRegion) &&
+  (!("up" in value) ||
+    (Array.isArray(value.up) && value.up.every((item: unknown) => typeof item === "string" && URL.canParse(item, location.href))));
+
+const isReturning = (value: unknown): value is NonNullable<Memory["returning"]> =>
+  typeof value === "object" &&
+  value !== null &&
+  "url" in value &&
+  typeof value.url === "string" &&
+  localPage(value.url) !== undefined &&
+  "from" in value &&
+  typeof value.from === "string" &&
+  localPage(value.from) !== undefined;
+
+const read = (): Memory => {
+  try {
+    const value: unknown = JSON.parse(sessionStorage.getItem(STORAGE_KEY) ?? "null");
+    if (value !== null && typeof value === "object" && "visits" in value && Array.isArray(value.visits)) {
+      const visits = value.visits.filter(isVisit);
+      return "returning" in value && isReturning(value.returning) ? { visits, returning: value.returning } : { visits };
+    }
+  } catch {
+    // A full or blocked storage only costs the memory, never the navigation.
+  }
+  return { visits: [] };
+};
+const write = (memory: Memory) => {
+  try {
+    sessionStorage.setItem(STORAGE_KEY, JSON.stringify(memory));
+  } catch {
+    // See `read`.
+  }
+};
+
+const here = () => `${location.pathname}${location.search}${location.hash}`;
+const pathOf = (url: URL) => url.pathname.replace(/\/+$/, "") || "/";
+const resolve = (href: string) => new URL(href, location.href);
+
+/** A remembered page is the page `target` names when it has the same path and every query value `target` sets. */
+const isPage = (visited: URL, target: URL) =>
+  visited.origin === target.origin &&
+  pathOf(visited) === pathOf(target) &&
+  [...target.searchParams].every(([key, value]) => visited.searchParams.getAll(key).includes(value));
+/** How many of `from`'s query values `url` carries, less the ones the two do not share. */
+const queryMatch = (url: URL, from: URL) => {
+  const shared = [...url.searchParams].filter(([key, value]) => from.searchParams.getAll(key).includes(value)).length;
+  return 2 * shared - ([...url.searchParams].length - shared) - ([...from.searchParams].length - shared);
+};
+
+/** The page's scroll positions: the window, the shell's page scroller, and every keyed `data-scroll-preserve` region. */
+const captureRegions = (): Region[] => {
+  const regions: Region[] = [{ key: "@window", top: window.scrollY, left: window.scrollX }];
+  const main = document.querySelector<HTMLElement>(MAIN);
+  if (main) regions.push({ key: "@main", top: main.scrollTop, left: main.scrollLeft });
+  for (const element of document.querySelectorAll<HTMLElement>("[data-scroll-preserve]")) {
+    const key = element.dataset.scrollPreserve;
+    if (key) regions.push({ key, top: element.scrollTop, left: element.scrollLeft });
+  }
+  return regions.filter((region) => region.top || region.left);
+};
+
+/** Remembers the page as it is now, newest first, with the levels above it. */
+export const rememberPage = () => {
+  const memory = read();
+  const url = here();
+  const up = readPageTrail()?.ancestors.map((level) => level.href) ?? [];
+  memory.visits = [{ url, regions: captureRegions(), up }, ...memory.visits.filter((visit) => visit.url !== url)].slice(0, VISIT_LIMIT);
+  write(memory);
+};
+
+/**
+ * Where an up link leads in this tab: the page's last URL here, or its own
+ * `href`. A page below the target is never that page, even when its address
+ * carries the target's query, as a Files document carries its folder's: it
+ * names the target as a level above it.
+ */
+export const upDestination = (href: string): string => {
+  const target = resolve(href);
+  const below = (visit: Visit) => (visit.up ?? []).some((level) => isPage(resolve(level), target) && isPage(target, resolve(level)));
+  const visit = read().visits.find((candidate) => isPage(resolve(candidate.url), target) && !below(candidate));
+  return visit?.url ?? `${target.pathname}${target.search}${target.hash}`;
+};
+
+/**
+ * Goes one or more levels up to `href`, back to how this tab left that page.
+ * An island that navigates in place takes the way up itself (see
+ * `layout.handleUp`); otherwise the page loads. Returns whether it took the
+ * way up; a link it does not take stays a plain link.
+ */
+export const goUp = (href: string): boolean => {
+  // The way up stays on this origin; a link elsewhere, such as `javascript:`, names no page above.
+  if (resolve(href).origin !== location.origin) return false;
+  rememberPage();
+  const destination = upDestination(href);
+  // The destination is read as a path of this origin and must stay there; one that starts with `//` names another host.
+  const url = localPage(destination);
+  if (!url) return false;
+  const detail: PageUpDetail = { href: destination };
+  if (!window.dispatchEvent(new CustomEvent(PAGE_UP_EVENT, { cancelable: true, detail }))) return true;
+  const memory = read();
+  memory.returning = { url: destination, from: here() };
+  write(memory);
+  location.assign(url.href);
+  return true;
+};
+
+const regionElement = (key: string): HTMLElement | null =>
+  key === "@main"
+    ? document.querySelector<HTMLElement>(MAIN)
+    : document.querySelector<HTMLElement>(`[data-scroll-preserve="${CSS.escape(key)}"]`);
+
+/** Scores of links to the page itself rank above every link to a page above it, which score by path length. */
+const SAME_PAGE = 1_000_000;
+
+/**
+ * The link on this page that led towards `from`: the same page, or, for
+ * nested paths, the nearest page above it. Navigation, the rail, and trails
+ * themselves lead elsewhere and do not count.
+ */
+const rowTowards = (from: URL): HTMLElement | null => {
+  const scope = document.querySelector(MAIN) ?? document.body;
+  let best: { element: HTMLAnchorElement; score: number } | null = null;
+  for (const link of scope.querySelectorAll<HTMLAnchorElement>("a[href]")) {
+    if (link.closest(".k2b-page-title, .k2b-app-workspace__sidebar, .layout-rail, nav")) continue;
+    const url = resolve(link.getAttribute("href") ?? "");
+    if (url.origin !== from.origin) continue;
+    // The row may carry the list's query or leave it out; either way it names the same page. The closer its query
+    // is to `from`'s, the surer it is the row: a link without one, such as "All things", only names the list.
+    const same = isPage(from, url) || isPage(url, from);
+    const above = !same && url.search === "" && pathOf(from).startsWith(`${pathOf(url)}/`);
+    if (!same && !above) continue;
+    const score = same ? SAME_PAGE + queryMatch(url, from) : pathOf(url).length;
+    if (!best || score > best.score) best = { element: link, score };
+  }
+  return best ? (best.element.closest<HTMLElement>("tr, [role='row'], li") ?? best.element) : null;
+};
+
+/** Restores a returning page's scroll positions and marks the row that led down. Islands render late, so it retries per frame. */
+const restoreReturn = (visit: Visit | undefined, from: URL) => {
+  const pending = new Map((visit?.regions ?? []).map((region) => [region.key, region]));
+  let marked: HTMLElement | null = null;
+  let frames = 0;
+  const step = () => {
+    for (const [key, region] of pending) {
+      // A region is restored once both axes hold; content that renders late can still widen or lengthen it.
+      if (key === "@window") {
+        window.scrollTo(region.left, region.top);
+        if (Math.abs(window.scrollY - region.top) < 1 && Math.abs(window.scrollX - region.left) < 1) pending.delete(key);
+        continue;
+      }
+      const element = regionElement(key);
+      if (!element) continue;
+      element.scrollTop = region.top;
+      element.scrollLeft = region.left;
+      if (Math.abs(element.scrollTop - region.top) < 1 && Math.abs(element.scrollLeft - region.left) < 1) pending.delete(key);
+    }
+    if (!marked?.isConnected) {
+      marked = rowTowards(from);
+      if (marked) {
+        marked.setAttribute("data-page-trail-recent", "");
+        if (!visit?.regions.length) marked.scrollIntoView({ block: "nearest" });
+      }
+    }
+    frames += 1;
+    if (frames < RESTORE_FRAMES && (pending.size || !marked)) requestAnimationFrame(step);
+  };
+  requestAnimationFrame(step);
+};
+
+/** The localized name and description of the "One level up" command for a parent page. */
+export type PageUpLabels = (parent: string) => { title: string; description: string };
+
+/**
+ * Offers "One level up" (Alt+↑, ⌥↑ on a Mac) while the page has a page above
+ * it, through the shared command system: the shortcut, the palette, and the
+ * shortcut help list it only then, and the shortcut stays quiet in text
+ * fields. It follows trail changes from `layout.update()`.
+ */
+const offerPageUp = (labels: PageUpLabels): (() => void) => {
+  let unregister = () => {};
+  const update = () => {
+    unregister();
+    unregister = () => {};
+    const parent = readPageTrail()?.ancestors.at(-1);
+    if (!parent) return;
+    unregister = registerContextAwareCommand({
+      id: "cloud.page-up",
+      ...labels(parent.title),
+      icon: "ti ti-arrow-up",
+      shortcut: "alt+arrowup",
+      action: () => {
+        goUp(parent.href);
+      },
+    });
+  };
+  update();
+  window.addEventListener(PAGE_TRAIL_EVENT, update);
+  return () => {
+    window.removeEventListener(PAGE_TRAIL_EVENT, update);
+    unregister();
+  };
+};
+
+/**
+ * Installs the runtime for the document. Every click and Enter remembers the
+ * page as it is before anything navigates, also in place, as a list row that
+ * opens on Enter does; a plain click on a trail link goes up through the
+ * memory. Returns the disposer.
+ */
+export const installPageTrailRuntime = (labels: PageUpLabels): (() => void) => {
+  const stopPageUp = offerPageUp(labels);
+  const memory = read();
+  const returning = memory.returning;
+  if (returning) {
+    delete memory.returning;
+    write(memory);
+    const current = resolve(here());
+    if (pathOf(resolve(returning.url)) === pathOf(current) && resolve(returning.url).search === current.search)
+      restoreReturn(
+        memory.visits.find((visit) => visit.url === returning.url),
+        resolve(returning.from),
+      );
+  }
+  const onCapture = () => rememberPage();
+  const onKey = (event: KeyboardEvent) => {
+    if (event.key === "Enter") rememberPage();
+  };
+  const onClick = (event: MouseEvent) => {
+    if (event.defaultPrevented || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+    const link = (event.target as Element | null)?.closest?.<HTMLAnchorElement>(TRAIL_LINK);
+    if (!link || (link.target && link.target !== "_self")) return;
+    if (goUp(link.href)) event.preventDefault();
+  };
+  document.addEventListener("click", onCapture, true);
+  document.addEventListener("keydown", onKey, true);
+  document.addEventListener("click", onClick);
+  window.addEventListener("pagehide", onCapture);
+  return () => {
+    stopPageUp();
+    document.removeEventListener("click", onCapture, true);
+    document.removeEventListener("keydown", onKey, true);
+    document.removeEventListener("click", onClick);
+    window.removeEventListener("pagehide", onCapture);
+  };
+};

package/src/ssr/page-trail.browser-harness.tsx

@@ -0,0 +1,216 @@
+import { AppWorkspace } from "@k2b/ui";
+import { Hono } from "hono";
+import type { JSX } from "solid-js";
+import { defineApp } from "../_internal/define-app";
+import { person } from "../_internal/define-app.test-fixture";
+import Layout from "./Layout";
+import PageTrail from "./PageTrail";
+
+// Pages for `page-trail.browser.test.ts`: Accounts-like list and detail pages
+// in a workspace, a Files-like folder at any depth, a page without a
+// workspace, and a third-party app that draws its own header. All names are
+// invented.
+
+const probe = defineApp({
+  id: "page-trail-probe",
+  name: "Page trail probe",
+  icon: "ti ti-route",
+  description: "Page trail probe",
+  baseUrl: "http://page-trail-probe:3000",
+  routes: ["/app/accounts"],
+});
+const apps = [
+  {
+    id: "accounts",
+    name: "Accounts",
+    icon: "ti ti-users",
+    description: "People",
+    routes: ["/app/accounts"],
+    nav: { href: "/app/accounts", section: "primary" },
+  },
+  {
+    id: "files",
+    name: "Files",
+    icon: "ti ti-files",
+    description: "Files",
+    routes: ["/app/files"],
+    nav: { href: "/app/files", section: "primary" },
+  },
+  // A third-party app: it draws its own header and places the trail there.
+  {
+    id: "timetrack",
+    name: "Time",
+    icon: "ti ti-clock",
+    description: "Time tracking",
+    routes: ["/app/timetrack"],
+    nav: { href: "/app/timetrack", section: "primary" },
+  },
+  { id: "core", name: "Account", icon: "ti ti-user", description: "Account", routes: ["/me"], nav: { href: "/me", section: "hidden" } },
+];
+type LayoutContext = Parameters<typeof Layout>[0]["c"];
+type Title = { title: string; href?: string }[];
+
+const start = { title: "Start", href: "/" };
+const accountsRoot = { title: "Accounts", href: "/app/accounts" };
+export const users = Array.from({ length: 60 }, (_, index) => `user${String(index + 1).padStart(2, "0")}`);
+export const folders = [
+  "Projects for the new community centre",
+  "2026 budget year with the second construction phase",
+  "Quotes from all invited suppliers",
+  "Supplier A, Hartmann and Sons, Bremen branch",
+  "Questions about the foundation",
+];
+
+const Page = (props: { c: unknown; title: Title; children: JSX.Element }) => (
+  <Layout c={props.c as LayoutContext} fullWidth fullPage title={props.title}>
+    {props.children}
+  </Layout>
+);
+const AccountsWorkspace = (props: { children: JSX.Element }) => (
+  <AppWorkspace mobileSurface="flush" class="min-h-0 flex-1">
+    <AppWorkspace.Sidebar id="accounts-navigation" label="Accounts">
+      <AppWorkspace.SidebarDesktop>
+        <AppWorkspace.SidebarItem href="/app/accounts/users" icon="ti ti-user" active>
+          Users
+        </AppWorkspace.SidebarItem>
+      </AppWorkspace.SidebarDesktop>
+    </AppWorkspace.Sidebar>
+    <AppWorkspace.Content>
+      <AppWorkspace.Main scrollPreserveKey="accounts-users">{props.children}</AppWorkspace.Main>
+    </AppWorkspace.Content>
+  </AppWorkspace>
+);
+const folderHref = (depth: number) => `/app/files?path=${encodeURIComponent(folders.slice(0, depth).join("/"))}`;
+const filesTitle = (depth: number): Title => [
+  { title: "Files", href: "/app/files" },
+  ...folders.slice(0, depth - 1).map((name, index) => ({ title: name, href: folderHref(index + 1) })),
+  { title: folders[depth - 1]! },
+];
+/** A document in the editor, as Files names it: its way up is its folder with the document's row selected. */
+const editorTitle = (depth: number, file: string): Title => [
+  ...filesTitle(depth).slice(0, -1),
+  { title: folders[depth - 1]!, href: `${folderHref(depth)}&file=${encodeURIComponent(file)}` },
+  { title: file.split("/").at(-1)! },
+];
+
+export const server = new Hono()
+  .use(async (c, next) => {
+    c.set("runtime" as never, { apps } as never);
+    c.set("user" as never, person as never);
+    await next();
+  })
+  .get(
+    "/app/accounts/users",
+    ...probe.ssr((c) => {
+      const group = c.req.query("group");
+      const shown = group ? users.filter((_, index) => index % 2 === 0) : users;
+      return () => (
+        <Page c={c} title={[start, accountsRoot, { title: "Users" }]}>
+          <AccountsWorkspace>
+            <h1 class="p-3 font-semibold">{group ? `Users in ${group}` : "Users"}</h1>
+            {/* A region that scrolls sideways once its content arrives, as a wide table that renders late does. */}
+            <div data-scroll-preserve="accounts-wide" class="accounts-wide" style="width:300px;overflow:auto">
+              <div class="accounts-wide-content" style="width:300px;height:8px" />
+            </div>
+            <table class="w-full">
+              <tbody>
+                {shown.map((uid) => (
+                  <tr style="height:48px">
+                    <td>
+                      <a href={`/app/accounts/users/${uid}${group ? `?group=${group}` : ""}`}>{uid}</a>
+                    </td>
+                  </tr>
+                ))}
+              </tbody>
+            </table>
+          </AccountsWorkspace>
+        </Page>
+      );
+    }),
+  )
+  .get(
+    "/app/accounts/users/:uid",
+    ...probe.ssr((c) => {
+      const uid = c.req.param("uid") ?? "";
+      return () => (
+        <Page c={c} title={[start, accountsRoot, { title: "Users", href: "/app/accounts/users" }, { title: uid }]}>
+          <AccountsWorkspace>
+            <p class="p-3">Profile of {uid}</p>
+            <input aria-label="Note" class="m-3" />
+          </AccountsWorkspace>
+        </Page>
+      );
+    }),
+  )
+  .get(
+    "/app/files",
+    ...probe.ssr((c) => {
+      const depth = (c.req.query("path") ?? "").split("/").filter(Boolean).length || 1;
+      const file = c.req.query("view") === "edit" ? c.req.query("file") : undefined;
+      return () => (
+        <Page c={c} title={file ? editorTitle(depth, file) : filesTitle(depth)}>
+          <AppWorkspace mobileSurface="flush" class="min-h-0 flex-1">
+            <AppWorkspace.Sidebar id="files-navigation" label="Storage">
+              <AppWorkspace.SidebarDesktop>
+                <AppWorkspace.SidebarItem href="/app/files" icon="ti ti-folder">
+                  My files
+                </AppWorkspace.SidebarItem>
+              </AppWorkspace.SidebarDesktop>
+            </AppWorkspace.Sidebar>
+            <AppWorkspace.Content>
+              <AppWorkspace.Main>Folder contents</AppWorkspace.Main>
+              <AppWorkspace.Detail id="file-detail" open={c.req.query("detail") === "1"} width="lg">
+                Details
+              </AppWorkspace.Detail>
+            </AppWorkspace.Content>
+          </AppWorkspace>
+        </Page>
+      );
+    }),
+  )
+  .get(
+    "/me/notifications/history",
+    ...probe.ssr((c) => () => (
+      <Page
+        c={c}
+        title={[
+          start,
+          { title: "Account", href: "/me" },
+          { title: "Notifications", href: "/me/notifications" },
+          { title: "Delivery history" },
+        ]}
+      >
+        <div class="p-3">
+          <h1 class="text-xl font-semibold">Delivery history</h1>
+          <p>Every message sent to you.</p>
+        </div>
+      </Page>
+    )),
+  )
+  .get(
+    "/app/timetrack/entries/:id",
+    ...probe.ssr((c) => () => (
+      <Page
+        c={c}
+        title={[
+          start,
+          { title: "Time", href: "/app/timetrack" },
+          { title: "Website relaunch", href: "/app/timetrack/projects/web" },
+          { title: "Homepage: agree on drafts" },
+        ]}
+      >
+        <div class="flex min-h-0 flex-1 flex-col">
+          <header class="timetrack-head flex min-h-14 items-center gap-2 px-3">
+            <PageTrail subtitle="2:15 h" />
+            <button type="button" class="ml-auto">
+              Start timer
+            </button>
+          </header>
+          <dl class="p-3">
+            <dt>Project</dt>
+            <dd>Website relaunch</dd>
+          </dl>
+        </div>
+      </Page>
+    )),
+  );

package/src/ssr/page-trail.ts

@@ -0,0 +1,59 @@
+import type { PageTrailLink, PageTrailState } from "@k2b/ui";
+import type { LayoutBreadcrumb } from "./layout-runtime";
+
+/** `path` without trailing slashes, in one pass: a regular expression would backtrack on long runs of `/`. */
+const withoutTrailingSlashes = (path: string): string => {
+  let end = path.length;
+  while (end > 0 && path[end - 1] === "/") end--;
+  return path.slice(0, end);
+};
+
+/** Path and query of a same-origin link, without a trailing slash; the hash names no other page. */
+const pageOf = (href: string): string => {
+  const hash = href.indexOf("#");
+  const withoutHash = hash >= 0 ? href.slice(0, hash) : href;
+  const queryStart = withoutHash.indexOf("?");
+  const path = queryStart >= 0 ? withoutHash.slice(0, queryStart) : withoutHash;
+  const query = queryStart >= 0 ? withoutHash.slice(queryStart) : "";
+  return (path.length > 1 ? withoutTrailingSlashes(path) : path) + (query.length > 1 ? query : "");
+};
+
+/** The trail without levels that link to `page` itself, by path and query. */
+export const dropSelfLinks = (trail: PageTrailState, page: string): PageTrailState => {
+  const self = pageOf(page);
+  const ancestors = trail.ancestors.filter((level) => pageOf(level.href) !== self);
+  return ancestors.length === trail.ancestors.length ? trail : { ...trail, ancestors };
+};
+
+/**
+ * The page trail from a page's title array, by one rule for every app.
+ *
+ * The last entry is the page itself. Above it, Start (`href: "/"`) and the
+ * app's own root (`href` equal to its base path) are dropped: the rail already
+ * leads there. So is an entry without an `href`, because nobody can go back to
+ * it, and one that links to the page itself (`currentPage`, path and query).
+ * What remains are the levels below the app root, nearest last; their number
+ * alone decides how the shell shows the way up, so an app never chooses a form
+ * and every app with the same depth looks the same.
+ */
+export const derivePageTrail = (
+  title: string | readonly LayoutBreadcrumb[] | undefined,
+  appBasePath: string | undefined,
+  fallback: string,
+  currentPage?: string,
+): PageTrailState => {
+  if (typeof title === "string") return { title, ancestors: [] };
+  const current = title?.at(-1);
+  if (!title || !current) return { title: fallback, ancestors: [] };
+  const base = appBasePath ? pageOf(appBasePath) : undefined;
+  const ancestors = title
+    .slice(0, -1)
+    .filter((entry): entry is PageTrailLink => typeof entry.href === "string" && entry.href.length > 0)
+    .filter((entry) => {
+      const page = pageOf(entry.href);
+      return page !== "/" && page !== "" && page !== base;
+    })
+    .map((entry) => ({ title: entry.title, href: entry.href }));
+  const trail = { title: current.title, ancestors };
+  return currentPage ? dropSelfLinks(trail, currentPage) : trail;
+};

package/src/ssr/platform-messages.ts

@@ -65,6 +65,8 @@ export const platformMessages = i18n.define({
       searchShortcut: "Search (⌘/Ctrl+K)",
       openShortcutHelp: "Open shortcut help",
       shortcutHelpDescription: "Open help, guides, and keyboard shortcuts.",
+      pageUp: ({ page }: { page: string }) => `One level up: ${page}`,
+      pageUpDescription: "Go to the page above this one, as you left it in this tab.",
       openHelp: "Open help",
       helpShortcut: "Help (Shift+/)",
       signIn: "Sign in",
@@ -134,6 +136,8 @@ export const platformMessages = i18n.define({
       searchShortcut: "Suchen (⌘/Strg+K)",
       openShortcutHelp: "Tastaturhilfe öffnen",
       shortcutHelpDescription: "Hilfe, Anleitungen und Tastaturkürzel öffnen.",
+      pageUp: ({ page }: { page: string }) => `Eine Ebene höher: ${page}`,
+      pageUpDescription: "Zur Seite darüber, so wie du sie in diesem Tab verlassen hast.",
       openHelp: "Hilfe öffnen",
       helpShortcut: "Hilfe (Umschalt+/)",
       signIn: "Anmelden",

package/src/ssr/rail-context.ts

@@ -1,4 +1,4 @@
-import { type RailPreferences, type RailSnapshot, RailSnapshotSchema } from "../contracts/rail-preferences";
+import type { RailPreferences, RailSnapshot } from "../contracts/rail-preferences";
 import type { RailApp } from "./rail-navigation";
 
 export type RailContext = { apps: RailApp[]; settings: RailSnapshot };
@@ -8,9 +8,10 @@ export const readRailContext = (): RailContext | undefined => {
   if (typeof document === "undefined") return undefined;
   const text = document.getElementById("cloud-rail-data")?.textContent;
   if (!text) return undefined;
-  // Framework-generated, escaped SSR data; never loaded from localStorage.
+  // Framework-generated, escaped SSR data; never loaded from localStorage. The server validates the snapshot when
+  // it reads it, so the shell does not load the schemas on every page.
   const value: RailContext = JSON.parse(text);
-  return { apps: value.apps, settings: RailSnapshotSchema.parse(value.settings) };
+  return { apps: value.apps, settings: value.settings };
 };
 
 export const publishRailPreferences = (settings: RailPreferences) => {

package/src/ssr/runtime.ts

@@ -4,7 +4,7 @@
  */
 import type { CloudRuntime } from "../contracts/app";
 import { getLocale } from "../server/locale";
-import { resolveAppPresentations } from "../shared/app-presentation";
+import { resolveAppPresentation, resolveAppPresentations } from "../shared/app-presentation";
 
 export type RuntimeContext = CloudRuntime;
 
@@ -29,3 +29,16 @@ export const getLocalizedRuntimeContext = (carrier: RuntimeCarrier & { req: { ra
   const locale = getLocale(carrier as Parameters<typeof getLocale>[0]);
   return { ...runtime, apps: resolveAppPresentations(runtime.apps, locale) };
 };
+
+/** An app's name in the request locale while the app is registered; `fallback` (its stored base name) otherwise. */
+export const localizedAppName = (
+  carrier: RuntimeCarrier & { req: { raw: { headers: Headers } } },
+  appId: string,
+  fallback: string,
+): string => {
+  const runtime = carrier.get("runtime");
+  const apps =
+    runtime && typeof runtime === "object" && Array.isArray((runtime as RuntimeContext).apps) ? (runtime as RuntimeContext).apps : [];
+  const app = apps.find((entry) => entry.id === appId);
+  return app ? resolveAppPresentation(app, getLocale(carrier as Parameters<typeof getLocale>[0])).name : fallback;
+};