basalt-ui 1.29.2 → 1.30.1

package/src/shell/app-mobile-nav.tsx

@@ -7,7 +7,8 @@
  * page used to cost a tap to open a sheet plus a tap to pick a row. An overlay now exists only
  * where a slot genuinely holds more than one destination (the trailing "More" slot, or an opt-in
  * group slot), and its surface is INFERRED from the row count rather than configured: a content-
- * sized `Menu` that pops out of the tab up to `menuMax` rows, a bottom `Drawer` past it.
+ * sized `Menu` that pops out of the tab up to `menuMax` rows, a bottom `Drawer` past it. The menu
+ * is bounded by its own `max-height`, so `menuMax` decides taste, never whether it fits.
  *
  * This component paints a finished `MobileNavModel` and owns exactly one piece of state — which
  * slot's surface is open. Every selection decision lives in `mobile-nav-model.ts`, which is pure.
@@ -45,8 +46,9 @@ import classes from './app-mobile-nav.module.css'
 
 /**
  * Floating-ui middlewares for a tab menu. `flip: false` is correct, not lazy: flipping a
- * bottom-anchored menu puts it UNDER the footer, off-screen — `menuMax` is what guarantees it fits
- * above the bar (§2.2). `shift.padding` is a viewport inset in px, not a layout spacing token.
+ * bottom-anchored menu puts it UNDER the footer, off-screen. What guarantees it fits above the bar
+ * is `.menuDropdown`'s own `max-height` (see the CSS module) — NOT `menuMax`, which is only the
+ * menu-vs-sheet threshold. `shift.padding` is a viewport inset in px, not a layout spacing token.
  */
 const MENU_MIDDLEWARES = { flip: false, shift: { padding: 8 } }
 
@@ -198,49 +200,36 @@ function settingsRows(items: SettingsMenuItem[] | undefined): ActionRow[] {
   }))
 }
 
-/** One destination row, in a `Menu` dropdown. `depth` indents a nested child. */
-const menuRow = (item: SidebarItem, depth: number): ReactElement => {
-  // `.menuItem[data-disabled] { pointer-events: none }` is the primary guard, but it cannot be the
-  // only one: Mantine's `MenuItem` composes the CALLER's `onClick` first and only then checks
-  // `data-disabled` itself, so anything that reaches the node without a pointer — a keyboard
-  // activation, a synthetic click, a consumer stylesheet resetting `pointer-events` — would still
-  // fire the destination's handler on a row the projection deliberately rendered dead (§2.9).
-  const onClick = (event: MouseEvent<HTMLElement>) => {
-    if (item.disabled) {
-      event.preventDefault()
-      return
+/**
+ * The deepest element inside `root` that is CURRENTLY scrolled, or `null`.
+ *
+ * `common/scroll-parent.ts`'s `scrollParentOf` asks the opposite question — which ANCESTOR scrolls
+ * a given element — and this twin deliberately stays local rather than joining it there. That
+ * module is a shared vocabulary with several consumers and one meaning ("which box scrolls this");
+ * this is a scroll-to-top TARGET search with exactly one call site, a visibility rule and a
+ * deepest-wins tiebreak that only make sense for it. Per the consolidation doctrine a new shared
+ * export needs a named consumer outside the module that wanted it; this one does not have a second.
+ *
+ * Deepest wins because nested scrollers nest by specificity: a page scroller holding a thread pane
+ * means the pane is the surface the user is looking at. Visibility is part of "actually scrolled" —
+ * a hidden box keeps its `scrollTop` forever — but `getClientRects()` is only asked of the handful
+ * of nodes that pass the cheap `scrollTop` test, never of the whole tree.
+ */
+function deepestScrolledDescendant(root: ParentNode | null): HTMLElement | null {
+  if (root === null) return null
+  let best: HTMLElement | null = null
+  let bestDepth = -1
+  for (const node of root.querySelectorAll<HTMLElement>('*')) {
+    if (node.scrollTop <= 0) continue
+    if (node.getClientRects().length === 0) continue
+    let depth = 0
+    for (let parent = node.parentElement; parent !== null; parent = parent.parentElement) depth += 1
+    if (depth > bestDepth) {
+      best = node
+      bestDepth = depth
     }
-    item.onClick?.(event)
-  }
-  const shared = {
-    className: depth > 0 ? `${classes.menuItem} ${classes.menuItemNested}` : classes.menuItem,
-    leftSection: item.icon,
-    disabled: Boolean(item.disabled),
-    // Mantine emits `data-disabled` (a STYLING hook) and nothing else, so the ARIA state is ours
-    // to set — a disabled destination still renders (§2.3 rule 11), so it has to announce itself.
-    'aria-disabled': item.disabled || undefined,
-    'aria-current': item.active ? ('page' as const) : undefined,
-    rightSection: item.count ? <NavCountBadge count={item.count} /> : undefined,
-    onClick,
   }
-  const Anchor = item.Anchor
-  if (Anchor && !item.disabled) {
-    return (
-      <Menu.Item key={item.key} component={Anchor} {...shared}>
-        {item.label}
-      </Menu.Item>
-    )
-  }
-  return (
-    <Menu.Item
-      key={item.key}
-      component="a"
-      {...(item.href !== undefined && !item.disabled && { href: item.href })}
-      {...shared}
-    >
-      {item.label}
-    </Menu.Item>
-  )
+  return best
 }
 
 /** Depth-first: parent, then its children as indented rows — nesting survives to mobile. */
@@ -251,11 +240,12 @@ const rows = (
 ): ReactElement[] =>
   items.flatMap((item) => [render(item, depth), ...rows(item.children ?? [], depth + 1, render)])
 
-/** An account/settings row, in a `Menu` dropdown. */
-const menuActionRow = (row: ActionRow) => (
+/** An account/settings row, in a `Menu` dropdown. `sectionStart` draws the tail's own top rule
+ *  (see `tailRule` and `menuSlot`) when this is the first row of the unlabelled tail. */
+const menuActionRow = (row: ActionRow, sectionStart = false) => (
   <Menu.Item
     key={row.key}
-    className={classes.menuItem}
+    className={sectionStart ? `${classes.menuItem} ${classes.menuSectionStart}` : classes.menuItem}
     leftSection={row.icon}
     rightSection={row.active ? <IconCheck /> : undefined}
     {...(row.danger ? { color: 'red' } : {})}
@@ -296,20 +286,63 @@ export function MobileNav({
 
   const close = () => setOpenKey(null)
 
+  /** Scrolls `target` only if it has somewhere to go. The return value is the whole point — see
+   *  `scrollToTop`: "I asked it to scroll" and "it scrolled" are different facts. */
+  const scrollElementToTop = (target: Element | null | undefined): boolean => {
+    if (!target || target.scrollTop <= 0) return false
+    target.scrollTo({ top: 0, behavior: reduceMotion ? 'auto' : 'smooth' })
+    return true
+  }
+
   /**
    * §2.5 — re-tapping the ACTIVE slot scrolls to top instead of pushing a redundant history entry.
    *
-   * `AppShell.Main` is the shell's scrollport (`app-main.module.css`), so `document.scrollingElement`
-   * scrolls nothing inside a shell and the tap read as dead. The declared handle comes FIRST after
-   * the consumer's own override, and the document stays the fallback for a shell-less app.
+   * RETURNS WHETHER ANYTHING ACTUALLY SCROLLED, and that is the fix for the reported dead tap. The
+   * old version resolved `[data-basalt-scrollport]` (= `AppShell.Main`) and scrolled it
+   * unconditionally, while the caller had ALREADY suppressed the navigation. On any page whose
+   * real scroller is an INNER element — `/agent`'s thread panes, `/data`'s
+   * `Table.ScrollContainer`, `/content`'s article body — Main's own `scrollTop` is 0, so the scroll
+   * moved nothing and the navigation was gone too: a 100% dead tap, on exactly the pages that have
+   * the most to scroll.
+   *
+   * So the search widens and the answer is honest. The consumer's handle wins, then the declared
+   * scrollport, then the deepest inner scroller that is genuinely scrolled, then the document for a
+   * shell-less app. A `false` here means the caller must let the navigation through — a redundant
+   * same-route navigation is strictly better than silence.
    */
-  const scrollToTop = () => {
-    const target =
-      config?.getScrollElement?.() ??
-      document.querySelector(`[${SCROLLPORT_ATTRIBUTE}]`) ??
-      document.scrollingElement ??
-      document.documentElement
-    target.scrollTo({ top: 0, behavior: reduceMotion ? 'auto' : 'smooth' })
+  const scrollToTop = (): boolean => {
+    const declared =
+      config?.getScrollElement?.() ?? document.querySelector(`[${SCROLLPORT_ATTRIBUTE}]`)
+    if (scrollElementToTop(declared)) return true
+    if (scrollElementToTop(deepestScrolledDescendant(declared ?? document.body))) return true
+    return scrollElementToTop(document.scrollingElement ?? document.documentElement)
+  }
+
+  /**
+   * §2.5 + §2.9 in ONE place, because the three row builders used to disagree about what a tap on
+   * a row MEANS. `linkTab` implemented the active-retap rule and `menuRow`/`sheetRow` did not, so
+   * a row inside the More surface rendered `aria-current="page"` and then navigated to the route
+   * it was already on — the router no-ops, the surface closes, nothing moves. Since More is where
+   * most destinations live the moment the bar is full, that was the MORE common dead tap of the
+   * two. `sheetRow` was also missing the disabled guard `menuRow` carries.
+   *
+   * Order is load-bearing: the scroll is ATTEMPTED FIRST and the navigation is suppressed only if
+   * something really moved (`scrollToTop`'s doc). Returns `false` when the tap was swallowed by
+   * the disabled guard, so a caller owning a surface knows not to dismiss it.
+   */
+  const onActivate = (item: SidebarItem, event: MouseEvent<HTMLElement>): boolean => {
+    // Mantine emits `data-disabled` as a STYLING hook and the rows are polymorphic
+    // (`component="a"`/the consumer's Anchor), so the native `disabled` attribute never applies —
+    // and `MenuItem` composes the CALLER's `onClick` before checking `data-disabled` itself. The
+    // CSS no longer sets `pointer-events: none` (a row that swallows a tap with no press state is
+    // indistinguishable from a broken one), which makes this the ONLY guard, on every path.
+    if (item.disabled) {
+      event.preventDefault()
+      return false
+    }
+    if (item.active === true && scrollToTop()) event.preventDefault()
+    item.onClick?.(event)
+    return true
   }
 
   const extraRows = [...accountRows(account), ...settingsRows(settingsMenuItems)]
@@ -326,18 +359,38 @@ export function MobileNav({
   )
   const listBlocks = moreBlocks.filter((block): block is SidebarListBlock => block.kind === 'list')
 
+  /**
+   * Whether the More surface's UNLABELLED tail (blocks + account + settings) opens its own band —
+   * the guard the deleted `Menu.Divider` used to carry inline. A separator separates: with no
+   * destination rows above it, a More slot raised purely by those rows would open a band under the
+   * dropdown's top edge with nothing on the other side of it.
+   */
+  const tailRule = (slot: SurfaceSlot): boolean =>
+    moreBlocks.length + extraRows.length > 0 && slotHasRows(slot)
+
   /** A list block raises its nested sheet; a progress block just fires its own handler. */
   const activateBlock = (block: (typeof moreBlocks)[number]) => {
     close()
     if (block.kind === 'list') {
-      setOpenBlockKey(block.key)
+      // ONE FRAME, deliberately. `close()` starts the Menu's `returnFocus` (it restores focus to
+      // the More tab) while the nested Drawer traps focus on mount — in the same handler the two
+      // race, and focus lands wherever the loser wrote last, which is how a tap on a block row
+      // could leave the sheet open with focus back on the bar behind it. Deferring the open by one
+      // rAF lets the return finish before the trap starts.
+      requestAnimationFrame(() => setOpenBlockKey(block.key))
       return
     }
     block.onClick?.()
   }
 
-  const menuBlockRow = (block: (typeof moreBlocks)[number]) => (
-    <Menu.Item key={block.key} className={classes.menuItem} onClick={() => activateBlock(block)}>
+  const menuBlockRow = (block: (typeof moreBlocks)[number], sectionStart = false) => (
+    <Menu.Item
+      key={block.key}
+      className={
+        sectionStart ? `${classes.menuItem} ${classes.menuSectionStart}` : classes.menuItem
+      }
+      onClick={() => activateBlock(block)}
+    >
       {blockRowLabel(block)}
     </Menu.Item>
   )
@@ -411,17 +464,25 @@ export function MobileNav({
   )
 
   /**
-   * The trigger for a `menu`/`sheet` slot. A plain button: Mantine's `Menu.Target` clones
-   * `aria-haspopup`/`aria-expanded`/`aria-controls` onto it (`withRoles` default), so hand-setting
-   * them here would double them up (§2.9).
+   * The trigger for a `menu`/`sheet` slot.
+   *
+   * The two paths differ in who owns the ARIA, and the guard below is what keeps them apart. On
+   * the MENU path the button is a `Menu.Target` child, so Mantine clones
+   * `aria-haspopup`/`aria-expanded`/`aria-controls` onto it (`withRoles` default) and setting them
+   * here would double them up (§2.9). On the SHEET path there is no `Menu.Target` and no clone at
+   * all, so the trigger announced nothing — a button that opens a dialog and says so only to
+   * sighted users. `onClick` is present on exactly the sheet path, which is why it is the
+   * discriminator rather than a second parameter that could disagree with reality.
    */
-  const surfaceTab = (slot: SurfaceSlot, onClick?: () => void) => (
+  const surfaceTab = (slot: SurfaceSlot, onClick?: () => void, expanded?: boolean) => (
     <UnstyledButton
       className={classes.tab}
       data-active={slot.active || undefined}
       aria-current={slot.active ? 'page' : undefined}
       aria-label={slot.label}
-      {...(onClick ? { onClick } : {})}
+      {...(onClick
+        ? { onClick, 'aria-haspopup': 'dialog' as const, 'aria-expanded': Boolean(expanded) }
+        : {})}
     >
       {tabInner(slot)}
     </UnstyledButton>
@@ -429,14 +490,12 @@ export function MobileNav({
 
   /** A `link` slot: the consumer's router anchor IS the tab, so preload/back/middle-click all work. */
   const linkTab = (slot: LinkSlot) => {
+    // VERIFIED in @tanstack/react-router: `Link` composes the caller's handler FIRST and returns
+    // early when `defaultPrevented`, so `onActivate` suppresses navigation without touching
+    // preload. A link slot's `active` and its item's `active` are the same fact by construction —
+    // every path that builds one reads `isActiveDestination` (`mobile-nav-model.ts`).
     const onClick = (e: MouseEvent<HTMLElement>) => {
-      // VERIFIED in @tanstack/react-router: `Link` composes the caller's handler FIRST and returns
-      // early when `defaultPrevented`, so this suppresses navigation without touching preload.
-      if (slot.active) {
-        e.preventDefault()
-        scrollToTop()
-      }
-      slot.item.onClick?.(e)
+      onActivate(slot.item, e)
     }
     const shared = {
       className: classes.tab,
@@ -465,10 +524,53 @@ export function MobileNav({
     )
   }
 
+  /**
+   * One destination row, in a `Menu` dropdown. `depth` indents a nested child.
+   *
+   * Lives INSIDE the component (it used to be a module-level const) for one reason: it needs
+   * `onActivate`, which needs `scrollToTop`, which needs `config` and `reduceMotion`. Recreating
+   * it per render costs what `sheetRow` already costs and buys all three row builders one handler.
+   */
+  const menuRow = (item: SidebarItem, depth: number): ReactElement => {
+    const shared = {
+      className: depth > 0 ? `${classes.menuItem} ${classes.menuItemNested}` : classes.menuItem,
+      leftSection: item.icon,
+      disabled: Boolean(item.disabled),
+      // Mantine emits `data-disabled` (a STYLING hook) and nothing else, so the ARIA state is ours
+      // to set — a disabled destination still renders (§2.3 rule 11), so it has to announce itself.
+      'aria-disabled': item.disabled || undefined,
+      'aria-current': item.active ? ('page' as const) : undefined,
+      rightSection: item.count ? <NavCountBadge count={item.count} /> : undefined,
+      onClick: (event: MouseEvent<HTMLElement>) => {
+        onActivate(item, event)
+      },
+    }
+    const Anchor = item.Anchor
+    if (Anchor && !item.disabled) {
+      return (
+        <Menu.Item key={item.key} component={Anchor} {...shared}>
+          {item.label}
+        </Menu.Item>
+      )
+    }
+    return (
+      <Menu.Item
+        key={item.key}
+        component="a"
+        {...(item.href !== undefined && !item.disabled && { href: item.href })}
+        {...shared}
+      >
+        {item.label}
+      </Menu.Item>
+    )
+  }
+
   /** One destination row, in the sheet. 44px minimum, per the touch-target floor. */
   const sheetRow = (item: SidebarItem, depth: number): ReactElement => {
     const onClick = (e: MouseEvent<HTMLElement>) => {
-      item.onClick?.(e)
+      // The disabled guard `menuRow` always had, now shared — a dead row must not dismiss the
+      // sheet either, or the tap reads as "it did something" while going nowhere.
+      if (!onActivate(item, e)) return
       close()
     }
     const shared = {
@@ -522,7 +624,12 @@ export function MobileNav({
       onChange={(opened) => setOpenKey(opened ? slot.key : null)}
       position={slot.isMore ? 'top-end' : 'top'}
       offset={8}
-      width={step.mobileNavMenuWidth}
+      // Only the More dropdown widens. `mobileNavMenuWidth` (232px) is sized for a section slot's
+      // short destination labels; More also carries block rows like `Awaiting action · 3` and
+      // account rows like `Billing & payment`, which wrap or clip at that width. A viewport-
+      // relative cap rather than a second token: it is a fraction of the phone it opens on, and it
+      // is the only surface in the bar whose contents are not the consumer's nav labels.
+      width={slot.isMore ? 'min(78vw, 300px)' : step.mobileNavMenuWidth}
       withinPortal
       // AppShell itself sits at z-index 100 (`getDefaultZIndex('app')`), so the menu must clear it.
       zIndex={400}
@@ -550,25 +657,50 @@ export function MobileNav({
             : []),
           ...rows(group.items, 0, menuRow),
         ])}
-        {/* A separator separates. With nothing above it — a More slot raised purely by the block,
-            account and settings rows — it would render as the dropdown's first child, a rule under
-            the top edge. Both sides have to exist. */}
-        {slot.isMore && moreBlocks.length + extraRows.length > 0 && slotHasRows(slot) ? (
-          <Menu.Divider />
-        ) : null}
-        {slot.isMore ? moreBlocks.map(menuBlockRow) : null}
-        {slot.isMore ? extraRows.map(menuActionRow) : null}
+        {/* The `Menu.Divider` node that used to sit here is gone: section rhythm is SPACE opened
+            by each group's own heading (`.menuDropdown .menuLabel:not(:first-child)` in the CSS
+            module, which explains why it is space and not a line — `theme/divider-law.test.ts`
+            bans a hairline under a heading in the chrome lane). That is what makes the popover
+            read as sections instead of as one long list, which is the structure the More surface
+            needed a whole Drawer to get. The unlabelled tail (blocks + account + settings) has no
+            heading to open its band, so its FIRST row carries `.menuSectionStart` instead. The old
+            guard survives verbatim in `tailRule`: a separator separates, so with nothing above it
+            — a More slot raised purely by those rows — no band opens at all. */}
+        {slot.isMore
+          ? moreBlocks.map((block, index) => menuBlockRow(block, tailRule(slot) && index === 0))
+          : null}
+        {slot.isMore
+          ? extraRows.map((row, index) =>
+              menuActionRow(row, tailRule(slot) && moreBlocks.length === 0 && index === 0),
+            )
+          : null}
       </Menu.Dropdown>
     </Menu>
   )
 
   const sheetSlot = (slot: SurfaceSlot) => (
     <Fragment key={slot.key}>
-      {surfaceTab(slot, () => setOpenKey(slot.key))}
+      {/* A real TOGGLE, not a setter. It used to be `() => setOpenKey(slot.key)`, so re-tapping an
+          open sheet's own tab did nothing at all — while the menu path, which gets Mantine's
+          disclosure behaviour for free, closed on the second tap. Same trigger, same gesture, two
+          different answers. */}
+      {surfaceTab(
+        slot,
+        () => setOpenKey(openKey === slot.key ? null : slot.key),
+        openKey === slot.key,
+      )}
       <Drawer
         opened={openKey === slot.key}
         onClose={close}
         position="bottom"
+        // The bar is inside `AppShell.Footer` at z-index 100 and Mantine's modal default is 200, so
+        // the Drawer's OVERLAY covered the bar. Combined with `lockScroll` and a 220ms exit, that
+        // overlay stayed hit-testable after `onClose`: with a sheet open, a tap on another tab
+        // dismissed the sheet and did nothing else, and a quick second tap was eaten by the exiting
+        // overlay. Matching the Menu's 400 puts the bar and its surfaces on one layer, and a
+        // shorter exit shrinks the window in which a closing overlay can still swallow a tap.
+        zIndex={400}
+        overlayProps={{ zIndex: 400 }}
         // NO `size` prop — `size="auto"` used to be here, but it is a no-op on a bottom Drawer in
         // Mantine 9.3.0 (see the `.sheet` rule in the CSS module for the full trap). The sheet's
         // actual height/max-height comes entirely from that unlayered CSS rule, which overrides
@@ -589,6 +721,10 @@ export function MobileNav({
         transitionProps={{
           transition: 'slide-up',
           duration: reduceMotion ? 0 : 220,
+          // Asymmetric on purpose: the entrance may take its time, the EXIT is a hit-test window.
+          // Mantine's default exit equals the duration, so a dismissed sheet left 220ms of live
+          // overlay over the bar — long enough to eat the next tab tap.
+          exitDuration: reduceMotion ? 0 : 120,
           timingFunction: 'cubic-bezier(0.32, 0.72, 0, 1)',
         }}
       >
@@ -636,6 +772,10 @@ export function MobileNav({
       opened={openBlockKey === block.key}
       onClose={() => setOpenBlockKey(null)}
       position="bottom"
+      // Same layer as `sheetSlot`'s Drawer and the Menu — see that one's note. This sheet is
+      // reached FROM the More surface, so it inherits the same overlay-over-the-bar problem.
+      zIndex={400}
+      overlayProps={{ zIndex: 400 }}
       padding="md"
       title={block.label}
       classNames={{
@@ -646,6 +786,8 @@ export function MobileNav({
       transitionProps={{
         transition: 'slide-up',
         duration: reduceMotion ? 0 : 220,
+        // Same reasoning as `sheetSlot`'s Drawer — a long exit leaves a live overlay over the bar.
+        exitDuration: reduceMotion ? 0 : 120,
         timingFunction: 'cubic-bezier(0.32, 0.72, 0, 1)',
       }}
     >

package/src/shell/app-sidebar.module.css

@@ -142,12 +142,50 @@
 
 /* Re-apply the bled inset INSIDE the viewport, so rows keep their exact 10px/10px column while the
  * bar floats clear of them in the gutter. Static padding, not Mantine's `offsetScrollbars`: the
- * latter pads only while overflowing, which reflows the rows the moment a section expands. */
+ * latter pads only while overflowing, which reflows the rows the moment a section expands.
+ *
+ * `padding-block-end` is the scroll END-STOP: with only the inline inset, an overflowing column
+ * cut its last row flush against the viewport edge, which reads as a label whose list is CLIPPED
+ * rather than as something that scrolls. One `region-gap` of air below the last row is the same
+ * number the search slot opens at the column's other end.
+ *
+ * The end-stop is necessary and NOT sufficient, and the mask below is the other half. MEASURED at
+ * 1512x945 with the playground's nav: `.navScroll` is `flex: 1; min-height: 0` between the search
+ * slot and a `flex-shrink: 0` footer, so any nav taller than the leftover column overflows — and
+ * the end-stop only pads the BOTTOM OF THE CONTENT, which the reader sees exactly once, at the
+ * scroll end. Everywhere else the viewport's own edge cuts whatever row happens to cross it, and
+ * `.footer`'s progress block starts one `region-gap` under that cut. Two hard edges 12px apart:
+ * the column reads BROKEN rather than scrolled. Nothing else says otherwise, because the
+ * ScrollArea is `type="hover"` — at rest there is no bar at all.
+ *
+ * So: a scroll fade on the viewport's bottom edge, and deliberately NOT the other candidate, a
+ * `--vx-divider` seam on `.footer`. A rule there would answer a question nobody asked — the footer
+ * boundary is already carried by its own `padding-top` and the account row's inset (see `.footer`
+ * below) — and it would answer the real one WRONG: a hairline drawn across a row that is severed
+ * mid-glyph makes the severing crisper, not legible. A fade is the only one of the two that says
+ * "there is more, and it moves". It also keeps this module out of `theme/divider-law.test.ts`'s
+ * inventory, which is the correct outcome and not a dodge: that ledger exists so every hairline is
+ * a line someone chose, and this one would have been chosen to stand in for a scrollbar.
+ *
+ * The ramp is one `region-gap` tall, which is what pairs it with the end-stop instead of fighting
+ * it: at the scroll END those 12px hold the end-stop's padding — empty — so the last row lands
+ * fully opaque, and a column that does not overflow fades nothing but its own trailing air. Only
+ * mid-scroll, where a real row crosses the edge, does the fade have anything to dim.
+ *
+ * `black`/`transparent` here are alpha, not color: a mask reads only the alpha channel, so these
+ * carry no design meaning and deliberately are NOT `--vx-*` tokens. Do not route them through the
+ * palette in a token sweep. */
 .navViewport {
   padding-inline-end: var(--vx-space-row-inset-x);
+  padding-block-end: var(--vx-space-sidebar-region-gap);
+  mask-image: linear-gradient(
+    to bottom,
+    black calc(100% - var(--vx-space-sidebar-region-gap)),
+    transparent
+  );
 }
 
-/* Sections separate by SPACING only — 15px between sections, nothing above the first (the brand
+/* Sections separate by SPACING only — 16px between sections, nothing above the first (the brand
  * band's centred `min-height` already opens the region's air, and the optional search slot's own
  * `padding-block` opens more when it renders). */
 .nav > div + div {
@@ -156,9 +194,24 @@
 
 /*
  * Footer region — no border; the account row's own top padding supplies the separation.
+ *
+ * The region owns its own air on both axes, because the `Stack` wrapping it is `gap={0}`
+ * (`app-sidebar.tsx`) — the footer's rhythm is single-sourced HERE, so the whole answer is
+ * readable in one place rather than split between a prop and a stylesheet. Without it a
+ * bottom-placed block (a `kind: 'progress'` block defaults to `'bottom'`) stacked FLUSH on the
+ * settings and account rows and on the scroll region above, which is the "cramped" footer.
+ *
+ * `region-gap` (12) above the cluster, `stack-sm` (8) between its parts — deliberately tighter
+ * than the nav's `section-gap` (16): the footer is ONE pinned cluster whose rows belong together,
+ * not a list of peer sections.
  */
 .footer {
   flex-shrink: 0;
+  padding-top: var(--vx-space-sidebar-region-gap);
+}
+
+.footer > * + * {
+  margin-top: var(--vx-space-stack-sm);
 }
 
 /*

package/src/shell/index.tsx

@@ -291,10 +291,6 @@ function collapseStore(key: string): () => readonly [boolean, (next: boolean) =>
   return store
 }
 
-// The shared inset for the shell padding and the header's inline padding, so the breadcrumb's
-// left edge and the global actions' right edge land on the card column's edges.
-const SHELL_INSET = 'sm' as const
-
 /**
  * The shell's two page-level regions are providers, and both wrap the frame rather than living
  * inside it: `PageBarProvider` owns the header portal and the single-kebab claim, `AsideProvider`
@@ -334,6 +330,30 @@ function ShellFrame({
   // (controls, the search trigger/avatar, nav labels) already track density, so a fixed literal
   // container squeezes progressively worse as density rises.
   const { step } = useBasaltSpacing()
+  // THE PAGE GUTTER, responsive — the shared inset for `AppShell`'s own padding and the header's
+  // inline padding, so the breadcrumb's left edge and the global actions' right edge land on the
+  // card column's edges. It used to be the literal `'sm'` spacing key, which is 13px at EVERY
+  // width: 13 on a 360px phone and 13 on a 2560px monitor, with no token behind it. Now it is the
+  // `appShellInset` / `appShellInsetMobile` pair (see their entries in `tokens/palette.ts`).
+  //
+  // On a 390px phone that is 8 a side instead of 13 — 10px more line width, and 10px less vertical
+  // chrome, since `padding` is Main's vertical inset too. From `sm` up it is 20, which is the x the
+  // sidebar's nav icon column already sits at, so the brand mark, the nav icons and the page's
+  // first column all start on one vertical line.
+  //
+  // VERIFIED against the installed Mantine 9.3 source, because both props take the object by a
+  // DIFFERENT road and both had to be checked:
+  //   - `AppShell padding`: `AppShellMediaStyles/assign-padding-variables.mjs` puts `base` in the
+  //     `:root` rule and every other key in `get-variables.mjs`'s MIN-width block
+  //     (`(min-width: <breakpoint>)`), so the pair is mobile-first and needs no max-width twin.
+  //   - `AppShell.Header px`: a Box style prop, `Box/style-props/parse-style-props.mjs` — same
+  //     `{ base, … }` shape, same `(min-width: theme.breakpoints.sm)` query, emitted on a generated
+  //     class. Both resolve `sm` from `theme.breakpoints`, so the two gutters step at one width.
+  // A NUMBER on either road is CONVERTED by Mantine's `rem()` — 8 becomes
+  // `calc(0.5rem * var(--mantine-scale))` — rather than looked up, which is exactly why these are
+  // numbers: a spacing KEY resolves to `var(--mantine-spacing-sm)` and hands the gutter back to
+  // Mantine's own scale, which is where the 13px came from.
+  const inset = { base: step.appShellInsetMobile, sm: step.appShellInset }
   const aside = useAsideRegion()
   const [storedCollapsed, setStoredCollapsed] = collapseStore(storageKey)()
   // Controlled/uncontrolled seam (item 19): an explicit `collapsed` prop overrides the internal
@@ -410,7 +430,7 @@ function ShellFrame({
       // A plain number, NOT a `calc(... + env(safe-area-inset-bottom))` string: Mantine's own
       // `.footer` rule already adds the inset to both the height and the padding (§2.7).
       footer={{ height: { base: step.mobileNavBarHeight, sm: 0 } }}
-      padding={SHELL_INSET}
+      padding={inset}
       // `mainClasses.shell` is not decoration — see its rule for why the root has to establish a
       // block formatting context now that Main is offset with margins.
       className={cx(mainClasses.shell, className)}
@@ -419,7 +439,7 @@ function ShellFrame({
       {/* Region seams (docs/DESIGN-SPEC.md §5, §8 #12): Mantine's `[data-with-border]` painted in
        * `--vx-divider` by the theme's `AppShell.extend({ vars })`. No shell module draws a region
        * edge; never opt a section back out of its border here. */}
-      <AppShell.Header px={SHELL_INSET}>
+      <AppShell.Header px={inset}>
         <div className={headerClasses.bar}>
           {/* The header's LEADING ZONE — exactly `--app-shell-navbar-offset` wide, so its trailing
            * edge lands on the sidebar|main seam and the breadcrumb after it starts on Main's own