@eifi1/ui-kit 0.8.1 → 0.9.0

package/src/components/disclosure.tsx

@@ -144,8 +144,17 @@ export interface DisclosureProps extends Omit<ComponentPropsWithoutRef<"div">, "
    * settings or analysis page. `bare` draws nothing: a leading chevron that turns
    * down, for an inline "Show 3 hidden accounts" inside something that already has
    * its own surface.
+   *
+   * `menu` is a row of a `HoverMenu`: the top bar's menu-item look
+   * (`TOPBAR_MENU_ITEM_CLASS` — full-width, `px-3 py-2`, regular weight, square, the
+   * hover wash with the text colour left alone), an INSET focus ring so the menu's
+   * clipping edge cannot cut it off, the chevron at the end (`chevronPosition`
+   * defaults to `end` here) and a body with no padding of its own, so the sub-list's
+   * rows sit flush like the rows around them. keksdose's account menu opens its
+   * language sub-list this way, and on `bare` it took four header overrides and a
+   * body one to get there (account-menu.tsx).
    */
-  variant?: "card" | "bare";
+  variant?: "card" | "bare" | "menu";
   /**
    * Where a `bare` disclosure draws its chevron. `start` (default) is the leading
    * chevron that turns from the reading direction to down. `end` puts it at the far
@@ -153,7 +162,7 @@ export interface DisclosureProps extends Omit<ComponentPropsWithoutRef<"div">, "
    * account menu, whose language sub-list reads "Language 🇩🇪 ⌄" with the chevron
    * after the flag, like every other menu row with a sub-list. With `trailing`, the
    * chevron follows it, as on a card. A `card` always has it at the end, so this is
-   * ignored there.
+   * ignored there. A `menu` defaults to `end`, like the menu rows around it.
    */
   chevronPosition?: "start" | "end";
   /**
@@ -230,7 +239,7 @@ export function Disclosure({
   defaultOpen = false,
   onOpenChange,
   variant = "card",
-  chevronPosition = "start",
+  chevronPosition,
   headingAs: Heading,
   keepMounted,
   disabled,
@@ -247,8 +256,10 @@ export function Disclosure({
   const open = controlled ?? own;
   const bodyId = useId();
   const card = variant === "card";
-  // The card's chevron trails always; a bare one only when asked to.
-  const chevronAtEnd = card || chevronPosition === "end";
+  const menu = variant === "menu";
+  // The card's chevron trails always; a menu row's unless asked otherwise; a bare
+  // one only when asked to.
+  const chevronAtEnd = card || (chevronPosition ?? (menu ? "end" : "start")) === "end";
   const triggerOnly = controls !== undefined;
   // The card's header squares its lower corners only when a body opens under it.
   const joined = open && !triggerOnly;
@@ -280,7 +291,7 @@ export function Disclosure({
             cn(
               "min-w-0 flex-1 after:absolute after:inset-0 after:content-['']",
               "focus-visible:after:ring-2 focus-visible:after:ring-inset focus-visible:after:ring-[var(--brand)]",
-              card ? cn("after:rounded-lg", joined && "after:rounded-b-none") : "after:rounded-sm",
+              card ? cn("after:rounded-lg", joined && "after:rounded-b-none") : !menu && "after:rounded-sm",
             )
           : "focus-visible:ring-2 focus-visible:ring-[var(--brand)]",
         card
@@ -289,7 +300,12 @@ export function Disclosure({
               hasTrailing ? "pe-0" : "hover:bg-[var(--bg-hover)] focus-visible:ring-inset",
               joined && "rounded-b-none",
             )
-          : "items-center rounded-sm text-sm font-medium text-[var(--text-secondary)] hover:text-[var(--text-primary)]",
+          : menu
+            ? // TOPBAR_MENU_ITEM_CLASS's row, spelled out rather than imported: a
+              // component does not reach up into the shell. A test holds the two to
+              // the same classes.
+              "items-center justify-between gap-3 px-3 py-2 text-sm text-[var(--text-secondary)] hover:bg-[var(--bg-hover)] focus-visible:ring-inset"
+            : "items-center rounded-sm text-sm font-medium text-[var(--text-secondary)] hover:text-[var(--text-primary)]",
         headerClassName,
       )}
     >
@@ -337,7 +353,7 @@ export function Disclosure({
       )}
       {!triggerOnly && (
         <Collapse id={bodyId} open={open} keepMounted={keepMounted}>
-          <div className={cn(card ? "space-y-3 px-4 pb-4" : "space-y-2 pt-2", bodyClassName)}>{children}</div>
+          <div className={cn(card ? "space-y-3 px-4 pb-4" : !menu && "space-y-2 pt-2", bodyClassName)}>{children}</div>
         </Collapse>
       )}
     </div>

package/src/components/floating-panel.tsx

@@ -65,6 +65,30 @@ export interface FloatingActionButtonProps extends Omit<ButtonHTMLAttributes<HTM
    * clears the transactions page's own action group this way (`calc(1rem + 4rem)`).
    */
   offset?: string;
+  /**
+   * Whether the button carries the browser's own tooltip (`title`, the `label` unless a
+   * `title` is passed). Default `true`, so an icon-only button keeps a hover hint for a
+   * mouse user with no other way to learn what it is. `false` renders no `title` at all:
+   * keksdose has ONE tooltip, the kit's `Tooltip` (dev#523), and its source scan fails a
+   * native `title=` anywhere — so a flag, not `title=""`, which the scan would still
+   * see. An empty `title` renders no attribute either, for the caller who has no scan.
+   *
+   * Not flipped to off by default: a FAB wrapped in nothing would lose the only hover
+   * hint it has, silently, in every app already on it. And the kit cannot wrap itself
+   * in its `Tooltip` — the bubble's anchor is a `relative inline-flex` span, and the
+   * button is `fixed` and portalled — so the one-tooltip caller wraps it.
+   */
+  nativeTitle?: boolean;
+  /**
+   * Make it a toggle. `true`/`false` set `aria-pressed` and swap the solid brand disc for
+   * a surface disc — the glyph in brand on the quiet brand fill when on, the secondary
+   * text colour when off — the "on" look of `IconButton`'s `pressed` and of a selected
+   * Chip. Left out, it is the ordinary action FAB. For keksdose's corner filter toggles
+   * (feedback-page's "awaiting only", the /transactions pending and upcoming toggles),
+   * which paint `text-[var(--brand)]` on a surface button by hand. Keep `label` the same
+   * in both states; `aria-pressed` already says which one it is in.
+   */
+  pressed?: boolean;
   ref?: Ref<HTMLButtonElement>;
 }
 
@@ -90,12 +114,18 @@ export function FloatingActionButton({
   icon,
   corner = "bottom-end",
   offset = "1rem",
+  nativeTitle = true,
+  pressed,
   className,
   style,
   type = "button",
+  title,
   ...rest
 }: FloatingActionButtonProps) {
   const [marker, dir] = usePortalDir();
+  const toggle = pressed !== undefined;
+  // An empty title is "no tooltip", not an attribute with nothing in it.
+  const nativeTip = nativeTitle && title !== "" ? (title ?? label) : undefined;
   return (
     <>
       <span ref={marker} hidden />
@@ -106,11 +136,20 @@ export function FloatingActionButton({
             type={type}
             dir={dir}
             aria-label={label}
-            title={rest.title ?? label}
+            aria-pressed={pressed ?? rest["aria-pressed"]}
+            title={nativeTip}
             style={{ ...cornerStyle(corner, offset), ...style }}
             className={cn(
               "fixed z-40 inline-flex size-12 items-center justify-center rounded-full",
-              "bg-[var(--brand)] text-[var(--brand-contrast)] shadow-lg transition-colors hover:bg-[var(--brand-hover)]",
+              "shadow-lg transition-colors",
+              !toggle && "bg-[var(--brand)] text-[var(--brand-contrast)] hover:bg-[var(--brand-hover)]",
+              // A toggle sits on the page's surface — a solid brand disc would read as
+              // "on" in both states — and says "on" in the brand family.
+              toggle && "border border-[var(--border)]",
+              pressed === false &&
+                "bg-[var(--bg-surface)] text-[var(--text-secondary)] hover:bg-[var(--bg-hover)] hover:text-[var(--text-primary)]",
+              pressed === true &&
+                "border-[var(--brand)] bg-[var(--brand-bg)] text-[var(--brand)] hover:bg-[var(--brand-bg-hover)]",
               "outline-none focus-visible:ring-2 focus-visible:ring-[var(--brand)] focus-visible:ring-offset-2",
               "[&_svg]:size-6",
               className,
@@ -141,6 +180,9 @@ export interface FloatingPanelProps {
   /** The FAB's distance above the nav — see {@link FloatingActionButtonProps.offset}.
    *  From `md` up the card sits above the FAB, so it moves with it. */
   offset?: string;
+  /** The FAB's native `title` — see {@link FloatingActionButtonProps.nativeTitle}.
+   *  `false` for keksdose's assistant launcher, under its one-tooltip rule (dev#523). */
+  fabNativeTitle?: boolean;
   /** Default: `floatingPanel.close` from the {@link UiKitProvider}, else "Close". */
   closeLabel?: string;
   /**
@@ -196,6 +238,7 @@ export function FloatingPanel({
   onOpenChange,
   corner = "bottom-end",
   offset = "1rem",
+  fabNativeTitle,
   closeLabel,
   initialFocus,
   className,
@@ -264,6 +307,7 @@ export function FloatingPanel({
         icon={fabIcon}
         corner={corner}
         offset={offset}
+        nativeTitle={fabNativeTitle}
         aria-expanded={open}
         aria-controls={open ? panelId : undefined}
         onClick={() => {

package/src/components/progress-bar.tsx

@@ -3,8 +3,30 @@ import type { ComponentPropsWithoutRef, ReactNode } from "react";
 import { cn } from "../lib/cn";
 import { DEFAULT_COMMON_LABELS, useKitLabels, useKitLocale } from "../i18n/kit-labels";
 
-export type ProgressBarTone = "brand" | "neutral" | "success" | "warning" | "danger" | "info";
-export type ProgressBarSize = "sm" | "md" | "lg";
+/**
+ * `income` / `expense` are the money pair (`--money-income` / `--money-expense`), the
+ * names `Chip`, `StatTile` and `Sparkline` already use for them: a share bar of what
+ * came in or went out is money, and painting it `success` / `warning` said "good" and
+ * "careful" about a figure that is neither. keksdose's report meters (food-group-card,
+ * drilldown-modal) sit beside amounts that are already in the money colours.
+ */
+export type ProgressBarTone =
+  | "brand"
+  | "neutral"
+  | "success"
+  | "warning"
+  | "danger"
+  | "info"
+  | "income"
+  | "expense";
+/**
+ * Track heights: `sm` 4px, `slim` 6px, `md` 8px, `lg` 12px. `slim` is a word and not a
+ * letter because the letters are taken in order — an `xs` at 6px would be THICKER than
+ * `sm` — and renaming `sm` would move every bar already on it. 6px is the Slider's
+ * track and keksdose's hand-drawn meters (`h-1.5`, landing-visuals), for a bar under a
+ * line of text where 8px outweighs the text.
+ */
+export type ProgressBarSize = "sm" | "slim" | "md" | "lg";
 
 const FILL: Record<ProgressBarTone, string> = {
   brand: "bg-[var(--brand)]",
@@ -13,9 +35,11 @@ const FILL: Record<ProgressBarTone, string> = {
   warning: "bg-[var(--warning)]",
   danger: "bg-[var(--danger)]",
   info: "bg-[var(--info)]",
+  income: "bg-[var(--money-income)]",
+  expense: "bg-[var(--money-expense)]",
 };
 
-const TRACK_HEIGHT: Record<ProgressBarSize, string> = { sm: "h-1", md: "h-2", lg: "h-3" };
+const TRACK_HEIGHT: Record<ProgressBarSize, string> = { sm: "h-1", slim: "h-1.5", md: "h-2", lg: "h-3" };
 
 export interface ProgressBarProps extends Omit<ComponentPropsWithoutRef<"div">, "children" | "role"> {
   /** Where it stands. Leave it undefined for an INDETERMINATE bar — work is under way

package/src/components/ui.tsx

@@ -154,27 +154,50 @@ const ICON_BUTTON_SIZES: Record<IconButtonSize, string> = {
 };
 
 // A tone re-colours the glyph without changing what the variant draws around it.
-// `muted` and `danger` both sit quiet at rest — an action in every row of a list
-// must not shout from every row — and `danger` answers the pointer in the
-// destructive family, so the red arrives only on the one row you are about to
-// act on.
-const ICON_BUTTON_TONES = {
-  default: "",
-  muted:
-    "text-[var(--text-placeholder)] hover:bg-[var(--bg-surface-2)] hover:text-[var(--text-primary)]",
-  danger:
-    "text-[var(--text-placeholder)] hover:bg-[var(--danger-bg)] hover:text-[var(--danger)] focus:ring-[var(--danger-border)]",
-  // Amber AT REST, unlike `danger`: a warning icon button is the one on the row that
-  // needs attention (keksdose's "needs review" flag on a transaction, the stale-rate
-  // marker), not an action repeated down a list — quiet grey would hide the very
-  // thing it is there to point out.
-  warning:
-    "text-[var(--warning)] hover:bg-[var(--warning-bg)] focus:ring-[var(--warning-border)]",
-  // Sky at rest, for the same reason as `warning`: keksdose's reconcile action on an
-  // account row (accounts-page:867) is the one on the row to notice, and it is
-  // informational rather than a problem, so it takes the `--info` family.
-  info: "text-[var(--info)] hover:bg-[var(--info-bg)] focus:ring-[var(--info-border)]",
-} as const;
+// Each coloured tone comes in two resting looks, picked by `quiet` (see the prop):
+// QUIET is placeholder grey until the pointer or focus arrives, then the tone's
+// family; TONED wears the tone's colour at rest. The defaults are the looks each tone
+// had before `quiet` existed: `danger` is quiet — an action in every row of a list
+// must not shout from every row, so the red arrives only on the one row you are about
+// to act on — while `warning` and `info` are toned, because they mark the ONE thing
+// on the row to notice (keksdose's "needs review" flag, its reconcile action at
+// accounts-page:867), and quiet grey would hide the very thing they point out.
+// `muted` is quiet by definition and has no toned look; `default` has no tone.
+export type IconButtonTone = "default" | "muted" | "danger" | "warning" | "info";
+
+type ColouredTone = "danger" | "warning" | "info";
+
+const ICON_BUTTON_TONES: Record<ColouredTone, { quiet: string; toned: string }> = {
+  danger: {
+    quiet:
+      "text-[var(--text-placeholder)] hover:bg-[var(--danger-bg)] hover:text-[var(--danger)] focus:ring-[var(--danger-border)]",
+    toned: "text-[var(--danger)] hover:bg-[var(--danger-bg)] focus:ring-[var(--danger-border)]",
+  },
+  warning: {
+    quiet:
+      "text-[var(--text-placeholder)] hover:bg-[var(--warning-bg)] hover:text-[var(--warning)] focus:ring-[var(--warning-border)]",
+    toned: "text-[var(--warning)] hover:bg-[var(--warning-bg)] focus:ring-[var(--warning-border)]",
+  },
+  info: {
+    quiet:
+      "text-[var(--text-placeholder)] hover:bg-[var(--info-bg)] hover:text-[var(--info)] focus:ring-[var(--info-border)]",
+    toned: "text-[var(--info)] hover:bg-[var(--info-bg)] focus:ring-[var(--info-border)]",
+  },
+};
+
+const ICON_BUTTON_MUTED =
+  "text-[var(--text-placeholder)] hover:bg-[var(--bg-surface-2)] hover:text-[var(--text-primary)]";
+
+/** Which tones sit quiet at rest when `quiet` is left out. */
+const QUIET_BY_DEFAULT: Record<ColouredTone, boolean> = { danger: true, warning: false, info: false };
+
+function iconButtonToneClass(tone: IconButtonTone, quiet: boolean | undefined): string {
+  if (tone === "default") return "";
+  if (tone === "muted") return cn(ICON_BUTTON_MUTED, ICON_BUTTON_QUIET_DISABLED_REST);
+  const isQuiet = quiet ?? QUIET_BY_DEFAULT[tone];
+  const look = ICON_BUTTON_TONES[tone];
+  return isQuiet ? cn(look.quiet, ICON_BUTTON_QUIET_DISABLED_REST) : look.toned;
+}
 
 // A disabled button must not answer the pointer. The hover classes above are plain
 // `hover:` (so a caller's `className="hover:…"` still replaces them through
@@ -194,11 +217,9 @@ const ICON_BUTTON_DISABLED_REST: Record<ButtonVariant | "overlay", string> = {
   overlay: "disabled:hover:bg-[color-mix(in_srgb,var(--bg-inverse)_60%,transparent)]",
 };
 
-// The tones that change the glyph on hover pin their resting glyph the same way.
-const ICON_BUTTON_TONES_DISABLED_REST: Partial<Record<keyof typeof ICON_BUTTON_TONES, string>> = {
-  muted: "disabled:hover:text-[var(--text-placeholder)]",
-  danger: "disabled:hover:text-[var(--text-placeholder)]",
-};
+// The quiet looks change the glyph on hover, so they pin their resting glyph the
+// same way. A toned look keeps its glyph on hover and needs no pin.
+const ICON_BUTTON_QUIET_DISABLED_REST = "disabled:hover:text-[var(--text-placeholder)]";
 
 // `pressed`: a toggle that is on. The brand glyph on the quiet brand fill — the
 // "selected" look of a Chip or a SegmentedControl option, so an on toggle reads as on
@@ -229,8 +250,26 @@ export interface IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>
    *  hover. `danger`: the same grey at rest, `--danger` on hover and focus — for a
    *  remove/delete that repeats down a list. `warning`: amber at rest — a flag that
    *  wants attention. `info`: sky at rest — a notice-worthy but harmless action
-   *  (keksdose's reconcile). Default: the variant's own colours. */
-  tone?: keyof typeof ICON_BUTTON_TONES;
+   *  (keksdose's reconcile). Default: the variant's own colours. See `quiet` for
+   *  turning a coloured tone's resting look the other way. */
+  tone?: IconButtonTone;
+  /**
+   * Whether a coloured tone (`danger`, `warning`, `info`) waits for the pointer:
+   * `true` is placeholder grey at rest and the tone's colour on hover and focus;
+   * `false` wears the tone's colour at rest. Left out, each tone keeps its own
+   * default — `danger` quiet, `warning` and `info` not. Ignored for `muted` (quiet by
+   * definition) and `default` (no tone).
+   *
+   * `quiet={false}` on `danger` is for a destructive action that stands ALONE, where
+   * hover-to-reveal hides it: keksdose's phone bulk bar (mobile-bulk-bar.tsx) has one
+   * "delete all" and a touch screen that never hovers, so it painted rose by hand.
+   * `quiet` on `warning`/`info` is the same switch the other way, for a flag repeated
+   * down a list. A boolean over the tone rather than a new tone (`danger-solid`) or an
+   * `emphasis` scale: there are exactly two resting looks, every coloured tone has
+   * both, and which one fits is a question about the SITE (alone or repeated, touch or
+   * pointer), not about the tone — so it is one switch the family shares.
+   */
+  quiet?: boolean;
   /**
    * Make it a toggle button. `true` sets `aria-pressed="true"` and draws the "on" look
    * (brand glyph on the quiet brand fill); `false` sets `aria-pressed="false"` with the
@@ -269,7 +308,7 @@ export interface IconButtonProps extends ButtonHTMLAttributes<HTMLButtonElement>
 }
 
 export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(function IconButton(
-  { variant = "ghost", size = "md", tone = "default", pressed, stopPropagation, className, onClick, onKeyDown, ...rest },
+  { variant = "ghost", size = "md", tone = "default", quiet, pressed, stopPropagation, className, onClick, onKeyDown, ...rest },
   ref,
 ) {
   return (
@@ -293,8 +332,7 @@ export const IconButton = forwardRef<HTMLButtonElement, IconButtonProps>(functio
         // After the size, so the overlay's `rounded-full` beats the small sizes' `rounded`.
         variant === "overlay" ? ICON_BUTTON_OVERLAY : buttonVariantClasses[variant],
         ICON_BUTTON_DISABLED_REST[variant],
-        ICON_BUTTON_TONES[tone],
-        ICON_BUTTON_TONES_DISABLED_REST[tone],
+        iconButtonToneClass(tone, quiet),
         pressed && ICON_BUTTON_PRESSED,
         className,
       )}
@@ -1334,13 +1372,24 @@ export function Spinner({ className, label, ...rest }: SpinnerProps) {
   );
 }
 
-export interface EmptyStateProps extends Omit<ComponentPropsWithoutRef<"div">, "children"> {
+export interface EmptyStateProps extends Omit<ComponentPropsWithoutRef<"div">, "children" | "title"> {
   /** The box renders `title` and `hint` in its own two-line rhythm, which is what makes
    *  every empty state in three apps look like the same thing — so there is no
    *  `children` slot to put arbitrary content in. The two slots below are the only
    *  other things an empty state has turned out to need, and each has a fixed place. */
-  title: string;
-  hint?: string;
+  /** Nodes rather than strings, so a title can carry a code, a link or an emphasised
+   *  word — keksdose's error boundary shows the error's name in `<code>` — while the
+   *  box still sets the type. */
+  title: ReactNode;
+  hint?: ReactNode;
+  /**
+   * Render the title as a heading of this level. Left out it is a `<div>`, as before:
+   * most empty states are a message inside a section that already has its heading.
+   * keksdose's error boundary IS the page when it trips, and its `<h2>` went missing
+   * when it moved onto EmptyState — so the page's heading outline lost the one line
+   * that says what happened. Only the element changes; the look is the box's.
+   */
+  headingAs?: "h2" | "h3" | "h4" | "h5" | "h6";
   /** A glyph ABOVE the title — kastlan's InboxEmptyState (an inbox), keksdose's
    *  offline card (a cloud with a slash). Sized by the box (`[&_svg]:size-8`) and
    *  muted, so five call sites cannot pick five sizes; hidden from assistive tech,
@@ -1353,7 +1402,8 @@ export interface EmptyStateProps extends Omit<ComponentPropsWithoutRef<"div">, "
   action?: ReactNode;
 }
 
-export function EmptyState({ title, hint, icon, action, className, ...rest }: EmptyStateProps) {
+export function EmptyState({ title, hint, icon, action, headingAs, className, ...rest }: EmptyStateProps) {
+  const Title = headingAs ?? "div";
   return (
     <div
       {...rest}
@@ -1367,8 +1417,9 @@ export function EmptyState({ title, hint, icon, action, className, ...rest }: Em
           {icon}
         </div>
       )}
-      <div className="font-medium text-[var(--text-secondary)]">{title}</div>
-      {hint && <div className="mt-1 text-xs">{hint}</div>}
+      {/* `text-sm`: a heading keeps the box's size, not whatever a stylesheet gives h2. */}
+      <Title className="text-sm font-medium text-[var(--text-secondary)]">{title}</Title>
+      {hint != null && hint !== false && hint !== "" && <div className="mt-1 text-xs">{hint}</div>}
       {action != null && (
         <div className="mt-4 flex flex-wrap items-center justify-center gap-2">{action}</div>
       )}

package/src/hooks/use-overlay-history.ts

@@ -81,9 +81,48 @@ interface PushedEntry {
   href: string;
   /** Its overlay is gone but the entry is not — someone above owes this pop. */
   dead: boolean;
+  /** The router's `idx` on this entry when the marker went on — see {@link locate}. */
+  idx: number | undefined;
+  /** The router's `key` copied from the page entry beneath ours. */
+  key: string | undefined;
+  /** {@link routeOf} the address the marker was placed at. */
+  route: string;
 }
 const pushed: PushedEntry[] = [];
 
+/**
+ * Entries of ours that a ROUTER NAVIGATION made from inside the overlay has left
+ * behind — ours, still in the history, but no longer on top and no longer anyone's.
+ *
+ * Nothing can take an entry out from under a newer one, so they cannot be unwound;
+ * what can be done is to not let the user land on one. A traversal that comes to
+ * rest on a buried entry is carried straight on over the whole run of them, in the
+ * direction it was going (see `skipBuried`): Back from the new page lands on the page
+ * the overlay was opened from, Forward from there lands on the new page, and no press
+ * is spent on an entry with nothing on screen for it.
+ *
+ * `below` / `above` count the buried entries of the same run on either side. The
+ * router's `idx` tells the direction apart — except after a REPLACE navigation, when
+ * the page above the run shares the run's `idx`; the two keys decide there.
+ */
+interface BuriedEntry {
+  idx: number;
+  /** The `idx` of the router entry that buried the run: higher after a push, the
+   *  same after a replace. */
+  aboveIdx: number;
+  /** The key of the page entry directly beneath the run. */
+  belowKey: string | undefined;
+  /** The key of the router entry that buried the run, when it did. */
+  aboveKey: string | undefined;
+  below: number;
+  above: number;
+}
+const buried = new Map<string, BuriedEntry>();
+
+/** The router `{idx, key}` of the entry the last traversal (or burial) left us on —
+ *  what `skipBuried` compares against to know which way the user was going. */
+let lastSeen: { idx: number | undefined; key: string | undefined } | null = null;
+
 /** Entries a real Back press already consumed. Their overlay's cleanup still has to
  *  run, and it must not mistake "my entry is not current" for "my entry is buried"
  *  — it has no entry left at all. */
@@ -140,7 +179,12 @@ function runUnwind(): void {
   const job = unwind;
   unwind = null;
   if (!job) return;
-  if (currentSentinel() !== job.id || currentHref() !== job.href) return;
+  if (currentSentinel() !== job.id || currentHref() !== job.href) {
+    // A router navigation landed between the cleanup and this task: the entries
+    // are under it (or were replaced by it) rather than simply forgotten.
+    if (taggedSentinel() === null) buryUnder(job.entries);
+    return;
+  }
   pendingProgrammatic += 1;
   window.history.go(-job.entries.length);
 }
@@ -149,6 +193,120 @@ function currentHref(): string {
   return typeof window === "undefined" ? "" : window.location.href;
 }
 
+/** The router's own `{idx, key}` on the current entry, where a router has put them. */
+function routerMark(): { idx: number | undefined; key: string | undefined } {
+  const state = typeof window !== "undefined" ? (window.history.state as unknown) : null;
+  if (!state || typeof state !== "object") return { idx: undefined, key: undefined };
+  const { idx, key } = state as Record<string, unknown>;
+  return { idx: typeof idx === "number" ? idx : undefined, key: typeof key === "string" ? key : undefined };
+}
+
+/**
+ * The part of an address that names the PAGE — the query string left out.
+ *
+ * A `setSearchParams(…, { replace: true })` rewrites the query on the entry the
+ * overlay is standing on; that is a wipe to repair, not a move. Anything else changing
+ * is a navigation. Under a hash router the page lives in the hash (`#/table?f.q=x`), so
+ * a hash that starts with `#/` counts up to its own `?`; an ordinary `#fragment` does
+ * not name a page and is left out.
+ */
+function routeOf(href: string): string {
+  try {
+    const url = new URL(href);
+    const hashRoute = url.hash.startsWith("#/") ? url.hash.split("?")[0] : "";
+    return url.origin + url.pathname + hashRoute;
+  } catch {
+    return href;
+  }
+}
+
+/**
+ * Is the untagged entry we are standing on still `p`'s — merely wiped by the router —
+ * or an entry the router NAVIGATED to from inside the overlay?
+ *
+ * The router's `idx` is the one per-entry fact that separates the two, because it is
+ * the one the router itself keeps straight: a replace leaves it as it was, a push adds
+ * one. Our own push copies the page's state, so our entry carries the page's `idx` and
+ * a router push on top of it carries one more. The key would not do — every replace
+ * mints a new one, so the wipe this repair exists for would already fail it. Neither
+ * would the address alone: a push to the address we are already at is still a push.
+ *
+ * `idx` does not see one move, the router REPLACING our entry with a different page
+ * (same `idx`), so the page named by the address must also be unchanged. Where there is
+ * no `idx` to compare (no router, or one that keeps none) the address is all there is.
+ */
+function isStillOn(p: PushedEntry): boolean {
+  if (routeOf(currentHref()) !== p.route) return false;
+  const { idx } = routerMark();
+  return idx === undefined || p.idx === undefined || idx === p.idx;
+}
+
+/**
+ * The router has navigated while our entries were on top: record which of `records`
+ * (ours, oldest first, ending with the top one) it buried and which it replaced, and
+ * drop them from `pushed` — none of them can be unwound any more. Returns whether it
+ * recognised a navigation at all; when it cannot tell (no router `idx` to go by), it
+ * leaves everything as it was and the caller falls back to marking the entry dead.
+ */
+function buryUnder(records: PushedEntry[]): boolean {
+  const top = records[records.length - 1];
+  const here = routerMark();
+  if (!top || top.idx === undefined || here.idx === undefined) return false;
+  let run: PushedEntry[];
+  if (here.idx > top.idx) {
+    run = [];
+    for (let i = records.length - 1; i >= 0 && records[i].idx === top.idx; i -= 1) run.unshift(records[i]);
+  } else if (here.idx === top.idx && !isStillOn(top)) {
+    // Replaced: the top entry IS the new page now, and gone as ours. Those beneath it
+    // are buried under it.
+    run = [];
+    for (let i = records.length - 2; i >= 0 && records[i].idx === top.idx; i -= 1) run.unshift(records[i]);
+  } else {
+    return false;
+  }
+  run.forEach((r, i) => {
+    buried.set(r.id, {
+      idx: top.idx as number,
+      aboveIdx: here.idx as number,
+      belowKey: run[0].key,
+      aboveKey: here.key,
+      below: i,
+      above: run.length - 1 - i,
+    });
+  });
+  for (const r of records) forgetPushed(r.id);
+  lastSeen = here;
+  return true;
+}
+
+/**
+ * A traversal came to rest on one of our buried entries: carry it on over the run, the
+ * way it was going. Back from above (a higher `idx`, or the very entry that buried us)
+ * continues down to the page beneath; Forward from that page continues up. A landing
+ * from anywhere this cannot place is left alone — one idle press is the price of not
+ * guessing, and a wrong guess would move the user somewhere they did not ask to go.
+ */
+function skipBuried(from: typeof lastSeen): void {
+  const tag = taggedSentinel();
+  const rec = tag !== null ? buried.get(tag) : undefined;
+  if (!rec || !from || stack.some((e) => e.id === tag)) return;
+  let steps = 0;
+  if ((from.idx !== undefined && from.idx > rec.idx) || (from.key !== undefined && from.key === rec.aboveKey)) {
+    steps = -(rec.below + 1);
+  } else if (
+    from.idx !== undefined &&
+    // Below the run, or level with it when nothing above it is (a push buried it),
+    // or level with it and provably the page beneath (a replace buried it). The
+    // router's first entry has no key at all, so an absent key is a key here.
+    (from.idx < rec.idx || (from.idx === rec.idx && (rec.aboveIdx > rec.idx || from.key === rec.belowKey)))
+  ) {
+    steps = rec.above + 1;
+  }
+  if (steps === 0) return;
+  pendingProgrammatic += 1;
+  window.history.go(steps);
+}
+
 function forgetPushed(id: string): void {
   const at = pushed.findIndex((p) => p.id === id);
   if (at >= 0) pushed.splice(at, 1);
@@ -210,7 +368,14 @@ function currentSentinel(): string | null {
   // belief left over from an overlay that is long gone — a tab that has since
   // navigated, a test file that ran another case — would be stamped onto a
   // stranger's entry, and the next cleanup would traverse off it.
-  if (!pushed.some((p) => p.id === standing)) {
+  //
+  // And only an entry that is still the one the marker was placed on. A row that
+  // NAVIGATES (a palette result, a dialog's link) has the router push the new page
+  // before the overlay's cleanup runs; that entry carries no tag either, and
+  // re-stamping it made the cleanup "unwind" the navigation itself — the page
+  // changed and changed straight back. See `isStillOn` for how the two are told apart.
+  const record = pushed.find((p) => p.id === standing);
+  if (!record || !isStillOn(record)) {
     standing = null;
     return null;
   }
@@ -223,10 +388,17 @@ function handlePop() {
   // entry we have landed on before anything below consults it, or the repair in
   // `currentSentinel` would stamp the entry we just left onto the one we are on.
   standing = taggedSentinel();
+  const from = lastSeen;
+  lastSeen = routerMark();
   if (pendingProgrammatic > 0) {
     pendingProgrammatic -= 1;
     return;
   }
+  closeOnPop();
+  skipBuried(from);
+}
+
+function closeOnPop() {
   // Nothing open → an ordinary navigation, which is none of our business.
   const top = stack[stack.length - 1];
   if (!top) return;
@@ -290,7 +462,8 @@ export function useOverlayHistory(open: boolean, onClose: () => void): void {
       window.history.replaceState(marked, "");
       // The abandoned ones beneath come back owed; ours takes the top slot.
       for (const owed of inherited.slice(0, -1)) pushed.push({ ...owed, dead: true });
-      pushed.push({ id, href: currentHref(), dead: false });
+      const was = inherited[inherited.length - 1];
+      pushed.push({ id, href: currentHref(), dead: false, idx: was.idx, key: was.key, route: was.route });
       standing = id;
     } else {
       // A push DESTROYS every entry ahead of the one we are on, so anything we
@@ -304,7 +477,8 @@ export function useOverlayHistory(open: boolean, onClose: () => void): void {
       // Preserve react-router's own `{usr,key,idx}` — we only tack a marker on, and
       // the URL is unchanged, so the router treats popping this as a no-op re-render.
       window.history.pushState(marked, "");
-      pushed.push({ id, href: currentHref(), dead: false });
+      const page = routerMark();
+      pushed.push({ id, href: currentHref(), dead: false, idx: page.idx, key: page.key, route: routeOf(currentHref()) });
       standing = id;
     }
     return () => {
@@ -320,6 +494,9 @@ export function useOverlayHistory(open: boolean, onClose: () => void): void {
       // a SIBLING overlay's sentinel landed on top, that overlay is about to unwind
       // and is the one that can take ours with it.
       if (currentSentinel() !== id) {
+        // A router navigation from inside the overlay: nothing to unwind — the
+        // entries it left beneath the new page are skipped over instead.
+        if (mine >= 0 && taggedSentinel() === null && buryUnder(pushed.slice(0, pushed.length))) return;
         if (mine >= 0) pushed[mine].dead = true;
         return;
       }