basalt-ui 1.31.0 → 1.32.1

package/src/guard/index.ts

@@ -152,7 +152,7 @@ const CSS_WIDTH_MEDIA_QUERY = new RegExp(
  * 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)` —
+ * (`@container basalt-grid (min-width: 800px) 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.
@@ -177,30 +177,23 @@ const CSS_NON_COARSE_POINTER_QUERY =
  * 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',
-])
+ * `basalt-form`/`basalt-grid` are the declared remaining two, reserved here so a consumer adopting
+ * one ahead of the framework does not immediately trip this guard. `basalt-main` was a third until
+ * 1.32.1 dropped it: nothing ever declared it, so the guard accepted a query that never matched.
+ *
+ * `basalt-grid` is also what `StatGroup`/`WidgetGrid` declare (`src/dashboard/*.module.css`) —
+ * they shipped as `basalt-stat-group`/`basalt-widget-grid` until 1.32.0 moved them onto this table.
+ */
+const DECLARED_CONTAINER_NAMES = new Set(['basalt-card', 'basalt-form', '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.
+ * against `basalt-card` and unnamed queries: the other 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])
 
@@ -229,7 +222,14 @@ function isSanctionedShellMediaQuery(relPath: string, query: string): boolean {
   // 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')) ?? []
+  //
+  // But `query` is the whole at-rule prelude up to the width condition, so it can also carry a
+  // NON-width clause — the shell's own landscape rule is `(max-height: 480px) and (orientation:
+  // landscape) and (max-width: 52.49375em)`, and reading its `480px` height as an off-table width
+  // flagged the framework's own sanctioned implementation. Only the parenthesized clauses that name
+  // `width` are read.
+  const widthClauses = query.match(/\([^()]*\bwidth\b[^()]*\)/g) ?? []
+  const widths = widthClauses.flatMap((c) => c.match(new RegExp(CSS_WIDTH_NUM, 'g')) ?? [])
   return widths.length > 0 && widths.every((w) => SIZE_CLASS_LITERALS.has(w))
 }
 
@@ -687,9 +687,12 @@ const PROSE_CONTEXT_TAG = /<(?:Prose|ArticleLayout|Modal|Drawer)(?![\w])/
  * read differently in the two lanes. The plugin gates them on the tag's basalt IMPORT; a 12-line
  * regex window has no import graph, so this lane matches by name and accepts the missed warn on a
  * consumer's own `PanelRow` — the same direction every approximation in this scan already leans.
+ *
+ * The name set is the plugin's `CONTROL_HOST_TAGS` ∪ `BASALT_HOST_TAGS`; `oxlint-plugin.test.ts` ›
+ * lane parity asserts the two agree (1.32.1 — `FormRow`/`FormGroup` had drifted out of this lane).
  */
 const CONTROL_HOST_TAG =
-  /<(?:SettingsRow|Modal|Drawer|Popover\.Dropdown|Menu\.Dropdown|Composer|FilterSet|PageAside|PanelRow)(?![\w])/
+  /<(?:SettingsRow|FormRow|FormGroup|Modal|Drawer|Popover\.Dropdown|Menu\.Dropdown|Composer|FilterSet|PageAside|PanelRow)(?![\w])/
 
 /**
  * How far ABOVE a control the host-tag window reaches, in lines.
@@ -860,8 +863,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.32.0',
+    promote: '1.33.0',
     why:
+      "Extended 1.32.0 -> 1.33.0 at the 1.32.0 release, the last extension: basalt's own tree is at 0 (consumer-loop r1 dogfood) and argo is at 2, but RE-MEASURED 2026-09-30 the fleet carries ~33 (image-gen 11, rb 7, image-share 6, weatherorb 5, email-gateway 4, argo 2). The 1.32.0 fleet upgrade clears them while they warn, together with raw-breakpoint, so 1.33.0 promotes all four ids against a measured-clean fleet. " +
       '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 ' +
@@ -880,15 +884,15 @@ export const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, GraceEntry>> = {
   },
   'raw-media-query': {
     since: '1.31.0',
-    promote: '1.32.0',
+    promote: '1.33.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.',
+      "The CSS-text twin of the oxlint plugin's `basalt/raw-breakpoint` — ONE LAW, TWO LANES, ONE " +
+      'PROMOTION, so it moves with that rule and never alone (`configs/oxlint-plugin.test.ts` › twin lanes share one promotion pins the pair). New in ' +
+      'the wave-11 responsive/touch guards; reaching CSS is a NEW file type for this check, same ' +
+      "reasoning as `css-raw-surface`, with incumbents in basalt's own tree at ship time, so it " +
+      'shipped warn. Extended 1.32.0 -> 1.33.0 with its twin: 1.31.0 named ' +
+      'no reachable container primitive, and 1.32.0 is the first minor that documents one ' +
+      '(`CONTAINER_CLASSES` + the declared `@container` names, MIGRATING § `basalt/raw-breakpoint`).',
   },
 }
 
@@ -2195,7 +2199,7 @@ export const GUARD_RULES = {
     // JSX-tag-shaped (`<Select …>`) — never appears in CSS text.
     appliesTo: (relPath) => !relPath.endsWith('.css'),
     message:
-      'Raw selection control with no home — a filter or tab belongs in a PageBar / Section / WidgetHeader slot and takes a `field` (a FieldHandle), so it owns the URL write and the localStorage mirror instead of carrying value/onChange (docs/CONTROLS-SPEC.md laws C1–C3). Use the bound control from basalt-ui/controls. A settings row, an overlay and an @mantine/form file are the declared non-homes and never report. 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.',
+      '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, a FormRow / FormGroup, an overlay and an @mantine/form file are the declared non-homes and never report. No shell? PageBar needs no BasaltShell: outside one it renders in flow, sticky, with its own title — so its slots are a reachable home for a provider-only app. This is the TEXT lane of basalt/control-outside-home, which answers the same question against the real AST — where the two disagree, the plugin is right.',
   },
   'inline-font-size': {
     kind: 'inline-font-size',
@@ -2209,7 +2213,7 @@ export const GUARD_RULES = {
     // 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.`,
+    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(' / ')}, and a basalt-card or unnamed @container query must sit at a boundary in ${[...CONTAINER_CLASS_LITERALS_PX].map((px) => `${px}px`).join(' / ')} (the other declared names have no numeric table yet, so their literals are not judged); 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>
 
@@ -2476,7 +2480,7 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
         }
         // 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
+        // against, so it is judged against this one too; the other declared names stay
         // unjudged until they ship their own.
         if (name !== '' && name !== 'basalt-card') continue
         for (const lit of body.matchAll(CSS_CONTAINER_LITERAL)) {

package/src/notifications/center.tsx

@@ -205,6 +205,9 @@ export function NotificationCenter({ maxHeight = 320, className, style }: Notifi
       </Group>
 
       {/* View switch */}
+      {/* theme-allow control-outside-home — the center's own inbox/all view, rendered inside
+          `NotificationBell`'s Popover (an overlay, a declared non-home the AST cannot see across
+          the component boundary). */}
       <SegmentedControl
         fullWidth
         size="xs"

package/src/provider/index.tsx

@@ -242,8 +242,13 @@ export function composeInjectedCss(
 
 // ── Host attribute ────────────────────────────────────────────────────────────────────────────────
 
-/** Mount count backing `useHostAttribute`'s ref-counted removal — see that function's doc. */
-let hostAttributeCount = 0
+/** A module-level mount count across every `BasaltProvider`; each call returns the new count. */
+function createMountCounter(): { mount: () => number; unmount: () => number } {
+  let count = 0
+  return { mount: () => ++count, unmount: () => --count }
+}
+
+const hostAttributeMounts = createMountCounter()
 
 /**
  * `data-basalt-host` on `<html>` — the one place a `display-mode` query is read; CSS keys off it.
@@ -261,17 +266,16 @@ export function useHostAttribute(): void {
     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.
+  // Ref-counted across every mounted `BasaltProvider`: 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 keyed on `[isPwa]` would decrement this counter on every `isPwa` change.
   useIsomorphicLayoutEffect(() => {
-    hostAttributeCount++
+    hostAttributeMounts.mount()
     return () => {
-      hostAttributeCount--
-      if (hostAttributeCount === 0) document.documentElement.removeAttribute('data-basalt-host')
+      if (hostAttributeMounts.unmount() === 0) {
+        document.documentElement.removeAttribute('data-basalt-host')
+      }
     }
   }, [])
 }
@@ -374,21 +378,18 @@ function BasaltBridge({
  * misuse, not a false positive from React 18 StrictMode's double-invoke (that mounts/unmounts the
  * SAME instance in sequence, so the count returns to 0 before a second instance could ever exist).
  */
-let mountedProviderCount = 0
+const providerMounts = createMountCounter()
 
 function useDuplicateProviderGuard(): void {
   useEffect(() => {
-    mountedProviderCount++
-    if (mountedProviderCount > 1 && isDev()) {
+    if (providerMounts.mount() > 1 && isDev()) {
       console.warn(
         '[basalt] BasaltProvider: more than one instance is mounted at once — nested/duplicate ' +
           'BasaltProviders double-mount MantineProvider, the palette <style> and ' +
           'ConnectivityProvider. Mount exactly one, at the app root.',
       )
     }
-    return () => {
-      mountedProviderCount--
-    }
+    return () => void providerMounts.unmount()
   }, [])
 }
 

package/src/shell/aside-docking.ts

@@ -0,0 +1,54 @@
+/**
+ * Aside docking (`docs/DESIGN-CORE.md` § Layout, elevation, shapes) — the pure decision `ShellFrame`
+ * sizes `AppShell.Aside` from. An open aside pushes main only in `expanded` while main keeps
+ * `MAIN_MIN_WIDTH` beside the navbar; otherwise the region reserves just its rail and an open panel
+ * overlays main. Unclaimed, the region is zero-wide.
+ */
+import { toEm } from '../tokens/size-classes'
+import type { SizeClass } from './use-size-class'
+
+/**
+ * Main keeps at least this much width, or an open aside overlays it instead of docking. Not
+ * derived from a token: it is the readable floor for a page body, independent of density.
+ */
+const MAIN_MIN_WIDTH = 720
+
+export type AsideDockingInput = {
+  claimed: boolean
+  folded: boolean
+  sizeClass: SizeClass
+  /** The `asideDockQuery` media query's result. */
+  roomToDock: boolean
+  asideWidth: number
+  asideRailWidth: number
+}
+
+export type AsideDocking = {
+  /** An open aside pushes main rather than overlaying it. */
+  docks: boolean
+  /** An open aside renders over main (reserving only its rail). */
+  overlay: boolean
+  /** The width `AppShell` reserves for the region. */
+  width: number
+}
+
+/** The `min-width` query that holds while navbar + open aside + `MAIN_MIN_WIDTH` fit side by side. */
+export function asideDockQuery(input: { navbarWidth: number; asideWidth: number }): string {
+  return `(min-width: ${toEm(input.navbarWidth + input.asideWidth + MAIN_MIN_WIDTH)})`
+}
+
+/**
+ * The room-to-dock query's SSR/no-`matchMedia` fallback — an `'expanded'` `sizeClassHint` means the
+ * server already believes there is room, matching `useSizeClass`'s own hint-seeded guard
+ * (`use-size-class.ts`), so the first client paint doesn't fold a default-open aside for one commit.
+ */
+export function roomToDockServerFallback(sizeClassHint: SizeClass | undefined): boolean {
+  return sizeClassHint === 'expanded'
+}
+
+export function resolveAsideDocking(input: AsideDockingInput): AsideDocking {
+  const docks = input.sizeClass === 'expanded' && input.roomToDock
+  const open = input.claimed && !input.folded
+  const reserved = open && docks ? input.asideWidth : input.asideRailWidth
+  return { docks, overlay: open && !docks, width: input.claimed ? reserved : 0 }
+}

package/src/shell/index.tsx

@@ -34,6 +34,7 @@ import { blockRowCount, projectMobileNav } from './mobile-nav-model'
 import { AppBreadcrumbs } from './app-breadcrumbs'
 import { PageBarBandOutlet, PageBarOutlet, PageBarProvider, usePageKebabClaimed } from './page-bar'
 import { AsideDocksContext, AsideOutlet, AsideProvider, useAsideRegion } from './page-aside'
+import { asideDockQuery, resolveAsideDocking, roomToDockServerFallback } from './aside-docking'
 import { OverflowMenu, globalActionAsBarAction, globalActionMobile } from '../controls/actions'
 import type { GlobalAction } from '../controls/actions'
 import type { AccountMenuItem, BasaltAccountProps } from './account-types'
@@ -47,9 +48,7 @@ import type {
 } from './nav-types'
 import { CtlSlot, useBasaltSpacing } from '../theme'
 import { createPersistedStore } from '../state/persisted'
-import { toEm } from '../tokens/size-classes'
 import { SizeClassHintContext, useSizeClass } from './use-size-class'
-import type { SizeClass } from './use-size-class'
 import brandClasses from './app-brand.module.css'
 import headerClasses from './app-header.module.css'
 import mainClasses from './app-main.module.css'
@@ -303,25 +302,6 @@ function collapseStore(key: string): CollapseStore {
   return store
 }
 
-/**
- * Main keeps at least this much width, or an open aside overlays it instead of docking. Not
- * derived from a token: it is the readable floor for a page body, independent of density.
- */
-const MAIN_MIN_WIDTH = 720
-
-/**
- * The room-to-dock `min-width` query's SSR/no-`matchMedia` fallback — an `'expanded'`
- * `sizeClassHint` means the server already believes there is room, matching `useSizeClass`'s own
- * hint-seeded guard one level up (`use-size-class.ts`). Extracted as its own pure function (rather
- * than the inline `sizeClassHint === 'expanded'` it replaces) purely so `index.test.tsx` can pin it
- * without needing to render `BasaltShell` through a real SSR pass — `AppShell`'s + `PageAside`'s own
- * effects/refs/portals make that path unobservable through rendered markup, and the previous
- * hardcoded `false` fallback here shipped with no test at all for exactly that reason.
- */
-export function roomToDockServerFallback(sizeClassHint: SizeClass | undefined): boolean {
-  return sizeClassHint === 'expanded'
-}
-
 /**
  * The shell's two page-level regions are providers, and both wrap the frame rather than living
  * inside it: `PageBarProvider` owns the header portal and the single-kebab claim, `AsideProvider`
@@ -395,25 +375,23 @@ function ShellFrame({
   const isCollapseControlled = collapsedProp !== undefined
   const uncontrolledCollapsed = collapseIsSet ? storedCollapsed : sizeClass === 'medium'
   const collapsed = isCollapseControlled ? collapsedProp : uncontrolledCollapsed
-  // Aside docking (`docs/DESIGN-CORE.md` § Layout, elevation, shapes): an open aside pushes main only in
-  // `expanded` while main keeps `MAIN_MIN_WIDTH` beside this navbar; otherwise the region reserves
-  // just its rail and an open panel overlays main. Provided through `AsideDocksContext` in the SAME
-  // render, so `PageAside` defaults its fold from the right value on its first pass.
+  // Aside docking (`aside-docking.ts`), provided through `AsideDocksContext` in the SAME render so
+  // `PageAside` defaults its fold from the right value on its first pass.
   const navbarWidth = collapsed ? step.appShellNavbarRailWidth : step.appShellNavbarWidth
-  // The SSR/first-paint fallback mirrors `useSizeClass`'s own hint-seeded guard: an `expanded` hint
-  // from `<BasaltProvider sizeClassHint>` means the server already believes there is room to dock, so
-  // the first client paint agrees instead of defaulting to "cannot dock" and folding a default-open
-  // aside for one commit.
   const sizeClassHint = useContext(SizeClassHintContext)
   const roomToDock = useMediaQuery(
-    `(min-width: ${toEm(navbarWidth + step.appShellAsideWidth + MAIN_MIN_WIDTH)})`,
+    asideDockQuery({ navbarWidth, asideWidth: step.appShellAsideWidth }),
     roomToDockServerFallback(sizeClassHint),
   )
-  const docks = sizeClass === 'expanded' && roomToDock
-  const asideOpen = aside.claimed && !aside.folded
-  const asideOverlay = asideOpen && !docks
-  const asideReserved = asideOpen && docks ? step.appShellAsideWidth : step.appShellAsideRailWidth
-  const asideWidth = aside.claimed ? asideReserved : 0
+  const docking = resolveAsideDocking({
+    claimed: aside.claimed,
+    folded: aside.folded,
+    sizeClass,
+    roomToDock,
+    asideWidth: step.appShellAsideWidth,
+    asideRailWidth: step.appShellAsideRailWidth,
+  })
+  const asideOverlay = docking.overlay
   // Keyboard escape hatch for the overlay form only — the docked form never blocks content, so
   // there is nothing to escape out of. `requestClose` is a stable callback from `AsideProvider`
   // (destructured, not read as `aside.requestClose`, so the effect deps name it directly rather
@@ -460,7 +438,7 @@ function ShellFrame({
   )
 
   return (
-    <AsideDocksContext.Provider value={docks}>
+    <AsideDocksContext.Provider value={docking.docks}>
       <AppShell
         h="100dvh"
         // Mantine's DEFAULT layout, not `alt`: the header spans the full viewport width on top and
@@ -484,7 +462,7 @@ function ShellFrame({
         // prop for it on purpose; the ROUTE decides, the same way it decides its page bar.
         aside={{
           // An overlay reserves the rail only — `<AppShell.Aside>` below widens itself over main.
-          width: asideWidth,
+          width: docking.width,
           breakpoint: 'sm',
           // Below `sm` there is no region at all — `PageAside` renders its content in the page
           // flow instead, one node, no responsive twin (law C9).

package/src/shell/page-bar.tsx

@@ -346,6 +346,30 @@ function useMeasuredHeightVar(active: boolean): (el: HTMLDivElement | null) => v
   return attach
 }
 
+/**
+ * The page's control bar — row 1 (title/icon, `actions`, `sync`) and row 2 (`tabs`, `filters`,
+ * `filtersEnd`). Inside `BasaltShell` both rows portal into shell chrome; with no shell it renders
+ * ONE sticky bar in flow, `title` leading, and needs no `PageBarProvider`.
+ *
+ * @example
+ * // Shell-less (linewatch-shaped): the store is local, the bar is the page's first child.
+ * const filters = createLocalStore({ key: 'outages', fields: { q: field.string({ max: 60 }) } })
+ *
+ * function OutagesPage() {
+ *   const [q] = filters.field.q.use()
+ *   return (
+ *     <>
+ *       <PageBar
+ *         title="Outages"
+ *         actions={{ primary: { key: 'export', label: 'Export', onClick: exportCsv } }}
+ *         filters={<FilterSet><SearchFilter field={filters.field.q} placeholder="Find a line" /></FilterSet>}
+ *         classNames={{ root: classes.bleed }} // your gutter bleed — see `PageBarSlot`
+ *       />
+ *       <OutageTable query={q} />
+ *     </>
+ *   )
+ * }
+ */
 export function PageBar({
   title,
   icon,

package/src/shell/use-breakpoint.ts

@@ -1,5 +1,5 @@
 /**
- * `useBreakpoint` — DEPRECATED (on notice in `MIGRATING.md`, removed next minor): use
+ * `useBreakpoint` — DEPRECATED (on notice in `MIGRATING.md`, removed in 1.33.0): use
  * `useSizeClass` from `./use-size-class`. One media-query hook over the theme's own breakpoints,
  * built on the shared `useMediaQuery` (`common/use-media-query`) — SSR/hydration-safe.
  *
@@ -21,7 +21,7 @@ import { useMediaQuery } from '../common/use-media-query'
 export type BreakpointName = 'xs' | 'sm' | 'md' | 'lg' | 'xl'
 
 /**
- * @deprecated Use `useSizeClass` — removed next minor (see `MIGRATING.md`). `theme.breakpoints` is
+ * @deprecated Use `useSizeClass` — removed in 1.33.0 (see `MIGRATING.md`). `theme.breakpoints` is
  * now derived: `sm` moved 48em → 52.5em and `md`/`lg`/`xl` all sit at 75em (`xs`/`sm` collapse,
  * `md`/`lg`/`xl` collapse).
  */

package/src/theme/floating.module.css

@@ -42,6 +42,7 @@
  * `.sheetBody` is the Modal body; it reaches the trailing button row `overlays.confirm`
  * renders (Mantine `Group`), stretching the buttons to full width at the `--vx-hit` floor.
  */
+/* theme-allow raw-media-query — the bottom sheet IS the compact size class's overlay form */
 @media (max-width: 52.49375em) {
   .sheetInner {
     align-items: flex-end;

package/src/theme-lab/derive-controls.tsx

@@ -178,6 +178,8 @@ export function DeriveControls({ resetIcon }: DeriveControlsProps) {
         <Text size="xs" fw={500} mb={4}>
           Neutral family
         </Text>
+        {/* theme-allow control-outside-home — a theme-lab setting (a settings row, a declared
+            non-home), not a page filter: it edits the derive config, never page data. */}
         <SegmentedControl
           size="xs"
           fullWidth

package/src/tokens/index.ts

@@ -52,6 +52,11 @@ export type { RadiusValues } from './palette'
 export { deriveSpacing } from './palette'
 export type { SpaceValues } from './palette'
 
+// The two responsive tables — MIGRATING recipes and the raw-breakpoint guard messages send
+// consumers here for them; `migrating-imports.test.ts` pins that every documented import resolves.
+export { CONTAINER_CLASSES, resolveContainerClass, SIZE_CLASSES } from './size-classes'
+export type { ContainerClass } from './size-classes'
+
 /** A per-theme color pair: a hue keeps its identity but shifts shade across schemes. */
 export type ColorPair = { light: string; dark: string }