basalt-ui 1.25.0 → 1.27.0

package/src/shell/index.test.tsx

@@ -7,22 +7,37 @@
 import { MantineProvider } from '@mantine/core'
 import { fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { describe, expect, test } from 'bun:test'
-import { BasaltShell } from './index'
-import type { BasaltAccountProps, SidebarSection } from './index'
+import { ActionGroup } from '../controls/actions'
+import { BasaltShell, PageBar } from './index'
+import type { BasaltAccountProps, SidebarBlock, SidebarSection } from './index'
 
 const BRAND = { name: 'Argo' }
 const ONE_SECTION: SidebarSection[] = [
   { label: 'Main', items: [{ key: 'home', label: 'Home', icon: null }] },
 ]
 
-describe('BasaltShell sidebarNavExtra', () => {
-  test("reaches AppSidebar's nav scroll region through the BasaltShell -> AppSidebar hand-off", () => {
+const AWAITING: SidebarBlock = {
+  kind: 'list',
+  key: 'awaiting',
+  label: 'Awaiting action',
+  count: 3,
+  items: [
+    { key: 'a', label: 'Review PR' },
+    { key: 'b', label: 'Sign contract' },
+    { key: 'c', label: 'Reply to Jo' },
+  ],
+}
+
+describe('BasaltShell sidebarBlocks', () => {
+  test("a 'custom' block reaches the sidebar's nav scroll region through the hand-off", () => {
     const { container } = render(
       <MantineProvider>
         <BasaltShell
           brand={BRAND}
           sections={ONE_SECTION}
-          sidebarNavExtra={<div data-testid="nav-extra">Extra</div>}
+          sidebarBlocks={[
+            { kind: 'custom', key: 'tree', node: <div data-testid="nav-extra">Extra</div> },
+          ]}
         />
       </MantineProvider>,
     )
@@ -31,6 +46,77 @@ describe('BasaltShell sidebarNavExtra', () => {
     expect(stack).not.toBeNull()
     expect(stack?.contains(extra)).toBe(true)
   })
+
+  /**
+   * Both halves of the SAME prop, which is the point of C13: one declaration renders the desktop
+   * block and produces the mobile row. `sidebarNavExtra` + `mobileNav.moreExtra` needed two.
+   */
+  test('the same block projects to ONE More row that opens a nested sheet of its items', async () => {
+    render(
+      <MantineProvider>
+        <BasaltShell brand={BRAND} sections={ONE_SECTION} sidebarBlocks={[AWAITING]} />
+      </MantineProvider>,
+    )
+
+    fireEvent.click(screen.getByLabelText('More'))
+    await waitFor(() => expect(document.querySelector('[role="menu"]')).not.toBeNull())
+    // One row, stating its own count — not three rows, one per item. `Home` took the bar slot, so
+    // the block row is the whole More surface here.
+    const row = screen.getByText('Awaiting action · 3')
+    expect(document.querySelectorAll('.mantine-Menu-item')).toHaveLength(1)
+
+    fireEvent.click(row)
+    await waitFor(() => expect(document.querySelector('.mantine-Drawer-content')).not.toBeNull())
+    // Scoped to the sheet: the desktop block renders the same three labels, and a bare `getByText`
+    // would match both copies rather than proving the sheet holds them.
+    const body = document.querySelector('.mantine-Drawer-body')?.textContent ?? ''
+    expect(body).toContain('Review PR')
+    expect(body).toContain('Reply to Jo')
+  })
+
+  test("mobile:'hidden' keeps the block off the More surface entirely", () => {
+    render(
+      <MantineProvider>
+        <BasaltShell
+          brand={BRAND}
+          sections={[
+            { label: 'Main', items: [{ key: 'home', label: 'Home', icon: null, mobile: 'tab' }] },
+          ]}
+          sidebarBlocks={[{ ...AWAITING, mobile: 'hidden' }]}
+        />
+      </MantineProvider>,
+    )
+    // Nothing else feeds More, so a hidden block must not conjure the slot at all.
+    expect(screen.queryByLabelText('More')).toBeNull()
+  })
+})
+
+/**
+ * Law C13's enforcement column is "tsc — `sidebarNavExtra` / `mobileNav.moreExtra` removed". These
+ * two `@ts-expect-error`s ARE that gate: they fail the build the day either prop comes back, which
+ * is the only way a type-level removal can be asserted from a test file.
+ */
+describe('BasaltShell — the removed ReactNode slots', () => {
+  test('sidebarNavExtra and mobileNav.moreExtra no longer type-check', () => {
+    const removedNavExtra = (
+      <BasaltShell
+        brand={BRAND}
+        sections={ONE_SECTION}
+        // @ts-expect-error sidebarNavExtra was replaced by `sidebarBlocks` kind 'custom' (C13)
+        sidebarNavExtra={<div />}
+      />
+    )
+    const removedMoreExtra = (
+      <BasaltShell
+        brand={BRAND}
+        sections={ONE_SECTION}
+        // @ts-expect-error mobileNav.moreExtra was replaced by `sidebarBlocks` kind 'list' (C13)
+        mobileNav={{ moreExtra: <div /> }}
+      />
+    )
+    expect(removedNavExtra).toBeTruthy()
+    expect(removedMoreExtra).toBeTruthy()
+  })
 })
 
 /**
@@ -140,3 +226,203 @@ describe('BasaltShell collapse persistence', () => {
     expect(localStorage.getItem(`basalt:${key}`)).toBe(JSON.stringify({ v: 1, value: false }))
   })
 })
+
+/**
+ * Law C14 — an empty home renders nothing, so no route pays for a reserved row. This is the
+ * assertion the spec names as the law's gate: through 1.25.0 the mobile header was a 97px SUM whose
+ * second row (`appHeaderMobileActionsHeight`, 52px) was reserved on every route whether or not the
+ * page portalled anything into it. Both tokens are deleted; the header is `appShellHeaderHeight` at
+ * every width, and an empty `PageBar` adds no node in either place.
+ */
+describe('BasaltShell header height (law C14)', () => {
+  test('the AppShell header is ONE row — a single unconditional height declaration, no media override', () => {
+    render(
+      <MantineProvider>
+        <BasaltShell brand={BRAND} sections={ONE_SECTION} />
+      </MantineProvider>,
+    )
+    // Mantine emits the AppShell dimensions as a `<style>` block: one `:root` rule plus one
+    // `@media` rule per RESPONSIVE prop. A `{ base, sm }` header height therefore shows up twice;
+    // a single number shows up once, which is the invariant.
+    const css = [...document.querySelectorAll('style')]
+      .map((tag) => tag.textContent ?? '')
+      .find((text) => text.includes('--app-shell-header-height'))
+    expect(css).toBeDefined()
+    const heights = [...(css ?? '').matchAll(/--app-shell-header-height:\s*([^;]+)/g)].map(
+      (m) => m[1],
+    )
+    expect(heights).toHaveLength(1)
+    // 48px, expressed the way Mantine's own `rem()` does.
+    expect(heights[0]).toContain('3rem')
+    // The navbar and footer ARE responsive, so their overrides prove the query blocks still exist —
+    // the header simply is not among them any more.
+    expect(css).toContain('--app-shell-footer-height:0rem')
+  })
+
+  test('an empty PageBar contributes no node — not in the header, not in the page flow', () => {
+    render(
+      <MantineProvider>
+        <BasaltShell brand={BRAND} sections={ONE_SECTION}>
+          <PageBar />
+        </BasaltShell>
+      </MantineProvider>,
+    )
+    expect(document.querySelector('[data-basalt-page-bar]')).toBeNull()
+  })
+})
+
+/**
+ * `globalActions` is DECLARED DATA since 1.26.0 (`GlobalAction[]`, was `ReactNode`), which is what
+ * lets basalt project it onto mobile at all: the first two ride the bar, the rest fold into the
+ * header's ONE kebab, and a `'hidden'` one is dropped below `sm`. A `ReactNode` slot could express
+ * none of that, which is why every consumer hand-rolled a responsive twin instead.
+ */
+describe('BasaltShell globalActions mobile policy', () => {
+  const ACTIONS = [
+    { key: 'timer', node: <span data-testid="g-timer" /> },
+    { key: 'bell', node: <span data-testid="g-bell" /> },
+    { key: 'theme', node: <span data-testid="g-theme" /> },
+    { key: 'devtools', node: <span data-testid="g-devtools" />, mobile: 'hidden' as const },
+  ]
+
+  const renderWithGlobals = () =>
+    render(
+      <MantineProvider>
+        <BasaltShell brand={BRAND} sections={ONE_SECTION} globalActions={ACTIONS} />
+      </MantineProvider>,
+    )
+
+  test('the first two are mounted ONCE, unwrapped — visible at every width', () => {
+    renderWithGlobals()
+    for (const id of ['g-timer', 'g-bell']) {
+      const node = screen.getByTestId(id)
+      expect(node.closest('.mantine-visible-from-sm')).toBeNull()
+      expect(node.closest('.mantine-hidden-from-sm')).toBeNull()
+    }
+  })
+
+  test("the third defaults to 'more': desktop-only inline, plus the header's one kebab", () => {
+    renderWithGlobals()
+    expect(screen.getByTestId('g-theme').closest('.mantine-visible-from-sm')).not.toBeNull()
+    const kebabs = document.querySelectorAll('[aria-label="More actions"]')
+    expect(kebabs).toHaveLength(1)
+    expect(kebabs[0]?.closest('.mantine-hidden-from-sm')).not.toBeNull()
+  })
+
+  test("'hidden' drops it below sm and never reaches the kebab", () => {
+    renderWithGlobals()
+    expect(screen.getByTestId('g-devtools').closest('.mantine-visible-from-sm')).not.toBeNull()
+  })
+
+  test('a page ActionGroup takes over the kebab, so the header never shows two', () => {
+    render(
+      <MantineProvider>
+        <BasaltShell brand={BRAND} sections={ONE_SECTION} globalActions={ACTIONS}>
+          <PageBar actions={{ secondary: [{ key: 'export', label: 'Export' }] }} />
+        </BasaltShell>
+      </MantineProvider>,
+    )
+    expect(document.querySelectorAll('[aria-label="More actions"]')).toHaveLength(1)
+  })
+
+  test('filtersEnd folds into the SAME kebab — never a second one in row 2', () => {
+    // The bug this pins: every `ActionGroup` used to read the shell's `mobile: 'more'` globals and
+    // claim a kebab, so `PageBar.filtersEnd` (projected through its own group in row 2) grew a
+    // SECOND kebab that re-mounted the global node. Now only row 1 is `host: 'page'`.
+    render(
+      <MantineProvider>
+        <BasaltShell brand={BRAND} sections={ONE_SECTION} globalActions={ACTIONS}>
+          <PageBar
+            actions={{ secondary: [{ key: 'export', label: 'Export CSV' }] }}
+            filtersEnd={[{ key: 'metrics', label: 'Manage metrics' }]}
+          />
+        </BasaltShell>
+      </MantineProvider>,
+    )
+
+    const kebabs = document.querySelectorAll('[aria-label="More actions"]')
+    expect(kebabs).toHaveLength(1)
+    // And it is the HEADER's, not row 2's.
+    expect(kebabs[0]?.closest('[data-basalt-page-bar="shell"]')).toBeNull()
+    expect(document.querySelector('.mantine-AppShell-header')?.contains(kebabs[0] as Node)).toBe(
+      true,
+    )
+  })
+
+  test('the global node reaches ONE dropdown, not two', async () => {
+    render(
+      <MantineProvider>
+        <BasaltShell brand={BRAND} sections={ONE_SECTION} globalActions={ACTIONS}>
+          <PageBar
+            actions={{ secondary: [{ key: 'export', label: 'Export CSV' }] }}
+            filtersEnd={[{ key: 'metrics', label: 'Manage metrics' }]}
+          />
+        </BasaltShell>
+      </MantineProvider>,
+    )
+
+    // One inline copy (the desktop-only `visibleFrom` box) before any dropdown opens.
+    expect(screen.getAllByTestId('g-theme')).toHaveLength(1)
+    fireEvent.click(screen.getByLabelText('More actions'))
+    await waitFor(() => expect(document.querySelector('[role="menu"]')).not.toBeNull())
+    // Exactly one more copy — the open dropdown's — so the node is never live in two menus at once.
+    expect(screen.getAllByTestId('g-theme')).toHaveLength(2)
+    expect(document.querySelectorAll('[role="menu"]')).toHaveLength(1)
+  })
+
+  test("filtersEnd alone still yields exactly one kebab, and it is the header's", () => {
+    render(
+      <MantineProvider>
+        <BasaltShell brand={BRAND} sections={ONE_SECTION} globalActions={ACTIONS}>
+          <PageBar filtersEnd={[{ key: 'metrics', label: 'Manage metrics' }]} />
+        </BasaltShell>
+      </MantineProvider>,
+    )
+    const kebabs = document.querySelectorAll('[aria-label="More actions"]')
+    expect(kebabs).toHaveLength(1)
+    expect(document.querySelector('.mantine-AppShell-header')?.contains(kebabs[0] as Node)).toBe(
+      true,
+    )
+  })
+
+  test('a PageBar with no row-1 actions and no filtersEnd hands the kebab BACK to the shell', () => {
+    render(
+      <MantineProvider>
+        <BasaltShell brand={BRAND} sections={ONE_SECTION} globalActions={ACTIONS}>
+          <PageBar tabs={<span data-testid="tabs" />} />
+        </BasaltShell>
+      </MantineProvider>,
+    )
+    const kebabs = document.querySelectorAll('[aria-label="More actions"]')
+    expect(kebabs).toHaveLength(1)
+    expect(kebabs[0]?.closest('.mantine-hidden-from-sm')).not.toBeNull()
+  })
+
+  test('an ActionGroup mounted in some OTHER home inherits no global rows and no claim', () => {
+    // A consumer's tier-2 kebab (a `Section`/`ChartCard` actions slot) must not swallow the shell's
+    // globals — nor steal the claim, which would leave the shell's own kebab unrendered.
+    render(
+      <MantineProvider>
+        <BasaltShell brand={BRAND} sections={ONE_SECTION} globalActions={ACTIONS}>
+          <ActionGroup secondary={[{ key: 'a', label: 'Section action' }]} />
+        </BasaltShell>
+      </MantineProvider>,
+    )
+    // Two kebabs is CORRECT here: the shell's (globals) and the section's (its own rows). What must
+    // not happen is the global node appearing in the section's.
+    const shellKebab = document
+      .querySelector('.mantine-AppShell-header')
+      ?.querySelector('[aria-label="More actions"]')
+    expect(shellKebab).not.toBeNull()
+    expect(screen.getAllByTestId('g-theme')).toHaveLength(1)
+  })
+
+  test('no globalActions at all renders no kebab', () => {
+    render(
+      <MantineProvider>
+        <BasaltShell brand={BRAND} sections={ONE_SECTION} />
+      </MantineProvider>,
+    )
+    expect(document.querySelector('[aria-label="More actions"]')).toBeNull()
+  })
+})

package/src/shell/index.tsx

@@ -17,25 +17,37 @@
  * active item across `sections`, not from a router hook. Collapse is persisted via basalt's own
  * `createPersistedState` (`../state`) keyed by `storageKey` — see `collapseStore`.
  */
-import { AppShell } from '@mantine/core'
-import { useMemo } from 'react'
+import { AppShell, Box } from '@mantine/core'
+import { Fragment, useMemo } from 'react'
 import type { MouseEvent, ReactNode } from 'react'
 import { AppSidebar } from './app-sidebar'
 import { MobileNav, accountRowCount } from './app-mobile-nav'
-import { projectMobileNav } from './mobile-nav-model'
+import { blockRowCount, projectMobileNav } from './mobile-nav-model'
 import { AppBreadcrumbs } from './app-breadcrumbs'
-import { PageActionsOutlet, PageHeaderProvider } from './page-header'
-import type { BasaltAccountProps } from './account-types'
-import type { SidebarSearchConfig } from './sidebar-search'
-import type { MobileNavConfig, NavAnchor, SidebarItem, SidebarSection } from '../nav/types'
-import { useBasaltSpacing } from '../theme'
+import { PageBarOutlet, PageBarProvider, usePageKebabClaimed } from './page-bar'
+import { OverflowMenu, globalActionAsBarAction, globalActionMobile } from '../controls/actions'
+import type { GlobalAction } from '../controls/actions'
+import type { AccountMenuItem, BasaltAccountProps } from './account-types'
+import type { SidebarSearchActions, SidebarSearchConfig } from './sidebar-search'
+import type {
+  MobileNavConfig,
+  NavAnchor,
+  SidebarBlock,
+  SidebarItem,
+  SidebarSection,
+} from '../nav/types'
+import { CtlSlot, useBasaltSpacing } from '../theme'
 import { createPersistedState } from '../state'
 import headerClasses from './app-header.module.css'
 import mobileNavClasses from './app-mobile-nav.module.css'
 
 export { AppSidebar, type AppSidebarProps } from './app-sidebar'
 export { NavCountBadge } from './nav-count-badge'
-export { SidebarSearch, type SidebarSearchConfig } from './sidebar-search'
+export {
+  SidebarSearch,
+  type SidebarSearchConfig,
+  type SidebarSearchActions,
+} from './sidebar-search'
 export { SidebarAccount } from './app-sidebar-account'
 export type {
   AccountBadgeTone,
@@ -56,7 +68,7 @@ export {
   MOBILE_MORE_KEY,
 } from './mobile-nav-model'
 export { AppBreadcrumbs } from './app-breadcrumbs'
-export { PageHeaderProvider, PageActions, PageActionsOutlet } from './page-header'
+export { PageBar, type PageBarProps } from './page-bar'
 
 /**
  * The shared nav vocabulary lives in `src/nav/types.ts` so the headless router bridge can `import
@@ -70,6 +82,12 @@ export type {
   NavSectionMobile,
   SidebarItem,
   SidebarSection,
+  SidebarBlock,
+  SidebarBlockItem,
+  SidebarBlockTone,
+  SidebarListBlock,
+  SidebarProgressBlock,
+  SidebarCustomBlock,
   MobileNavConfig,
   MobileNavGroup,
   MobileNavModel,
@@ -98,8 +116,11 @@ export type SettingsMenuItem = {
 }
 
 export type BasaltShellProps = {
-  /** Brand identity for the sidebar header. */
-  brand: BrandConfig
+  /**
+   * 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.
+   */
+  brand: BrandConfig & { menu?: AccountMenuItem[] }
   /** Grouped nav sections — the ONE definition, rendered as the sidebar and projected to the bar. */
   sections: SidebarSection[]
   /**
@@ -107,28 +128,54 @@ export type BasaltShellProps = {
    * configured still produces a working bar (see `projectMobileNav`'s zero-config fallback).
    */
   mobileNav?: MobileNavConfig
-  /** Persistent, shell-owned top-bar slot (timer, refresh, notifications). */
-  globalActions?: ReactNode
   /**
-   * DESKTOP ONLY. Arbitrary content appended after `sections` inside the sidebar's nav scroll
-   * region (a tree, a filter panel, a project list, …), for anything a set of `SidebarItem`s can't
-   * express. Hidden on the collapsed desktop rail; the sidebar itself no longer exists below the
-   * `sm` breakpoint, so this slot has no mobile representation — put mobile-reachable extras in
-   * `mobileNav.moreExtra` instead.
+   * Persistent, shell-owned header actions (timer, notifications, a global `SyncButton`) — DECLARED
+   * DATA, not a `ReactNode` slot, so basalt owns the mobile projection: the first two ride the bar,
+   * the rest fold into the header's single kebab (`mobile: 'bar' | 'more' | 'hidden'`, see
+   * `GlobalAction`). That kebab is the SAME one `PageBar`'s ROW 1 opens — a route whose bar has
+   * row-1 actions (or `filtersEnd`) lends it, any other route gets it from the shell. An
+   * `ActionGroup` a consumer mounts in some other home never inherits these rows.
+   */
+  globalActions?: GlobalAction[]
+  /**
+   * Sidebar blocks — DECLARED DATA (law C13, `docs/CONTROLS-SPEC.md` §2.3), which replaced both
+   * `sidebarNavExtra` and `mobileNav.moreExtra`. `placement: 'nav'` (the default for `list` and
+   * `custom`) appends after the nav sections inside the scroll region; `'bottom'` pins above the
+   * settings footer.
+   *
+   * Because they are data, basalt owns the projections the two `ReactNode` slots could not express:
+   * a `list` with a `count` becomes a dot on its icon in the collapsed rail, a `progress` block
+   * becomes a ring on the settings row, and a block with `mobile: 'more'` becomes one More-sheet
+   * row opening a nested sheet of its items. A `kind: 'custom'` block is desktop-only, exactly as
+   * `sidebarNavExtra` was.
+   */
+  sidebarBlocks?: SidebarBlock[]
+  /**
+   * Entries appended to the sidebar settings footer — flat link rows at three or fewer, one gear
+   * menu at four or more (`AppSidebarProps.settingsMenuItems` documents the threshold).
    */
-  sidebarNavExtra?: ReactNode
-  /** Entries appended to the sidebar settings menu. */
   settingsMenuItems?: SettingsMenuItem[]
   /**
-   * Optional account row rendered above the settings menu in the sidebar footer (see
+   * Forces the footer form instead of taking the count rule above: `'flat'` always renders link
+   * rows, `'menu'` always renders the gear dropdown. `'auto'` (the default) is today's ≤3 → flat
+   * behaviour. Reach for it when the rows are CONTROLS rather than destinations — three of those
+   * (a theme radio group, a devtools switch) read as a widget pile in the footer even though the
+   * count says flat. Full rationale on `AppSidebarProps.settingsMenu`.
+   *
+   * @default 'auto'
+   */
+  settingsMenu?: 'auto' | 'flat' | 'menu'
+  /**
+   * Optional account row rendered below the settings menu in the sidebar footer (see
    * `SidebarAccount` / `BasaltAccountProps`). Omitting it reproduces today's footer unchanged.
    */
   account?: BasaltAccountProps
   /**
    * Optional search field below the brand in the sidebar (fixed, above the nav scroll). Supply
-   * `onOpen`, e.g. `() => openSpotlight()` from basalt-ui/commands.
+   * `onOpen`, e.g. `() => openSpotlight()` from basalt-ui/commands. `actions` adds one or two
+   * icon-only buttons to the right of that row (a tuple by type — see `SidebarSearchActions`).
    */
-  search?: SidebarSearchConfig
+  search?: SidebarSearchConfig & { actions?: SidebarSearchActions }
   /**
    * localStorage key for the persisted sidebar-collapsed flag. Ignored when `collapsed` is set.
    *
@@ -254,8 +301,9 @@ export function BasaltShell({
   sections,
   mobileNav,
   globalActions,
-  sidebarNavExtra,
+  sidebarBlocks,
   settingsMenuItems,
+  settingsMenu,
   storageKey = 'basalt-sidebar-collapsed',
   collapsed: collapsedProp,
   onCollapsedChange,
@@ -280,26 +328,29 @@ export function BasaltShell({
   }
 
   const activeCrumb = findActiveCrumb(sections)
-  // The account row and every settings entry render as flat rows in the More surface (there is no
-  // mobile sidebar to reach them through any more), so they count toward BOTH `needsMore` and the
-  // menu-vs-sheet threshold. `accountRowCount` is the SAME function that renders those rows, not a
-  // second estimate of them: an account is worth 0 rows while `loading` and up to seven once
-  // authenticated, and §2.2's whole guarantee (`menuMax` rows fit the headroom above the bar, and
-  // the menu runs `flip: false` so it cannot escape upward) is arithmetic over this number.
+  // The account row, every settings entry and every mobile-reachable sidebar block render as flat
+  // rows in the More surface (there is no mobile sidebar to reach them through any more), so they
+  // count toward BOTH `needsMore` and the menu-vs-sheet threshold. `accountRowCount` and
+  // `blockRowCount` are the SAME functions the renderer agrees with, not second estimates of them:
+  // an account is worth 0 rows while `loading` and up to seven once authenticated, a block is worth
+  // exactly one row however many items it holds, and §2.2's whole guarantee (`menuMax` rows fit the
+  // headroom above the bar, and the menu runs `flip: false` so it cannot escape upward) is
+  // arithmetic over this number.
   const extraMoreRows =
-    accountRowCount(account) + (settingsMenuItems?.length ?? 0) + (mobileNav?.moreExtra ? 1 : 0)
+    accountRowCount(account) + (settingsMenuItems?.length ?? 0) + blockRowCount(sidebarBlocks)
   const model = useMemo(
     () => projectMobileNav(sections, { config: mobileNav, extraMoreRows }),
     [sections, mobileNav, extraMoreRows],
   )
 
   return (
-    <PageHeaderProvider>
+    <PageBarProvider globalActions={globalActions ?? []}>
       <AppShell
         h="100dvh"
         layout="alt"
         header={{
-          height: { base: step.appShellHeaderMobileHeight, sm: step.appShellHeaderHeight },
+          // ONE height at every width (law C14): nothing reserves a second mobile row any more.
+          height: step.appShellHeaderHeight,
         }}
         navbar={{
           width: {
@@ -320,8 +371,8 @@ export function BasaltShell({
             <div className={headerClasses.lead}>
               <AppBreadcrumbs {...activeCrumb} />
             </div>
-            <PageActionsOutlet className={headerClasses.pageActions} />
-            {globalActions && <div className={headerClasses.global}>{globalActions}</div>}
+            <PageBarOutlet className={headerClasses.pageBar} />
+            <HeaderGlobalActions actions={globalActions ?? []} />
           </div>
         </AppShell.Header>
 
@@ -331,8 +382,9 @@ export function BasaltShell({
             sections={sections}
             collapsed={collapsed}
             onToggleCollapse={toggleCollapse}
-            navExtra={sidebarNavExtra}
+            {...(sidebarBlocks !== undefined && { blocks: sidebarBlocks })}
             {...(settingsMenuItems !== undefined && { settingsMenuItems })}
+            {...(settingsMenu !== undefined && { settingsMenu })}
             {...(account !== undefined && { account })}
             {...(search !== undefined && { search })}
           />
@@ -349,9 +401,56 @@ export function BasaltShell({
             config={mobileNav}
             {...(account !== undefined && { account })}
             {...(settingsMenuItems !== undefined && { settingsMenuItems })}
+            {...(sidebarBlocks !== undefined && { blocks: sidebarBlocks })}
           />
         </AppShell.Footer>
       </AppShell>
-    </PageHeaderProvider>
+    </PageBarProvider>
+  )
+}
+
+/**
+ * The shell's own `globalActions`, projected for both viewports.
+ *
+ * Each action is mounted EXACTLY ONCE inline, in declaration order — a `mobile: 'bar'` action with
+ * no wrapper (visible at every width), a `'more'`/`'hidden'` one inside a `visibleFrom="sm"` box.
+ * The `'more'` nodes appear a second time only inside the kebab dropdown, which Mantine mounts
+ * lazily on open. That asymmetry is why `GlobalAction`'s JSDoc points anything stateful at
+ * `mobile: 'bar'`.
+ *
+ * The kebab renders here only while NO page bar owns one (`usePageKebabClaimed`), so a header never
+ * shows two — the claim is what makes "one kebab per header" a fact rather than a convention.
+ */
+function HeaderGlobalActions({ actions }: { actions: readonly GlobalAction[] }): ReactNode {
+  const kebabClaimed = usePageKebabClaimed()
+  if (actions.length === 0) return null
+
+  const more = actions
+    .filter((action, index) => globalActionMobile(action, index) === 'more')
+    .map(globalActionAsBarAction)
+
+  return (
+    // `CtlSlot` here for the same reason a home wraps its own slot (law C5): `globalActions` are
+    // consumer NODES, so basalt cannot pass them a size — it can only provide the tier they resolve
+    // against. Without it a `<NotificationBell/>`'s internal `ActionIcon` fell back to Mantine's
+    // `md` (28px) beside a 30px page group.
+    <CtlSlot>
+      <div className={headerClasses.global}>
+        {actions.map((action, index) =>
+          globalActionMobile(action, index) === 'bar' ? (
+            <Fragment key={action.key}>{action.node}</Fragment>
+          ) : (
+            <Box key={action.key} visibleFrom="sm">
+              {action.node}
+            </Box>
+          ),
+        )}
+        {!kebabClaimed && more.length > 0 && (
+          <Box hiddenFrom="sm">
+            <OverflowMenu actions={more} trigger="kebab" label="More actions" />
+          </Box>
+        )}
+      </div>
+    </CtlSlot>
   )
 }