basalt-ui 1.24.0 → 1.26.0

package/src/data/table.ts

@@ -48,4 +48,6 @@ export {
   type ColumnHelper,
   type PaginationState,
   type ColumnPinningState,
+  // The type `onColumnFiltersChange` hands back — needed at the call site for server-side faceting.
+  type ColumnFiltersState,
 } from '@tanstack/react-table'

package/src/guard/check-source.test.ts

@@ -1,7 +1,7 @@
 /**
  * Unit tests for checkSource — the pure (text, relPath, cfg) → Finding[] core.
  *
- * Covers all 25 guard kinds. Co-located with the guard, excluded from tsc
+ * Covers all 27 guard kinds. Co-located with the guard, excluded from tsc
  * (tsconfig exclude: src/**\/*.test.ts), run via `bun test`.
  *
  * The walker/reporter half is covered by the integration test in
@@ -1916,15 +1916,16 @@ describe('severity', () => {
     expect(f.find((v) => v.kind === 'raw-spacing')?.severity).toBe('error')
   })
 
-  // The grace ledger. Five kinds landed warn-only in the round-4 guard minor; deleting an entry
-  // from GRACE_PERIOD_KINDS is the promotion, and it shows up here as an explicit diff.
+  // The grace ledger. These five kinds landed warn-only in the round-4 guard minor and sat there
+  // for five minors with nothing tracking the promise (D4) — GRACE_PERIOD_KINDS is now empty and
+  // the C16 version gate in grace.test.ts is what stops a future entry sitting unpromoted again.
   it.each([
     'theme-allow-unscoped',
     'surface-shadow-override',
     'css-raw-surface',
     'inline-font-size',
     'hidden-inline-style',
-  ])('%s is still in its grace minor (warn)', (kind) => {
+  ])('%s is promoted past its grace minor (error)', (kind) => {
     const cases: Record<string, [string, string]> = {
       'theme-allow-unscoped': ['const x = 1 // theme-allow', PATH],
       'surface-shadow-override': ['const s = { boxShadow: `0 0 0 2px ${VX.accent}` }', PATH],
@@ -1937,7 +1938,7 @@ describe('severity', () => {
     }
     const [src, path] = cases[kind] as [string, string]
     const hit = find(src, path).find((v) => v.kind === kind)
-    expect(hit?.severity).toBe('warn')
+    expect(hit?.severity).toBe('error')
   })
 
   it('ships every OTHER kind past its grace period', () => {
@@ -2139,9 +2140,9 @@ describe('theme-allow scoping', () => {
     expect(f).toHaveLength(0)
   })
 
-  it('ships theme-allow-unscoped as a warning, not a build failure', () => {
+  it('ships theme-allow-unscoped as an error (promoted, C16)', () => {
     const f = find(`const x = 1 // theme-allow`)
-    expect(f.every((v) => v.severity === 'warn')).toBe(true)
+    expect(f.every((v) => v.severity === 'error')).toBe(true)
   })
 
   // The annotation itself lives in a comment; a `theme-allow` in real code must not waive anything.
@@ -2370,9 +2371,9 @@ describe('surface-shadow-override', () => {
     expect(kinds(f)).not.toContain('surface-shadow-override')
   })
 
-  it('ships as a warning for its grace minor', () => {
+  it('is an error now that its grace minor has ended (promoted, C16)', () => {
     const f = find('const s = { boxShadow: `0 0 0 2px ${VX.accent}` }')
-    expect(f.find((v) => v.kind === 'surface-shadow-override')?.severity).toBe('warn')
+    expect(f.find((v) => v.kind === 'surface-shadow-override')?.severity).toBe('error')
   })
 })
 
@@ -2435,6 +2436,114 @@ describe('inline-font-size', () => {
   })
 })
 
+// ── 26. in-body-page-title (the text lane of law C8) ─────────────────────────
+
+describe('in-body-page-title', () => {
+  it('flags <Title order={1}> in the body', () => {
+    expect(kinds(find(`<Title order={1}>Analytics</Title>`))).toContain('in-body-page-title')
+  })
+
+  it('flags order={2} too', () => {
+    expect(kinds(find(`<Title order={2}>Analytics</Title>`))).toContain('in-body-page-title')
+  })
+
+  // The formatted default — the reason this kind is a bounded TAG scan and not a line regex.
+  it('flags a Title formatted across lines', () => {
+    const f = find(`<Title\n  order={1}\n  mb="sm"\n>\n  Analytics\n</Title>`)
+    expect(kinds(f)).toContain('in-body-page-title')
+  })
+
+  it('does NOT flag order={3} — a section heading', () => {
+    expect(kinds(find(`<Title order={3}>Sessions</Title>`))).not.toContain('in-body-page-title')
+  })
+
+  it('does NOT flag a Title with no order', () => {
+    expect(kinds(find(`<Title>Sessions</Title>`))).not.toContain('in-body-page-title')
+  })
+
+  it('does NOT flag anything under a content/ path segment', () => {
+    const f = find(`<Title order={1}>Doc</Title>`, 'src/content/Guide.tsx')
+    expect(kinds(f)).not.toContain('in-body-page-title')
+  })
+
+  // File-scoped and coarser than the plugin's node-level ancestry, on purpose: a document heading
+  // told to become a breadcrumb is the WRONG advice, so the text lane errs silent.
+  it('does NOT flag a file that renders Prose', () => {
+    const f = find(`<Prose>\n  <Title order={1}>Doc</Title>\n</Prose>`)
+    expect(kinds(f)).not.toContain('in-body-page-title')
+  })
+
+  it('honours a theme-allow', () => {
+    const f = find(
+      `// theme-allow in-body-page-title — a shell-less print view\n<Title order={1}>P</Title>`,
+    )
+    expect(kinds(f)).not.toContain('in-body-page-title')
+  })
+
+  it('lands warn while the grace entry stands (C16)', () => {
+    const f = find(`<Title order={1}>Analytics</Title>`)
+    expect(f.find((x) => x.kind === 'in-body-page-title')?.severity).toBe('warn')
+  })
+})
+
+// ── 27. raw-selection-control (the text lane of law C1) ──────────────────────
+
+describe('raw-selection-control', () => {
+  it.each(['SegmentedControl', 'Select', 'MultiSelect', 'NativeSelect', 'TagsInput', 'Chip.Group'])(
+    'flags a raw <%s>',
+    (tag) => {
+      expect(kinds(find(`<${tag} data={[]} />`))).toContain('raw-selection-control')
+    },
+  )
+
+  it('reports the tag it found, not the whole line', () => {
+    const f = find(`<Select data={[]} />`)
+    expect(f.find((x) => x.kind === 'raw-selection-control')?.token).toBe('<Select')
+  })
+
+  it.each(['SettingsRow', 'Modal', 'Drawer', 'Menu.Dropdown'])(
+    'does NOT flag one inside a %s window',
+    (host) => {
+      const f = find(`<${host}>\n  <Select data={[]} />\n</${host}>`)
+      expect(kinds(f)).not.toContain('raw-selection-control')
+    },
+  )
+
+  // The window is 12 lines; past it the approximation would start swallowing the NEXT row's control.
+  it('DOES flag one 20 lines below the host tag — the window is bounded', () => {
+    const f = find(`<Modal>\n${'  <Text>x</Text>\n'.repeat(20)}  <Select data={[]} />\n</Modal>`)
+    expect(kinds(f)).toContain('raw-selection-control')
+  })
+
+  it('does NOT flag anything in a file importing @mantine/form', () => {
+    const f = find(`import { useForm } from '@mantine/form'\n<Select data={[]} />`)
+    expect(kinds(f)).not.toContain('raw-selection-control')
+  })
+
+  it('does NOT flag the file that DEFINES a basalt control', () => {
+    const f = find(`export function ViewTabs() {\n  return <SegmentedControl data={[]} />\n}`)
+    expect(kinds(f)).not.toContain('raw-selection-control')
+  })
+
+  it('does NOT flag a bound basalt control', () => {
+    expect(kinds(find(`<SelectFilter field={f} label="Channel" />`))).not.toContain(
+      'raw-selection-control',
+    )
+  })
+
+  it('honours a theme-allow', () => {
+    const f = find(
+      `{/* theme-allow raw-selection-control — a one-off admin picker */}\n<Select data={[]} />`,
+    )
+    expect(kinds(f)).not.toContain('raw-selection-control')
+  })
+
+  it('lands warn while the grace entry stands (C16)', () => {
+    const f = find(`<Select data={[]} />`)
+    expect(f.find((x) => x.kind === 'raw-selection-control')?.severity).toBe('warn')
+  })
+})
+
 // ── 26. hidden-inline-style ──────────────────────────────────────────────────
 
 describe('hidden-inline-style', () => {
@@ -2475,12 +2584,12 @@ export const C = () => <div style={labelStyle} />`,
     expect(kinds(f)).not.toContain('hidden-inline-style')
   })
 
-  it('ships as a warning for its grace minor', () => {
+  it('is an error now that its grace minor has ended (promoted, C16)', () => {
     const f = find(
       `const wrapperStyle = { position: 'relative', width: '100%' }
 export const C = () => <div style={wrapperStyle} />`,
     )
-    expect(f.find((v) => v.kind === 'hidden-inline-style')?.severity).toBe('warn')
+    expect(f.find((v) => v.kind === 'hidden-inline-style')?.severity).toBe('error')
   })
 })
 
@@ -2638,7 +2747,7 @@ describe('markup files (index.html / *.webmanifest)', () => {
  * Round 9: `.astro` and `.vue` became scannable and fell through to the `ts` dialect, so `<!-- … -->`
  * was never stripped — a `theme-allow` written in an HTML comment waived nothing there, and a color
  * inside a commented-out block still reported. They resolve as `sfc` now: BOTH comment dialects,
- * and the full 25-kind set (not `MARKUP_KINDS` — an `.astro` template is JSX-shaped and a `.vue`
+ * and the full 27-kind set (not `MARKUP_KINDS` — an `.astro` template is JSX-shaped and a `.vue`
  * `<script setup>` is real TS).
  */
 describe('single-file components (.astro / .vue)', () => {
@@ -2770,11 +2879,15 @@ describe("profile: 'tokens-only'", () => {
     'css-raw-surface': false,
     'inline-font-size': false,
     'hidden-inline-style': true,
+    // The two wave-6 control kinds: `<Title>` is a Mantine component, and the remedy for either is
+    // a Mantine-rendered home (PageBar / WidgetHeader) or a basalt control over @mantine/core.
+    'in-body-page-title': true,
+    'raw-selection-control': true,
   }
 
   it('classifies every kind in the registry — the table is exhaustive', () => {
     expect(Object.keys(MANTINE_COUPLED).toSorted()).toEqual(Object.keys(GUARD_RULES).toSorted())
-    expect(Object.keys(MANTINE_COUPLED)).toHaveLength(25)
+    expect(Object.keys(MANTINE_COUPLED)).toHaveLength(27)
   })
 
   it('the disabled set is exactly the Mantine-coupled half — a complete partition', () => {

package/src/guard/grace.test.ts

@@ -0,0 +1,149 @@
+/**
+ * The C16 version gate (`docs/CONTROLS-SPEC.md` §1): a `GRACE_PERIOD_KINDS` entry fails the build
+ * once `package.json`'s version reaches its `promote`, and every entry must declare `since` before
+ * `promote`. This is the mechanism that replaces the honor system — deleting an entry used to be
+ * the ONLY enforcement of "warn for one minor", and nothing checked that anyone had (D4:
+ * `docs/archive/CONTROLS-SYNTHESIS.md`). Five kinds landed together in the round-4 guard minor and sat
+ * at `warn` for five minors before this test existed.
+ *
+ * `assertGraceLedger` is tested directly against synthetic entries below rather than only through
+ * the real ledger: every pre-existing entry promoted or moved to `PLUGIN_RULE_ADVISORY`'s guard-side
+ * sibling, and an `it.each` over the empty ledger that left behind ran zero assertions, which proved
+ * nothing about the gate actually firing. The ledger now carries the two wave-6 control kinds
+ * (`in-body-page-title`, `raw-selection-control`, both `promote: '1.27.0'`), and the real-ledger
+ * check below runs against them.
+ *
+ * This gate measures the version already PUBLISHED, so it can only go red after the release that
+ * shipped a due entry. `scripts/check-grace.ts` is the other end — `scripts/release.sh` runs it
+ * against the version the dry run computed, before the release is cut.
+ *
+ * Excluded from tsc (tsconfig exclude: src/**\/*.test.ts), run via `bun test`.
+ */
+import { describe, expect, it } from 'bun:test'
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { GRACE_PERIOD_KINDS } from './index'
+
+const PACKAGE_JSON_PATH = resolve(import.meta.dirname, '..', '..', 'package.json')
+const CURRENT_VERSION = (JSON.parse(readFileSync(PACKAGE_JSON_PATH, 'utf8')) as { version: string })
+  .version
+
+type GraceEntry = { since: string; promote: string; why: string }
+
+/**
+ * Tiny local semver compare — no dependency. Assumes plain `x.y.z`, no pre-release identifiers
+ * (basalt-ui bans majors and ships no pre-releases). Returns negative when `a` sorts before `b`,
+ * positive when after, zero when equal. Compares each component numerically, not lexically, so
+ * `'1.9.0' < '1.10.0'` and `'1.3.0' < '1.26.0'` — a string compare would get both backwards.
+ */
+export function compareSemver(a: string, b: string): number {
+  const partsA = a.split('.').map(Number)
+  const partsB = b.split('.').map(Number)
+  for (let i = 0; i < 3; i++) {
+    const diff = (partsA[i] ?? 0) - (partsB[i] ?? 0)
+    if (diff !== 0) return diff > 0 ? 1 : -1
+  }
+  return 0
+}
+
+/**
+ * The C16 gate itself, extracted so it can be exercised against a synthetic ledger as well as the
+ * real one. Throws naming the first offending entry when either invariant breaks: `since` must
+ * precede `promote` for every entry, and no entry's `promote` may be `<=` the given `version`.
+ */
+export function assertGraceLedger(ledger: Record<string, GraceEntry>, version: string): void {
+  for (const [id, entry] of Object.entries(ledger)) {
+    if (compareSemver(entry.since, entry.promote) >= 0) {
+      throw new Error(
+        `${id}: \`since\` (${entry.since}) must be before \`promote\` (${entry.promote}).`,
+      )
+    }
+    if (compareSemver(version, entry.promote) >= 0) {
+      throw new Error(
+        `${id}: package.json is at ${version}, which has reached its promote version ` +
+          `${entry.promote} — promote to error or extend \`promote\` with a reason.`,
+      )
+    }
+  }
+}
+
+describe('compareSemver', () => {
+  it('orders multi-digit components numerically, not lexically', () => {
+    expect(compareSemver('1.9.0', '1.10.0')).toBeLessThan(0)
+    expect(compareSemver('1.10.0', '1.9.0')).toBeGreaterThan(0)
+    expect(compareSemver('1.3.0', '1.26.0')).toBeLessThan(0)
+    expect(compareSemver('1.26.0', '1.3.0')).toBeGreaterThan(0)
+  })
+
+  it('treats equal versions as equal', () => {
+    expect(compareSemver('1.25.0', '1.25.0')).toBe(0)
+  })
+})
+
+describe('assertGraceLedger', () => {
+  it('does not throw on a well-formed entry not yet due', () => {
+    const ledger = { 'fake-kind': { since: '1.0.0', promote: '2.0.0', why: 'synthetic' } }
+    expect(() => assertGraceLedger(ledger, '1.25.0')).not.toThrow()
+  })
+
+  it('throws once the given version reaches promote', () => {
+    const ledger = { 'fake-kind': { since: '1.0.0', promote: '1.25.0', why: 'synthetic' } }
+    expect(() => assertGraceLedger(ledger, '1.25.0')).toThrow(/fake-kind/)
+  })
+
+  it('throws once the given version is past promote', () => {
+    const ledger = { 'fake-kind': { since: '1.0.0', promote: '1.9.0', why: 'synthetic' } }
+    expect(() => assertGraceLedger(ledger, '1.10.0')).toThrow(/fake-kind/)
+  })
+
+  it('throws when since does not precede promote', () => {
+    const ledger = { 'fake-kind': { since: '1.5.0', promote: '1.5.0', why: 'synthetic' } }
+    expect(() => assertGraceLedger(ledger, '1.0.0')).toThrow(/since/)
+  })
+})
+
+describe('GRACE_PERIOD_KINDS — version gate (C16)', () => {
+  it('the real ledger passes the gate against the real package version', () => {
+    expect(() =>
+      assertGraceLedger(GRACE_PERIOD_KINDS as Record<string, GraceEntry>, CURRENT_VERSION),
+    ).not.toThrow()
+  })
+})
+
+// ── the release-time half: scripts/check-grace.ts ────────────────────────────
+// Exercised as a PROCESS, because that is how `scripts/release.sh` consumes it — the exit code is
+// the whole interface, and a script that printed the right words with status 0 would gate nothing.
+
+const CHECK_GRACE = resolve(import.meta.dirname, '..', '..', 'scripts', 'check-grace.ts')
+
+function runCheckGrace(...args: string[]): { code: number; stderr: string; stdout: string } {
+  const result = Bun.spawnSync(['bun', CHECK_GRACE, ...args])
+  return {
+    code: result.exitCode,
+    stderr: result.stderr.toString(),
+    stdout: result.stdout.toString(),
+  }
+}
+
+describe('scripts/check-grace.ts', () => {
+  it('passes for a version below every promote', () => {
+    const { code, stdout } = runCheckGrace('1.0.0')
+    expect([code, stdout.includes('clear of all')]).toEqual([0, true])
+  })
+
+  it('refuses a version that has reached a promote, naming the entries', () => {
+    const { code, stderr } = runCheckGrace('9.9.9')
+    expect(code).toBe(1)
+    expect(stderr).toContain('raw-selection-control')
+    expect(stderr).toContain('basalt/control-outside-home')
+  })
+
+  it('refuses the version the wave-6 entries are due in (1.27.0)', () => {
+    expect(runCheckGrace('1.27.0').code).toBe(1)
+  })
+
+  it('exits 2 on a missing or malformed version rather than passing vacuously', () => {
+    expect(runCheckGrace().code).toBe(2)
+    expect(runCheckGrace('not-a-version').code).toBe(2)
+  })
+})

package/src/guard/index.ts

@@ -1,7 +1,7 @@
 /**
  * ./guard — headless policy core. Mantine-free, dependency-free.
  *
- * GUARD_RULES: the closed registry of all 25 violation kinds.
+ * GUARD_RULES: the closed registry of all 27 violation kinds.
  * checkSource:  pure (text, relPath, cfg) → Finding[]. No FS, no walk, no console.
  */
 import type { Finding, GuardConfig, GuardKind, GuardSeverity } from './types'
@@ -483,6 +483,52 @@ const RAW_FORM_CONTROL = /<(?:input|select|textarea)\b/g
 // for a sub-floor fontSize.
 const RAW_FORM_CONTROL_TAG = /<(?:input|select|textarea)\b(?:=>|[^>])*?>/g
 
+// ── Control-home patterns (docs/CONTROLS-SPEC.md §6 — the text lane of laws C1/C8) ──────────────
+//
+// Bounded full-text tag scans, the CARD_SURFACE_TAG / CHART_ENTRY_POINT_TAG shape: a `<Title>` and a
+// `<Select>` are both routinely formatted across lines, so a per-line regex would see neither.
+
+/** A `<Title …>` opening tag, however it is wrapped. `order` is judged separately, on the tag text. */
+const PAGE_TITLE_TAG = /<Title(?![\w.])(?:=>|[^>])*?>/g
+/** `order={1}` / `order={2}` — the two orders that name a PAGE rather than a section. */
+const PAGE_TITLE_ORDER_PROP = /\border\s*=\s*\{\s*([12])\s*\}/
+
+/**
+ * A raw Mantine selection control's opening tag — the text-lane twin of the oxlint plugin's
+ * RAW_FILTER_TAGS. `Chip.Group` carries a dot, so the name class allows one.
+ */
+const RAW_SELECTION_CONTROL_TAG =
+  /<(SegmentedControl|Select|MultiSelect|NativeSelect|DatePickerInput|DateInput|TagsInput|Chip\.Group)(?![\w])(?:=>|[^>])*?>/g
+
+/**
+ * A tag whose presence makes an `order={1|2}` Title a DOCUMENT heading rather than a page title.
+ * File-scoped on purpose — see the scan's own comment for why the coarser test is the honest one.
+ */
+const PROSE_CONTEXT_TAG = /<(?:Prose|ArticleLayout|Modal|Drawer)(?![\w])/
+
+/** An opening tag for one of the declared non-homes — a settings row, an overlay, a composer. */
+const CONTROL_HOST_TAG =
+  /<(?:SettingsRow|Modal|Drawer|Popover\.Dropdown|Menu\.Dropdown|Composer)(?![\w])/
+
+/**
+ * How far ABOVE a control the host-tag window reaches, in lines.
+ *
+ * The text lane has no ancestry, so "inside a SettingsRow" is approximated by "a SettingsRow opens
+ * within the last N lines". 12 covers every row shape in the five consumer repos (label +
+ * description + the `control={` line); past that the window would start swallowing the next row's
+ * control, which is the direction that makes the kind silent rather than noisy. The plugin rule
+ * (`basalt/control-outside-home`) is the one that answers this exactly — this kind exists for the
+ * PreToolUse hook lane, which sees one file's TEXT and no AST at all.
+ */
+const CONTROL_HOST_WINDOW_LINES = 12
+
+/** A name whose DECLARATION means this file DEFINES a basalt control rather than consuming one. */
+const CONTROL_OWNER_DEF =
+  /\b(?:function|const|class)\s+(?:RangeFilter|CompareFilter|SelectFilter|MultiSelectFilter|SearchFilter|ToggleFilter|ViewTabs|FilterSet|FilterPill|SyncButton|ActionGroup|OverflowMenu|CtlSlot)(?![\w])/
+
+/** `@mantine/form` — a form is C1's third home, and its inputs are not filters. */
+const MANTINE_FORM_IMPORT = /from\s+['"]@mantine\/form['"]/
+
 // A Mantine `styles={{ input: {...} }}` per-part style — the `input` key specifically targets the
 // rendered <input>/<textarea> part of TextInput/Select/Textarea/etc. Requires `input` be the FIRST
 // key in the styles object (see the sub-16-input-font doc comment for the scoping trade-off this
@@ -541,20 +587,32 @@ export const DEFAULT_GUARD_CONFIG: GuardConfig = {
   severity: {},
 }
 
+/**
+ * A grace-ledger entry: `since` and `promote` are plain `x.y.z` semver strings (C16,
+ * `docs/CONTROLS-SPEC.md` §1). `grace.test.ts` fails the build once `package.json`'s version
+ * reaches `promote` while the entry is still here — the version-gate that replaces the honor
+ * system a bare promotion-note string used to run on. `since` must be strictly before `promote`,
+ * also asserted there.
+ */
+export type GraceEntry = { since: string; promote: string; why: string }
+
 /**
  * Kinds still inside their grace minor — reported, not fatal, until the next minor promotes them.
  * See {@link GuardSeverity} for the doctrine and why basalt-ui in particular needs it.
  *
- * The value is the promotion note, so the entry carries its own expiry rather than relying on
- * someone remembering. Adding a kind here is part of shipping it; removing the entry IS the
- * promotion, and belongs in its own commit so the changelog says enforcement got stricter.
+ * Adding a kind here is part of shipping it; removing the entry IS the promotion, and belongs in
+ * its own commit so the changelog says enforcement got stricter. `grace.test.ts` is the other half
+ * of "belongs in its own commit": it fails once `package.json`'s version reaches an entry's
+ * `promote` while the entry is still here, so a kind can no longer sit at `warn` with nothing
+ * tracking it — which is exactly what happened to the five entries this ledger shipped in the
+ * round-4 guard minor (D4, `docs/CONTROLS-SPEC.md` §6): all five stayed `warn` for five minors
+ * because deleting the entry was the only enforcement, and nothing checked that anyone had.
  *
  * The runway is measured in consumer UPGRADES, not in version numbers: `mantine-shade-index`
  * (the table's first tenant, promoted and gone) sat here across two minors because 1.8.0 shipped
  * the same day as 1.7.0 and 1.9.0 carried the chart batch the same consumer was upgrading for —
  * bundling a build-breaking promotion into the minor they take for the fixes turns a routine bump
- * into an unplanned refactor, which is exactly what the grace minor exists to prevent. The five
- * entries below all landed together in the round-4 guard minor and all promote one minor later.
+ * into an unplanned refactor, which is exactly what the grace minor exists to prevent.
  *
  * **A `SCANNABLE_EXT` widening cannot be expressed here, and 1.23.2's was deliberately not.**
  * Adding `.astro`/`.jsx`/`.vue` widens the FILE SET for all 25 kinds at once — there is no kind to
@@ -572,29 +630,30 @@ export const DEFAULT_GUARD_CONFIG: GuardConfig = {
  * with `theme-allow`, `basalt.severity` and `exemptRules` all still available.
  *
  * @example
- * const GRACE: Partial<Record<GuardKind, string>> = {
- *   'raw-font-family': 'introduced 1.4.0 — promote to error in 1.5.0',
+ * const GRACE: Partial<Record<GuardKind, GraceEntry>> = {
+ *   'raw-font-family': { since: '1.4.0', promote: '1.5.0', why: 'introduced 1.4.0 — …' },
  * }
  */
-const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, string>> = {
-  'theme-allow-unscoped':
-    'introduced in the round-4 guard minor — promote to error one minor later. Every consumer has ' +
-    'bare `theme-allow` comments today (basalt itself has ~20), and landing this as an error would ' +
-    'fail every one of their builds on an upgrade they took for the fixes.',
-  'surface-shadow-override':
-    'introduced in the round-4 guard minor — promote to error one minor later. Catches the shape a ' +
-    'TOKEN-FLUENT consumer writes, so the code it rejects is code that looks correct and passed ' +
-    'every previous release.',
-  'css-raw-surface':
-    'introduced in the round-4 guard minor — promote to error one minor later. The surface kinds ' +
-    'reaching CSS at all is the "existing kind, new file type" case the doctrine names explicitly.',
-  'inline-font-size':
-    'introduced in the round-4 guard minor — promote to error one minor later. The oxlint plugin ' +
-    'has enforced the same thing as `basalt/no-raw-font-size` for a while, so a consumer running ' +
-    'both sees nothing new; one running check-theme alone gets a minor of runway.',
-  'hidden-inline-style':
-    'introduced in the round-4 guard minor — promote by DELETING the kind and folding its two ' +
-    'scans into `raw-html-layout`, which is where they belong once the widening has had its minor.',
+export const GRACE_PERIOD_KINDS: Partial<Record<GuardKind, GraceEntry>> = {
+  'in-body-page-title': {
+    since: '1.26.0',
+    promote: '1.27.0',
+    why:
+      'new in the wave-6 control guards (docs/CONTROLS-SPEC.md §6, law C8). Its AST twin is the ' +
+      'oxlint rule of the SAME id, whose PLUGIN_RULE_GRACE entry carries the same dates — one law, ' +
+      'two lanes, one promotion. Warn for a minor because the fix is a route/breadcrumb change ' +
+      '(the page is named by staticData.title), not a prop edit, so a consumer needs to schedule it.',
+  },
+  'raw-selection-control': {
+    since: '1.26.0',
+    promote: '1.27.0',
+    why:
+      '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. Promotion is gated with the plugin half on the wave-7 consumer run (≤3 ' +
+      'waivers), and `scripts/check-grace.ts` refuses the 1.27.0 release while the entry is still here.',
+  },
 }
 
 /** A kind's effective severity: consumer override first, then the grace table, then `error`. */
@@ -762,6 +821,16 @@ export const PLUGIN_RULE_IDS: ReadonlySet<string> = new Set([
   'hand-rolled-shell',
   'shadow-basalt-export',
   'raw-scroll-container',
+  'hand-rolled-filter',
+  'control-outside-home',
+  'control-size-literal',
+  'page-bar-budget',
+  'responsive-twin',
+  'search-literal-link',
+  'use-search-from-literal',
+  // `in-body-page-title` is deliberately ABSENT: it is a plugin rule AND a guard kind under one id
+  // (one law, two lanes, one annotation), and this set is the ids OUTSIDE `checkSource`'s reach.
+  // `check-source.test.ts` asserts the two registries stay disjoint.
   'visx-boundary',
   'visx-tooltip',
   'token-layer-boundary',
@@ -1388,6 +1457,11 @@ export const TOKENS_ONLY_DISABLED_KINDS: ReadonlySet<GuardKind> = new Set([
   'chart-missing-aria-label',
   'raw-form-control',
   'sub-16-input-font',
+  // Both wave-6 control kinds: `<Title>` is a Mantine component and the remedy for either one is a
+  // Mantine-rendered home (PageBar / WidgetHeader) or a basalt control over @mantine/core. Neither
+  // sentence is followable in a consumer that installs the token layer and nothing else.
+  'in-body-page-title',
+  'raw-selection-control',
 ])
 
 // A `/` opens a regex literal (not division) when the previous significant token is one of these
@@ -1608,7 +1682,7 @@ type GuardRule = {
 }
 
 /**
- * The closed registry of all 25 guard kinds. The triad test asserts
+ * The closed registry of all 27 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
@@ -1827,7 +1901,23 @@ export const GUARD_RULES = {
     enabled: (cfg: GuardConfig) => cfg.rawHtmlLayout,
     appliesTo: (relPath) => !isChartFile(relPath) && !relPath.endsWith('.css'),
     message:
-      'Raw HTML element with inline layout/surface styling that the line scan cannot see — the tag is formatted across lines, or the style object is hoisted to a const. Same violation as raw-html-layout: use a Mantine layout primitive (Box/Flex/Grid/Stack/Group). Its own kind for one minor so the widening lands as a warning; it merges into raw-html-layout at the promotion.',
+      'Raw HTML element with inline layout/surface styling that the line scan cannot see — the tag is formatted across lines, or the style object is hoisted to a const. Same violation as raw-html-layout: use a Mantine layout primitive (Box/Flex/Grid/Stack/Group). Promoted to error in the Unreleased minor (C16) with severity only — the kind stayed standalone rather than folding into raw-html-layout as originally planned; the merge is still open, tracked as a follow-up, not done here.',
+  },
+  'in-body-page-title': {
+    kind: 'in-body-page-title',
+    pattern: PAGE_TITLE_TAG, // handled inline (full-text tag-scoped scan); entry keeps the registry complete
+    // JSX-tag-shaped (`<Title order={1}>`) — never appears in CSS text.
+    appliesTo: (relPath) => !relPath.endsWith('.css'),
+    message:
+      'In-body page title — a page is named ONCE, by the breadcrumb (staticData.title) or by PageBar.title in a shell-less app, and every section/card/table title is a WidgetHeader (docs/CONTROLS-SPEC.md law C8). An <Title order={1|2}> in the body is a second name for the same page, and it drifts. Prose / ArticleLayout / an overlay and anything under a content/ path are document headings and never report. Same law the oxlint plugin enforces as basalt/in-body-page-title — one id, two lanes, so one theme-allow covers both.',
+  },
+  'raw-selection-control': {
+    kind: 'raw-selection-control',
+    pattern: RAW_SELECTION_CONTROL_TAG, // handled inline (full-text tag-scoped scan + host window)
+    // 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. 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',
@@ -2249,6 +2339,59 @@ export function checkSource(text: string, relPath: string, cfg: GuardConfig): Fi
     }
   }
 
+  // in-body-page-title — full-text tag scan (the card-with-border shape), because a `<Title>` with
+  // its props on separate lines is the formatted default. `order` is judged on the tag's own text.
+  //
+  // Two file-level exemptions, both deliberately coarser than the plugin's node-level ones and both
+  // false-NEGATIVE-only: anything under a `content/` path segment, and any file that renders
+  // `<Prose>` / `<ArticleLayout>` / an overlay anywhere in it. A text scan has no ancestry, so
+  // "under Prose" is not answerable per node — and a document heading told to become a breadcrumb is
+  // the wrong advice, not merely noise. `basalt/in-body-page-title` (the AST lane, same id) is the
+  // half that scopes this exactly.
+  if (
+    ruleApplies('in-body-page-title', relPath) &&
+    !relPath.split('/').includes('content') &&
+    !PROSE_CONTEXT_TAG.test(codeText)
+  ) {
+    for (const m of codeText.matchAll(PAGE_TITLE_TAG)) {
+      const order = PAGE_TITLE_ORDER_PROP.exec(m[0])
+      if (order === null) continue
+      const startLine = codeText.slice(0, m.index ?? 0).split('\n').length
+      const endLine = startLine + (m[0].split('\n').length - 1)
+      if (isAllowedInRange(startLine, endLine, 'in-body-page-title')) continue
+      findings.push({
+        relPath,
+        line: startLine,
+        token: `<Title order={${order[1]}}`,
+        kind: 'in-body-page-title',
+      })
+    }
+  }
+
+  // raw-selection-control — full-text tag scan plus the host WINDOW (see CONTROL_HOST_WINDOW_LINES).
+  // Two file-level exemptions mirror the plugin rule's, so the two lanes agree on the same file:
+  // a file that DEFINES a basalt control cannot be told to use one, and a file importing
+  // `@mantine/form` is a form — C1's third home, whose inputs are not filters.
+  if (
+    ruleApplies('raw-selection-control', relPath) &&
+    !CONTROL_OWNER_DEF.test(codeText) &&
+    !MANTINE_FORM_IMPORT.test(codeText)
+  ) {
+    for (const m of codeText.matchAll(RAW_SELECTION_CONTROL_TAG)) {
+      const startLine = codeText.slice(0, m.index ?? 0).split('\n').length
+      const windowStart = Math.max(0, startLine - 1 - CONTROL_HOST_WINDOW_LINES)
+      if (CONTROL_HOST_TAG.test(codeLines.slice(windowStart, startLine).join('\n'))) continue
+      const endLine = startLine + (m[0].split('\n').length - 1)
+      if (isAllowedInRange(startLine, endLine, 'raw-selection-control')) continue
+      findings.push({
+        relPath,
+        line: startLine,
+        token: `<${m[1] ?? 'Select'}`,
+        kind: 'raw-selection-control',
+      })
+    }
+  }
+
   // sub-16-input-font — two full-text scans (same shape as the tag-scoped scans above): (a) a raw
   // form-control's own inline `style={{ fontSize: N }}`, (b) a Mantine `styles={{ input: { fontSize:
   // N } }}` per-part style. Either shape is now DEAD CODE against the `!important` floor in