basalt-ui 1.30.2 → 1.32.0

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

@@ -131,8 +131,59 @@
  * `padding-right`; the block padding keeps coming from the shorthand. The bottom inset already
  * rides `margin-bottom` above (`env(safe-area-inset-bottom)`); the PWA's top inset needs no rule here
  * (the status bar uses the opaque `default` style, per argo's own seed comment). */
-@media (display-mode: standalone) {
-  .main {
-    padding-right: max(var(--app-shell-padding), env(safe-area-inset-right));
+:global(:root[data-basalt-host]:not([data-basalt-host='web'])) .main {
+  padding-right: max(var(--app-shell-padding), env(safe-area-inset-right));
+}
+
+/*
+ * PUBLIC SHELL BOTTOM INSET — `--app-shell-footer-offset` (stable name, do not rename): the visible
+ * bottom-bar height WITHOUT the safe-area inset, and 0 wherever there is no bar (from `sm` up).
+ * Anything bottom-anchored (toasts, a chat composer) sits at
+ * `calc(var(--app-shell-footer-offset, 0px) + env(safe-area-inset-bottom, 0px))`.
+ *
+ * Mantine emits it on `:root` for a fixed-mode AppShell (its `cssVariablesSelector`), so a
+ * body-level portal reads it; the landscape override below is on `:root` for the same reason.
+ */
+
+/*
+ * An OPEN aside that does not dock: the region reserved only its rail, so it widens itself over
+ * main (`--app-shell-aside-width` is set on this element by `shell/index.tsx`) instead of shrinking
+ * it, lifted on the card depth token.
+ */
+.asideOverlay {
+  box-shadow: var(--vx-shadow-card);
+}
+
+/*
+ * Landscape phone: the header and the bottom bar take their compact row, SCALED to the viewport's
+ * own height budget rather than a flat step — a flat 40/45 barely shrinks (44→40, 56→45, ≈9-20%)
+ * against the height itself halving (812→375), so the chrome's SHARE of the screen nearly doubles
+ * (r2 N1: 16.7% portrait → 32.3% landscape even with the flat numbers). `clamp(floor, Ndvh,
+ * ceiling)` keeps continuity at the 480px breakpoint edge (Ndvh ≈ ceiling there) and keeps
+ * shrinking below it, down to a floor: 36px for the header (room for the brand/burger row), and
+ * `--vx-space-mobile-nav-row-height + 1px` (its own seam) for the bar — the row token, not a flat
+ * 45px, because `deriveSpacing`'s density knob only FLOORS that token at 44 and is free to scale it
+ * taller at density > 0; a hardcoded 45px floor would then clamp the footer BELOW its own row's
+ * real height at any positive density, clipping it. The heights are JS numbers in `AppShell` props,
+ * so the override is on `:root` where Mantine writes them; `:root:root` outranks its later-rendered
+ * `<style>` at equal source order. Both rules are gated to the same width — the header and the bar
+ * both exist ONLY below `sm` in this landscape-compact form; a wide landscape phone/tablet has no
+ * bar (and keeps `--app-shell-footer-offset` 0) and reads its header at the ordinary, un-clamped
+ * height, not this mobile row. Labels hidden: `app-mobile-nav.module.css`.
+ */
+@media (max-height: 480px) and (orientation: landscape) and (max-width: 52.49375em) {
+  :global(:root:root) {
+    --app-shell-header-height: clamp(36px, 9dvh, 40px);
+    --app-shell-header-offset: clamp(36px, 9dvh, 40px);
+    --app-shell-footer-height: clamp(
+      calc(var(--vx-space-mobile-nav-row-height) + 1px),
+      9.4dvh,
+      56px
+    );
+    --app-shell-footer-offset: clamp(
+      calc(var(--vx-space-mobile-nav-row-height) + 1px),
+      9.4dvh,
+      56px
+    );
   }
 }

package/src/shell/app-main.module.css.d.ts

@@ -7,5 +7,6 @@ declare const classes: {
   readonly shell: string
   readonly band: string
   readonly main: string
+  readonly asideOverlay: string
 }
 export default classes

package/src/shell/app-mobile-nav.module.css

@@ -195,7 +195,7 @@
  * The popover's SECTION RHYTHM — what replaced the single `Menu.Divider`, and it is SPACE, not a
  * line.
  *
- * The Drawer's bulk was never its row height (40px is a WCAG 2.5.5 floor pinned by
+ * The Drawer's bulk was never its row height (44px is the WCAG 2.5.5 AAA-enhanced floor pinned by
  * `theme/density-relations.test.ts`); it was the stack rhythm around the rows — a 12px section
  * gap, 18px of Drawer padding and a header row. A popover with one hairline through the middle and
  * no rhythm at all is the other extreme, so each group opens its own band instead.
@@ -218,8 +218,8 @@
  * `max-height` above answers, and the cheaper half. MEASURED per heading at 8/8: 8px margin + 8px
  * padding-top + 2px padding-bottom + a 17px line = a 35px box, and there are FIVE of them in the
  * shipped More surface — 175px, 28% of the whole dropdown spent on five words. 6/4 takes each
- * banded heading to 29px and hands 24px back to the rows. It does NOT touch the row height (40px
- * is the WCAG 2.5.5 floor named at the top of this comment) and it does not add the line the
+ * banded heading to 29px and hands 24px back to the rows. It does NOT touch the row height (44px
+ * is the WCAG 2.5.5 AAA-enhanced floor named at the top of this comment) and it does not add the line the
  * paragraph above rules out: this is the same space that argument asked to carry the boundary,
  * spent tighter.
  */
@@ -331,7 +331,7 @@
  * longer fights that — it used to force the dense desktop row's padding back OPEN with
  * `!important`, which is exactly how a "44px touch row" and a "29px sidebar row" ended up as two
  * unrelated geometries for the same list. What is left here is only what the theme does not supply:
- * the touch-target `min-height` floor (`--vx-space-mobile-nav-row-height`, 40px — WCAG 2.5.5 AA).
+ * the touch-target `min-height` floor (`--vx-space-mobile-nav-row-height`, 44px — WCAG 2.5.5 AAA-enhanced).
  */
 .row {
   display: flex;
@@ -403,3 +403,15 @@
     transition: none;
   }
 }
+
+/* Landscape phone: the bar's compact row (`app-main.module.css` sets its height) is icons only —
+ * the label is visually hidden, not removed, so each tab keeps its accessible name. */
+@media (max-height: 480px) and (orientation: landscape) {
+  .label {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+  }
+}

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

@@ -30,10 +30,8 @@
  * notch on the side the sidebar touches. `max()` is a FLOOR — the inset only grows the padding
  * past its normal value, never shrinks it. Right inset is `app-main.module.css`'s to draw; the
  * PWA's top inset needs no rule here (the status bar uses the opaque `default` style). */
-@media (display-mode: standalone) {
-  .root {
-    padding-left: max(var(--vx-space-row-inset-x), env(safe-area-inset-left));
-  }
+:global(:root[data-basalt-host]:not([data-basalt-host='web'])) .root {
+  padding-left: max(var(--vx-space-row-inset-x), env(safe-area-inset-left));
 }
 
 .link {
@@ -634,12 +632,12 @@
 }
 
 /*
- * Icon-rail (collapsed) — desktop only. Gated behind min-width: sm (48em) so the sidebar doesn't
+ * Icon-rail (collapsed) — desktop only. Gated behind min-width: sm (52.5em) so the sidebar doesn't
  * exist at all below that breakpoint (see `MobileNav`) regardless of the persisted collapse flag.
  * Hide the section labels and nav labels; center the remaining icons. The brand's own rail form
  * lives in `app-brand.module.css` now, keyed off the same `data-collapsed` attribute.
  */
-@media (min-width: 48em) {
+@media (min-width: 52.5em) {
   .root[data-collapsed] .searchSlot {
     padding-block: var(--vx-space-sidebar-region-gap);
     display: flex;

package/src/shell/aside-docking.ts

@@ -0,0 +1,54 @@
+/**
+ * Aside docking (`docs/DESIGN-CORE.md` § Layout, elevation, shapes) — the pure decision `ShellFrame`
+ * sizes `AppShell.Aside` from. An open aside pushes main only in `expanded` while main keeps
+ * `MAIN_MIN_WIDTH` beside the navbar; otherwise the region reserves just its rail and an open panel
+ * overlays main. Unclaimed, the region is zero-wide.
+ */
+import { toEm } from '../tokens/size-classes'
+import type { SizeClass } from './use-size-class'
+
+/**
+ * Main keeps at least this much width, or an open aside overlays it instead of docking. Not
+ * derived from a token: it is the readable floor for a page body, independent of density.
+ */
+const MAIN_MIN_WIDTH = 720
+
+export type AsideDockingInput = {
+  claimed: boolean
+  folded: boolean
+  sizeClass: SizeClass
+  /** The `asideDockQuery` media query's result. */
+  roomToDock: boolean
+  asideWidth: number
+  asideRailWidth: number
+}
+
+export type AsideDocking = {
+  /** An open aside pushes main rather than overlaying it. */
+  docks: boolean
+  /** An open aside renders over main (reserving only its rail). */
+  overlay: boolean
+  /** The width `AppShell` reserves for the region. */
+  width: number
+}
+
+/** The `min-width` query that holds while navbar + open aside + `MAIN_MIN_WIDTH` fit side by side. */
+export function asideDockQuery(input: { navbarWidth: number; asideWidth: number }): string {
+  return `(min-width: ${toEm(input.navbarWidth + input.asideWidth + MAIN_MIN_WIDTH)})`
+}
+
+/**
+ * The room-to-dock query's SSR/no-`matchMedia` fallback — an `'expanded'` `sizeClassHint` means the
+ * server already believes there is room, matching `useSizeClass`'s own hint-seeded guard
+ * (`use-size-class.ts`), so the first client paint doesn't fold a default-open aside for one commit.
+ */
+export function roomToDockServerFallback(sizeClassHint: SizeClass | undefined): boolean {
+  return sizeClassHint === 'expanded'
+}
+
+export function resolveAsideDocking(input: AsideDockingInput): AsideDocking {
+  const docks = input.sizeClass === 'expanded' && input.roomToDock
+  const open = input.claimed && !input.folded
+  const reserved = open && docks ? input.asideWidth : input.asideRailWidth
+  return { docks, overlay: open && !docks, width: input.claimed ? reserved : 0 }
+}

package/src/shell/index.tsx

@@ -15,14 +15,17 @@
  * `item.onClick`, `item.badge`/`item.count` and supplies `item.Anchor` — its router `<Link>`,
  * which basalt HOSTS rather than delegating rendering to. The breadcrumb is derived from the
  * active item across `sections`, not from a router hook. Collapse is persisted via basalt's own
- * `createPersistedState` (`../state`) keyed by `storageKey` — see `collapseStore`.
+ * `createPersistedStore` (`../state/persisted`, `createPersistedState` plus an `isSet` flag) keyed
+ * by `storageKey` — see `collapseStore`. While nothing is persisted the size class picks the
+ * default (rail in `medium`); any stored value, `false` included, wins.
  */
-import { AppShell, Box } from '@mantine/core'
-import { Fragment, useCallback, useEffect, useMemo } from 'react'
-import type { MouseEvent, ReactNode } from 'react'
+import { AppShell, Box, rem } from '@mantine/core'
+import { Fragment, useCallback, useContext, useEffect, useMemo } from 'react'
+import type { CSSProperties, MouseEvent, ReactNode } from 'react'
 import { registerSidebarToggle } from '../commands/shell-bridge'
 import { cx } from '../common/props'
 import type { BasaltProps } from '../common/props'
+import { useMediaQuery } from '../common/use-media-query'
 import { assertRequiredProps } from '../common/validate'
 import { AppSidebar } from './app-sidebar'
 import { AppBrand } from './app-brand'
@@ -30,7 +33,8 @@ import { MobileNav, accountRowCount } from './app-mobile-nav'
 import { blockRowCount, projectMobileNav } from './mobile-nav-model'
 import { AppBreadcrumbs } from './app-breadcrumbs'
 import { PageBarBandOutlet, PageBarOutlet, PageBarProvider, usePageKebabClaimed } from './page-bar'
-import { AsideOutlet, AsideProvider, useAsideRegion } from './page-aside'
+import { AsideDocksContext, AsideOutlet, AsideProvider, useAsideRegion } from './page-aside'
+import { asideDockQuery, resolveAsideDocking, roomToDockServerFallback } from './aside-docking'
 import { OverflowMenu, globalActionAsBarAction, globalActionMobile } from '../controls/actions'
 import type { GlobalAction } from '../controls/actions'
 import type { AccountMenuItem, BasaltAccountProps } from './account-types'
@@ -43,7 +47,8 @@ import type {
   SidebarSection,
 } from './nav-types'
 import { CtlSlot, useBasaltSpacing } from '../theme'
-import { createPersistedState } from '../state'
+import { createPersistedStore } from '../state/persisted'
+import { SizeClassHintContext, useSizeClass } from './use-size-class'
 import brandClasses from './app-brand.module.css'
 import headerClasses from './app-header.module.css'
 import mainClasses from './app-main.module.css'
@@ -80,6 +85,7 @@ export { AppBreadcrumbs, type AppBreadcrumbsProps } from './app-breadcrumbs'
 export { PageBar, type PageBarProps, type PageBarSlot } from './page-bar'
 export { PageAside, type PageAsideProps, type PageAsideSlot } from './page-aside'
 export { useBreakpoint, type BreakpointName } from './use-breakpoint'
+export { useSizeClass, type SizeClass } from './use-size-class'
 export { PageTitle, type PageTitleProps, type PageTitleSlot } from './page-title'
 
 /**
@@ -268,7 +274,9 @@ function findActiveWithParent(
 const COLLAPSE_VERSION = 1
 
 /**
- * One `createPersistedState` store per `storageKey`, memoized at module scope.
+ * One `createPersistedStore` store per `storageKey`, memoized at module scope. Its third tuple
+ * element, `isSet`, is what lets an unset key take the size-class default while an explicit
+ * write of `false` still pins the navbar open.
  *
  * Through 1.20.0 the shell persisted collapse with `@mantine/hooks`' `useLocalStorage` while
  * `createPersistedState` was the documented house API — and this component's own docstring told
@@ -276,17 +284,20 @@ const COLLAPSE_VERSION = 1
  * `localStorage` call was COMPLIANCE with the shipped component rather than drift. A framework
  * cannot ship a persistence rule its own shell breaks; this is the shell coming into line.
  *
- * The memo is required, not an optimization: `createPersistedState` is a per-key module FACTORY and
+ * The memo is required, not an optimization: `createPersistedStore` is a per-key module FACTORY and
  * `storageKey` is a runtime prop, so calling it during render would allocate a fresh store (and a
  * fresh `useSyncExternalStore` subscription) on every commit. Swapping keys mid-life stays safe —
- * every store's hook calls exactly one `useSyncExternalStore`, so the hook count never moves.
+ * every store's hook calls the same two `useSyncExternalStore`s (value, `isSet`), so the hook count
+ * never moves.
  */
-const collapseStores = new Map<string, () => readonly [boolean, (next: boolean) => void]>()
+type CollapseStore = () => readonly [boolean, (next: boolean) => void, boolean]
 
-function collapseStore(key: string): () => readonly [boolean, (next: boolean) => void] {
+const collapseStores = new Map<string, CollapseStore>()
+
+function collapseStore(key: string): CollapseStore {
   const cached = collapseStores.get(key)
   if (cached) return cached
-  const store = createPersistedState<boolean>({ key, version: COLLAPSE_VERSION, initial: false })
+  const store = createPersistedStore<boolean>({ key, version: COLLAPSE_VERSION, initial: false })
   collapseStores.set(key, store)
   return store
 }
@@ -355,11 +366,46 @@ function ShellFrame({
   // 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)()
+  const sizeClass = useSizeClass()
+  const [storedCollapsed, setStoredCollapsed, collapseIsSet] = collapseStore(storageKey)()
   // Controlled/uncontrolled seam (item 19): an explicit `collapsed` prop overrides the internal
-  // localStorage-persisted state entirely — the consumer becomes the source of truth.
+  // localStorage-persisted state entirely — the consumer becomes the source of truth. Otherwise the
+  // size class picks the default (rail in `medium`) ONLY while the user has never toggled; an
+  // explicit write — `false` included — always wins.
   const isCollapseControlled = collapsedProp !== undefined
-  const collapsed = isCollapseControlled ? collapsedProp : storedCollapsed
+  const uncontrolledCollapsed = collapseIsSet ? storedCollapsed : sizeClass === 'medium'
+  const collapsed = isCollapseControlled ? collapsedProp : uncontrolledCollapsed
+  // Aside docking (`aside-docking.ts`), provided through `AsideDocksContext` in the SAME render so
+  // `PageAside` defaults its fold from the right value on its first pass.
+  const navbarWidth = collapsed ? step.appShellNavbarRailWidth : step.appShellNavbarWidth
+  const sizeClassHint = useContext(SizeClassHintContext)
+  const roomToDock = useMediaQuery(
+    asideDockQuery({ navbarWidth, asideWidth: step.appShellAsideWidth }),
+    roomToDockServerFallback(sizeClassHint),
+  )
+  const docking = resolveAsideDocking({
+    claimed: aside.claimed,
+    folded: aside.folded,
+    sizeClass,
+    roomToDock,
+    asideWidth: step.appShellAsideWidth,
+    asideRailWidth: step.appShellAsideRailWidth,
+  })
+  const asideOverlay = docking.overlay
+  // Keyboard escape hatch for the overlay form only — the docked form never blocks content, so
+  // there is nothing to escape out of. `requestClose` is a stable callback from `AsideProvider`
+  // (destructured, not read as `aside.requestClose`, so the effect deps name it directly rather
+  // than the whole `aside` object — a fresh literal every render); `PageAside` folds itself in
+  // response (see its own `closeSignal` effect).
+  const { requestClose } = aside
+  useEffect(() => {
+    if (!asideOverlay) return
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (event.key === 'Escape') requestClose()
+    }
+    window.addEventListener('keydown', onKeyDown)
+    return () => window.removeEventListener('keydown', onKeyDown)
+  }, [asideOverlay, requestClose])
   const toggleCollapse = useCallback(() => {
     const next = !collapsed
     if (!isCollapseControlled) setStoredCollapsed(next)
@@ -392,126 +438,129 @@ function ShellFrame({
   )
 
   return (
-    <AppShell
-      h="100dvh"
-      // Mantine's DEFAULT layout, not `alt`: the header spans the full viewport width on top and
-      // the navbar/aside start underneath it at `top: var(--app-shell-header-offset)`. `alt` did
-      // the opposite — a full-height navbar with the header inset beside it — which put the top
-      // bar to the RIGHT of the sidebar instead of above it.
-      header={{
-        // ONE height at every width (law C14): nothing reserves a second mobile row any more.
-        height: step.appShellHeaderHeight,
-      }}
-      navbar={{
-        width: {
-          base: step.appShellNavbarWidth,
-          sm: collapsed ? step.appShellNavbarRailWidth : step.appShellNavbarWidth,
-        },
-        breakpoint: 'sm',
-        // No mobile sidebar drawer, ever — the bottom bar is the entire mobile nav.
-        collapsed: { mobile: true },
-      }}
-      // The aside region (`docs/ASIDE-SPEC.md` §0). It is DECLARED here on every route and costs
-      // nothing until a page mounts a `PageAside` to claim it: unclaimed it is zero-wide and
-      // `collapsed.desktop`, so `--app-shell-aside-offset` stays 0 and the main column is
-      // full-width (law C14 — an empty home renders nothing). There is no `BasaltShellProps`
-      // prop for it on purpose; the ROUTE decides, the same way it decides its page bar.
-      aside={{
-        width: aside.claimed
-          ? aside.folded
-            ? step.appShellAsideRailWidth
-            : step.appShellAsideWidth
-          : 0,
-        breakpoint: 'sm',
-        // Below `sm` there is no region at all — `PageAside` renders its content in the page
-        // flow instead, one node, no responsive twin (law C9).
-        collapsed: { desktop: !aside.claimed, mobile: true },
-      }}
-      // 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={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)}
-      {...(style !== undefined && { style })}
-    >
-      {/* 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={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
-           * content edge. The brand lives here rather than in the sidebar because with a full-width
-           * header a sidebar brand row painted as a SECOND 48px band under the header seam; see
-           * `app-brand.tsx`. `data-collapsed` is the rail's one signal — the zone narrows with the
-           * navbar and shows the toggle alone, exactly as the sidebar's own row did. */}
-          <div className={brandClasses.zone} data-collapsed={collapsed || undefined}>
-            <AppBrand brand={brand} collapsed={collapsed} onToggleCollapse={toggleCollapse} />
-          </div>
-          <div className={headerClasses.lead}>
-            <AppBreadcrumbs {...activeCrumb} />
+    <AsideDocksContext.Provider value={docking.docks}>
+      <AppShell
+        h="100dvh"
+        // Mantine's DEFAULT layout, not `alt`: the header spans the full viewport width on top and
+        // the navbar/aside start underneath it at `top: var(--app-shell-header-offset)`. `alt` did
+        // the opposite — a full-height navbar with the header inset beside it — which put the top
+        // bar to the RIGHT of the sidebar instead of above it.
+        header={{
+          // ONE height at every width (law C14): nothing reserves a second mobile row any more.
+          height: step.appShellHeaderHeight,
+        }}
+        navbar={{
+          width: { base: step.appShellNavbarWidth, sm: navbarWidth },
+          breakpoint: 'sm',
+          // No mobile sidebar drawer, ever — the bottom bar is the entire mobile nav.
+          collapsed: { mobile: true },
+        }}
+        // The aside region (`docs/ASIDE-SPEC.md` §0). It is DECLARED here on every route and costs
+        // nothing until a page mounts a `PageAside` to claim it: unclaimed it is zero-wide and
+        // `collapsed.desktop`, so `--app-shell-aside-offset` stays 0 and the main column is
+        // full-width (law C14 — an empty home renders nothing). There is no `BasaltShellProps`
+        // prop for it on purpose; the ROUTE decides, the same way it decides its page bar.
+        aside={{
+          // An overlay reserves the rail only — `<AppShell.Aside>` below widens itself over main.
+          width: docking.width,
+          breakpoint: 'sm',
+          // Below `sm` there is no region at all — `PageAside` renders its content in the page
+          // flow instead, one node, no responsive twin (law C9).
+          collapsed: { desktop: !aside.claimed, mobile: true },
+        }}
+        // 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={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)}
+        {...(style !== undefined && { style })}
+      >
+        {/* 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={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
+             * content edge. The brand lives here rather than in the sidebar because with a full-width
+             * header a sidebar brand row painted as a SECOND 48px band under the header seam; see
+             * `app-brand.tsx`. `data-collapsed` is the rail's one signal — the zone narrows with the
+             * navbar and shows the toggle alone, exactly as the sidebar's own row did. */}
+            <div className={brandClasses.zone} data-collapsed={collapsed || undefined}>
+              <AppBrand brand={brand} collapsed={collapsed} onToggleCollapse={toggleCollapse} />
+            </div>
+            <div className={headerClasses.lead}>
+              <AppBreadcrumbs {...activeCrumb} />
+            </div>
+            <PageBarOutlet className={headerClasses.pageBar} />
+            <HeaderGlobalActions actions={globalActions ?? []} />
           </div>
-          <PageBarOutlet className={headerClasses.pageBar} />
-          <HeaderGlobalActions actions={globalActions ?? []} />
-        </div>
-      </AppShell.Header>
+        </AppShell.Header>
 
-      <AppShell.Navbar p={0}>
-        <AppSidebar
-          brand={brand}
-          sections={sections}
-          collapsed={collapsed}
-          onToggleCollapse={toggleCollapse}
-          {...(sidebarBlocks !== undefined && { blocks: sidebarBlocks })}
-          {...(settingsMenuItems !== undefined && { settingsMenuItems })}
-          {...(settingsMenu !== undefined && { settingsMenu })}
-          {...(account !== undefined && { account })}
-          {...(search !== undefined && { search })}
-        />
-      </AppShell.Navbar>
+        <AppShell.Navbar p={0}>
+          <AppSidebar
+            brand={brand}
+            sections={sections}
+            collapsed={collapsed}
+            onToggleCollapse={toggleCollapse}
+            {...(sidebarBlocks !== undefined && { blocks: sidebarBlocks })}
+            {...(settingsMenuItems !== undefined && { settingsMenuItems })}
+            {...(settingsMenu !== undefined && { settingsMenu })}
+            {...(account !== undefined && { account })}
+            {...(search !== undefined && { search })}
+          />
+        </AppShell.Navbar>
 
-      {/* The PAGE-BAR BAND — a shell-owned outlet between the header and the scrollport that
-       * `PageBar` row 2 portals into, the same mechanism row 1 uses one region up. It is written
-       * BEFORE Main because the two are the AppShell root's only in-flow children (every other
-       * region is `position: fixed`), so DOM order is column order: band, then whatever height is
-       * left. Empty, it is a zero-height, seam-less box (law C14). */}
-      <PageBarBandOutlet className={mainClasses.band} />
+        {/* The PAGE-BAR BAND — a shell-owned outlet between the header and the scrollport that
+         * `PageBar` row 2 portals into, the same mechanism row 1 uses one region up. It is written
+         * BEFORE Main because the two are the AppShell root's only in-flow children (every other
+         * region is `position: fixed`), so DOM order is column order: band, then whatever height is
+         * left. Empty, it is a zero-height, seam-less box (law C14). */}
+        <PageBarBandOutlet className={mainClasses.band} />
 
-      {/* MAIN IS THE SCROLLPORT (`app-main.module.css`), not the document: the scrollbar belongs
-       * on the content's own right edge, inside the aside, and every sticky offset in the package
-       * resolves against this box rather than the window. `data-basalt-scrollport` is the public
-       * handle — `scrollParentOf` (`../common`) and `MobileNav`'s scroll-to-top both resolve it —
-       * and `data-scroll-restoration-id` is the attribute TanStack Router's scroll restoration
-       * reads (`@tanstack/router-core`'s `scrollRestorationIdAttribute`), so a router-driven app
-       * restores THIS element's scrollTop instead of the window's, which no longer moves. */}
-      <AppShell.Main
-        className={mainClasses.main}
-        data-basalt-scrollport
-        data-scroll-restoration-id="basalt-main"
-      >
-        {children}
-      </AppShell.Main>
+        {/* MAIN IS THE SCROLLPORT (`app-main.module.css`), not the document: the scrollbar belongs
+         * on the content's own right edge, inside the aside, and every sticky offset in the package
+         * resolves against this box rather than the window. `data-basalt-scrollport` is the public
+         * handle — `scrollParentOf` (`../common`) and `MobileNav`'s scroll-to-top both resolve it —
+         * and `data-scroll-restoration-id` is the attribute TanStack Router's scroll restoration
+         * reads (`@tanstack/router-core`'s `scrollRestorationIdAttribute`), so a router-driven app
+         * restores THIS element's scrollTop instead of the window's, which no longer moves. */}
+        <AppShell.Main
+          className={mainClasses.main}
+          data-basalt-scrollport
+          data-scroll-restoration-id="basalt-main"
+        >
+          {children}
+        </AppShell.Main>
 
-      {/* The outlet is bare; the region's leading seam is the AppShell's own. An unclaimed region
-       * is zero-wide but NOT display-none — Mantine's collapsed aside keeps its border-box, so a
-       * seam would still paint as a 1px ghost at the viewport's right edge (measured on
-       * `/dashboard`). The border follows the claim, not the section (C14). */}
-      <AppShell.Aside p={0} withBorder={aside.claimed}>
-        <AsideOutlet className={asideClasses.outlet} />
-      </AppShell.Aside>
+        {/* The outlet is bare; the region's leading seam is the AppShell's own. An unclaimed region
+         * is zero-wide but NOT display-none — Mantine's collapsed aside keeps its border-box, so a
+         * seam would still paint as a 1px ghost at the viewport's right edge (measured on
+         * `/dashboard`). The border follows the claim, not the section (C14). */}
+        <AppShell.Aside
+          p={0}
+          withBorder={aside.claimed}
+          {...(asideOverlay && {
+            className: mainClasses.asideOverlay,
+            style: { '--app-shell-aside-width': rem(step.appShellAsideWidth) } as CSSProperties,
+          })}
+        >
+          <AsideOutlet className={asideClasses.outlet} />
+        </AppShell.Aside>
 
-      <AppShell.Footer hiddenFrom="sm" p={0}>
-        <MobileNav
-          model={model}
-          config={mobileNav}
-          {...(account !== undefined && { account })}
-          {...(settingsMenuItems !== undefined && { settingsMenuItems })}
-          {...(sidebarBlocks !== undefined && { blocks: sidebarBlocks })}
-        />
-      </AppShell.Footer>
-    </AppShell>
+        <AppShell.Footer hiddenFrom="sm" p={0}>
+          <MobileNav
+            model={model}
+            config={mobileNav}
+            {...(account !== undefined && { account })}
+            {...(settingsMenuItems !== undefined && { settingsMenuItems })}
+            {...(sidebarBlocks !== undefined && { blocks: sidebarBlocks })}
+          />
+        </AppShell.Footer>
+      </AppShell>
+    </AsideDocksContext.Provider>
   )
 }
 

package/src/shell/mobile-nav-model.ts

@@ -19,7 +19,7 @@
  * padding), so the 560px cap uses 73% of it; on the smallest supported viewport (320x568) the
  * headroom is ~496px and 72dvh is 409px — the cap is binding on every supported phone, and the row
  * count never is. The old arithmetic here ("6 x 44px + 8px padding against 415px of headroom") was
- * stale in almost every number: rows are 40px (`--vx-space-mobile-nav-row-height`), the dropdown's
+ * stale in almost every number: rows are 44px (`--vx-space-mobile-nav-row-height`), the dropdown's
  * own padding is `2 * --vx-space-stack-xs` = 8px, and the headroom figures above are the measured
  * ones.
  *