basalt-ui 1.32.0 → 1.33.0

package/src/cli/config.ts

@@ -0,0 +1,209 @@
+// The `basalt` config shape and helpers, shared by the dispatcher and `--audit-allows`. A leaf: it
+// imports nothing from `./index`, so audit-allows → index → check-theme → audit-allows is no cycle.
+import type { GuardKind, GuardSeverity } from '../guard'
+
+/** Shape of the optional `"basalt"` key in a consumer's package.json. */
+export type BasaltConfig = {
+  /** Source roots to scan. Default: `['src']`. Set explicitly for a monorepo layout. */
+  roots?: string[]
+  /** Files exempt from the scan (they ARE the palette source). Default: argo's exempt set. */
+  exempt?: string[]
+  /**
+   * Declares this package a tokens-only consumer: it uses the `--vx-*` layer and no Mantine. Turns
+   * off every guard kind whose remedy is a Mantine component, a Mantine prop or the React theme
+   * factory, leaving the color and typography kinds live. Default: `'mantine'`.
+   *
+   * Deliberately not inferred from a missing `@mantine/core`: silencing 17 rules (the live count is
+   * `TOKENS_ONLY_DISABLED_KINDS.size`, which the check-theme banner prints) is a decision, and
+   * a repo that keeps Mantine in a workspace package would otherwise switch off half its own guard
+   * without saying so. `basalt-ui doctor` detects the shape and tells you to set this.
+   */
+  profile?: 'mantine' | 'tokens-only'
+  /**
+   * Extra files to scan, named individually and relative to this package — for a design surface
+   * that lives outside every root and outside the `index.html` / `public/` conventions the walker
+   * already derives. Also the ONLY way a `.json` is ever scanned: the guard understands JSON as
+   * markup, but a consumer repo's JSON is overwhelmingly config, fixtures and lockfiles, so
+   * blanket-scanning it is a false-positive generator rather than a guard.
+   *
+   * @example
+   * { include: ['app/manifest.json', 'emails/template.html'] }
+   */
+  include?: string[]
+  /** Named spacing-scale steps (px) flagged when used as a raw spacing prop. Default: 10/12/16/20/32. */
+  spacingSteps?: number[]
+  /** Per-kind severity override — `'warn'` reports without failing, `'error'` fails the build.
+   *  See `GuardSeverity` in ../guard/types for the grace-minor doctrine behind it. */
+  severity?: Partial<Record<GuardKind, GuardSeverity>>
+  /** Off-identity Mantine accent families forbidden as chrome accents. Default: argo's set. */
+  forbiddenAccents?: string[]
+  /** Earned accent hue recorded in DESIGN.md `{{ACCENT_HUE}}`. Default: `blue`. */
+  accentHue?: string
+  /**
+   * Flag any numeric radius prop literal (radius={6}) — use the radius token scale instead.
+   * Default: `true` (ON). Set `false` to disable the `raw-radius` check (e.g. a repo that DEFINES
+   * the radius primitives).
+   */
+  rawRadius?: boolean
+  /**
+   * Flag ad-hoc inline surface styling (`border`/`borderRadius`/`boxShadow` literals in a `style={{}}`)
+   * that bypasses the radius-token + `VX.surface.*` + `VX.shadowCard` system. Default: `true` (ON).
+   * Set `false` to disable the `raw-surface` check.
+   */
+  rawSurface?: boolean
+  /**
+   * Flag `withBorder` on a `Card` / `Paper`. Card depth is `--vx-shadow-card` — a whisper shadow
+   * with the 1px ring baked into the SAME value — so `withBorder` draws a SECOND, real border over
+   * that ring and the card reads heavy/boxed (docs/DESIGN-SPEC.md doctrine inversion #1).
+   * `withBorder={false}` and `<Card.Section withBorder>` (a section divider) both pass.
+   * Default: `true` (ON). Set `false` to disable the `card-with-border` check.
+   */
+  cardWithBorder?: boolean
+  /**
+   * Flag references to a raw Mantine ramp step used for surface color
+   * (`var(--mantine-color-gray-N)` / `var(--mantine-color-dark-N)`) — these bypass the basalt
+   * surface tokens. Default: `true` (ON). Set `false` to disable the `off-system-surface-var` check.
+   */
+  offSystemSurfaceVar?: boolean
+  /**
+   * Flag a SHADE-PINNED Mantine color — `c="yellow.7"`, `bg="blue.4"`,
+   * `var(--mantine-color-red-6)`. A pinned step is one fixed swatch in BOTH color schemes, so it
+   * cannot stay legible in either; route a verdict color through `VX.status.*` / `--vx-status-*`,
+   * or drop the index (`c="red"`) and let the theme resolve the shade per scheme. `gray-*`/`dark-*`
+   * in `var()` form belong to `off-system-surface-var` instead. Default: `true` (ON). Set `false`
+   * to disable the `mantine-shade-index` check.
+   */
+  mantineShadeIndex?: boolean
+  /**
+   * Flag raw lowercase JSX layout/surface elements (`div`/`span`/`section`/…) carrying an inline
+   * `style={{}}` with a layout/surface property — steer to a Mantine layout primitive
+   * (`Box`/`Flex`/`Grid`/`Stack`/`Group`/`SimpleGrid`/`Paper`). Default: `true` (ON). Set `false`
+   * to disable the `raw-html-layout` check.
+   */
+  rawHtmlLayout?: boolean
+  /**
+   * Flag spacing/sizing literals inside an inline `style={{}}` (`padding`/`margin`/`gap`/…) — the
+   * `raw-spacing` check only catches the Mantine prop syntax. Default: `true` (ON). Set `false` to
+   * disable the `inline-spacing` check.
+   */
+  inlineSpacing?: boolean
+  /**
+   * Flag `display: 'flex' | 'grid' | 'inline-flex' | 'inline-grid'` in an inline `style={{}}` —
+   * steer to `<Flex>`/`<Grid>`/`<Group>`. Default: `true` (ON). Set `false` to disable the
+   * `inline-display` check.
+   */
+  inlineDisplay?: boolean
+  /**
+   * Flag raw `<AxisLeft>` / `<AxisBottom>` / `<AxisRight>` visx JSX inside chart files (a path
+   * containing `/charts/`) — these bypass the `AxisLeftNumeric` / `AxisBottomDate` /
+   * `AxisRightNumeric` primitives that carry the theme tokens + smart ticks. The legitimate wrapper
+   * (`Axes.tsx`, which IS the primitive) is exempt. Default: `true` (ON). Set `false` to disable the
+   * `raw-visx-axis` check.
+   */
+  rawVisxAxis?: boolean
+  /**
+   * Flag a hardcoded duration/spring/ease literal inline in a `transition={{...}}` prop — route it
+   * through `MOTION_DURATION` / `MOTION_SPRING` / `MOTION_EASE_STANDARD` instead. Default: `true`
+   * (ON). Set `false` to disable the `raw-motion-value` check.
+   */
+  rawMotionValue?: boolean
+  /**
+   * Flag a chart entry-point JSX tag (`MultiLine`/`Bars`/`Donut`/`DualPanel`/`Heatmap`/`ZonedLine`/
+   * `StackedArea`/`LineSparkline`/`BarSparkline`) missing an `ariaLabel` prop. Default: `true`
+   * (ON). Set `false` to disable the `chart-missing-aria-label` check.
+   */
+  chartMissingAriaLabel?: boolean
+  /**
+   * Flag a raw lowercase `<input>`/`<select>`/`<textarea>` JSX element — it bypasses the entire
+   * theme, not just the iOS font-size floor. Use the Mantine equivalents (`TextInput`,
+   * `NumberInput`, `Select`, `Textarea`, …) instead. Default: `true` (ON). Set `false` to disable
+   * the `raw-form-control` check.
+   */
+  rawFormControl?: boolean
+  /**
+   * Flag a `fontSize`/`font-size` literal below 16 inside a `style={{…}}` on a raw form control,
+   * or a Mantine `styles={{ input: {…} }}` per-part style — the `styles.css` iOS floor is
+   * `!important`, so the override is dead code. Default: `true` (ON). Set `false` to disable the
+   * `sub-16-input-font` check.
+   */
+  sub16InputFont?: boolean
+  /**
+   * Path of the consumer's guard-exempt series file, for DESIGN.md `{{SERIES_MODULE_PATH}}`.
+   * Default: `<first basalt.root>/lib/series.ts` — see `resolveSeriesModulePath`.
+   */
+  seriesModulePath?: string
+  /**
+   * Per-rule, per-path exemptions — complements whole-file `exempt` (which skips ALL rules for a
+   * file) and the hardcoded per-kind `appliesTo` scoping (e.g. `raw-visx-axis` → chart files
+   * only). Each value is a list of patterns matched against a finding's relative path. A pattern
+   * may be a whole path segment (`'agent'` matches `src/agent/x.tsx`, not `src/agenting.ts`), a
+   * relative path (`'public/site.webmanifest'`), a directory prefix, or a glob — `*` stops at `/`,
+   * `**` does not, and a slash-free glob also matches the basename, so `'*.module.css'` works.
+   * A trailing `/` is stripped. An entry that suppresses nothing is reported, and
+   * `check-theme --audit-allows` exits 1 on it. Default: `{}` (no exemptions).
+   *
+   * Two forms per kind. The bare array is paths only. The object form adds the REASON, which is
+   * the half a `theme-allow` carries and this key could not: JSON has no comments, so a
+   * `.webmanifest` / `.json` finding's only escape is this key, and it was un-reviewable by
+   * construction — the rationale ended up in a CLAUDE.md paragraph nobody reads next to the diff.
+   * `check-theme --audit-allows` prints the reason (or names its absence) beside what the entry
+   * still suppresses. The array form stays supported and unchanged; nothing here is required.
+   *
+   * @example
+   * { exemptRules: { 'inline-display': ['agent'] } } // inline-display never fires under src/agent/**
+   * @example
+   * { exemptRules: { 'raw-hex': { paths: ['site.webmanifest'],
+   *   reason: 'a PWA manifest theme_color MUST be a literal hex — JSON cannot reference a CSS var' } } }
+   */
+  exemptRules?: Partial<Record<GuardKind, ExemptRuleEntry>>
+  /**
+   * Declares an intentional `ai` package major-version skew across workspace packages, exempting
+   * `doctor`'s `ai-major-parity` hard check. The value IS the reason — a bare `true` is rejected,
+   * because the whole point of this key is that the pairing is written down, not just switched off.
+   * A written declaration is the pin `basalt/ai-sdk-major`'s own comment notes is otherwise missing.
+   *
+   * Semantics: absent (or present but not a non-empty string) → the skew still hard-fails exactly as
+   * without this key. A non-empty string with a skew present → `doctor` passes, echoing both the
+   * skew and this reason. A non-empty string with NO skew present → `doctor` warns that the
+   * exemption is stale and can be deleted (an exemption nobody re-checks is how a real, later skew
+   * slips through unnoticed).
+   *
+   * @example
+   * // apps/api streams on ai@5; apps/dashboard parses on ai@7; a producer-side TransformStream
+   * // neutralizes the one enum value that differs between the two majors.
+   * { aiMajorSkewReason: 'apps/api pinned to ai@5, apps/dashboard on ai@7 — the skew is neutralized '
+   *   + 'by a producer-side TransformStream in apps/api/src/stream-transform.ts' }
+   */
+  aiMajorSkewReason?: string
+}
+
+/**
+ * One `basalt.exemptRules` value: the historical bare path list, or the same list with the reason
+ * it exists. See `BasaltConfig.exemptRules`.
+ */
+export type ExemptRuleEntry = string[] | { paths: string[]; reason: string }
+
+/** The paths half of an exemption entry, whichever form it was written in. */
+export function exemptRulePaths(entry: ExemptRuleEntry | undefined): string[] {
+  if (entry === undefined) return []
+  return Array.isArray(entry) ? entry : entry.paths
+}
+
+/** The recorded reason for an exemption entry, or null for the bare-array form. */
+export function exemptRuleReason(entry: ExemptRuleEntry | undefined): string | null {
+  if (entry === undefined || Array.isArray(entry)) return null
+  return entry.reason.trim().length > 0 ? entry.reason.trim() : null
+}
+
+export const DEFAULT_ROOT = 'src'
+export const DEFAULT_ROOTS = [DEFAULT_ROOT]
+
+/**
+ * The configured source roots, or the built-in default. The ONE resolution every roots-derived seed
+ * reads — an empty `roots: []` falls back rather than resolving to nothing, because a bare `??`
+ * would let `[]` through and render an empty oxfmt glob into the seeded CI, reproducing the exact
+ * "matches zero files" break this derivation exists to prevent.
+ */
+export function resolveRoots(cfg: BasaltConfig): string[] {
+  return cfg.roots?.length ? cfg.roots : DEFAULT_ROOTS
+}

package/src/cli/doctor.ts

@@ -6,7 +6,7 @@
 import { existsSync } from 'node:fs'
 import { relative, resolve } from 'node:path'
 
-import type { BasaltConfig } from './index'
+import type { BasaltConfig } from './config'
 import {
   MANIFEST_PATH,
   basaltBinCommand,
@@ -21,10 +21,10 @@ import {
   readIfExists,
   readManifest,
   resolveProjectDir,
-  resolveRoots,
   scannableFiles,
   shippedAssetPath,
 } from './index'
+import { resolveRoots } from './config'
 import { findManifestAbove, parentInstallAdvice } from './sync'
 
 export type DoctorResult = {

package/src/cli/guard-hook.ts

@@ -8,14 +8,8 @@ import { isAbsolute, relative, resolve } from 'node:path'
 import { DEFAULT_GUARD_CONFIG } from '../guard'
 import type { GuardConfig } from '../guard'
 import { evaluateGuardHook } from '../guard/guard-hook'
-import {
-  DEFAULT_ROOTS,
-  SKIP,
-  declaredProfile,
-  defaultExempt,
-  readBasaltConfig,
-  resolveExemptRules,
-} from './index'
+import { SKIP, declaredProfile, defaultExempt, readBasaltConfig, resolveExemptRules } from './index'
+import { DEFAULT_ROOTS } from './config'
 
 /**
  * guard-hook — PreToolUse stdin adapter.

package/src/cli/index.ts

@@ -39,199 +39,8 @@ import { COMMAND_OPTIONS, USAGE, unknownFlag } from './help'
 import { init } from './init'
 import { sync } from './sync'
 import { fontsCss, normalizeColorFunctions, tokensCss } from './tokens-css'
-
-/** Shape of the optional `"basalt"` key in a consumer's package.json. */
-export type BasaltConfig = {
-  /** Source roots to scan. Default: `['src']`. Set explicitly for a monorepo layout. */
-  roots?: string[]
-  /** Files exempt from the scan (they ARE the palette source). Default: argo's exempt set. */
-  exempt?: string[]
-  /**
-   * Declares this package a tokens-only consumer: it uses the `--vx-*` layer and no Mantine. Turns
-   * off every guard kind whose remedy is a Mantine component, a Mantine prop or the React theme
-   * factory, leaving the color and typography kinds live. Default: `'mantine'`.
-   *
-   * Deliberately not inferred from a missing `@mantine/core`: silencing 17 rules (the live count is
-   * `TOKENS_ONLY_DISABLED_KINDS.size`, which the check-theme banner prints) is a decision, and
-   * a repo that keeps Mantine in a workspace package would otherwise switch off half its own guard
-   * without saying so. `basalt-ui doctor` detects the shape and tells you to set this.
-   */
-  profile?: 'mantine' | 'tokens-only'
-  /**
-   * Extra files to scan, named individually and relative to this package — for a design surface
-   * that lives outside every root and outside the `index.html` / `public/` conventions the walker
-   * already derives. Also the ONLY way a `.json` is ever scanned: the guard understands JSON as
-   * markup, but a consumer repo's JSON is overwhelmingly config, fixtures and lockfiles, so
-   * blanket-scanning it is a false-positive generator rather than a guard.
-   *
-   * @example
-   * { include: ['app/manifest.json', 'emails/template.html'] }
-   */
-  include?: string[]
-  /** Named spacing-scale steps (px) flagged when used as a raw spacing prop. Default: 10/12/16/20/32. */
-  spacingSteps?: number[]
-  /** Per-kind severity override — `'warn'` reports without failing, `'error'` fails the build.
-   *  See `GuardSeverity` in ../guard/types for the grace-minor doctrine behind it. */
-  severity?: Partial<Record<GuardKind, GuardSeverity>>
-  /** Off-identity Mantine accent families forbidden as chrome accents. Default: argo's set. */
-  forbiddenAccents?: string[]
-  /** Earned accent hue recorded in DESIGN.md `{{ACCENT_HUE}}`. Default: `blue`. */
-  accentHue?: string
-  /**
-   * Flag any numeric radius prop literal (radius={6}) — use the radius token scale instead.
-   * Default: `true` (ON). Set `false` to disable the `raw-radius` check (e.g. a repo that DEFINES
-   * the radius primitives).
-   */
-  rawRadius?: boolean
-  /**
-   * Flag ad-hoc inline surface styling (`border`/`borderRadius`/`boxShadow` literals in a `style={{}}`)
-   * that bypasses the radius-token + `VX.surface.*` + `VX.shadowCard` system. Default: `true` (ON).
-   * Set `false` to disable the `raw-surface` check.
-   */
-  rawSurface?: boolean
-  /**
-   * Flag `withBorder` on a `Card` / `Paper`. Card depth is `--vx-shadow-card` — a whisper shadow
-   * with the 1px ring baked into the SAME value — so `withBorder` draws a SECOND, real border over
-   * that ring and the card reads heavy/boxed (docs/DESIGN-SPEC.md doctrine inversion #1).
-   * `withBorder={false}` and `<Card.Section withBorder>` (a section divider) both pass.
-   * Default: `true` (ON). Set `false` to disable the `card-with-border` check.
-   */
-  cardWithBorder?: boolean
-  /**
-   * Flag references to a raw Mantine ramp step used for surface color
-   * (`var(--mantine-color-gray-N)` / `var(--mantine-color-dark-N)`) — these bypass the basalt
-   * surface tokens. Default: `true` (ON). Set `false` to disable the `off-system-surface-var` check.
-   */
-  offSystemSurfaceVar?: boolean
-  /**
-   * Flag a SHADE-PINNED Mantine color — `c="yellow.7"`, `bg="blue.4"`,
-   * `var(--mantine-color-red-6)`. A pinned step is one fixed swatch in BOTH color schemes, so it
-   * cannot stay legible in either; route a verdict color through `VX.status.*` / `--vx-status-*`,
-   * or drop the index (`c="red"`) and let the theme resolve the shade per scheme. `gray-*`/`dark-*`
-   * in `var()` form belong to `off-system-surface-var` instead. Default: `true` (ON). Set `false`
-   * to disable the `mantine-shade-index` check.
-   */
-  mantineShadeIndex?: boolean
-  /**
-   * Flag raw lowercase JSX layout/surface elements (`div`/`span`/`section`/…) carrying an inline
-   * `style={{}}` with a layout/surface property — steer to a Mantine layout primitive
-   * (`Box`/`Flex`/`Grid`/`Stack`/`Group`/`SimpleGrid`/`Paper`). Default: `true` (ON). Set `false`
-   * to disable the `raw-html-layout` check.
-   */
-  rawHtmlLayout?: boolean
-  /**
-   * Flag spacing/sizing literals inside an inline `style={{}}` (`padding`/`margin`/`gap`/…) — the
-   * `raw-spacing` check only catches the Mantine prop syntax. Default: `true` (ON). Set `false` to
-   * disable the `inline-spacing` check.
-   */
-  inlineSpacing?: boolean
-  /**
-   * Flag `display: 'flex' | 'grid' | 'inline-flex' | 'inline-grid'` in an inline `style={{}}` —
-   * steer to `<Flex>`/`<Grid>`/`<Group>`. Default: `true` (ON). Set `false` to disable the
-   * `inline-display` check.
-   */
-  inlineDisplay?: boolean
-  /**
-   * Flag raw `<AxisLeft>` / `<AxisBottom>` / `<AxisRight>` visx JSX inside chart files (a path
-   * containing `/charts/`) — these bypass the `AxisLeftNumeric` / `AxisBottomDate` /
-   * `AxisRightNumeric` primitives that carry the theme tokens + smart ticks. The legitimate wrapper
-   * (`Axes.tsx`, which IS the primitive) is exempt. Default: `true` (ON). Set `false` to disable the
-   * `raw-visx-axis` check.
-   */
-  rawVisxAxis?: boolean
-  /**
-   * Flag a hardcoded duration/spring/ease literal inline in a `transition={{...}}` prop — route it
-   * through `MOTION_DURATION` / `MOTION_SPRING` / `MOTION_EASE_STANDARD` instead. Default: `true`
-   * (ON). Set `false` to disable the `raw-motion-value` check.
-   */
-  rawMotionValue?: boolean
-  /**
-   * Flag a chart entry-point JSX tag (`MultiLine`/`Bars`/`Donut`/`DualPanel`/`Heatmap`/`ZonedLine`/
-   * `StackedArea`/`LineSparkline`/`BarSparkline`) missing an `ariaLabel` prop. Default: `true`
-   * (ON). Set `false` to disable the `chart-missing-aria-label` check.
-   */
-  chartMissingAriaLabel?: boolean
-  /**
-   * Flag a raw lowercase `<input>`/`<select>`/`<textarea>` JSX element — it bypasses the entire
-   * theme, not just the iOS font-size floor. Use the Mantine equivalents (`TextInput`,
-   * `NumberInput`, `Select`, `Textarea`, …) instead. Default: `true` (ON). Set `false` to disable
-   * the `raw-form-control` check.
-   */
-  rawFormControl?: boolean
-  /**
-   * Flag a `fontSize`/`font-size` literal below 16 inside a `style={{…}}` on a raw form control,
-   * or a Mantine `styles={{ input: {…} }}` per-part style — the `styles.css` iOS floor is
-   * `!important`, so the override is dead code. Default: `true` (ON). Set `false` to disable the
-   * `sub-16-input-font` check.
-   */
-  sub16InputFont?: boolean
-  /**
-   * Path of the consumer's guard-exempt series file, for DESIGN.md `{{SERIES_MODULE_PATH}}`.
-   * Default: `<first basalt.root>/lib/series.ts` — see `resolveSeriesModulePath`.
-   */
-  seriesModulePath?: string
-  /**
-   * Per-rule, per-path exemptions — complements whole-file `exempt` (which skips ALL rules for a
-   * file) and the hardcoded per-kind `appliesTo` scoping (e.g. `raw-visx-axis` → chart files
-   * only). Each value is a list of patterns matched against a finding's relative path. A pattern
-   * may be a whole path segment (`'agent'` matches `src/agent/x.tsx`, not `src/agenting.ts`), a
-   * relative path (`'public/site.webmanifest'`), a directory prefix, or a glob — `*` stops at `/`,
-   * `**` does not, and a slash-free glob also matches the basename, so `'*.module.css'` works.
-   * A trailing `/` is stripped. An entry that suppresses nothing is reported, and
-   * `check-theme --audit-allows` exits 1 on it. Default: `{}` (no exemptions).
-   *
-   * Two forms per kind. The bare array is paths only. The object form adds the REASON, which is
-   * the half a `theme-allow` carries and this key could not: JSON has no comments, so a
-   * `.webmanifest` / `.json` finding's only escape is this key, and it was un-reviewable by
-   * construction — the rationale ended up in a CLAUDE.md paragraph nobody reads next to the diff.
-   * `check-theme --audit-allows` prints the reason (or names its absence) beside what the entry
-   * still suppresses. The array form stays supported and unchanged; nothing here is required.
-   *
-   * @example
-   * { exemptRules: { 'inline-display': ['agent'] } } // inline-display never fires under src/agent/**
-   * @example
-   * { exemptRules: { 'raw-hex': { paths: ['site.webmanifest'],
-   *   reason: 'a PWA manifest theme_color MUST be a literal hex — JSON cannot reference a CSS var' } } }
-   */
-  exemptRules?: Partial<Record<GuardKind, ExemptRuleEntry>>
-  /**
-   * Declares an intentional `ai` package major-version skew across workspace packages, exempting
-   * `doctor`'s `ai-major-parity` hard check. The value IS the reason — a bare `true` is rejected,
-   * because the whole point of this key is that the pairing is written down, not just switched off.
-   * A written declaration is the pin `basalt/ai-sdk-major`'s own comment notes is otherwise missing.
-   *
-   * Semantics: absent (or present but not a non-empty string) → the skew still hard-fails exactly as
-   * without this key. A non-empty string with a skew present → `doctor` passes, echoing both the
-   * skew and this reason. A non-empty string with NO skew present → `doctor` warns that the
-   * exemption is stale and can be deleted (an exemption nobody re-checks is how a real, later skew
-   * slips through unnoticed).
-   *
-   * @example
-   * // apps/api streams on ai@5; apps/dashboard parses on ai@7; a producer-side TransformStream
-   * // neutralizes the one enum value that differs between the two majors.
-   * { aiMajorSkewReason: 'apps/api pinned to ai@5, apps/dashboard on ai@7 — the skew is neutralized '
-   *   + 'by a producer-side TransformStream in apps/api/src/stream-transform.ts' }
-   */
-  aiMajorSkewReason?: string
-}
-
-/**
- * One `basalt.exemptRules` value: the historical bare path list, or the same list with the reason
- * it exists. See `BasaltConfig.exemptRules`.
- */
-export type ExemptRuleEntry = string[] | { paths: string[]; reason: string }
-
-/** The paths half of an exemption entry, whichever form it was written in. */
-export function exemptRulePaths(entry: ExemptRuleEntry | undefined): string[] {
-  if (entry === undefined) return []
-  return Array.isArray(entry) ? entry : entry.paths
-}
-
-/** The recorded reason for an exemption entry, or null for the bare-array form. */
-export function exemptRuleReason(entry: ExemptRuleEntry | undefined): string | null {
-  if (entry === undefined || Array.isArray(entry)) return null
-  return entry.reason.trim().length > 0 ? entry.reason.trim() : null
-}
+import { DEFAULT_ROOT, exemptRulePaths, resolveRoots } from './config'
+import type { BasaltConfig } from './config'
 
 /**
  * The guard-shaped `exemptRules` — paths only. The reason the object form carries never reaches
@@ -247,19 +56,6 @@ export function resolveExemptRules(cfg: BasaltConfig): GuardConfig['exemptRules'
   return out
 }
 
-export const DEFAULT_ROOT = 'src'
-export const DEFAULT_ROOTS = [DEFAULT_ROOT]
-
-/**
- * The configured source roots, or the built-in default. The ONE resolution every roots-derived seed
- * reads — an empty `roots: []` falls back rather than resolving to nothing, because a bare `??`
- * would let `[]` through and render an empty oxfmt glob into the seeded CI, reproducing the exact
- * "matches zero files" break this derivation exists to prevent.
- */
-export function resolveRoots(cfg: BasaltConfig): string[] {
-  return cfg.roots?.length ? cfg.roots : DEFAULT_ROOTS
-}
-
 /**
  * The one consumer series path — the DESIGN.md template's `{{SERIES_MODULE_PATH}}`, the default
  * scan exemption, and the skills' prose all resolve through this single function.

package/src/commands/define-commands.ts

@@ -24,7 +24,6 @@
  */
 import type { ReactNode } from 'react'
 import type { Slot } from '../register'
-import { isDev } from '../common/is-dev'
 
 // ── Context ───────────────────────────────────────────────────────────────────
 
@@ -172,7 +171,8 @@ export function defineCommand(cmd: Command): Command {
 export function runCommand(id: CommandId, ctx?: CommandRunContext): void | Promise<void> {
   const cmd = activeCommands[id as string]
   if (cmd === undefined) {
-    if (isDev()) console.warn(`[basalt] runCommand: no command registered for "${id}"`)
+    if (process.env.NODE_ENV !== 'production')
+      console.warn(`[basalt] runCommand: no command registered for "${id}"`)
     return
   }
   return cmd.run(ctx)

package/src/commands/define-overlays.ts

@@ -29,7 +29,6 @@ import type { ReactNode } from 'react'
 import { useEffect } from 'react'
 import { missingLayer } from '../common/errors'
 import type { Slot } from '../register'
-import { isDev } from '../common/is-dev'
 
 // ── Lazy @mantine/modals resolution ───────────────────────────────────────────
 // @mantine/modals is an OPTIONAL peer — never imported at module evaluation time, so importing
@@ -372,7 +371,7 @@ export const overlays = {
   open<K extends OverlayKey>(key: K, props: OverlayProps<K>): void {
     const spec = activeOverlays[key as string]
     if (spec === undefined) {
-      if (isDev())
+      if (process.env.NODE_ENV !== 'production')
         console.warn(`[basalt] overlays.open: no overlay registered for "${String(key)}"`)
       return
     }

package/src/common/index.ts

@@ -19,5 +19,4 @@ export {
 } from './errors'
 export { useValidateProps, assertRequiredProps, resetValidatedProps } from './validate'
 export { scrollParentOf, SCROLLPORT_ATTRIBUTE } from './scroll-parent'
-export { isDev } from './is-dev'
 export { MOTION_DURATION, MOTION_EASE_STANDARD, MOTION_SPRING } from './motion'

package/src/common/validate.ts

@@ -7,7 +7,6 @@
  * mean warns once in dev and renders on (`useValidateProps`).
  */
 import { useEffect } from 'react'
-import { isDev } from './is-dev'
 import { requiredProp } from './errors'
 
 /** A check returns the message(s) it has, or nothing. `null`/`undefined` entries are ignored. */
@@ -23,8 +22,8 @@ const reported = new Set<string>()
 
 /**
  * Dev-only prop validation. `console.error`s each message ONCE per `(component, message)` pair, and
- * is a no-op in production: `isDev()` reads `process.env.NODE_ENV`, which every bundler
- * constant-folds, so the whole body disappears from a production build.
+ * is a no-op in production: the gate is a literal `process.env.NODE_ENV` read, which every bundler
+ * constant-folds, so the whole body disappears from a production build (see `dev-gate.test.ts`).
  *
  * **The dedup key is `${component} ${message}`, and nothing else** — not the instance, not the
  * props. Two instances of one component producing the SAME message say it once between them, which
@@ -46,7 +45,7 @@ export function useValidateProps(
   deps: unknown[],
 ): void {
   useEffect(() => {
-    if (!isDev()) return
+    if (process.env.NODE_ENV === 'production') return
     const result = check()
     const messages = Array.isArray(result) ? result : [result]
     for (const raw of messages) {
@@ -67,7 +66,7 @@ export function useValidateProps(
  * are about to win in the very next render.
  */
 export function reportOnce(component: string, message: string): void {
-  if (!isDev()) return
+  if (process.env.NODE_ENV === 'production') return
   const key = `${component} ${message}`
   if (reported.has(key)) return
   reported.add(key)

package/src/content/article-card.tsx

@@ -166,6 +166,7 @@ export type ArticleGridProps = {
 
 export function ArticleGrid({ children, cols = 3 }: ArticleGridProps) {
   return (
+    // theme-allow raw-breakpoint — `cols` is documented per viewport `lg`; container keys would re-flow every consumer's grid, so that move ships opt-in
     <SimpleGrid cols={{ base: 1, sm: 2, lg: cols }} spacing="sm">
       {children}
     </SimpleGrid>

package/src/controls/enum-filter.tsx

@@ -26,13 +26,13 @@
  * its doc). Both public wrappers still type `field` exactly, so a wrong field kind is still a type
  * error at the call site; the widening lives here, where nothing consumer-facing points at it.
  */
-import { Button, Radio, Stack } from '@mantine/core'
+import { Radio, Stack } from '@mantine/core'
 import type { ReactNode } from 'react'
 import type { BasaltProps } from '../common/props'
 import type { FieldOption } from '../state'
 import classes from './controls.module.css'
 import { POPOVER_ROW_HIT_GAP, useFilterRegistration, useFilterSurface } from './filter-context'
-import { FilterPill } from './filter-pill'
+import { FilterClearButton, FilterPill } from './filter-pill'
 import { useControlName } from './filter-sheet'
 import { PanelChoice, PanelRow } from './panel-row'
 import type { FilterOption } from './select-filter'
@@ -157,17 +157,7 @@ export function EnumFilter<T extends string>({
           />
         ))}
       </Stack>
-      {clearable === true && !isDefault && (
-        <Button
-          variant="subtle"
-          size="ctl"
-          onClick={() => {
-            field.clear()
-          }}
-        >
-          Clear
-        </Button>
-      )}
+      {clearable === true && !isDefault && <FilterClearButton onClear={() => field.clear()} />}
     </Radio.Group>
   )
 

package/src/controls/filter-pill.tsx

@@ -122,3 +122,23 @@ export function FilterPill({
     </Popover>
   )
 }
+
+/**
+ * The popover's `Clear` — one button for `EnumFilter`, `NumberFilter` and `MultiSelectFilter`. Its
+ * mousedown keeps focus where it is: a stepper commits its draft on blur, so a press that blurred
+ * first would land the typed value in the URL a tick before the clear replaced it.
+ */
+export function FilterClearButton({ onClear }: { readonly onClear: () => void }): ReactNode {
+  return (
+    <Button
+      variant="subtle"
+      size="ctl"
+      onMouseDown={(event) => {
+        event.preventDefault()
+      }}
+      onClick={onClear}
+    >
+      Clear
+    </Button>
+  )
+}

package/src/controls/multi-select-filter.tsx

@@ -22,7 +22,7 @@
  * // arrive as a map rather than baked into the labels the way the runtime catalogue does it.
  * <MultiSelectFilter field={shipments.field.origin} label="Origin" counts={countsByOrigin} />
  */
-import { Button, Checkbox, Stack } from '@mantine/core'
+import { Checkbox, Stack } from '@mantine/core'
 import { useState } from 'react'
 import type { CSSProperties, ReactNode } from 'react'
 import type { BasaltProps } from '../common/props'
@@ -31,7 +31,7 @@ import type { FieldHandle, MultiField } from '../state'
 import type { FilterOption } from './select-filter'
 import classes from './controls.module.css'
 import { POPOVER_ROW_HIT_GAP, useFilterRegistration, useFilterSurface } from './filter-context'
-import { FilterPill } from './filter-pill'
+import { FilterClearButton, FilterPill } from './filter-pill'
 import { CheckGlyph, useControlName } from './filter-sheet'
 import { PanelRow } from './panel-row'
 
@@ -153,17 +153,7 @@ export function MultiSelectFilter<T extends string>(props: MultiSelectFilterProp
           />
         ))}
       </Stack>
-      {!isDefault && (
-        <Button
-          variant="subtle"
-          size="ctl"
-          onClick={() => {
-            field.clear()
-          }}
-        >
-          Clear
-        </Button>
-      )}
+      {!isDefault && <FilterClearButton onClear={() => field.clear()} />}
     </Checkbox.Group>
   )