basalt-ui 1.25.0 → 1.26.0

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

package/src/guard/types.ts

@@ -1,12 +1,12 @@
 /**
  * Guard types — Mantine-free, dependency-free (zero imports beyond TS types).
  *
- * GuardKind is the closed set of 25 violation kinds the theme guard can emit.
+ * GuardKind is the closed set of 27 violation kinds the theme guard can emit.
  * Finding is the structured result per violation, replacing the old `Violation` shape.
  * GuardConfig is the per-run configuration that drives checkSource.
  */
 
-/** The 25 theme-guard violation kinds. */
+/** The 27 theme-guard violation kinds. */
 export type GuardKind =
   | 'raw-hex'
   | 'raw-color-fn'
@@ -33,6 +33,8 @@ export type GuardKind =
   | 'css-raw-surface'
   | 'inline-font-size'
   | 'hidden-inline-style'
+  | 'in-body-page-title'
+  | 'raw-selection-control'
 
 /**
  * How hard a finding lands. `error` fails the build; `warn` reports and passes.

package/src/index.ts

@@ -14,6 +14,14 @@ export {
 } from './provider'
 export { createBasaltTheme, baseTheme, cssVariablesResolver } from './theme'
 export type { BasaltFontsConfig, CreateBasaltThemeOptions } from './theme'
+export { CTL_THEME, CtlSlot } from './theme'
+export type { CtlSlotProps } from './theme'
+/**
+ * The action vocabulary every home's `actions` slot takes (`docs/CONTROLS-SPEC.md` §2.1). The
+ * COMPONENTS that project it (`ActionGroup`, `OverflowMenu`, `SyncButton`, and the filter family)
+ * live on `basalt-ui/controls` — only the types a `PageBar`/`BasaltShell` prop mentions are here.
+ */
+export type { BarAction, ActionGroupProps, GlobalAction } from './controls/actions'
 export { ThemeToggle, type ThemeToggleProps } from './theme-toggle'
 export { MOTION_DURATION, MOTION_SPRING, MOTION_EASE_STANDARD } from './motion'
 export {
@@ -22,6 +30,7 @@ export {
   AppSidebar,
   SidebarSearch,
   type SidebarSearchConfig,
+  type SidebarSearchActions,
   SidebarAccount,
   MobileNav,
   type MobileNavProps,
@@ -31,11 +40,16 @@ export {
   MOBILE_MENU_MAX_DEFAULT,
   MOBILE_MORE_KEY,
   AppBreadcrumbs,
-  PageHeaderProvider,
-  PageActions,
-  PageActionsOutlet,
+  PageBar,
+  type PageBarProps,
   type SidebarSection,
   type SidebarItem,
+  type SidebarBlock,
+  type SidebarBlockItem,
+  type SidebarBlockTone,
+  type SidebarListBlock,
+  type SidebarProgressBlock,
+  type SidebarCustomBlock,
   type NavAnchor,
   type NavAnchorProps,
   type NavMobilePlacement,
@@ -72,14 +86,41 @@ export {
   type StandardSchemaV1,
 } from './register'
 
-// ── Persisted state + online hook (state.ts) ─────────────────────────────────────────────────────
+// ── Persisted state + the headless store kernel (state.ts) ───────────────────────────────────────
+// The `field.*` VALUE is deliberately not re-exported here — `basalt-ui/forms` already owns the
+// name `field` on its own barrel. Import it from `basalt-ui/router-tanstack` (beside
+// `createSearchStore`) or from `basalt-ui/state` (beside `createLocalStore`).
 export {
   createPersistedState,
   type PersistedStateOptions,
-  useOnlineStatus,
   readPersistedValue,
+  createLocalStore,
+  type LocalStore,
+  type AnyField,
+  type BooleanField,
+  type EnumField,
+  type FieldHandle,
+  type FieldLane,
+  type FieldOption,
+  type FieldValue,
+  type MultiField,
+  type NumberField,
+  type RangeField,
+  type RangeParams,
+  type RangePresets,
+  type RangeValue,
+  type ResolvedLane,
+  type SearchValues,
+  type StoredValues,
+  type StringField,
 } from './state'
 
+// ── WidgetHeader (unified section/widget/card heading primitive, docs/CONTROLS-SPEC.md §2.2) ─────
+export { WidgetHeader, type WidgetHeaderProps } from './widget-header'
+
+// ── Section (tier-2 heading composer over WidgetHeader, docs/CONTROLS-SPEC.md §2.2) ───────────────
+export { Section, type SectionProps } from './section'
+
 // ── Dashboard composites (KPI atoms + settings building blocks) ──────────────────────────────────
 export {
   DeltaBadge,

package/src/nav/types.ts

@@ -40,6 +40,8 @@ export type SidebarItem = {
   /** Plain href — the no-router fallback, and the breadcrumb parent target. */
   href?: string
   active?: boolean
+  /** A parent on the path to the active row. NOT active itself — never carries `aria-current`. */
+  ancestor?: boolean
   disabled?: boolean
   onClick?: (e: MouseEvent) => void
   /** Rich desktop badge (e.g. `NavCountBadge`). Desktop only. */
@@ -70,6 +72,88 @@ export type SidebarSection = {
   mobile?: false | NavSectionMobile
 }
 
+/**
+ * Status tone on a sidebar-block item — the same three-member vocabulary as `StatCardTone`, whose
+ * members are `VX.status` keys by construction. Declared here rather than imported from
+ * `../dashboard/stat-card`: this module is the one `./router-tanstack` reads, and even a
+ * type-only edge into the Mantine layer would make `nav/types.d.ts` unresolvable without
+ * `@mantine/core` installed.
+ */
+export type SidebarBlockTone = 'good' | 'warn' | 'bad'
+
+/** One row inside a `kind: 'list'` block. Same router seam as `SidebarItem` — `Anchor`, then href. */
+export type SidebarBlockItem = {
+  key: string
+  label: string
+  /** Trailing muted text (a timestamp, a count, an owner). */
+  meta?: string
+  icon?: ReactNode
+  /** Renders a status dot in place of a missing `icon`; reads `--vx-status-*`, never a hex. */
+  tone?: SidebarBlockTone
+  Anchor?: NavAnchor
+  href?: string
+  onClick?: () => void
+}
+
+/**
+ * A list of non-destination rows under a micro-label — "Awaiting action", "Recents", a project
+ * list. `count` is the header badge (and what earns a rail dot); `max` shows the first N with a
+ * "Show more" toggle past it.
+ */
+export type SidebarListBlock = {
+  kind: 'list'
+  key: string
+  label: string
+  icon?: ReactNode
+  count?: number
+  /** Rows shown before the "Show more" toggle. Omit to show every row. */
+  max?: number
+  items: SidebarBlockItem[]
+  /** @default 'nav' */
+  placement?: 'nav' | 'bottom'
+  collapsible?: boolean
+  /** Collapsed-rail projection. @default 'dot' when `count` is set, `'hidden'` otherwise */
+  rail?: 'dot' | 'hidden'
+  /** @default 'more' */
+  mobile?: 'more' | 'hidden'
+}
+
+/** A "Getting started 1 of 5" progress row. Pinned above the settings footer; never in the nav. */
+export type SidebarProgressBlock = {
+  kind: 'progress'
+  key: string
+  label: string
+  value: number
+  total: number
+  onClick?: () => void
+  /** @default 'bottom' — the only placement a progress row has. */
+  placement?: 'bottom'
+  /** Collapsed-rail projection: a ring on the settings row. @default 'ring' */
+  rail?: 'ring' | 'hidden'
+  /** @default 'hidden' */
+  mobile?: 'more' | 'hidden'
+}
+
+/**
+ * DESKTOP ONLY — arbitrary consumer content (a tree, a filter panel) that no set of rows can
+ * express. Replaced `BasaltShellProps.sidebarNavExtra`; hidden on the collapsed rail and absent
+ * from mobile for the same reason that prop was.
+ */
+export type SidebarCustomBlock = {
+  kind: 'custom'
+  key: string
+  node: ReactNode
+  /** @default 'nav' */
+  placement?: 'nav' | 'bottom'
+}
+
+/**
+ * A sidebar block — DECLARED DATA, never a `ReactNode` slot (law C13, `docs/CONTROLS-SPEC.md`
+ * §2.3), which is what lets basalt own the collapsed-rail badge and the mobile More-sheet
+ * projection instead of each consumer hand-rolling both.
+ */
+export type SidebarBlock = SidebarListBlock | SidebarProgressBlock | SidebarCustomBlock
+
 export type MobileNavSurface = 'link' | 'menu' | 'sheet'
 
 /** One row inside a `menu`/`sheet` slot, grouped under its source section. */
@@ -108,8 +192,6 @@ export type MobileNavConfig = {
   menuMax?: number
   /** @default 'More' */
   moreLabel?: string
-  /** Extra content pinned to the bottom of the More surface. */
-  moreExtra?: ReactNode
   /** Scroll container for active-slot re-tap. @default document.scrollingElement */
   getScrollElement?: () => HTMLElement | null
 }