basalt-ui 1.27.0 → 1.29.0

package/src/shell/app-sidebar.tsx

@@ -18,7 +18,6 @@
  * favor of this package.
  */
 import {
-  ActionIcon,
   Box,
   Collapse,
   Group,
@@ -34,8 +33,11 @@ import {
 import { useDisclosure } from '@mantine/hooks'
 import { useEffect, useRef } from 'react'
 import type { ReactNode } from 'react'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
 import type { BrandConfig, SettingsMenuItem } from './index'
-import type { SidebarBlock, SidebarItem, SidebarSection } from '../nav/types'
+import type { SidebarBlock, SidebarItem, SidebarSection } from './nav-types'
 import { NavCountBadge } from './nav-count-badge'
 import { SidebarAccount } from './app-sidebar-account'
 import type { AccountMenuItem, BasaltAccountProps } from './account-types'
@@ -56,15 +58,20 @@ import { VX } from '../tokens'
 import { useBasaltSpacing } from '../theme'
 import classes from './app-sidebar.module.css'
 
-export type AppSidebarProps = {
+export type AppSidebarProps = BasaltProps & {
   /**
-   * Brand identity. Supplying `menu` turns the brand row into a `Name ▾` workspace switcher —
+   * Brand identity. Supplying `menu` turns the header's brand into a `Name ▾` workspace switcher —
    * the entries are the existing `AccountMenuItem` shape, so a consumer already mapping account
    * actions needs no second vocabulary.
    */
   brand: BrandConfig & { menu?: AccountMenuItem[] }
   sections: SidebarSection[]
   collapsed: boolean
+  /**
+   * Consumed by the HEADER's brand zone (`app-brand.tsx`), not by this component — the collapse
+   * toggle moved up there with the brand. Still declared here because it is part of the sidebar's
+   * collapse contract and `BasaltShell` feeds both halves from one place.
+   */
   onToggleCollapse: () => void
   /**
    * Footer settings-menu entries (theme switcher, devtools, …) — supplied by the consumer.
@@ -123,8 +130,7 @@ export type AppSidebarProps = {
   blocks?: SidebarBlock[]
 }
 
-/** Inline collapse/expand chevrons — keeps the shell icon-dependency-free. */
-function IconCollapse({ collapsed }: { collapsed: boolean }) {
+function IconGear() {
   return (
     <svg
       width={18}
@@ -137,28 +143,29 @@ function IconCollapse({ collapsed }: { collapsed: boolean }) {
       strokeLinejoin="round"
       aria-hidden
     >
-      <path d="M4 4h16v16H4z" />
-      <path d="M9 4v16" />
-      {collapsed ? <path d="M14 9l3 3l-3 3" /> : <path d="M16 9l-3 3l3 3" />}
+      <path d="M10.325 4.317c.426 -1.756 2.924 -1.756 3.35 0a1.724 1.724 0 0 0 2.573 1.066c1.543 -.94 3.31 .826 2.37 2.37a1.724 1.724 0 0 0 1.065 2.572c1.756 .426 1.756 2.924 0 3.35a1.724 1.724 0 0 0 -1.066 2.573c.94 1.543 -.826 3.31 -2.37 2.37a1.724 1.724 0 0 0 -2.572 1.065c-.426 1.756 -2.924 1.756 -3.35 0a1.724 1.724 0 0 0 -2.573 -1.066c-1.543 .94 -3.31 -.826 -2.37 -2.37a1.724 1.724 0 0 0 -1.065 -2.572c-1.756 -.426 -1.756 -2.924 0 -3.35a1.724 1.724 0 0 0 1.066 -2.573c-.94 -1.543 .826 -3.31 2.37 -2.37c1 .608 2.296 .07 2.572 -1.065z" />
+      <path d="M9 12a3 3 0 1 0 6 0a3 3 0 0 0 -6 0" />
     </svg>
   )
 }
 
-function IconGear() {
+/** The `SettingsMenuItem.active` glyph — no icon package, so a plain inline mark like `IconGear`
+ * above. Shared shape with `app-mobile-nav.tsx`'s own copy (that module's More sheet is a
+ * different render tree and basalt ships no icon dependency to import between them). */
+function IconCheck() {
   return (
     <svg
-      width={18}
-      height={18}
+      width={14}
+      height={14}
       viewBox="0 0 24 24"
       fill="none"
       stroke="currentColor"
-      strokeWidth={2}
+      strokeWidth={2.5}
       strokeLinecap="round"
       strokeLinejoin="round"
       aria-hidden
     >
-      <path d="M10.325 4.317c.426 -1.756 2.924 -1.756 3.35 0a1.724 1.724 0 0 0 2.573 1.066c1.543 -.94 3.31 .826 2.37 2.37a1.724 1.724 0 0 0 1.065 2.572c1.756 .426 1.756 2.924 0 3.35a1.724 1.724 0 0 0 -1.066 2.573c.94 1.543 -.826 3.31 -2.37 2.37a1.724 1.724 0 0 0 -2.572 1.065c-.426 1.756 -2.924 1.756 -3.35 0a1.724 1.724 0 0 0 -2.573 -1.066c-1.543 .94 -3.31 -.826 -2.37 -2.37a1.724 1.724 0 0 0 -1.065 -2.572c-1.756 -.426 -1.756 -2.924 0 -3.35a1.724 1.724 0 0 0 1.066 -2.573c-.94 -1.543 .826 -3.31 2.37 -2.37c1 .608 2.296 .07 2.572 -1.065z" />
-      <path d="M9 12a3 3 0 1 0 6 0a3 3 0 0 0 -6 0" />
+      <path d="M5 12l5 5l10 -10" />
     </svg>
   )
 }
@@ -169,54 +176,6 @@ const HOVER_CLOSE_DELAY = 200
 /** `settingsMenuItems` at or under this count render as flat rows — see the prop's JSDoc. */
 const FLAT_SETTINGS_MAX = 3
 
-/**
- * The brand name, and — when `brand.menu` is supplied — the workspace switcher it becomes.
- *
- * The entries are `AccountMenuItem`s: the shell already had exactly this row shape (label, icon,
- * onClick, danger) for the account menu, and a second vocabulary for the same dropdown would be
- * two things to keep in step for no gain. The chevron is inline text, not an icon dependency.
- */
-function BrandName({
-  brand,
-  menuWidth,
-}: {
-  brand: BrandConfig & { menu?: AccountMenuItem[] }
-  menuWidth: number
-}) {
-  const label = (
-    <Text className={classes.brandName} fz={VX.text.xl} fw={550}>
-      {brand.name}
-    </Text>
-  )
-  const menu = brand.menu
-  if (menu === undefined || menu.length === 0) return label
-
-  return (
-    <Menu position="bottom-start" withArrow width={menuWidth} zIndex={500}>
-      <Menu.Target>
-        <UnstyledButton className={classes.brandButton} aria-label={`${brand.name} workspace`}>
-          {label}
-          {/* `open` is the DOWN glyph — a switcher's affordance points at its dropdown, and this is
-              the same chevron every fold in the sidebar uses rather than a second one. */}
-          <IconChevron open />
-        </UnstyledButton>
-      </Menu.Target>
-      <Menu.Dropdown>
-        {menu.map((entry) => (
-          <Menu.Item
-            key={entry.key}
-            leftSection={entry.icon}
-            {...(entry.danger === true && { color: 'red' })}
-            onClick={entry.onClick}
-          >
-            {entry.label}
-          </Menu.Item>
-        ))}
-      </Menu.Dropdown>
-    </Menu>
-  )
-}
-
 /** True when the item or any descendant is active — drives inline child expansion. */
 function hasActiveDescendant(item: SidebarItem): boolean {
   if (item.active) return true
@@ -469,17 +428,24 @@ function NavItemRow({ item, collapsed }: { item: SidebarItem; collapsed: boolean
   )
 }
 
-export function AppSidebar({
-  brand,
-  sections,
-  collapsed,
-  onToggleCollapse,
-  settingsMenuItems,
-  settingsMenu = 'auto',
-  account,
-  search,
-  blocks,
-}: AppSidebarProps) {
+export function AppSidebar(props: AppSidebarProps) {
+  assertRequiredProps('AppSidebar', props, ['brand'])
+  const {
+    brand,
+    sections,
+    collapsed,
+    // `onToggleCollapse` is deliberately NOT read here any more — the toggle it drives moved into
+    // the header's leading zone with the brand (`app-brand.tsx`). The prop stays on
+    // `AppSidebarProps` because it is the shell's public seam for a consumer-owned collapse, and
+    // dropping it would break every call site for no gain.
+    settingsMenuItems,
+    settingsMenu = 'auto',
+    account,
+    search,
+    blocks,
+    className,
+    style,
+  } = props
   // Density-tracking Menu dropdown width (`SPACE_STEP.sidebarSettingsMenuWidth`) — read the ACTIVE
   // resolved level, not the frozen level-0 constant (see that constant's own doc in
   // `tokens/palette.ts`).
@@ -520,6 +486,7 @@ export function AppSidebar({
             className={classes.footerBtn}
             onClick={entry.onClick}
             aria-label={entry.label}
+            aria-current={entry.active ? 'true' : undefined}
           >
             {/* A FIXED slot, so rows align on one icon column whether or not each ships an icon —
                 and the gear fallback is functional, not decorative: in the collapsed rail the label
@@ -532,6 +499,7 @@ export function AppSidebar({
             </Text>
             {/* The rail ring rides the FIRST row only — one progress block is one mark. */}
             {index === 0 ? ringMark : null}
+            {entry.active ? <IconCheck /> : null}
           </UnstyledButton>
         ))}
         {versionLabel !== undefined && (
@@ -554,7 +522,13 @@ export function AppSidebar({
           </Menu.Target>
           <Menu.Dropdown>
             {settingsItems.map((entry) => (
-              <Menu.Item key={entry.key} leftSection={entry.icon} onClick={entry.onClick}>
+              <Menu.Item
+                key={entry.key}
+                leftSection={entry.icon}
+                rightSection={entry.active ? <IconCheck /> : undefined}
+                onClick={entry.onClick}
+                aria-current={entry.active ? 'true' : undefined}
+              >
                 {entry.label}
               </Menu.Item>
             ))}
@@ -570,36 +544,18 @@ export function AppSidebar({
     )
 
   return (
-    <Stack gap={0} h="100%" className={classes.root} data-collapsed={collapsed || undefined}>
-      <Group className={classes.brand} gap="sm" wrap="nowrap">
-        <Group className={classes.brandLead} gap="sm" wrap="nowrap">
-          {brand.logoSrc && (
-            <img
-              src={brand.logoSrc}
-              alt={brand.logoAlt ?? brand.name}
-              width={26}
-              height={26}
-              style={{ display: 'block' }}
-            />
-          )}
-          <BrandName brand={brand} menuWidth={step.sidebarAccountMenuWidth} />
-        </Group>
-        <ActionIcon
-          variant="subtle"
-          // A numeric size, not the named `"md"` — same opt-out as `connectivity-indicator.tsx`'s
-          // toolbar icon (see that comment): this is a plain collapse-toggle icon, not a control meant
-          // to match a `size="md"` Input/Button, so it must not pick up the theme's `ActionIcon.extend`
-          // control-height override. Reproduces Mantine's own static `--ai-size-md` (28px).
-          size={28}
-          visibleFrom="sm"
-          className={classes.ghostIcon}
-          onClick={onToggleCollapse}
-          aria-label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
-        >
-          <IconCollapse collapsed={collapsed} />
-        </ActionIcon>
-      </Group>
-
+    <Stack
+      gap={0}
+      h="100%"
+      className={cx(classes.root, className)}
+      data-collapsed={collapsed || undefined}
+      {...(style !== undefined && { style })}
+    >
+      {/* NO brand row. It moved into the header's leading zone (`app-brand.tsx`) when the shell
+          dropped `layout="alt"`: with a full-width header, an `appShellHeaderHeight` brand band
+          here painted as a second 48px row under the header seam. The column now starts with
+          `SidebarSearch` — at the same inset it always had. `brand` stays a prop because
+          `brand.version` labels the settings footer below. */}
       {search && (
         <div className={classes.searchSlot}>
           <SidebarSearch {...search} collapsed={collapsed} />

package/src/shell/index.tsx

@@ -18,13 +18,19 @@
  * `createPersistedState` (`../state`) keyed by `storageKey` — see `collapseStore`.
  */
 import { AppShell, Box } from '@mantine/core'
-import { Fragment, useMemo } from 'react'
+import { Fragment, useCallback, useEffect, useMemo } from 'react'
 import type { MouseEvent, ReactNode } from 'react'
+import { registerSidebarToggle } from '../commands/shell-bridge'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
 import { AppSidebar } from './app-sidebar'
+import { AppBrand } from './app-brand'
 import { MobileNav, accountRowCount } from './app-mobile-nav'
 import { blockRowCount, projectMobileNav } from './mobile-nav-model'
 import { AppBreadcrumbs } from './app-breadcrumbs'
-import { PageBarOutlet, PageBarProvider, usePageKebabClaimed } from './page-bar'
+import { PageBarBandOutlet, PageBarOutlet, PageBarProvider, usePageKebabClaimed } from './page-bar'
+import { AsideOutlet, AsideProvider, useAsideRegion } from './page-aside'
 import { OverflowMenu, globalActionAsBarAction, globalActionMobile } from '../controls/actions'
 import type { GlobalAction } from '../controls/actions'
 import type { AccountMenuItem, BasaltAccountProps } from './account-types'
@@ -35,16 +41,19 @@ import type {
   SidebarBlock,
   SidebarItem,
   SidebarSection,
-} from '../nav/types'
+} from './nav-types'
 import { CtlSlot, useBasaltSpacing } from '../theme'
 import { createPersistedState } from '../state'
+import brandClasses from './app-brand.module.css'
 import headerClasses from './app-header.module.css'
-import mobileNavClasses from './app-mobile-nav.module.css'
+import mainClasses from './app-main.module.css'
+import asideClasses from './page-aside.module.css'
 
 export { AppSidebar, type AppSidebarProps } from './app-sidebar'
-export { NavCountBadge } from './nav-count-badge'
+export { NavCountBadge, type NavCountBadgeProps } from './nav-count-badge'
 export {
   SidebarSearch,
+  type SidebarSearchProps,
   type SidebarSearchConfig,
   type SidebarSearchActions,
 } from './sidebar-search'
@@ -67,12 +76,15 @@ export {
   MOBILE_MENU_MAX_DEFAULT,
   MOBILE_MORE_KEY,
 } from './mobile-nav-model'
-export { AppBreadcrumbs } from './app-breadcrumbs'
-export { PageBar, type PageBarProps } from './page-bar'
+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 { PageTitle, type PageTitleProps, type PageTitleSlot } from './page-title'
 
 /**
- * The shared nav vocabulary lives in `src/nav/types.ts` so the headless router bridge can `import
- * type` it without reaching into the Mantine layer. Re-exported here so `SidebarItem` /
+ * The shared nav vocabulary lives in `src/shell/nav-types.ts` so the headless router bridge can
+ * `import type` it without reaching into the Mantine layer. Re-exported here so `SidebarItem` /
  * `SidebarSection` keep resolving straight from `basalt-ui`, exactly as before.
  */
 export type {
@@ -93,7 +105,7 @@ export type {
   MobileNavModel,
   MobileNavSlot,
   MobileNavSurface,
-} from '../nav/types'
+} from './nav-types'
 
 /** Brand identity shown in the sidebar header (logo + name). */
 export type BrandConfig = {
@@ -113,9 +125,13 @@ export type SettingsMenuItem = {
   label: string
   icon?: ReactNode
   onClick?: (e: MouseEvent) => void
+  /** This entry is the current selection (e.g. the active theme radio, the open dev tool) — a
+   * trailing check glyph renders in every form (flat footer row, gear `Menu.Item`, the mobile
+   * More-sheet row) and the row carries `aria-current="true"`. */
+  active?: boolean
 }
 
-export type BasaltShellProps = {
+export type BasaltShellProps = BasaltProps & {
   /**
    * Brand identity for the sidebar header. Supplying `menu` turns the brand row into a `Name ▾`
    * workspace switcher — the rows are `AccountMenuItem`s, the shape the account menu already uses.
@@ -267,36 +283,36 @@ const COLLAPSE_VERSION = 1
  */
 const collapseStores = new Map<string, () => readonly [boolean, (next: boolean) => void]>()
 
-/**
- * Seeds `basalt:<key>` from the raw pre-1.20.1 key once, so the switch doesn't silently re-expand
- * every consumer's sidebar. Mantine's `useLocalStorage` wrote a bare `JSON.stringify(value)` at the
- * un-namespaced key; only `'true'`/`'false'` are accepted, and only when the house key is empty.
- * A one-upgrade bridge, not a supported format — delete it once no consumer predates 1.20.1.
- */
-function migrateLegacyCollapse(key: string): void {
-  try {
-    if (window.localStorage.getItem(`basalt:${key}`) !== null) return
-    const legacy = window.localStorage.getItem(key)
-    if (legacy !== 'true' && legacy !== 'false') return
-    window.localStorage.setItem(
-      `basalt:${key}`,
-      JSON.stringify({ v: COLLAPSE_VERSION, value: legacy === 'true' }),
-    )
-  } catch {
-    // Storage blocked (private browsing, quota) — defaulting to expanded is a fine outcome.
-  }
-}
-
 function collapseStore(key: string): () => readonly [boolean, (next: boolean) => void] {
   const cached = collapseStores.get(key)
   if (cached) return cached
-  if (typeof window !== 'undefined') migrateLegacyCollapse(key)
   const store = createPersistedState<boolean>({ key, version: COLLAPSE_VERSION, initial: false })
   collapseStores.set(key, store)
   return store
 }
 
-export function BasaltShell({
+// 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`
+ * owns the aside portal, the region CLAIM and the claiming page's fold state — which `ShellFrame`
+ * has to READ to size `AppShell.Aside`, so it cannot be the component that provides it.
+ */
+export function BasaltShell(props: BasaltShellProps) {
+  assertRequiredProps('BasaltShell', props, ['brand', 'sections'])
+  return (
+    <PageBarProvider globalActions={props.globalActions ?? []}>
+      <AsideProvider>
+        <ShellFrame {...props} />
+      </AsideProvider>
+    </PageBarProvider>
+  )
+}
+
+function ShellFrame({
   brand,
   sections,
   mobileNav,
@@ -310,22 +326,34 @@ export function BasaltShell({
   account,
   search,
   children,
+  className,
+  style,
 }: BasaltShellProps) {
   // The active density level's resolved spacing — the AppShell dimensions below must track it
   // (see `SPACE_STEP_BASE`'s "shell/index.tsx" group doc in `tokens/palette.ts`): their contents
   // (controls, the search trigger/avatar, nav labels) already track density, so a fixed literal
   // container squeezes progressively worse as density rises.
   const { step } = useBasaltSpacing()
+  const aside = useAsideRegion()
   const [storedCollapsed, setStoredCollapsed] = 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.
   const isCollapseControlled = collapsedProp !== undefined
   const collapsed = isCollapseControlled ? collapsedProp : storedCollapsed
-  const toggleCollapse = () => {
+  const toggleCollapse = useCallback(() => {
     const next = !collapsed
     if (!isCollapseControlled) setStoredCollapsed(next)
     onCollapsedChange?.(next)
-  }
+  }, [collapsed, isCollapseControlled, setStoredCollapsed, onCollapsedChange])
+  // `commands/shell-bridge.ts`'s `toggleSidebar` handle — registered here so a consumer's
+  // `commands.tsx` calls it with ZERO module-scope bridge of its own, unlike argo's hand-rolled
+  // `sidebar-bridge.ts` this seeds from (see that file's own doc). Re-registered whenever
+  // `toggleCollapse` itself changes identity, so the handle always flips the CURRENT state rather
+  // than a stale closure's.
+  useEffect(() => {
+    registerSidebarToggle(toggleCollapse)
+    return () => registerSidebarToggle(null)
+  }, [toggleCollapse])
 
   const activeCrumb = findActiveCrumb(sections)
   // The account row, every settings entry and every mobile-reachable sidebar block render as flat
@@ -344,68 +372,126 @@ export function BasaltShell({
   )
 
   return (
-    <PageBarProvider globalActions={globalActions ?? []}>
-      <AppShell
-        h="100dvh"
-        layout="alt"
-        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 },
-        }}
-        // 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="sm"
-      >
-        <AppShell.Header px="md" withBorder={false}>
-          <div className={headerClasses.bar}>
-            <div className={headerClasses.lead}>
-              <AppBreadcrumbs {...activeCrumb} />
-            </div>
-            <PageBarOutlet className={headerClasses.pageBar} />
-            <HeaderGlobalActions actions={globalActions ?? []} />
+    <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={SHELL_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={SHELL_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>
-        </AppShell.Header>
+          <div className={headerClasses.lead}>
+            <AppBreadcrumbs {...activeCrumb} />
+          </div>
+          <PageBarOutlet className={headerClasses.pageBar} />
+          <HeaderGlobalActions actions={globalActions ?? []} />
+        </div>
+      </AppShell.Header>
 
-        <AppShell.Navbar p={0} withBorder={false}>
-          <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>
 
-        {/* `mainSafeArea` closes the one real safe-area gap: Mantine sets
-         * `--app-shell-footer-offset` to the RAW footer height, so Main's own padding-bottom is
-         * short by exactly `env(safe-area-inset-bottom)` (§2.7). */}
-        <AppShell.Main className={mobileNavClasses.mainSafeArea}>{children}</AppShell.Main>
+      {/* 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} />
 
-        <AppShell.Footer hiddenFrom="sm" p={0} withBorder={false}>
-          <MobileNav
-            model={model}
-            config={mobileNav}
-            {...(account !== undefined && { account })}
-            {...(settingsMenuItems !== undefined && { settingsMenuItems })}
-            {...(sidebarBlocks !== undefined && { blocks: sidebarBlocks })}
-          />
-        </AppShell.Footer>
-      </AppShell>
-    </PageBarProvider>
+      {/* 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>
+
+      <AppShell.Footer hiddenFrom="sm" p={0}>
+        <MobileNav
+          model={model}
+          config={mobileNav}
+          {...(account !== undefined && { account })}
+          {...(settingsMenuItems !== undefined && { settingsMenuItems })}
+          {...(sidebarBlocks !== undefined && { blocks: sidebarBlocks })}
+        />
+      </AppShell.Footer>
+    </AppShell>
   )
 }
 

package/src/shell/isomorphic-layout-effect.ts

@@ -0,0 +1,14 @@
+/**
+ * Internal — `useLayoutEffect` in the browser, `useEffect` on the server.
+ *
+ * The standard isomorphic pattern, so an SSR render never trips React's "useLayoutEffect does
+ * nothing on the server" warning. The branch reads a global that cannot change between renders, so
+ * the hook identity is stable across every render of every caller.
+ *
+ * One module rather than one `const` per file: `page-bar.tsx` and `page-aside.tsx` declared the
+ * same line with the same doc, and the second copy's doc already said "see `page-bar.tsx`'s copy".
+ * Not exported from any barrel — this is a shell-internal utility, not a published hook.
+ */
+import { useEffect, useLayoutEffect } from 'react'
+
+export const useIsomorphicLayoutEffect = typeof window === 'undefined' ? useEffect : useLayoutEffect