basalt-ui 1.32.1 → 1.34.0

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/common/vx-families.ts

@@ -0,0 +1,36 @@
+// GENERATED by scripts/gen-vx-names.ts — do not edit. `vx-names.test.ts` fails on drift.
+
+/**
+ * The families every emitted `--vx-*` name lives in (`basaltVxFamilies`) — basalt-owned:
+ * `unknown-vx-token` judges every name inside one, and `groupTokens`/`seriesTokens` warn on a
+ * consumer ref there.
+ */
+export const BASALT_VX_FAMILIES: readonly string[] = [
+  'accent',
+  'area',
+  'axis',
+  'bad',
+  'crosshair',
+  'divider',
+  'dot',
+  'faint',
+  'fill',
+  'good',
+  'grid',
+  'hit',
+  'ink',
+  'keyboard',
+  'legend',
+  'line',
+  'muted',
+  'neutral',
+  'prose',
+  'radius',
+  'shadow',
+  'space',
+  'status',
+  'surface',
+  'text',
+  'tooltip',
+  'warn',
+]

package/src/common/vx-family.ts

@@ -0,0 +1,22 @@
+/**
+ * A `--vx-*` name's FAMILY — its leading lowercase run: `--vx-surface-bg` → `surface`, `--vx-ink2`
+ * → `ink`, `--vx-tooltipBg` → `tooltip`, `--vx-fillHover-cyan` → `fill`. Dependency-free, because
+ * three sides must agree on it byte for byte: the generator that writes `BASALT_VX_FAMILIES`, the
+ * guard that judges every name inside one of those families, and the token factories that refuse a
+ * consumer name inside one — the refusal is what makes the guard's judgement honest.
+ */
+export function vxFamilyOf(name: string): string {
+  return /^--vx-([a-z]*)/.exec(name)?.[1] ?? ''
+}
+
+/**
+ * Families a consumer extends without any factory: the theme emits `--vx-on-<color>` for EVERY
+ * `theme.colors` entry, a consumer's own colors included, so `on` is never basalt's alone.
+ */
+const CONSUMER_EXTENSIBLE_FAMILIES: ReadonlySet<string> = new Set(['on'])
+
+/** The basalt-owned families among `names` — run over every name basalt emits (`collectVxNames`). */
+export function basaltVxFamilies(names: readonly string[]): string[] {
+  const families = new Set(names.map(vxFamilyOf))
+  return [...families].filter((f) => f !== '' && !CONSUMER_EXTENSIBLE_FAMILIES.has(f)).toSorted()
+}

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>
   )
 

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)
@@ -1231,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/guard/index.ts

@@ -1,10 +1,13 @@
 /**
  * ./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 { vxFamilyOf } from '../common/vx-family'
+import { BASALT_VX_FAMILIES } from '../common/vx-families'
+import { BASALT_VX_NAMES } from './vx-names'
 
 export type { Finding, GuardConfig, GuardKind, GuardSeverity }
 
@@ -286,6 +289,57 @@ 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 families basalt owns (`vxFamilyOf`: `surface`, `space`, `ink`, `keyboard`, …), which the
+ * generator reads off every name basalt emits. Every name inside one is judged against the exact
+ * emitted set, so `--vx-surface-2` and a bare root like `--vx-space` are both findings.
+ *
+ * That judgement is honest only because no consumer ref may point into these families:
+ * `groupTokens`/`seriesTokens` warn on a name inside one (and throw once this kind promotes). A name in any OTHER family (argo's
+ * `--vx-activity-*`, rb's `--vx-confidence-*`) may be a consumer group declared in a file this scan
+ * cannot see, and is never judged.
+ */
+const BASALT_VX_FAMILY_SET: ReadonlySet<string> = new Set(BASALT_VX_FAMILIES)
+
 // 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
 
@@ -861,38 +915,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',
+  'unknown-vx-token': {
+    since: '1.34.0',
+    promote: '1.35.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',
-    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 at 1.33.0 (consumer-loop r2 B3): obsidian lost its 44px touch floor to a removed ' +
+      '`var(--vx-space-touch-target)` that nothing reported. WIDENED at 1.34.0 (image-gen r4: ' +
+      '`var(--vx-surface-2)` rendered transparent, unreported) to every unemitted name inside a ' +
+      'basalt-owned family, so the grace restarts: warn through 1.34.x, error at 1.35.0.',
   },
 }
 
@@ -1132,6 +1162,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
 
@@ -1973,7 +2010,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
@@ -2065,7 +2102,7 @@ export const GUARD_RULES = {
     // JSX-tag-shaped (`<Card withBorder>`) — never appears in CSS text.
     appliesTo: (relPath) => !relPath.endsWith('.css'),
     message:
-      'withBorder on a Card/Paper double-draws the edge — card depth is --vx-shadow-card, which already bakes a 1px ring into the shadow. Drop the prop (docs/DESIGN-SPEC.md doctrine inversion #1).',
+      'withBorder on a Card/Paper double-draws the edge — card depth is --vx-shadow-card, which already bakes a 1px ring into the shadow. Drop the prop (docs/DESIGN-SPEC.md doctrine inversion #1) — and fix the inset in the same edit: an explicit p/padding or radius on that Card/Paper is the other half of the idiom, which only the oxlint lane sees (basalt/card-inset); leave both to the theme or use py="xs" px="sm".',
   },
   'off-system-surface-var': {
     kind: 'off-system-surface-var',
@@ -2215,6 +2252,17 @@ export const GUARD_RULES = {
     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(' / ')}, 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 (basalt-owned families); 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. Judged: every name inside a basalt-owned family (${[...BASALT_VX_FAMILY_SET].join(', ')}) — pick the token from basalt-ui/tokens.css; your own series belong in a family of their own (groupTokens warns on one inside basalt's). Removed names and their replacements: ${Object.entries(
+      REMOVED_VX_NAMES,
+    )
+      .map(([from, to]) => `${from} → ${to ?? '(deleted, no replacement)'}`)
+      .join(
+        '; ',
+      )}. A name in any other family is never judged, because groupTokens may declare it in a file this scan cannot see.`,
+  },
 } as const satisfies Record<GuardKind, GuardRule>
 
 /**
@@ -2389,6 +2437,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: any unemitted name inside a basalt-owned family — see BASALT_VX_FAMILY_SET.
+  // 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 (KNOWN_VX_NAMES.has(name) || !BASALT_VX_FAMILY_SET.has(vxFamilyOf(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] ?? ''
 
@@ -2793,6 +2857,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. */
@@ -2831,19 +2904,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`. */