basalt-ui 1.38.0 → 1.39.0

package/AGENTS.md

@@ -15,7 +15,7 @@ Toolchain: Bun runtime, oxlint + oxfmt, conventional commits (empty scope), `mas
 | `basalt-ui/vite`            | build-tooling   | basaltViteConfig(opts) — Vite preset for basalt-ui consumer apps; basaltAppPlugin(opts) — PWA head, manifest, and icon metadata derived from the token palette                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `basalt-ui/guard`           | headless        | checkSource, GUARD_RULES, Finding types — the headless theme-guard core                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
 | `basalt-ui/router-tanstack` | headless        | TanStack Router bridge: defineNav/navGroup/navTarget (one typed nav definition) + useNav (sections + mobileNav, spread onto BasaltShell) + useBasaltNav (active route) + useRouterBreadcrumbs + createSearchStore (typed URL > localStorage > fallback store over field.enum/multi/range/number/boolean/string; the deprecated createSearchParamStore/createMultiSearchParamStore wrappers were removed in 1.29.0, C1 consolidation)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
-| `basalt-ui/forms`           | mantine-coupled | Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls — a spread `key` is a React 19 warning; the deprecated `field` alias for `inputProps` was removed in 1.29.0, C1 consolidation), useFormSubmit (submit state, decoded errors, server fieldErrors, focus-first-error, validateAsync), FormStateProvider disable propagation, useFieldArray, FormErrorSummary, useFormDraft with autosave (Standard Schema). The FormSection/FormRow/FormGroup/FormActions layout moved to ./controls in 1.36.0 and the useForm/schemaResolver re-exports are deprecated (import from @mantine/form); all six stay here until 1.37.0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `basalt-ui/forms`           | mantine-coupled | Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls — a spread `key` is a React 19 warning; the deprecated `field` alias for `inputProps` was removed in 1.29.0, C1 consolidation), useFormSubmit (submit state, decoded errors, server fieldErrors, focus-first-error, validateAsync), FormStateProvider disable propagation, useFieldArray, FormErrorSummary, useFormDraft with autosave (Standard Schema). The FormSection/FormRow/FormGroup/FormActions layout lives in ./controls (moved in 1.36.0) and useForm/schemaResolver come from @mantine/form; the six re-exports here were removed in 1.39.0                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
 | `basalt-ui/notifications`   | mantine-coupled | Mantine notifications: notify helpers, typed registry, persisted history, NotificationBell, NotificationCenter                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `basalt-ui/commands`        | mantine-coupled | typed command bus + overlay controller, toSpotlightActions, ShortcutsHelp, BasaltOverlays                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `basalt-ui/data/table`      | mantine-coupled | BasaltDataTable: a sortable data table over TanStack Table, rendered with Mantine (Mantine-rendered)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

package/CHANGELOG.md

@@ -1,3 +1,18 @@
+# [1.39.0](https://github.com/jkrumm/basalt-ui/compare/v1.38.1...v1.39.0) (2026-10-04)
+
+
+### Features
+
+* add BasaltShell headerHeight for a deliberate, consumer-set header row ([3561361](https://github.com/jkrumm/basalt-ui/commit/3561361279664d3ee51d245586331e057dd62844))
+* remove the deprecated forms layout and useForm re-exports ([9e8b8c6](https://github.com/jkrumm/basalt-ui/commit/9e8b8c69241ea33d8bdf47532358166a809eb4ce))
+
+## [1.38.1](https://github.com/jkrumm/basalt-ui/compare/v1.38.0...v1.38.1) (2026-10-04)
+
+
+### Bug Fixes
+
+* take the page content inset one step down, 20/12 to 16/8 from sm up ([cf61c05](https://github.com/jkrumm/basalt-ui/commit/cf61c05410df114d5c6182ed4a8c5ed38b308a56))
+
 # [1.38.0](https://github.com/jkrumm/basalt-ui/compare/v1.37.1...v1.38.0) (2026-10-04)
 
 

package/MIGRATING.md

@@ -66,18 +66,18 @@ There is one row per SURFACE, not per export, and a surface earns a row once any
 shipped lefthook preset both changed in 1.30.0 with no row that owned them — which is how a
 consumer read this index, found nothing, and diffed a KPI row that had silently gone 4-up → 2-up.
 
-| Surface                       | 1.27.0                                                       | 1.28.0                                                                                 | 1.29.0                                                                                         | 1.30.0                                                                             | 1.30.1                                                                | 1.30.2 | 1.31.0                                                                                                | 1.32.0                                                                    | 1.32.1                                                                                                          | 1.33.0                                                                        | 1.34.0                             | 1.34.1 | 1.35.0 | 1.36.0                                                                                       | 1.36.1 | 1.37.0 | 1.37.1 | 1.38.0 | Unreleased |
-| ----------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------- | ------ | ------ | -------------------------------------------------------------------------------------------- | ------ | ------ | ------ | ------ | ---------- |
-| **tokens** (`./tokens`)       | —                                                            | `--vx-divider` → `rgba()` on both schemes (§ Shell)                                    | `--vx-space-touch-target` added (§ Additions)                                                  | eight spacing numbers (§ Chrome)                                                   | —                                                                     | —      | `--vx-hit` replaces the touch vars; `SIZE_CLASSES` (§ 1.31.0)                                         | —                                                                         | `SIZE_CLASSES`/`CONTAINER_CLASSES` actually exported (§ Fixes)                                                  | `CONTAINER_GRID_BREAKPOINTS`; `raw-breakpoint` trusts it (§ 1.33.0)           | `CONTAINER_KEYS` (§ 1.34.0)        | —      | —      | —                                                                                            | —      | —      | —      | —      | —          |
-| **charts** (`./charts`)       | —                                                            | phone tier, `curve`, formatters, `state`, log axis (§ preamble)                        | `ChartState.empty: string`, `AxisBottomNumeric` (§ Additions)                                  | responsive `height`, `legend.maxRows` (§ Charts)                                   | `height` reaches the kinds; `maxRows` beats the `fill` fit (§ Charts) | —      | container-class tier + `height` keys (§ 1.31.0)                                                       | —                                                                         | `ResponsiveChartHeight` `sm` → key (§ Container recipes)                                                        | —                                                                             | —                                  | —      | —      | —                                                                                            | —      | —      | —      | —      | —          |
-| **shell** (`.`)               | —                                                            | scrollport, region seams, **the brand left the sidebar** (§§ scrollport, brand, Shell) | `PageTitle`, `BasaltDevDock`, `useBreakpoint` (§ Additions)                                    | More popover, aside pill, the responsive gutter, `useBasaltSpacing` (§ Chrome)     | —                                                                     | —      | `theme.breakpoints` derived, `useSizeClass`, `data-basalt-host`, `useBreakpoint` on notice (§ 1.31.0) | `useBreakpoint` removal → 1.33.0; `useSizeClass` is shell-only (§ 1.32.0) | shell-less `shell/` gutter, `AppShell` breakpoints, `useSizeClass` for overlays (§§ Shell-less, `useSizeClass`) | —                                                                             | `useBreakpoint` removed (§ 1.34.0) | —      | —      | `useCoarsePointer()` (§ `useCoarsePointer()`)                                                | —      | —      | —      | —      | —          |
-| **controls** (`./controls`)   | `NumberFilter`, `field.number` (§ Controls)                  | sheet renders panel rows; `PanelRow`, `SliderControl` (§ `basalt-ui/controls`)         | —                                                                                              | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | `NumberFilter clearable`; `createSearchStore` `resets` (§ State and controls) | —                                  | —      | —      | `FormSection`/`FormRow`/`FormGroup`/`FormActions` move here (§ The form layout moves)        | —      | —      | —      | —      | —          |
-| **forms** (`./forms`)         | —                                                            | `field` → `inputProps`, **`inputProps` drops `key`**, the layout tier (§ `inputProps`) | `field` DELETED — and the `--fix` recipe no longer works (§ Consolidation)                     | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | `FormGroup` row no longer stretches (§ Fixes)                                                                   | —                                                                             | —                                  | —      | —      | the layout + `useForm`/`schemaResolver` deprecated, removed 1.37.0 (§ The form layout moves) | —      | —      | —      | —      | —          |
-| **data** (`./data/table`)     | —                                                            | root is a `<div>`, row selection, `getItemKey` required (§ `basalt-ui/data`)           | `./data` + `./query` + `./connectivity` dropped (§ Consolidation)                              | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | `renderCard` documented (§ `renderCard`)                                                                        | —                                                                             | —                                  | —      | —      | —                                                                                            | —      | —      | —      | —      | —          |
-| **dashboard** (`.`)           | `StatCard`: `unit`, `breakdown`, delta format (§ `StatCard`) | `StatGroup`, `WidgetGrid`, query-aware `StatCard` — additive                           | —                                                                                              | **the column law keys on the CONTAINER; `cols={4}` is 2-up at `sm`** (§ Dashboard) | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | —                                                                             | —                                  | —      | —      | —                                                                                            | —      | —      | —      | —      | —          |
-| **toolchain** (`./configs/*`) | —                                                            | —                                                                                      | the shipped lefthook preset's `check-theme` BROKE — the CLI resolver stopped ascending (§ CLI) | the preset's default bin, and the `root:` recipe (§ Toolchain)                     | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | —                                                                             | —                                  | —      | —      | —                                                                                            | —      | —      | —      | —      | —          |
-| **CLI** (`basalt-ui`)         | —                                                            | —                                                                                      | **resolver stops relocating; `doctor` loses 6 of 10 checks** (§ CLI)                           | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | —                                                                             | —                                  | —      | —      | —                                                                                            | —      | —      | —      | —      | —          |
-| **guards**                    | five rules → `error` (§ Guards)                              | six new ids at `warn` (§ preamble)                                                     | `query-dual-import` retired in 1.29.1 (§ Guards)                                               | four rules → `error` (§ Guards)                                                    | —                                                                     | —      | —                                                                                                     | `raw-breakpoint`: the container-grid answer, `error` at 1.33.0 (§ 1.32.0) | `FormRow`/`FormGroup` homes in both lanes; `basalt-main` dropped (§ Fixes)                                      | C1 + breakpoint pairs → `error`; `unknown-vx-token` `warn` (§ Guards)         | —                                  | —      | —      | `unknown-vx-token` → `error`; the token factories throw (§ Guards)                           | —      | —      | —      | —      | —          |
+| Surface                       | 1.27.0                                                       | 1.28.0                                                                                 | 1.29.0                                                                                         | 1.30.0                                                                             | 1.30.1                                                                | 1.30.2 | 1.31.0                                                                                                | 1.32.0                                                                    | 1.32.1                                                                                                          | 1.33.0                                                                        | 1.34.0                             | 1.34.1 | 1.35.0 | 1.36.0                                                                                       | 1.36.1 | 1.37.0 | 1.37.1 | 1.38.0 | 1.38.1 | 1.39.0                                          | Unreleased |
+| ----------------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ---------------------------------- | ------ | ------ | -------------------------------------------------------------------------------------------- | ------ | ------ | ------ | ------ | ------ | ----------------------------------------------- | ---------- | --- |
+| **tokens** (`./tokens`)       | —                                                            | `--vx-divider` → `rgba()` on both schemes (§ Shell)                                    | `--vx-space-touch-target` added (§ Additions)                                                  | eight spacing numbers (§ Chrome)                                                   | —                                                                     | —      | `--vx-hit` replaces the touch vars; `SIZE_CLASSES` (§ 1.31.0)                                         | —                                                                         | `SIZE_CLASSES`/`CONTAINER_CLASSES` actually exported (§ Fixes)                                                  | `CONTAINER_GRID_BREAKPOINTS`; `raw-breakpoint` trusts it (§ 1.33.0)           | `CONTAINER_KEYS` (§ 1.34.0)        | —      | —      | —                                                                                            | —      | —      | —      | —      |        | `appShellInset` 20 → 16 (§ 1.38.1)              | —          | —   |
+| **charts** (`./charts`)       | —                                                            | phone tier, `curve`, formatters, `state`, log axis (§ preamble)                        | `ChartState.empty: string`, `AxisBottomNumeric` (§ Additions)                                  | responsive `height`, `legend.maxRows` (§ Charts)                                   | `height` reaches the kinds; `maxRows` beats the `fill` fit (§ Charts) | —      | container-class tier + `height` keys (§ 1.31.0)                                                       | —                                                                         | `ResponsiveChartHeight` `sm` → key (§ Container recipes)                                                        | —                                                                             | —                                  | —      | —      | —                                                                                            | —      | —      | —      | —      | —      | —                                               | —          |
+| **shell** (`.`)               | —                                                            | scrollport, region seams, **the brand left the sidebar** (§§ scrollport, brand, Shell) | `PageTitle`, `BasaltDevDock`, `useBreakpoint` (§ Additions)                                    | More popover, aside pill, the responsive gutter, `useBasaltSpacing` (§ Chrome)     | —                                                                     | —      | `theme.breakpoints` derived, `useSizeClass`, `data-basalt-host`, `useBreakpoint` on notice (§ 1.31.0) | `useBreakpoint` removal → 1.33.0; `useSizeClass` is shell-only (§ 1.32.0) | shell-less `shell/` gutter, `AppShell` breakpoints, `useSizeClass` for overlays (§§ Shell-less, `useSizeClass`) | —                                                                             | `useBreakpoint` removed (§ 1.34.0) | —      | —      | `useCoarsePointer()` (§ `useCoarsePointer()`)                                                | —      | —      | —      | —      |        | content gutter 16, block 8 from `sm` (§ 1.38.1) | —          | —   |
+| **controls** (`./controls`)   | `NumberFilter`, `field.number` (§ Controls)                  | sheet renders panel rows; `PanelRow`, `SliderControl` (§ `basalt-ui/controls`)         | —                                                                                              | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | `NumberFilter clearable`; `createSearchStore` `resets` (§ State and controls) | —                                  | —      | —      | `FormSection`/`FormRow`/`FormGroup`/`FormActions` move here (§ The form layout moves)        | —      | —      | —      | —      | —      | —                                               | —          |
+| **forms** (`./forms`)         | —                                                            | `field` → `inputProps`, **`inputProps` drops `key`**, the layout tier (§ `inputProps`) | `field` DELETED — and the `--fix` recipe no longer works (§ Consolidation)                     | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | `FormGroup` row no longer stretches (§ Fixes)                                                                   | —                                                                             | —                                  | —      | —      | the layout + `useForm`/`schemaResolver` deprecated, removed 1.37.0 (§ The form layout moves) | —      | —      | —      | —      | —      | —                                               | —          |
+| **data** (`./data/table`)     | —                                                            | root is a `<div>`, row selection, `getItemKey` required (§ `basalt-ui/data`)           | `./data` + `./query` + `./connectivity` dropped (§ Consolidation)                              | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | `renderCard` documented (§ `renderCard`)                                                                        | —                                                                             | —                                  | —      | —      | —                                                                                            | —      | —      | —      | —      | —      | —                                               | —          |
+| **dashboard** (`.`)           | `StatCard`: `unit`, `breakdown`, delta format (§ `StatCard`) | `StatGroup`, `WidgetGrid`, query-aware `StatCard` — additive                           | —                                                                                              | **the column law keys on the CONTAINER; `cols={4}` is 2-up at `sm`** (§ Dashboard) | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | —                                                                             | —                                  | —      | —      | —                                                                                            | —      | —      | —      | —      | —      | —                                               | —          |
+| **toolchain** (`./configs/*`) | —                                                            | —                                                                                      | the shipped lefthook preset's `check-theme` BROKE — the CLI resolver stopped ascending (§ CLI) | the preset's default bin, and the `root:` recipe (§ Toolchain)                     | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | —                                                                             | —                                  | —      | —      | —                                                                                            | —      | —      | —      | —      | —      | —                                               | —          |
+| **CLI** (`basalt-ui`)         | —                                                            | —                                                                                      | **resolver stops relocating; `doctor` loses 6 of 10 checks** (§ CLI)                           | —                                                                                  | —                                                                     | —      | —                                                                                                     | —                                                                         | —                                                                                                               | —                                                                             | —                                  | —      | —      | —                                                                                            | —      | —      | —      | —      | —      | —                                               | —          |
+| **guards**                    | five rules → `error` (§ Guards)                              | six new ids at `warn` (§ preamble)                                                     | `query-dual-import` retired in 1.29.1 (§ Guards)                                               | four rules → `error` (§ Guards)                                                    | —                                                                     | —      | —                                                                                                     | `raw-breakpoint`: the container-grid answer, `error` at 1.33.0 (§ 1.32.0) | `FormRow`/`FormGroup` homes in both lanes; `basalt-main` dropped (§ Fixes)                                      | C1 + breakpoint pairs → `error`; `unknown-vx-token` `warn` (§ Guards)         | —                                  | —      | —      | `unknown-vx-token` → `error`; the token factories throw (§ Guards)                           | —      | —      | —      | —      | —      | —                                               | —          |
 
 ---
 
@@ -86,6 +86,44 @@ consumer read this index, found nothing, and diffed a KPI row that had silently
 _Nothing yet. Author the next section under this heading as `## Unreleased — <title>`; the
 release renames it and opens a new one here._
 
+## 1.39.0 — the forms aliases leave
+
+**Added: `BasaltShell headerHeight?: number`** (px, default unchanged — the density-tracking
+`appShellHeaderHeight`, 44). One value for both sidebar forms and every width; the navbar and aside
+tops, the page-bar band and Main follow it. A native unified-toolbar title bar sets ~52.
+
+**Removed (grace ended — deprecated in 1.36.0, re-dated twice):** the six `basalt-ui/forms`
+re-exports below. No autofix: move the import by hand.
+
+| Was (`basalt-ui/forms`)                                                               | Now                                      |
+| ------------------------------------------------------------------------------------- | ---------------------------------------- |
+| `FormSection`, `FormRow`, `FormGroup`, `FormActions` (+ their `*Props`/`*Slot` types) | the same names from `basalt-ui/controls` |
+| `useForm`, `schemaResolver`, `UseFormReturnType`, `UseFormInput`                      | `@mantine/form` directly                 |
+
+`basalt/deprecated-export` keeps the rows as `removed: true`, so an old import still gets a finding
+that names the new home. `useBasaltForm`, `inputProps`, `fieldKey`, `useFormSubmit`,
+`FormStateProvider`, `useFieldArray`, `FormErrorSummary` and `useFormDraft` are unchanged.
+The `public symbols` budget is back to 400.
+
+## 1.38.1 — the content inset
+
+No export changed. Two default numbers moved, both from `sm` up (the phone gutter is untouched):
+
+| Measured, 1440px desktop                                  | Before   | After    |
+| --------------------------------------------------------- | -------- | -------- |
+| Main's inner box, from the sidebar seam (`appShellInset`) | 20px     | 16px     |
+| Main's inner box, under the header / page-bar band        | 12px     | 8px      |
+| Header breadcrumb x, expanded / rail                      | 269 / 61 | 272 / 64 |
+| Brand mark x (the sidebar's nav-icon column)              | 20px     | 20px     |
+
+The block inset is `stack-sm` from `sm` up and stays `stack-md` (12) on a phone. The breadcrumb
+now sits exactly on Main's content edge (it was 7px short of it); the brand mark no longer borrows
+the page gutter for its x — it is the nav-icon column (`row-inset-x` twice) on its own, so it stays
+at 20 while the gutter is 16.
+
+A consumer that wants the old numbers has no knob for them: the gutter
+is a `SPACE_STEP` entry, so retune it through the density level or accept the new default.
+
 ## 1.38.0
 
 _Nothing to migrate in this release._

package/configs/oxlint-plugin.js

@@ -3672,6 +3672,7 @@ export const DEPRECATED_EXPORTS = [
     name: 'FormSection',
     replacement: "FormSection from 'basalt-ui/controls'",
     removeIn: '1.39.0',
+    removed: true,
     fix: false,
   },
   {
@@ -3679,6 +3680,7 @@ export const DEPRECATED_EXPORTS = [
     name: 'FormRow',
     replacement: "FormRow from 'basalt-ui/controls'",
     removeIn: '1.39.0',
+    removed: true,
     fix: false,
   },
   {
@@ -3686,6 +3688,7 @@ export const DEPRECATED_EXPORTS = [
     name: 'FormGroup',
     replacement: "FormGroup from 'basalt-ui/controls'",
     removeIn: '1.39.0',
+    removed: true,
     fix: false,
   },
   {
@@ -3693,6 +3696,7 @@ export const DEPRECATED_EXPORTS = [
     name: 'FormActions',
     replacement: "FormActions from 'basalt-ui/controls'",
     removeIn: '1.39.0',
+    removed: true,
     fix: false,
   },
   {
@@ -3700,6 +3704,7 @@ export const DEPRECATED_EXPORTS = [
     name: 'useForm',
     replacement: "useForm from '@mantine/form'",
     removeIn: '1.39.0',
+    removed: true,
     fix: false,
   },
   {
@@ -3707,6 +3712,7 @@ export const DEPRECATED_EXPORTS = [
     name: 'schemaResolver',
     replacement: "schemaResolver from '@mantine/form'",
     removeIn: '1.39.0',
+    removed: true,
     fix: false,
   },
   {

package/configs/oxlint-plugin.test.ts

@@ -3393,7 +3393,7 @@ describe('basalt/deprecated-export — the form layout move', () => {
       )
       expect(rules).toContain('deprecated-export')
       expect(output).toContain(`'basalt-ui/controls'`)
-      expect(output).toContain('removed in 1.39.0')
+      expect(output).toContain('was removed in 1.39.0')
     },
   )
 
@@ -3403,6 +3403,7 @@ describe('basalt/deprecated-export — the form layout move', () => {
     )
     expect(rules).toContain('deprecated-export')
     expect(output).toContain(`'@mantine/form'`)
+    expect(output).toContain('was removed in 1.39.0')
   })
 
   it('does NOT report FormRow imported from basalt-ui/controls', () => {

package/dist/forms/index.d.ts

@@ -8,38 +8,15 @@
  *
  * Four pieces: the form (`useBasaltForm` + `inputProps`/`fieldKey`), the submit lifecycle
  * (`useFormSubmit` + `FormStateProvider`), the list field (`useFieldArray`) and the draft
- * (`useFormDraft`). The layout (`FormSection` / `FormRow` / `FormGroup` / `FormActions`) moved to
- * `basalt-ui/controls` in 1.36.0 — it needs no `@mantine/form` — and stays here as deprecated
- * aliases until 1.39.0, as do the `useForm`/`schemaResolver` re-exports (import from
- * `@mantine/form`).
+ * (`useFormDraft`). The layout (`FormSection` / `FormRow` / `FormGroup` / `FormActions`) lives in
+ * `basalt-ui/controls` (it needs no `@mantine/form`); `useForm`/`schemaResolver` come from
+ * `@mantine/form` directly. Both stopped being re-exported here in 1.39.0.
  *
  * Optional peer: @mantine/form ^9.3.0 — install with: bun add @mantine/form
  */
 export { useBasaltForm } from './create-form.js';
 export type { UseBasaltFormOptions } from './create-form.js';
 export { inputProps, fieldKey } from './field.js';
-export { 
-/** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
-FormSection, 
-/** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
-FormRow, 
-/** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
-FormGroup, 
-/** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
-FormActions, } from '../controls/form-layout.js';
-export type { 
-/** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
-FormSectionProps, 
-/** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
-FormSectionSlot, 
-/** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
-FormRowProps, 
-/** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
-FormRowSlot, 
-/** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
-FormGroupProps, 
-/** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
-FormActionsProps, } from '../controls/form-layout.js';
 export { useFormSubmit, isFieldErrorEnvelope } from './use-form-submit.js';
 export type { FormFieldErrors, UseFormSubmitOptions, UseFormSubmitReturn } from './use-form-submit.js';
 export { FormStateProvider, useFormState } from './form-state.js';
@@ -50,14 +27,4 @@ export { FormErrorSummary } from './FormErrorSummary.js';
 export type { FormErrorSummaryProps } from './FormErrorSummary.js';
 export { useFormDraft, DEFAULT_AUTOSAVE_DEBOUNCE_MS } from './use-form-draft.js';
 export type { UseFormDraftOptions, UseFormDraftReturn } from './use-form-draft.js';
-export { 
-/** @deprecated Import from '@mantine/form' — removed in 1.39.0. */
-useForm, 
-/** @deprecated Import from '@mantine/form' — removed in 1.39.0. */
-schemaResolver, } from '@mantine/form';
-export type { 
-/** @deprecated Import from '@mantine/form' — removed in 1.39.0. */
-UseFormReturnType, 
-/** @deprecated Import from '@mantine/form' — removed in 1.39.0. */
-UseFormInput, } from '@mantine/form';
 //# sourceMappingURL=index.d.ts.map

package/dist/forms/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/forms/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AAIzD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAG9C,OAAO;AACL,wEAAwE;AACxE,WAAW;AACX,wEAAwE;AACxE,OAAO;AACP,wEAAwE;AACxE,SAAS;AACT,wEAAwE;AACxE,WAAW,GACZ,MAAM,yBAAyB,CAAA;AAChC,YAAY;AACV,wEAAwE;AACxE,gBAAgB;AAChB,wEAAwE;AACxE,eAAe;AACf,wEAAwE;AACxE,YAAY;AACZ,wEAAwE;AACxE,WAAW;AACX,wEAAwE;AACxE,cAAc;AACd,wEAAwE;AACxE,gBAAgB,GACjB,MAAM,yBAAyB,CAAA;AAGhC,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AACvE,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACnG,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC9D,YAAY,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAGrE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAG5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACrD,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAG/D,OAAO,EAAE,YAAY,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAA;AAC7E,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAG/E,OAAO;AACL,mEAAmE;AACnE,OAAO;AACP,mEAAmE;AACnE,cAAc,GACf,MAAM,eAAe,CAAA;AACtB,YAAY;AACV,mEAAmE;AACnE,iBAAiB;AACjB,mEAAmE;AACnE,YAAY,GACb,MAAM,eAAe,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/forms/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,YAAY,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AAIzD,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAA;AAG9C,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AACvE,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACnG,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AAC9D,YAAY,EAAE,SAAS,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAGrE,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AACjD,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAG5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACrD,YAAY,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAG/D,OAAO,EAAE,YAAY,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAA;AAC7E,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA"}

package/dist/forms/index.js

@@ -1,35 +1,19 @@
 import { useBasaltForm } from "./create-form.js";
 import { inputProps, fieldKey } from "./field.js";
-import {
-  FormSection,
-  FormRow,
-  FormGroup,
-  FormActions
-} from "../controls/form-layout.js";
 import { useFormSubmit, isFieldErrorEnvelope } from "./use-form-submit.js";
 import { FormStateProvider, useFormState } from "./form-state.js";
 import { useFieldArray } from "./use-field-array.js";
 import { FormErrorSummary } from "./FormErrorSummary.js";
 import { useFormDraft, DEFAULT_AUTOSAVE_DEBOUNCE_MS } from "./use-form-draft.js";
-import {
-  useForm,
-  schemaResolver
-} from "@mantine/form";
 export {
   DEFAULT_AUTOSAVE_DEBOUNCE_MS,
-  FormActions,
   FormErrorSummary,
-  FormGroup,
-  FormRow,
-  FormSection,
   FormStateProvider,
   fieldKey,
   inputProps,
   isFieldErrorEnvelope,
-  schemaResolver,
   useBasaltForm,
   useFieldArray,
-  useForm,
   useFormDraft,
   useFormState,
   useFormSubmit

package/dist/shell/app-brand.module.css

@@ -8,13 +8,15 @@
  *
  * The zone's WIDTH is `--app-shell-navbar-offset`, so it tracks the rail collapse with no React
  * state and lands its trailing edge exactly on the sidebar|main seam. The negative
- * `margin-inline-start` cancels `AppShell.Header`'s own `px` inset so the zone starts at the
- * viewport edge and re-applies that inset as padding — which is what puts the brand lead on the
- * same x as the sidebar's nav ICON column below it. The arithmetic, now that the page gutter is
- * `SPACE.appShellInset`: the zone re-applies `--app-shell-padding` = 20, and a nav icon sits at
- * 10px of `.root` frame inset plus 10px of NavLink inset (`rowInsetX`) = 20. One vertical line
- * across the seam — a claim this comment used to make while the gutter was 13, and that the
- * 13 -> 20 move made true.
+ * `margin-inline-start` cancels `AppShell.Header`'s own `px` inset (the page gutter,
+ * `--app-shell-padding`) so the zone starts at the viewport edge, and the zone's OWN inline padding
+ * is the sidebar's nav-icon column — 10px of `.root` frame inset plus 10px of NavLink inset, i.e.
+ * `row-inset-x` twice — which is what puts the brand lead on the same x as the nav ICON column below
+ * it. That padding used to BE the page gutter (`--app-shell-padding`, 20, the same number by
+ * coincidence); the gutter is 16 now, and the two are different claims, so each is stated on its
+ * own. The breadcrumb lands on Main's content edge: the zone's trailing margin is the gutter minus
+ * the header row's flex gap (`app-header.module.css`'s `--basalt-header-gap`), so zone end + margin
+ * + gap = seam + gutter.
  *
  * `--basalt-shell-lead-inset` (default 0px, set by the consumer on `:root`) is the opt-in native
  * title-bar contract: a macOS overlay title bar paints its traffic lights ON TOP of this zone, so a
@@ -30,6 +32,8 @@
    * `--ai-size-md` (1.75rem). Mantine defines that var on the ActionIcon, not on `:root`, so the
    * zone restates the same arithmetic; `app-brand.module.css.test.ts` pins the two together. */
   --basalt-shell-toggle-size: calc(1.75rem * var(--mantine-scale, 1));
+  /* The sidebar's nav-icon column: `.root` inset + NavLink inset, both `row-inset-x`. */
+  --basalt-nav-icon-x: calc(2 * var(--vx-space-row-inset-x));
   --basalt-shell-zone-width: max(
     var(--app-shell-navbar-offset, 0rem),
     calc(var(--basalt-shell-lead-inset, 0px) + var(--basalt-shell-toggle-size))
@@ -43,8 +47,9 @@
    * like, and the rail's centred toggle centres against the whole row. */
   align-self: stretch;
   margin-inline-start: calc(-1 * var(--app-shell-padding, 0px));
-  padding-inline: var(--app-shell-padding, 0px);
-  padding-inline-start: calc(var(--app-shell-padding, 0px) + var(--basalt-shell-lead-inset, 0px));
+  margin-inline-end: calc(var(--app-shell-padding, 0px) - var(--basalt-header-gap, 0px));
+  padding-inline: var(--basalt-nav-icon-x);
+  padding-inline-start: calc(var(--basalt-nav-icon-x) + var(--basalt-shell-lead-inset, 0px));
   overflow: hidden;
   /* Mantine's own AppShell timing, so the zone and the navbar under it move as one box. */
   transition-property: flex-basis, width;

package/dist/shell/app-header.module.css

@@ -17,9 +17,12 @@
  * `alt` — never a border in this module.
  */
 .bar {
+  /* Named so the leading zone (`app-brand.module.css`) can offset its trailing margin by exactly
+   * this gap and land the breadcrumb on Main's content edge. */
+  --basalt-header-gap: var(--mantine-spacing-sm);
   display: flex;
   align-items: center;
-  gap: var(--mantine-spacing-sm);
+  gap: var(--basalt-header-gap);
   width: 100%;
   height: 100%;
 }

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

@@ -97,13 +97,13 @@
    * value rather than an offset, because Mantine owns the responsive switch (`shell/index.tsx`
    * hands `AppShell` the `appShellInset`/`appShellInsetMobile` pair) and the header, the band and
    * Main all have to land on the SAME number — re-deriving it here would fork it. It is an
-   * ALIGNMENT constraint: 20 at `sm`+ puts the page's first column on the sidebar nav icon
-   * column's x across the seam (`app-brand.module.css` states that arithmetic).
+   * ALIGNMENT constraint: the header's breadcrumb and globals land on the same edges as the
+   * content (`app-brand.module.css` states the arithmetic).
    *
-   * Block is `stack-md` and is only breathing room under the band's single `--vx-divider` line —
-   * nothing aligns to it, so it has no business tracking a gutter that grew for an alignment
-   * reason. Holding it at 12 keeps the total chrome above the first card at ~97px (44 header + 40
-   * band + 1 seam + 12) — DOWN from 100 — even though the inline gutter grew 13 -> 20.
+   * Block is breathing room under the band's single `--vx-divider` line — nothing aligns to it.
+   * `stack-md` (12) on a phone, one rung down (`stack-sm`, 8) from `sm` up where the inline gutter
+   * is 16: the page then sits 16 from the seam and 8 under the header, rather than the 20/12 it
+   * used to.
    */
   padding: var(--vx-space-stack-md) var(--app-shell-padding);
   /* Without this a wide flex/grid child (a bare table, a nowrap control row) sizes Main to ITSELF. */
@@ -122,11 +122,17 @@
   transition-property: margin;
 }
 
+@media (min-width: 52.5em) {
+  .main {
+    padding-block: var(--vx-space-stack-sm);
+  }
+}
+
 /* Installed PWA (C5 consolidation, seeded from argo's `styles/native.css`): clear the landscape
  * notch on the side Main touches. `max()` is a FLOOR over the INLINE value of `.main`'s `padding`
  * shorthand above — same mechanism as `app-sidebar.module.css`'s left counterpart, and it still
  * floors correctly now that the shorthand is two axes and the inline one is responsive: this rule
- * reads the same `--app-shell-padding`, so the floor is against whichever of 20/8 is live, and on
+ * reads the same `--app-shell-padding`, so the floor is against whichever of 16/8 is live, and on
  * the phone half (8) it is doing MORE work than before, not less. It overrides only
  * `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

package/dist/shell/index.d.ts

@@ -144,6 +144,17 @@ export type BasaltShellProps = BasaltProps & {
      * a no-op when omitted.
      */
     onCollapsedChange?: (collapsed: boolean) => void;
+    /**
+     * The header row's height in px — default `SPACE_STEP.appShellHeaderHeight` (44, tracking the
+     * density level). ONE number at every width and in both sidebar forms (law C14): the navbar's and
+     * aside's top, the page-bar band, the aside's shell header and Main all derive from Mantine's
+     * `--app-shell-header-height`, so they follow it with no second value to keep in step. Brand,
+     * breadcrumb, page actions and globals centre vertically in the row. For a host that draws its
+     * own chrome into the header, e.g. a native macOS unified-toolbar title bar (~52): pair it with
+     * `--basalt-shell-lead-inset`. Keep it at or above the `ctl` control height (32) — the row holds
+     * one `ctl`-tier control.
+     */
+    headerHeight?: number;
     /** Page content. */
     children?: ReactNode;
 };

package/dist/shell/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shell/index.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shell/index.tsx"],"names":[],"mappings":"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"}

package/dist/shell/index.js

@@ -87,6 +87,7 @@ function ShellFrame({
   storageKey = "basalt-sidebar-collapsed",
   collapsed: collapsedProp,
   onCollapsedChange,
+  headerHeight,
   account,
   search,
   children,
@@ -146,7 +147,7 @@ function ShellFrame({
       h: "100dvh",
       header: {
         // ONE height at every width (law C14): nothing reserves a second mobile row any more.
-        height: step.appShellHeaderHeight
+        height: headerHeight ?? step.appShellHeaderHeight
       },
       navbar: {
         width: { base: step.appShellNavbarWidth, sm: navbarWidth },

package/dist/surfaces.d.ts

@@ -267,7 +267,7 @@ export declare const SURFACES: {
         readonly skill: readonly ["basalt-design"];
         readonly guardKinds: readonly [];
         readonly pluginRules: readonly ["forms-field-key"];
-        readonly description: "Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls — a spread `key` is a React 19 warning; the deprecated `field` alias for `inputProps` was removed in 1.29.0, C1 consolidation), useFormSubmit (submit state, decoded errors, server fieldErrors, focus-first-error, validateAsync), FormStateProvider disable propagation, useFieldArray, FormErrorSummary, useFormDraft with autosave (Standard Schema). The FormSection/FormRow/FormGroup/FormActions layout moved to ./controls in 1.36.0 and the useForm/schemaResolver re-exports are deprecated (import from @mantine/form); all six stay here until 1.37.0";
+        readonly description: "Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls — a spread `key` is a React 19 warning; the deprecated `field` alias for `inputProps` was removed in 1.29.0, C1 consolidation), useFormSubmit (submit state, decoded errors, server fieldErrors, focus-first-error, validateAsync), FormStateProvider disable propagation, useFieldArray, FormErrorSummary, useFormDraft with autosave (Standard Schema). The FormSection/FormRow/FormGroup/FormActions layout lives in ./controls (moved in 1.36.0) and useForm/schemaResolver come from @mantine/form; the six re-exports here were removed in 1.39.0";
         readonly optionalPeers: readonly ["@mantine/form"];
         readonly forbiddenImports: readonly [];
     };

package/dist/surfaces.js

@@ -243,7 +243,7 @@ const SURFACES = {
     // only stops resetting. `warn` through the 1.30.0 grace because it fires on what every
     // consumer ships today (`PLUGIN_RULE_GRACE`).
     pluginRules: ["forms-field-key"],
-    description: "Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls \u2014 a spread `key` is a React 19 warning; the deprecated `field` alias for `inputProps` was removed in 1.29.0, C1 consolidation), useFormSubmit (submit state, decoded errors, server fieldErrors, focus-first-error, validateAsync), FormStateProvider disable propagation, useFieldArray, FormErrorSummary, useFormDraft with autosave (Standard Schema). The FormSection/FormRow/FormGroup/FormActions layout moved to ./controls in 1.36.0 and the useForm/schemaResolver re-exports are deprecated (import from @mantine/form); all six stay here until 1.37.0",
+    description: "Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls \u2014 a spread `key` is a React 19 warning; the deprecated `field` alias for `inputProps` was removed in 1.29.0, C1 consolidation), useFormSubmit (submit state, decoded errors, server fieldErrors, focus-first-error, validateAsync), FormStateProvider disable propagation, useFieldArray, FormErrorSummary, useFormDraft with autosave (Standard Schema). The FormSection/FormRow/FormGroup/FormActions layout lives in ./controls (moved in 1.36.0) and useForm/schemaResolver come from @mantine/form; the six re-exports here were removed in 1.39.0",
     optionalPeers: ["@mantine/form"],
     forbiddenImports: []
   },

package/dist/tokens/palette.d.ts

@@ -502,6 +502,8 @@ declare const SPACE_STEP_BASE: {
      *  folds that row's overflow into a kebab and moves its filters/tabs into the page flow, so the
      *  bar is one row on a phone too and there is no sum to keep in step any more.
      *
+     *  Consumer-settable per shell through `BasaltShell`'s `headerHeight` (px); this is its default.
+     *
      *  44, down from 48. The band holds ONE `ctl`-tier row (32 since this pass), so 48 left 8px of
      *  dead air above and below it — the "too much spacing at the top bar" the header reads as. 44
      *  keeps 6px of breathing room a side, still clears `controlHeight` (42) for a `size="md"`
@@ -541,13 +543,13 @@ declare const SPACE_STEP_BASE: {
      *  `tokens/index.ts` for why), because it is the single most visible spacing number the framework
      *  ships and a consumer retuning its identity has to be able to reach it.
      *
-     *  20, up from the 13 (`SPACE_SCALE.sm`) the main column used to borrow. The sidebar's nav ICON
-     *  column already sits at x=20 — 10px of `.root` frame inset plus 10px of NavLink inset
-     *  (`rowInsetX`) — and the brand row claims to align with it while sitting at 13. 20 makes that
-     *  claim true across the seam: brand mark, nav icons and the page's first column all start on one
-     *  vertical line, and the content gets a seam-side gutter that reads deliberate instead of
-     *  incidental. */
-    readonly appShellInset: 20;
+     *  16, down from 20 (and from the 13 `SPACE_SCALE.sm` the main column borrowed before that): at 20
+     *  the content read as pushed away from the seam. 16 sits on the 4px grid. It is NOT the sidebar's
+     *  nav-icon column any more (x=20: 10px of `.root` frame inset plus 10px of NavLink inset,
+     *  `rowInsetX` twice) — the header's brand zone aligns to that column on its own
+     *  (`shell/app-brand.module.css`), so the page gutter is free to be a gutter. The header's
+     *  breadcrumb, the page-bar band and Main all land on this one number. */
+    readonly appShellInset: 16;
     /** The page gutter BELOW `sm` — the phone half of `appShellInset` above. A separate entry rather
      *  than one responsive value for the same reason `appShellNavbarWidth` is one: there is no sidebar
      *  seam to align to on a phone, so the number is answering a different question (how much of a

package/dist/tokens/palette.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"palette.d.ts","sourceRoot":"","sources":["../../src/tokens/palette.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"palette.d.ts","sourceRoot":"","sources":["../../src/tokens/palette.ts"],"names":[],"mappings":"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"}

package/dist/tokens/palette.js

@@ -414,6 +414,8 @@ const SPACE_STEP_BASE = {
    *  folds that row's overflow into a kebab and moves its filters/tabs into the page flow, so the
    *  bar is one row on a phone too and there is no sum to keep in step any more.
    *
+   *  Consumer-settable per shell through `BasaltShell`'s `headerHeight` (px); this is its default.
+   *
    *  44, down from 48. The band holds ONE `ctl`-tier row (32 since this pass), so 48 left 8px of
    *  dead air above and below it — the "too much spacing at the top bar" the header reads as. 44
    *  keeps 6px of breathing room a side, still clears `controlHeight` (42) for a `size="md"`
@@ -453,13 +455,13 @@ const SPACE_STEP_BASE = {
    *  `tokens/index.ts` for why), because it is the single most visible spacing number the framework
    *  ships and a consumer retuning its identity has to be able to reach it.
    *
-   *  20, up from the 13 (`SPACE_SCALE.sm`) the main column used to borrow. The sidebar's nav ICON
-   *  column already sits at x=20 — 10px of `.root` frame inset plus 10px of NavLink inset
-   *  (`rowInsetX`) — and the brand row claims to align with it while sitting at 13. 20 makes that
-   *  claim true across the seam: brand mark, nav icons and the page's first column all start on one
-   *  vertical line, and the content gets a seam-side gutter that reads deliberate instead of
-   *  incidental. */
-  appShellInset: 20,
+   *  16, down from 20 (and from the 13 `SPACE_SCALE.sm` the main column borrowed before that): at 20
+   *  the content read as pushed away from the seam. 16 sits on the 4px grid. It is NOT the sidebar's
+   *  nav-icon column any more (x=20: 10px of `.root` frame inset plus 10px of NavLink inset,
+   *  `rowInsetX` twice) — the header's brand zone aligns to that column on its own
+   *  (`shell/app-brand.module.css`), so the page gutter is free to be a gutter. The header's
+   *  breadcrumb, the page-bar band and Main all land on this one number. */
+  appShellInset: 16,
   /** The page gutter BELOW `sm` — the phone half of `appShellInset` above. A separate entry rather
    *  than one responsive value for the same reason `appShellNavbarWidth` is one: there is no sidebar
    *  seam to align to on a phone, so the number is answering a different question (how much of a

package/dist/tokens.css

@@ -95,7 +95,7 @@
   --vx-space-sidebar-child-list-indent: 15px;
   --vx-space-sidebar-child-row-inset-y: 4px;
   --vx-space-sidebar-child-row-indent: 12px;
-  --vx-space-app-shell-inset: 20px;
+  --vx-space-app-shell-inset: 16px;
   --vx-space-app-shell-inset-mobile: 8px;
   --vx-space-app-shell-header-lead-min: 96px;
   --vx-space-mobile-nav-tab-gap: 3px;

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.38.0
+# basalt-ui v1.39.0
 # Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets
 #
 # basalt-ui is an opinionated framework for Mantine-based React apps.
@@ -19,7 +19,7 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.38.0
+Version: 1.39.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'
@@ -70,7 +70,7 @@ OptionalPeers: @tanstack/react-router@^1.170.0
 
 ## basalt-ui/forms
 Import: import { ... } from 'basalt-ui/forms'
-Description: Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls — a spread `key` is a React 19 warning; the deprecated `field` alias for `inputProps` was removed in 1.29.0, C1 consolidation), useFormSubmit (submit state, decoded errors, server fieldErrors, focus-first-error, validateAsync), FormStateProvider disable propagation, useFieldArray, FormErrorSummary, useFormDraft with autosave (Standard Schema). The FormSection/FormRow/FormGroup/FormActions layout moved to ./controls in 1.36.0 and the useForm/schemaResolver re-exports are deprecated (import from @mantine/form); all six stay here until 1.37.0
+Description: Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls — a spread `key` is a React 19 warning; the deprecated `field` alias for `inputProps` was removed in 1.29.0, C1 consolidation), useFormSubmit (submit state, decoded errors, server fieldErrors, focus-first-error, validateAsync), FormStateProvider disable propagation, useFieldArray, FormErrorSummary, useFormDraft with autosave (Standard Schema). The FormSection/FormRow/FormGroup/FormActions layout lives in ./controls (moved in 1.36.0) and useForm/schemaResolver come from @mantine/form; the six re-exports here were removed in 1.39.0
 Layer: mantine-coupled
 Rule: basalt-batteries
 OptionalPeers: @mantine/form@^9.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "1.38.0",
+  "version": "1.39.0",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets",
   "keywords": [
     "charts",

package/src/forms/index.ts

@@ -8,10 +8,9 @@
  *
  * Four pieces: the form (`useBasaltForm` + `inputProps`/`fieldKey`), the submit lifecycle
  * (`useFormSubmit` + `FormStateProvider`), the list field (`useFieldArray`) and the draft
- * (`useFormDraft`). The layout (`FormSection` / `FormRow` / `FormGroup` / `FormActions`) moved to
- * `basalt-ui/controls` in 1.36.0 — it needs no `@mantine/form` — and stays here as deprecated
- * aliases until 1.39.0, as do the `useForm`/`schemaResolver` re-exports (import from
- * `@mantine/form`).
+ * (`useFormDraft`). The layout (`FormSection` / `FormRow` / `FormGroup` / `FormActions`) lives in
+ * `basalt-ui/controls` (it needs no `@mantine/form`); `useForm`/`schemaResolver` come from
+ * `@mantine/form` directly. Both stopped being re-exported here in 1.39.0.
  *
  * Optional peer: @mantine/form ^9.3.0 — install with: bun add @mantine/form
  */
@@ -24,32 +23,6 @@ export type { UseBasaltFormOptions } from './create-form'
 // Two calls, never one object: `key` inside a spread is a React 19 warning. See field.ts.
 export { inputProps, fieldKey } from './field'
 
-// ── layout — moved to ./controls (1.36.0), deprecated aliases until 1.39.0 ─────
-export {
-  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
-  FormSection,
-  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
-  FormRow,
-  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
-  FormGroup,
-  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
-  FormActions,
-} from '../controls/form-layout'
-export type {
-  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
-  FormSectionProps,
-  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
-  FormSectionSlot,
-  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
-  FormRowProps,
-  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
-  FormRowSlot,
-  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
-  FormGroupProps,
-  /** @deprecated Import from 'basalt-ui/controls' — removed in 1.39.0. */
-  FormActionsProps,
-} from '../controls/form-layout'
-
 // ── submit lifecycle ──────────────────────────────────────────────────────────
 export { useFormSubmit, isFieldErrorEnvelope } from './use-form-submit'
 export type { FormFieldErrors, UseFormSubmitOptions, UseFormSubmitReturn } from './use-form-submit'
@@ -67,17 +40,3 @@ export type { FormErrorSummaryProps } from './FormErrorSummary'
 // ── useFormDraft ──────────────────────────────────────────────────────────────
 export { useFormDraft, DEFAULT_AUTOSAVE_DEBOUNCE_MS } from './use-form-draft'
 export type { UseFormDraftOptions, UseFormDraftReturn } from './use-form-draft'
-
-// ── @mantine/form re-exports — deprecated, zero consumers import them from here ──
-export {
-  /** @deprecated Import from '@mantine/form' — removed in 1.39.0. */
-  useForm,
-  /** @deprecated Import from '@mantine/form' — removed in 1.39.0. */
-  schemaResolver,
-} from '@mantine/form'
-export type {
-  /** @deprecated Import from '@mantine/form' — removed in 1.39.0. */
-  UseFormReturnType,
-  /** @deprecated Import from '@mantine/form' — removed in 1.39.0. */
-  UseFormInput,
-} from '@mantine/form'

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

@@ -8,13 +8,15 @@
  *
  * The zone's WIDTH is `--app-shell-navbar-offset`, so it tracks the rail collapse with no React
  * state and lands its trailing edge exactly on the sidebar|main seam. The negative
- * `margin-inline-start` cancels `AppShell.Header`'s own `px` inset so the zone starts at the
- * viewport edge and re-applies that inset as padding — which is what puts the brand lead on the
- * same x as the sidebar's nav ICON column below it. The arithmetic, now that the page gutter is
- * `SPACE.appShellInset`: the zone re-applies `--app-shell-padding` = 20, and a nav icon sits at
- * 10px of `.root` frame inset plus 10px of NavLink inset (`rowInsetX`) = 20. One vertical line
- * across the seam — a claim this comment used to make while the gutter was 13, and that the
- * 13 -> 20 move made true.
+ * `margin-inline-start` cancels `AppShell.Header`'s own `px` inset (the page gutter,
+ * `--app-shell-padding`) so the zone starts at the viewport edge, and the zone's OWN inline padding
+ * is the sidebar's nav-icon column — 10px of `.root` frame inset plus 10px of NavLink inset, i.e.
+ * `row-inset-x` twice — which is what puts the brand lead on the same x as the nav ICON column below
+ * it. That padding used to BE the page gutter (`--app-shell-padding`, 20, the same number by
+ * coincidence); the gutter is 16 now, and the two are different claims, so each is stated on its
+ * own. The breadcrumb lands on Main's content edge: the zone's trailing margin is the gutter minus
+ * the header row's flex gap (`app-header.module.css`'s `--basalt-header-gap`), so zone end + margin
+ * + gap = seam + gutter.
  *
  * `--basalt-shell-lead-inset` (default 0px, set by the consumer on `:root`) is the opt-in native
  * title-bar contract: a macOS overlay title bar paints its traffic lights ON TOP of this zone, so a
@@ -30,6 +32,8 @@
    * `--ai-size-md` (1.75rem). Mantine defines that var on the ActionIcon, not on `:root`, so the
    * zone restates the same arithmetic; `app-brand.module.css.test.ts` pins the two together. */
   --basalt-shell-toggle-size: calc(1.75rem * var(--mantine-scale, 1));
+  /* The sidebar's nav-icon column: `.root` inset + NavLink inset, both `row-inset-x`. */
+  --basalt-nav-icon-x: calc(2 * var(--vx-space-row-inset-x));
   --basalt-shell-zone-width: max(
     var(--app-shell-navbar-offset, 0rem),
     calc(var(--basalt-shell-lead-inset, 0px) + var(--basalt-shell-toggle-size))
@@ -43,8 +47,9 @@
    * like, and the rail's centred toggle centres against the whole row. */
   align-self: stretch;
   margin-inline-start: calc(-1 * var(--app-shell-padding, 0px));
-  padding-inline: var(--app-shell-padding, 0px);
-  padding-inline-start: calc(var(--app-shell-padding, 0px) + var(--basalt-shell-lead-inset, 0px));
+  margin-inline-end: calc(var(--app-shell-padding, 0px) - var(--basalt-header-gap, 0px));
+  padding-inline: var(--basalt-nav-icon-x);
+  padding-inline-start: calc(var(--basalt-nav-icon-x) + var(--basalt-shell-lead-inset, 0px));
   overflow: hidden;
   /* Mantine's own AppShell timing, so the zone and the navbar under it move as one box. */
   transition-property: flex-basis, width;

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

@@ -17,9 +17,12 @@
  * `alt` — never a border in this module.
  */
 .bar {
+  /* Named so the leading zone (`app-brand.module.css`) can offset its trailing margin by exactly
+   * this gap and land the breadcrumb on Main's content edge. */
+  --basalt-header-gap: var(--mantine-spacing-sm);
   display: flex;
   align-items: center;
-  gap: var(--mantine-spacing-sm);
+  gap: var(--basalt-header-gap);
   width: 100%;
   height: 100%;
 }

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

@@ -97,13 +97,13 @@
    * value rather than an offset, because Mantine owns the responsive switch (`shell/index.tsx`
    * hands `AppShell` the `appShellInset`/`appShellInsetMobile` pair) and the header, the band and
    * Main all have to land on the SAME number — re-deriving it here would fork it. It is an
-   * ALIGNMENT constraint: 20 at `sm`+ puts the page's first column on the sidebar nav icon
-   * column's x across the seam (`app-brand.module.css` states that arithmetic).
+   * ALIGNMENT constraint: the header's breadcrumb and globals land on the same edges as the
+   * content (`app-brand.module.css` states the arithmetic).
    *
-   * Block is `stack-md` and is only breathing room under the band's single `--vx-divider` line —
-   * nothing aligns to it, so it has no business tracking a gutter that grew for an alignment
-   * reason. Holding it at 12 keeps the total chrome above the first card at ~97px (44 header + 40
-   * band + 1 seam + 12) — DOWN from 100 — even though the inline gutter grew 13 -> 20.
+   * Block is breathing room under the band's single `--vx-divider` line — nothing aligns to it.
+   * `stack-md` (12) on a phone, one rung down (`stack-sm`, 8) from `sm` up where the inline gutter
+   * is 16: the page then sits 16 from the seam and 8 under the header, rather than the 20/12 it
+   * used to.
    */
   padding: var(--vx-space-stack-md) var(--app-shell-padding);
   /* Without this a wide flex/grid child (a bare table, a nowrap control row) sizes Main to ITSELF. */
@@ -122,11 +122,17 @@
   transition-property: margin;
 }
 
+@media (min-width: 52.5em) {
+  .main {
+    padding-block: var(--vx-space-stack-sm);
+  }
+}
+
 /* Installed PWA (C5 consolidation, seeded from argo's `styles/native.css`): clear the landscape
  * notch on the side Main touches. `max()` is a FLOOR over the INLINE value of `.main`'s `padding`
  * shorthand above — same mechanism as `app-sidebar.module.css`'s left counterpart, and it still
  * floors correctly now that the shorthand is two axes and the inline one is responsive: this rule
- * reads the same `--app-shell-padding`, so the floor is against whichever of 20/8 is live, and on
+ * reads the same `--app-shell-padding`, so the floor is against whichever of 16/8 is live, and on
  * the phone half (8) it is doing MORE work than before, not less. It overrides only
  * `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

package/src/shell/index.tsx

@@ -232,6 +232,17 @@ export type BasaltShellProps = BasaltProps & {
    * a no-op when omitted.
    */
   onCollapsedChange?: (collapsed: boolean) => void
+  /**
+   * The header row's height in px — default `SPACE_STEP.appShellHeaderHeight` (44, tracking the
+   * density level). ONE number at every width and in both sidebar forms (law C14): the navbar's and
+   * aside's top, the page-bar band, the aside's shell header and Main all derive from Mantine's
+   * `--app-shell-header-height`, so they follow it with no second value to keep in step. Brand,
+   * breadcrumb, page actions and globals centre vertically in the row. For a host that draws its
+   * own chrome into the header, e.g. a native macOS unified-toolbar title bar (~52): pair it with
+   * `--basalt-shell-lead-inset`. Keep it at or above the `ctl` control height (32) — the row holds
+   * one `ctl`-tier control.
+   */
+  headerHeight?: number
   /** Page content. */
   children?: ReactNode
 }
@@ -349,6 +360,7 @@ function ShellFrame({
   storageKey = 'basalt-sidebar-collapsed',
   collapsed: collapsedProp,
   onCollapsedChange,
+  headerHeight,
   account,
   search,
   children,
@@ -466,7 +478,7 @@ function ShellFrame({
         // 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,
+          height: headerHeight ?? step.appShellHeaderHeight,
         }}
         navbar={{
           width: { base: step.appShellNavbarWidth, sm: navbarWidth },

package/src/surfaces.ts

@@ -443,7 +443,7 @@ export const SURFACES = {
     // consumer ships today (`PLUGIN_RULE_GRACE`).
     pluginRules: ['forms-field-key'],
     description:
-      'Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls — a spread `key` is a React 19 warning; the deprecated `field` alias for `inputProps` was removed in 1.29.0, C1 consolidation), useFormSubmit (submit state, decoded errors, server fieldErrors, focus-first-error, validateAsync), FormStateProvider disable propagation, useFieldArray, FormErrorSummary, useFormDraft with autosave (Standard Schema). The FormSection/FormRow/FormGroup/FormActions layout moved to ./controls in 1.36.0 and the useForm/schemaResolver re-exports are deprecated (import from @mantine/form); all six stay here until 1.37.0',
+      'Mantine form layer: useBasaltForm + inputProps/fieldKey (two calls — a spread `key` is a React 19 warning; the deprecated `field` alias for `inputProps` was removed in 1.29.0, C1 consolidation), useFormSubmit (submit state, decoded errors, server fieldErrors, focus-first-error, validateAsync), FormStateProvider disable propagation, useFieldArray, FormErrorSummary, useFormDraft with autosave (Standard Schema). The FormSection/FormRow/FormGroup/FormActions layout lives in ./controls (moved in 1.36.0) and useForm/schemaResolver come from @mantine/form; the six re-exports here were removed in 1.39.0',
     optionalPeers: ['@mantine/form'],
     forbiddenImports: [],
   },

package/src/tokens/palette.ts

@@ -611,6 +611,8 @@ const SPACE_STEP_BASE = {
    *  folds that row's overflow into a kebab and moves its filters/tabs into the page flow, so the
    *  bar is one row on a phone too and there is no sum to keep in step any more.
    *
+   *  Consumer-settable per shell through `BasaltShell`'s `headerHeight` (px); this is its default.
+   *
    *  44, down from 48. The band holds ONE `ctl`-tier row (32 since this pass), so 48 left 8px of
    *  dead air above and below it — the "too much spacing at the top bar" the header reads as. 44
    *  keeps 6px of breathing room a side, still clears `controlHeight` (42) for a `size="md"`
@@ -650,13 +652,13 @@ const SPACE_STEP_BASE = {
    *  `tokens/index.ts` for why), because it is the single most visible spacing number the framework
    *  ships and a consumer retuning its identity has to be able to reach it.
    *
-   *  20, up from the 13 (`SPACE_SCALE.sm`) the main column used to borrow. The sidebar's nav ICON
-   *  column already sits at x=20 — 10px of `.root` frame inset plus 10px of NavLink inset
-   *  (`rowInsetX`) — and the brand row claims to align with it while sitting at 13. 20 makes that
-   *  claim true across the seam: brand mark, nav icons and the page's first column all start on one
-   *  vertical line, and the content gets a seam-side gutter that reads deliberate instead of
-   *  incidental. */
-  appShellInset: 20,
+   *  16, down from 20 (and from the 13 `SPACE_SCALE.sm` the main column borrowed before that): at 20
+   *  the content read as pushed away from the seam. 16 sits on the 4px grid. It is NOT the sidebar's
+   *  nav-icon column any more (x=20: 10px of `.root` frame inset plus 10px of NavLink inset,
+   *  `rowInsetX` twice) — the header's brand zone aligns to that column on its own
+   *  (`shell/app-brand.module.css`), so the page gutter is free to be a gutter. The header's
+   *  breadcrumb, the page-bar band and Main all land on this one number. */
+  appShellInset: 16,
   /** The page gutter BELOW `sm` — the phone half of `appShellInset` above. A separate entry rather
    *  than one responsive value for the same reason `appShellNavbarWidth` is one: there is no sidebar
    *  seam to align to on a phone, so the number is answering a different question (how much of a