basalt-ui 1.29.1 → 1.30.0

package/src/cli/doctor.ts

@@ -4,7 +4,7 @@
  * managed-file manifest path) back from `./index`, this package's shared CLI helpers.
  */
 import { existsSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { relative, resolve } from 'node:path'
 
 import type { BasaltConfig } from './index'
 import {
@@ -19,7 +19,10 @@ import {
   parseJsonc,
   readBasaltConfig,
   readIfExists,
+  readManifest,
   resolveProjectDir,
+  resolveRoots,
+  scannableFiles,
   shippedAssetPath,
 } from './index'
 import { findManifestAbove, parentInstallAdvice } from './sync'
@@ -102,16 +105,22 @@ function resolveAiMajorSkewReason(cfg: BasaltConfig): {
  * Check a consumer repo's basalt integration and print a pass/warn report.
  *
  * Narrowed to what a single-directory-scoped run can actually verify — no workspace-glob walking,
- * no ascend/descend project discovery (see {@link resolveProjectDir}). Four checks, numbered in
+ * no ascend/descend project discovery (see {@link resolveProjectDir}). Six checks, numbered in
  * the order they run and print:
  *
  * Hard failures (exit non-zero):
  *   1. `.basalt/manifest.json` exists (`basalt-ui init` was run).
- *   2. `oxlint-preset` ("rules in sync"): the consumer's `.oxlintrc.json` extends the shipped
+ *   2. `install-parity`: basalt-ui resolves, doctor prints WHERE and at what version, and that
+ *      version agrees with the manifest's `basaltVersion`.
+ *   3. `guard-scan`: `check-theme` would scan more than zero files, sharing `scannableFiles` so the
+ *      two cannot disagree. Both RESTORED in 1.30.0 after four minors gone with no MIGRATING row —
+ *      README § `doctor` carries what their absence cost (a no-op CI gate, a green guard scanning
+ *      nothing, and two basalt-WRITTEN docs describing output the CLI no longer produced).
+ *   4. `oxlint-preset` ("rules in sync"): the consumer's `.oxlintrc.json` extends the shipped
  *      preset AND that path resolves. `init` keeps an existing config, so the framework's whole
  *      lint half can be silently off — one repo carried six real violations invisibly across five
  *      minors this way.
- *   4. `ai-major-parity`: within THIS package.json, `dependencies`/`devDependencies`/
+ *   6. `ai-major-parity`: within THIS package.json, `dependencies`/`devDependencies`/
  *      `peerDependencies` agree on the `ai` package's major. `basalt/ai-sdk-major` (the oxlint
  *      plugin rule) already catches this per linted FILE against its nearest package.json; this
  *      check exists for the shape a lint run cannot see — a package whose own manifest asks its
@@ -121,7 +130,7 @@ function resolveAiMajorSkewReason(cfg: BasaltConfig): {
  *      already agree warns that the exemption is stale.
  *
  * Warning (non-fatal):
- *   3. `lefthook-preset` ("lefthook wired"): a pre-commit command runs `check-theme`, read from
+ *   5. `lefthook-preset` ("lefthook wired"): a pre-commit command runs `check-theme`, read from
  *      `lefthook dump --format json` (resolves `extends`/`include`/`root:` the way lefthook itself
  *      does — see {@link inspectLefthookGate}). No lefthook config at all is a pass (a consumer may
  *      gate elsewhere); a config that resolves but wires no guard command warns; a config lefthook
@@ -189,7 +198,39 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
 
   const install = findBasaltInstall(cwd)
 
-  // ── Hard check 2: the consumer's oxlint config extends the shipped preset ──
+  // ── Hard check 2: install matches the manifest, and doctor says WHERE (the CLAUDE-block's claim)
+  const manifestVersion = profile === 'tokens-only' ? undefined : readManifest(cwd).basaltVersion
+  const at = install.dir === null ? '' : `${relative(cwd, install.dir)} (${install.version})`
+  if (install.dir === null) {
+    fail(
+      'install-parity: basalt-ui does not resolve here, above, or in a sibling workspace package.',
+    )
+  } else if (manifestVersion === undefined || install.version === manifestVersion) {
+    const matches = manifestVersion === undefined ? '' : " and matches the manifest's basaltVersion"
+    pass(`basalt-ui resolves at ${at}${matches}`)
+  } else {
+    fail(
+      `install-parity: basalt-ui resolves at ${at}, but ${MANIFEST_PATH} was last written by ` +
+        `${manifestVersion} — the managed layer is from a different release than the code. Run ` +
+        '`basalt-ui sync` (or `bun install`, if the lockfile is what is stale).',
+    )
+  }
+
+  // ── Hard check 3: the guard sees files — zero-file roots are a green guard enforcing nothing ──
+  const scanned = profile === 'tokens-only' ? null : scannableFiles(cwd, cfg).length
+  if (scanned === null) {
+    pass('guard-scan: n/a — a tokens-only consumer runs the token lane, not the file walk')
+  } else if (scanned === 0) {
+    fail(
+      'guard-scan: `check-theme` would scan ZERO files here — either `basalt.roots` points at ' +
+        'paths that do not exist, or this is not the package the config lives in (BASALT_CWD, ' +
+        'else the cwd; nothing is inferred).',
+    )
+  } else {
+    pass(`guard-scan: check-theme covers ${scanned} file(s) under ${resolveRoots(cfg).join(', ')}`)
+  }
+
+  // ── Hard check 4: the consumer's oxlint config extends the shipped preset ──
   // `init` KEEPS an existing `.oxlintrc.json`, so a repo can carry the whole scaffold with the
   // framework's lint half switched off and nothing anywhere saying so. One repo ran five minors
   // that way and surfaced six real `basalt/no-raw-font-size` errors the moment it was wired.
@@ -235,7 +276,7 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
     }
   }
 
-  // ── Warn check 3: the pre-commit hook actually runs the guard ──────────────
+  // ── Warn check 5: the pre-commit hook actually runs the guard ──────────────
   // Read via `lefthook dump --format json`, which resolves `extends`/`include`/remote configs/
   // `root:` the way lefthook itself does — see {@link inspectLefthookGate}.
   const repoRoot = findRepoRoot(cwd)
@@ -262,7 +303,7 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
     )
   }
 
-  // ── Hard check 4: ai package major version parity within THIS package.json ─
+  // ── Hard check 6: ai package major version parity within THIS package.json ─
   // basalt/ai-sdk-major (the lint rule) is per-file against the NEAREST package.json, so a lint
   // run scoped to one workspace package only ever sees that package's own `ai` major and is
   // perfectly happy. This check reads the SAME package.json across its dependencies/

package/src/cli/help.ts

@@ -21,6 +21,7 @@ export const COMMAND_OPTIONS: Record<string, Record<string, { type: 'string' | '
   sync: {
     force: { type: 'boolean' },
     check: { type: 'boolean' },
+    verbose: { type: 'boolean' },
     'tokens-only': { type: 'boolean' },
     framework: { type: 'boolean' },
   },
@@ -65,7 +66,7 @@ export function unknownFlag(cmd: string, flags: readonly string[]): string | nul
 /** The one usage string — printed by `basalt help` / `--help` / `-h` AND the unknown-command fallback. */
 export const USAGE =
   'Usage: basalt-ui <--version | init [--with-router] [--with-query] [--merge-lint] |\n' +
-  '                  sync [--force] [--check] [--tokens-only|--framework] |\n' +
+  '                  sync [--force] [--check] [--verbose] [--tokens-only|--framework] |\n' +
   '                  check-theme [--audit-allows] |\n' +
   '                  doctor [--tokens-only|--framework] | guard-hook | tokens:css | fonts:css | help>\n\n' +
   'check-theme [--tokens-only|--framework] [--audit-allows]\n' +
@@ -89,9 +90,10 @@ export const USAGE =
   '  Checks THIS project only: the manifest exists, the oxlint preset is wired, the pre-commit\n' +
   '  hook runs check-theme (via `lefthook dump`), and the ai package major is consistent within\n' +
   '  this package.json. Profile is DECLARED, same as check-theme — never inferred.\n\n' +
-  'sync [--force] [--check] [--tokens-only|--framework]\n' +
+  'sync [--force] [--check] [--verbose] [--tokens-only|--framework]\n' +
   '  Refreshes an EXISTING install; it never creates one (that is init). A tokens-only consumer\n' +
-  '  has no scaffold to reconcile, so sync reports n/a and exits 0 there — as doctor does.\n\n' +
+  '  has no scaffold to reconcile, so sync reports n/a and exits 0 there — as doctor does.\n' +
+  '  --check prints the permanent placement skips as a COUNT; --verbose spells them out again.\n\n' +
   'check-theme / doctor / sync all resolve their project the same way: BASALT_CWD, else the\n' +
   'invocation cwd — nothing inferred, nothing ascended or descended into.\n' +
   '--tokens-only and --framework are alternatives; passing both is an error.\n\n' +

package/src/cli/index.ts

@@ -333,6 +333,17 @@ function sanitizeSeverity(cfg: BasaltConfig): BasaltConfig {
   return { ...cfg, severity: kept as Partial<Record<GuardKind, GuardSeverity>> }
 }
 
+/** Does `cwd`'s own `package.json` carry a `basalt` key? — "misconfigured roots" vs "wrong
+ *  directory", the failure a root-invoked hook hits since 1.29.0's single resolver. Never a walk. */
+export function hasBasaltKey(cwd: string): boolean {
+  const raw = readIfExists(resolve(cwd, 'package.json'))
+  try {
+    return raw !== null && (JSON.parse(raw) as { basalt?: unknown }).basalt !== undefined
+  } catch {
+    return false
+  }
+}
+
 export function readBasaltConfig(cwd: string): BasaltConfig {
   try {
     const pkg = JSON.parse(readFileSync(resolve(cwd, 'package.json'), 'utf8')) as {
@@ -1114,6 +1125,44 @@ export function managedFiles(
   return [...rules, ...skills, claudeBlock, design, oxfmt, ...rootTooling, oxlintrc, ...scaffolds]
 }
 
+/**
+ * The PERMANENT placement skips as sentences — one text for `init` and `sync`, which carried two
+ * near-copies that had already drifted apart. Correct and unchanging, which is why `sync --check`
+ * hides them behind `--verbose`. `extends` alone is NOT the recipe for the hook, and saying only
+ * that shipped a broken one: lefthook merges the preset's commands but runs every one at the REPO
+ * ROOT, with no oxlint config, no local binary and no basalt config. `root:` moves the invocation
+ * cwd per command and merges (the preset does not define it) — see the preset's MONOREPO RECIPE.
+ */
+export function placementNotices(cwd: string, placement: PlacementFlags): string[] {
+  const out: string[] = []
+  const install = findBasaltInstall(cwd)
+  const asset = (n: string): string => shippedAssetPath(install, placement.repoRoot, n)
+  // Bare, no `./` — a lefthook `root:` and an Actions `working-directory:` are already repo-relative.
+  const pkg = relativePosix(placement.repoRoot, cwd).replace(/^\.\//, '')
+  const notRoot = `(not the repo root — repo root detected at ${placement.repoRoot})`
+  if (!placement.isPackageRepoRoot) {
+    out.push(
+      `skipped lefthook.yml ${notRoot} — lefthook only reads config at the repo root. Extend ` +
+        `${asset('configs/lefthook.yml')} from your root lefthook.yml AND give every merged ` +
+        `command \`root: '${pkg}/'\` — \`pre-commit.commands.{oxlint,oxfmt,check-theme}.root: ` +
+        `'${pkg}/'\` — or they run at the root where your oxlint config, your binaries and your ` +
+        'basalt config are not.',
+      `skipped .github/workflows/check.yml ${notRoot} — GitHub Actions only reads .github/ at the ` +
+        `repo root; copy the steps from ${asset('configs/check.yml')} into your root CI workflow ` +
+        `instead, and give each one \`working-directory: ${pkg}\` — the same relocation \`root:\` ` +
+        'performs for lefthook, and needed for the same reason.',
+    )
+  }
+  if (placement.relocatedQueryClient !== null) {
+    out.push(
+      `skipped src/query-client.ts (found an existing query client at ` +
+        `${relative(cwd, placement.relocatedQueryClient)}) — import it from there instead of ` +
+        're-seeding at the original path.',
+    )
+  }
+  return out
+}
+
 export type Manifest = {
   version: 1
   /** The basalt-ui version that last wrote this manifest — `doctor`'s one reconciliation axis. */

package/src/cli/init.ts

@@ -4,7 +4,7 @@
  * oxlint-preset plugin reader from `./sync` (also called there).
  */
 import { existsSync } from 'node:fs'
-import { relative, resolve } from 'node:path'
+import { resolve } from 'node:path'
 
 import { deriveSpacing } from '../tokens'
 import type { MergeLintResult, ScaffoldFlags } from './index'
@@ -15,17 +15,16 @@ import {
   mergeOxlintExtends,
   normalizeForLedger,
   patchPackageJson,
+  placementNotices,
   pruneRetiredManagedFiles,
   readManifest,
   reconcileRoots,
-  relativePosix,
   renderContext,
   reportPrune,
   resolvePeerFlags,
   resolvePlacement,
   rootsNotices,
   sha256,
-  shippedAssetPath,
   unitState,
   writeFileEnsuringDir,
   writeUnit,
@@ -166,30 +165,10 @@ export function init(cwd: string = process.cwd(), scaffoldFlags: ScaffoldFlags =
   if (seededLintScript) {
     console.log(`basalt-ui init: added the "lint:basalt" script (${lintScript}) to package.json.`)
   }
-  // lefthook.yml / .github/workflows/check.yml are repo-root-shaped — neither lefthook nor GitHub
-  // Actions reads config from anywhere but the repo root, so a package living in a subdirectory
-  // skips both rather than relocating them into a spot nothing reads.
-  if (!placement.isPackageRepoRoot) {
-    console.log(
-      `basalt-ui init: skipped lefthook.yml (this package is not the repo root — repo root ` +
-        `detected at ${placement.repoRoot}) — lefthook only reads config at the repo root; extend ` +
-        `${ctx.vars.LEFTHOOK_PRESET_PATH} from your root lefthook.yml instead, and give its ` +
-        `check-theme command \`env: { BASALT_CWD: ${relativePosix(placement.repoRoot, cwd)} }\` ` +
-        'so the guard runs where your basalt config actually lives.',
-    )
-    console.log(
-      `basalt-ui init: skipped .github/workflows/check.yml (this package is not the repo root — ` +
-        `repo root detected at ${placement.repoRoot}) — GitHub Actions only reads .github/ at the ` +
-        `repo root; copy the steps from ${shippedAssetPath(install, placement.repoRoot, 'configs/check.yml')} ` +
-        'into your root CI workflow instead.',
-    )
-  }
-  if (placement.relocatedQueryClient !== null) {
-    console.log(
-      `basalt-ui init: skipped src/query-client.ts (found an existing query client at ` +
-        `${relative(cwd, placement.relocatedQueryClient)}) — import it from there instead of ` +
-        're-seeding at the original path.',
-    )
+  // The permanent placement skips (repo-root-shaped tooling, a relocated scaffold) — one text,
+  // shared with `sync`. See {@link placementNotices}.
+  for (const line of placementNotices(cwd, placement)) {
+    console.log(`basalt-ui init: ${line}`)
   }
   // query-client.ts / __root.tsx reference the optional TanStack peers directly — seeding them
   // without the peer installed would ship an unresolved import. Hint how to opt in instead.

package/src/cli/sync.ts

@@ -5,7 +5,7 @@
  * resolution back from `./index`, this package's shared CLI helpers.
  */
 import { existsSync } from 'node:fs'
-import { relative, resolve } from 'node:path'
+import { resolve } from 'node:path'
 
 import { deriveSpacing } from '../tokens'
 import {
@@ -21,6 +21,7 @@ import {
   managedFiles,
   normalizeForLedger,
   parseJsonc,
+  placementNotices,
   pruneRetiredManagedFiles,
   readBasaltConfig,
   readIfExists,
@@ -232,26 +233,12 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
   })
   staleForCheck += pruned.removed.length + pruned.drifted.length
 
-  // Placement notices — informational, never affect the exit code (a skipped tooling seed or a
-  // relocated scaffold is a legitimate consumer choice, not a sync failure).
-  if (!placement.isPackageRepoRoot) {
-    console.log(
-      `basalt-ui sync: skipped lefthook.yml (this package is not the repo root — repo root ` +
-        `detected at ${placement.repoRoot}) — lefthook only reads config at the repo root; extend ` +
-        'node_modules/basalt-ui/configs/lefthook.yml from your root lefthook.yml instead.',
-    )
-    console.log(
-      `basalt-ui sync: skipped .github/workflows/check.yml (this package is not the repo root — ` +
-        `repo root detected at ${placement.repoRoot}) — GitHub Actions only reads .github/ at the ` +
-        'repo root; extend node_modules/basalt-ui/configs/check.yml from your root CI workflow instead.',
-    )
-  }
-  if (placement.relocatedQueryClient !== null) {
-    console.log(
-      `basalt-ui sync: skipped src/query-client.ts (found an existing query client at ` +
-        `${relative(cwd, placement.relocatedQueryClient)}) — import it from there instead of ` +
-        're-seeding at the original path.',
-    )
+  // Placement notices — informational, never affecting the exit code, and PERMANENT: `--check`
+  // hides them behind `--verbose` (it sits in consumers' CI chains, where three unchanging
+  // "skipped" paragraphs per run are noise indistinguishable from drift) but still prints the COUNT.
+  const placementSkips = placementNotices(cwd, placement)
+  if (opts.check !== true || syncFlags.includes('--verbose')) {
+    for (const line of placementSkips) console.log(`basalt-ui sync: ${line}`)
   }
 
   const rootsMessages = rootsNotices(rootsState)
@@ -298,7 +285,9 @@ export function sync(opts: SyncOptions = {}, invocationCwd: string = process.cwd
       console.error(`basalt-ui sync --check: ${staleForCheck} managed file(s) out of date.`)
       return 1
     }
-    console.log('✓ basalt-ui sync --check: all managed files current.')
+    const n = placementSkips.length
+    const skips = n === 0 ? '' : ` (${n} permanent placement skip(s) — --verbose for detail)`
+    console.log(`✓ basalt-ui sync --check: all managed files current.${skips}`)
     return 0
   }
 

package/src/controls/actions.tsx

@@ -13,6 +13,7 @@
  * media query, so there is no first-paint flash and no hook that re-renders on resize.
  */
 import { ActionIcon, Button, Group, Menu } from '@mantine/core'
+import type { MantineBreakpoint } from '@mantine/core'
 import { createContext, isValidElement, useContext, useEffect } from 'react'
 import type { ReactNode } from 'react'
 import type { BasaltProps } from '../common/props'
@@ -187,6 +188,19 @@ const MOBILE_PRIMARY_PADDING_X = 10
  */
 const BAR_GAP = 6
 
+/**
+ * A declared WIDTH TIER for one rendered form of an action — Mantine's own `visibleFrom`/`hiddenFrom`
+ * style props, forwarded verbatim, which is the same CSS-only mechanism this file's `sm` swap uses
+ * (see the module header). Never a JS media query: no first-paint flash, no resize re-render.
+ *
+ * It exists because `sm` is not the only width at which this row runs out of room — see
+ * {@link BarEntry}'s `md` label fold for the arithmetic.
+ */
+type TierVisibility = {
+  visibleFrom?: MantineBreakpoint
+  hiddenFrom?: MantineBreakpoint
+}
+
 /**
  * One action as a button. No `size` prop anywhere: the enclosing `CtlSlot` (mounted by the home,
  * never by the action) resolves the `ctl` tier — law C5.
@@ -195,15 +209,19 @@ function BarButton({
   action,
   variant,
   px,
+  tier,
 }: {
   action: BarActionItem
   variant: 'filled' | 'default'
   /** Overrides the tier's horizontal inset — only the compact mobile primary passes it. */
   px?: number
+  /** The declared width tier this form paints at — see {@link TierVisibility}. */
+  tier?: TierVisibility
 }): ReactNode {
   const shared = {
     variant,
     ...(px !== undefined && { px }),
+    ...tier,
     disabled: action.disabled === true,
     loading: action.loading === true,
     // EVERY icon in this file goes through `IconSlot` — the box is the framework's, never the
@@ -234,13 +252,17 @@ function BarButton({
 function BarIconButton({
   action,
   variant,
+  tier,
 }: {
   action: BarActionItem
   /** `default` is the bordered desktop form — a joined `ControlGroup` member (see {@link BarEntry}). */
   variant: 'filled' | 'subtle' | 'default'
+  /** The declared width tier this form paints at — see {@link TierVisibility}. */
+  tier?: TierVisibility
 }): ReactNode {
   const shared = {
     variant,
+    ...tier,
     'aria-label': action.label,
     disabled: action.disabled === true,
     loading: action.loading === true,
@@ -698,6 +720,35 @@ function BarEntry({
   if (iconOnly === true && action.icon !== undefined) {
     return <BarIconButton action={action} variant="default" />
   }
+  // THE `md` LABEL FOLD — the second declared tier, and the only fold this row had between `sm`
+  // (48em, where the whole mobile swap happens) and the width at which a desktop header is
+  // genuinely wide. Above `sm` the only fold was `DESKTOP_SECONDARY_MAX`, which is a COUNT and
+  // never a width: three labelled secondaries are three labelled secondaries at 768px and at
+  // 2560px.
+  //
+  // The arithmetic, on /dashboard at exactly 768px — the width where the navbar appears and takes
+  // 256px: 512px of header left, against ~554px of row 1 + ~102px of globals + ~48px of gaps ≈
+  // 704px. ~192px over, and nothing above `sm` folded — the breadcrumb absorbed it by shrinking to
+  // zero (`shell/app-header.module.css`'s `.lead`, now floored at 96px, which this tier pays for).
+  // Dropping up to `DESKTOP_SECONDARY_MAX` labelled secondaries to their 30px icon form returns
+  // roughly 180-240px on that row: a labelled `ctl` button is its icon slot + label + insets
+  // (~90-110px depending on the word), an icon-only one is the tier's 30px square.
+  //
+  // The PRIMARY keeps its label at every width — it is the one action a reader must be able to
+  // name without hovering (law C6: exactly one per home), so `emphasis === 'primary'` never enters
+  // this branch. An icon-LESS secondary keeps its label too: there is nothing to fall back to, the
+  // same reason `MobileBarEntry` renders a compact labelled button below `sm`.
+  //
+  // Both forms are rendered and CSS picks one, the mechanism the `sm` swap already uses — that is
+  // law C9 being HONOURED, not breached: the swap belongs to the control, and this is the control.
+  if (emphasis === 'secondary' && action.icon !== undefined) {
+    return (
+      <>
+        <BarIconButton action={action} variant="default" tier={{ hiddenFrom: 'md' }} />
+        <BarButton action={action} variant="default" tier={{ visibleFrom: 'md' }} />
+      </>
+    )
+  }
   return <BarButton action={action} variant={emphasis === 'primary' ? 'filled' : 'default'} />
 }
 

package/src/dashboard/section.module.css

@@ -6,20 +6,27 @@
 
 /*
  * 12px from the header to the body, and the same between two body children — one rhythm, read from
- * the stack scale (`--vx-space-stack-md`) instead of the card-inset scale
- * (`--mantine-spacing-sm`, 13px). A Section is a page-level GROUPING, so its gaps belong to the
- * vertical rhythm, not to the inset ladder its cards use.
+ * the stack scale (`SPACE.stackMd`, via the `--vx-space-section-gap` role token) instead of the
+ * card-inset scale (13px). A Section is a page-level GROUPING, so its gaps belong to the vertical
+ * rhythm, not to the inset ladder its cards use.
+ *
+ * Below `sm` it steps to `stackSm` (8px), together with the cards' own horizontal inset. That step
+ * is NOT written here: it belongs to the mobile inset ladder, whose ONE home is `spaceMobileDecls`
+ * in `tokens/index.ts` — this rule only reads the role token and gets the responsive value for
+ * free. See that function's doc for why the law lives in the emitter rather than in the three
+ * stylesheets that consume it (two of the three are inline styles, which cannot hold a media
+ * query at all).
  */
 .root {
   display: flex;
   flex-direction: column;
-  gap: var(--vx-space-stack-md, 0.75rem);
+  gap: var(--vx-space-section-gap, 0.75rem);
 }
 
 .body {
   display: flex;
   flex-direction: column;
-  gap: var(--vx-space-stack-md, 0.75rem);
+  gap: var(--vx-space-section-gap, 0.75rem);
 }
 
 /*
@@ -48,8 +55,9 @@
  * The collapse chevron — a plain control, not a Mantine ActionIcon, so it sits directly in the header
  * row (its own CtlSlot fragment would nest a theme provider around one glyph). It is sized to the
  * `ctl` tier BY HAND for exactly that reason: a 12px glyph in a 20px box was a different height from
- * every other control in the same header, which is what made the section header read as ragged. 30px
- * square, glyph centred, no padding — the box IS the tier.
+ * every other control in the same header, which is what made the section header read as ragged. 32px
+ * square (the `ctl` tier, 30 before the desktop-shell pass), glyph centred, no padding — the box IS
+ * the tier.
  */
 .chevron {
   /* `relative` is the anchor for the C15 hit-area overlay in the `< sm` block at the bottom. */

package/src/dashboard/stat-card.tsx

@@ -378,7 +378,12 @@ export function StatCard({
     <Card
       className={cx(classNames?.root, className)}
       style={{
-        // Card inset = spacing xs / sm, matching every other basalt card. `overflow: hidden` clips
+        // Card inset = the `cardInsetY`/`cardInsetX` role tokens (11/13 at level 0 — the same
+        // `xs`/`sm` rungs this used to spell as `--mantine-spacing-*`), matching every other basalt
+        // card because `ChartCard` reads the SAME two vars. Below `sm` the horizontal one steps a
+        // rung down on its own: the responsive half of the ladder lives in `spaceMobileDecls`
+        // (`tokens/index.ts`), which is the only home that can reach an inline style like this one.
+        // `overflow: hidden` clips
         // the full-bleed sparkline to the card's rounded corners; an element's own `box-shadow`
         // renders outside its border box and is NOT clipped by its own `overflow`, so the
         // shadow-card ring is unaffected (verified — only an ANCESTOR's overflow clips a
@@ -390,7 +395,7 @@ export function StatCard({
         // body is `height: 100%` and the sparkline is `margin-top: auto`. The content is what states
         // the height now (~88-96px), and four cards in a `SimpleGrid` still match because a grid row
         // stretches its items.
-        padding: 'var(--mantine-spacing-xs) var(--mantine-spacing-sm)',
+        padding: 'var(--vx-space-card-inset-y, 0.6875rem) var(--vx-space-card-inset-x, 0.8125rem)',
         overflow: 'hidden',
         // Anchors the tone rail. Set unconditionally so a card's stacking context does not change
         // depending on whether it happens to have crossed a threshold this render.

package/src/dashboard/stat-group.module.css

@@ -1,10 +1,41 @@
 /*
- * StatGroup's column law and its optional rail, in CSS (law C9). The literals are Mantine's
- * `--mantine-breakpoint-sm` (48em) and `--mantine-breakpoint-lg` (75em) — a `@media` condition
- * cannot read a custom property, so the number has to be written; the COUNTS are custom properties
- * the component sets per instance.
+ * StatGroup's column law and its optional rail, in CSS (law C9).
+ *
+ * **The law keys on the CONTAINER, not the viewport.** A viewport breakpoint answers the wrong
+ * question — the same one `resolveChartTier` refuses to ask (`charts/primitives/chart-frame-layout.
+ * ts`): the shell has regions that change the AVAILABLE width with the viewport held still (a
+ * `PageAside` claiming its 300px, the sidebar collapsing 256px → its 48px rail, a consumer's own
+ * split layout), and `@media` cannot see any of them. Measured defect: a `PageAside` mounted on a
+ * 1512px desktop left the KPI row ~956px wide, `@media` still resolved `lg`, and four cells of
+ * 239px truncated their own values mid-word ("8,7…", "Organic se…").
+ *
+ * `.container` is what makes the queries answerable — `StatGroup` renders it around the grid, so
+ * the container context ALWAYS exists and is ALWAYS the box the grid actually fills, whatever the
+ * shell or the consumer wrapped it in. It deliberately does not depend on the shell establishing
+ * one: a query with no container resolves to false, so a shell-only context would have silently
+ * pinned every non-shell consumer to the base count.
+ *
+ * The `@supports not` block below it is the pre-2023 fallback and the ONLY place the old viewport
+ * law survives. It is written as an exclusive alternative rather than as a base the container
+ * queries override, because the rail's `:nth-child` suppressors are MORE specific than the rule
+ * that draws the border: two overlapping laws would each suppress a different set of leading cells
+ * and the rail would lose hairlines in the middle of a row. One law at a time, chosen by support.
+ *
+ * The literals: `@container` conditions are stated in px, `@media` ones in Mantine's own `em`
+ * (`--mantine-breakpoint-sm` 48em, `--mantine-breakpoint-lg` 75em). Both spellings name the same
+ * boundary at the 16px initial font size — 768px and 1200px — but `em` inside a `@container`
+ * condition resolves against the CONTAINER's font-size rather than the root's, so a consumer panel
+ * with smaller text would silently move the breakpoint. px is the only spelling that cannot drift.
+ * (`47.99375em` → `767.9px`, `74.99375em` → `1199.9px`; the same complements `stat-card.module.css`
+ * uses.) A condition still cannot read a custom property either way, so the numbers are written;
+ * the COUNTS are custom properties the component sets per instance.
  */
 
+.container {
+  container-type: inline-size;
+  container-name: basalt-stat-group;
+}
+
 .root {
   display: grid;
   /* Two KPIs abreast on a phone, never one: a KPI is a short pre-formatted number, and a single
@@ -13,13 +44,13 @@
   gap: var(--vx-space-stack-md);
 }
 
-@media (min-width: 48em) {
+@container basalt-stat-group (min-width: 768px) {
   .root {
     grid-template-columns: repeat(var(--basalt-stat-group-cols-sm), minmax(0, 1fr));
   }
 }
 
-@media (min-width: 75em) {
+@container basalt-stat-group (min-width: 1200px) {
   .root {
     grid-template-columns: repeat(var(--basalt-stat-group-cols-lg), minmax(0, 1fr));
   }
@@ -40,14 +71,14 @@
   padding-inline-start: var(--vx-space-stack-md);
 }
 
-@media (max-width: 47.99375em) {
+@container basalt-stat-group (max-width: 767.9px) {
   .root[data-divided] > *:nth-child(2n + 1) {
     border-inline-start: 0;
     padding-inline-start: 0;
   }
 }
 
-@media (min-width: 48em) and (max-width: 74.99375em) {
+@container basalt-stat-group (min-width: 768px) and (max-width: 1199.9px) {
   .root[data-divided][data-sm-cols='2'] > *:nth-child(2n + 1),
   .root[data-divided][data-sm-cols='3'] > *:nth-child(3n + 1) {
     border-inline-start: 0;
@@ -55,7 +86,7 @@
   }
 }
 
-@media (min-width: 75em) {
+@container basalt-stat-group (min-width: 1200px) {
   .root[data-divided][data-cols='2'] > *:nth-child(2n + 1),
   .root[data-divided][data-cols='3'] > *:nth-child(3n + 1),
   .root[data-divided][data-cols='4'] > *:nth-child(4n + 1),
@@ -64,3 +95,48 @@
     padding-inline-start: 0;
   }
 }
+
+/*
+ * 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` also cannot parse the `@container` blocks above, 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-stat-group-cols-sm), minmax(0, 1fr));
+    }
+  }
+
+  @media (min-width: 75em) {
+    .root {
+      grid-template-columns: repeat(var(--basalt-stat-group-cols-lg), minmax(0, 1fr));
+    }
+  }
+
+  @media (max-width: 47.99375em) {
+    .root[data-divided] > *:nth-child(2n + 1) {
+      border-inline-start: 0;
+      padding-inline-start: 0;
+    }
+  }
+
+  @media (min-width: 48em) and (max-width: 74.99375em) {
+    .root[data-divided][data-sm-cols='2'] > *:nth-child(2n + 1),
+    .root[data-divided][data-sm-cols='3'] > *:nth-child(3n + 1) {
+      border-inline-start: 0;
+      padding-inline-start: 0;
+    }
+  }
+
+  @media (min-width: 75em) {
+    .root[data-divided][data-cols='2'] > *:nth-child(2n + 1),
+    .root[data-divided][data-cols='3'] > *:nth-child(3n + 1),
+    .root[data-divided][data-cols='4'] > *:nth-child(4n + 1),
+    .root[data-divided][data-cols='5'] > *:nth-child(5n + 1) {
+      border-inline-start: 0;
+      padding-inline-start: 0;
+    }
+  }
+}

package/src/dashboard/stat-group.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
 }
 export default classes