basalt-ui 1.26.0 → 1.28.0

package/configs/oxlint-plugin.test.ts

@@ -14,6 +14,7 @@ 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, {
   CTL_THEME_TAGS,
+  DEPRECATED_EXPORTS,
   KNOWN_RULE_IDS,
   PLUGIN_RULE_ADVISORY,
   PLUGIN_RULE_GRACE,
@@ -35,7 +36,14 @@ beforeEach(() => {
       plugins: [],
       jsPlugins: [PLUGIN_PATH],
       rules: {
+        'basalt/provider-above-router': 'error',
+        'basalt/duplicate-notifications-mount': 'error',
+        'basalt/query-dual-import': 'error',
+        'basalt/query-fn-unwrap': 'error',
+        'basalt/deprecated-export': 'error',
+        'basalt/forms-field-key': 'error',
         'basalt/no-raw-font-size': 'error',
+        'basalt/raw-size-literal': 'error',
         'basalt/card-inset': 'error',
         'basalt/chart-in-raw-surface': 'error',
         'basalt/hand-rolled-plot': 'error',
@@ -45,6 +53,7 @@ beforeEach(() => {
         'basalt/raw-scroll-container': 'error',
         'basalt/hand-rolled-filter': 'error',
         'basalt/control-outside-home': 'error',
+        'basalt/bound-control-outside-home': 'error',
         'basalt/control-size-literal': 'error',
         'basalt/page-bar-budget': 'error',
         'basalt/in-body-page-title': 'error',
@@ -111,6 +120,76 @@ describe('basalt/no-raw-font-size', () => {
     expect(code).toBe(0)
     expect(rules).not.toContain('no-raw-font-size')
   })
+
+  // F25: symmetric with raw-size-literal's own test-file skip below — the doctrine is about
+  // shipped UI, not fixtures.
+  it('does NOT flag a numeric fz inside a *.test.tsx file', () => {
+    const { code, rules } = run(`export const C = () => <Text fz={10}>a</Text>\n`, 'lib.test.tsx')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('no-raw-font-size')
+  })
+})
+
+// ── raw-size-literal ─────────────────────────────────────────────────────────
+
+describe('basalt/raw-size-literal', () => {
+  it('flags a CSS-length string on size', () => {
+    const { code, rules } = run(`export const C = () => <ThemeIcon size="2rem" />\n`)
+    expect(code).toBe(1)
+    expect(rules).toContain('raw-size-literal')
+  })
+
+  it('flags a CSS-length string on fz', () => {
+    const { code, rules } = run(`export const C = () => <Text fz="0.8rem">a</Text>\n`)
+    expect(code).toBe(1)
+    expect(rules).toContain('raw-size-literal')
+  })
+
+  it('does NOT flag a scale token on size', () => {
+    const { code, rules } = run(`export const C = () => <ThemeIcon size="md" />\n`)
+    expect(code).toBe(0)
+    expect(rules).not.toContain('raw-size-literal')
+  })
+
+  it('does NOT flag a numeric size (the documented icon-dimension idiom)', () => {
+    const { code, rules } = run(`export const C = () => <ThemeIcon size={32} />\n`)
+    expect(code).toBe(0)
+    expect(rules).not.toContain('raw-size-literal')
+  })
+
+  it('does NOT flag with a same-line theme-allow comment', () => {
+    const { code, rules } = run(
+      `export const C = () => <Text fz="0.8rem" /* theme-allow: legacy */>a</Text>\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('raw-size-literal')
+  })
+
+  // F25: was the asymmetric half — no-raw-font-size already skipped test files, this rule did not.
+  it('does NOT flag a CSS-length string inside a *.test.tsx file', () => {
+    const { code, rules } = run(
+      `export const C = () => <Text fz="0.8rem">a</Text>\n`,
+      'lib.test.tsx',
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('raw-size-literal')
+  })
+
+  // A3: the /src/tokens/ exemption used to be a bare path-substring check, then a check gated on
+  // `isBasaltScopedFile` — but that predicate tests "does the nearest package.json depend on
+  // basalt-ui", not "is this file basalt's own", so a CONSUMER package that merely depends on
+  // basalt-ui could still put raw literals under its own `src/tokens/` and silence the rule. The
+  // exemption is deleted outright rather than re-gated on package identity: both rules only ever
+  // visit JSX, and basalt's real `src/tokens/**` is pure `.ts` data with none, so no gate was ever
+  // load-bearing there. A `src/tokens/` path — basalt's own or a consumer's — now always fires.
+  it('DOES flag a CSS-length string inside a src/tokens/ file (no path exemption)', () => {
+    const { code, rules } = run(
+      `export const C = () => <ThemeIcon size="2rem" />\n`,
+      'src/tokens/palette.tsx',
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('raw-size-literal')
+  })
 })
 
 // ── card-inset ───────────────────────────────────────────────────────────────
@@ -1296,6 +1375,30 @@ describe('PLUGIN_RULE_GRACE', () => {
   it('passes the C16 gate against the real ledger and package version', () => {
     expect(() => assertGraceLedger(Object.fromEntries(graceEntries), pkgVersion)).not.toThrow()
   })
+
+  // F27: a grace entry is written for a rule that lands in the NEXT release, so its `since` can sit
+  // one minor ahead of `package.json`'s current version (`bound-control-outside-home` at 1.28.0
+  // while the published version still reads 1.27.0, exactly like `control-outside-home` before it).
+  // What this catches is a `since` that is malformed or planted further out than that — a value
+  // static analysis has no way to verify is "the version this actually ships in", so the bound this
+  // test enforces is the one thing that IS checkable: well-formed semver, no more than one minor
+  // past what is currently published.
+  it("every grace entry's since is valid semver, at most one minor past the published version", () => {
+    const SEMVER = /^\d+\.\d+\.\d+$/
+    const [major, minor] = pkgVersion.split('.').map(Number)
+    const nextMinorCeiling = `${major}.${minor + 1}.0`
+    for (const [id, entry] of graceEntries) {
+      if (!SEMVER.test(entry.since)) {
+        throw new Error(`${id}: \`since\` (${entry.since}) is not valid semver.`)
+      }
+      if (compareSemver(entry.since, nextMinorCeiling) > 0) {
+        throw new Error(
+          `${id}: \`since\` (${entry.since}) is more than one minor past the published version ` +
+            `${pkgVersion}.`,
+        )
+      }
+    }
+  })
 })
 
 // ── chart-legend-literal: the .map() half ────────────────────────────────────
@@ -1681,6 +1784,28 @@ describe('basalt/control-outside-home', () => {
     },
   )
 
+  // FormRow/FormGroup (`basalt-ui/forms`) are law C1's third home written for a `<form>` rather
+  // than a settings page — the same non-home treatment SettingsRow gets, via the same
+  // CONTROL_HOST_TAGS ancestry walk.
+  it.each(['FormRow', 'FormGroup'])(
+    'does NOT flag a raw Select nested inside a %s imported from basalt-ui/forms',
+    (host) => {
+      const { code, rules } = run(
+        `import { ${host} } from 'basalt-ui/forms'\n${MANTINE_IMPORT}` +
+          `export const C = () => <${host} label="L"><Select data={[]} /></${host}>\n`,
+      )
+      expect(code).toBe(0)
+      expect(rules).not.toContain('control-outside-home')
+    },
+  )
+
+  it('still flags a bare Select in a page body with no FormRow/FormGroup around it', () => {
+    const { rules } = run(
+      `${MANTINE_IMPORT}export const C = () => <div><Select data={[]} /></div>\n`,
+    )
+    expect(rules).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`,
@@ -1708,6 +1833,58 @@ describe('basalt/control-outside-home', () => {
     expect(rules).not.toContain('control-outside-home')
   })
 
+  /**
+   * The exemption's SECOND half. `CONTROL_OWNER_NAMES` carries generic names (`PanelRow`,
+   * `EnumFilter`, `SliderControl`), so a bare-name match let one local helper switch this rule —
+   * and `bound-control-outside-home` and `responsive-twin` with it — off for a whole consumer file.
+   * A file that imports `basalt-ui*` is CONSUMING basalt; basalt's own control sources import each
+   * other relatively and never name the package.
+   */
+  it('DOES flag a file that declares its own PanelRow but imports basalt-ui', () => {
+    const { rules } = run(
+      `import { Section } from 'basalt-ui'\n${MANTINE_IMPORT}` +
+        `function PanelRow({ children }) {\n  return <div>{children}</div>\n}\n` +
+        `export const C = () => (\n  <Section title="x">\n    <Select value={v} onChange={set} data={[]} />\n  </Section>\n)\n`,
+    )
+    expect(rules).toContain('control-outside-home')
+  })
+
+  /**
+   * The basalt SUBTREE homes, which this rule did not know: `bound-control-outside-home` has read
+   * `FilterSet` / `PageAside` / `PanelRow` as homes since it shipped, so a `<Select>` inside a
+   * `<PageAside><PanelRow>` reported while the bound control beside it did not — two rules
+   * answering one question two ways.
+   */
+  it('does NOT flag one inside a PageAside > PanelRow subtree', () => {
+    const { code, rules } = run(
+      `import { PageAside } from 'basalt-ui'\nimport { PanelRow } from 'basalt-ui/controls'\n${MANTINE_IMPORT}` +
+        `export const C = () => (\n  <PageAside title="Filters">\n    <PanelRow label="Scale">\n      <Select data={[]} />\n    </PanelRow>\n  </PageAside>\n)\n`,
+      'src/scale-page.tsx',
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('control-outside-home')
+  })
+
+  it('does NOT flag one inside a FilterSet subtree', () => {
+    const { rules } = run(
+      `import { FilterSet } from 'basalt-ui/controls'\n${MANTINE_IMPORT}` +
+        `export const C = () => (\n  <FilterSet>\n    <Select data={[]} />\n  </FilterSet>\n)\n`,
+      'src/scale-page.tsx',
+    )
+    expect(rules).not.toContain('control-outside-home')
+  })
+
+  // Provenance, the test `SLOT_OWNER_TAGS` already applies: a consumer's own `PanelRow` is a layout
+  // helper, not a basalt home, so it exempts nothing.
+  it("still flags one inside a consumer's OWN PanelRow", () => {
+    const { rules } = run(
+      `import { PanelRow } from './panel-row'\n${MANTINE_IMPORT}` +
+        `export const C = () => (\n  <PanelRow label="Scale">\n    <Select data={[]} />\n  </PanelRow>\n)\n`,
+      'src/scale-page.tsx',
+    )
+    expect(rules).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` +
@@ -1731,6 +1908,292 @@ describe('basalt/control-outside-home', () => {
     )
     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')
+    })
+
+    // The SECOND dialect: a repo mandating `PascalCase.tsx` for component files (basalt's own root
+    // CLAUDE.md included) can never write `foo-panel.tsx`, so the kebab form alone exempted nothing
+    // there — which is how the CBBI panel collected four warns for a `<PageAside>` in its parent.
+    it.each(['src/EditSessionModal.tsx', 'src/FiltersDrawer.tsx', 'src/CbbiPanel.tsx'])(
+      'does NOT flag %s — the PascalCase dialect of the same convention',
+      (filename) => {
+        const { code, rules } = run(SOURCE, filename)
+        expect(code).toBe(0)
+        expect(rules).not.toContain('control-outside-home')
+      },
+    )
+
+    /**
+     * The trade, stated as a test rather than only as prose: a `FooPanel.tsx` that renders NO page
+     * bar is exempt WHOLE-FILE, so a control that genuinely belongs in a bar goes unreported there.
+     * Measured before keeping it — across argo, linewatch, image-share, rb and image-gen the
+     * PascalCase dialect matches 9 files, all in image-gen, and NONE of them renders a `<PageBar>`
+     * or sits under a `routes/` directory. Nine overlay bodies, zero pages, so the dialect stays
+     * whole-file rather than growing a "does it render a page bar" predicate (CONTROLS-SPEC §6).
+     */
+    it('exempts a FooPanel.tsx that renders no page bar — the measured trade', () => {
+      const { code, rules } = run(SOURCE, 'src/components/refine/CropPanel.tsx')
+      expect(code).toBe(0)
+      expect(rules).not.toContain('control-outside-home')
+    })
+
+    it('needs the leading subject in the PascalCase dialect too', () => {
+      const { rules } = run(SOURCE, 'src/Panel.tsx')
+      expect(rules).toContain('control-outside-home')
+    })
+
+    it('is CASE-sensitive — foopanel.tsx is neither dialect', () => {
+      const { rules } = run(SOURCE, 'src/foopanel.tsx')
+      expect(rules).toContain('control-outside-home')
+    })
+  })
+})
+
+/**
+ * Ledger G5 (`docs/ASIDE-SPEC.md` §2) — the basalt half of law C1. Mirrors the
+ * `control-outside-home` block above case for case, because the two rules answer the same question
+ * about a different tag set: that one matches raw Mantine, this one matches a bound basalt control.
+ */
+describe('basalt/bound-control-outside-home', () => {
+  const CONTROLS_IMPORT = `import { FilterSet, PanelRow, SelectFilter, SliderControl } from 'basalt-ui/controls'\n`
+  const ASIDE_IMPORT = `import { PageAside, PageBar, Section } from 'basalt-ui'\n`
+
+  it("flags a bound control in a Section's BODY — the stray pill G5 named", () => {
+    const { code, rules } = run(
+      `${ASIDE_IMPORT}${CONTROLS_IMPORT}export const C = () => (\n  <Section title="Composition">\n    <SelectFilter field={f} />\n  </Section>\n)\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('bound-control-outside-home')
+  })
+
+  it('flags one in a bare page Stack', () => {
+    const { rules } = run(
+      `import { Stack } from '@mantine/core'\n${CONTROLS_IMPORT}` +
+        `export const C = () => (\n  <Stack>\n    <SelectFilter field={f} />\n  </Stack>\n)\n`,
+    )
+    expect(rules).toContain('bound-control-outside-home')
+  })
+
+  it('does NOT flag one in a PageBar filters slot', () => {
+    const { code, rules } = run(
+      `${ASIDE_IMPORT}${CONTROLS_IMPORT}export const C = () => <PageBar filters={<SelectFilter field={f} />} />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  it('does NOT flag one inside a FilterSet subtree', () => {
+    const { code, rules } = run(
+      `${CONTROLS_IMPORT}export const C = () => (\n  <FilterSet>\n    <SelectFilter field={f} />\n  </FilterSet>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  // The aside is a shell REGION whose body IS a home — it scopes its children to the `panel`
+  // surface, where the same control renders as a row rather than a pill (docs/ASIDE-SPEC.md §3).
+  it('does NOT flag one inside a PageAside subtree, Section and all', () => {
+    const { code, rules } = run(
+      `${ASIDE_IMPORT}${CONTROLS_IMPORT}export const C = () => (\n  <PageAside title="Filters">\n    <Section title="Origin">\n      <SelectFilter field={f} />\n    </Section>\n  </PageAside>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  it("does NOT flag one as a PanelRow's `end` — the attribute hangs off PanelRow itself", () => {
+    const { code, rules } = run(
+      `${CONTROLS_IMPORT}export const C = () => <PanelRow label="Weight" end={<SelectFilter field={f} />} />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  it("does NOT flag one in a PanelRow's children — the row IS the home", () => {
+    const { rules } = run(
+      `${CONTROLS_IMPORT}export const C = () => (\n  <PanelRow label="Origin">\n    <SelectFilter field={f} />\n  </PanelRow>\n)\n`,
+    )
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  it('does NOT flag one inside an overlay host (Modal)', () => {
+    const { rules } = run(
+      `import { Modal } from '@mantine/core'\n${CONTROLS_IMPORT}` +
+        `export const C = () => (\n  <Modal opened>\n    <SelectFilter field={f} />\n  </Modal>\n)\n`,
+    )
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  // FormRow/FormGroup are the same declared non-home as SettingsRow — shared CONTROL_HOST_TAGS walk.
+  it.each(['FormRow', 'FormGroup'])('does NOT flag one inside a %s', (host) => {
+    const { code, rules } = run(
+      `import { ${host} } from 'basalt-ui/forms'\n${CONTROLS_IMPORT}` +
+        `export const C = () => <${host} label="L"><SelectFilter field={f} /></${host}>\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  it.each(['src/cbbi-panel.tsx', 'src/CbbiPanel.tsx'])(
+    'does NOT flag %s — a panel body whose host lives in the parent, in either dialect',
+    (filename) => {
+      const { code, rules } = run(
+        `${CONTROLS_IMPORT}export const C = () => <div><SelectFilter field={f} /></div>\n`,
+        filename,
+      )
+      expect(code).toBe(0)
+      expect(rules).not.toContain('bound-control-outside-home')
+    },
+  )
+
+  // Both dialects need the leading SUBJECT, and neither is case-insensitive — `foopanel.tsx` is a
+  // page module spelled without a separator, not a declaration.
+  it.each(['src/foopanel.tsx', 'src/Panel.tsx'])('still flags %s', (filename) => {
+    const { rules } = run(
+      `${CONTROLS_IMPORT}export const C = () => <div><SelectFilter field={f} /></div>\n`,
+      filename,
+    )
+    expect(rules).toContain('bound-control-outside-home')
+  })
+
+  it('honors a scoped theme-allow', () => {
+    const { rules } = run(
+      `${CONTROLS_IMPORT}export const C = () => (\n  <div>\n    {/* theme-allow bound-control-outside-home — a one-off embedded picker */}\n    <SelectFilter field={f} />\n  </div>\n)\n`,
+    )
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  it('honors a theme-allow-file declaration', () => {
+    const { rules } = run(
+      `// theme-allow-file bound-control-outside-home — a legacy page, migrating next sprint\n` +
+        `${CONTROLS_IMPORT}export const C = () => <div><SelectFilter field={f} /></div>\n`,
+    )
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  // Provenance, the same test the raw-filter rules apply the other way round: a consumer's own
+  // `SelectFilter` is not basalt's, and basalt has no claim over where it is written.
+  it('does NOT flag a locally-defined SelectFilter', () => {
+    const { code, rules } = run(
+      `import { SelectFilter } from './my-filters'\n` +
+        `export const C = () => <div><SelectFilter field={f} /></div>\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  it('flags an ALIASED basalt import with no home', () => {
+    const { rules } = run(
+      `import { SelectFilter as Picker } from 'basalt-ui/controls'\n` +
+        `export const C = () => <div><Picker field={f} /></div>\n`,
+    )
+    expect(rules).toContain('bound-control-outside-home')
+  })
+
+  /**
+   * The owner exemption needs the file to import NOTHING from `basalt-ui*` — see
+   * `control-outside-home`'s copy for why. For THIS rule that makes the exemption reachable only
+   * inside basalt's own `src/`, which is exactly where it is meant to apply: provenance already
+   * requires a basalt import (or a relative one inside that tree), so a consumer file can never be
+   * both the owner and a place this rule could fire.
+   */
+  it('DOES flag a consumer file that declares its own PanelRow', () => {
+    const { rules } = run(
+      `${CONTROLS_IMPORT}function PanelRow({ children }) {\n  return <div>{children}</div>\n}\n` +
+        `export const C = () => <div><SelectFilter field={f} /></div>\n`,
+    )
+    expect(rules).toContain('bound-control-outside-home')
+  })
+
+  // Provenance on the HOME too, the same test `control-outside-home` applies: a consumer's own
+  // `PanelRow` is a layout helper, not the aside's row primitive.
+  it("still flags one inside a consumer's OWN PanelRow", () => {
+    const { rules } = run(
+      `import { SelectFilter } from 'basalt-ui/controls'\nimport { PanelRow } from './panel-row'\n` +
+        `export const C = () => (\n  <PanelRow label="Scale">\n    <SelectFilter field={f} />\n  </PanelRow>\n)\n`,
+    )
+    expect(rules).toContain('bound-control-outside-home')
+  })
+
+  /**
+   * `SliderControl` is NOT policed: it renders its own `PanelRow` and has no pill form at all
+   * (`docs/ASIDE-SPEC.md` §3), so "this renders as a stray pill" is false for it and a `Section`
+   * body is a legitimate place to write one. The plugin has no per-tag home set, so the honest fix
+   * is dropping it from the policed set rather than giving it a private exemption.
+   */
+  it('does NOT flag a SliderControl in a Section body — it has no pill form', () => {
+    const { code, rules } = run(
+      `${ASIDE_IMPORT}${CONTROLS_IMPORT}export const C = () => (\n  <Section title="Weights">\n    <SliderControl field={f} label="Pi" />\n  </Section>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  it('resolves a hoisted binding handed to a slot, like its siblings do', () => {
+    const { rules } = run(
+      `${ASIDE_IMPORT}${CONTROLS_IMPORT}const pills = <SelectFilter field={f} />\n` +
+        `export const C = () => <PageBar filters={pills} />\n`,
+    )
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  /**
+   * …and one handed to a subtree home as its CHILDREN, which the ancestry walk cannot see: at the
+   * `const` there is no `PageAside` above the node at all. The same `Program:exit` deferral the
+   * slot lane uses, over the home's `{expr}` children instead of its attributes.
+   */
+  it('resolves a hoisted binding rendered as a PageAside CHILD', () => {
+    const { code, rules } = run(
+      `${ASIDE_IMPORT}${CONTROLS_IMPORT}const rows = <SelectFilter field={f} />\n` +
+        `export const C = () => <PageAside title="Filters">{rows}</PageAside>\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('bound-control-outside-home')
+  })
+
+  it('still flags the same hoisted binding under a bare Stack', () => {
+    const { rules } = run(
+      `import { Stack } from '@mantine/core'\n${CONTROLS_IMPORT}const rows = <SelectFilter field={f} />\n` +
+        `export const C = () => <Stack>{rows}</Stack>\n`,
+    )
+    expect(rules).toContain('bound-control-outside-home')
+  })
 })
 
 describe('basalt/control-size-literal', () => {
@@ -1761,6 +2224,82 @@ describe('basalt/control-size-literal', () => {
     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`,
@@ -2043,6 +2582,17 @@ describe('basalt/responsive-twin', () => {
     expect(rules).not.toContain('responsive-twin')
   })
 
+  // The owner exemption's second half, the same predicate its two siblings apply: a consumer file
+  // that names a helper `PanelRow` and imports basalt is consuming basalt, not defining a control.
+  it('DOES flag a file that declares its own PanelRow but imports basalt-ui', () => {
+    const { rules } = run(
+      `import { Section } from 'basalt-ui'\n` +
+        `function PanelRow({ children }) {\n  return <div>{children}</div>\n}\n` +
+        `export const C = () => (\n  <div>\n    <SegmentedControl visibleFrom="sm" data={[]} />\n    <SegmentedControl hiddenFrom="sm" data={[]} />\n  </div>\n)\n`,
+    )
+    expect(rules).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`,
@@ -2232,42 +2782,801 @@ describe('basalt/shadow-basalt-export — SHADOW_ALIASES', () => {
   })
 })
 
-// ── SURFACES ↔ the plugin registry ───────────────────────────────────────────
+/**
+ * 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')
+  })
 
-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('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')
   })
 
-  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])
-    }
+  // 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("puts the shell rule on the root barrel's surface (wave 6)", () => {
-    expect(SURFACES['.'].pluginRules).toContain('hand-rolled-shell')
+  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')
   })
 
-  it('gives ./controls the control-tier rules', () => {
-    expect([...SURFACES['./controls'].pluginRules].toSorted()).toEqual([
-      'control-outside-home',
-      'control-size-literal',
-      'hand-rolled-filter',
-      'responsive-twin',
+  // 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([
+      'bound-control-outside-home',
+      'control-outside-home',
+      'control-size-literal',
+      'hand-rolled-filter',
+      'responsive-twin',
     ])
   })
 })
+
+// ── provider-above-router (F5) ───────────────────────────────────────────────
+
+describe('basalt/provider-above-router', () => {
+  const IMPORTS =
+    `import { BasaltProvider } from 'basalt-ui'\n` +
+    `import { RouterProvider } from '@tanstack/react-router'\n`
+
+  it('flags a BasaltProvider rendered inside a RouterProvider', () => {
+    const { code, rules } = run(
+      `${IMPORTS}export const App = () => (\n` +
+        `  <RouterProvider router={r}>\n    <BasaltProvider>{null}</BasaltProvider>\n` +
+        `  </RouterProvider>\n)\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('provider-above-router')
+  })
+
+  it('does NOT flag the correct order — provider above router', () => {
+    const { code, rules } = run(
+      `${IMPORTS}export const App = () => (\n` +
+        `  <BasaltProvider>\n    <RouterProvider router={r} />\n  </BasaltProvider>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('provider-above-router')
+  })
+
+  // Provenance both ways: the tag names alone are not the finding.
+  it("does NOT flag a consumer's own BasaltProvider (no basalt import)", () => {
+    const { code, rules } = run(
+      `import { RouterProvider } from '@tanstack/react-router'\n` +
+        `import { BasaltProvider } from './my-provider'\n` +
+        `export const App = () => (\n  <RouterProvider router={r}>\n` +
+        `    <BasaltProvider>{null}</BasaltProvider>\n  </RouterProvider>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('provider-above-router')
+  })
+
+  it('does NOT flag a RouterProvider that is not TanStack s', () => {
+    const { code, rules } = run(
+      `import { BasaltProvider } from 'basalt-ui'\n` +
+        `import { RouterProvider } from 'other-router'\n` +
+        `export const App = () => (\n  <RouterProvider router={r}>\n` +
+        `    <BasaltProvider>{null}</BasaltProvider>\n  </RouterProvider>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('provider-above-router')
+  })
+
+  // The alias is why the ancestry is read by BINDING and not by written tag name.
+  it('flags through an aliased RouterProvider import', () => {
+    const { code, rules } = run(
+      `import { BasaltProvider } from 'basalt-ui'\n` +
+        `import { RouterProvider as Router } from '@tanstack/react-router'\n` +
+        `export const App = () => (\n  <Router router={r}>\n` +
+        `    <BasaltProvider>{null}</BasaltProvider>\n  </Router>\n)\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('provider-above-router')
+  })
+
+  it('honours a theme-allow naming the rule', () => {
+    const { code, rules } = run(
+      `${IMPORTS}export const App = () => (\n  <RouterProvider router={r}>\n` +
+        `    {/* theme-allow provider-above-router — legacy bootstrap, ported next minor */}\n` +
+        `    <BasaltProvider>{null}</BasaltProvider>\n  </RouterProvider>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('provider-above-router')
+  })
+
+  // The documented limit of the heuristic — stated in the rule's own JSDoc, pinned here so a
+  // future widening has to move this test rather than discover the gap.
+  it('does NOT see a cross-file composition (static JSX ancestry only)', () => {
+    const { code, rules } = run(
+      `import { BasaltProvider } from 'basalt-ui'\n` +
+        `import { Routes } from './routes'\n` +
+        `export const App = () => (\n  <Routes>\n    <BasaltProvider>{null}</BasaltProvider>\n` +
+        `  </Routes>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('provider-above-router')
+  })
+})
+
+// ── duplicate-notifications-mount (F5) ───────────────────────────────────────
+
+describe('basalt/duplicate-notifications-mount', () => {
+  const IMPORTS =
+    `import { BasaltOverlays } from 'basalt-ui/commands'\n` +
+    `import { BasaltNotifications } from 'basalt-ui/notifications'\n`
+
+  it('flags both mounts in one file', () => {
+    const { code, rules } = run(
+      `${IMPORTS}export const App = () => (\n  <BasaltOverlays notifications>\n` +
+        `    <BasaltNotifications />\n  </BasaltOverlays>\n)\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('duplicate-notifications-mount')
+  })
+
+  // `notifications` defaults to TRUE, so the attribute being absent is the same defect.
+  it('flags when BasaltOverlays writes no notifications prop at all', () => {
+    const { code, rules } = run(
+      `${IMPORTS}export const App = () => (\n  <BasaltOverlays>\n` +
+        `    <BasaltNotifications />\n  </BasaltOverlays>\n)\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('duplicate-notifications-mount')
+  })
+
+  it('does NOT flag when BasaltOverlays disables its notifications layer', () => {
+    const { code, rules } = run(
+      `${IMPORTS}export const App = () => (\n  <BasaltOverlays notifications={false}>\n` +
+        `    <BasaltNotifications />\n  </BasaltOverlays>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('duplicate-notifications-mount')
+  })
+
+  it('does NOT flag a standalone BasaltNotifications on its own', () => {
+    const { code, rules } = run(
+      `import { BasaltNotifications } from 'basalt-ui/notifications'\n` +
+        `export const App = () => <BasaltNotifications />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('duplicate-notifications-mount')
+  })
+
+  it("does NOT flag a consumer's own components of the same names", () => {
+    const { code, rules } = run(
+      `import { BasaltOverlays } from './overlays'\n` +
+        `import { BasaltNotifications } from './notifications'\n` +
+        `export const App = () => (\n  <BasaltOverlays>\n    <BasaltNotifications />\n` +
+        `  </BasaltOverlays>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('duplicate-notifications-mount')
+  })
+
+  it('honours a theme-allow naming the rule', () => {
+    const { code, rules } = run(
+      `${IMPORTS}export const App = () => (\n  <BasaltOverlays notifications>\n` +
+        `    {/* theme-allow duplicate-notifications-mount — two roots, never both mounted */}\n` +
+        `    <BasaltNotifications />\n  </BasaltOverlays>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('duplicate-notifications-mount')
+  })
+
+  // Two mounts WRITTEN, one mount RENDERED — the ternary is the shape a consumer reaches for while
+  // migrating from the standalone layer to the composed one, and it was never a double mount.
+  it('does NOT flag the two branches of one ternary', () => {
+    const { code, rules } = run(
+      `${IMPORTS}export const App = ({ composed }) => (\n` +
+        `  <div>{composed ? <BasaltOverlays /> : <BasaltNotifications />}</div>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('duplicate-notifications-mount')
+  })
+
+  it('does NOT flag the two operands of one logical expression', () => {
+    const { code, rules } = run(
+      `${IMPORTS}export const App = ({ composed }) => (\n` +
+        `  <div>{(composed && <BasaltOverlays />) || <BasaltNotifications />}</div>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('duplicate-notifications-mount')
+  })
+
+  // The exemption is the NEAREST common ancestor only. Two separate `&&` guards can both hold, so
+  // this stays a finding — the pair is conditional, not exclusive.
+  it('DOES flag two independently-guarded mounts under one parent', () => {
+    const { code, rules } = run(
+      `${IMPORTS}export const App = ({ a, b }) => (\n` +
+        `  <div>{a && <BasaltOverlays />}{b && <BasaltNotifications />}</div>\n)\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('duplicate-notifications-mount')
+  })
+
+  // One exclusive pair does not excuse a second, unconditional overlays mount.
+  it('DOES flag when a NON-exclusive overlays mount also exists', () => {
+    const { code, rules } = run(
+      `${IMPORTS}export const App = ({ composed }) => (\n` +
+        `  <BasaltOverlays>\n` +
+        `    {composed ? <BasaltOverlays /> : <BasaltNotifications />}\n` +
+        `  </BasaltOverlays>\n)\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('duplicate-notifications-mount')
+  })
+})
+
+// ── query-dual-import (F5) ───────────────────────────────────────────────────
+
+describe('basalt/query-dual-import', () => {
+  it('flags a file importing from both @tanstack/react-query and basalt-ui/query', () => {
+    const { code, rules, output } = run(
+      `import { useQuery } from '@tanstack/react-query'\n` +
+        `import { unwrap } from 'basalt-ui/query'\n` +
+        `export const useThing = () => useQuery({ queryKey: ['t'], queryFn: () => unwrap(get()) })\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('query-dual-import')
+    expect(output).toContain('Dual query import')
+  })
+
+  // The softer half — the one that actually catches the drift, and why the rule is `warn`.
+  it('flags a raw @tanstack/react-query import beside a basalt root import', () => {
+    const { code, rules, output } = run(
+      `import { useQuery } from '@tanstack/react-query'\n` +
+        `import { QueryState } from 'basalt-ui'\n` +
+        `export const useThing = () => useQuery({ queryKey: ['t'], queryFn: get })\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('query-dual-import')
+    expect(output).toContain('Raw @tanstack/react-query import')
+  })
+
+  it('does NOT flag basalt-ui/query on its own', () => {
+    const { code, rules } = run(
+      `import { useQuery, unwrap } from 'basalt-ui/query'\n` +
+        `export const useThing = () => useQuery({ queryKey: ['t'], queryFn: () => unwrap(get()) })\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('query-dual-import')
+  })
+
+  // `import type` is erased at compile time — there is no runtime import to route through the
+  // seam, and typing against the library's own result type is what `QueryStateLike` documents as
+  // legitimate. Same skip `agent-no-raw-usechat` and `ai-sdk-major` take.
+  it('does NOT flag a type-only @tanstack/react-query import beside basalt-ui/query', () => {
+    const { code, rules } = run(
+      `import type { UseQueryResult } from '@tanstack/react-query'\n` +
+        `import { unwrap } from 'basalt-ui/query'\n` +
+        `export const pick = (q: UseQueryResult<number>) => unwrap(q.data)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('query-dual-import')
+  })
+
+  it('does NOT flag @tanstack/react-query in a file with no basalt import', () => {
+    const { code, rules } = run(
+      `import { useQuery } from '@tanstack/react-query'\n` +
+        `export const useThing = () => useQuery({ queryKey: ['t'], queryFn: get })\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('query-dual-import')
+  })
+
+  // The devtools package is a different package, not a subpath.
+  it('does NOT flag @tanstack/react-query-devtools', () => {
+    const { code, rules } = run(
+      `import { ReactQueryDevtools } from '@tanstack/react-query-devtools'\n` +
+        `import { unwrap } from 'basalt-ui/query'\n` +
+        `export const D = () => <ReactQueryDevtools />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('query-dual-import')
+  })
+
+  it('honours a theme-allow naming the rule', () => {
+    const { code, rules } = run(
+      `// theme-allow query-dual-import — the persister API has no basalt re-export yet\n` +
+        `import { useQuery } from '@tanstack/react-query'\n` +
+        `import { unwrap } from 'basalt-ui/query'\n` +
+        `export const useThing = () => useQuery({ queryKey: ['t'], queryFn: () => unwrap(g()) })\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('query-dual-import')
+  })
+})
+
+// ── query-fn-unwrap (F5) ─────────────────────────────────────────────────────
+
+describe('basalt/query-fn-unwrap', () => {
+  const IMPORT = `import { unwrap } from 'basalt-ui/query'\n`
+
+  it('flags a queryFn that fetches with no unwrap', () => {
+    const { code, rules } = run(
+      `${IMPORT}export const o = { queryKey: ['t'], queryFn: () => fetch('/api/t') }\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('query-fn-unwrap')
+  })
+
+  it('flags the async .json() form', () => {
+    const { code, rules } = run(
+      `${IMPORT}export const o = {\n  queryKey: ['t'],\n` +
+        `  queryFn: async () => (await fetch('/api/t')).json(),\n}\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('query-fn-unwrap')
+  })
+
+  it('does NOT flag a queryFn that wraps the call', () => {
+    const { code, rules } = run(
+      `${IMPORT}export const o = { queryKey: ['t'], queryFn: () => unwrap(fetch('/api/t')) }\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('query-fn-unwrap')
+  })
+
+  it('does NOT flag a queryFn with no fetch in it', () => {
+    const { code, rules } = run(
+      `${IMPORT}export const o = { queryKey: ['t'], queryFn: () => client.t.get() }\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('query-fn-unwrap')
+  })
+
+  // The scope gate: with no basalt-ui/query import this is an opinion about `fetch`, which basalt
+  // does not have.
+  it('does NOT flag a file that never imports basalt-ui/query', () => {
+    const { code, rules } = run(
+      `export const o = { queryKey: ['t'], queryFn: () => fetch('/api/t') }\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('query-fn-unwrap')
+  })
+
+  // The documented blind spot — a reference, not a function literal. Pinned so a widening moves it.
+  it('does NOT see a queryFn passed as a reference', () => {
+    const { code, rules } = run(
+      `${IMPORT}const load = () => fetch('/api/t')\n` +
+        `export const o = { queryKey: ['t'], queryFn: load }\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('query-fn-unwrap')
+  })
+
+  it('honours a theme-allow naming the rule', () => {
+    const { code, rules } = run(
+      `${IMPORT}export const o = {\n  queryKey: ['t'],\n` +
+        `  // theme-allow query-fn-unwrap — raw Response is the point, this reads a blob\n` +
+        `  queryFn: () => fetch('/api/t'),\n}\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('query-fn-unwrap')
+  })
+})
+
+// ── deprecated-export (B4) ───────────────────────────────────────────────────
+
+describe('basalt/deprecated-export', () => {
+  it('flags a deprecated named import', () => {
+    const { code, rules, output } = run(
+      `import { field } from 'basalt-ui/forms'\nexport const f = field\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('deprecated-export')
+    expect(output).toContain('inputProps')
+  })
+
+  it('does NOT flag the replacement', () => {
+    const { code, rules } = run(
+      `import { inputProps } from 'basalt-ui/forms'\nexport const f = inputProps\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('deprecated-export')
+  })
+
+  it('does NOT flag a same-named import from somewhere else', () => {
+    const { code, rules } = run(`import { field } from 'basalt-ui/state'\nexport const f = field\n`)
+    expect(code).toBe(0)
+    expect(rules).not.toContain('deprecated-export')
+  })
+
+  it('flags each deprecated BasaltProvider connectivity prop', () => {
+    const { code, rules, output } = run(
+      `import { BasaltProvider } from 'basalt-ui'\n` +
+        `export const App = () => (\n` +
+        `  <BasaltProvider sseUrl="/e" healthUrl="/h" healthIntervalMs={5000}>{null}</BasaltProvider>\n)\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('deprecated-export')
+    expect(output).toContain('connectivity')
+  })
+
+  it('does NOT flag the connectivity object prop', () => {
+    const { code, rules } = run(
+      `import { BasaltProvider } from 'basalt-ui'\n` +
+        `export const App = () => <BasaltProvider connectivity={{ sseUrl: '/e' }}>{null}</BasaltProvider>\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('deprecated-export')
+  })
+
+  it("does NOT flag an sseUrl on a consumer's own component", () => {
+    const { code, rules } = run(
+      `import { BasaltProvider } from './provider'\n` +
+        `export const App = () => <BasaltProvider sseUrl="/e">{null}</BasaltProvider>\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('deprecated-export')
+  })
+
+  it('honours a theme-allow naming the rule', () => {
+    const { code, rules } = run(
+      `// theme-allow deprecated-export — pinned to 1.27.0 until the forms port lands\n` +
+        `import { field } from 'basalt-ui/forms'\nexport const f = field\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('deprecated-export')
+  })
+
+  // `field` → `inputProps` is NOT a drop-in rename any more (`inputProps` returns no `key`), so
+  // the row carries `fix: false`: the diagnostic still fires, but `--fix` must leave the import
+  // alone — the rewrite belongs to `basalt/forms-field-key`, which also inserts the key.
+  it('leaves a row with `fix: false` untouched under --fix while still reporting it', () => {
+    const source = `import { field } from 'basalt-ui/forms'\nexport const f = field\n`
+    writeFileSync(resolve(dir, 'fixture.tsx'), source)
+    Bun.spawnSync([OXLINT_BIN, '-c', '.oxlintrc.json', '--fix', 'fixture.tsx'], { cwd: dir })
+    expect(readFileSync(resolve(dir, 'fixture.tsx'), 'utf8')).toBe(source)
+    const { rules } = run(source)
+    expect(rules).toContain('deprecated-export')
+  })
+})
+
+// ── forms-field-key ──────────────────────────────────────────────────────────
+
+describe('basalt/forms-field-key', () => {
+  const FORMS = `import { inputProps } from 'basalt-ui/forms'\n`
+
+  it('flags a spread inputProps() with no sibling key', () => {
+    const { code, rules, output } = run(
+      `${FORMS}export const C = () => <TextInput {...inputProps(form, 'email')} />\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('forms-field-key')
+    expect(output).toContain('no sibling `key`')
+  })
+
+  it('does NOT flag the documented two-call idiom', () => {
+    const { code, rules } = run(
+      `import { fieldKey, inputProps } from 'basalt-ui/forms'\n` +
+        `export const C = () => <TextInput key={fieldKey(form, 'e')} {...inputProps(form, 'e')} />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('forms-field-key')
+  })
+
+  // An `inputProps` a consumer wrote themselves is not basalt's — the same provenance gate the
+  // control and chart rules take, one lane over.
+  it('does NOT flag a same-named helper imported from somewhere else', () => {
+    const { code, rules } = run(
+      `import { inputProps } from './my-helpers'\n` +
+        `export const C = () => <TextInput {...inputProps(form, 'email')} />\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('forms-field-key')
+  })
+
+  it('resolves an aliased import — `inputProps as f` is still inputProps', () => {
+    const { code, rules } = run(
+      `import { inputProps as f } from 'basalt-ui/forms'\n` +
+        `export const C = () => <TextInput {...f(form, 'email')} />\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('forms-field-key')
+  })
+
+  // The second message: `field` still RETURNS `key`, so it is reported whether or not the element
+  // carries one — the remedy is the rename, never an added attribute.
+  it('flags a spread field() even when the element already has a key', () => {
+    const { code, rules, output } = run(
+      `import { field } from 'basalt-ui/forms'\n` +
+        `export const C = () => <TextInput key="e" {...field(form, 'email')} />\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('forms-field-key')
+    expect(output).toContain('@deprecated 1.27 alias')
+  })
+
+  it('honours a theme-allow naming the rule', () => {
+    const { code, rules } = run(
+      `${FORMS}export const C = () => (\n` +
+        `  // theme-allow forms-field-key — this input is remounted by its parent\n` +
+        `  <TextInput {...inputProps(form, 'email')} />\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('forms-field-key')
+  })
+
+  // The autofix has to produce COMPILING code: an inserted `fieldKey(…)` with no import is a worse
+  // outcome than the missing key it replaced.
+  it('autofixes the key in, with the same arguments, and adds fieldKey to the import once', () => {
+    const source =
+      `${FORMS}export const C = () => (\n` +
+      `  <form>\n` +
+      `    <TextInput {...inputProps(form, 'email')} label="Email" />\n` +
+      `    <TextInput {...inputProps(form, 'name')} />\n` +
+      `  </form>\n)\n`
+    writeFileSync(resolve(dir, 'fixture.tsx'), source)
+    Bun.spawnSync([OXLINT_BIN, '-c', '.oxlintrc.json', '--fix', 'fixture.tsx'], { cwd: dir })
+    const fixed = readFileSync(resolve(dir, 'fixture.tsx'), 'utf8')
+    expect(fixed).toContain(`import { inputProps, fieldKey } from 'basalt-ui/forms'`)
+    expect(fixed).toContain(`key={fieldKey(form, 'email')} {...inputProps(form, 'email')}`)
+    expect(fixed).toContain(`key={fieldKey(form, 'name')} {...inputProps(form, 'name')}`)
+    // Once, not twice: two overlapping edits to one import declaration would drop one of them.
+    expect(fixed.match(/fieldKey,|, fieldKey/g)).toHaveLength(1)
+  })
+
+  it('does not re-add fieldKey when it is already imported', () => {
+    const source =
+      `import { fieldKey, inputProps } from 'basalt-ui/forms'\n` +
+      `export const C = () => <TextInput {...inputProps(form, 'email')} />\n`
+    writeFileSync(resolve(dir, 'fixture.tsx'), source)
+    Bun.spawnSync([OXLINT_BIN, '-c', '.oxlintrc.json', '--fix', 'fixture.tsx'], { cwd: dir })
+    const fixed = readFileSync(resolve(dir, 'fixture.tsx'), 'utf8')
+    expect(fixed).toContain(`import { fieldKey, inputProps } from 'basalt-ui/forms'`)
+    expect(fixed).toContain(`key={fieldKey(form, 'email')}`)
+  })
+})
+
+// ── the deprecation ledger (B4) ──────────────────────────────────────────────
+
+describe('DEPRECATED_EXPORTS', () => {
+  const pkgVersion = (
+    JSON.parse(readFileSync(resolve(import.meta.dirname, '..', 'package.json'), 'utf8')) as {
+      version: string
+    }
+  ).version
+
+  it('carries a replacement and a removeIn at least one minor out on every row', () => {
+    const [major, minor] = pkgVersion.split('.').map(Number)
+    const floor = `${major}.${(minor as number) + 1}.0`
+    for (const row of DEPRECATED_EXPORTS) {
+      expect([row.name, row.replacement.length > 0]).toEqual([row.name, true])
+      expect([row.name, /^\d+\.\d+\.\d+$/.test(row.removeIn)]).toEqual([row.name, true])
+      expect([row.name, compareSemver(row.removeIn, floor) >= 0]).toEqual([row.name, true])
+    }
+  })
+
+  it('names a real published subpath on every row', () => {
+    const exports = Object.keys(
+      (
+        JSON.parse(readFileSync(resolve(import.meta.dirname, '..', 'package.json'), 'utf8')) as {
+          exports: Record<string, unknown>
+        }
+      ).exports,
+    )
+    for (const row of DEPRECATED_EXPORTS) {
+      const subpath = row.subpath === 'basalt-ui' ? '.' : row.subpath.replace('basalt-ui', '.')
+      expect([row.subpath, exports.includes(subpath)]).toEqual([row.subpath, true])
+    }
+  })
+
+  /**
+   * The barrel half of the lifecycle: a JSDoc `@deprecated` on a published barrel with no ledger
+   * row is an export nothing nudges anyone off. Deliberately scoped to `src/**' + '/index.ts(x)` —
+   * the files a consumer's import resolves through. To add one: write the `@deprecated` JSDoc, add
+   * the `DEPRECATED_EXPORTS` row, add the `MIGRATING.md` row.
+   */
+  it('has a row for every @deprecated JSDoc tag on a published barrel', () => {
+    const barrels = [
+      ...new Bun.Glob('src/**/index.{ts,tsx}').scanSync({
+        cwd: resolve(import.meta.dirname, '..'),
+        absolute: true,
+      }),
+    ]
+    const names = new Set(DEPRECATED_EXPORTS.map((row) => row.prop ?? row.name))
+    for (const file of barrels) {
+      const lines = readFileSync(file, 'utf8').split('\n')
+      for (const [index, line] of lines.entries()) {
+        if (!/^\s*\*\s*@deprecated\b/.test(line)) continue
+        const declared = lines
+          .slice(index, index + 12)
+          .map((l) => /^\s*(?:readonly\s+)?([A-Za-z_$][\w$]*)\??\s*[:(]/.exec(l)?.[1])
+          .find((name) => name !== undefined)
+        expect([file, declared, declared !== undefined && names.has(declared)]).toEqual([
+          file,
+          declared,
+          true,
+        ])
+      }
+    }
+  })
+})
+
+// ── the `Ships:` claim above each rule (F26) ─────────────────────────────────
+
+/**
+ * F26 was a rule's own doc comment claiming a level it did not ship at, with nothing able to catch
+ * it: the C16 ledger is asserted against the preset, and a COMMENT is outside the ledger. So the
+ * claim is now one normalised line — `// Ships: <level>` directly above each rule's `const` — and
+ * this is the assertion that makes it as checkable as the ledger it restates.
+ */
+describe('the `Ships:` line above each rule', () => {
+  const source = readFileSync(resolve(import.meta.dirname, 'oxlint-plugin.js'), 'utf8')
+  const lines = source.split('\n')
+  const shipped = JSON.parse(readFileSync(resolve(import.meta.dirname, 'oxlint.json'), 'utf8')) as {
+    rules: Record<string, unknown>
+  }
+  // The registry block maps rule id → the `const` implementing it.
+  const registry = [
+    ...source.slice(source.indexOf('export default {')).matchAll(/^ {4}'([\w-]+)': (\w+),$/gm),
+  ].map(([, id, binding]) => ({ id: id as string, binding: binding as string }))
+
+  it('covers every registered rule', () => {
+    expect(registry.map((r) => r.id).toSorted()).toEqual(Object.keys(basaltPlugin.rules).toSorted())
+  })
+
+  for (const { id, binding } of registry) {
+    it(`${id}: the claim matches oxlint.json`, () => {
+      const at = lines.indexOf(`const ${binding} = {`)
+      expect([id, at]).not.toEqual([id, -1])
+      const claim = /^\/\/ Ships: (.+)$/.exec(lines[at - 1] as string)?.[1]
+      const level = shipped.rules[`basalt/${id}`]
+      if (level === undefined) {
+        expect([id, claim]).toEqual([id, 'repo-local only'])
+        return
+      }
+      if (Object.hasOwn(PLUGIN_RULE_GRACE, id)) {
+        const { promote } = PLUGIN_RULE_GRACE[id] as GraceEntry
+        expect([id, claim]).toEqual([id, `warn (grace → ${promote})`])
+        expect([id, level]).toEqual([id, 'warn'])
+        return
+      }
+      if (Object.hasOwn(PLUGIN_RULE_ADVISORY, id)) {
+        expect([id, claim]).toEqual([id, 'warn (advisory)'])
+        expect([id, level]).toEqual([id, 'warn'])
+        return
+      }
+      expect([id, claim]).toEqual([id, 'error'])
+      expect([id, level]).toEqual([id, 'error'])
+    })
+  }
+})