basalt-ui 1.21.0 → 1.23.0

package/agent/rules/basalt-charts.md

@@ -58,11 +58,13 @@ radial/matrix shape, is not optional — two `basalt` oxlint plugin rules
   compose `CartesianChart`. **Since 1.20.0 every assembly node is reported and waived on its own**
   — one comment no longer grants the whole file permanent immunity, which is how a 604-line chart
   file went unpoliced. To waive ONE node, put `theme-allow hand-rolled-plot — <why>` on it (or on a
-  comment-only line above it). A genuinely non-single-plot shape (multi-pane, radial, matrix)
-  declares the whole file with `theme-allow-file hand-rolled-plot — two panes over one x scale`,
-  anywhere in it; `DualPanel` carries the repo's only one. **`theme-allow-file` is the 1.20.1
-  spelling** — at 1.20.0 a node-scoped annotation was silently promoted to a file declaration, so
-  per-node scoping was not expressible; move the one word. The file that DEFINES `CartesianChart` is
+  comment-only line above it). A genuinely non-single-plot shape (multi-pane, radial, matrix, or a
+  strip with no y dimension) declares the whole file with `theme-allow-file hand-rolled-plot —
+<why>`, anywhere in it; basalt's own tree carries three, on `DualPanel`, `BandStrip` and
+  `MirroredBars`. `Donut` and `Heatmap` are non-single-plot too and carry none — they render no
+  assembly primitive, so the rule never fires and there is nothing to waive.
+  **`theme-allow-file` is the 1.21.0 spelling** — at 1.20.0 a node-scoped annotation was silently
+  promoted to a file declaration, so per-node scoping was not expressible; move the one word. The file that DEFINES `CartesianChart` is
   exempt definitionally (detected by declaration, not by path), since a rule saying "compose X"
   cannot fire inside X.
 - **`basalt/chart-legend-literal`** — a hand-written array literal passed to `ChartLegend`'s
@@ -95,7 +97,7 @@ ships no map kind.
 - **Want `@visx/geo` anyway?** Install it yourself — basalt doesn't pin it — and keep it under a
   `charts/` segment like every other visx import, same as any bespoke chart.
 - **Style map chrome with `--vx-*` tokens** (`VX.*`/`alpha()`) so it matches the rest of the app.
-- **The guard trap, narrowed at 1.20.1:** `check-theme`'s `inline-spacing` kind is a per-line regex
+- **The guard trap, narrowed at 1.21.0:** `check-theme`'s `inline-spacing` kind is a per-line regex
   over raw source, not an AST pass. A **unitless** number now only reports inside a style-object
   context (a `style=`/`sx=`/`css=` attribute, or a const whose name or type says styles), so a map's
   pixel geometry — `fitBounds({ padding: 48 })`, marker offsets — no longer trips it: an options bag
@@ -160,6 +162,13 @@ ships no map kind.
    onto one domain value, silently dropping one from the plot (see #6 below for why that's the
    cursor's problem too). `Heatmap` is deliberately excluded: its existing `colLabel`/`rowLabel`
    already are that seam, and a second prop over one concern would fork them.
+   **Which x ticks get painted is a separate seam**, `xTickValues?: (keys, xMax) => readonly
+string[]`, on `CartesianChart` and forwarded by `Bars`/`MultiLine`/`StackedArea`/`ZonedLine`
+   plus both band kinds. Resolution order is explicit VALUES → explicit COUNT (`xTicks`, unchanged)
+   → as many as fit (`smartTicks`); omit both and nothing moves. Reach for it on a dense time axis,
+   because **a count cannot express one**: `smartTicks`/`smartTicksEvery` append the final key
+   unconditionally, so any count that does not land exactly on the last index paints two labels on
+   top of each other at the right edge — at every count, not at an unlucky one.
    **The x axis is CATEGORICAL, and this is not inferable from the API.** `CartesianChart` builds
    its x scale as `scalePoint<string>`, so N points are N evenly spaced positions whatever the
    values behind the keys — there is no linear or time x scale. Correct and invisible for a domain
@@ -332,6 +341,24 @@ per-series `getValue` accessors on `ChartSeries<T>`):
   wrapper.
 - **`Donut`** — proportional donut with an optional center-content overlay. Composes `ChartFrame`
   directly (radial, not cartesian).
+- **`BandStrip`** — 1-D categorical bands over a shared x axis, **no y dimension at all**: one rect
+  per slot, `getBand(d) => { state, fill?, absentFraction?, marker? }`. `series` IS the state set —
+  it drives the legend, each band's fill and the one derived tooltip row, so a strip cannot name a
+  state it does not draw. `absentFraction` paints the share of a folded slot nothing measured as a
+  hatch; `marker` carries a fact that must not be readable off the `fill` ramp. `cursorResolution`
+  defaults `'leading'` here (a band IS a bucket), not `'nearest'`. Composes `ChartFrame` directly —
+  `CartesianChart` renders `AxisLeftNumeric` unconditionally, so this shape could never use it.
+- **`MirroredBars`** — two BAR panes over one x scale, mirrored around one baseline, each pane in
+  its own domain. `up`/`down` take `{ key, max?, autoMaxFloor?, ticks?, format }`; `upFraction`
+  (default 0.35) is the up pane's share of the band height, which is where the shared baseline sits;
+  `getAbsentFraction` hatches an unmeasured slot and `getBarOpacity` dims one. A sibling of
+  `DualPanel`, not an extension: `DualPanel`'s top pane is a LINE pane and its bottom takes one
+  SIGNED `getBar` over a symmetric domain. Two independent magnitudes are not one signed quantity.
+  Composes `ChartFrame` directly.
+
+Both band kinds fold their domain by width (`fold: { minBandPx?, merge }`), and `foldBands` is
+exported so a consumer can test their merge against the grouping that will actually run.
+`HatchPattern` / `hatchFill` / `hatchSizeFor` ship the absence fill.
 
 `ZonedLine` and `MultiLine` also accept `xZones?: XZoneSpec[]` — the vertical counterpart to a
 kind's horizontal zone bands, for marking a time window rather than a value range. Each
@@ -477,6 +504,14 @@ margin. Passing `y2` to get a dual-axis chart no longer needs a manual margin nu
 The escape hatch is `margin={{ left: n }}` (`Partial<ChartMargin>`) on `CartesianChart` — a per-side
 override applied LAST, after measurement, so it always wins.
 
+**A band plot has one extra law, because a band axis puts its FIRST tick on the plot's left edge.**
+With no left axis to measure, `autoMargin` stops at `VX.margin.left` and half the first x label
+hangs off the canvas — so `BandStrip` floors its left gutter at half the widest x label, mirroring
+what `autoMargin` already does on the right. Both terminal gutters are then capped (14% of width
+left, 12% right): uncapped, half a `DD.MM HH:MM` label is 48px of a 338px chart. `MirroredBars`
+probes real tick labels from both panes, so it takes the plain measured margin and neither the
+floor nor the cap applies.
+
 `chartMargin(opts?)` (`basalt-ui/tokens`, also re-exported from `basalt-ui/charts`) still exists,
 but only matters for a bespoke chart that composes `ChartFrame` directly (not `CartesianChart`) and
 needs a right-axis-sized margin without running its own measurement pass — `DualPanel` and `Heatmap`

package/agent/rules/basalt-router.md

@@ -83,7 +83,7 @@ against it.
 - Update via `navigate({ search: { window: 'all', from: undefined, to: undefined } })` — prefer plain
   objects over reducers to avoid `| undefined` assignability errors when the schema has defaults.
 
-### Wire the reader, or the store does nothing (1.20.1)
+### Wire the reader, or the store does nothing (1.21.0)
 
 `validateSearch` is only half the store. It restores the value when you arrive with **no** param —
 it cannot do anything about a nav link that declares the param itself, and a link written

package/agent/rules/basalt-state.md

@@ -25,7 +25,7 @@ Pick the right home for each kind of state — don't dump everything into one st
 - **UI preferences that must survive navigation but aren't URL-worthy** (sidebar collapsed, panel
   layout, draft filters) → `createPersistedState` from `basalt-ui/state` — the framework's own
   versioned localStorage primitive (see below). `BasaltShell` persists its own collapse state
-  through that same primitive since 1.20.1; use `createPersistedState` for app-level preferences.
+  through that same primitive since 1.21.0; use `createPersistedState` for app-level preferences.
   Reach for a third-party store only when complex cross-component state genuinely warrants it (see
   escape hatch below).
 
@@ -67,7 +67,7 @@ const [layout, setLayout] = usePanelLayout()
 Keys are namespaced `basalt:<key>` automatically and never collide with the theme-scheme guard.
 Pass a `schema` (Standard Schema) to validate persisted values and fall back to `initial` on mismatch.
 
-### Mirroring `BasaltShell`'s collapse (changed key at 1.20.1)
+### Mirroring `BasaltShell`'s collapse (changed key at 1.21.0)
 
 `BasaltShell` used `@mantine/hooks`' `useLocalStorage` while `createPersistedState` was the
 documented house API — so a consumer reading the raw key was complying with the shipped component,
@@ -77,11 +77,11 @@ moves the key:
 ```ts
 import { readPersistedValue } from 'basalt-ui/state'
 
-// 1.20.1: localStorage['basalt:<storageKey>'] === '{"v":1,"value":true}'
+// 1.21.0: localStorage['basalt:<storageKey>'] === '{"v":1,"value":true}'
 const collapsed = readPersistedValue('basalt-sidebar-collapsed', 1)
 ```
 
-A one-time migration adopts the raw pre-1.20.1 value, so an upgrade does not silently re-expand
+A one-time migration adopts the raw pre-1.21.0 value, so an upgrade does not silently re-expand
 every sidebar. It is a bridge, not a format — do not write against it.
 
 ## Zustand escape hatch (complex cross-component stores)

package/agent/rules/basalt-tokens.md

@@ -43,7 +43,7 @@ The scan reaches slightly beyond `roots`: each root's PARENT contributes its `in
 meta and a webmanifest's `background_color` actually live. `.json` is never blanket-scanned — name a
 design-surface JSON in `basalt.include`, the only route to one.
 
-## `theme-allow` — the 1.20.1 contract
+## `theme-allow` — the 1.21.0 contract
 
 The full grammar, in both engines:
 
@@ -63,7 +63,7 @@ An id is a guard kind (`raw-surface`, `inline-spacing`, …) or an oxlint plugin
 ```
 
 - **An annotation must START its comment** — after `//`, `/*`, `<!--`, a block-comment gutter `*`,
-  or nothing but whitespace. Before 1.20.1 any comment that merely _mentioned_ the token parsed as
+  or nothing but whitespace. Before 1.21.0 any comment that merely _mentioned_ the token parsed as
   the bare blanket form and switched every rule off on the line below: linewatch documented its own
   waivers in a docblock and thereby disarmed the file. Prose about the escape hatch no longer waives
   anything; everything a consumer actually writes still qualifies.
@@ -71,7 +71,7 @@ An id is a guard kind (`raw-surface`, `inline-spacing`, …) or an oxlint plugin
   Plain `theme-allow` is the node/line waiver in both engines. At 1.20.0 the two halves of the
   contract intersected at exactly one legal shape and that shape was whole-file — naming a rule and
   giving a reason was read as a file declaration, which is why per-node scoping did not actually
-  ship. **This is the consumer break in 1.20.1**: move each existing file declaration one word.
+  ship. **This is the consumer break in 1.21.0**: move each existing file declaration one word.
 - **A bare `theme-allow` still waives everything on its placement** but reports
   `theme-allow-unscoped` (`warn` for one minor, then `error`). A bare `theme-allow-file` waives
   nothing at all — whole-file blanket immunity off one unnamed comment is the thing this contract
@@ -96,6 +96,22 @@ An id is a guard kind (`raw-surface`, `inline-spacing`, …) or an oxlint plugin
   still ends the block; that is how you say "this comment is not about the next statement".
 - **`basalt/hand-rolled-plot` grants whole-file immunity only through `theme-allow-file`.** Every
   assembly node is otherwise waived on its own.
+- **Eight shapes are asserted NOT to waive, in both halves.** They are pinned as unsupported rather
+  than merely left out, so "unsupported" and "silently broken" stop reading the same. Don't write
+  them:
+
+  | Shape                                                                                                                              | Why it does not waive                                                                                               |
+  | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+  | a blank line between the annotation and the code — after `//`, after `{/* */}`, or after a `{/*` whose closer sits on its own line | a blank line is how you say "this comment is not about the next statement"                                          |
+  | the token mid-sentence in a line comment, a docblock gutter, or a JSX expression comment                                           | prose that MENTIONS the token is not an annotation — the reason it must START its comment                           |
+  | the token inside a string literal                                                                                                  | same                                                                                                                |
+  | above a multi-line OPENING tag, when the finding sits on a later attribute line                                                    | a waiver reaches the first line below its comment, not an arbitrary line further down — put it beside the attribute |
+
+  The whole grid — four axes, comment style × token position × where the closer falls × what
+  follows — is pinned row for row in `src/guard/check-source.test.ts` (37 supported + these 8) and
+  `configs/oxlint-plugin.test.ts` (32 + 8; five of the guard's rows are CSS/HTML/JSON dialects
+  oxlint never sees). Zero disagreements between the two, and no waiver tally moved in any of the
+  seven consumer repos.
 
 ### Audit them: `basalt-ui check-theme --audit-allows`
 
@@ -141,7 +157,12 @@ nothing is forked.
 - **Exact name match only** — the one limit that is structural. Round 5 confirmed the miss rate:
   linewatch's forks are named `Cell` and `Box`, rb's is `Stat`. Rename the fork and the rule goes
   quiet, which is what a fork's author naturally does.
-- **Scope: everything importable.** Since 1.20.1 it reads all nine published barrels, not just
+- **Scope: basalt consumers only, and component-shaped declarations only.** Since 1.22.0 the rule
+  gates on `isBasaltScopedFile` like every other rule in the file, and needs a function, an arrow, a
+  `memo`/`forwardRef` wrapper or a class extending one. A plain data class sharing a name with a
+  shipped export is a collision, not a fork — it fired on a `SlugTracker` class in a React-free
+  package that cannot import basalt-ui.
+- **Scope: everything importable.** Since 1.21.0 it reads all nine published barrels, not just
   `dist/index.d.ts` — so the `basalt-ui/charts` layer, which is where forks actually live, is finally
   covered. Names a barrel merely re-exports from a third party are skipped: `./charts` passes
   `Bar` / `Line` / `Pie` straight through from `@visx/shape`, and a local `Bar` is not a fork of

package/agent/skills/basalt-app/SKILL.md

@@ -120,9 +120,10 @@ Lint wires as `oxlint . && basalt-ui check-theme` (seeded as the `lint:basalt` s
 guard is the teeth behind the token doctrine. Before writing any composite, check whether basalt
 already ships it: round 4 found ~15 forked copies of shipped components across seven repos, all
 passing every gate, because a fork by a token-fluent author uses exactly the right tokens.
-`basalt/shadow-basalt-export` reads all nine published barrels since 1.20.1 (the charts layer
-included), but it warns only on an **exact** name collision — round 5 found the renamed forks
-(`Cell`, `Box`, `Stat`) sail straight past it. It is a tripwire, not coverage; nothing catches the
+`basalt/shadow-basalt-export` reads all nine published barrels since 1.21.0 (the charts layer
+included), but it warns only on an **exact** name collision, in a basalt-scoped file, on a
+component-shaped declaration — round 5 found the renamed forks (`Cell`, `Box`, `Stat`) sail straight
+past it. It is a tripwire, not coverage; nothing catches the
 rest. Ask before you build; do not wait to be told.
 
 The consumer series file (`<first basalt.root>/lib/series.ts` by default — so `src/lib/series.ts` on

package/agent/skills/basalt-charts/SKILL.md

@@ -16,9 +16,9 @@ everything below assumes — composing `CartesianChart` (single-plot) or `ChartF
 Before writing chart code, decide which of three paths you are on:
 
 1. **Reuse a shipped kind.** basalt-ui ships `ZonedLine`, `Bars`, `StackedArea`, `MultiLine`,
-   `DualPanel`, `Heatmap`, `Donut`. If the shape matches, use it — props are declarative (`data`,
-   `chartId`, `getX`, `series`/`positiveBars`, one `AxisConfig` per axis, zones/thresholds/refLines
-   as plain arrays). Done.
+   `DualPanel`, `Heatmap`, `Donut`, `BandStrip`, `MirroredBars`. If the shape matches, use it —
+   props are declarative (`data`, `chartId`, `getX`, `series`/`positiveBars`, one `AxisConfig` per
+   axis, zones/thresholds/refLines as plain arrays). Done.
    - **`ZonedLine`** — a single-series line with zone bands, thresholds, x-zones, refLines.
    - **`Bars`** — 1+ stacked positive/negative bar series, optional line overlays, dual-axis config.
    - **`StackedArea`** — opaque stacked bands, auto cumulative-top y-domain.
@@ -33,6 +33,13 @@ Before writing chart code, decide which of three paths you are on:
    - **`Heatmap`** — category×category intensity grid (`color-mix` alpha), per-cell tooltip,
      optional gradient legend strip. Replaces bespoke time-of-day.
    - **`Donut`** — proportional donut, optional `centerContent` overlay.
+   - **`BandStrip`** — 1-D categorical bands, no y dimension: one rect per slot,
+     `getBand(d) => { state, fill?, absentFraction?, marker? }`. `series` is the state set and
+     drives legend, fill and the one derived tooltip row. Replaces a bespoke state/availability
+     strip.
+   - **`MirroredBars`** — two BAR panes over one x scale and one baseline, each in its own domain
+     (`up`/`down` take `{ key, max?, autoMaxFloor?, ticks?, format }`). Not `DualPanel`, whose top
+     pane is a LINE and whose bottom takes one SIGNED accessor.
 2. **Extract a new kind (second instance of a pattern).** When you are about to build the _second_
    chart of a shape that has no shipped kind, extract a kind. Don't extract on the first; don't
    wait past the third. A new kind lives in the consumer's chart kinds dir (or, if generic enough
@@ -43,6 +50,12 @@ Before writing chart code, decide which of three paths you are on:
    genuinely different scales that don't fit any kind's config surface) composes `CartesianChart`
    or `ChartFrame` directly in the page's chart file — not in `kinds/`.
 
+**Extracting a kind? Prove it by porting.** A kind is proven by moving a real consumer's call
+sites onto it and reporting what it could NOT express — not by a demo page, which is written
+against the API that already exists. The two band kinds were built that way (linewatch, 1884 → 957
+source lines, 11 `hand-rolled-plot` waivers retired, two live `NaN`-geometry bugs found). Ship the
+"still cannot express" list with the kind.
+
 > Anti-pattern: a single `<Chart type="..." config={...} />` god-component that switches by kind.
 > That is the Recharts trap. Prefer N small kinds. **If a chart doesn't fit the primitives, add a
 > kind — don't loosen the primitives.**
@@ -109,8 +122,9 @@ Theme tuning of these series happens in the theme lab — pass them as `groups`
 ## Compose the primitives (never hand-roll)
 
 Every chart — kind or bespoke — composes `CartesianChart` for a single plot rect, or `ChartFrame`
-directly for a multi-pane / non-cartesian shape (`DualPanel`'s two panes, `Heatmap`'s grid,
-`Donut`'s ring). Either way the contract is the same: the primitive owns margin, scales, grid,
+directly for a multi-pane / non-cartesian shape — five of them ship: `DualPanel`'s two panes,
+`MirroredBars`' two bar panes, `BandStrip`'s missing y dimension, `Heatmap`'s grid, `Donut`'s ring.
+Either way the contract is the same: the primitive owns margin, scales, grid,
 axes, legend, the shared cursor, and the tooltip; you supply `series` and draw ONLY marks. This is
 mandatory, not a convention — `basalt/hand-rolled-plot` fails the build on a bypass (see "Respect
 the boundary" below); it is easier to compose it than to work around it.
@@ -212,9 +226,10 @@ import { ChartCursorScope } from 'basalt-ui/charts'
   primitive (`AxisLeftNumeric`, `AxisRightNumeric`, `AxisBottomDate`, `HoverOverlay`, `Crosshair`)
   rendered in a file that doesn't compose `CartesianChart`, per NODE. Escape:
   `theme-allow hand-rolled-plot — <why>` on the one node, or `theme-allow-file hand-rolled-plot —
-<why>` anywhere in the file — how a genuinely non-single-plot shape (`DualPanel`, `Heatmap`,
-  `Donut`) declares itself. `-file` is the 1.20.1 spelling and it is required. The file that defines
-  `CartesianChart` is exempt definitionally.
+<why>` anywhere in the file — how a genuinely non-single-plot shape (`DualPanel`, `MirroredBars`,
+  `BandStrip`; `Heatmap` and `Donut` render no assembly primitive and need none) declares itself.
+  `-file` is the 1.21.0 spelling and it is required. The file that defines `CartesianChart` is
+  exempt definitionally.
 - **No hand-authored legends.** `basalt/chart-legend-literal` fails the build on a hand-written
   array literal passed to `ChartLegend`'s `items` — derive it from the same `series` the chart draws
   (`deriveLegend`, or let `ChartFrame`/`CartesianChart` do it) so it can't name a series the plot no

package/agent/templates/DESIGN.md.tpl

@@ -1,6 +1,8 @@
 # {{APP_NAME}} — Design
 
-> Managed by basalt-ui ({{BASALT_VERSION}}). This is a **thin** instantiation — it records this
+> Managed by basalt-ui — run `basalt-ui doctor` for the version, never trust a number written into
+> a file (this one is a seed: written once at `init`, then owned by you, so any version stamped
+> here would be frozen at scaffold time). This is a **thin** instantiation — it records this
 > app's **deltas only** on top of the shipped `basalt-*` rules. The universal law (earned color,
 > neutral-by-default, three-tier `--vx-*` tokens, theme-is-data, the chart primitive contract, the
 > elevation/density/shape doctrine) lives in those rules and the `/basalt:design` skill, and is

package/configs/oxlint-plugin.js

@@ -245,8 +245,49 @@ function allComments(context) {
 }
 
 /**
- * True when a NODE-scoped `theme-allow` covering `ruleId` sits on `node`'s own source line or the
- * line above — or when the file carries a `theme-allow-file` declaration for it.
+ * Every comment that REACHES `nodeLine` — the comment on the node's own line, the one directly
+ * above it, and any further comment separated from that one by nothing but comment.
+ *
+ * This is the plugin's half of "which node does this annotation scope to", and it has to answer the
+ * same question `src/guard`'s forward walk answers: **an annotation reaches the first line below its
+ * comment that is not itself comment.** The test used to be a flat `end.line === nodeLine ||
+ * nodeLine - 1`, which is the same rule only when the annotation is the LAST comment above the node
+ * — so anything sitting between the annotation and the node, comment included, was reported here
+ * while the guard waived it:
+ *
+ * ```text
+ * // theme-allow raw-hex — the vendor brand hex, kept in sync with     ← a reason that wrapped
+ * // the marketing site's own palette                                     onto a second comment
+ * const BRAND = '#ff0000'
+ *
+ * {/* theme-allow card-inset — … *\/}
+ * {/* 3. the density row *\/}                                            ← an unrelated note
+ * <Card p={0} />
+ * ```
+ *
+ * The wrapped-reason one is not hypothetical: it is pinned in the guard's tests as a shape argo
+ * writes. A blank line still separates, because a blank line is not comment — which is what makes
+ * "this comment is not about the next statement" expressible in both halves.
+ *
+ * Returned bottom-up, which is also the cheap order to walk: stop at the first gap.
+ */
+function reachingComments(context, nodeLine) {
+  const comments = allComments(context).toSorted((a, b) => a.loc.start.line - b.loc.start.line)
+  const out = []
+  let reach = nodeLine
+  for (let i = comments.length - 1; i >= 0; i--) {
+    const comment = comments[i]
+    if (comment.loc.end.line > nodeLine) continue
+    if (comment.loc.end.line < reach - 1) break
+    out.push(comment)
+    reach = Math.min(reach, comment.loc.start.line)
+  }
+  return out
+}
+
+/**
+ * True when a NODE-scoped `theme-allow` covering `ruleId` reaches `node` (see
+ * {@link reachingComments}) — or when the file carries a `theme-allow-file` declaration for it.
  *
  * The `ruleId` argument is what stops one exemption from being a blanket one: a `theme-allow
  * raw-hex — …` written for a color no longer silently switches off `card-inset` on the same line.
@@ -254,13 +295,11 @@ function allComments(context) {
  */
 function hasThemeAllow(context, node, ruleId) {
   if (hasFileDeclaration(context, ruleId)) return true
-  const nodeLine = node.loc.start.line
-  return allComments(context).some((comment) => {
-    if (comment.loc.end.line !== nodeLine && comment.loc.end.line !== nodeLine - 1) return false
-    return parseThemeAllows(comment.value).some(
+  return reachingComments(context, node.loc.start.line).some((comment) =>
+    parseThemeAllows(comment.value).some(
       (allow) => allow.scope === 'line' && allowCovers(allow, ruleId),
-    )
-  })
+    ),
+  )
 }
 
 /**
@@ -535,10 +574,12 @@ const cardInset = {
 // ── Rule 3 — chart-in-raw-surface ───────────────────────────────────────────────────────────────
 
 const CHART_TAGS = new Set([
+  'BandStrip',
   'Bars',
   'Donut',
   'DualPanel',
   'Heatmap',
+  'MirroredBars',
   'MultiLine',
   'StackedArea',
   'ZonedLine',
@@ -1332,11 +1373,37 @@ const chartLegendLiteral = {
 const PACKAGE_ROOT = resolvePath(PLUGIN_DIR, '..')
 
 /**
- * A component-shaped name: starts uppercase and carries a lowercase letter, which excludes the
+ * A component-shaped NAME: starts uppercase and carries a lowercase letter, which excludes the
  * SCREAMING_CASE constants and the two-letter token namespaces in the same barrel.
+ *
+ * A name test alone is not a component test — see {@link isComponentInit}. Every PascalCase binding
+ * passes this, which is how obsidian's `SlugTracker` (a plain data class in a React-free package)
+ * became a "forked component" the moment 1.21.0 widened the rule to all nine barrels.
  */
 const COMPONENT_NAME = /^[A-Z][A-Za-z0-9]*[a-z][A-Za-z0-9]*$/
 
+/** The two wrappers a function component is legitimately declared inside. */
+const COMPONENT_WRAPPERS = new Set(['memo', 'forwardRef'])
+
+/**
+ * Is this initializer component-SHAPED — a function, an arrow, or one wrapped in `memo` /
+ * `forwardRef`?
+ *
+ * The second half of the fix for obsidian's false positive. `const Foo = new Map()` and
+ * `class SlugTracker {}` share a name with a basalt export and nothing else; a fork of a component
+ * is a function (or, historically, a class that `extends` one). Narrowing here costs the rule
+ * nothing it was ever meant to catch and removes the whole "PascalCase binding" false-positive
+ * class, which the nine-barrel widening made large.
+ */
+function isComponentInit(init) {
+  if (init === null || init === undefined) return false
+  if (init.type === 'ArrowFunctionExpression' || init.type === 'FunctionExpression') return true
+  if (init.type !== 'CallExpression') return false
+  const callee = init.callee
+  const name = callee?.type === 'MemberExpression' ? callee.property?.name : callee?.name
+  return typeof name === 'string' && COMPONENT_WRAPPERS.has(name)
+}
+
 /**
  * The barrels a consumer can import a component FROM. The root one is not the whole surface: a
  * chart-layer fork (`ChartFrame`, `CartesianChart`, `ChartCard`, …) collided with nothing, because
@@ -1428,6 +1495,11 @@ const shadowBasaltExport = {
     // basalt's own source DEFINES these names; a consumer's does not.
     if (BASALT_EXPORTS.size === 0 || filename.startsWith(`${PACKAGE_ROOT}/`)) return {}
     if (isTestFile(context)) return {}
+    // Scoped exactly like `ai-sdk-major`, and for the same reason: a package with no basalt-ui
+    // dependency (or one outside a declared `basalt.roots`) cannot import the export it is accused
+    // of forking, so the advice — "import it from 'basalt-ui' instead" — is not followable there.
+    // obsidian's React-free `obsidian-vault-core` took the report and had to waive it.
+    if (filename.length === 0 || !isBasaltScopedFile(filename)) return {}
 
     const report = (node, name) => {
       if (typeof name !== 'string' || !BASALT_EXPORTS.has(name)) return
@@ -1440,9 +1512,14 @@ const shadowBasaltExport = {
         report(node, node.id?.name)
       },
       VariableDeclarator(node) {
+        if (!isComponentInit(node.init)) return
         report(node, node.id?.name)
       },
+      // A class only counts when it EXTENDS something — a legacy class component. basalt ships no
+      // class components, so a standalone `class X {}` sharing a name with one of its exports is a
+      // collision between two unrelated things, not a fork.
       ClassDeclaration(node) {
+        if (node.superClass === null || node.superClass === undefined) return
         report(node, node.id?.name)
       },
     }

package/configs/oxlint-plugin.test.ts

@@ -44,6 +44,13 @@ beforeEach(() => {
       },
     }),
   )
+  // `shadow-basalt-export` and `ai-sdk-major` both scope through `isBasaltScopedFile`, so a fixture
+  // repo with NO manifest is out of scope for both and every other assertion here would pass
+  // vacuously. Written per-test by the `ai-sdk-major` block, which needs its own `ai` pin.
+  writeFileSync(
+    resolve(dir, 'package.json'),
+    JSON.stringify({ name: 'fixture', version: '0.0.0', dependencies: { 'basalt-ui': '^1.21.0' } }),
+  )
 })
 
 afterEach(() => {
@@ -918,6 +925,172 @@ describe('basalt/shadow-basalt-export', () => {
     expect(code).toBe(0)
     expect(rules).not.toContain('shadow-basalt-export')
   })
+
+  // The scoping fix, mirroring `ai-sdk-major`'s. obsidian's `packages/obsidian-vault-core` is
+  // React-free, carries no basalt-ui dependency, and sits outside the root's declared
+  // `basalt.roots` — so it CANNOT import the export it was told it had forked. The rule reported
+  // `SlugTracker` there anyway, because it was the one rule in this file that never asked.
+  it('does NOT flag a package that does not depend on basalt-ui at all', () => {
+    writeFileSync(resolve(dir, 'package.json'), JSON.stringify({ name: 'standalone' }))
+    const { code, rules } = run(`export function EmptyState() { return null }\n`)
+    expect(code).toBe(0)
+    expect(rules).not.toContain('shadow-basalt-export')
+  })
+
+  it('does NOT flag a file outside a declared basalt.roots', () => {
+    writeFileSync(
+      resolve(dir, 'package.json'),
+      JSON.stringify({
+        basalt: { roots: ['packages/ui/src'] },
+        devDependencies: { 'basalt-ui': '^1.21.0' },
+      }),
+    )
+    expect(
+      run(`export function EmptyState() { return null }\n`, 'packages/core/src/a.tsx').rules,
+    ).not.toContain('shadow-basalt-export')
+    // …and the declared root is still policed, so the narrowing costs no real coverage.
+    expect(
+      run(`export function EmptyState() { return null }\n`, 'packages/ui/src/a.tsx').rules,
+    ).toContain('shadow-basalt-export')
+  })
+
+  // The second half: a PascalCase name is not a component. The nine-barrel widening pulled every
+  // PascalCase value export into range, and a bare-PascalCase test then matched a plain data class
+  // (obsidian's `SlugTracker` — the same NAME basalt's `./content` exports, and nothing else).
+  it('does NOT flag a plain class that merely shares a name', () => {
+    const { code, rules } = run(`export class SlugTracker {}\n`, 'slug.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('shadow-basalt-export')
+  })
+
+  it('DOES still flag a legacy class component (one that extends)', () => {
+    const { rules } = run(`export class EmptyState extends Component {}\n`)
+    expect(rules).toContain('shadow-basalt-export')
+  })
+
+  it('does NOT flag a non-function binding that shares a name', () => {
+    const { code, rules } = run(`export const EmptyState = { label: 'none' }\n`, 'consts.ts')
+    expect(code).toBe(0)
+    expect(rules).not.toContain('shadow-basalt-export')
+  })
+
+  it('DOES still flag a memo/forwardRef-wrapped component', () => {
+    expect(run(`export const EmptyState = memo(() => null)\n`).rules).toContain(
+      'shadow-basalt-export',
+    )
+    expect(run(`export const EmptyState = React.forwardRef(() => null)\n`).rules).toContain(
+      'shadow-basalt-export',
+    )
+  })
+})
+
+// ── theme-allow shape grid (the plugin half of the annotation contract) ──────
+
+/**
+ * The plugin's copy of the grid pinned in `src/guard/check-source.test.ts`, row name for row name.
+ *
+ * Five holes in four rounds, twice because the two parsers disagreed about what an annotation IS —
+ * so the shapes are enumerated over the axes that vary (comment style × token position × where the
+ * closer falls × what follows), not collected as anecdotes. Every row here has a twin there; the
+ * guard-only dialects (CSS continuation lines, HTML, the JSON member form) have no twin because
+ * oxlint never parses those files.
+ *
+ * `no-raw-font-size` is the vehicle — a JSXAttribute rule, so the reported node's line is exactly
+ * the line an annotation has to reach.
+ */
+/** Wraps JSX children in a component, so a `{/* … *\/}` child is legal source. */
+const jsxShape = (body: string): string =>
+  `export const C = () => (\n  <div>\n${body}\n  </div>\n)\n`
+
+describe('theme-allow shape grid', () => {
+  const REASON = 'deliberate legacy value'
+  const A = `theme-allow no-raw-font-size — ${REASON}`
+  const AF = `theme-allow-file no-raw-font-size — ${REASON}`
+  const T = `<Text fz={10} />`
+  const J = jsxShape
+
+  const waives = (source: string): boolean => !run(source).rules.has('no-raw-font-size')
+
+  it.each([
+    ['// own line', `// ${A}\nexport const C = ${T}\n`],
+    ['// indented', `function f() {\n  // ${A}\n  return ${T}\n}\n`],
+    ['// no space after the marker', `//${A}\nexport const C = ${T}\n`],
+    ['// trailing', `export const C = ${T} // ${A}\n`],
+    [
+      '// reason wrapped onto a second // comment',
+      `// ${A},\n// continued here\nexport const C = ${T}\n`,
+    ],
+    ['/* */ own line', `/* ${A} */\nexport const C = ${T}\n`],
+    ['/* */ trailing', `export const C = ${T} /* ${A} */\n`],
+    ['/** */ own line (docblock opener)', `/** ${A} */\nexport const C = ${T}\n`],
+    ['/* opener + token, closer on its own line', `/* ${A}\n*/\nexport const C = ${T}\n`],
+    ['/* gutter token, closer on the token line', `/*\n ${A} */\nexport const C = ${T}\n`],
+    ['/* gutter token, closer on its own line', `/*\n ${A}\n*/\nexport const C = ${T}\n`],
+    ['/** star gutter, closer on the token line', `/**\n * ${A} */\nexport const C = ${T}\n`],
+    ['/** star gutter, closer on its own line', `/**\n * ${A}\n */\nexport const C = ${T}\n`],
+    ['/** token then 1 prose line', `/**\n * ${A}\n * more\n */\nexport const C = ${T}\n`],
+    [
+      '/** token then 12 prose lines',
+      `/**\n * ${A}\n${' * p\n'.repeat(12)} */\nexport const C = ${T}\n`,
+    ],
+    [
+      '/** prose first, token on a later gutter line',
+      `/**\n * some prose\n * ${A}\n */\nexport const C = ${T}\n`,
+    ],
+    ['{/* */} own line', J(`    {/* ${A} */}\n    ${T}`)],
+    ['{/* */} trailing on the target line', J(`    ${T} {/* ${A} */}`)],
+    ['{/* opener + token, closer on its own line', J(`    {/* ${A}\n    */}\n    ${T}`)],
+    ['{/* gutter token, closer on the token line', J(`    {/*\n      ${A} */}\n    ${T}`)],
+    ['{/* gutter token, closer on its own line', J(`    {/*\n      ${A}\n    */}\n    ${T}`)],
+    ['{/** star gutter, closer on the token line', J(`    {/**\n     * ${A} */}\n    ${T}`)],
+    ['{/** star gutter, closer on its own line', J(`    {/**\n     * ${A}\n     */}\n    ${T}`)],
+    [
+      '{/** token then 6 prose lines',
+      J(`    {/**\n     * ${A}\n${'     * p\n'.repeat(6)}     */}\n    ${T}`),
+    ],
+    ['{/* target on the closer line', J(`    {/*\n      ${A}\n    */}${T}`)],
+    ['{/* closer alone, tab indented', J(`\t{/*\n\t  ${A}\n\t*/}\n\t${T}`)],
+    ['{/* closer alone, space between */ and }', J(`    {/*\n      ${A}\n    */ }\n    ${T}`)],
+    [
+      '{/* closer alone, two annotations in one block',
+      J(`    {/*\n      ${A}\n      theme-allow card-inset — ${REASON}\n    */}\n    ${T}`),
+    ],
+    [
+      '/** */ then an unrelated // note',
+      `/** ${A} */\n// an unrelated note\nexport const C = ${T}\n`,
+    ],
+    ['{/* */} then an unrelated {/* */}', J(`    {/* ${A} */}\n    {/* unrelated */}\n    ${T}`)],
+    ['theme-allow-file, {/* closer on its own line', J(`    {/*\n      ${AF}\n    */}\n    ${T}`)],
+    ['theme-allow-file, /** star gutter', `/**\n * ${AF}\n */\nexport const C = ${T}\n`],
+  ])('%s waives', (_name, source) => {
+    expect(waives(source as string)).toBe(true)
+  })
+
+  // ── UNSUPPORTED — asserted, so a hole can never pass for a design decision ──
+  it.each([
+    ['blank line after a // annotation', `// ${A}\n\nexport const C = ${T}\n`],
+    ['blank line after a {/* */} annotation', J(`    {/* ${A} */}\n\n    ${T}`)],
+    [
+      'blank line after a {/* closer on its own line',
+      J(`    {/*\n      ${A}\n    */}\n\n    ${T}`),
+    ],
+    ['mid-sentence in a line comment', `// we normally write a ${A} here\nexport const C = ${T}\n`],
+    [
+      'mid-sentence in a docblock gutter',
+      `/**\n * Each value is escaped with a ${A} annotation.\n */\nexport const C = ${T}\n`,
+    ],
+    [
+      'mid-sentence in a JSX expression comment',
+      J(`    {/* the shape here is a ${A} comment */}\n    ${T}`),
+    ],
+    [
+      'inside a string literal',
+      `const doc = 'theme-allow no-raw-font-size'\nexport const C = ${T}\n`,
+    ],
+    ['above a multi-line opening tag', J(`    {/* ${A} */}\n    <Text\n      fz={10}\n    />`)],
+  ])('%s does NOT waive', (_name, source) => {
+    expect(waives(source as string)).toBe(false)
+  })
 })
 
 // ── hand-rolled-shell ────────────────────────────────────────────────────────