basalt-ui 1.29.1 → 1.30.0

package/src/dashboard/stat-group.tsx

@@ -4,12 +4,18 @@
  * packs tighter than a chart card and the law starts at TWO on a phone.
  *
  * **`cols` is the DESKTOP count** and the only number a consumer states; the law is
- * `base 2 → sm min(cols, 3) → lg cols`. Five is the ceiling — past that the cells are narrower than
+ * `base 2 → sm min(cols, 3), except 4 → 2 → lg cols`. Five is the ceiling — past that the cells are narrower than
  * a formatted currency value and the row is a table.
  *
  * **`lg` enters the package here and in `WidgetGrid`, nowhere else.** `sm` stays the only
  * breakpoint a consumer writes (`docs/CONTROLS-SPEC.md` §2).
  *
+ * **The column law keys on the CONTAINER, not the viewport.** `StatGroup` renders its own
+ * `container-type: inline-size` box around the grid, so the counts follow the width the row
+ * ACTUALLY has — a `PageAside` claiming 300px, a collapsed sidebar giving 208px back, a consumer's
+ * split pane — rather than the viewport width, which changes for none of those. See
+ * `stat-group.module.css`'s header for the measured defect and the pre-2023 fallback.
+ *
  * `divided` swaps the column gap for a hairline rail between cells — the bare-metric-row look, for
  * KPIs that are one reading split several ways rather than several independent cards. It draws the
  * rule on the GROUP, so the cells stay whatever they are; on `StatCard`s (which carry their own
@@ -33,7 +39,7 @@ import classes from './stat-group.module.css'
 export type StatGroupCols = 2 | 3 | 4 | 5
 
 export type StatGroupProps = BasaltProps & {
-  /** The DESKTOP column count (`lg` and up). Default `4`. `sm` gets `min(cols, 3)`, a phone gets 2.
+  /** The DESKTOP column count (`lg` and up). Default `4`. `sm` gets `min(cols, 3)` — except `4`, which gets 2 rather than an orphan row. A phone gets 2.
    * Never a responsive object — the law is basalt's, see the module docblock. */
   cols?: StatGroupCols
   /** Swap the column gap for a hairline rail between cells. Default `false`. */
@@ -49,26 +55,40 @@ export function StatGroup({
   className,
   style,
 }: StatGroupProps) {
-  const smCols = Math.min(cols, 3)
+  // `4 -> 2`, not `4 -> 3`. `min(cols, 3)` is the general rule and it is right for 2, 3 and 5, but
+  // FOUR is the default and the overwhelmingly common count, and three columns leave a four-KPI row
+  // as 3 + 1 — one orphan cell against two thirds of empty track. MEASURED on the playground
+  // dashboard with a `PageAside` claimed (group 916px): three cells of ~273px plus an orphan, where
+  // two of ~450px read as one balanced block. A KPI row is a set of peers; a ragged last row says
+  // one of them is different, which is the one thing it must not say.
+  const smCols = cols === 4 ? 2 : Math.min(cols, 3)
 
   return (
-    <div
-      className={cx(classes.root, className)}
-      data-cols={cols}
-      data-sm-cols={smCols}
-      // An ATTRIBUTE, not a second class: the rail's rules key off the resolved column count
-      // (`[data-cols]`/`[data-sm-cols]`) already, so one selector shape carries the whole law —
-      // same idiom `stat-card.module.css` uses for `[data-placement]`.
-      {...(divided && { 'data-divided': 'true' })}
-      style={
-        {
-          '--basalt-stat-group-cols-sm': smCols,
-          '--basalt-stat-group-cols-lg': cols,
-          ...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: no percentage height resolves differently,
+    // 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}
+        data-sm-cols={smCols}
+        // An ATTRIBUTE, not a second class: the rail's rules key off the resolved column count
+        // (`[data-cols]`/`[data-sm-cols]`) already, so one selector shape carries the whole law —
+        // same idiom `stat-card.module.css` uses for `[data-placement]`.
+        {...(divided && { 'data-divided': 'true' })}
+        style={
+          {
+            '--basalt-stat-group-cols-sm': smCols,
+            '--basalt-stat-group-cols-lg': cols,
+          } as CSSProperties
+        }
+      >
+        {children}
+      </div>
     </div>
   )
 }

package/src/dashboard/widget-grid.module.css

@@ -1,15 +1,34 @@
 /*
  * WidgetGrid's column law, in CSS (law C9 — a responsive swap belongs to the control, never to a JS
- * media query). The two literals below are Mantine's own `--mantine-breakpoint-sm` (48em) and
- * `--mantine-breakpoint-lg` (75em); a `@media` condition is resolved before custom properties
- * exist, so the number has to be written — same standing constraint `content/article-layout.
- * module.css` documents.
+ * media query).
  *
- * The COUNTS are custom properties instead, set once per instance by the component: three
- * hand-written `repeat()` blocks would have to enumerate every `cols` value, and the whole point of
- * this primitive is that a consumer states one desktop number and basalt owns the rest.
+ * **The law keys on the CONTAINER, not the viewport**, for the reason `stat-group.module.css`'s
+ * header states in full: the shell moves the available width without moving the viewport (a
+ * `PageAside` claiming 300px, the sidebar collapsing to its 48px rail, a consumer's split layout),
+ * and `@media` is blind to all of it. `.container` — rendered by `WidgetGrid` around the grid —
+ * is what makes the queries answerable and is always the box the grid actually fills; a query with
+ * no container resolves to false, so leaning on the shell to establish one would have pinned every
+ * non-shell consumer to a single column.
+ *
+ * `.item`'s span law is in the same blocks for the same reason: `grid-column: span <n>` must be
+ * clamped against the count the ROOT is actually rendering, and the root's count now follows the
+ * container. A span resolved against the viewport while the tracks follow the container is exactly
+ * the phantom-track defect `WidgetGrid.Item`'s context clamp exists to prevent.
+ *
+ * The literals: px in `@container`, Mantine's own `em` in the `@supports not` fallback — same
+ * boundary (768px / 1200px at the 16px initial font size), but `em` inside a `@container`
+ * condition resolves against the CONTAINER's font-size, so px is the only spelling that cannot
+ * drift. A condition cannot read a custom property either way, so the numbers are written; the
+ * COUNTS are custom properties, set once per instance by the component — three hand-written
+ * `repeat()` blocks would have to enumerate every `cols` value, and the whole point of this
+ * primitive is that a consumer states one desktop number and basalt owns the rest.
  */
 
+.container {
+  container-type: inline-size;
+  container-name: basalt-widget-grid;
+}
+
 .root {
   display: grid;
   /* Below `sm` a widget column is always 1 — a dashboard card holds a chart, and two of them on a
@@ -18,18 +37,6 @@
   gap: var(--vx-space-stack-md);
 }
 
-@media (min-width: 48em) {
-  .root {
-    grid-template-columns: repeat(var(--basalt-widget-grid-cols-sm), minmax(0, 1fr));
-  }
-}
-
-@media (min-width: 75em) {
-  .root {
-    grid-template-columns: repeat(var(--basalt-widget-grid-cols-lg), minmax(0, 1fr));
-  }
-}
-
 /*
  * `min-width: 0` on every cell: a grid track's default `min-width: auto` is its content's intrinsic
  * width, so one wide `<table>` or one long unbroken value blows the whole row out instead of
@@ -40,14 +47,50 @@
   min-width: 0;
 }
 
-@media (min-width: 48em) {
+@container basalt-widget-grid (min-width: 768px) {
+  .root {
+    grid-template-columns: repeat(var(--basalt-widget-grid-cols-sm), minmax(0, 1fr));
+  }
+
   .item {
     grid-column: span var(--basalt-widget-grid-span-sm);
   }
 }
 
-@media (min-width: 75em) {
+@container basalt-widget-grid (min-width: 1200px) {
+  .root {
+    grid-template-columns: repeat(var(--basalt-widget-grid-cols-lg), minmax(0, 1fr));
+  }
+
   .item {
     grid-column: span var(--basalt-widget-grid-span-lg);
   }
 }
+
+/*
+ * The pre-container-query fallback — Safari < 16, Chrome < 106, Firefox < 110. Verbatim the law
+ * this file shipped before, keyed on the viewport, and reachable ONLY where `@container` is not: a
+ * browser that cannot parse `container-type` cannot parse the blocks above either, so the two sets
+ * are never live at once.
+ */
+@supports not (container-type: inline-size) {
+  @media (min-width: 48em) {
+    .root {
+      grid-template-columns: repeat(var(--basalt-widget-grid-cols-sm), minmax(0, 1fr));
+    }
+
+    .item {
+      grid-column: span var(--basalt-widget-grid-span-sm);
+    }
+  }
+
+  @media (min-width: 75em) {
+    .root {
+      grid-template-columns: repeat(var(--basalt-widget-grid-cols-lg), minmax(0, 1fr));
+    }
+
+    .item {
+      grid-column: span var(--basalt-widget-grid-span-lg);
+    }
+  }
+}

package/src/dashboard/widget-grid.module.css.d.ts

@@ -3,6 +3,7 @@
  * signature — so dot access stays verbatim under the package's strict flags.
  */
 declare const classes: {
+  readonly container: string
   readonly root: string
   readonly item: string
 }

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/query-client.ts

@@ -63,6 +63,16 @@ export function createBasaltQueryClient(config?: QueryClientConfig): QueryClient
  * `unwrap` reference — so `api.threads.get().then(unwrap)` silently widened. A single generic
  * signature has exactly one type to read regardless of how the reference is used.
  *
+ * **The conditional infers the raw `data` type and strips `null`/`undefined` from it**, rather
+ * than inferring the already-narrowed `Envelope<TData>`'s `TData` directly — Eden Treaty's
+ * response type is a UNION of envelope shapes (`{ data: T; error: null } | { data: null; error:
+ * EdenFetchError }`), and inferring through `Envelope<infer TData>` reads `TData` off whichever
+ * union member the conditional happens to match, landing on `T | null` at every Eden call site. A
+ * conditional type distributes over a union input when the checked type is a bare type parameter,
+ * so inferring `D` from `{ data: infer D; error: unknown }` and wrapping the result in
+ * `NonNullable` runs the check per union member and unions the results back together —
+ * `NonNullable<T> | NonNullable<null>` collapses to `T`.
+ *
  * @example
  * import { unwrap } from 'basalt-ui'
  *
@@ -86,12 +96,14 @@ export function unwrap<R extends Envelope | Promise<Envelope>>(response: R): Unw
 type Envelope<TData = unknown> = { data: TData | null | undefined; error: unknown }
 
 /** `unwrap`'s conditional return: a `Promise<TData>` when `R` is a promised envelope, `TData` when
- * it is an already-resolved one — inferred off the SAME `R` the overload used to split on. */
+ * it is an already-resolved one — inferred off the SAME `R` the overload used to split on, and
+ * distributing over a union `R` (see the JSDoc above) so an Eden Treaty response's null branch
+ * never leaks into the resolved type. */
 type UnwrapResult<R> =
-  R extends Promise<Envelope<infer TData>>
-    ? Promise<TData>
-    : R extends Envelope<infer TData>
-      ? TData
+  R extends Promise<{ data: infer TData; error: unknown }>
+    ? Promise<NonNullable<TData>>
+    : R extends { data: infer TData; error: unknown }
+      ? NonNullable<TData>
       : never
 
 function unwrapEnvelope<TData>(envelope: Envelope<TData>): TData {

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 {