basalt-ui 1.32.1 → 1.34.0

package/src/agent/coalesce.ts

@@ -38,7 +38,6 @@
  * <PartList parts={coalesceParts(parts)} />
  */
 import type { AgentPart, ReasoningPart, TextPart, ToolCallPart } from './parts'
-import { isDev } from '../common/is-dev'
 
 type TextLike = TextPart | ReasoningPart
 
@@ -170,7 +169,7 @@ function mergeToolPart(existing: ToolCallPart, next: ToolCallPart): ToolCallPart
       // and make every field read below a compile error, so the assertion is what makes the
       // runtime value usable. It asserts nothing tsc has not already proved on the line above.
       const fallback = unhandled as ToolCallPart
-      if (isDev()) {
+      if (process.env.NODE_ENV !== 'production') {
         console.warn(
           `[basalt] coalesceParts: unrecognized tool state ${JSON.stringify(fallback.state)} — kept, merged best-effort`,
         )

package/src/agent/merge.ts

@@ -29,7 +29,6 @@
  * // parts === [{ id: 'p1', type: 'text', text: 'Hello' }]
  */
 import type { ReasoningPart, TextPart } from './parts'
-import { isDev } from '../common/is-dev'
 
 type TextLike = TextPart | ReasoningPart
 
@@ -79,7 +78,7 @@ function clampOffset(offset: number, length: number): number {
   // A non-finite offset would make every slice() return '' and blank the part outright — it is
   // out of range like any other, and appending is the safe reading of "position unknown".
   const clamped = Number.isFinite(offset) ? Math.min(Math.max(offset, 0), length) : length
-  if (clamped !== offset && isDev()) {
+  if (clamped !== offset && process.env.NODE_ENV !== 'production') {
     console.warn(
       `[basalt] mergePart: text offset ${offset} out of range [0, ${length}] — clamped to ${clamped}`,
     )

package/src/agent-chat/relative-time.ts

@@ -7,7 +7,6 @@
  *
  * Internal to `agent-chat/` — not part of the public barrel.
  */
-import { isDev } from '../common/is-dev'
 
 const RELATIVE_TIME_FORMAT = new Intl.RelativeTimeFormat('en', { numeric: 'auto' })
 
@@ -41,7 +40,7 @@ const RELATIVE_TIME_UNITS: readonly {
  */
 export function formatRelativeTime(timestamp: number): string {
   if (!Number.isFinite(timestamp)) {
-    if (isDev()) {
+    if (process.env.NODE_ENV !== 'production') {
       console.warn(
         `[basalt] formatRelativeTime: non-finite timestamp ${String(timestamp)} — rendering empty string`,
       )

package/src/agent-chat/thread-message.tsx

@@ -60,7 +60,6 @@ import { formatRelativeTime } from './relative-time'
 import { ToolChip } from './tool-chip'
 import { resolveVirtualize } from './virtualize'
 import type { VirtualizeOptions, VirtualizeProps } from './virtualize'
-import { isDev } from '../common/is-dev'
 
 /** The mono, uppercase, letter-spaced micro-label idiom (docs/DESIGN-SPEC.md §3) — shared by the
  * transcript's role labels and the reasoning/tool-call headers below. */
@@ -189,11 +188,11 @@ function UnknownPartChip({ part }: { part: ForeignPart }): JSX.Element {
   )
 }
 
-/** Consulted only when `ThreadTranscript` gets no `fallbackRenderer` prop. `isDev()` reads
+/** Consulted only when `ThreadTranscript` gets no `fallbackRenderer` prop. The gate reads
  * `process.env.NODE_ENV` (not `import.meta.env` — basalt-ui bans it) INSIDE the render so tests can
  * flip it. */
 const DEFAULT_FALLBACK_RENDERER: PartRenderer<ForeignPart> = ({ part }) =>
-  isDev() ? <UnknownPartChip part={part} /> : null
+  process.env.NODE_ENV !== 'production' ? <UnknownPartChip part={part} /> : null
 
 // ── Part resolution — the three-step order that is the whole design ───────────
 //

package/src/charts/kinds/BandStrip.tsx

@@ -17,7 +17,6 @@ import type { ChartState } from '../primitives/ChartPending'
 import type { ChartLegendConfig, SeriesStyle } from '../series'
 import { fmtAxisDate } from '../utils/format'
 import { BandAxisOverlay, BandTooltip, clampFraction } from './band-chrome'
-import { isDev } from '../../common/is-dev'
 
 /**
  * A state a strip can draw. Extends `SeriesStyle` rather than `ChartSeries` because a band has no
@@ -266,7 +265,8 @@ function BandStripPlot<T>(props: BandStripPlotProps<T>) {
       const style = styleByKey.get(span.state)
       const x = i * step
       if (style === undefined) {
-        if (isDev()) throw unknownStateError('BandSpan.state', span.state, styleByKey.keys())
+        if (process.env.NODE_ENV !== 'production')
+          throw unknownStateError('BandSpan.state', span.state, styleByKey.keys())
         out.push(
           <rect
             key={getX(d)}
@@ -298,7 +298,11 @@ function BandStripPlot<T>(props: BandStripPlotProps<T>) {
       const hatchWidth = bandWidth - measuredWidth
       const markerKey = span.marker?.state ?? span.state
       const markerColor = styleByKey.get(markerKey)?.color
-      if (span.marker !== undefined && markerColor === undefined && isDev()) {
+      if (
+        span.marker !== undefined &&
+        markerColor === undefined &&
+        process.env.NODE_ENV !== 'production'
+      ) {
         throw unknownStateError('BandSpan.marker.state', markerKey, styleByKey.keys())
       }
       const inset = span.marker?.inset ?? DEFAULT_MARKER_INSET

package/src/charts/kinds/Bars.tsx

@@ -13,7 +13,6 @@ import type { ChartState } from '../primitives/ChartPending'
 import { curveFor, LINE_OVERLAY_STROKE_WIDTH } from '../series'
 import type { ChartLegendConfig, ChartSeries, SeriesCurve } from '../series'
 import { padAutoLower } from '../utils/domain'
-import { isDev } from '../../common/is-dev'
 
 /**
  * `T = unknown` is load-bearing, not a shortcut: it keeps a consumer's existing
@@ -196,7 +195,7 @@ function BarsInner<T>(props: BarsProps<T>) {
   // Stacking sums bar heights via `posOffset`/`negOffset` in yScale units directly — a log axis
   // has no additive zero, so a stacked total is meaningless on it (`docs/CHARTS-SPEC.md`'s null-gap
   // + log contract). `grouped` bars only ever read one bar's own scaled value, so they're unaffected.
-  if (isDev() && barLayout === 'stacked' && y?.scale === 'log') {
+  if (process.env.NODE_ENV !== 'production' && barLayout === 'stacked' && y?.scale === 'log') {
     throw new Error(
       'Bars: stacked bars cannot use a log axis (y.scale: "log") — the stack sums bar heights, ' +
         "and a log axis has no additive zero to sum from. Use barLayout: 'grouped' instead.",

package/src/charts/kinds/StackedArea.tsx

@@ -9,7 +9,6 @@ import type { ResponsiveChartHeight } from '../primitives/ChartFrame'
 import type { ChartState } from '../primitives/ChartPending'
 import { curveFor } from '../series'
 import type { ChartLegendConfig, ChartSeries } from '../series'
-import { isDev } from '../../common/is-dev'
 
 export type StackedAreaProps<T> = BasaltProps & {
   data: T[]
@@ -113,7 +112,10 @@ function StackedAreaInner<T>(props: StackedAreaProps<T>) {
 
   // The stack sums band heights via `getValue` totals directly — a log axis has no additive zero
   // to sum from (`docs/CHARTS-SPEC.md`'s null-gap + log contract, mirrored from `Bars`' own guard).
-  if (isDev() && (y as { scale?: string } | undefined)?.scale === 'log') {
+  if (
+    process.env.NODE_ENV !== 'production' &&
+    (y as { scale?: string } | undefined)?.scale === 'log'
+  ) {
     throw new Error(
       'StackedArea: cannot use a log axis (y.scale: "log") — the stack sums band heights, ' +
         'and a log axis has no additive zero to sum from.',

package/src/charts/primitives/legend-disclosure.tsx

@@ -43,6 +43,7 @@ function disclosurePlacement(chip: DOMRect, coarse: boolean): CSSProperties {
     }
   }
   const below = window.innerHeight - chip.bottom
+  // theme-allow raw-breakpoint — clamps a fixed panel inside the viewport; a position, not a breakpoint
   const left = Math.max(8, Math.min(chip.left, window.innerWidth - 248))
   const base = { left, right: 'auto', minWidth: 200, maxWidth: 'calc(100vw - 16px)' }
   return below >= 200 || below >= chip.top

package/src/cli/audit-allows.ts

@@ -13,8 +13,8 @@ import {
   unmatchedExemptPatterns,
 } from '../guard'
 import type { Finding, GuardConfig, GuardKind } from '../guard'
-import type { BasaltConfig, ExemptRuleEntry } from './index'
-import { exemptRulePaths, exemptRuleReason, resolveRoots } from './index'
+import { exemptRulePaths, exemptRuleReason, resolveRoots } from './config'
+import type { BasaltConfig, ExemptRuleEntry } from './config'
 
 // ── check-theme --audit-allows — every waiver, and whether it still suppresses anything ─────────
 
@@ -30,7 +30,7 @@ type PluginProbe = {
   readonly rel: string
   /** 1-based line of the annotation, as {@link findAllowAnnotations} reports it. */
   readonly line: number
-  readonly ids: readonly string[]
+  readonly reach: string
   readonly site: string
   readonly suffix: string
 }
@@ -231,14 +231,15 @@ export function auditAllows(
         waiverLines.push(`${label} suppresses ${[...new Set(revealed)].join(', ')}${suffix}`)
         continue
       }
-      // Nothing in check-theme's reach moved. If the annotation names a PLUGIN rule, the oxlint
-      // half decides it — a placeholder holds the slot so the report stays in file/line order.
-      if (site.pluginRules.length > 0 && site.guardKinds.length === 0) {
+      // Nothing the guard reaches moved: oxlint decides it (a placeholder keeps the report order).
+      if (site.oxlintRules.length > 0) {
         pluginProbes.push({
           slot: waiverLines.length,
           rel,
           line: site.line,
-          ids: site.pluginRules,
+          reach: site.bare
+            ? 'a bare annotation, waiving every oxlint plugin rule on its line'
+            : `scoped to ${site.oxlintRules.join(', ')}, which oxlint judges`,
           site: label,
           suffix,
         })
@@ -266,8 +267,8 @@ export function auditAllows(
     if (revealed === undefined) {
       outOfReach++
       waiverLines[probe.slot] =
-        `${probe.site} scoped to ${probe.ids.join(', ')} — an oxlint plugin rule, and oxlint ` +
-        `could not be run here, so this audit cannot judge it${probe.suffix}`
+        `${probe.site} ${probe.reach} — and oxlint could not be run here, so this audit ` +
+        `cannot judge it${probe.suffix}`
       continue
     }
     if (revealed.length > 0) {

package/src/cli/check-theme.ts

@@ -3,32 +3,80 @@
  * Imports its shared plumbing (config/project resolution) back from `./index`, and its
  * `--audit-allows` mode from `./audit-allows`.
  */
-import { readFileSync } from 'node:fs'
-import { resolve } from 'node:path'
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
 
 import {
   checkSource,
-  DEFAULT_GUARD_CONFIG,
   guardKindRemedy,
   TOKENS_ONLY_DISABLED_KINDS,
   unmatchedExemptPatterns,
 } from '../guard'
-import type { Finding, GuardConfig } from '../guard'
+import type { Finding } from '../guard'
 import { auditAllows } from './audit-allows'
+import { DEFAULT_ROOTS, resolveRoots } from './config'
 import {
+  basaltPresetEntry,
   conflictingProfileFlags,
+  findRepoRoot,
   declaredProfile,
-  DEFAULT_ROOTS,
   hasBasaltKey,
+  namesShipped,
+  noteRelocation,
+  OXLINT_FILES,
+  packageRoot,
+  parseJsonc,
   readBasaltConfig,
-  resolveExemptRules,
+  readIfExists,
+  readSource,
+  resolveGuardConfig,
   resolveProjectDir,
-  resolveRoots,
   scannableFiles,
   SERIES_MODULE_HINT_RE,
   waiverHintFor,
 } from './index'
 
+/**
+ * What the `.oxlintrc.json` in `dir` does for the AST lane. A plugin load alone enables no rule, so
+ * it counts only beside a `basalt/*` rule of its own; an extends counts when it is a shipped preset.
+ */
+function oxlintLaneAt(dir: string): 'absent' | 'wired' | 'unwired' {
+  const raw = readIfExists(resolve(dir, '.oxlintrc.json'))
+  if (raw === null) return 'absent'
+  const rc = parseJsonc(raw)
+  const ownRules = Object.keys(Object(rc?.['rules'])).some((id) => id.startsWith('basalt/'))
+  const plugin = ownRules
+    ? [rc?.['jsPlugins']].flat().find((e) => namesShipped(e, OXLINT_FILES.plugin))
+    : undefined
+  const entry = basaltPresetEntry(rc?.['extends']) ?? plugin
+  return entry !== undefined && existsSync(resolve(dir, entry)) ? 'wired' : 'unwired'
+}
+
+/**
+ * One line when the nearest `.oxlintrc.json` up to the repo root does not wire the AST lane: the
+ * basalt/* rules — two of the 1.33.0 promotions among them — live only there, and a
+ * check-theme-only CI otherwise reads as the whole guard (emailgw r4). Doctor names the fix.
+ */
+function astLaneNotice(cwd: string): string | null {
+  const root = findRepoRoot(cwd)
+  for (let dir = cwd; ; dir = dirname(dir)) {
+    const lane = oxlintLaneAt(dir)
+    if (lane === 'wired') return null
+    if (lane === 'unwired' || dir === root || dirname(dir) === dir) break
+  }
+  const preset = readSource(packageRoot(), OXLINT_FILES.guards)
+  const count =
+    preset === null
+      ? `every (${OXLINT_FILES.guards} unreadable, so uncounted)`
+      : String(preset.match(/"basalt\/[\w-]+":/g)?.length ?? 0)
+  return (
+    `ℹ basalt-ui check-theme: AST lane not enforced — ${count} basalt/* rule ids unguarded ` +
+    '(incl. the promoted control-outside-home, raw-breakpoint): no .oxlintrc.json up to the repo ' +
+    'root extends basalt-ui/configs/oxlint.json (or the guards-only oxlint-basalt.json). `basalt-ui ' +
+    'doctor` names the fix.'
+  )
+}
+
 /**
  * Theme guard — thin FS walker over the headless `../guard` core. Reads BasaltConfig, builds a
  * GuardConfig, walks roots, calls checkSource per file, collects Finding[], groups/reports, returns
@@ -41,19 +89,10 @@ export function checkTheme(
   invocationCwd: string = process.cwd(),
   flags: readonly string[] = [],
 ): number {
-  if (conflictingProfileFlags(flags)) {
-    console.error(
-      'basalt-ui check-theme: --tokens-only and --framework are alternatives — pass one.',
-    )
-    return 1
-  }
+  if (conflictingProfileFlags('check-theme', flags)) return 1
   const project = resolveProjectDir(invocationCwd)
   const cwd = project.dir
-  if (project.relocatedFrom !== null) {
-    console.log(
-      `basalt-ui check-theme: BASALT_CWD relocated from ${project.relocatedFrom} to ${cwd}.`,
-    )
-  }
+  noteRelocation('check-theme', project)
   const cfg = readBasaltConfig(cwd)
   const roots = resolveRoots(cfg)
   const profile = declaredProfile(cfg, flags)
@@ -65,27 +104,7 @@ export function checkTheme(
     )
   }
 
-  const guardCfg: GuardConfig = {
-    spacingSteps: cfg.spacingSteps ?? DEFAULT_GUARD_CONFIG.spacingSteps,
-    rawRadius: cfg.rawRadius ?? DEFAULT_GUARD_CONFIG.rawRadius,
-    forbiddenAccents: cfg.forbiddenAccents ?? DEFAULT_GUARD_CONFIG.forbiddenAccents,
-    mantineShadeIndex: cfg.mantineShadeIndex ?? DEFAULT_GUARD_CONFIG.mantineShadeIndex,
-    rawSurface: cfg.rawSurface ?? DEFAULT_GUARD_CONFIG.rawSurface,
-    cardWithBorder: cfg.cardWithBorder ?? DEFAULT_GUARD_CONFIG.cardWithBorder,
-    offSystemSurfaceVar: cfg.offSystemSurfaceVar ?? DEFAULT_GUARD_CONFIG.offSystemSurfaceVar,
-    rawHtmlLayout: cfg.rawHtmlLayout ?? DEFAULT_GUARD_CONFIG.rawHtmlLayout,
-    inlineSpacing: cfg.inlineSpacing ?? DEFAULT_GUARD_CONFIG.inlineSpacing,
-    inlineDisplay: cfg.inlineDisplay ?? DEFAULT_GUARD_CONFIG.inlineDisplay,
-    rawVisxAxis: cfg.rawVisxAxis ?? DEFAULT_GUARD_CONFIG.rawVisxAxis,
-    rawMotionValue: cfg.rawMotionValue ?? DEFAULT_GUARD_CONFIG.rawMotionValue,
-    chartMissingAriaLabel: cfg.chartMissingAriaLabel ?? DEFAULT_GUARD_CONFIG.chartMissingAriaLabel,
-    rawFormControl: cfg.rawFormControl ?? DEFAULT_GUARD_CONFIG.rawFormControl,
-    sub16InputFont: cfg.sub16InputFont ?? DEFAULT_GUARD_CONFIG.sub16InputFont,
-    allowComment: 'theme-allow',
-    exemptRules: resolveExemptRules(cfg),
-    severity: cfg.severity ?? DEFAULT_GUARD_CONFIG.severity,
-    ...(profile === 'tokens-only' ? { profile: 'tokens-only' as const } : {}),
-  }
+  const guardCfg = resolveGuardConfig(cfg, profile)
 
   const findings: Finding[] = []
   const scanned = scannableFiles(cwd, cfg)
@@ -143,6 +162,9 @@ export function checkTheme(
     )
   }
 
+  const notice = profile === 'tokens-only' ? null : astLaneNotice(cwd)
+  if (notice !== null) console.error(notice)
+
   if (findings.length === 0) {
     console.log('✓ Theme guard: no off-palette colors.')
     return 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,
@@ -16,15 +16,16 @@ import {
   findBasaltInstall,
   findRepoRoot,
   inspectLefthookGate,
+  OXLINT_FILES,
   parseJsonc,
   readBasaltConfig,
   readIfExists,
   readManifest,
   resolveProjectDir,
-  resolveRoots,
   scannableFiles,
   shippedAssetPath,
 } from './index'
+import { resolveRoots } from './config'
 import { findManifestAbove, parentInstallAdvice } from './sync'
 
 export type DoctorResult = {
@@ -140,10 +141,7 @@ function resolveAiMajorSkewReason(cfg: BasaltConfig): {
  * Returns the exit code: 0 = all good, 1 = one or more hard failures.
  */
 export function doctor(invocationCwd: string = process.cwd(), flags: string[] = []): number {
-  if (conflictingProfileFlags(flags)) {
-    console.error('basalt-ui doctor: --tokens-only and --framework are alternatives — pass one.')
-    return 1
-  }
+  if (conflictingProfileFlags('doctor', flags)) return 1
   const project = resolveProjectDir(invocationCwd)
   const cwd = project.dir
   const cfg = readBasaltConfig(cwd)
@@ -256,7 +254,7 @@ export function doctor(invocationCwd: string = process.cwd(), flags: string[] =
         )
       } else {
         const entry = basaltPresetEntry(parsed['extends'])
-        const correct = shippedAssetPath(install, cwd, 'configs/oxlint.json')
+        const correct = shippedAssetPath(install, cwd, OXLINT_FILES.preset)
         if (entry === null) {
           fail(
             '.oxlintrc.json does NOT extend the shipped preset — every basalt/* design rule is off ' +