basalt-ui 1.29.2 → 1.30.1

package/dist/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/dist/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/dist/guard/index.d.ts

@@ -90,6 +90,23 @@ export declare function unmatchedExemptPatterns(cfg: GuardConfig, scannedRelPath
  * with the plugin's own `KNOWN_RULE_IDS`; `configs/oxlint-plugin.test.ts` asserts the two agree.
  */
 export declare const PLUGIN_RULE_IDS: ReadonlySet<string>;
+/**
+ * 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 declare const WAIVER_ID_ALIASES: Readonly<Record<string, readonly string[]>>;
 /**
  * The exact first line of every stylesheet the CLI emits — the contract between `basalt-ui
  * tokens:css` / `fonts:css` and this scanner, and the single source of truth for it (`src/cli`
@@ -279,13 +296,13 @@ export declare const GUARD_RULES: {
         readonly kind: "in-body-page-title";
         readonly pattern: RegExp;
         readonly appliesTo: (relPath: string) => boolean;
-        readonly 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.";
+        readonly message: "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.";
     };
     readonly 'raw-selection-control': {
         readonly kind: "raw-selection-control";
         readonly pattern: RegExp;
         readonly appliesTo: (relPath: string) => boolean;
-        readonly 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.";
+        readonly 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. 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.";
     };
     readonly 'inline-font-size': {
         readonly kind: "inline-font-size";

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

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

package/dist/guard/index.js

@@ -158,6 +158,16 @@ const RAW_FORM_CONTROL = /<(?:input|select|textarea)\b/g;
 const RAW_FORM_CONTROL_TAG = /<(?:input|select|textarea)\b(?:=>|[^>])*?>/g;
 const PAGE_TITLE_TAG = /<Title(?![\w.])(?:=>|[^>])*?>/g;
 const PAGE_TITLE_ORDER_PROP = /\border\s*=\s*\{\s*([12])\s*\}/;
+const PAGE_TITLE_BRACED_RUN = /\{[^{}]*(?:\{[^{}]*\}[^{}]*)*\}/g;
+const PAGE_TITLE_LAUNDERED_LITERAL = /^\s*['"`][^'"`]*['"`]\s*$/;
+function titleBodyNamesThePage(body) {
+  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() !== "";
+}
 const RAW_SELECTION_CONTROL_TAG = /<(SegmentedControl|Select|MultiSelect|NativeSelect|DatePickerInput|DateInput|TagsInput|Chip\.Group)(?![\w])(?:=>|[^>])*?>/g;
 const PROSE_CONTEXT_TAG = /<(?:Prose|ArticleLayout|Modal|Drawer)(?![\w])/;
 const CONTROL_HOST_TAG = /<(?:SettingsRow|Modal|Drawer|Popover\.Dropdown|Menu\.Dropdown|Composer|FilterSet|PageAside|PanelRow)(?![\w])/;
@@ -198,8 +208,8 @@ const DEFAULT_GUARD_CONFIG = {
 const GRACE_PERIOD_KINDS = {
   "raw-selection-control": {
     since: "1.26.0",
-    promote: "1.30.0",
-    why: 'new in the wave-6 control guards (docs/CONTROLS-SPEC.md \xA76, law C1). The text lane cannot see ancestry, so "no home" is approximated by a 12-line host-tag window \u2014 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 \u2014 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 \u2014 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.'
+    promote: "1.31.0",
+    why: 'new in the wave-6 control guards (docs/CONTROLS-SPEC.md \xA76, law C1). The text lane cannot see ancestry, so "no home" is approximated by a 12-line host-tag window \u2014 the loosest reading in the guard, and the reason this one lands warn rather than error even though its 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 \u2014 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 \u2014 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.'
   }
 };
 function severityOf(kind, cfg) {
@@ -321,6 +331,10 @@ const PLUGIN_RULE_IDS = /* @__PURE__ */ new Set([
   // Mirrored by the plugin's own `RETIRED_RULE_IDS`.
   "query-dual-import"
 ]);
+const WAIVER_ID_ALIASES = {
+  "control-outside-home": ["raw-selection-control"],
+  "raw-selection-control": ["control-outside-home"]
+};
 const MIN_ALLOW_REASON_LENGTH = 4;
 function parseAllowAnnotation(rest, scope) {
   const rules = [];
@@ -445,6 +459,7 @@ function collectAllowAnnotations(lines, codeLines, allowComment, syntax) {
 }
 function annotationCovers(annotation, kind) {
   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;
 }
@@ -868,7 +883,7 @@ const GUARD_RULES = {
     // handled inline (full-text tag-scoped scan); entry keeps the registry complete
     // JSX-tag-shaped (`<Title order={1}>`) — never appears in CSS text.
     appliesTo: (relPath) => !relPath.endsWith(".css"),
-    message: "In-body page title \u2014 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 \u2014 one id, two lanes, so one theme-allow covers both."
+    message: "In-body page title \u2014 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 \u2014 {doc.title}, {RANK_LABEL[rank]} \u2014 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 \u2014 one id, two lanes, so one theme-allow covers both."
   },
   "raw-selection-control": {
     kind: "raw-selection-control",
@@ -876,7 +891,7 @@ const GUARD_RULES = {
     // handled inline (full-text tag-scoped scan + host window)
     // JSX-tag-shaped (`<Select …>`) — never appears in CSS text.
     appliesTo: (relPath) => !relPath.endsWith(".css"),
-    message: "Raw selection control with no home \u2014 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\u2013C3). 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 \u2014 where the two disagree, the plugin is right."
+    message: "Raw selection control with no home \u2014 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\u2013C3). 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 \u2014 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 \u2014 where the two disagree, the plugin is right."
   },
   "inline-font-size": {
     kind: "inline-font-size",
@@ -924,6 +939,9 @@ function checkSource(text, relPath, cfg) {
   for (const annotation of fileScoped) {
     for (const rule of annotation.rules) {
       if (Object.hasOwn(GUARD_RULES, rule)) fileWaived.add(rule);
+      for (const alias of WAIVER_ID_ALIASES[rule] ?? []) {
+        if (Object.hasOwn(GUARD_RULES, alias)) fileWaived.add(alias);
+      }
     }
   }
   const isAllowed = (line, kind) => fileWaived.has(kind) || annotationsCover(waivers.get(line - 1), kind);
@@ -1119,6 +1137,10 @@ function checkSource(text, relPath, cfg) {
     for (const m of codeText.matchAll(PAGE_TITLE_TAG)) {
       const order = PAGE_TITLE_ORDER_PROP.exec(m[0]);
       if (order === null) continue;
+      if (m[0].endsWith("/>")) continue;
+      const bodyStart = (m.index ?? 0) + m[0].length;
+      const closeAt = codeText.indexOf("</Title>", bodyStart);
+      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;
@@ -1212,6 +1234,7 @@ export {
   NEUTRALIZED_ALLOW_TOKEN,
   PLUGIN_RULE_IDS,
   TOKENS_ONLY_DISABLED_KINDS,
+  WAIVER_ID_ALIASES,
   checkSource,
   findAllowAnnotations,
   guardKindRemedy,

package/dist/index.d.ts

@@ -11,6 +11,15 @@ export { createBasaltTheme, baseTheme, cssVariablesResolver } from './theme/inde
 export type { BasaltFontsConfig, CreateBasaltThemeOptions } from './theme/index.js';
 export { CTL_THEME, CtlSlot } from './theme/index.js';
 export type { CtlSlotProps } from './theme/index.js';
+/**
+ * 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/index.js';
 export { ThemeToggle, type ThemeToggleProps } from './theme/theme-toggle.js';
 /**
  * The action vocabulary every home's `actions` slot takes (`docs/CONTROLS-SPEC.md` §2.1). The

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -9,6 +9,7 @@ import {
 } from "./common/index.js";
 import { createBasaltTheme, baseTheme, cssVariablesResolver } from "./theme/index.js";
 import { CTL_THEME, CtlSlot } from "./theme/index.js";
+import { useBasaltSpacing } from "./theme/index.js";
 import { ThemeToggle } from "./theme/theme-toggle.js";
 import {
   ActionGroup
@@ -148,6 +149,7 @@ export {
   toErrorMessage,
   unwrap,
   useAgentThreadRuns,
+  useBasaltSpacing,
   useBreakpoint,
   useConnectivity
 };

package/dist/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/dist/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/dist/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/dist/shell/app-mobile-nav.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-mobile-nav.d.ts","sourceRoot":"","sources":["../../src/shell/app-mobile-nav.tsx"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAc,YAAY,EAAa,MAAM,OAAO,CAAA;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAGlD,OAAO,KAAK,EACV,eAAe,EAEf,cAAc,EAEd,YAAY,EAKb,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAmB/C,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG;IACzC,kFAAkF;IAClF,KAAK,EAAE,cAAc,CAAA;IACrB,MAAM,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACpC;;wEAEoE;IACpE,OAAO,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAA;IACxC,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,GAAG,SAAS,CAAA;IAClD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,YAAY,EAAE,GAAG,SAAS,CAAA;CACpC,CAAA;AAwGD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,kBAAkB,GAAG,SAAS,GAAG,MAAM,CAE/E;AAyFD,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,MAAM,EACN,OAAO,EACP,iBAAiB,EACjB,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,cAAc,GAAG,YAAY,CAmY/B"}
+{"version":3,"file":"app-mobile-nav.d.ts","sourceRoot":"","sources":["../../src/shell/app-mobile-nav.tsx"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAc,YAAY,EAAa,MAAM,OAAO,CAAA;AAEhE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAGlD,OAAO,KAAK,EACV,eAAe,EAEf,cAAc,EAEd,YAAY,EAKb,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AACzD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAA;AAoB/C,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG;IACzC,kFAAkF;IAClF,KAAK,EAAE,cAAc,CAAA;IACrB,MAAM,CAAC,EAAE,eAAe,GAAG,SAAS,CAAA;IACpC;;wEAEoE;IACpE,OAAO,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAA;IACxC,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,GAAG,SAAS,CAAA;IAClD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,YAAY,EAAE,GAAG,SAAS,CAAA;CACpC,CAAA;AAwGD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,kBAAkB,GAAG,SAAS,GAAG,MAAM,CAE/E;AA6ED,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,MAAM,EACN,OAAO,EACP,iBAAiB,EACjB,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,cAAc,GAAG,YAAY,CA2hB/B"}