basalt-ui 1.29.2 → 1.30.1

package/src/dashboard/widget-grid.tsx

@@ -14,6 +14,14 @@
  * deliberately NOT forwarded — a responsive object on the public prop is exactly the seam that let
  * five call sites disagree.
  *
+ * **The law keys on the CONTAINER, not the viewport.** `WidgetGrid` renders its own
+ * `container-type: inline-size` box around the grid, so the counts follow the width the grid
+ * ACTUALLY has. The shell moves that width without moving the viewport — a `PageAside` claiming its
+ * 300px, the sidebar collapsing 256px → its 48px rail, a consumer's split pane — and a `@media`
+ * query sees none of it: it kept three chart columns in a 956px content box and every chart in the
+ * row went narrower than `VX.phoneChartWidth`, which is the exact condition the `lg` rung exists to
+ * avoid. See `widget-grid.module.css`'s header for the fallback.
+ *
  * **This is the sanctioned place `lg` enters the package.** `sm` is still the only breakpoint a
  * consumer writes (`docs/CONTROLS-SPEC.md` §2); `WidgetGrid` and `StatGroup` own `lg` internally so
  * nobody else has to.
@@ -77,18 +85,28 @@ export function WidgetGrid({ cols = 2, children, className, style }: WidgetGridP
 
   return (
     <WidgetGridColsContext.Provider value={resolved}>
-      <div
-        className={cx(classes.root, className)}
-        data-cols={cols}
-        style={
-          {
-            '--basalt-widget-grid-cols-sm': resolved.sm,
-            '--basalt-widget-grid-cols-lg': resolved.lg,
-            ...style,
-          } as CSSProperties
-        }
-      >
-        {children}
+      {/*
+        Two boxes, and the outer one is not decoration: a size container is a container for its
+        DESCENDANTS, never for itself, so the grid whose tracks the query decides has to sit inside
+        the box being measured. `className`/`style` land on the OUTER box because that is the root
+        element a consumer positions (`BasaltProps`) — and because measuring the box the consumer
+        sized is the whole point. `container-type: inline-size` contains the inline axis only, so
+        the wrapper's block size still comes from the grid: percentage heights resolve exactly as
+        before, and there is no paint containment, so nothing inside is clipped.
+      */}
+      <div className={cx(classes.container, className)} style={style}>
+        <div
+          className={classes.root}
+          data-cols={cols}
+          style={
+            {
+              '--basalt-widget-grid-cols-sm': resolved.sm,
+              '--basalt-widget-grid-cols-lg': resolved.lg,
+            } as CSSProperties
+          }
+        >
+          {children}
+        </div>
       </div>
     </WidgetGridColsContext.Provider>
   )

package/src/guard/index.ts

@@ -517,6 +517,33 @@ const PAGE_TITLE_TAG = /<Title(?![\w.])(?:=>|[^>])*?>/g
 /** `order={1}` / `order={2}` — the two orders that name a PAGE rather than a section. */
 const PAGE_TITLE_ORDER_PROP = /\border\s*=\s*\{\s*([12])\s*\}/
 
+/**
+ * The text-lane twin of the plugin's `hasStaticTitleText`: does the body between `<Title …>` and
+ * `</Title>` spell a NAME out, or render a value?
+ *
+ * The law is "one NAME per page", and a name is written in words — so a `<Title order={1}>{
+ * knot.title}</Title>` on a nav-less detail route, and a card's hero value
+ * `<Title order={2}>{RANK_LABEL[rank]}</Title>`, are data rather than a second page name and stop
+ * reporting in BOTH lanes. Kept in step with the plugin deliberately: the two share one id, so one
+ * `theme-allow` covers both and they must not disagree about what they cover.
+ *
+ * Text-lane approximation, and the direction of its error is the safe one: everything outside the
+ * outermost `{…}` runs is stripped of braces' contents and what remains has to be blank. A
+ * LAUNDERED literal (`{'Users'}`, a substitution-free template) is read as the text it is, so the
+ * escape is the expression, not the braces.
+ */
+const PAGE_TITLE_BRACED_RUN = /\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}/g
+const PAGE_TITLE_LAUNDERED_LITERAL = /^\s*['"`][^'"`]*['"`]\s*$/
+
+function titleBodyNamesThePage(body: string): boolean {
+  let outsideBraces = body
+  for (const braced of body.match(PAGE_TITLE_BRACED_RUN) ?? []) {
+    if (PAGE_TITLE_LAUNDERED_LITERAL.test(braced.slice(1, -1))) return true
+    outsideBraces = outsideBraces.replace(braced, '')
+  }
+  return outsideBraces.replace(/<[^>]*>/g, '').trim() !== ''
+}
+
 /**
  * A raw Mantine selection control's opening tag — the text-lane twin of the oxlint plugin's
  * RAW_FILTER_TAGS. `Chip.Group` carries a dot, so the name class allows one.
@@ -713,19 +740,22 @@ export type GraceEntry = { since: string; promote: string; why: string }
 export const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, GraceEntry>> = {
   'raw-selection-control': {
     since: '1.26.0',
-    promote: '1.30.0',
+    promote: '1.31.0',
     why:
       'new in the wave-6 control guards (docs/CONTROLS-SPEC.md §6, law C1). The text lane cannot ' +
       'see ancestry, so "no home" is approximated by a 12-line host-tag window — the loosest ' +
       'reading in the guard, and the reason this one lands warn rather than error even though its ' +
-      'law is settled. It moved from 1.27.0 to 1.30.0 with its AST twin, `basalt/control-outside-' +
-      'home`, whose PLUGIN_RULE_GRACE entry carries the measurement: the wave-7 run left 9 warns ' +
-      'in argo, all of them a control in a modal/form module whose `<Modal>` is rendered by the ' +
-      'PARENT — law C1 cross-file, which neither lane can see. `isOverlayConventionFile` (this ' +
-      'file, and the same regex in the plugin) exempts that declared naming convention in both ' +
-      'lanes. Re-dated 2026-08-28 — the argo wave-7 migration has not run; the PascalCase overlay ' +
-      'convention (this change) is expected to clear most of the 9. 1.30.0 is when the remainder ' +
-      'is re-measured. One law, two lanes, one promotion.',
+      'law is settled. ONE LAW, TWO LANES, ONE PROMOTION: it moves with its AST twin, ' +
+      '`basalt/control-outside-home`, whose PLUGIN_RULE_GRACE entry carries the full argument and ' +
+      'the measurement, and it must never be promoted or extended alone — a consumer waiving one ' +
+      'spelling and failing the other is the exact confusion `WAIVER_ID_ALIASES` exists to close. ' +
+      'RE-MEASURED 2026-09-09 across the whole fleet on 1.29.2: 29 AST-lane incumbents in five ' +
+      "repos, plus three of basalt's own (data-table, notifications/center, theme-lab). Extended " +
+      'to 1.31.0 because 1.30.0 is the FIRST release in which either lane names a home a ' +
+      'provider-only consumer can reach — every home both messages listed was a shell slot, and ' +
+      'the shell-less `PageBar` sentence ships in this minor. Promoting in the same minor that ' +
+      'makes a rule satisfiable gives nobody a window to act. 1.31.0 is when the 29 are ' +
+      're-measured against that number.',
   },
 }
 
@@ -940,6 +970,27 @@ export const PLUGIN_RULE_IDS: ReadonlySet<string> = new Set([
   'query-dual-import',
 ])
 
+/**
+ * ONE LAW, TWO RULE IDS — the ids that waive each other, in BOTH directions.
+ *
+ * `raw-selection-control` (this lane) and `basalt/control-outside-home` (the oxlint plugin) are the
+ * same law read by two engines, and this lane's own message already says so. They keep separate ids
+ * because the two engines disagree often enough that a consumer needs to be able to name which one
+ * they are waiving — but a consumer waiving the LAW should not have to know that, and before this
+ * map they did: `theme-allow control-outside-home` parsed here (the plugin's ids are all known,
+ * see {@link PLUGIN_RULE_IDS}) and then covered nothing, so the only working annotation was
+ * `theme-allow raw-selection-control control-outside-home` — two ids, undocumented, one silent
+ * debug cycle per consumer. `in-body-page-title` needs no entry: it is one id in both lanes.
+ *
+ * Mirrored VERBATIM in `configs/oxlint-plugin.js` (which cannot import from this package — see its
+ * header); `check-source.test.ts` asserts the two agree. An alias only ever WIDENS what an
+ * annotation covers, so a waiver can never become stricter by being spelled the other way.
+ */
+export const WAIVER_ID_ALIASES: Readonly<Record<string, readonly string[]>> = {
+  'control-outside-home': ['raw-selection-control'],
+  'raw-selection-control': ['control-outside-home'],
+}
+
 /** The shortest string accepted as a written reason — enough to exclude a stray separator. */
 const MIN_ALLOW_REASON_LENGTH = 4
 
@@ -1346,6 +1397,7 @@ function collectAllowAnnotations(
  */
 function annotationCovers(annotation: AllowAnnotation, kind: GuardKind): boolean {
   if (annotation.rules.includes(kind)) return true
+  if ((WAIVER_ID_ALIASES[kind] ?? []).some((alias) => annotation.rules.includes(alias))) return true
   if (annotation.scope === 'file') return false
   return annotation.rules.length === 0 && annotation.unknownRules.length === 0
 }
@@ -1998,7 +2050,7 @@ export const GUARD_RULES = {
     // JSX-tag-shaped (`<Title order={1}>`) — never appears in CSS text.
     appliesTo: (relPath) => !relPath.endsWith('.css'),
     message:
-      'In-body page title — a page is named ONCE, by the breadcrumb (staticData.title) or by PageBar.title in a shell-less app, and every section/card/table title is a WidgetHeader (docs/CONTROLS-SPEC.md law C8). An <Title order={1|2}> in the body is a second name for the same page, and it drifts. Prose / ArticleLayout / an overlay and anything under a content/ path are document headings and never report. Same law the oxlint plugin enforces as basalt/in-body-page-title — one id, two lanes, so one theme-allow covers both.',
+      'In-body page title — a page is named ONCE: by the breadcrumb (staticData.title), by PageBar.title, or by <PageTitle> on a shell-less surface (a route error, an auth gate, a standalone screen). Every section/card/table title is a WidgetHeader (docs/CONTROLS-SPEC.md law C8). An <Title order={1|2}> spelling a name out in the body is a second name for the same page, and it drifts. A Title rendering a VALUE — {doc.title}, {RANK_LABEL[rank]} — never reports: that is data, not a name. Prose / ArticleLayout / an overlay and anything under a content/ path never report either. Same law the oxlint plugin enforces as basalt/in-body-page-title — one id, two lanes, so one theme-allow covers both.',
   },
   'raw-selection-control': {
     kind: 'raw-selection-control',
@@ -2006,7 +2058,7 @@ export const GUARD_RULES = {
     // JSX-tag-shaped (`<Select …>`) — never appears in CSS text.
     appliesTo: (relPath) => !relPath.endsWith('.css'),
     message:
-      'Raw selection control with no home — a filter or tab belongs in a PageBar / Section / WidgetHeader slot and takes a `field` (a FieldHandle), so it owns the URL write and the localStorage mirror instead of carrying value/onChange (docs/CONTROLS-SPEC.md laws C1–C3). Use the bound control from basalt-ui/controls. A settings row, an overlay and an @mantine/form file are the declared non-homes and never report. This is the TEXT lane of basalt/control-outside-home, which answers the same question against the real AST — where the two disagree, the plugin is right.',
+      'Raw selection control with no home — a filter or tab belongs in a PageBar / Section / WidgetHeader slot and takes a `field` (a FieldHandle), so it owns the URL write and the localStorage mirror instead of carrying value/onChange (docs/CONTROLS-SPEC.md laws C1–C3). Use the bound control from basalt-ui/controls. A settings row, an overlay and an @mantine/form file are the declared non-homes and never report. No shell? PageBar needs no BasaltShell: outside one it renders in flow, sticky, with its own title — so its slots are a reachable home for a provider-only app. This is the TEXT lane of basalt/control-outside-home, which answers the same question against the real AST — where the two disagree, the plugin is right.',
   },
   'inline-font-size': {
     kind: 'inline-font-size',
@@ -2125,6 +2177,12 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
   for (const annotation of fileScoped) {
     for (const rule of annotation.rules) {
       if (Object.hasOwn(GUARD_RULES, rule)) fileWaived.add(rule as GuardKind)
+      // The plugin-id spelling of a shared law reaches file scope too — a `theme-allow-file
+      // control-outside-home — <why>` names a rule this lane knows under another id, and honouring
+      // it on one lane only is the same silent half-application the line scope had.
+      for (const alias of WAIVER_ID_ALIASES[rule] ?? []) {
+        if (Object.hasOwn(GUARD_RULES, alias)) fileWaived.add(alias as GuardKind)
+      }
     }
   }
 
@@ -2432,6 +2490,16 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
     for (const m of codeText.matchAll(PAGE_TITLE_TAG)) {
       const order = PAGE_TITLE_ORDER_PROP.exec(m[0])
       if (order === null) continue
+      // A self-closing `<Title order={1} />` renders no name at all, so it never reports — and the
+      // test has to be explicit rather than fall out of the body scan, which would otherwise run to
+      // the NEXT `</Title>` in the file and judge unrelated code. The plugin agrees by construction
+      // (an element with no children has no static text), and one id must not mean two verdicts.
+      if (m[0].endsWith('/>')) continue
+      const bodyStart = (m.index ?? 0) + m[0].length
+      const closeAt = codeText.indexOf('</Title>', bodyStart)
+      // No closing tag at all: no body to judge, so nothing names the page. See below for what a
+      // body has to hold before this kind reports.
+      if (closeAt === -1 || !titleBodyNamesThePage(codeText.slice(bodyStart, closeAt))) continue
       const startLine = codeText.slice(0, m.index ?? 0).split('\n').length
       const endLine = startLine + (m[0].split('\n').length - 1)
       if (isAllowedInRange(startLine, endLine, 'in-body-page-title')) continue

package/src/index.ts

@@ -37,6 +37,15 @@ export { createBasaltTheme, baseTheme, cssVariablesResolver } from './theme'
 export type { BasaltFontsConfig, CreateBasaltThemeOptions } from './theme'
 export { CTL_THEME, CtlSlot } from './theme'
 export type { CtlSlotProps } from './theme'
+/**
+ * The ACTIVE resolved spacing off the running theme, not the frozen level-0 `SPACE`/`SPACE_STEP`
+ * snapshot on `basalt-ui/tokens`. Public because a consumer laying out ITS OWN chrome beside the
+ * shell's (a sticky sub-header under the app header, a fixed rail beside the navbar) has to hit the
+ * same rhythm the shell resolved, and every one of those numbers is JS-consumed — an AppShell
+ * dimension or a `<Menu width={…}>` — so there is no `--vx-*` var to read it from instead. See
+ * `theme/use-basalt-spacing.ts` for the level-0 fallback contract.
+ */
+export { useBasaltSpacing } from './theme'
 export { ThemeToggle, type ThemeToggleProps } from './theme/theme-toggle'
 /**
  * The action vocabulary every home's `actions` slot takes (`docs/CONTROLS-SPEC.md` §2.1). The

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

@@ -10,7 +10,11 @@
  * 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 rows below it.
+ * 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.
  */
 .zone {
   flex: 0 0 var(--app-shell-navbar-offset, 0rem);
@@ -58,11 +62,16 @@
 }
 
 /* Workspace switcher (`brand.menu`) — the brand name plus a chevron, as a row-shaped trigger. The
- * chevron is faint until hover so the brand still reads as the brand, not as a control. */
+ * chevron is faint until hover so the brand still reads as the brand, not as a control.
+ *
+ * `control-gap`, not the `sidebar-section-label-gap` this used to borrow: it is a HORIZONTAL
+ * name-to-glyph gap inside one control, and it has nothing to do with a sidebar label's vertical
+ * proximity pair — which is exactly why it moved when that token was retuned for an unrelated
+ * reason. Same 6px, correct by meaning. */
 .brandButton {
   display: flex;
   align-items: center;
-  gap: var(--vx-space-sidebar-section-label-gap);
+  gap: var(--vx-space-control-gap);
   min-width: 0;
   padding: 0;
   color: var(--vx-faint);

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

@@ -1,4 +1,4 @@
-/* App-shell top bar layout. ONE 48px row on every viewport, spanning the FULL viewport width —
+/* App-shell top bar layout. ONE 44px row on every viewport, spanning the FULL viewport width —
  * [brand | collapse] [breadcrumb] ········ [page bar row 1] | [global actions].
  *
  * The leading zone is `app-brand.module.css`'s `.zone`: exactly `--app-shell-navbar-offset` wide,
@@ -36,17 +36,48 @@
  * overflows towards its START, so the sync button painted 30px INTO the page title. Measured in
  * Chrome: the title spanned 119.7–197.1 and the sync button 158.3–188.3.
  *
- * So the lead is now the elastic side (`flex: 1 1 auto`, `min-width: 0`, each crumb truncating via
- * its own `truncate` prop) and the control side is rigid. A row of buttons that genuinely does not
- * fit is not a shrinking problem — it is the OVERFLOW FOLD's problem, and basalt already owns that
- * (law C7: below `sm` row 1 is the primary plus ONE kebab).
+ * So the lead is now the elastic side (`flex: 1 1 auto`, each crumb truncating via its own
+ * `truncate` prop) and the control side is rigid. A row of buttons that genuinely does not fit is
+ * not a shrinking problem — it is the OVERFLOW FOLD's problem, and basalt already owns that (law
+ * C7: below `sm` row 1 is the primary plus ONE kebab).
+ *
+ * `min-width` is a FLOOR, not the `0` it used to be: elastic still, but never elastic to nothing.
+ * With `0` the breadcrumb was the row's entire shock absorber and it absorbed itself out of
+ * existence — and then the row overflowed anyway, because `.pageBar` and `.global` below are both
+ * rigid. Measured on /dashboard at exactly 768px (the `sm` breakpoint, where the navbar appears):
+ * 768 − 256 navbar = 512px of header left, against ~554px of row 1 + ~102px of globals + ~48px of
+ * gaps ≈ 704px. ~192px over, with the page title already at zero — so the fold bought nothing and
+ * cost the reader the one word saying where they are.
+ *
+ * 96px, because the current crumb is `VX.text.lg` (16px) at `font-stretch: 88%`, i.e. ~7px of
+ * average advance: 96px is ~13 characters ("Study progress") before the crumb's own `truncate`
+ * starts eliding, and a short title ("Dashboard", "Settings") fits with room to spare. Below that
+ * the crumb is an ellipsis with a letter in front of it, which is the state this floor exists to
+ * forbid.
+ *
+ * It reads a TOKEN (`SPACE_STEP.appShellHeaderLeadMin`) rather than the raw `96px` it shipped as,
+ * because the derivation above is entirely in units that move with density — the crumb's type size
+ * and its average advance — so a frozen floor would buy ~13 characters at level 0 and fewer at
+ * every level up. The rem fallback is the level-0 number, for a stylesheet loaded before the
+ * provider's.
+ *
+ * Unscoped by width on purpose — it costs nothing on a phone. At 390px the row is the breadcrumb
+ * plus ~66px of mobile bar, ~66px of globals and ~26px of gaps inside a 374px content box, so the
+ * floor is never the binding constraint there.
+ *
+ * The floor is NOT free above `sm`: on its own it adds its own 96px to that ~192px overflow. The
+ * `md` label fold in `controls/actions.tsx` (`BarEntry`, same 62em tier) is what pays for it —
+ * dropping up to `DESKTOP_SECONDARY_MAX` (3) labelled secondaries to `ctl`-tier icon buttons returns
+ * roughly 180-240px on that same row. The two are one change; neither is correct alone, and
+ * NEITHER is the real answer, which is measuring the row (a ResizeObserver fold) rather than
+ * declaring breakpoints for it. This pair is the cheap, declared interim until that exists.
  */
 .lead {
   display: flex;
   align-items: center;
   gap: var(--mantine-spacing-sm);
   flex: 1 1 auto;
-  min-width: 0;
+  min-width: var(--vx-space-app-shell-header-lead-min, 96px);
 }
 
 /* No `overflow: hidden` here or on `.lead` above: Mantine's focus ring is `outline: 2px solid;
@@ -81,7 +112,8 @@
 }
 
 /*
- * The shell globals sit at the SAME 30px tier as everything else in the row, and they get there the
+ * The shell globals sit at the SAME 32px `ctl` tier as everything else in the row, and they get there
+ * the
  * same way a home's slot does — `HeaderGlobalActions` wraps this region in a `CtlSlot`, so a
  * consumer's bare `<ActionIcon>` in `globalActions` defaults to `size="ctl"` with no prop at the call
  * site (law C5). They rendered at Mantine's `md` 28px before, which is 2px under the page group
@@ -98,9 +130,17 @@
   flex-shrink: 0;
 }
 
+/* Glyph BOX, 1.125rem — the SAME decoration-class fixed size `page-bar.module.css` sets on row 1's
+ * own glyphs, and deliberately NOT a `--vx-space-*` token (an icon is not a gap; the shipped icon
+ * set draws on a 24px grid and the box is a fraction of the type size, not of the spacing scale).
+ * Do not re-litigate these in a token sweep.
+ * 1.125rem rather than the old 1rem for the same reason the page bar's grew — `controlHeightCtl`
+ * went 30 -> 32, and a glyph held at 16px inside a 32px control reads EMPTIER, not bigger. The two
+ * rows are ONE control family (`HeaderGlobalActions` and `PageBar` row 1 sit in the same 44px
+ * band), so they had to stop disagreeing by 2px on the same glyph. */
 .global :global(.mantine-ActionIcon-root) > svg {
-  width: 1rem;
-  height: 1rem;
+  width: 1.125rem;
+  height: 1.125rem;
 }
 
 /*

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

@@ -89,7 +89,23 @@
   margin-bottom: calc(var(--app-shell-footer-offset, 0rem) + env(safe-area-inset-bottom, 0px));
   margin-inline-start: var(--app-shell-navbar-offset, 0rem);
   margin-inline-end: var(--app-shell-aside-offset, 0rem);
-  padding: var(--app-shell-padding);
+  /*
+   * The scrollport's own inset, SPLIT by axis — a gap under a divider is not a gutter beside a
+   * seam.
+   *
+   * Inline stays on `--app-shell-padding`, the one Mantine var this module still reads for a
+   * 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).
+   *
+   * 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.
+   */
+  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. */
   min-width: 0;
   overflow-y: auto;
@@ -107,9 +123,13 @@
 }
 
 /* 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 `.main`'s own `padding` shorthand above
- * — same mechanism as `app-sidebar.module.css`'s left counterpart. The bottom inset already rides
- * `margin-bottom` above (`env(safe-area-inset-bottom)`); the PWA's top inset needs no rule here
+ * 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
+ * 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
  * (the status bar uses the opaque `default` style, per argo's own seed comment). */
 @media (display-mode: standalone) {
   .main {

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

@@ -9,7 +9,14 @@
   align-items: stretch;
   width: 100%;
   height: 100%;
-  background: var(--mantine-color-body);
+  /* NOT `--mantine-color-body`: that is the EXACT fill the scrollport above paints (both resolve
+   * to `--vx-surface-bg`), so the only thing separating the bar from the page was the region
+   * seam's 9%-alpha hairline — invisible on a phone, which is the "it could also have a border"
+   * report. `--vx-surface-panel` is a derived step above bg on both schemes and is the same
+   * relation `.sheet` already uses, so the edge is a real tonal one with no new token, no drop
+   * shadow (DESIGN-CORE pins depth to three tokens, none of them an upward-cast footer shadow)
+   * and no `withBorder` on the shell region (basalt-mantine.md forbids drawing that ourselves). */
+  background-color: var(--vx-surface-panel);
   -webkit-tap-highlight-color: transparent;
   /* NO padding-bottom / env() here: Mantine's own AppShell `.footer` rule already does
    * `height: calc(var(--app-shell-footer-height) + env(safe-area-inset-bottom))` +
@@ -90,7 +97,8 @@
   height: 8px;
   border-radius: 999px;
   background-color: var(--vx-accent);
-  box-shadow: 0 0 0 2px var(--mantine-color-body);
+  /* The halo punches the dot out of whatever the BAR paints, so it tracks `.bar`'s fill. */
+  box-shadow: 0 0 0 2px var(--vx-surface-panel);
 }
 
 /* `text-overflow: clip`, never an ellipsis — a truncated word with a "…" in a 72px tab reads as
@@ -106,10 +114,25 @@
 }
 
 /* The menu pops UP out of its tab and is configured `flip: false` — flipping a bottom-anchored
- * menu would put it under the footer. `menuMax` is what guarantees it fits (§2.2). */
+ * menu would put it under the footer, so something has to guarantee it fits. That something is the
+ * `max-height` below, not `menuMax` (§2.2 as it used to be written). */
 .menuDropdown {
-  padding: 4px;
-  max-height: min(60dvh, 360px);
+  padding: var(--vx-space-stack-xs);
+  /* THIS is what guarantees the menu never renders below the fold — not `menuMax`, which is only
+   * the menu-vs-sheet taste threshold (`mobile-nav-model.ts`'s module doc has the accounting).
+   *
+   * `min(62dvh, 440px)`, down from `min(72dvh, 560px)`. The old pair fit — but fitting was never
+   * the whole ask: MEASURED in headless Chrome at 390x844 the dropdown rendered 300x560 at
+   * y=221..781, i.e. 66% of the screen, which reads as a panel rather than as the "subtle, small
+   * menu" the More surface is supposed to be. At 440 the same phone gets 52%.
+   *
+   * The accounting, at both ends of the supported range. 390x844: headroom above the bar is 772px,
+   * 62dvh resolves to 523px, so the 440px term binds — 57% of the headroom. 320x568: headroom is
+   * ~496px, 62dvh resolves to 352px, so THAT term binds — 71% of the headroom. Either way the
+   * binding term is one of the two written here and it lands under the headroom, which is the
+   * property that matters: the cap, not `menuMax`, is the guarantee. Past it the dropdown scrolls
+   * inside itself instead of growing, so a long More list costs scroll, never fold. */
+  max-height: min(62dvh, 440px);
   overflow-y: auto;
   overscroll-behavior: contain;
 }
@@ -135,13 +158,16 @@
 /*
  * A disabled destination still RENDERS in the menu (§2.3 rule 11) — it just must not be reachable.
  * Mantine's `Menu.css` styles `[data-disabled]` with a dimmed color and nothing else, and the row
- * is polymorphic (`component="a"`), so the native `disabled` attribute does not apply either: with
- * no rule here the row stays fully clickable. `pointer-events: none` is the real guard; `menuRow`
- * carries a matching handler guard for the paths pointers do not cover (keyboard, synthetic
- * clicks, a consumer stylesheet that resets this).
+ * is polymorphic (`component="a"`), so the native `disabled` attribute does not apply either.
+ *
+ * `pointer-events: none` USED to be the guard here and is deliberately gone. It made the row
+ * swallow a tap with zero feedback — no `:active`, no press state, nothing — which on a phone is
+ * indistinguishable from a button that is simply broken, and "I tap and nothing happens" is
+ * literally the report this change answers. The guard is now entirely in the handlers (`menuRow`,
+ * `sheetRow`), which cover the pointer path and every path a pointer never takes; the row still
+ * depresses under a finger and still goes nowhere, which is the honest version of dead.
  */
 .menuItem[data-disabled] {
-  pointer-events: none;
   cursor: not-allowed;
 }
 
@@ -151,7 +177,10 @@
   padding-inline-start: calc(var(--mantine-spacing-md) + 12px) !important;
 }
 
-/* Overflow section heading inside the menu — inherits the theme's mono micro-label. */
+/* Overflow section heading, in the menu AND in the sheet — inherits the theme's mono micro-label.
+ * The inset matches the rows' own (`--vx-space-row-inset-x`) so the heading and the labels under
+ * it share one left edge; the vertical padding is asymmetric on purpose — a heading belongs to
+ * what follows it, so it sits closer to its own rows than to the section above. */
 .menuLabel {
   font-family: var(--basalt-font-mono);
   font-size: var(--vx-text-micro);
@@ -159,6 +188,65 @@
   text-transform: uppercase;
   letter-spacing: 0.08em;
   color: var(--vx-faint);
+  padding: 6px var(--vx-space-row-inset-x) 2px;
+}
+
+/*
+ * The popover's SECTION RHYTHM — what replaced the single `Menu.Divider`, and it is SPACE, not a
+ * line.
+ *
+ * The Drawer's bulk was never its row height (40px is a WCAG 2.5.5 floor pinned by
+ * `theme/density-relations.test.ts`); it was the stack rhythm around the rows — a 12px section
+ * gap, 18px of Drawer padding and a header row. A popover with one hairline through the middle and
+ * no rhythm at all is the other extreme, so each group opens its own band instead.
+ *
+ * A `border-top: 1px solid var(--vx-divider)` here was the obvious move and is deliberately NOT
+ * what shipped: `theme/divider-law.test.ts` inventories every horizontal hairline in the package
+ * and classifies it as `between-rows`, `region-boundary` or (inside `content/**` only)
+ * `prose-typography` — and it says in as many words that a rule under a HEADING in the chrome lane
+ * is none of the three, and that the fix is to delete it and let the type scale and the space do
+ * the work. A mono uppercase micro-label at `--vx-faint` over its own band of air is already a
+ * section boundary; a line under it would be the second one.
+ *
+ * `:not(:first-child)` keeps the first group flush with the dropdown's own padding instead of
+ * opening a band under the top edge with nothing above it — the same "a separator separates"
+ * property the guarded `Menu.Divider` used to carry in JSX. Scoped to `.menuDropdown` because
+ * `.menuLabel` is also the SHEET's group heading (`sheetGroupLabel`), where each label is its
+ * group Stack's first child and the rhythm is the Drawer's own to draw.
+ *
+ * The band is 6/4, down from 8/8 — the second half of the same "still too big" verdict the
+ * `max-height` above answers, and the cheaper half. MEASURED per heading at 8/8: 8px margin + 8px
+ * padding-top + 2px padding-bottom + a 17px line = a 35px box, and there are FIVE of them in the
+ * shipped More surface — 175px, 28% of the whole dropdown spent on five words. 6/4 takes each
+ * banded heading to 29px and hands 24px back to the rows. It does NOT touch the row height (40px
+ * is the WCAG 2.5.5 floor named at the top of this comment) and it does not add the line the
+ * paragraph above rules out: this is the same space that argument asked to carry the boundary,
+ * spent tighter.
+ */
+.menuDropdown .menuLabel:not(:first-child) {
+  margin-top: 6px;
+  padding-top: 4px;
+}
+
+/* The same band, on the first row of the UNLABELLED tail (blocks + account + settings) — the one
+ * boundary in the More surface with no heading to open it. Margin rather than padding: a row is a
+ * touch target with a `min-height` floor and symmetric inset, so growing one side of it would make
+ * that row read as a different size from its siblings. */
+.menuDropdown .menuSectionStart {
+  margin-top: 8px;
+}
+
+/*
+ * A sticky heading over a scrolling dropdown must be OPAQUE. `theme/index.ts` documents the same
+ * fix for the Drawer's header: basalt dropped that background to `transparent`, which reads fine
+ * until rows actually scroll under it and then shows every one of them straight through the title.
+ * `--vx-surface-overlay` is the dropdown's own fill, so the heading matches the box it sits in.
+ */
+.menuDropdown .menuLabel {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  background-color: var(--vx-surface-overlay);
 }
 
 /*

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

@@ -13,6 +13,7 @@ declare const classes: {
   readonly menuItem: string
   readonly menuItemNested: string
   readonly menuLabel: string
+  readonly menuSectionStart: string
   readonly sheet: string
   readonly sheetTitle: string
   readonly sheetHeader: string