@k2b/cloud 0.30.0 → 0.32.0

package/src/ssr/ProfilePreferences.island.tsx

@@ -8,16 +8,20 @@ type ProfilePreferencesProps = {
   avatarSrc?: string;
   initialTheme: CloudTheme;
   name: string;
-  placement: "header" | "rail";
 };
 
+/**
+ * The avatar at the bottom of the rail. Its menu opens beside the rail and,
+ * because the avatar is the rail's last control, grows upward from the window's
+ * bottom edge.
+ */
 export default function ProfilePreferences(props: ProfilePreferencesProps) {
   const { preferences, items, signOut, signingOut } = createProfileActions(props.initialTheme, props.appHref);
 
   const avatar = () => <Avatar name={props.name} src={props.avatarSrc} size="xs" />;
 
   return (
-    <div class="layout-profile-preferences" data-placement={props.placement}>
+    <div class="layout-profile-preferences">
       <button type="button" class="layout-profile-preferences__link" aria-label={preferences.messages().menuLabel}>
         {avatar()}
       </button>
@@ -49,7 +53,7 @@ export default function ProfilePreferences(props: ProfilePreferencesProps) {
         class="layout-profile-preferences__dropdown"
         items={items()}
         label={preferences.messages().menuLabel}
-        position={props.placement === "rail" ? "right-start" : "bottom-left"}
+        position="right-start"
         width="14rem"
       >
         <Dropdown.Trigger

package/src/ssr/RailApps.island.tsx

@@ -10,7 +10,7 @@ import { projectRailNavigation, type RailApp, type RailLink, railLinkActive } fr
 function RailIcon(props: { link: RailLink; currentPath: string }) {
   let target: HTMLAnchorElement | undefined;
   const active = () => railLinkActive(props.link, props.currentPath);
-  const badge = useAppBadgeDescription(() => props.link.badge);
+  const badge = useAppBadgeDescription(() => ({ endpoint: props.link.badge, appId: props.link.appId }));
   return (
     <>
       <a
@@ -23,7 +23,7 @@ function RailIcon(props: { link: RailLink; currentPath: string }) {
       >
         <i class={`${props.link.iconClass} text-base`} aria-hidden="true" />
         <span class="sr-only">{props.link.label}</span>
-        <AppBadge endpoint={props.link.badge} />
+        <AppBadge endpoint={props.link.badge} appId={props.link.appId} />
       </a>
       <Tooltip target={() => target} content={props.link.label} placement="right" delay={0} />
     </>

package/src/ssr/app-badges.ts

@@ -1,5 +1,7 @@
 import { createSignal } from "solid-js";
 import { APP_BADGES_REFRESH_EVENT } from "../browser/app-badges";
+import { APPROVAL_COUNTS_PATH } from "../contracts/approval-paths";
+import type { ApprovalCounts } from "../contracts/approvals";
 
 /**
  * Shortest time between two scheduled reads in one tab, and the longest one
@@ -13,8 +15,20 @@ export const APP_BADGE_INTERVAL_MS = 60_000;
 // count. Only the browser ever writes it; server renders always see no badge.
 const [counts, setCounts] = createSignal<ReadonlyMap<string, number>>(new Map());
 
-/** The count for a declared `nav.badge` endpoint; 0 until the browser has read it. */
-export const appBadgeCount = (endpoint: string | undefined): number => (endpoint ? (counts().get(endpoint) ?? 0) : 0);
+const [approvalCounts, setApprovalCounts] = createSignal<ApprovalCounts | null>(null);
+
+/** Retain an SSR count until the first browser read; a failed read still resolves to zero. */
+export const liveApprovalCount = (appId?: string): number | null => {
+  const current = approvalCounts();
+  if (!current) return null;
+  if (appId === undefined) return current.total;
+  return Object.hasOwn(current.apps, appId) ? (current.apps[appId] ?? 0) : 0;
+};
+export const approvalCount = (appId?: string): number => liveApprovalCount(appId) ?? 0;
+
+/** Endpoint and approval counts for one app; 0 until the browser has read them. */
+export const appBadgeCount = (input: { endpoint?: string; appId?: string }): number =>
+  (input.endpoint ? (counts().get(input.endpoint) ?? 0) : 0) + (input.appId ? approvalCount(input.appId) : 0);
 
 /** A positive safe integer from an `AppNavBadge` body, else 0. */
 export const parseAppBadge = (body: unknown): number => {
@@ -33,6 +47,33 @@ const readBadge = async (endpoint: string, signal: AbortSignal): Promise<number>
   }
 };
 
+const isCount = (value: unknown, minimum: number): value is number =>
+  typeof value === "number" && Number.isSafeInteger(value) && value >= minimum;
+
+/** What `ApprovalCountsSchema` accepts from a JSON body, without loading validators into the shell; a test compares both. */
+export const parseApprovalCounts = (body: unknown): ApprovalCounts | null => {
+  if (typeof body !== "object" || body === null || Array.isArray(body)) return null;
+  if (Object.keys(body).length !== 2 || !("total" in body) || !("apps" in body)) return null;
+  const { total, apps } = body;
+  if (!isCount(total, 0) || typeof apps !== "object" || apps === null || Array.isArray(apps)) return null;
+  // Like Zod's record, ignore a `__proto__` key that JSON.parse keeps as an own property.
+  const entries = Object.entries(apps).filter(([app]) => app !== "__proto__");
+  return entries.every(([, count]) => isCount(count, 1)) ? { total, apps: Object.fromEntries(entries) } : null;
+};
+
+const readApprovalCounts = async (signal: AbortSignal): Promise<ApprovalCounts> => {
+  try {
+    const response = await fetch(APPROVAL_COUNTS_PATH, { credentials: "same-origin", headers: { accept: "application/json" }, signal });
+    if (response.status === 200) {
+      const parsed = parseApprovalCounts(await response.json());
+      if (parsed) return parsed;
+    }
+  } catch {
+    // A failing read clears approval counts just like an app badge.
+  }
+  return { total: 0, apps: {} };
+};
+
 let watching = false;
 
 /**
@@ -45,8 +86,8 @@ let watching = false;
  * read still running after the interval gives up. Returns a disposer.
  */
 export const watchAppBadges = (endpoints: readonly string[]): (() => void) => {
-  const unique = [...new Set(endpoints)];
-  if (typeof window === "undefined" || unique.length === 0 || watching) return () => {};
+  const unique = [...new Set([...endpoints, APPROVAL_COUNTS_PATH])];
+  if (typeof window === "undefined" || watching) return () => {};
   watching = true;
   const stopped = new AbortController();
   // Endpoints with a read in flight, mapped to whether one more read waits for it.
@@ -60,9 +101,12 @@ export const watchAppBadges = (endpoints: readonly string[]): (() => void) => {
       return;
     }
     running.set(endpoint, false);
-    void readBadge(endpoint, AbortSignal.any([stopped.signal, AbortSignal.timeout(APP_BADGE_INTERVAL_MS)])).then((count) => {
+    const signal = AbortSignal.any([stopped.signal, AbortSignal.timeout(APP_BADGE_INTERVAL_MS)]);
+    const result = endpoint === APPROVAL_COUNTS_PATH ? readApprovalCounts(signal) : readBadge(endpoint, signal);
+    void result.then((count) => {
       if (stopped.signal.aborted) return;
-      setCounts((previous) => new Map(previous).set(endpoint, count));
+      if (typeof count === "number") setCounts((previous) => new Map(previous).set(endpoint, count));
+      else setApprovalCounts(count);
       const queued = running.get(endpoint);
       running.delete(endpoint);
       if (queued && document.visibilityState !== "hidden") read(endpoint);

package/src/ssr/islands/index.ts

@@ -1,3 +1,4 @@
+export { default as PageTrail, type PageTrailProps } from "../PageTrail";
 export { default as WorkspaceNavigationProvider } from "../WorkspaceNavigationProvider";
 export { provideWorkspaceNavigation } from "../workspace-navigation";
 export { default as SearchBar } from "./SearchBar";

package/src/ssr/layout-runtime.ts

@@ -1,3 +1,6 @@
+import { readPageTrail, setPageTrail } from "@k2b/ui";
+import { derivePageTrail, dropSelfLinks } from "./page-trail";
+
 export type LayoutBreadcrumb = {
   title: string;
   href?: string;
@@ -10,13 +13,70 @@ export type LayoutUpdate = {
 
 export const LAYOUT_UPDATE_EVENT = "cloud:layout:update";
 
+/** The canvas attribute that carries the current app's base path, for the trail rule in the browser. */
+export const APP_BASE_ATTRIBUTE = "data-app-base";
+/** Set on the canvas of a page that shows its title without a way up: anonymous and focus-mode pages. */
+const TITLE_ONLY_ATTRIBUTE = "data-page-trail-title-only";
+
+/**
+ * Window event before the way up (a trail link or Alt+↑) loads a page. Its
+ * `detail.href` is where it leads: the page above, as this tab left it.
+ * Cancelling it keeps the document; the listener then navigates itself.
+ */
+export const PAGE_UP_EVENT = "cloud:page-up";
+export type PageUpDetail = { href: string };
+
+const here = () => `${location.pathname}${location.search}`;
+
 export const layout = {
+  /**
+   * Updates the page after an in-page navigation: the document title, and the
+   * page title with its way up wherever the shell or `PageTrail` shows it.
+   * `breadcrumbs` is the same title array `Layout` takes, under the same rule;
+   * `title` alone renames the current page and keeps the levels above it.
+   */
   update(update: LayoutUpdate) {
     if (typeof window === "undefined") return;
 
     const title = update.title ?? update.breadcrumbs?.at(-1)?.title;
     if (title) document.title = title;
+    const canvas = document.querySelector(".cloud-app-canvas");
+    const base = canvas?.getAttribute(APP_BASE_ATTRIBUTE) ?? undefined;
+    const current = readPageTrail();
+    const derived = update.breadcrumbs?.length
+      ? derivePageTrail(update.breadcrumbs, base, title ?? current?.title ?? document.title)
+      : title && current
+        ? { ...current, title }
+        : undefined;
+    if (!derived) return;
+    const trail = update.title ? { ...derived, title: update.title } : derived;
+    setPageTrail(canvas?.hasAttribute(TITLE_ONLY_ATTRIBUTE) ? { ...trail, ancestors: [] } : trail);
+    if (update.breadcrumbs?.length) {
+      // An island may change the address right after this call, in the same task, so the link to the page itself
+      // is known only then. Comparing earlier would drop the page the island has just left.
+      queueMicrotask(() => {
+        const published = readPageTrail();
+        if (!published) return;
+        const settled = dropSelfLinks(published, here());
+        if (settled !== published) setPageTrail(settled);
+      });
+    }
 
     window.dispatchEvent(new CustomEvent<LayoutUpdate>(LAYOUT_UPDATE_EVENT, { detail: update }));
   },
+
+  /**
+   * Lets an island that navigates in place, such as a file browser, take the
+   * way up itself instead of a page load that would end its running work.
+   * `go` gets the destination and returns `true` when it goes there in place.
+   * Returns the disposer.
+   */
+  handleUp(go: (href: string) => boolean): () => void {
+    if (typeof window === "undefined") return () => {};
+    const listener = (event: Event) => {
+      if (!event.defaultPrevented && go((event as CustomEvent<PageUpDetail>).detail.href)) event.preventDefault();
+    };
+    window.addEventListener(PAGE_UP_EVENT, listener);
+    return () => window.removeEventListener(PAGE_UP_EVENT, listener);
+  },
 };

package/src/ssr/mobile-menu-history.ts

@@ -18,7 +18,7 @@ export function openMobileMenu(view: (beforeSelect: () => Promise<boolean>) => D
     history.pushState({ ...previous, [marker]: id }, "");
     const abort = new AbortController();
     let leavingPage = false;
-    const mobile = window.matchMedia("(max-width: 1023px)");
+    const mobile = window.matchMedia("(max-width: 767px)");
     const pop = () => {
       if (history.state?.[marker] !== id) abort.abort();
     };

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);
+  };
+};