basalt-ui 1.30.2 → 1.31.0

package/src/data/virtual-list.tsx

@@ -23,7 +23,9 @@ import type { ReactNode, Ref } from 'react'
 import { cx } from '../common/props'
 import type { BasaltProps, SlotStylesProps } from '../common/props'
 import { BASALT_PREFIX } from '../common/errors'
+import { HIT_COARSE } from '../common/hit-floor'
 import { assertRequiredProps, useValidateProps } from '../common/validate'
+import { readMediaQuery } from '../common/use-media-query'
 import { ErrorState } from '../dashboard/query-state'
 import type { QueryStateLike } from '../dashboard/query-state'
 import { dataQueryBranch } from './query-branch'
@@ -112,6 +114,16 @@ export type BasaltVirtualListProps<T> = BasaltProps &
     ref?: Ref<BasaltVirtualListHandle>
   }
 
+/** `estimateSize` sets every row's rendered height — there is no per-row measurement in this
+ * component — so a value under the coarse floor understates the touch target for every row. */
+function shortRowHeightMessage(estimateSize: number): string {
+  return (
+    `${BASALT_PREFIX} BasaltVirtualList: "estimateSize" is ${estimateSize}px under a coarse ` +
+    '(touch) pointer — every row renders at this height, below the `--vx-hit` floor (44px, WCAG ' +
+    '2.5.5). Raise "estimateSize" to at least 44, or pad the row content so it clears the floor.'
+  )
+}
+
 /**
  * Imperative escape hatch for {@link BasaltVirtualList} — the virtualizer's own `scrollToIndex` /
  * `scrollToOffset` / `scrollToEnd` were otherwise unreachable, since the component owns the
@@ -198,6 +210,25 @@ export function BasaltVirtualList<T>(props: BasaltVirtualListProps<T>) {
     [query === undefined, props.isLoading === undefined],
   )
 
+  // A coarse pointer only — a mouse user's row height is a layout choice, not an accessibility
+  // floor. `estimateSize` sets every row's actual rendered height (this component never measures
+  // one), so a value under the floor is not a false positive to catch later.
+  //
+  // Reads `props.estimateSize`, not the destructured `estimateSize` above: the shipped DEFAULT
+  // (40) is itself under `HIT_COARSE` (44), so warning off the destructured value fired on every
+  // coarse-pointer mount that never named `estimateSize` at all. Only a caller's OWN too-short
+  // value is a defect to report.
+  useValidateProps(
+    'BasaltVirtualList',
+    () =>
+      props.estimateSize !== undefined &&
+      props.estimateSize < HIT_COARSE &&
+      readMediaQuery('(pointer: coarse)', false)
+        ? shortRowHeightMessage(props.estimateSize)
+        : null,
+    [props.estimateSize],
+  )
+
   const parentRef = useRef<HTMLDivElement>(null)
 
   const rowVirtualizer = useVirtualizer({

package/src/forms/form-layout.module.css

@@ -6,8 +6,17 @@
  * deliberately rather than forked: a form row and a `SettingsRow` are the same shape at the same
  * rhythm, and a second pair of numbers is how the two drift apart.
  *
- * The `47.99375em` literal is the `sm` breakpoint (law C9 — the responsive swap is CSS, never a JS
- * media query). A `@media` condition cannot read a custom property, so the number is written.
+ * The label/control swap keys on the row's OWN measured width via `@container`, not the viewport
+ * (law C9 — the responsive swap is CSS, never a JS media query, but a viewport `@media` answers the
+ * wrong question here the same way `StatGroup`'s used to: a narrow column can leave a row too
+ * tight for two 250px+ cells well before the viewport itself crosses `sm`, and a wide one — a
+ * landscape phone, a split pane — can afford two columns well under it). `.row` establishes the
+ * containment and `.grid` is the queried child, the same split `StatGroup`'s `.container`/`.root`
+ * uses — a container cannot reliably query ITSELF for a layout-affecting property (measured here:
+ * Chrome silently keeps the un-queried value even once the container's own width crosses the
+ * condition), only a descendant. The `599.9px`/`47.99375em` literals: 600px is roughly the point
+ * two ~250px+ cells stop feeling cramped; `@container`/`@media` conditions cannot read a custom
+ * property, so both are written numbers, not `--vx-*` refs.
  */
 
 /* ── FormSection ─────────────────────────────────────────────────────────────────────────────── */
@@ -32,6 +41,11 @@
  * itself against a one-line input.
  */
 .row {
+  container-type: inline-size;
+  container-name: basalt-form;
+}
+
+.grid {
   display: grid;
   grid-template-columns: minmax(0, 1fr) minmax(0, 1.4fr);
   align-items: start;
@@ -80,14 +94,25 @@
   color: var(--vx-status-bad);
 }
 
-/* The phone twin: the control needs the full width, so the label goes above it. */
-@media (max-width: 47.99375em) {
-  .row {
+/* The narrow twin: the control needs the full width, so the label goes above it. */
+@container basalt-form (max-width: 599.9px) {
+  .grid {
     grid-template-columns: minmax(0, 1fr);
     gap: var(--vx-space-stack-xs);
   }
 }
 
+/* Pre-container-query fallback (Safari < 16, Chrome < 106, Firefox < 110) — the old viewport law,
+ * reachable only where `@container` itself cannot parse (same reasoning as `stat-group.module.css`). */
+@supports not (container-type: inline-size) {
+  @media (max-width: 47.99375em) {
+    .grid {
+      grid-template-columns: minmax(0, 1fr);
+      gap: var(--vx-space-stack-xs);
+    }
+  }
+}
+
 /* ── FormGroup ───────────────────────────────────────────────────────────────────────────────── */
 
 /* Same UA reset as `.control`, same reason. */

package/src/forms/form-layout.module.css.d.ts

@@ -6,6 +6,7 @@ declare const classes: {
   readonly section: string
   readonly sectionBody: string
   readonly row: string
+  readonly grid: string
   readonly rowLabel: string
   readonly label: string
   readonly hint: string

package/src/forms/form-layout.tsx

@@ -185,17 +185,19 @@ export function FormRow(props: FormRowProps) {
       className={cx(classes.row, classNames?.root, className)}
       {...(style !== undefined && { style })}
     >
-      <div className={cx(classes.rowLabel, classNames?.label)}>
-        <label className={classes.label} {...(htmlFor !== undefined && { htmlFor })}>
-          {label}
-          <RequiredMark required={required} />
-        </label>
-        {hint !== undefined && <span className={classes.hint}>{hint}</span>}
+      <div className={classes.grid}>
+        <div className={cx(classes.rowLabel, classNames?.label)}>
+          <label className={classes.label} {...(htmlFor !== undefined && { htmlFor })}>
+            {label}
+            <RequiredMark required={required} />
+          </label>
+          {hint !== undefined && <span className={classes.hint}>{hint}</span>}
+        </div>
+        <fieldset className={cx(classes.control, classNames?.control)} disabled={disabled}>
+          {children}
+          <FieldError error={error} />
+        </fieldset>
       </div>
-      <fieldset className={cx(classes.control, classNames?.control)} disabled={disabled}>
-        {children}
-        <FieldError error={error} />
-      </fieldset>
     </div>
   )
 }

package/src/guard/index.ts

@@ -1,7 +1,7 @@
 /**
  * ./guard — headless policy core. Mantine-free, dependency-free.
  *
- * GUARD_RULES: the closed registry of all 26 violation kinds.
+ * GUARD_RULES: the closed registry of all 27 violation kinds.
  * checkSource:  pure (text, relPath, cfg) → Finding[]. No FS, no walk, no console.
  */
 import type { Finding, GuardConfig, GuardKind, GuardSeverity } from './types'
@@ -113,6 +113,126 @@ const SHADOW_IS_COMPOSED = /var\(|\$\{/
 const CSS_SURFACE_RADIUS = /(?<![\w-])border-radius\s*:\s*([^;}]+)/g
 const CSS_SURFACE_SHADOW = /(?<![\w-])box-shadow\s*:\s*([^;}]+)/g
 
+/** One numeric width literal — the value half of every shape `CSS_WIDTH_MEDIA_QUERY` matches. */
+const CSS_WIDTH_NUM = '[\\d.]+(?:px|em|rem|vw)'
+
+/**
+ * A width `@media` condition — `(min-width: 52.5em)` / `(max-width: 767.9px)`, plus every range-
+ * comparison spelling CSS lets an author use instead (the SAME condition, just spelled
+ * differently): keyword-first (`width >= 600px`), value-first (`600px <= width`), and CHAINED, both
+ * sides at once (`400px <= width <= 700px`, `700px >= width >= 400px`). A regex that only covered
+ * the keyword-first comparison form let every value-first or chained range slip past unflagged —
+ * the exact shape `width >= 600px` catches that `600px <= width` (the same boundary, spelled the
+ * other way round) does not. The size-class axis
+ * (`docs/DESIGN-CORE.md` § Layout, elevation, shapes) names its own home (`shell/**`, `@media`
+ * against `SIZE_CLASSES` literals); anywhere else a hard-coded viewport breakpoint has skipped the
+ * framework's one seam for it (`useSizeClass()`, or the derived `theme.breakpoints`). See
+ * `raw-breakpoint`, the oxlint plugin's
+ * AST-side twin for the same law over JSX (`configs/oxlint-plugin.js`) — this is the CSS-text half,
+ * the shape the plugin cannot see. New file type for this check (CSS, same reasoning as
+ * `css-raw-surface`), so it lands under its own kind at `warn` for one minor rather than widening an
+ * existing one.
+ */
+const CSS_WIDTH_MEDIA_QUERY = new RegExp(
+  '@media[^{]*\\(\\s*(?:' +
+    // keyword form: min-width: N / max-width: N
+    `(?:min|max)-width\\s*:\\s*${CSS_WIDTH_NUM}` +
+    // width-first comparison, with an optional CHAINED second boundary on the other side:
+    // width OP N, or N OP width OP N
+    `|(?:${CSS_WIDTH_NUM}\\s*[<>]=?\\s*)?width\\s*[<>]=?\\s*${CSS_WIDTH_NUM}` +
+    // value-first comparison with NO trailing boundary: N OP width. The lookahead excludes the
+    // chained shape (already matched whole by the alternative above) so this only fires for the
+    // plain value-first form.
+    `|${CSS_WIDTH_NUM}\\s*[<>]=?\\s*width(?!\\s*[<>]=?\\s*${CSS_WIDTH_NUM})` +
+    ')\\s*\\)',
+  'g',
+)
+
+/**
+ * An `@container` condition — the declared NAME (optional: `@container (min-width: …)` with no
+ * name is legal CSS, scoping to the nearest ancestor container regardless of its name) plus every
+ * raw boundary across the WHOLE at-rule, chained `and (...)` clauses included
+ * (`@container basalt-stat-group (min-width: 768px) and (max-width: 1199.9px)` —
+ * `stat-group.module.css` ships exactly this shape). Capturing only the first parenthesized clause
+ * would silently skip every boundary after the first `and`; group 2 here is the full run of
+ * `(...)`/`and` text so `CSS_CONTAINER_LITERAL`'s own `matchAll` below finds all of them.
+ */
+const CSS_CONTAINER_QUERY = /@container(?:\s+([\w-]+))?\s*((?:\([^)]*\)\s*(?:and\s*)?)+)/g
+
+/**
+ * One numeric boundary inside an `@container` condition's parens, in either syntax CSS allows: the
+ * range-media form (`min-width:`/`max-width:`) and the newer comparison form (`width >= …`).
+ */
+const CSS_CONTAINER_LITERAL = /(?:min-width|max-width|width)\s*(?:[<>]=?|:)\s*([\d.]+)(px|em)?/g
+
+/**
+ * A `(pointer: …)` / `(any-pointer: …)` media condition whose value is neither sanctioned tier.
+ * `coarse` is the touch tier (`--vx-hit` 44px); `fine` is its standard companion for a hover-only
+ * affordance (`(hover: hover) and (pointer: fine)`), so both are legal — anything else is not.
+ */
+const CSS_NON_COARSE_POINTER_QUERY =
+  /\(\s*(?:any-)?pointer\s*:\s*(?!(?:coarse|fine)\b)[a-z-]+\s*\)/g
+
+/**
+ * The `@container` names the container-class axis declares — a consumer container carrying any
+ * other name has invented its own container-query breakpoint instead of using the framework's.
+ * `basalt-card` is the one shipped today (`src/dashboard/section.module.css`);
+ * `basalt-form`/`basalt-main`/`basalt-grid` are the declared remaining three, reserved here so a
+ * consumer adopting one ahead of the framework does not immediately trip this guard.
+ *
+ * Two container names already shipped ahead of this table — `basalt-stat-group` and
+ * `basalt-widget-grid` (`src/tokens/breakpoint-literals.test.ts`'s own `LEGACY_CONTAINER_LITERALS`
+ * names them) — predate the declared table and are deliberately NOT in this set: they surface as
+ * `warn` findings against basalt's own source the same way any other kind's incumbent violations do
+ * at grace time, rather than being silently grandfathered into a shipped rule's allowlist.
+ */
+const DECLARED_CONTAINER_NAMES = new Set([
+  'basalt-card',
+  'basalt-form',
+  'basalt-main',
+  'basalt-grid',
+])
+
+/**
+ * `CONTAINER_CLASSES` (`src/tokens/size-classes.ts`) boundaries, duplicated per the `CTL_THEME_TAGS`
+ * convention in the oxlint plugin — this module is dependency-free by contract (file header) and
+ * must not import `../tokens`. Pinned against the real table by `check-source.test.ts`. Judged only
+ * against `basalt-card`: the other three declared names have no shipped numeric table yet. `0` is
+ * the container's own floor, not a class boundary, but `(width >= 0px)` is a legitimate idiom for
+ * "scope this rule to the container, whatever its width" (`widget-header.module.css`'s `cqi` clamp)
+ * — allowed for that reason, not because it names a real `CONTAINER_CLASSES` step.
+ */
+const CONTAINER_CLASS_LITERALS_PX = new Set([0, 240, 239.9, 480, 479.9, 800, 799.9])
+
+/**
+ * `SIZE_CLASSES`' two boundaries (840/1200px) as the em literals `theme.breakpoints`/`shell/**`
+ * actually write (`size-classes.ts`'s `toEm`/`sizeClassMaxEm`, 16px root): `52.5em`/`75em` (the
+ * `min-width` boundaries) and their `max-width` companions one hundredth of a px short,
+ * `52.49375em`/`74.99375em`. The size-class axis names `shell/**` its one CSS home — a width
+ * `@media` there against one of these four is the framework's own sanctioned implementation of the
+ * axis, not a raw breakpoint a consumer invented.
+ */
+const SIZE_CLASS_LITERALS = new Set(['52.5em', '75em', '52.49375em', '74.99375em'])
+
+/** The size-class axis's one CSS home is `shell/**`. Any `shell/`-pathed CSS, basalt's own or a
+ * consumer's own shell chrome alike — not a name list, because a consumer's shell directory is
+ * never one of `SHELL_HOME_NAMES`' three (or four) declared components. */
+const SHELL_CSS_PATH = /(?:^|\/)shell\//
+
+function isSanctionedShellMediaQuery(relPath: string, query: string): boolean {
+  if (!SHELL_CSS_PATH.test(relPath)) return false
+  // `query` is always one whole match of `CSS_WIDTH_MEDIA_QUERY`, which only ever matches a WIDTH
+  // condition — keyword (`min-width:`/`max-width:`), comparison (`width >= N` / `N <= width`), or
+  // chained (`N <= width <= N`) — so every `px`/`em`/`rem`/`vw`-suffixed literal anywhere in it IS a
+  // width boundary, regardless of which of those spellings produced it. Extracting every literal
+  // this way (rather than a keyword-only `(?:min|max)-width:` scan) is what lets this understand
+  // the comparison/chained spellings too, with no shape-specific regex of its own. All four units
+  // are captured (not `em` only) so a `px` width — never a `SIZE_CLASS_LITERALS` member — correctly
+  // fails the check below, rather than `.every()` vacuously passing on an empty match.
+  const widths = query.match(new RegExp(CSS_WIDTH_NUM, 'g')) ?? []
+  return widths.length > 0 && widths.every((w) => SIZE_CLASS_LITERALS.has(w))
+}
+
 /** The largest CSS radius literal treated as a sub-scale micro-corner, in px — below the 4px floor. */
 const MICRO_RADIUS_CEILING_PX = 3
 /** Radius values that name a SHAPE rather than a surface corner — a circle and the pill idiom. */
@@ -740,8 +860,9 @@ 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.31.0',
+    promote: '1.32.0',
     why:
+      'Extended 1.31.0 -> 1.32.0 at the 1.31.0 release: the basalt tree still carries incumbents (data-table, notifications center, theme-lab) and the argo sweep has not run. ' +
       '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 ' +
@@ -757,6 +878,18 @@ export const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, GraceEntry>> = {
       'makes a rule satisfiable gives nobody a window to act. 1.31.0 is when the 29 are ' +
       're-measured against that number.',
   },
+  'raw-media-query': {
+    since: '1.31.0',
+    promote: '1.32.0',
+    why:
+      'new in the wave-11 responsive/touch guards — the CSS-text ' +
+      "twin of the oxlint plugin's `basalt/raw-breakpoint`. Reaching CSS is a NEW file type for this " +
+      "check, same reasoning as `css-raw-surface`, and basalt's own `src/dashboard/stat-group.module" +
+      '.css` / `widget-grid.module.css` already declare `@container` names (`basalt-stat-group`, ' +
+      "`basalt-widget-grid`) outside the declared four-name table, plus `shell/**`'s own " +
+      "legitimate width `@media` rules — real incumbents in basalt's own tree at ship time, so this " +
+      'ships warn rather than error from the start. Promotes with its AST twin at 1.32.0.',
+  },
 }
 
 /** A kind's effective severity: consumer override first, then the grace table, then `error`. */
@@ -950,6 +1083,10 @@ export const PLUGIN_RULE_IDS: ReadonlySet<string> = new Set([
   'visx-tooltip',
   'token-layer-boundary',
   'no-import-meta-env',
+  // AST-only, same reason as `bound-control-outside-home`: a responsive-object prop, a shell-home
+  // exemption and a hook import all need the import graph and JSX ancestry, neither of which a
+  // 12-line text window has. `raw-media-query` is its CSS-text twin and lives in `GUARD_RULES`.
+  'raw-breakpoint',
   // These three honour `basalt-agent-allow`, never `theme-allow` — but they are still REAL ids, so
   // a `theme-allow ai-sdk-major` must parse as a (useless) scoped annotation rather than as prose.
   'agent-resume-guard',
@@ -1832,7 +1969,7 @@ type GuardRule = {
 }
 
 /**
- * The closed registry of all 26 guard kinds. The triad test asserts
+ * The closed registry of all 27 guard kinds. The triad test asserts
  * `surface.guardKinds ⊆ keyof GUARD_RULES` at runtime.
  *
  * raw-surface, raw-html-layout, and sub-16-input-font are handled inline in checkSource
@@ -2066,6 +2203,14 @@ export const GUARD_RULES = {
     message:
       'Raw font-size literal — route through VX.text.* (numbers) / --vx-text-* (CSS), or the Mantine fz token. Same rule the oxlint plugin enforces as basalt/no-raw-font-size; this is the half a check-theme-only CI can see.',
   },
+  'raw-media-query': {
+    kind: 'raw-media-query',
+    pattern: CSS_WIDTH_MEDIA_QUERY, // handled inline (three independent shapes); entry keeps the registry complete
+    // CSS-only: a width @media, an @container name/literal or a non-coarse pointer query has no JSX
+    // spelling — the AST-side twin of this law is the oxlint plugin's basalt/raw-breakpoint.
+    appliesTo: (relPath) => relPath.endsWith('.css'),
+    message: `Raw viewport/container breakpoint in CSS — a width @media belongs to shell/** against SIZE_CLASSES (useSizeClass() is the JS seam); an @container name must be one of ${[...DECLARED_CONTAINER_NAMES].join(' / ')} at a boundary in ${[...CONTAINER_CLASS_LITERALS_PX].map((px) => `${px}px`).join(' / ')}; and a pointer query other than (pointer: coarse) or (pointer: fine) has no framework meaning. Same law the oxlint plugin enforces as basalt/raw-breakpoint over JSX; this is the CSS half.`,
+  },
 } as const satisfies Record<GuardKind, GuardRule>
 
 /**
@@ -2312,6 +2457,41 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
       }
     }
 
+    // raw-media-query: three independent CSS-only shapes — a width @media, an @container
+    // name/literal outside the declared table, and a pointer query that is neither coarse nor fine.
+    if (ruleApplies('raw-media-query', relPath)) {
+      for (const m of line.matchAll(CSS_WIDTH_MEDIA_QUERY)) {
+        if (isSanctionedShellMediaQuery(relPath, m[0])) continue
+        push('raw-media-query', i + 1, m[0].trim())
+      }
+      for (const m of line.matchAll(CSS_CONTAINER_QUERY)) {
+        const name = m[1] ?? ''
+        const body = m[2] ?? ''
+        // An UNNAMED `@container (...)` is legal CSS (scopes to the nearest ancestor container
+        // regardless of its name) — only a name that IS present and NOT in the declared table is a
+        // violation; the empty name itself never is.
+        if (name !== '' && !DECLARED_CONTAINER_NAMES.has(name)) {
+          push('raw-media-query', i + 1, m[0].trim())
+          continue
+        }
+        // Literal boundaries are judged against `basalt-card`'s own table (see
+        // `CONTAINER_CLASS_LITERALS_PX`'s doc) — an unnamed query has no OTHER table to judge
+        // against, so it is judged against this one too; the other three declared names stay
+        // unjudged until they ship their own.
+        if (name !== '' && name !== 'basalt-card') continue
+        for (const lit of body.matchAll(CSS_CONTAINER_LITERAL)) {
+          const px = lit[2] === 'em' ? Number(lit[1]) * ROOT_FONT_SIZE_PX : Number(lit[1])
+          if (!CONTAINER_CLASS_LITERALS_PX.has(px)) {
+            push('raw-media-query', i + 1, m[0].trim())
+            break
+          }
+        }
+      }
+      for (const m of line.matchAll(CSS_NON_COARSE_POINTER_QUERY)) {
+        push('raw-media-query', i + 1, m[0].trim())
+      }
+    }
+
     // off-system-surface-var — pattern + gating from GUARD_RULES.
     if (GUARD_RULES['off-system-surface-var'].enabled!(cfg)) {
       for (const m of line.matchAll(GUARD_RULES['off-system-surface-var'].pattern as RegExp)) {

package/src/guard/types.ts

@@ -1,7 +1,7 @@
 /**
  * Guard types — Mantine-free, dependency-free (zero imports beyond TS types).
  *
- * GuardKind is the closed set of 26 violation kinds the theme guard can emit — `unframed-chart`
+ * GuardKind is the closed set of 27 violation kinds the theme guard can emit — `unframed-chart`
  * retired at the C2 consolidation wave: its only case (a hand-authored `<ChartLegend items={[...]}>`
  * array literal) is fully subsumed by the oxlint plugin's `basalt/chart-legend-literal`, which also
  * catches the `.map()`-over-a-non-series form the regex never could. `'unframed-chart'` stays a
@@ -11,7 +11,7 @@
  * GuardConfig is the per-run configuration that drives checkSource.
  */
 
-/** The 26 theme-guard violation kinds. */
+/** The 27 theme-guard violation kinds. */
 export type GuardKind =
   | 'raw-hex'
   | 'raw-color-fn'
@@ -39,6 +39,7 @@ export type GuardKind =
   | 'hidden-inline-style'
   | 'in-body-page-title'
   | 'raw-selection-control'
+  | 'raw-media-query'
 
 /**
  * How hard a finding lands. `error` fails the build; `warn` reports and passes.

package/src/index.ts

@@ -87,6 +87,8 @@ export {
   type PageAsideSlot,
   useBreakpoint,
   type BreakpointName,
+  useSizeClass,
+  type SizeClass,
   PageTitle,
   type PageTitleProps,
   type PageTitleSlot,

package/src/provider/index.tsx

@@ -35,8 +35,12 @@ import type { BuildPaletteOpts } from '../tokens'
 import { isDefaultDeriveConfig } from '../tokens/derive'
 import { buildPaletteData } from '../tokens/palette'
 import { isDev } from '../common/is-dev'
+import { useMediaQuery } from '../common/use-media-query'
 import { registerColorSchemeSetter } from '../commands/shell-bridge'
+import { useIsomorphicLayoutEffect } from '../common/isomorphic-layout-effect'
 import { PageTitle } from '../shell/page-title'
+import { SizeClassHintContext } from '../shell/use-size-class'
+import type { SizeClass } from '../shell/use-size-class'
 
 /**
  * Where an error surfaced — drives consumer routing (a render error vs a global rejection differ).
@@ -108,6 +112,14 @@ export type BasaltProviderProps = {
    * `ConnectivityProvider`).
    */
   connectivity?: Omit<ConnectivityProviderProps, 'children'>
+  /**
+   * The size class `useSizeClass()` reports on the server and during hydration, before `matchMedia`
+   * can answer. Default `'compact'` (mobile-first). An SSR app that knows the device class (UA
+   * hint, cookie) passes it so the first frame already matches. An SSR desktop app SHOULD pass it:
+   * without it the first paint is `'compact'`, and `PageAside`/`ThreadWorkspace` remount after
+   * hydration when the real class lands.
+   */
+  sizeClassHint?: SizeClass
 } & Omit<MantineProviderProps, 'children' | 'theme' | 'defaultColorScheme' | 'cssVariablesResolver'>
 
 // ── Default error handler ─────────────────────────────────────────────────────────────────────────
@@ -228,6 +240,42 @@ export function composeInjectedCss(
   return [base, fontsCss, radiusCss, densityCss].filter(Boolean).join('\n')
 }
 
+// ── Host attribute ────────────────────────────────────────────────────────────────────────────────
+
+/** Mount count backing `useHostAttribute`'s ref-counted removal — see that function's doc. */
+let hostAttributeCount = 0
+
+/**
+ * `data-basalt-host` on `<html>` — the one place a `display-mode` query is read; CSS keys off it.
+ *
+ * The layout effect below lands the attribute before the browser paints the CLIENT render — true
+ * only for a client-rendered app. An SSR'd document paints its server HTML (with no
+ * `data-basalt-host` yet, since `display-mode` is a client-only read) before hydration ever reaches
+ * this effect, so a PWA can still flash web chrome across that server-to-hydration gap; this only
+ * closes the gap between hydration and the next client paint.
+ */
+export function useHostAttribute(): void {
+  const isPwa = useMediaQuery('(display-mode: standalone)', false)
+
+  useIsomorphicLayoutEffect(() => {
+    document.documentElement.setAttribute('data-basalt-host', isPwa ? 'pwa' : 'web')
+  }, [isPwa])
+
+  // Ref-counted across every mounted `BasaltProvider` — mirrors `useDuplicateProviderGuard`'s own
+  // module-level counter just below. A second provider (a nested route wrapping its own, two trees
+  // on one page) unmounting must not rip the attribute out from under a first one still mounted;
+  // only the LAST unmount removes it. Deliberately a SEPARATE effect from the one above: sharing one
+  // effect keyed on `[isPwa]` would decrement (and possibly zero out) this counter on every
+  // `isPwa` change, not only on a genuine unmount.
+  useIsomorphicLayoutEffect(() => {
+    hostAttributeCount++
+    return () => {
+      hostAttributeCount--
+      if (hostAttributeCount === 0) document.documentElement.removeAttribute('data-basalt-host')
+    }
+  }, [])
+}
+
 // ── Inner bridge ──────────────────────────────────────────────────────────────────────────────────
 
 /**
@@ -355,9 +403,11 @@ export function BasaltProvider({
   onError,
   nonce,
   connectivity,
+  sizeClassHint = 'compact',
   ...rest
 }: BasaltProviderProps) {
   useDuplicateProviderGuard()
+  useHostAttribute()
   const errorHandler = onError ?? defaultOnError
 
   // `createBasaltTheme(theme)` — plus, when the theme lab's "Apply" switch is on, the delta of its
@@ -386,7 +436,9 @@ export function BasaltProvider({
           nonce={nonce}
           onError={errorHandler}
         >
-          <ConnectivityProvider {...resolvedConnectivity}>{children}</ConnectivityProvider>
+          <SizeClassHintContext.Provider value={sizeClassHint}>
+            <ConnectivityProvider {...resolvedConnectivity}>{children}</ConnectivityProvider>
+          </SizeClassHintContext.Provider>
         </BasaltBridge>
       </BasaltErrorBoundary>
     </MantineProvider>

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

@@ -36,7 +36,7 @@
 
 /* Below `sm` there is no navbar at all (the bottom bar is the whole nav), so the zone would be a
  * zero-width box holding a hidden toggle. The breadcrumb owns the phone header's lead. */
-@media (max-width: 47.99375em) {
+@media (max-width: 52.49375em) {
   .zone {
     display: none;
   }
@@ -103,7 +103,7 @@
  * (logo + name) hides and the toggle centres. The zone drops its inset so the toggle's centre lands
  * on the rail's icon column rather than 13px right of it.
  */
-@media (min-width: 48em) {
+@media (min-width: 52.5em) {
   .zone[data-collapsed] {
     padding-inline: 0;
   }

package/src/shell/app-brand.tsx

@@ -130,6 +130,7 @@ export function AppBrand({ brand, collapsed, onToggleCollapse, className, style
         size={28}
         visibleFrom="sm"
         className={classes.ghostIcon}
+        data-basalt-hit
         onClick={onToggleCollapse}
         aria-label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
       >

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

@@ -65,12 +65,10 @@
  * 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.
+ * Above `sm` the row is measured, not declared: `.lead` stops growing and `.pageBar` takes every
+ * remaining pixel (`flex: 1 1 0`), so its width IS the room `PageBar` row 1 folds its secondary
+ * actions against (`controls/actions.tsx`, `planBarFold`). `max-width` keeps a long breadcrumb from
+ * starving it.
  */
 .lead {
   display: flex;
@@ -111,6 +109,18 @@
   gap: var(--vx-space-control-gap);
 }
 
+@media (min-width: 52.5em) {
+  .lead {
+    flex: 0 1 auto;
+    max-width: 40%;
+  }
+
+  .pageBar {
+    flex: 1 1 0;
+    min-width: 0;
+  }
+}
+
 /*
  * The shell globals sit at the SAME 32px `ctl` tier as everything else in the row, and they get there
  * the
@@ -148,10 +158,10 @@
  * the row's elastic side truncated `Overview / Dashboard` to `O… / D…`, which is two ellipses and a
  * separator in place of the one word that says where the reader is.
  *
- * `47.99375em` is the `sm` breakpoint in the exact literal form every other basalt CSS module uses —
+ * `52.49375em` is the `sm` breakpoint in the exact literal form every other basalt CSS module uses —
  * a media query cannot resolve a custom property.
  */
-@media (max-width: 47.99375em) {
+@media (max-width: 52.49375em) {
   .crumbAncestors {
     display: none;
   }