basalt-ui 1.28.0 → 1.29.1

package/src/guard/index.ts

@@ -1,7 +1,7 @@
 /**
  * ./guard — headless policy core. Mantine-free, dependency-free.
  *
- * GUARD_RULES: the closed registry of all 27 violation kinds.
+ * GUARD_RULES: the closed registry of all 26 violation kinds.
  * checkSource:  pure (text, relPath, cfg) → Finding[]. No FS, no walk, no console.
  */
 import type { Finding, GuardConfig, GuardKind, GuardSeverity } from './types'
@@ -154,8 +154,8 @@ const INLINE_FONT_SIZE =
 // A `Card` / `Paper` opening tag carrying `withBorder`. Card depth is `--vx-shadow-card`, whose 1px
 // ring lives INSIDE the shadow value; `withBorder` therefore adds a SECOND, real `border` property
 // on top of it (the theme's `styles.root` pins bg/shadow/radius but never clears `border`), and the
-// card reads heavy/boxed. Bounded full-text tag scan, same shape as CHART_ENTRY_POINT_TAG below, so
-// a multi-line-formatted tag still resolves to one match.
+// card reads heavy/boxed. Bounded full-text tag scan, same shape as CHART_ENTRY_POINT_TAG_START below,
+// so a multi-line-formatted tag still resolves to one match.
 //
 // Two deliberate non-matches:
 //   • `<Card.Section withBorder>` — a section DIVIDER, not card depth. Excluded by the `(?![\w.])`
@@ -409,31 +409,54 @@ const MOTION_TRANSITION_NUMERIC =
   /\btransition\s*=\s*\{\{[^}]*\b(?:duration|stiffness|damping|mass)\s*:\s*-?\d/g
 const MOTION_TRANSITION_EASE_ARRAY = /\btransition\s*=\s*\{\{[^}]*\bease\s*:\s*\[/g
 
-// A hand-rolled <ChartLegend items={[ …array literal… ]}> — legend entries authored inline
-// instead of derived (`items={deriveLegend(series)}`, a call expression, which must NOT match).
-// Scoped to the JSX tag itself ([^>]* is bounded by the tag's own closing `>`, which also makes
-// this a full-text scan rather than the per-line style every other kind uses — a multi-line-
-// formatted <ChartLegend ...\n  items={[...\n/> still resolves to one match). Bounded scans over
-// text this small are not a performance concern.
-const RAW_CHART_LEGEND_ARRAY = /<ChartLegend\b[^>]*?\bitems\s*=\s*\{\s*\[/g
-
-// A chart entry-point JSX tag (the 7 kinds + 2 sparklines) — full opening/self-closing tag,
-// scanned for a missing `ariaLabel` prop (an accessible text alternative for the SVG graphic).
-// Bounded, full-text scan (like RAW_CHART_LEGEND_ARRAY above) so a multi-line-formatted tag still
-// resolves to one match. The scan must survive two `>` decoys inside an opening tag: an explicit
-// JSX generic argument (`<MultiLine<Point>`) — consumed by the optional `<[^<>]*>` group — and
-// arrow functions in prop expressions (`getX={(d) => d.date}`) — consumed atomically by the `=>`
-// alternative so their `>` never terminates the tag early. A bare `>` comparison inside a prop
-// expression still ends the match (accepted limitation of the bounded scan).
-const CHART_ENTRY_POINT_TAG =
-  /<(MultiLine|Bars|BandStrip|Donut|DualPanel|Heatmap|MirroredBars|ZonedLine|StackedArea|LineSparkline|BarSparkline)\b(?:<[^<>]*>)?(?:=>|[^>])*?>/g
+// A chart entry-point JSX tag (the 7 kinds + 2 sparklines) — matches the opening `<Name` plus an
+// optional explicit JSX generic argument (`<MultiLine<Point>`); the rest of the tag (up to its
+// closing `>`) is resolved by `scanChartTagClose` below, brace-depth aware, so it survives every
+// `>`-shaped decoy inside a prop expression — arrow functions (`=>`), comparisons (`>=`, `<=`),
+// shifts (`>>`) — without needing to enumerate them: a `>` only closes the tag outside every `{…}`.
+const CHART_ENTRY_POINT_TAG_START =
+  /<(MultiLine|Bars|BandStrip|Donut|DualPanel|Heatmap|MirroredBars|ZonedLine|StackedArea|LineSparkline|BarSparkline)\b(?:<[^<>]*>)?/g
 const HAS_ARIA_LABEL_PROP = /\bariaLabel\s*=/
 
-// ── Tag provenance, shared by the two chart tag rules ────────────────────────────────────────────
+/**
+ * Scans forward from `start` (immediately after a chart tag's name/generic-args) for the `>` that
+ * closes the JSX tag. Curly-brace depth aware: a `>` only closes the tag at depth 0, so anything
+ * living inside a `{…}` prop expression — `=>`, `>=`, `<=`, `>>`, a nested JSX child's own `>` —
+ * never ends the tag early. String/template literals are skipped verbatim so a quoted `>`
+ * cannot perturb the depth count either. Returns the index of the closing `>`, or -1 if the tag
+ * never closes (malformed/truncated source — the caller treats that as no match).
+ */
+function scanChartTagClose(codeText: string, start: number): number {
+  let depth = 0
+  let i = start
+  while (i < codeText.length) {
+    const ch = codeText[i]
+    if (ch === '"' || ch === "'" || ch === '`') {
+      const quote = ch
+      i++
+      while (i < codeText.length && codeText[i] !== quote) {
+        i += codeText[i] === '\\' ? 2 : 1
+      }
+      i++
+      continue
+    }
+    if (ch === '{') {
+      depth++
+    } else if (ch === '}') {
+      depth = Math.max(0, depth - 1)
+    } else if (ch === '>' && depth === 0) {
+      return i
+    }
+    i++
+  }
+  return -1
+}
+
+// ── Tag provenance, shared by chart-missing-aria-label ────────────────────────────────────────────
 //
-// Both `chart-missing-aria-label` and `unframed-chart` key on a JSX tag NAME, which is the whole of
-// their signal — so a consumer's OWN component that merely shares a shipped kind's name collected
-// the finding too. Reported by a consumer on 1.23.0: a hand-composed local `<MirroredBars>` was
+// `chart-missing-aria-label` keys on a JSX tag NAME, which is the whole of its signal — so a
+// consumer's OWN component that merely shares a shipped kind's name collected the finding too.
+// Reported by a consumer on 1.23.0: a hand-composed local `<MirroredBars>` was
 // told to pass an `ariaLabel` prop it does not accept, by a rule that presents as a correctness
 // finding rather than as a naming one. `shadow-basalt-export` / `ai-sdk-major` scope through
 // `isBasaltScopedFile` (package-level); the analogous file-level signal here is where the name in
@@ -480,13 +503,13 @@ function basaltImportedNames(codeText: string): ReadonlySet<string> {
 const RAW_FORM_CONTROL = /<(?:input|select|textarea)\b/g
 
 // A raw form-control's own opening tag — bounded full-text scan (same shape as CARD_SURFACE_TAG /
-// CHART_ENTRY_POINT_TAG), used ONLY by sub-16-input-font to search the tag's own inline `style`
+// CHART_ENTRY_POINT_TAG_START), used ONLY by sub-16-input-font to search the tag's own inline `style`
 // for a sub-floor fontSize.
 const RAW_FORM_CONTROL_TAG = /<(?:input|select|textarea)\b(?:=>|[^>])*?>/g
 
 // ── Control-home patterns (docs/CONTROLS-SPEC.md §6 — the text lane of laws C1/C8) ──────────────
 //
-// Bounded full-text tag scans, the CARD_SURFACE_TAG / CHART_ENTRY_POINT_TAG shape: a `<Title>` and a
+// Bounded full-text tag scans, the CARD_SURFACE_TAG / CHART_ENTRY_POINT_TAG_START shape: a `<Title>` and a
 // `<Select>` are both routinely formatted across lines, so a per-line regex would see neither.
 
 /** A `<Title …>` opening tag, however it is wrapped. `order` is judged separately, on the tag text. */
@@ -632,7 +655,6 @@ export const DEFAULT_GUARD_CONFIG: GuardConfig = {
   inlineDisplay: true,
   rawVisxAxis: true,
   rawMotionValue: true,
-  unframedChart: true,
   chartMissingAriaLabel: true,
   rawFormControl: true,
   sub16InputFont: true,
@@ -882,12 +904,10 @@ export const PLUGIN_RULE_IDS: ReadonlySet<string> = new Set([
   'responsive-twin',
   'search-literal-link',
   'use-search-from-literal',
-  // The four F5 rules and the B4 deprecation rule — all AST-only, all outside `checkSource`'s
-  // reach: provenance here is an import graph and a JSX ancestry, neither of which a 12-line
-  // regex window has. Same reason `bound-control-outside-home` has no text-lane twin.
+  // The three remaining F5 rules and the B4 deprecation rule — all AST-only, all outside
+  // `checkSource`'s reach: provenance here is an import graph and a JSX ancestry, neither of which
+  // a 12-line regex window has. Same reason `bound-control-outside-home` has no text-lane twin.
   'provider-above-router',
-  'duplicate-notifications-mount',
-  'query-dual-import',
   'query-fn-unwrap',
   'deprecated-export',
   // Same lane: `{...inputProps(…)}` without a sibling `key` is a JSX-ancestry claim (does this
@@ -899,11 +919,25 @@ export const PLUGIN_RULE_IDS: ReadonlySet<string> = new Set([
   'visx-boundary',
   'visx-tooltip',
   'token-layer-boundary',
+  'no-import-meta-env',
   // 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',
   'agent-no-raw-usechat',
   'ai-sdk-major',
+  // Retired guard kinds — `unframed-chart`'s only case (`<ChartLegend items={[...]}>`) is fully
+  // subsumed by `basalt/chart-legend-literal`. Kept here (mirrored by the plugin's own
+  // `RETIRED_RULE_IDS`) so an existing `theme-allow unframed-chart` reads as a dead waiver via
+  // `--audit-allows`, never as an unknown-id typo.
+  'unframed-chart',
+  // Retired plugin rule — `<BasaltNotifications />` mounted beside `<BasaltOverlays
+  // notifications>` is unreachable now that `BasaltNotifications` no longer exists as a
+  // standalone export. Mirrored by the plugin's own `RETIRED_RULE_IDS`.
+  'duplicate-notifications-mount',
+  // Retired plugin rule — its whole premise (a raw `@tanstack/react-query` import beside
+  // `basalt-ui/query`) is unreachable now that C1 (1.29.0) dropped the `./query` subpath.
+  // Mirrored by the plugin's own `RETIRED_RULE_IDS`.
+  'query-dual-import',
 ])
 
 /** The shortest string accepted as a written reason — enough to exclude a stray separator. */
@@ -1518,7 +1552,6 @@ export const TOKENS_ONLY_DISABLED_KINDS: ReadonlySet<GuardKind> = new Set([
   'inline-display',
   'raw-visx-axis',
   'raw-motion-value',
-  'unframed-chart',
   'chart-missing-aria-label',
   'raw-form-control',
   'sub-16-input-font',
@@ -1747,7 +1780,7 @@ type GuardRule = {
 }
 
 /**
- * The closed registry of all 27 guard kinds. The triad test asserts
+ * The closed registry of all 26 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
@@ -1900,18 +1933,9 @@ export const GUARD_RULES = {
     message:
       'Route animation timing through MOTION_DURATION / MOTION_SPRING / MOTION_EASE_STANDARD (basalt-ui motion tokens) instead of a hardcoded duration/spring/ease.',
   },
-  'unframed-chart': {
-    kind: 'unframed-chart',
-    pattern: RAW_CHART_LEGEND_ARRAY, // handled inline (full-text tag-scoped scan); entry keeps registry complete
-    enabled: (cfg: GuardConfig) => cfg.unframedChart,
-    // JSX-tag-shaped (`<ChartLegend items={[…]}>`) — never appears in CSS text.
-    appliesTo: (relPath) => !relPath.endsWith('.css'),
-    message:
-      'Hand-rolled ChartLegend built from an inline array literal — pass a derived legend (deriveLegend(series)), or compose ChartFrame, which derives it for you.',
-  },
   'chart-missing-aria-label': {
     kind: 'chart-missing-aria-label',
-    pattern: CHART_ENTRY_POINT_TAG, // handled inline (full-text tag-scoped scan); entry keeps registry complete
+    pattern: CHART_ENTRY_POINT_TAG_START, // handled inline (full-text tag-scoped scan); entry keeps registry complete
     enabled: (cfg: GuardConfig) => cfg.chartMissingAriaLabel,
     // JSX-tag-shaped (`<MultiLine …>`) — never appears in CSS text.
     appliesTo: (relPath) => !relPath.endsWith('.css'),
@@ -2342,32 +2366,16 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
     }
   }
 
-  // Both chart tag rules below gate on tag PROVENANCE (see the block above LOCAL_COMPONENT_DEF).
-  // Computed once, and only if one of the two actually runs.
-  const unframedChartRuns =
-    GUARD_RULES['unframed-chart'].enabled!(cfg) && ruleApplies('unframed-chart', relPath)
+  // The aria-label tag rule below gates on tag PROVENANCE (see the block above LOCAL_COMPONENT_DEF).
+  // Computed once, and only if the rule actually runs.
   const ariaLabelRuns =
     GUARD_RULES['chart-missing-aria-label'].enabled!(cfg) &&
     ruleApplies('chart-missing-aria-label', relPath)
-  const localNames =
-    unframedChartRuns || ariaLabelRuns ? localComponentNames(codeText) : new Set<string>()
-  const basaltNames =
-    unframedChartRuns || ariaLabelRuns ? basaltImportedNames(codeText) : new Set<string>()
+  const localNames = ariaLabelRuns ? localComponentNames(codeText) : new Set<string>()
+  const basaltNames = ariaLabelRuns ? basaltImportedNames(codeText) : new Set<string>()
   const isShippedTag = (tag: string): boolean => basaltNames.has(tag) || !localNames.has(tag)
 
-  // unframed-chart — full-text tag-scoped scan (not per-line, see RAW_CHART_LEGEND_ARRAY comment).
-  // Scans `codeText` (comment-stripped) so a legend example inside a comment can't match; reports
-  // at the line of the `items={[` token itself. Skipped wholesale when `ChartLegend` is this file's
-  // OWN component: a consumer's legend taking an `items` array is not the shipped one that derives
-  // its entries, and the remedy ("pass deriveLegend(series)") is unreachable there.
-  if (unframedChartRuns && isShippedTag('ChartLegend')) {
-    for (const m of codeText.matchAll(RAW_CHART_LEGEND_ARRAY)) {
-      const lineNo = codeText.slice(0, (m.index ?? 0) + m[0].length).split('\n').length
-      push('unframed-chart', lineNo, 'items={[')
-    }
-  }
-
-  // chart-missing-aria-label — full-text tag-scoped scan (same shape as unframed-chart above).
+  // chart-missing-aria-label — full-text tag-scoped scan.
   // A tag is a violation only when its own (possibly multi-line) prop list has no `ariaLabel=`.
   // Reports at the tag's OPENING line, like card-with-border below and unlike the end-of-match
   // arithmetic this used to do: on a multi-line-formatted chart the end lands on the closing `/>`,
@@ -2375,12 +2383,15 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
   // that is missing the prop. The allow-comment is honored anywhere in the tag's span, so a
   // `theme-allow` that used to sit on the closing line keeps working.
   if (ariaLabelRuns) {
-    for (const m of codeText.matchAll(CHART_ENTRY_POINT_TAG)) {
-      const tagText = m[0]
+    for (const m of codeText.matchAll(CHART_ENTRY_POINT_TAG_START)) {
+      const matchStart = m.index ?? 0
       // A tag this file defines itself is not the shipped kind — it does not take `ariaLabel`.
       if (!isShippedTag(m[1] as string)) continue
+      const closeIdx = scanChartTagClose(codeText, matchStart + m[0].length)
+      if (closeIdx === -1) continue
+      const tagText = codeText.slice(matchStart, closeIdx + 1)
       if (HAS_ARIA_LABEL_PROP.test(tagText)) continue
-      const startLine = codeText.slice(0, m.index ?? 0).split('\n').length
+      const startLine = codeText.slice(0, matchStart).split('\n').length
       const endLine = startLine + (tagText.split('\n').length - 1)
       if (isAllowedInRange(startLine, endLine, 'chart-missing-aria-label')) continue
       findings.push({

package/src/guard/types.ts

@@ -1,12 +1,17 @@
 /**
  * Guard types — Mantine-free, dependency-free (zero imports beyond TS types).
  *
- * GuardKind is the closed set of 27 violation kinds the theme guard can emit.
+ * GuardKind is the closed set of 26 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
+ * recognized id in `PLUGIN_RULE_IDS`/`KNOWN_RULE_IDS` so an existing `theme-allow unframed-chart`
+ * reads as a dead waiver, not a typo.
  * Finding is the structured result per violation, replacing the old `Violation` shape.
  * GuardConfig is the per-run configuration that drives checkSource.
  */
 
-/** The 27 theme-guard violation kinds. */
+/** The 26 theme-guard violation kinds. */
 export type GuardKind =
   | 'raw-hex'
   | 'raw-color-fn'
@@ -23,7 +28,6 @@ export type GuardKind =
   | 'inline-display'
   | 'raw-visx-axis'
   | 'raw-motion-value'
-  | 'unframed-chart'
   | 'chart-missing-aria-label'
   | 'raw-form-control'
   | 'sub-16-input-font'
@@ -127,13 +131,6 @@ export type GuardConfig = {
   readonly rawVisxAxis: boolean
   /** Flag a hardcoded duration/spring/ease literal in a `transition={{...}}` prop. Default true. */
   readonly rawMotionValue: boolean
-  /**
-   * Flag a hand-rolled `<ChartLegend items={[...]}>` array literal — legend entries must be
-   * derived (e.g. `items={deriveLegend(series)}`), never authored inline, so a bespoke chart
-   * can't silently drift from the shared legend. Default `true` (ON). Set `false` to disable the
-   * `unframed-chart` check.
-   */
-  readonly unframedChart: boolean
   /**
    * Flag a chart-kind JSX usage (`<MultiLine>`, `<Bars>`, `<Donut>`, `<DualPanel>`, `<Heatmap>`,
    * `<ZonedLine>`, `<StackedArea>`, `<LineSparkline>`, `<BarSparkline>`) missing an `ariaLabel`

package/src/index.ts

@@ -10,12 +10,17 @@ export {
   BasaltProvider,
   type BasaltProviderProps,
   BasaltErrorBoundary,
+  type BasaltErrorBoundaryProps,
   type BasaltErrorContext,
 } from './provider'
 // -- Common primitives (src/common) ------------------------------------------------------------
 // Not a subpath of its own: `BasaltProps` is the base every component's props extend, so it belongs
 // on the entry a consumer already imports. The module is Mantine-free (`common/boundary.test.ts`),
-// which is what lets `./charts` reach `cx`/`mergeRefs` without breaching the layer boundary.
+// which is what lets `./charts` reach `cx` without breaching the layer boundary.
+// The validate/errors internals (`useValidateProps`/`assertRequiredProps`/`requiredProp`/`oneOf`/
+// `deprecatedProp`/`duplicateMount`/`missingLayer`/`BASALT_PREFIX`) and the ref helpers
+// (`assignRef`/`mergeRefs`) are basalt's own diagnostic vocabulary, not a consumer's — no consumer
+// imports them, so they stay internal (C1 consolidation).
 export {
   type BasaltProps,
   type SlotClassNames,
@@ -24,16 +29,6 @@ export {
   type ToneWithNeutral,
   type Tier,
   cx,
-  assignRef,
-  mergeRefs,
-  BASALT_PREFIX,
-  requiredProp,
-  oneOf,
-  deprecatedProp,
-  duplicateMount,
-  missingLayer,
-  useValidateProps,
-  assertRequiredProps,
   scrollParentOf,
   SCROLLPORT_ATTRIBUTE,
 } from './common'
@@ -42,6 +37,7 @@ export { createBasaltTheme, baseTheme, cssVariablesResolver } from './theme'
 export type { BasaltFontsConfig, CreateBasaltThemeOptions } from './theme'
 export { CTL_THEME, CtlSlot } from './theme'
 export type { CtlSlotProps } from './theme'
+export { ThemeToggle, type ThemeToggleProps } from './theme/theme-toggle'
 /**
  * The action vocabulary every home's `actions` slot takes (`docs/CONTROLS-SPEC.md` §2.1). The
  * OTHER components that project it (`OverflowMenu`, `SyncButton`, and the filter family) live on
@@ -54,8 +50,7 @@ export {
   type ActionGroupProps,
   type GlobalAction,
 } from './controls/actions'
-export { ThemeToggle, type ThemeToggleProps } from './theme-toggle'
-export { MOTION_DURATION, MOTION_SPRING, MOTION_EASE_STANDARD } from './motion'
+export { MOTION_DURATION, MOTION_SPRING, MOTION_EASE_STANDARD } from './common/motion'
 export {
   BasaltShell,
   NavCountBadge,
@@ -81,6 +76,11 @@ export {
   PageAside,
   type PageAsideProps,
   type PageAsideSlot,
+  useBreakpoint,
+  type BreakpointName,
+  PageTitle,
+  type PageTitleProps,
+  type PageTitleSlot,
   type SidebarSection,
   type SidebarItem,
   type SidebarBlock,
@@ -127,10 +127,10 @@ export {
 
 // ── Persisted state + the headless store kernel (state.ts) ───────────────────────────────────────
 // The `field.*` VALUE is deliberately not re-exported here. `basalt-ui/forms` used to own the
-// name `field` too and collide with this one; that forms helper is now `inputProps` (`field`
-// stays there only as a @deprecated alias — see MIGRATING.md). Import `field.*` from
-// `basalt-ui/router-tanstack` (beside `createSearchStore`) or from `basalt-ui/state` (beside
-// `createLocalStore`).
+// name `field` too and collide with this one; that forms helper is `inputProps` now (the
+// `@deprecated field` alias was removed in 1.29.0, C1 consolidation — see MIGRATING.md). Import
+// `field.*` from `basalt-ui/router-tanstack` (beside `createSearchStore`) or from `basalt-ui/state`
+// (beside `createLocalStore`).
 export {
   createPersistedState,
   type PersistedStateOptions,
@@ -161,7 +161,8 @@ export {
   type StringField,
 } from './state'
 
-// ── WidgetHeader (unified section/widget/card heading primitive, docs/CONTROLS-SPEC.md §2.2) ─────
+// ── Dashboard composites (WidgetHeader/Section heading family + KPI atoms + settings building
+// blocks, docs/CONTROLS-SPEC.md §2.2) ──────────────────────────────────────────────────────────────
 export {
   WidgetHeader,
   type WidgetHeaderDeltaProps,
@@ -173,13 +174,9 @@ export {
   DeltaBadge,
   type DeltaBadgeProps,
   type DeltaPolarity,
-} from './widget-header'
-
-// ── Section (tier-2 heading composer over WidgetHeader, docs/CONTROLS-SPEC.md §2.2) ───────────────
-export { Section, type SectionProps, type SectionSlot } from './section'
-
-// ── Dashboard composites (KPI atoms + settings building blocks) ──────────────────────────────────
-export {
+  Section,
+  type SectionProps,
+  type SectionSlot,
   StatCard,
   type StatCardBreakdownRow,
   type StatCardProps,
@@ -208,7 +205,6 @@ export {
   type QueryStateLike,
   type QueryStateSlot,
   type QueryStateTier,
-  type QueryStateVariant,
   type QueryEmptyCopy,
   LoadingState,
   type LoadingStateProps,
@@ -216,14 +212,26 @@ export {
   type ErrorStateProps,
 } from './dashboard'
 
-// ── Connectivity (auto-mounted by BasaltProvider) ────────────────────────────────────────────────
-export { ConnectivityProvider, ConnectivityIndicator, useConnectivity } from './connectivity'
+// ── Connectivity (auto-mounted by BasaltProvider, merged into ./provider — dropped ./connectivity
+// subpath) ──────────────────────────────────────────────────────────────────────────────────────
+export { ConnectivityProvider } from './provider/connectivity-provider'
+export { ConnectivityIndicator } from './provider/connectivity-indicator'
+export { useConnectivity } from './provider/use-connectivity'
 export type {
   ConnectivityStatus,
   ConnectivitySnapshot,
   ConnectivityProviderProps,
   ConnectivityOverride,
-} from './connectivity'
+} from './provider/connectivity-types'
+export type { ConnectivityIndicatorProps } from './provider/connectivity-indicator'
+
+// ── Query (createBasaltQueryClient, unwrap, lazy devtools — dropped ./query subpath) ──────────────
+export { createBasaltQueryClient, unwrap } from './query-client'
+export { BasaltQueryDevtools } from './query-devtools'
+export { toErrorMessage, errorStatus } from './common/errors'
+
+// ── BasaltDevDock (C5 consolidation) ────────────────────────────────────────────────────────────
+export { BasaltDevDock, type BasaltDevDockProps, type BasaltDevDockTool } from './dev-dock'
 
 // ── Type-only re-exports for compile fixtures (H.4) ──────────────────────────────────────────────
 // SurfaceSpec/RuleName/SkillName: the value SURFACES stays internal; types only for surfaces-broken
@@ -264,6 +272,7 @@ export type {
   MessageAffordances,
   VirtualizeOptions,
   VirtualizeProps,
+  RowHeightProps,
   ToolChipProps,
 } from './agent-chat'
 export {

package/src/notifications/index.ts

@@ -2,7 +2,9 @@
  * ./notifications — Mantine notification adapter battery.
  *
  * Provides notify helpers, a typed registry, a persisted history store, and a bell/center
- * overlay component on top of @mantine/notifications.
+ * component on top of @mantine/notifications. The overlay mount is `<BasaltOverlays notifications
+ * />` (`basalt-ui/commands`) — this subpath no longer ships one of its own (C1 consolidation:
+ * `BasaltNotifications` was superseded and is removed).
  *
  * Optional peer: @mantine/notifications ^9.3.0.
  *
@@ -10,8 +12,8 @@
  *
  * @example
  * // main.tsx — mount the overlay:
- * import { BasaltNotifications } from 'basalt-ui/notifications'
- * <BasaltProvider><BasaltNotifications /><App /></BasaltProvider>
+ * import { BasaltOverlays } from 'basalt-ui/commands'
+ * <BasaltProvider><BasaltOverlays><App /></BasaltOverlays></BasaltProvider>
  *
  * // Usage:
  * import { notifySuccess, notifyError, notifyPromise, NotificationBell } from 'basalt-ui/notifications'
@@ -84,7 +86,3 @@ export type { NotificationBellProps } from './bell'
 // ── NotificationCenter ────────────────────────────────────────────────────────
 export { NotificationCenter } from './center'
 export type { NotificationCenterProps } from './center'
-
-// ── BasaltNotifications overlay ───────────────────────────────────────────────
-export { BasaltNotifications } from './overlay'
-export type { BasaltNotificationsProps } from './overlay'

package/src/notifications/mount-guard.ts

@@ -1,10 +1,8 @@
 /**
  * Duplicate-Notifications-mount guard (F15) — a shared module-level counter, not a per-caller ref,
- * because the whole point is detecting a SECOND, unrelated caller: `<BasaltOverlays notifications />`
- * (`commands/overlays-mount.tsx`) and `<BasaltNotifications />` (`./overlay.tsx`) both render
- * Mantine's `<Notifications />` and neither can see the other mount. `overlays-mount.tsx`'s own
- * JSDoc has warned against combining them since it shipped ("do NOT mount both … (double-mount of
- * `<Notifications />`)") with nothing enforcing it — this is that enforcement, finally.
+ * because the whole point is detecting a SECOND, unrelated caller mounting `<BasaltOverlays
+ * notifications />` (`commands/overlays-mount.tsx`) at once — nested/duplicate mounts double-render
+ * Mantine's `<Notifications />` and neither instance can see the other.
  *
  * Lives here (`./notifications`), not `./commands`, so `commands` is the one importing a shared util
  * rather than the reverse — `./notifications` never depends on `./commands`. Zero `@mantine/*`
@@ -14,7 +12,7 @@
  * as `provider/lab-theme.ts`.
  */
 import { useEffect } from 'react'
-import { isDev } from '../utils/is-dev'
+import { isDev } from '../common/is-dev'
 
 let mountedNotificationsCount = 0
 
@@ -29,9 +27,9 @@ export function useNotificationsMountGuard(): void {
     mountedNotificationsCount++
     if (mountedNotificationsCount > 1 && isDev()) {
       console.warn(
-        '[basalt] more than one Notifications overlay is mounted at once — mount ONE of ' +
-          '<BasaltOverlays notifications /> or <BasaltNotifications />, never both (they both ' +
-          "render Mantine's <Notifications />, so toasts would double-fire).",
+        '[basalt] more than one Notifications overlay is mounted at once — mount exactly ONE ' +
+          "<BasaltOverlays notifications /> (they all render Mantine's <Notifications />, so " +
+          'toasts would double-fire).',
       )
     }
     return () => {

package/src/{connectivity → provider}/connectivity-indicator.tsx

@@ -19,7 +19,7 @@ import { useRef } from 'react'
 import type { BasaltProps } from '../common/props'
 import { alpha, VX } from '../tokens'
 import { useConnectivity } from './use-connectivity'
-import type { ConnectivityStatus } from './types'
+import type { ConnectivityStatus } from './connectivity-types'
 
 export type ConnectivityIndicatorProps = BasaltProps
 

package/src/{connectivity → provider}/connectivity-provider.tsx

@@ -8,7 +8,7 @@
 import { createContext, useCallback, useEffect, useMemo, useRef, useState } from 'react'
 import type { ReactNode } from 'react'
 import { onlineManager } from '@tanstack/react-query'
-import type { ConnectivitySnapshot, ConnectivityProviderProps } from './types'
+import type { ConnectivitySnapshot, ConnectivityProviderProps } from './connectivity-types'
 
 // ── SSR-safe default ────────────────────────────────────────────────────────────────────────────────
 

package/src/provider/error-fallback.module.css

@@ -0,0 +1,21 @@
+/* The boundary renders ABOVE MantineProvider, so its fallback is plain HTML styled here — no
+   Mantine primitive, no inline style object (hidden-inline-style). Tokens only. */
+.root {
+  max-width: 32rem;
+  margin: 0 auto;
+  padding: var(--vx-space-stack-xl);
+  display: flex;
+  flex-direction: column;
+  gap: var(--vx-space-stack-md);
+}
+
+.reload {
+  align-self: flex-start;
+  font: inherit;
+  cursor: pointer;
+  padding: var(--vx-space-stack-xs) var(--vx-space-stack-md);
+  border: 1px solid var(--vx-divider);
+  border-radius: var(--vx-radius-ctrl);
+  background: transparent;
+  color: inherit;
+}

package/src/provider/error-fallback.module.css.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Typed CSS-module declaration (the S4 CSS-modules path). Named string props — not an index
+ * signature — so dot access stays verbatim under the package's strict flags.
+ */
+declare const classes: {
+  readonly root: string
+  readonly reload: string
+}
+export default classes