basalt-ui 1.25.0 → 1.27.0

package/configs/oxlint-plugin.test.ts

@@ -12,8 +12,15 @@ import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'nod
 import { tmpdir } from 'node:os'
 import { dirname, resolve } from 'node:path'
 // eslint-disable-next-line -- the plugin is plain JS; the ledger + id set are named exports beside it
-import basaltPlugin, { KNOWN_RULE_IDS, PLUGIN_RULE_GRACE } from './oxlint-plugin.js'
-import { GUARD_RULES } from '../src/guard/index.ts'
+import basaltPlugin, {
+  CTL_THEME_TAGS,
+  KNOWN_RULE_IDS,
+  PLUGIN_RULE_ADVISORY,
+  PLUGIN_RULE_GRACE,
+} from './oxlint-plugin.js'
+import { CTL_THEME } from '../src/theme/ctl-theme'
+import { GUARD_RULES, PLUGIN_RULE_IDS } from '../src/guard/index.ts'
+import { PLUGIN_RULE_ID_LIST, SURFACES } from '../src/surfaces.ts'
 
 const PLUGIN_PATH = resolve(import.meta.dirname, 'oxlint-plugin.js')
 const OXLINT_BIN = resolve(import.meta.dirname, '..', '..', '..', 'node_modules', '.bin', 'oxlint')
@@ -35,6 +42,15 @@ beforeEach(() => {
         'basalt/chart-legend-literal': 'error',
         'basalt/shadow-basalt-export': 'error',
         'basalt/hand-rolled-shell': 'error',
+        'basalt/raw-scroll-container': 'error',
+        'basalt/hand-rolled-filter': 'error',
+        'basalt/control-outside-home': 'error',
+        'basalt/control-size-literal': 'error',
+        'basalt/page-bar-budget': 'error',
+        'basalt/in-body-page-title': 'error',
+        'basalt/responsive-twin': 'error',
+        'basalt/search-literal-link': 'error',
+        'basalt/use-search-from-literal': 'error',
         'basalt/visx-boundary': 'error',
         'basalt/visx-tooltip': 'error',
         'basalt/token-layer-boundary': 'error',
@@ -1152,32 +1168,134 @@ export const C = () => <NavLink label="Settings" />\n`,
 
 // ── grace ledger ↔ shipped preset ────────────────────────────────────────────
 
+type GraceEntry = { since: string; promote: string; why: string }
+
+/**
+ * Tiny local semver compare — no dependency. Assumes plain `x.y.z`, no pre-release identifiers.
+ * 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.
+ */
+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 (docs/CONTROLS-SPEC.md §1), extracted so it can be exercised against a
+ * synthetic ledger as well as the real `PLUGIN_RULE_GRACE` — an `it.each` over the real ledger ran
+ * zero assertions while it was empty, which proved nothing about the gate actually firing. 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.
+ *
+ * `version` is `package.json`'s, i.e. the version already published, so this half can only fail
+ * AFTER the release that shipped a due entry — `release.yml` runs no tests and the
+ * `chore: release … [skip ci]` commit skips CI. The pre-release half is
+ * `scripts/check-grace.ts`, run by `scripts/release.sh` against the version the dry run computed.
+ */
+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(
+        `basalt/${id}: shipped preset 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-rule': { 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-rule': { since: '1.0.0', promote: '1.25.0', why: 'synthetic' } }
+    expect(() => assertGraceLedger(ledger, '1.25.0')).toThrow(/fake-rule/)
+  })
+
+  it('throws once the given version is past promote', () => {
+    const ledger = { 'fake-rule': { since: '1.0.0', promote: '1.9.0', why: 'synthetic' } }
+    expect(() => assertGraceLedger(ledger, '1.10.0')).toThrow(/fake-rule/)
+  })
+
+  it('throws when since does not precede promote', () => {
+    const ledger = { 'fake-rule': { since: '1.5.0', promote: '1.5.0', why: 'synthetic' } }
+    expect(() => assertGraceLedger(ledger, '1.0.0')).toThrow(/since/)
+  })
+})
+
 describe('PLUGIN_RULE_GRACE', () => {
   const shipped = JSON.parse(readFileSync(resolve(import.meta.dirname, 'oxlint.json'), 'utf8')) as {
     rules: Record<string, unknown>
   }
-  const graceIds = Object.keys(PLUGIN_RULE_GRACE)
+  const pkgVersion = (
+    JSON.parse(readFileSync(resolve(import.meta.dirname, '..', 'package.json'), 'utf8')) as {
+      version: string
+    }
+  ).version
+  const graceEntries = Object.entries(PLUGIN_RULE_GRACE) as [string, GraceEntry][]
+  const advisoryEntries = Object.entries(PLUGIN_RULE_ADVISORY) as [
+    string,
+    { since: string; why: string },
+  ][]
+  const graceIds = graceEntries.map(([id]) => id)
+  const advisoryIds = advisoryEntries.map(([id]) => id)
   const shippedBasaltIds = Object.keys(shipped.rules).filter((id) => id.startsWith('basalt/'))
 
   // The mechanism whose ABSENCE let three rules sit at `warn` for up to twelve minors with nothing
   // tracking them. Deleting a ledger entry IS the promotion, and this test makes flipping the
   // shipped level part of the same commit.
-  it('every ledger entry is warn in the shipped preset', () => {
-    for (const id of graceIds) expect(shipped.rules[`basalt/${id}`]).toBe('warn')
+  it('every grace and advisory entry is warn in the shipped preset', () => {
+    for (const id of [...graceIds, ...advisoryIds])
+      expect(shipped.rules[`basalt/${id}`]).toBe('warn')
   })
 
-  it('every shipped rule NOT in the ledger is error', () => {
+  it('every shipped rule NOT in either ledger is error', () => {
     for (const id of shippedBasaltIds) {
-      if (graceIds.includes(id.slice('basalt/'.length))) continue
+      const bareId = id.slice('basalt/'.length)
+      if (graceIds.includes(bareId) || advisoryIds.includes(bareId)) continue
       expect([id, shipped.rules[id]]).toEqual([id, 'error'])
     }
   })
 
-  it('every ledger entry carries a written promotion note', () => {
-    for (const id of graceIds) {
-      expect((PLUGIN_RULE_GRACE as Record<string, string>)[id]?.length ?? 0).toBeGreaterThan(40)
+  it('every entry carries a written why', () => {
+    for (const [id, entry] of [...graceEntries, ...advisoryEntries]) {
+      if (entry.why.length <= 40)
+        throw new Error(`${id}: \`why\` must be longer than 40 characters.`)
+      expect(entry.why.length).toBeGreaterThan(40)
     }
   })
+
+  // The C16 version gate, run against the REAL ledger and REAL package version — covers `since` <
+  // `promote` and "no entry has reached its promote version" in one call. ADVISORY entries are
+  // exempt by design (see `assertGraceLedger`'s synthetic coverage above for the gate itself).
+  it('passes the C16 gate against the real ledger and package version', () => {
+    expect(() => assertGraceLedger(Object.fromEntries(graceEntries), pkgVersion)).not.toThrow()
+  })
 })
 
 // ── chart-legend-literal: the .map() half ────────────────────────────────────
@@ -1287,10 +1405,29 @@ describe('KNOWN_RULE_IDS', () => {
     }
   })
 
+  // Deduped, because ONE id is deliberately in both registries: `in-body-page-title` is a plugin
+  // rule AND a guard kind (law C8 has an AST half and a text half), so one `theme-allow
+  // in-body-page-title — <why>` waives both lanes rather than needing a different word per lane.
   it('contains nothing else — it is exactly the union of the two registries', () => {
-    const expected = [...Object.keys(basaltPlugin.rules), ...Object.keys(GUARD_RULES)].toSorted()
+    const expected = [
+      ...new Set([...Object.keys(basaltPlugin.rules), ...Object.keys(GUARD_RULES)]),
+    ].toSorted()
     expect([...KNOWN_RULE_IDS].toSorted()).toEqual(expected)
   })
+
+  it('shares exactly one id between the two registries — the C8 pair', () => {
+    const shared = Object.keys(basaltPlugin.rules).filter((id) => Object.hasOwn(GUARD_RULES, id))
+    expect(shared).toEqual(['in-body-page-title'])
+  })
+
+  // The guard's own copy (`PLUGIN_RULE_IDS`) is what `check-theme --audit-allows` classifies an
+  // annotation against: an id in neither registry reads as a typo and is reported unscoped. A new
+  // plugin rule missing from it would make every waiver naming it look like a mistake.
+  it('every plugin rule is classifiable by the guard — its own id set or a guard kind', () => {
+    for (const id of Object.keys(basaltPlugin.rules)) {
+      expect([id, PLUGIN_RULE_IDS.has(id) || Object.hasOwn(GUARD_RULES, id)]).toEqual([id, true])
+    }
+  })
 })
 
 // ── theme-allow fails closed on a typo ─────────────────────────────────────────────────────────
@@ -1335,3 +1472,1045 @@ describe('theme-allow with an unrecognized rule id', () => {
     expect(code).toBe(0)
   })
 })
+
+// ── the control-home rules (docs/CONTROLS-SPEC.md §6) ────────────────────────
+
+const MANTINE_IMPORT = `import { Button, ScrollArea, SegmentedControl, Select } from '@mantine/core'\n`
+
+/**
+ * The home components, imported from basalt — the OWNER-tag provenance every slot rule now requires.
+ *
+ * Not decoration: `Section` is one of the most common local component names there is, and matching
+ * the bare tag made a consumer's own `<Section actions={…}>` an `error`-level tiered home. A fixture
+ * that renders `<PageBar>` out of thin air proves nothing a real consumer file would hit, so the
+ * fixtures import what they render.
+ */
+const BASALT_IMPORT = `import { ChartCard, PageBar, Section, SettingsSection } from 'basalt-ui'\n`
+
+describe('basalt/hand-rolled-filter', () => {
+  it('flags a raw Mantine Select handed to a PageBar filters slot', () => {
+    const { code, rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => <PageBar filters={<Select data={[]} />} />\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('hand-rolled-filter')
+  })
+
+  it('flags it through a hoisted binding — the argo headerExtra shape', () => {
+    const { code, rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}const pills = <Select data={[]} />\n` +
+        `export const C = () => <PageBar filters={pills} />\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('hand-rolled-filter')
+  })
+
+  it('flags one inside an ARRAY slot value (filtersEnd={[…]})', () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => <PageBar filtersEnd={[<Select key="a" data={[]} />]} />\n`,
+    )
+    expect(rules).toContain('hand-rolled-filter')
+  })
+
+  // The body form is the whole reason the walk stops at the slot ATTRIBUTE: a Section's children
+  // are a page region, not a control home, and a form there is C1's third home.
+  // `control-outside-home` DOES report this one (a Section body is not a home either) — which is
+  // the point of the split: the body form is a warn about placement, never an error about the slot.
+  it("does NOT flag a Select in a Section's CHILDREN — the body form", () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => (\n  <Section title="Filters">\n    <Select data={[]} />\n  </Section>\n)\n`,
+    )
+    expect(rules).not.toContain('hand-rolled-filter')
+  })
+
+  it("does NOT flag a slot prop on a tag that is not a home (a consumer's own Toolbar)", () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => <Toolbar filters={<Select data={[]} />} />\n`,
+    )
+    expect(rules).not.toContain('hand-rolled-filter')
+  })
+
+  it('does NOT flag a same-named component that is not the Mantine binding', () => {
+    const { code, rules } = run(
+      `${BASALT_IMPORT}import { Select } from './my-select'\nexport const C = () => <PageBar filters={<Select data={[]} />} />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('hand-rolled-filter')
+  })
+
+  it('does NOT flag a bound basalt control in the same slot', () => {
+    const { code, rules } = run(
+      `${BASALT_IMPORT}export const C = () => <PageBar filters={<RangeFilter field={f} />} />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('hand-rolled-filter')
+  })
+
+  // The settled reading of law C1's THIRD home (docs/CONTROLS-SPEC.md §5/§6): a form row keeps
+  // Mantine's `md` tier, so a raw input bound to a setting is right there — and `control` /
+  // `SettingsRow` are absent from the slot set for exactly that reason.
+  it("does NOT flag a raw Select in a SettingsRow's control — the form-row home", () => {
+    const { code, rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => (\n  <SettingsSection title="S">\n    <SettingsRow label="Channel" control={<Select data={[]} />} />\n  </SettingsSection>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('hand-rolled-filter')
+    expect(rules).not.toContain('control-outside-home')
+  })
+
+  it("still flags one in a SettingsSection's actions header slot — that IS tiered", () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => <SettingsSection title="S" actions={<Select data={[]} />} />\n`,
+    )
+    expect(rules).toContain('hand-rolled-filter')
+  })
+
+  it('flags a member tag whose ROOT binding is Mantine (Chip.Group)', () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}import { Chip } from '@mantine/core'\nexport const C = () => <PageBar filters={<Chip.Group multiple />} />\n`,
+    )
+    expect(rules).toContain('hand-rolled-filter')
+  })
+
+  it('honors a scoped theme-allow', () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => (\n  <PageBar\n    filters={\n      // theme-allow hand-rolled-filter — not a store field\n      <Select data={[]} />\n    }\n  />\n)\n`,
+    )
+    expect(rules).not.toContain('hand-rolled-filter')
+  })
+
+  it('honors a theme-allow-file declaration', () => {
+    const { rules } = run(
+      `// theme-allow-file hand-rolled-filter — a legacy page, migrating next sprint\n` +
+        `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => <PageBar filters={<Select data={[]} />} />\n`,
+    )
+    expect(rules).not.toContain('hand-rolled-filter')
+  })
+
+  // Colocating a trigger with its overlay in the slot is how a "create" modal and a "custom range"
+  // popover are written. The overlay's contents portal out of the slot and are already declared
+  // non-homes by `control-outside-home`, so the same code was exempt outside a slot and an `error`
+  // inside one.
+  it('does NOT flag a Select inside a Modal colocated in an actions slot', () => {
+    const { code, rules } = run(
+      `${BASALT_IMPORT}import { Button, Modal, Select } from '@mantine/core'\n` +
+        `export const C = () => (\n  <WidgetHeader\n    actions={\n      <>\n        <Button onClick={open}>New</Button>\n        <Modal opened>\n          <Select data={[]} />\n        </Modal>\n      </>\n    }\n  />\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('hand-rolled-filter')
+  })
+
+  it('does NOT flag one inside a Popover.Dropdown colocated in a filters slot', () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}import { Button, Popover, Select } from '@mantine/core'\n` +
+        `export const C = () => (\n  <Section\n    title="T"\n    filters={\n      <Popover>\n        <Popover.Target>\n          <Button>Custom range</Button>\n        </Popover.Target>\n        <Popover.Dropdown>\n          <Select data={[]} />\n        </Popover.Dropdown>\n      </Popover>\n    }\n  />\n)\n`,
+    )
+    expect(rules).not.toContain('hand-rolled-filter')
+  })
+
+  it('STILL flags a bare sibling Select in the same slot as an exempt overlay', () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}import { Modal, Select } from '@mantine/core'\n` +
+        `export const C = () => (\n  <PageBar\n    filters={\n      <>\n        <Select data={[]} />\n        <Modal opened>\n          <Select data={[]} />\n        </Modal>\n      </>\n    }\n  />\n)\n`,
+    )
+    expect(rules).toContain('hand-rolled-filter')
+  })
+
+  // `Select as MantineSelect` is the canonical way a consumer wraps a Mantine component — the exact
+  // case the provenance comment worried about — and keying membership on the LOCAL name made it
+  // invisible.
+  it('flags an ALIASED Mantine import in a slot', () => {
+    const { code, rules } = run(
+      `${BASALT_IMPORT}import { Select as MantineSelect } from '@mantine/core'\n` +
+        `export const C = () => <PageBar filters={<MantineSelect data={[]} />} />\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('hand-rolled-filter')
+  })
+
+  it('flags a NAMESPACE-imported Mantine control in a slot', () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}import * as M from '@mantine/core'\n` +
+        `export const C = () => <PageBar filters={<M.SegmentedControl data={[]} />} />\n`,
+    )
+    expect(rules).toContain('hand-rolled-filter')
+  })
+
+  it('flags an aliased MEMBER tag (Chip as C → C.Group)', () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}import { Chip as Ch } from '@mantine/core'\n` +
+        `export const C = () => <PageBar filters={<Ch.Group multiple />} />\n`,
+    )
+    expect(rules).toContain('hand-rolled-filter')
+  })
+
+  // `control-outside-home` DOES report this one — a local `Section` is not a home, so the control
+  // has none. Only this rule's silence is asserted; the exit code belongs to that warn.
+  it("does NOT flag a slot on a consumer's own Section — provenance is on the OWNER too", () => {
+    const { rules } = run(
+      `import { Section } from './layout/section'\n${MANTINE_IMPORT}` +
+        `export const C = () => <Section actions={<Select data={[]} />} />\n`,
+    )
+    expect(rules).not.toContain('hand-rolled-filter')
+  })
+})
+
+describe('basalt/control-outside-home', () => {
+  it('flags a raw Mantine Select in no home at all', () => {
+    const { code, rules } = run(
+      `${MANTINE_IMPORT}export const C = () => <div><Select data={[]} /></div>\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('control-outside-home')
+  })
+
+  it('does NOT flag one inside a home slot — that is hand-rolled-filter s business', () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => <PageBar filters={<Select data={[]} />} />\n`,
+    )
+    expect(rules).not.toContain('control-outside-home')
+  })
+
+  it.each(['SettingsRow', 'Modal', 'Drawer', 'Composer'])(
+    'does NOT flag one under a declared non-home (%s)',
+    (host) => {
+      const { rules } = run(
+        `${MANTINE_IMPORT}export const C = () => <${host}><Select data={[]} /></${host}>\n`,
+      )
+      expect(rules).not.toContain('control-outside-home')
+    },
+  )
+
+  it('does NOT flag one under a member-expression non-home (Menu.Dropdown)', () => {
+    const { rules } = run(
+      `${MANTINE_IMPORT}export const C = () => <Menu.Dropdown><Select data={[]} /></Menu.Dropdown>\n`,
+    )
+    expect(rules).not.toContain('control-outside-home')
+  })
+
+  it('does NOT flag anything in a file that imports @mantine/form — a form is the third home', () => {
+    const { code, rules } = run(
+      `${MANTINE_IMPORT}import { useForm } from '@mantine/form'\n` +
+        `export const C = () => <div><Select data={[]} /></div>\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('control-outside-home')
+  })
+
+  // The owner exemption, `hand-rolled-plot`'s shape: the module that IS the bound control cannot be
+  // told to use one.
+  // `shadow-basalt-export` reports the same fixture (a local `ViewTabs` collides with the shipped
+  // one), so only this rule's own silence is asserted — the exit code belongs to that rule.
+  it('does NOT flag the module that DEFINES a basalt control', () => {
+    const { rules } = run(
+      `${MANTINE_IMPORT}export function ViewTabs() {\n  return <SegmentedControl data={[]} />\n}\n`,
+    )
+    expect(rules).not.toContain('control-outside-home')
+  })
+
+  it('flags an ALIASED Mantine import with no home', () => {
+    const { code, rules } = run(
+      `import { Select as MantineSelect } from '@mantine/core'\n` +
+        `export const C = () => <div><MantineSelect data={[]} /></div>\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('control-outside-home')
+  })
+
+  it('flags a NAMESPACE-imported Mantine control with no home', () => {
+    const { rules } = run(
+      `import * as M from '@mantine/core'\n` +
+        `export const C = () => <div><M.SegmentedControl data={[]} /></div>\n`,
+    )
+    expect(rules).toContain('control-outside-home')
+  })
+
+  it('honors a scoped theme-allow', () => {
+    const { rules } = run(
+      `${MANTINE_IMPORT}export const C = () => (\n  <div>\n    {/* theme-allow control-outside-home — a one-off admin picker */}\n    <Select data={[]} />\n  </div>\n)\n`,
+    )
+    expect(rules).not.toContain('control-outside-home')
+  })
+
+  /**
+   * The CROSS-FILE case, exempted by a naming convention rather than by ancestry — argo carried 9 of
+   * these, each a control in a modal/form module whose `<Modal>` is rendered by the parent route.
+   * Nothing in the flagged file can see the host, so the ancestry walk never could have.
+   */
+  describe('the overlay filename convention', () => {
+    const SOURCE = `${MANTINE_IMPORT}export const C = () => <div><Select data={[]} /></div>\n`
+
+    it.each([
+      'src/edit-session-modal.tsx',
+      'src/filters-drawer.tsx',
+      'src/column-popover.tsx',
+      'src/detail-panel.tsx',
+      'src/booking-form.tsx',
+    ])('does NOT flag %s — its host lives in the parent', (filename) => {
+      const { code, rules } = run(SOURCE, filename)
+      expect(code).toBe(0)
+      expect(rules).not.toContain('control-outside-home')
+    })
+
+    it('still flags a plain page module beside them', () => {
+      const { rules } = run(SOURCE, 'src/bookings-page.tsx')
+      expect(rules).toContain('control-outside-home')
+    })
+
+    // Basename only: a directory of modals holds the page pieces around them too, so a whole
+    // `modal/` tree going silent is the version of this exemption that WOULD switch the rule off.
+    it('is a BASENAME convention, not a directory one', () => {
+      const { rules } = run(SOURCE, 'src/modal/session.tsx')
+      expect(rules).toContain('control-outside-home')
+    })
+
+    // `modal.tsx` with no leading segment is a page module in every consumer that has one; the
+    // convention is `<subject>-modal.tsx`, and the regex says so.
+    it('needs the leading subject — a bare modal.tsx is not the convention', () => {
+      const { rules } = run(SOURCE, 'src/modal.tsx')
+      expect(rules).toContain('control-outside-home')
+    })
+  })
+})
+
+describe('basalt/control-size-literal', () => {
+  it.each(['size="xs"', 'w={200}', 'fullWidth', 'visibleFrom="sm"', 'hiddenFrom="sm"'])(
+    'flags %s on an element inside a home slot',
+    (prop) => {
+      const { code, rules } = run(
+        `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => <PageBar actions={<Button ${prop}>Go</Button>} />\n`,
+      )
+      expect(code).toBe(1)
+      expect(rules).toContain('control-size-literal')
+    },
+  )
+
+  it('flags it through a hoisted slot binding too', () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}const acts = <Button size="xs">Go</Button>\n` +
+        `export const C = () => <PageBar actions={acts} />\n`,
+    )
+    expect(rules).toContain('control-size-literal')
+  })
+
+  it("does NOT flag a size prop in a SettingsRow's control — the form tier is Mantine's md", () => {
+    const { code, rules } = run(
+      `${MANTINE_IMPORT}export const C = () => (\n  <SettingsRow label="L" control={<Button size="compact-sm">Go</Button>} />\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('control-size-literal')
+  })
+
+  /**
+   * `ChartCard` is the one slot owner whose slot cannot mount the tier theme — it lives inside the
+   * Mantine-free chart layer, so it writes `data-basalt-tier` by hand and the control there really
+   * does have to state its own size. The rule fires on the `size` ATTRIBUTE and cannot tell a
+   * correct `ctl` from the `xs` it exists to catch, so this is an exemption, not a waiver.
+   */
+  describe('ChartCard.actions — the one slot with no tier theme', () => {
+    it('does NOT flag a size prop there', () => {
+      const { code, rules } = run(
+        `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => <ChartCard title="T" actions={<Button size="ctl">Go</Button>} />
+`,
+      )
+      expect(code).toBe(0)
+      expect(rules).not.toContain('control-size-literal')
+    })
+
+    // The owner test reads the IMPORTED name, so the alias every wrapper writes still resolves.
+    it('does NOT flag it under an aliased ChartCard import', () => {
+      const { rules } = run(
+        `import { ChartCard as Card } from 'basalt-ui'
+${MANTINE_IMPORT}` +
+          `export const C = () => <Card title="T" actions={<Button size="xs">Go</Button>} />
+`,
+      )
+      expect(rules).not.toContain('control-size-literal')
+    })
+
+    // The positive control: every OTHER home does mount the theme, so the rule still fires there.
+    it('STILL flags the same prop in a Section slot', () => {
+      const { code, rules } = run(
+        `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => <Section title="T" actions={<Button size="xs">Go</Button>} />
+`,
+      )
+      expect(code).toBe(1)
+      expect(rules).toContain('control-size-literal')
+    })
+
+    // The exemption is keyed on the OWNER, and one hoisted binding can be handed to several — so it
+    // holds only when EVERY home it reached is tierless. A last-writer-wins owner map made the
+    // verdict depend on which attribute came later in the file: same code, opposite answer.
+    it('STILL flags a hoisted binding shared with a Section slot — ChartCard last', () => {
+      const { rules } = run(
+        `${BASALT_IMPORT}${MANTINE_IMPORT}const acts = <Button size="xs">Go</Button>\n` +
+          `export const C = () => (\n  <>\n    <Section title="S" actions={acts} />\n    <ChartCard title="T" actions={acts} />\n  </>\n)\n`,
+      )
+      expect(rules).toContain('control-size-literal')
+    })
+
+    it('STILL flags a hoisted binding shared with a Section slot — ChartCard first', () => {
+      const { rules } = run(
+        `${BASALT_IMPORT}${MANTINE_IMPORT}const acts = <Button size="xs">Go</Button>\n` +
+          `export const C = () => (\n  <>\n    <ChartCard title="T" actions={acts} />\n    <Section title="S" actions={acts} />\n  </>\n)\n`,
+      )
+      expect(rules).toContain('control-size-literal')
+    })
+
+    it('does NOT flag a hoisted binding handed only to ChartCard', () => {
+      const { code, rules } = run(
+        `${BASALT_IMPORT}${MANTINE_IMPORT}const acts = <Button size="ctl">Go</Button>\n` +
+          `export const C = () => <ChartCard title="T" actions={acts} />\n`,
+      )
+      expect(code).toBe(0)
+      expect(rules).not.toContain('control-size-literal')
+    })
+
+    // A consumer's OWN `ChartCard` is not basalt's, so it is not a home at all and nothing fires —
+    // the same provenance rule every other home tag follows.
+    it('hand-rolled-filter is NOT exempted there — the tier is not what makes a filter wrong', () => {
+      const { rules } = run(
+        `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => <ChartCard title="T" actions={<Select data={[]} />} />
+`,
+      )
+      expect(rules).toContain('hand-rolled-filter')
+    })
+  })
+
+  it('does NOT flag a size prop on the HOME itself', () => {
+    const { code, rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => <PageBar w={200} actions={<Button>Go</Button>} />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('control-size-literal')
+  })
+
+  it("does NOT flag a size prop in a Section's CHILDREN", () => {
+    const { code, rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => (\n  <Section title="T">\n    <Button size="xs">Go</Button>\n  </Section>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('control-size-literal')
+  })
+
+  // The rule only reaches what the slot's own MantineThemeProvider re-tiers. An icon's `size` IS
+  // its only sizing API and the slot theme cannot touch an SVG, so "drop the prop" produced a 24px
+  // icon — on the shape the spec's own reference example writes.
+  it("does NOT flag an icon's size inside a slot — the slot theme cannot size an SVG", () => {
+    const { code, rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}import { IconDownload } from '@tabler/icons-react'\n` +
+        `export const C = () => (\n  <PageBar actions={<Button leftSection={<IconDownload size={14} />}>Export</Button>} />\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('control-size-literal')
+  })
+
+  it('does NOT flag a Badge or Loader size in a Section actions slot', () => {
+    const { code, rules } = run(
+      `${BASALT_IMPORT}import { Badge, Loader } from '@mantine/core'\n` +
+        `export const C = ({ n, busy }) => (\n  <Section title="T" actions={[<Badge key="c" size="sm">{n}</Badge>, busy ? <Loader key="l" size={14} /> : null]} />\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('control-size-literal')
+  })
+
+  it("does NOT flag a Modal's own size, or an input's size inside that Modal", () => {
+    const { code, rules } = run(
+      `${BASALT_IMPORT}import { Button, Modal, TextInput } from '@mantine/core'\n` +
+        `export const C = () => (\n  <WidgetHeader\n    actions={\n      <>\n        <Button>New</Button>\n        <Modal opened size="lg">\n          <TextInput size="md" />\n        </Modal>\n      </>\n    }\n  />\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('control-size-literal')
+  })
+
+  it('STILL flags a raw filter size in the slot beside those exemptions', () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => (\n  <PageBar filters={<Select size="xs" data={[]} />} />\n)\n`,
+    )
+    expect(rules).toContain('control-size-literal')
+  })
+
+  it('flags an ALIASED Mantine Button size in a slot', () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}import { Button as Btn } from '@mantine/core'\n` +
+        `export const C = () => <PageBar actions={<Btn size="xs">Go</Btn>} />\n`,
+    )
+    expect(rules).toContain('control-size-literal')
+  })
+
+  it("does NOT flag a size prop in a slot on a consumer's own Section", () => {
+    const { code, rules } = run(
+      `import { Section } from './layout/section'\n${MANTINE_IMPORT}` +
+        `export const C = () => <Section actions={<Button size="sm">Go</Button>} />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('control-size-literal')
+  })
+
+  it('honors a scoped theme-allow', () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => (\n  <PageBar\n    actions={\n      <Button\n        // theme-allow control-size-literal — a deliberate 24px tag\n        size="xs"\n      >\n        Go\n      </Button>\n    }\n  />\n)\n`,
+    )
+    expect(rules).not.toContain('control-size-literal')
+  })
+})
+
+// `control-size-literal`'s scope is a copy of the theme's own re-tiering list, because a plain-JS
+// plugin shipped to consumers cannot import Mantine-coupled TS. This is the pin that makes the copy
+// safe: a component added to (or dropped from) CTL_THEME without the rule following is a rule
+// telling someone to drop a prop nothing else sets — or silently ignoring one that matters.
+describe('CTL_THEME_TAGS ↔ CTL_THEME', () => {
+  it('is exactly the component map the slot theme re-tiers', () => {
+    expect([...(CTL_THEME_TAGS as Set<string>)].toSorted()).toEqual(
+      Object.keys(CTL_THEME.components ?? {}).toSorted(),
+    )
+  })
+})
+
+describe('basalt/page-bar-budget', () => {
+  it('flags two PageBars in the SAME returned tree — the pair that mounts together', () => {
+    const { code, rules } = run(
+      `${BASALT_IMPORT}export const C = () => (\n  <>\n    <PageBar title="A" />\n    <PageBar title="B" />\n  </>\n)\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('page-bar-budget')
+  })
+
+  // The two false positives the per-FILE count produced. Neither renders two bars at once, so
+  // nothing races for the portal node — and the only escape was a theme-allow on correct code.
+  it('does NOT flag an early-return loading state and the loaded bar', () => {
+    const { code, rules } = run(
+      `${BASALT_IMPORT}export const C = ({ data }) => {\n  if (!data) return <PageBar title="Jobs" />\n  return <PageBar title="Jobs" actions={{ primary: { key: 'r', label: 'Run' } }} />\n}\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('page-bar-budget')
+  })
+
+  it('does NOT flag two page components exported from one file', () => {
+    const { code, rules } = run(
+      `${BASALT_IMPORT}export const ListPage = () => <PageBar title="Jobs" />\nexport const DetailPage = () => <PageBar title="Job" />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('page-bar-budget')
+  })
+
+  it("does NOT flag a consumer's own PageBar-named component", () => {
+    const { code, rules } = run(
+      `import { PageBar } from './chrome/page-bar'\nexport const C = () => (\n  <>\n    <PageBar title="A" />\n    <PageBar title="B" />\n  </>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('page-bar-budget')
+  })
+
+  it('flags a 5-entry actions.secondary array', () => {
+    const five = [1, 2, 3, 4, 5].map((n) => `{ key: '${n}', label: '${n}' }`).join(', ')
+    const { code, rules } = run(
+      `${BASALT_IMPORT}export const C = () => <PageBar actions={{ secondary: [${five}] }} />\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('page-bar-budget')
+  })
+
+  it('does NOT flag a 4-entry actions.secondary array', () => {
+    const four = [1, 2, 3, 4].map((n) => `{ key: '${n}', label: '${n}' }`).join(', ')
+    const { code, rules } = run(
+      `${BASALT_IMPORT}export const C = () => <PageBar actions={{ secondary: [${four}] }} />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('page-bar-budget')
+  })
+
+  it('flags a 4-entry Section actions array (budget 3)', () => {
+    const four = [1, 2, 3, 4].map((n) => `{ key: '${n}', label: '${n}' }`).join(', ')
+    const { rules } = run(
+      `${BASALT_IMPORT}export const C = () => <Section actions={[${four}]} />\n`,
+    )
+    expect(rules).toContain('page-bar-budget')
+  })
+
+  it('flags a second variant="filled" inside one slot', () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => (\n  <PageBar actions={<><Button variant="filled">A</Button><Button variant="filled">B</Button></>} />\n)\n`,
+    )
+    expect(rules).toContain('page-bar-budget')
+  })
+
+  it('does NOT flag one filled action beside a default one', () => {
+    const { code, rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => (\n  <PageBar actions={<><Button variant="filled">A</Button><Button variant="default">B</Button></>} />\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('page-bar-budget')
+  })
+
+  // The `filled` count is a PRIMARY-ACTION count: a filled Badge is Mantine's default Badge
+  // variant and the ordinary way a header states a count (law C11 asks for one), and an overlay's
+  // submit button is not in the bar at all.
+  it('does NOT flag a filled Badge beside the one filled Button', () => {
+    const { code, rules } = run(
+      `${BASALT_IMPORT}import { Badge, Button } from '@mantine/core'\n` +
+        `export const C = () => (\n  <Section title="T" actions={<><Button variant="filled">Run</Button><Badge variant="filled">3</Badge></>} />\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('page-bar-budget')
+  })
+
+  it('does NOT flag a filled ThemeIcon beside the one filled Button', () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}import { Button, ThemeIcon } from '@mantine/core'\n` +
+        `export const C = () => (\n  <Section title="T" actions={<><Button variant="filled">Run</Button><ThemeIcon variant="filled" /></>} />\n)\n`,
+    )
+    expect(rules).not.toContain('page-bar-budget')
+  })
+
+  it("does NOT flag a Modal's own filled submit button colocated in the slot", () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}import { Button, Modal } from '@mantine/core'\n` +
+        `export const C = () => (\n  <PageBar actions={<><Button variant="filled">New</Button><Modal opened><Button variant="filled">Save</Button></Modal></>} />\n)\n`,
+    )
+    expect(rules).not.toContain('page-bar-budget')
+  })
+
+  it('honors a scoped theme-allow', () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}export const C = () => (\n  <>\n    <PageBar title="A" />\n    {/* theme-allow page-bar-budget — the print-only variant */}\n    <PageBar title="B" />\n  </>\n)\n`,
+    )
+    expect(rules).not.toContain('page-bar-budget')
+  })
+})
+
+describe('basalt/in-body-page-title', () => {
+  it.each([1, 2])('flags <Title order={%i}> in the body', (order) => {
+    const { code, rules } = run(`export const C = () => <Title order={${order}}>Page</Title>\n`)
+    expect(code).toBe(1)
+    expect(rules).toContain('in-body-page-title')
+  })
+
+  it('does NOT flag order={3} — a section heading', () => {
+    const { code, rules } = run(`export const C = () => <Title order={3}>Section</Title>\n`)
+    expect(code).toBe(0)
+    expect(rules).not.toContain('in-body-page-title')
+  })
+
+  it.each(['Prose', 'ArticleLayout', 'Modal', 'Drawer'])(
+    'does NOT flag one under %s — that is a document heading',
+    (host) => {
+      const { rules } = run(
+        `export const C = () => <${host}><Title order={1}>Doc</Title></${host}>\n`,
+      )
+      expect(rules).not.toContain('in-body-page-title')
+    },
+  )
+
+  it('does NOT flag one under a content/ path segment', () => {
+    const { code, rules } = run(
+      `export const C = () => <Title order={1}>Doc</Title>\n`,
+      'content/page.tsx',
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('in-body-page-title')
+  })
+
+  it('honors a scoped theme-allow', () => {
+    const { rules } = run(
+      `// theme-allow in-body-page-title — a shell-less print view\nexport const C = () => <Title order={1}>Page</Title>\n`,
+    )
+    expect(rules).not.toContain('in-body-page-title')
+  })
+})
+
+describe('basalt/responsive-twin', () => {
+  it('flags the same control mounted under visibleFrom and hiddenFrom', () => {
+    const { code, rules } = run(
+      `export const C = () => (\n  <div>\n    <SegmentedControl visibleFrom="sm" data={[]} />\n    <SegmentedControl hiddenFrom="sm" data={[]} />\n  </div>\n)\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('responsive-twin')
+  })
+
+  it('flags it when the control sits inside each half rather than being it', () => {
+    const { rules } = run(
+      `export const C = () => (\n  <div>\n    <Group visibleFrom="sm"><ViewTabs field={f} /></Group>\n    <Stack hiddenFrom="sm"><ViewTabs field={f} /></Stack>\n  </div>\n)\n`,
+    )
+    expect(rules).toContain('responsive-twin')
+  })
+
+  it('does NOT flag two halves on DIFFERENT breakpoints', () => {
+    const { code, rules } = run(
+      `export const C = () => (\n  <div>\n    <SegmentedControl visibleFrom="sm" data={[]} />\n    <SegmentedControl hiddenFrom="md" data={[]} />\n  </div>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('responsive-twin')
+  })
+
+  it('does NOT flag a pair holding DIFFERENT controls', () => {
+    const { rules } = run(
+      `export const C = () => (\n  <div>\n    <SegmentedControl visibleFrom="sm" data={[]} />\n    <Select hiddenFrom="sm" data={[]} />\n  </div>\n)\n`,
+    )
+    expect(rules).not.toContain('responsive-twin')
+  })
+
+  // Same fixture caveat as control-outside-home's owner test: the local `ViewTabs` name is itself a
+  // `shadow-basalt-export` finding, so only this rule's silence is asserted.
+  it('does NOT flag the module that DEFINES a basalt control — the CSS swap lives there', () => {
+    const { rules } = run(
+      `export function ViewTabs() {\n  return (\n    <div>\n      <SegmentedControl visibleFrom="sm" data={[]} />\n      <SegmentedControl hiddenFrom="sm" data={[]} />\n    </div>\n  )\n}\n`,
+    )
+    expect(rules).not.toContain('responsive-twin')
+  })
+
+  it('honors a scoped theme-allow', () => {
+    const { rules } = run(
+      `export const C = () => (\n  <div>\n    <SegmentedControl visibleFrom="sm" data={[]} />\n    {/* theme-allow responsive-twin — two genuinely different data sets */}\n    <SegmentedControl hiddenFrom="sm" data={[]} />\n  </div>\n)\n`,
+    )
+    expect(rules).not.toContain('responsive-twin')
+  })
+})
+
+describe('basalt/search-literal-link', () => {
+  const NAV = (search: string) =>
+    `export const nav = defineNav({\n  sections: [\n    { id: 'a', label: 'A', link: linkOptions({ to: '/dashboard'${search} }) },\n  ],\n})\n`
+
+  it('flags a `search` object literal inside defineNav', () => {
+    const { code, rules } = run(NAV(", search: { window: '30d' }"), 'nav.ts')
+    expect(code).toBe(1)
+    expect(rules).toContain('search-literal-link')
+  })
+
+  it('flags it inside navGroup too', () => {
+    const { rules } = run(
+      `export const g = navGroup({ id: 'g', label: 'G' }, [\n  { id: 'x', label: 'X', link: linkOptions({ to: '/d', search: { window: '30d' } }) },\n])\n`,
+      'nav.ts',
+    )
+    expect(rules).toContain('search-literal-link')
+  })
+
+  it('does NOT flag `search: store.linkSearch` passed by reference', () => {
+    const { code, rules } = run(NAV(', search: dashboardFilters.linkSearch'), 'nav.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('search-literal-link')
+  })
+
+  it('does NOT flag a linkOptions literal OUTSIDE a nav definition', () => {
+    const { code, rules } = run(
+      `export const target = linkOptions({ to: '/d', search: { window: '30d' } })\n`,
+      'nav.ts',
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('search-literal-link')
+  })
+
+  it('honors a scoped theme-allow', () => {
+    const { rules } = run(
+      `export const nav = defineNav({\n  sections: [\n    {\n      id: 'a',\n      label: 'A',\n      link: linkOptions({\n        to: '/d',\n        // theme-allow search-literal-link — a fixed report link, deliberately pinned\n        search: { window: '30d' },\n      }),\n    },\n  ],\n})\n`,
+      'nav.ts',
+    )
+    expect(rules).not.toContain('search-literal-link')
+  })
+})
+
+describe('basalt/use-search-from-literal', () => {
+  it('flags useSearch({ from: <literal> })', () => {
+    const { code, rules } = run(
+      `export const useRange = () => useSearch({ from: '/dashboard' })\n`,
+      'hooks.ts',
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('use-search-from-literal')
+  })
+
+  it('does NOT flag useSearch({ strict: false })', () => {
+    const { code, rules } = run(
+      `export const useRange = () => useSearch({ strict: false })\n`,
+      'hooks.ts',
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('use-search-from-literal')
+  })
+
+  it('honors a scoped theme-allow', () => {
+    const { rules } = run(
+      `export const useRange = () =>\n  useSearch({\n    // theme-allow use-search-from-literal — a route-owned loader, never rendered elsewhere\n    from: '/dashboard',\n  })\n`,
+      'hooks.ts',
+    )
+    expect(rules).not.toContain('use-search-from-literal')
+  })
+})
+
+// ── raw-scroll-container — the C7 widening ───────────────────────────────────
+
+describe('basalt/raw-scroll-container — the home widening (C7)', () => {
+  it('flags overflowX inside a home slot', () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}export const C = () => <PageBar filters={<div style={{ overflowX: 'auto' }} />} />\n`,
+    )
+    expect(rules).toContain('raw-scroll-container')
+  })
+
+  // The C7 widening is about a sideways-scrolling row of CONTROLS, which only ever lives in a slot.
+  // Counting the body made every wide table and every horizontally scrolling code block on a page
+  // an `error` carrying that message — the exact pattern this rule's own comment calls legitimate.
+  it('does NOT flag overflowX in a Section BODY — page content, not a control row', () => {
+    const { code, rules } = run(
+      `${BASALT_IMPORT}export const C = () => (\n  <Section title="Raw rows">\n    <div style={{ overflowX: 'scroll' }}>\n      <table />\n    </div>\n  </Section>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('raw-scroll-container')
+  })
+
+  it('does NOT flag <ScrollArea scrollbars="x"> around a wide table in a ChartCard body', () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => (\n  <ChartCard title="T">\n    <ScrollArea scrollbars="x">\n      <table />\n    </ScrollArea>\n  </ChartCard>\n)\n`,
+    )
+    expect(rules).not.toContain('raw-scroll-container')
+  })
+
+  it("does NOT flag a slot on a consumer's own Section — not a basalt home", () => {
+    const { code, rules } = run(
+      `import { Section } from './layout/section'\n${MANTINE_IMPORT}` +
+        `export const C = () => <Section actions={<ScrollArea scrollbars="x" />} />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('raw-scroll-container')
+  })
+
+  it("does NOT flag a consumer's own ScrollArea in a basalt slot", () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}import { ScrollArea } from './ui/scroll-area'\n` +
+        `export const C = () => <PageBar filters={<ScrollArea scrollbars="x" />} />\n`,
+    )
+    expect(rules).not.toContain('raw-scroll-container')
+  })
+
+  it('flags <ScrollArea scrollbars="x"> inside a home slot', () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => <PageBar filters={<ScrollArea scrollbars="x" />} />\n`,
+    )
+    expect(rules).toContain('raw-scroll-container')
+  })
+
+  // The original doctrine, unchanged: a horizontal bar outside a home reserves no gutter width, so
+  // a code block or a pinned-column table stays its own legitimate pattern.
+  it('does NOT flag overflowX outside a home', () => {
+    const { code, rules } = run(`const s = { overflowX: 'auto' }\n`, 'lib.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('raw-scroll-container')
+  })
+
+  it('does NOT flag <ScrollArea scrollbars="x"> outside a home', () => {
+    const { code, rules } = run(
+      `${MANTINE_IMPORT}export const C = () => <ScrollArea scrollbars="x" />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('raw-scroll-container')
+  })
+
+  it('honors a scoped theme-allow on the widened half', () => {
+    const { rules } = run(
+      `${BASALT_IMPORT}export const C = () => (\n  <Section\n    title="T"\n    actions={\n      // theme-allow raw-scroll-container — a pinned-column table owns its own scroll node\n      <div style={{ overflowX: 'auto' }} />\n    }\n  />\n)\n`,
+    )
+    expect(rules).not.toContain('raw-scroll-container')
+  })
+})
+
+// ── shadow-basalt-export — the rename table ──────────────────────────────────
+
+describe('basalt/shadow-basalt-export — SHADOW_ALIASES', () => {
+  it.each([
+    ['PageHeader', 'PageBar'],
+    ['WindowSelector', 'RangeFilter'],
+    ['SectionTitle', 'Section'],
+    ['RefreshButton', 'SyncButton'],
+    ['HeroCard', 'StatCard'],
+  ])('flags a local %s and names %s as what it forks', (local, canonical) => {
+    const { code, rules, output } = run(`export function ${local}() {\n  return null\n}\n`)
+    expect(code).toBe(1)
+    expect(rules).toContain('shadow-basalt-export')
+    expect(output).toContain(canonical)
+  })
+
+  it('flags the const form too', () => {
+    const { rules } = run(`export const FilterBar = () => null\n`)
+    expect(rules).toContain('shadow-basalt-export')
+  })
+
+  it('does NOT flag a name that is neither an export nor an alias', () => {
+    const { code, rules } = run(`export const RangePickerish = () => null\n`)
+    expect(code).toBe(0)
+    expect(rules).not.toContain('shadow-basalt-export')
+  })
+
+  it('is waivable with a scoped theme-allow', () => {
+    const { rules } = run(
+      `// theme-allow shadow-basalt-export — a marketing hero, unrelated to StatCard\nexport const HeroCard = () => null\n`,
+    )
+    expect(rules).not.toContain('shadow-basalt-export')
+  })
+})
+
+/**
+ * The provenance half of the alias table: a file that COMPOSES the export it renames is a wrapper,
+ * not a fork. argo's three hero cards each imported `StatCard`, wrapped it, and each took a warn
+ * telling them to import the thing they were already importing.
+ *
+ * Both directions are asserted, because the exemption is only worth having if the rule still fires
+ * WITHOUT the import — a wrapper is evidence, and silence on every `HeroCard` in the repo would be
+ * the rule switching itself off.
+ */
+describe('basalt/shadow-basalt-export — an alias that composes what it renames', () => {
+  it('fires on a HeroCard that does not import StatCard', () => {
+    const { rules, output } = run(
+      `export function HeroCard() {\n  return null\n}\n`,
+      'src/hero-card.tsx',
+    )
+    expect(rules).toContain('shadow-basalt-export')
+    expect(output).toContain('StatCard')
+  })
+
+  it('is silent on a HeroCard that composes the imported StatCard', () => {
+    const { code, rules } = run(
+      `import { StatCard } from 'basalt-ui'\n` +
+        `export function HeroCard() {\n  return <StatCard title="x" value="1" />\n}\n`,
+      'src/hero-card.tsx',
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('shadow-basalt-export')
+  })
+
+  // The provenance test reads the IMPORTED name, not the local one — `StatCard as BaseStatCard` is
+  // the canonical way a wrapper avoids shadowing its own import, and a local-name set would answer
+  // `BaseStatCard` and miss it.
+  it('is silent when the composed export is imported under an alias', () => {
+    const { rules } = run(
+      `import { StatCard as BaseStatCard } from 'basalt-ui'\n` +
+        `export function HeroCard() {\n  return <BaseStatCard title="x" value="1" />\n}\n`,
+      'src/hero-card.tsx',
+    )
+    expect(rules).not.toContain('shadow-basalt-export')
+  })
+
+  it('is silent from a basalt SUBPATH too, not just the root barrel', () => {
+    const { rules } = run(
+      `import { RangeFilter } from 'basalt-ui/controls'\n` +
+        `export function WindowSelector() {\n  return <RangeFilter field={{}} />\n}\n`,
+      'src/window-selector.tsx',
+    )
+    expect(rules).not.toContain('shadow-basalt-export')
+  })
+
+  // Importing SOMETHING from basalt is not the exemption — importing the thing you renamed is.
+  it('still fires when the file imports a DIFFERENT basalt export', () => {
+    const { rules } = run(
+      `import { Section } from 'basalt-ui'\n` +
+        `export function HeroCard() {\n  return <Section title="x" />\n}\n`,
+      'src/hero-card.tsx',
+    )
+    expect(rules).toContain('shadow-basalt-export')
+  })
+
+  // The COLLISION half is deliberately not exempted: a local `StatCard` beside an
+  // `import { StatCard as Base }` kept the name AND a piece of the original, which is the fork
+  // shape this rule most wants to see.
+  it('still fires on a name COLLISION even when the export is imported under an alias', () => {
+    const { rules } = run(
+      `import { StatCard as Base } from 'basalt-ui'\n` +
+        `export function StatCard() {\n  return <Base title="x" value="1" />\n}\n`,
+      'src/stat-card.tsx',
+    )
+    expect(rules).toContain('shadow-basalt-export')
+  })
+
+  // COMPOSITION, not import. A type-only import is erased at compile time, so the shape a
+  // props-copying fork actually writes — `ComponentProps<typeof StatCard>` off an
+  // `import type` — composes nothing and used to exempt the whole file.
+  it('still fires on a type-only import of the export it renames', () => {
+    const { rules } = run(
+      `import type { StatCard } from 'basalt-ui'\n` +
+        `export function HeroCard() {\n  return <div />\n}\n`,
+      'src/hero-card.tsx',
+    )
+    expect(rules).toContain('shadow-basalt-export')
+  })
+
+  it('still fires on an inline `type` specifier', () => {
+    const { rules } = run(
+      `import { type StatCard } from 'basalt-ui'\n` +
+        `export function HeroCard() {\n  return <div />\n}\n`,
+      'src/hero-card.tsx',
+    )
+    expect(rules).toContain('shadow-basalt-export')
+  })
+
+  // `typeof StatCard` is a `TSTypeQuery` around a plain Identifier, so a VALUE import used only in
+  // a type position has to be rejected too — otherwise the props-copying fork just drops `type`.
+  it('still fires when a value import is only used in a type position', () => {
+    const { rules } = run(
+      `import { StatCard } from 'basalt-ui'\n` +
+        `type P = { card: typeof StatCard }\n` +
+        `export function HeroCard(props: P) {\n  return <div>{String(props)}</div>\n}\n`,
+      'src/hero-card.tsx',
+    )
+    expect(rules).toContain('shadow-basalt-export')
+  })
+
+  it('still fires on a dead import left behind after the body was re-rolled', () => {
+    const { rules } = run(
+      `import { StatCard } from 'basalt-ui'\n` +
+        `export function HeroCard() {\n  return <div />\n}\n`,
+      'src/hero-card.tsx',
+    )
+    expect(rules).toContain('shadow-basalt-export')
+  })
+
+  // A JSX tag is not the only way to compose: a wrapper that hands the component on as a prop or to
+  // `createElement` composes it just as much, and a JSX-only test would report both.
+  it('is silent when the import is passed on as a prop rather than rendered', () => {
+    const { code, rules } = run(
+      `import { StatCard } from 'basalt-ui'\n` +
+        `export function HeroCard() {\n  return <Slot component={StatCard} />\n}\n`,
+      'src/hero-card.tsx',
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('shadow-basalt-export')
+  })
+})
+
+// ── SURFACES ↔ the plugin registry ───────────────────────────────────────────
+
+describe('PLUGIN_RULE_ID_LIST ↔ the plugin', () => {
+  // surfaces.ts cannot import the plugin (it is dependency-free by contract, and the plugin is a
+  // standalone .js loaded out of a consumer's node_modules), so the list is hand-maintained and
+  // THIS is the gate that keeps it honest.
+  it('is exactly the plugin s registered rule ids', () => {
+    expect([...PLUGIN_RULE_ID_LIST].toSorted()).toEqual(Object.keys(basaltPlugin.rules).toSorted())
+  })
+
+  it('maps every plugin rule to exactly one surface', () => {
+    const owners = new Map<string, string[]>()
+    for (const [key, spec] of Object.entries(SURFACES)) {
+      if (spec.kind !== 'doctrine') continue
+      for (const id of spec.pluginRules) owners.set(id, [...(owners.get(id) ?? []), key])
+    }
+    for (const id of PLUGIN_RULE_ID_LIST) {
+      expect([id, owners.get(id)?.length ?? 0]).toEqual([id, 1])
+    }
+    // …and no surface claims an id the plugin does not register (the type already forbids it; this
+    // catches a list entry deleted without its surface).
+    for (const id of owners.keys()) {
+      expect([id, (PLUGIN_RULE_ID_LIST as readonly string[]).includes(id)]).toEqual([id, true])
+    }
+  })
+
+  it("puts the shell rule on the root barrel's surface (wave 6)", () => {
+    expect(SURFACES['.'].pluginRules).toContain('hand-rolled-shell')
+  })
+
+  it('gives ./controls the control-tier rules', () => {
+    expect([...SURFACES['./controls'].pluginRules].toSorted()).toEqual([
+      'control-outside-home',
+      'control-size-literal',
+      'hand-rolled-filter',
+      'responsive-twin',
+    ])
+  })
+})