basalt-ui 1.32.0 → 1.33.0

package/src/controls/number-filter.tsx

@@ -51,6 +51,12 @@
  * // An open threshold — a pill holding a stepper, applied on blur or Enter.
  * // minDuration: field.number({ fallback: 0, min: 0, max: 600 })
  * <NumberFilter field={lines.field.minDuration} label="Min duration" step={30} />
+ *
+ * @example
+ * // "No filter" is the fallback, not a row: `clearable` writes it back, and the pill reads the
+ * // filter's name while no preset is picked.
+ * // difficulty: field.number({ fallback: 0, min: 0, max: 5, int: true })
+ * <NumberFilter field={library.field.difficulty} label="Difficulty" options={LEVELS} clearable />
  */
 import { NumberInput } from '@mantine/core'
 import { useEffect, useRef, useState } from 'react'
@@ -62,7 +68,7 @@ import classes from './controls.module.css'
 import { EnumFilter } from './enum-filter'
 import type { ChoiceHandle } from './enum-filter'
 import { useFilterRegistration, useFilterSurface } from './filter-context'
-import { FilterPill } from './filter-pill'
+import { FilterClearButton, FilterPill } from './filter-pill'
 import { useControlName } from './filter-sheet'
 import { PanelRow } from './panel-row'
 
@@ -89,6 +95,9 @@ export type NumberFilterProps = BasaltProps & {
    * declared none. Absent on both, the input keeps Mantine's own default of 1.
    */
   readonly step?: number
+  /** Adds a `Clear` action that clears the field — the same `field.clear()` `Reset all` calls.
+   *  Parity with `SelectFilter`/`EnumFilter`, in both forms. */
+  readonly clearable?: boolean
 }
 
 export function NumberFilter(props: NumberFilterProps): ReactNode {
@@ -97,7 +106,7 @@ export function NumberFilter(props: NumberFilterProps): ReactNode {
   assertRequiredProps('NumberFilter', props, ['field'], {
     field: 'bind it to a store field (`store.field.<name>`), never a value/onChange pair.',
   })
-  const { field, label, icon, options, step, className, style } = props
+  const { field, label, icon, options, step, clearable, className, style } = props
   // Two BRANCHES, two components, and never a conditional hook: the radio form's state lives in
   // `EnumFilter` and the stepper's in `NumberStepper`, so which one mounts is decided once by a prop
   // that does not change across a mount's life.
@@ -107,6 +116,7 @@ export function NumberFilter(props: NumberFilterProps): ReactNode {
         field={field}
         label={label}
         options={options}
+        {...(clearable === true && { clearable: true })}
         {...(icon !== undefined && { icon })}
         {...(className !== undefined && { className })}
         {...(style !== undefined && { style })}
@@ -120,6 +130,7 @@ export function NumberFilter(props: NumberFilterProps): ReactNode {
     <NumberStepper
       field={field}
       label={label}
+      {...(clearable === true && { clearable: true })}
       {...(icon !== undefined && { icon })}
       {...(grain !== undefined && { step: grain })}
       {...(className !== undefined && { className })}
@@ -147,6 +158,7 @@ function NumberChoice({
   label,
   icon,
   options,
+  clearable,
   className,
   style,
 }: BasaltProps & {
@@ -154,6 +166,7 @@ function NumberChoice({
   readonly label: string
   readonly icon?: ReactNode
   readonly options: readonly NumberFilterOption[]
+  readonly clearable?: boolean
 }): ReactNode {
   const [value, setValue] = field.use()
   const rows = options.map((option) => ({ value: String(option.value), label: option.label }))
@@ -182,6 +195,7 @@ function NumberChoice({
       label={label}
       numeric
       options={rows}
+      {...(clearable === true && { clearable: true })}
       {...(icon !== undefined && { icon })}
       {...(className !== undefined && { className })}
       {...(style !== undefined && { style })}
@@ -195,6 +209,7 @@ function NumberStepper({
   label,
   icon,
   step,
+  clearable,
   className,
   style,
 }: BasaltProps & {
@@ -202,6 +217,7 @@ function NumberStepper({
   readonly label: string
   readonly icon?: ReactNode
   readonly step?: number
+  readonly clearable?: boolean
 }): ReactNode {
   const [value, setValue] = field.use()
   const surface = useFilterSurface()
@@ -265,7 +281,12 @@ function NumberStepper({
       {...(className !== undefined && { className })}
       {...(style !== undefined && { style })}
     >
-      <div className={classes.optionList}>{input}</div>
+      <div className={classes.optionList}>
+        {input}
+        {/* Same placement as `EnumFilter`'s: popover only — the sheet and panel rows reset through
+            the `FilterSet` registration above. The draft follows the clear via its effect. */}
+        {clearable === true && !isDefault && <FilterClearButton onClear={() => field.clear()} />}
+      </div>
     </FilterPill>
   )
 }

package/src/controls/range-filter.tsx

@@ -32,7 +32,6 @@ import { useEffect, useRef, useState } from 'react'
 import type { ComponentType, ReactNode } from 'react'
 import type { BasaltProps } from '../common/props'
 import { assertRequiredProps } from '../common/validate'
-import { isDev } from '../common/is-dev'
 import type { FieldHandle, RangeField, RangeValue } from '../state'
 import classes from './controls.module.css'
 import { useFilterRegistration, useFilterSurface } from './filter-context'
@@ -60,7 +59,7 @@ const noPickerWarned = new Set<string>()
  * the type cannot tell "deliberately preset-only" from "forgot the import".
  */
 function warnCustomWithoutPicker(label: string, unreachable: boolean): void {
-  if (!unreachable || !isDev() || noPickerWarned.has(label)) return
+  if (!unreachable || process.env.NODE_ENV === 'production' || noPickerWarned.has(label)) return
   noPickerWarned.add(label)
   // oxlint-disable-next-line no-console -- a dev-time wiring warning has no other channel
   console.warn(

package/src/data/data-table.tsx

@@ -98,7 +98,6 @@ import {
   useRowDisclosure,
 } from './data-table-state'
 import { dataQueryBranch } from './query-branch'
-import { isDev } from '../common/is-dev'
 import classes from './data-table.module.css'
 
 // ── Column alignment ──────────────────────────────────────────────────────────
@@ -303,7 +302,7 @@ function resolveFacetColumn<T>(
 ): Column<T, unknown> | undefined {
   const column = table.getColumn(facet.columnId)
   if (column) return column
-  if (isDev()) {
+  if (process.env.NODE_ENV !== 'production') {
     const knownIds = table
       .getAllColumns()
       .map((known) => known.id)
@@ -608,7 +607,8 @@ export type BasaltDataTableProps<T> = BasaltProps &
      * list can never disagree with its table; a fixed card order is `initialSorting`, not a second
      * sort. Everything around the body stays: the header (title · count · toolbar), the bulk bar,
      * the pager, and `query` / `isLoading` / `emptyState`. `onRowActivate` makes each card
-     * activatable exactly as it does a row (click, or Enter on the focused card). The selection
+     * activatable exactly as it does a row (click, or Enter on the focused card — never Space, the
+     * browser's own page scroll on a focused non-button). The selection
      * checkbox is not projected — a card list with a selection keeps its bulk bar but no ticks.
      *
      * An activatable card takes `tabIndex=0` + `data-activatable`, never `role="button"`: a card is
@@ -616,7 +616,9 @@ export type BasaltDataTableProps<T> = BasaltProps &
      * descendant presentational, so those nested controls would vanish from the accessibility tree.
      * The affordance is the cursor and the focus ring, as on the row. `maxHeight` caps the card list
      * in a `ScrollArea`; `minWidth` does not apply — it is a horizontal floor for columns, and a
-     * card list has none.
+     * card list has none. `stickyHeader` has nothing to stick while the cards render. A card order
+     * with no user sort is `data`'s own order — sort it there (or `initialSorting`) for a domain
+     * order.
      *
      * Reach for it when the row carries more than the columns a phone can hold (a status + label +
      * age header, a clamped title, a prose line). A table that only needs to shed a column or two
@@ -761,6 +763,10 @@ export type BasaltDataTableProps<T> = BasaltProps &
      * its own card instead of widening the page. Reach for this only to hold a MINIMUM table width
      * — e.g. so eight columns keep their readable widths and scroll rather than compress.
      *
+     * Setting it also switches the column fold OFF (a declared floor is the caller saying "this
+     * table is at least this wide", which folding columns out would contradict), so a `minWidth`
+     * table scrolls where the same table without it folds. `maxHeight` alone keeps the fold.
+     *
      * The one table whose wrapper is MEASURED rather than declared is `stickyHeader` with neither
      * this nor `maxHeight`; see that prop and `useMeasuredContainment` in the implementation for
      * why, and pair it with `maxHeight` if the table must both scroll and stick.
@@ -1224,7 +1230,7 @@ const reportedBreaches = new Set<string>()
 function enforceManualPaginationContract(breaches: ManualPaginationBreach[]): void {
   if (breaches.length === 0) return
   const message = manualPaginationMessage(breaches)
-  if (isDev()) throw new Error(message)
+  if (process.env.NODE_ENV !== 'production') throw new Error(message)
   if (reportedBreaches.has(message)) return
   reportedBreaches.add(message)
   console.error(message)

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

@@ -138,9 +138,12 @@
   gap: var(--vx-space-stack-xs);
 }
 
+/* Bottom-aligned, not stretched: a trailing button beside a labelled FormRow keeps its own height
+   and lines up with the input, not with the label above it. */
 .groupControls[data-direction='row'] {
   flex-direction: row;
   flex-wrap: wrap;
+  align-items: flex-end;
   gap: var(--vx-space-control-gap);
 }
 

package/src/forms/form-layout.tsx

@@ -213,7 +213,12 @@ export type FormGroupProps = BasaltProps & {
   error?: ReactNode
   /** Marks the group required — same two-channel treatment as `FormRow`. */
   required?: boolean
-  /** `column` stacks the options; `row` lays them out inline and wraps. @default 'column' */
+  /**
+   * `column` stacks the options; `row` lays them out inline, wraps, and bottom-aligns them, so a
+   * trailing button sits level with the inputs instead of stretching to the tallest child. Give a
+   * `FormRow` inside a `row` group (or any flex row) a definite width — it is an inline-size
+   * container, so its intrinsic width is zero and it collapses otherwise. @default 'column'
+   */
   direction?: 'row' | 'column'
   /** The cluster — checkboxes, radios, chips. */
   children: ReactNode

package/src/guard/index.ts

@@ -1,10 +1,11 @@
 /**
  * ./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 28 violation kinds.
  * checkSource:  pure (text, relPath, cfg) → Finding[]. No FS, no walk, no console.
  */
 import type { Finding, GuardConfig, GuardKind, GuardSeverity } from './types'
+import { BASALT_VX_NAMES } from './vx-names'
 
 export type { Finding, GuardConfig, GuardKind, GuardSeverity }
 
@@ -177,27 +178,23 @@ const CSS_NON_COARSE_POINTER_QUERY =
  * The `@container` names the container-class axis declares — a consumer container carrying any
  * other name has invented its own container-query breakpoint instead of using the framework's.
  * `basalt-card` is the one shipped today (`src/dashboard/section.module.css`);
- * `basalt-form`/`basalt-main`/`basalt-grid` are the declared remaining three, reserved here so a
- * consumer adopting one ahead of the framework does not immediately trip this guard.
+ * `basalt-form`/`basalt-grid` are the declared remaining two, reserved here so a consumer adopting
+ * one ahead of the framework does not immediately trip this guard. `basalt-main` was a third until
+ * 1.32.1 dropped it: nothing ever declared it, so the guard accepted a query that never matched.
  *
  * `basalt-grid` is also what `StatGroup`/`WidgetGrid` declare (`src/dashboard/*.module.css`) —
  * they shipped as `basalt-stat-group`/`basalt-widget-grid` until 1.32.0 moved them onto this table.
  */
-const DECLARED_CONTAINER_NAMES = new Set([
-  'basalt-card',
-  'basalt-form',
-  'basalt-main',
-  'basalt-grid',
-])
+const DECLARED_CONTAINER_NAMES = new Set(['basalt-card', 'basalt-form', 'basalt-grid'])
 
 /**
  * `CONTAINER_CLASSES` (`src/tokens/size-classes.ts`) boundaries, duplicated per the `CTL_THEME_TAGS`
  * convention in the oxlint plugin — this module is dependency-free by contract (file header) and
  * must not import `../tokens`. Pinned against the real table by `check-source.test.ts`. Judged only
- * against `basalt-card`: the other three declared names have no shipped numeric table yet. `0` is
- * the container's own floor, not a class boundary, but `(width >= 0px)` is a legitimate idiom for
- * "scope this rule to the container, whatever its width" (`widget-header.module.css`'s `cqi` clamp)
- * — allowed for that reason, not because it names a real `CONTAINER_CLASSES` step.
+ * against `basalt-card` and unnamed queries: the other declared names have no shipped numeric table
+ * yet. `0` is the container's own floor, not a class boundary, but `(width >= 0px)` is a legitimate
+ * idiom for "scope this rule to the container, whatever its width" (`widget-header.module.css`'s
+ * `cqi` clamp) — allowed for that reason, not because it names a real `CONTAINER_CLASSES` step.
  */
 const CONTAINER_CLASS_LITERALS_PX = new Set([0, 240, 239.9, 480, 479.9, 800, 799.9])
 
@@ -290,6 +287,62 @@ const INLINE_FONT_SIZE =
 const CARD_SURFACE_TAG = /<(?:Card|Paper)(?![\w.])(?:=>|[^>])*?>/g
 const WITH_BORDER_PROP = /\bwithBorder\b(?!\s*=\s*\{\s*false\s*\})/
 
+/**
+ * A `var(--vx-*)` REFERENCE with a literal name. The name must end on an alphanumeric and must not
+ * run into a `${…}` interpolation, so `var(--vx-fill-${hue})` — a name computed at runtime — never
+ * matches a truncated `--vx-fill`.
+ */
+const VX_VAR_REF = /var\(\s*(--vx-[A-Za-z0-9-]*[A-Za-z0-9])(?![A-Za-z0-9-]|\$\{)/g
+
+/**
+ * A `--vx-*` name the file DECLARES — a consumer's own custom property, never unknown. Only a real
+ * declaration position counts, because the set is file-wide and one false hit silences every
+ * finding for that name in the file:
+ *
+ * - a CSS declaration (`--vx-x: …`, in a stylesheet or in CSS text inside a template literal),
+ *   directly after a line start, `{` or `;`;
+ * - a quoted style-object key (`{ '--vx-x': … }`), directly after `{` or `,` — but not a TS
+ *   member key (`'--vx-x'?: …`, or one typed `string`/`number`);
+ * - `setProperty('--vx-x', …)`.
+ *
+ * A quoted name used as an EXPRESSION — a ternary arm, a `case` label, an argument — is a reference,
+ * not a declaration, and never matches.
+ */
+const VX_LOCAL_DECLARATION =
+  /(?:^|[{;])\s*(--vx-[A-Za-z0-9-]*[A-Za-z0-9])\s*:|[{,]\s*(['"])(--vx-[A-Za-z0-9-]*[A-Za-z0-9])\2\s*:(?!\s*(?:string|number)\b)|\bsetProperty\(\s*['"](--vx-[A-Za-z0-9-]*[A-Za-z0-9])['"]/gm
+
+/**
+ * `--vx-*` names basalt once emitted and no longer does, with the replacement MIGRATING names
+ * (`null`: deleted with no replacement). Hand-kept on purpose: it is history, it only grows, and
+ * `vx-names.test.ts` pins that none of these is live and every replacement is.
+ */
+const REMOVED_VX_NAMES: Readonly<Record<string, string | null>> = {
+  '--vx-space-touch-target': '--vx-hit',
+  '--vx-space-touch-control-height': '--vx-hit',
+  '--vx-space-app-header-mobile-actions-height': '--vx-space-sticky-header-clearance',
+  '--vx-space-sticky-header-clearance-mobile': '--vx-space-sticky-header-clearance',
+  '--vx-space-sidebar-brand-inset-top': null,
+}
+
+const KNOWN_VX_NAMES: ReadonlySet<string> = new Set(BASALT_VX_NAMES)
+
+/**
+ * The bare family roots basalt never emits — `--vx-space`, `--vx-surface`, `--vx-status`, … — derived
+ * from the `--vx-<family>-` prefixes of the emitted names, minus any root that is itself a token
+ * (`--vx-hit`, `--vx-accent`). Nobody emits one: basalt only ever writes `<root>-<key>`, and so does
+ * `groupTokens`. It is the one shape of unknown name basalt can judge WITHOUT seeing the consumer's
+ * palette.
+ *
+ * An unknown name INSIDE a family (`--vx-surface-2`) is deliberately not judged. `groupTokens(name,
+ * map)` takes any `name`, so `--vx-surface-custom` may be a consumer group declared in a file this
+ * scan cannot see, and a per-file guard has no honest way to tell that from a typo.
+ */
+const BASALT_VX_FAMILY_ROOTS: ReadonlySet<string> = new Set(
+  BASALT_VX_NAMES.map((n) => /^(--vx-[A-Za-z0-9]+)-/.exec(n)?.[1]).filter(
+    (root): root is string => root !== undefined && !KNOWN_VX_NAMES.has(root),
+  ),
+)
+
 // Raw Mantine ramp step used for surface color — gray/dark + a step digit.
 const OFF_SYSTEM_SURFACE_VAR = /var\(--mantine-color-(gray|dark)-\d/g
 
@@ -691,9 +744,12 @@ const PROSE_CONTEXT_TAG = /<(?:Prose|ArticleLayout|Modal|Drawer)(?![\w])/
  * read differently in the two lanes. The plugin gates them on the tag's basalt IMPORT; a 12-line
  * regex window has no import graph, so this lane matches by name and accepts the missed warn on a
  * consumer's own `PanelRow` — the same direction every approximation in this scan already leans.
+ *
+ * The name set is the plugin's `CONTROL_HOST_TAGS` ∪ `BASALT_HOST_TAGS`; `oxlint-plugin.test.ts` ›
+ * lane parity asserts the two agree (1.32.1 — `FormRow`/`FormGroup` had drifted out of this lane).
  */
 const CONTROL_HOST_TAG =
-  /<(?:SettingsRow|Modal|Drawer|Popover\.Dropdown|Menu\.Dropdown|Composer|FilterSet|PageAside|PanelRow)(?![\w])/
+  /<(?:SettingsRow|FormRow|FormGroup|Modal|Drawer|Popover\.Dropdown|Menu\.Dropdown|Composer|FilterSet|PageAside|PanelRow)(?![\w])/
 
 /**
  * How far ABOVE a control the host-tag window reaches, in lines.
@@ -862,38 +918,14 @@ export type GraceEntry = { since: string; promote: string; why: string }
  * }
  */
 export const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, GraceEntry>> = {
-  'raw-selection-control': {
-    since: '1.26.0',
-    promote: '1.33.0',
-    why:
-      "Extended 1.32.0 -> 1.33.0 at the 1.32.0 release, the last extension: basalt's own tree is at 0 (consumer-loop r1 dogfood) and argo is at 2, but RE-MEASURED 2026-09-30 the fleet carries ~33 (image-gen 11, rb 7, image-share 6, weatherorb 5, email-gateway 4, argo 2). The 1.32.0 fleet upgrade clears them while they warn, together with raw-breakpoint, so 1.33.0 promotes all four ids against a measured-clean fleet. " +
-      'Extended 1.31.0 -> 1.32.0 at the 1.31.0 release: the basalt tree still carries incumbents (data-table, notifications center, theme-lab) and the argo sweep has not run. ' +
-      'new in the wave-6 control guards (docs/CONTROLS-SPEC.md §6, law C1). The text lane cannot ' +
-      'see ancestry, so "no home" is approximated by a 12-line host-tag window — the loosest ' +
-      'reading in the guard, and the reason this one lands warn rather than error even though its ' +
-      'law is settled. ONE LAW, TWO LANES, ONE PROMOTION: it moves with its AST twin, ' +
-      '`basalt/control-outside-home`, whose PLUGIN_RULE_GRACE entry carries the full argument and ' +
-      'the measurement, and it must never be promoted or extended alone — a consumer waiving one ' +
-      'spelling and failing the other is the exact confusion `WAIVER_ID_ALIASES` exists to close. ' +
-      'RE-MEASURED 2026-09-09 across the whole fleet on 1.29.2: 29 AST-lane incumbents in five ' +
-      "repos, plus three of basalt's own (data-table, notifications/center, theme-lab). Extended " +
-      'to 1.31.0 because 1.30.0 is the FIRST release in which either lane names a home a ' +
-      'provider-only consumer can reach — every home both messages listed was a shell slot, and ' +
-      'the shell-less `PageBar` sentence ships in this minor. Promoting in the same minor that ' +
-      'makes a rule satisfiable gives nobody a window to act. 1.31.0 is when the 29 are ' +
-      're-measured against that number.',
-  },
-  'raw-media-query': {
-    since: '1.31.0',
-    promote: '1.33.0',
+  'unknown-vx-token': {
+    since: '1.33.0',
+    promote: '1.34.0',
     why:
-      "The CSS-text twin of the oxlint plugin's `basalt/raw-breakpoint` — ONE LAW, TWO LANES, ONE " +
-      'PROMOTION, so it moves with that rule and never alone (`configs/oxlint-plugin.test.ts` › twin lanes share one promotion pins the pair). New in ' +
-      'the wave-11 responsive/touch guards; reaching CSS is a NEW file type for this check, same ' +
-      "reasoning as `css-raw-surface`, with incumbents in basalt's own tree at ship time, so it " +
-      'shipped warn. Extended 1.32.0 -> 1.33.0 with its twin: 1.31.0 named ' +
-      'no reachable container primitive, and 1.32.0 is the first minor that documents one ' +
-      '(`CONTAINER_CLASSES` + the declared `@container` names, MIGRATING § `basalt/raw-breakpoint`).',
+      'New kind (consumer-loop r2 B3): obsidian lost its 44px touch floor to a removed ' +
+      '`var(--vx-space-touch-target)` that nothing reported. A new kind rejects code every previous ' +
+      'release accepted, so it lands warn for one minor. Measured at ship time: argo, linewatch, rb, ' +
+      'rollhook, obsidian, weatherorb, image-share, email-gateway, image-gen 0.',
   },
 }
 
@@ -1133,6 +1165,13 @@ export const WAIVER_ID_ALIASES: Readonly<Record<string, readonly string[]>> = {
   'raw-selection-control': ['control-outside-home'],
 }
 
+/**
+ * The ids that are a guard kind AND an oxlint plugin rule — one law, two lanes, one annotation.
+ * {@link PLUGIN_RULE_IDS} leaves them out by design, so `--audit-allows` would otherwise never ask
+ * oxlint about them. `waiver-audit.test.ts` pins this against the plugin's own rule table.
+ */
+const DUAL_LANE_IDS: ReadonlySet<string> = new Set(['in-body-page-title'])
+
 /** The shortest string accepted as a written reason — enough to exclude a stray separator. */
 const MIN_ALLOW_REASON_LENGTH = 4
 
@@ -1974,7 +2013,7 @@ type GuardRule = {
 }
 
 /**
- * The closed registry of all 27 guard kinds. The triad test asserts
+ * The closed registry of all 28 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
@@ -2200,7 +2239,7 @@ export const GUARD_RULES = {
     // JSX-tag-shaped (`<Select …>`) — never appears in CSS text.
     appliesTo: (relPath) => !relPath.endsWith('.css'),
     message:
-      'Raw selection control with no home — a filter or tab belongs in a PageBar / Section / WidgetHeader slot and takes a `field` (a FieldHandle), so it owns the URL write and the localStorage mirror instead of carrying value/onChange (docs/CONTROLS-SPEC.md laws C1–C3). Use the bound control from basalt-ui/controls. A settings row, an overlay and an @mantine/form file are the declared non-homes and never report. No shell? PageBar needs no BasaltShell: outside one it renders in flow, sticky, with its own title — so its slots are a reachable home for a provider-only app. This is the TEXT lane of basalt/control-outside-home, which answers the same question against the real AST — where the two disagree, the plugin is right.',
+      'Raw selection control with no home — a filter or tab belongs in a PageBar / Section / WidgetHeader slot and takes a `field` (a FieldHandle), so it owns the URL write and the localStorage mirror instead of carrying value/onChange (docs/CONTROLS-SPEC.md laws C1–C3). Use the bound control from basalt-ui/controls. A settings row, a FormRow / FormGroup, an overlay and an @mantine/form file are the declared non-homes and never report. No shell? PageBar needs no BasaltShell: outside one it renders in flow, sticky, with its own title — so its slots are a reachable home for a provider-only app. This is the TEXT lane of basalt/control-outside-home, which answers the same question against the real AST — where the two disagree, the plugin is right.',
   },
   'inline-font-size': {
     kind: 'inline-font-size',
@@ -2214,7 +2253,18 @@ export const GUARD_RULES = {
     // CSS-only: a width @media, an @container name/literal or a non-coarse pointer query has no JSX
     // spelling — the AST-side twin of this law is the oxlint plugin's basalt/raw-breakpoint.
     appliesTo: (relPath) => relPath.endsWith('.css'),
-    message: `Raw viewport/container breakpoint in CSS — a width @media belongs to shell/** against SIZE_CLASSES (useSizeClass() is the JS seam); an @container name must be one of ${[...DECLARED_CONTAINER_NAMES].join(' / ')} at a boundary in ${[...CONTAINER_CLASS_LITERALS_PX].map((px) => `${px}px`).join(' / ')}; and a pointer query other than (pointer: coarse) or (pointer: fine) has no framework meaning. Same law the oxlint plugin enforces as basalt/raw-breakpoint over JSX; this is the CSS half.`,
+    message: `Raw viewport/container breakpoint in CSS — a width @media belongs to shell/** against SIZE_CLASSES (useSizeClass() is the JS seam); an @container name must be one of ${[...DECLARED_CONTAINER_NAMES].join(' / ')}, and a basalt-card or unnamed @container query must sit at a boundary in ${[...CONTAINER_CLASS_LITERALS_PX].map((px) => `${px}px`).join(' / ')} (the other declared names have no numeric table yet, so their literals are not judged); and a pointer query other than (pointer: coarse) or (pointer: fine) has no framework meaning. Same law the oxlint plugin enforces as basalt/raw-breakpoint over JSX; this is the CSS half.`,
+  },
+  'unknown-vx-token': {
+    kind: 'unknown-vx-token',
+    pattern: VX_VAR_REF, // handled inline (removed map + family roots); entry keeps the registry complete
+    message: `var() names a --vx-* token basalt does not emit, so it resolves to its fallback (or to nothing) with no error anywhere. Two shapes are judged, the only two basalt can judge without seeing your palette: a REMOVED name — ${Object.entries(
+      REMOVED_VX_NAMES,
+    )
+      .map(([from, to]) => `${from} → ${to ?? '(deleted, no replacement)'}`)
+      .join(
+        '; ',
+      )} — and a bare family root nothing emits (${[...BASALT_VX_FAMILY_ROOTS].join(', ')}): name the token under it from basalt-ui/tokens.css. Any other unknown name is never judged, because defineSeries/groupTokens may declare it in a file this scan cannot see.`,
   },
 } as const satisfies Record<GuardKind, GuardRule>
 
@@ -2390,6 +2440,22 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
     [...codeText.matchAll(STYLE_BOUND_IDENTIFIER)].map((m) => m[1] ?? ''),
   )
 
+  /** `--vx-*` names this file declares — its own custom properties, which `unknown-vx-token` skips. */
+  const locallyDeclaredVx = new Set(
+    [...codeText.matchAll(VX_LOCAL_DECLARATION)].map((m) => m[1] ?? m[3] ?? m[4] ?? ''),
+  )
+
+  // unknown-vx-token: a removed name, or a bare family root nothing emits — see the roots' doc.
+  // Scanned over the whole comment-stripped text rather than per line, so a formatter-wrapped
+  // `var(\n  --vx-x\n)` is seen; the finding lands on the line the NAME is on.
+  for (const m of codeText.matchAll(VX_VAR_REF)) {
+    const name = m[1] ?? ''
+    if (locallyDeclaredVx.has(name)) continue
+    if (!Object.hasOwn(REMOVED_VX_NAMES, name) && !BASALT_VX_FAMILY_ROOTS.has(name)) continue
+    const at = (m.index ?? 0) + m[0].length - name.length
+    push('unknown-vx-token', lineStarts.findLastIndex((start) => start <= at) + 1, name)
+  }
+
   for (let i = 0; i < lines.length; i++) {
     const line = codeLines[i] ?? ''
 
@@ -2481,7 +2547,7 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
         }
         // Literal boundaries are judged against `basalt-card`'s own table (see
         // `CONTAINER_CLASS_LITERALS_PX`'s doc) — an unnamed query has no OTHER table to judge
-        // against, so it is judged against this one too; the other three declared names stay
+        // against, so it is judged against this one too; the other declared names stay
         // unjudged until they ship their own.
         if (name !== '' && name !== 'basalt-card') continue
         for (const lit of body.matchAll(CSS_CONTAINER_LITERAL)) {
@@ -2794,6 +2860,15 @@ export type AllowAnnotationSite = {
   readonly guardKinds: readonly GuardKind[]
   /** The subset of `rules` the oxlint plugin owns — outside `checkSource`'s reach. */
   readonly pluginRules: readonly string[]
+  /**
+   * Every id an `oxlint` run can prove live: `pluginRules`, plus a guard kind that is ALSO a plugin
+   * rule (`in-body-page-title`) or aliases one ({@link WAIVER_ID_ALIASES}). A waiver is live if
+   * EITHER lane still needs it — judging only `pluginRules` called rb's live `in-body-page-title`
+   * waivers dead, and deleting them made oxlint exit 1. A bare LINE-scope annotation covers every
+   * plugin rule (the plugin's `allowCovers`), so it lists all of them; a bare file-scope one waives
+   * nothing in either lane and lists none.
+   */
+  readonly oxlintRules: readonly string[]
   /** Words that occupied the id slot but name no rule. Their presence makes the parse fail closed. */
   readonly unknownRules: readonly string[]
   /** A written reason follows the ids. */
@@ -2832,19 +2907,33 @@ export function findAllowAnnotations(
     cfg.allowComment,
     syntax,
   )
-  return declared.map(({ line, annotation }) => ({
-    line,
-    scope: annotation.scope,
-    rules: [...annotation.rules],
-    guardKinds: annotation.rules.filter((id): id is GuardKind => Object.hasOwn(GUARD_RULES, id)),
-    pluginRules: annotation.rules.filter(
-      (id) => !Object.hasOwn(GUARD_RULES, id) && PLUGIN_RULE_IDS.has(id),
-    ),
-    unknownRules: [...annotation.unknownRules],
-    hasReason: annotation.hasReason,
-    bare: annotation.rules.length === 0 && annotation.unknownRules.length === 0,
-    text: lines[line - 1] ?? '',
-  }))
+  const everyOxlintRule = [...PLUGIN_RULE_IDS, ...DUAL_LANE_IDS]
+  return declared.map(({ line, annotation }) => {
+    const bare = annotation.rules.length === 0 && annotation.unknownRules.length === 0
+    return {
+      line,
+      scope: annotation.scope,
+      rules: [...annotation.rules],
+      guardKinds: annotation.rules.filter((id): id is GuardKind => Object.hasOwn(GUARD_RULES, id)),
+      pluginRules: annotation.rules.filter(
+        (id) => !Object.hasOwn(GUARD_RULES, id) && PLUGIN_RULE_IDS.has(id),
+      ),
+      oxlintRules:
+        bare && annotation.scope === 'line'
+          ? everyOxlintRule
+          : [
+              ...new Set(
+                annotation.rules
+                  .flatMap((id) => [id, ...(WAIVER_ID_ALIASES[id] ?? [])])
+                  .filter((id) => PLUGIN_RULE_IDS.has(id) || DUAL_LANE_IDS.has(id)),
+              ),
+            ],
+      unknownRules: [...annotation.unknownRules],
+      hasReason: annotation.hasReason,
+      bare,
+      text: lines[line - 1] ?? '',
+    }
+  })
 }
 
 /** The token a neutralized annotation is rewritten to. Shares no substring with `theme-allow`. */

package/src/guard/types.ts

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