basalt-ui 1.29.2 → 1.30.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,
+  WAIVER_ID_ALIASES,
   DEPRECATED_EXPORTS,
   KNOWN_RULE_IDS,
   PLUGIN_RULE_ADVISORY,
@@ -21,7 +22,11 @@ import basaltPlugin, {
   RETIRED_RULE_IDS,
 } from './oxlint-plugin.js'
 import { CTL_THEME } from '../src/theme/ctl-theme'
-import { GUARD_RULES, PLUGIN_RULE_IDS } from '../src/guard/index.ts'
+import {
+  GUARD_RULES,
+  PLUGIN_RULE_IDS,
+  WAIVER_ID_ALIASES as GUARD_WAIVER_ID_ALIASES,
+} from '../src/guard/index.ts'
 import { PLUGIN_RULE_ID_LIST, SURFACES } from '../src/surfaces.ts'
 
 const PLUGIN_PATH = resolve(import.meta.dirname, 'oxlint-plugin.js')
@@ -1547,6 +1552,37 @@ describe('KNOWN_RULE_IDS', () => {
   })
 })
 
+// ── one law, two rule ids ──────────────────────────────────────────────────────────────────────
+
+/**
+ * `basalt/control-outside-home` and the guard's `raw-selection-control` are the SAME law read by
+ * two engines — the guard's own message says so — and a waiver naming either used to silence only
+ * the lane whose id it spelled. The working annotation was `theme-allow raw-selection-control
+ * control-outside-home`: two ids, undocumented, one silent debug cycle per consumer.
+ */
+describe('WAIVER_ID_ALIASES', () => {
+  it('is identical in both lanes', () => {
+    expect(WAIVER_ID_ALIASES).toEqual(GUARD_WAIVER_ID_ALIASES)
+  })
+
+  it('names only ids both registries know', () => {
+    for (const [id, aliases] of Object.entries(WAIVER_ID_ALIASES)) {
+      expect([id, KNOWN_RULE_IDS.has(id)]).toEqual([id, true])
+      for (const alias of aliases) expect([alias, KNOWN_RULE_IDS.has(alias)]).toEqual([alias, true])
+    }
+  })
+
+  it('waives the plugin rule under the TEXT lane’s id', () => {
+    const { code, rules } = run(
+      `import { Select } from '@mantine/core'\nexport const C = () => (\n  <div>\n` +
+        `    {/* theme-allow raw-selection-control — the Tauri header has no shell */}\n` +
+        `    <Select data={[]} />\n  </div>\n)\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('control-outside-home')
+  })
+})
+
 // ── theme-allow fails closed on a typo ─────────────────────────────────────────────────────────
 
 describe('theme-allow with an unrecognized rule id', () => {
@@ -1605,6 +1641,23 @@ const MANTINE_IMPORT = `import { Button, ScrollArea, SegmentedControl, Select }
 const BASALT_IMPORT = `import { ChartCard, PageBar, Section, SettingsSection } from 'basalt-ui'\n`
 
 describe('basalt/hand-rolled-filter', () => {
+  /**
+   * The deliberate consequence of teaching the slot resolver to read an object spread: a slot IS a
+   * slot in either spelling, so a raw Mantine control conditionally spread into one moves from
+   * `control-outside-home` (warn, and the WRONG verdict — it does have a home) to this rule
+   * (error, and the right one). One home model or none; a spread that is a home for the rule that
+   * exempts and not for the rule that polices is the silent half-application this wave removes.
+   */
+  it('flags a raw Select handed to a slot written as an object spread', () => {
+    const { code, rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = ({ cond }) => (\n` +
+        `  <Section {...(cond && { filters: <Select data={[]} /> })}>body</Section>\n)\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('hand-rolled-filter')
+    expect(rules).not.toContain('control-outside-home')
+  })
+
   it('flags a raw Mantine Select handed to a PageBar filters slot', () => {
     const { code, rules } = run(
       `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = () => <PageBar filters={<Select data={[]} />} />\n`,
@@ -2208,9 +2261,81 @@ describe('basalt/bound-control-outside-home', () => {
     )
     expect(rules).toContain('bound-control-outside-home')
   })
+
+  /**
+   * A slot written as an OBJECT SPREAD is the same home as a slot written as a JSXAttribute — and
+   * `exactOptionalPropertyTypes` FORCES the spread, because `tabs={cond ? <X/> : undefined}` is not
+   * assignable to an optional prop. Every control rule resolved homes off JSXAttribute nodes alone,
+   * so a strict consumer's conditional slot was a false positive on a rule scheduled to go `error`.
+   */
+  describe('a slot written as an object spread', () => {
+    it.each([
+      '{...(cond && { tabs: <SelectFilter field={f} /> })}',
+      '{...(cond ? { tabs: <SelectFilter field={f} /> } : {})}',
+      '{...{ filters: <SelectFilter field={f} /> }}',
+    ])('does NOT flag %s on a Section', (spread) => {
+      const { code, rules } = run(
+        `${ASIDE_IMPORT}${CONTROLS_IMPORT}export const C = ({ cond }) => (\n  <Section ${spread}>body</Section>\n)\n`,
+      )
+      expect(code).toBe(0)
+      expect(rules).not.toContain('bound-control-outside-home')
+    })
+
+    it('does NOT flag a hoisted binding handed to a spread slot', () => {
+      const { rules } = run(
+        `${ASIDE_IMPORT}${CONTROLS_IMPORT}const tabs = <SelectFilter field={f} />\n` +
+          `export const C = ({ cond }) => <Section {...(cond && { tabs })}>body</Section>\n`,
+      )
+      expect(rules).not.toContain('bound-control-outside-home')
+    })
+
+    // Deliberately narrow: only a Property reaching a JSXSpreadAttribute through object / `&&` /
+    // `?:` nodes is claimed. A non-slot key, and an object built anywhere else, are not homes.
+    it('still flags a non-slot key in the same spread', () => {
+      const { rules } = run(
+        `${ASIDE_IMPORT}${CONTROLS_IMPORT}export const C = ({ cond }) => (\n` +
+          `  <Section {...(cond && { footer: <SelectFilter field={f} /> })}>body</Section>\n)\n`,
+      )
+      expect(rules).toContain('bound-control-outside-home')
+    })
+
+    it('still flags a slot-shaped object built inside a .map() callback', () => {
+      const { rules } = run(
+        `${CONTROLS_IMPORT}export const C = () => [1].map((k) => ({ tabs: <SelectFilter field={f} /> }))\n`,
+      )
+      expect(rules).toContain('bound-control-outside-home')
+    })
+
+    it('still flags one on a tag that is not a slot owner', () => {
+      const { rules } = run(
+        `import { Stack } from '@mantine/core'\n${CONTROLS_IMPORT}export const C = ({ cond }) => (\n` +
+          `  <Stack {...(cond && { tabs: <SelectFilter field={f} /> })} />\n)\n`,
+      )
+      expect(rules).toContain('bound-control-outside-home')
+    })
+  })
+
+  it('names PageBar as the reachable home for a shell-less app', () => {
+    const { output } = run(
+      `import { Stack } from '@mantine/core'\n${CONTROLS_IMPORT}` +
+        `export const C = () => (\n  <Stack>\n    <SelectFilter field={f} />\n  </Stack>\n)\n`,
+    )
+    expect(output).toContain('PageBar` needs no `BasaltShell`')
+  })
 })
 
 describe('basalt/control-size-literal', () => {
+  // Same widening as `hand-rolled-filter` above, for the same reason: a slot is a slot in either
+  // spelling, and the tier the message promises is mounted by the slot however it was written.
+  it('flags a size prop inside a slot written as an object spread', () => {
+    const { code, rules } = run(
+      `${BASALT_IMPORT}${MANTINE_IMPORT}export const C = ({ cond }) => (\n` +
+        `  <Section {...(cond && { actions: <Button size="xs">Go</Button> })}>body</Section>\n)\n`,
+    )
+    expect(code).toBe(1)
+    expect(rules).toContain('control-size-literal')
+  })
+
   it.each(['size="xs"', 'w={200}', 'fullWidth', 'visibleFrom="sm"', 'hiddenFrom="sm"'])(
     'flags %s on an element inside a home slot',
     (prop) => {
@@ -2554,6 +2679,43 @@ describe('basalt/in-body-page-title', () => {
     )
     expect(rules).not.toContain('in-body-page-title')
   })
+
+  // The narrowing that made C8 satisfiable — the law is "one NAME per page", and a name is
+  // written in words. rb hit both of these shapes 24 times across 12 files with no legal fix.
+  it('does NOT flag a nav-less detail route rendering the document title', () => {
+    const { code, rules } = run(
+      `export const C = ({ knot }) => <Title order={1}>{knot.title}</Title>\n`,
+    )
+    expect(code).toBe(0)
+    expect(rules).not.toContain('in-body-page-title')
+  })
+
+  it("does NOT flag a card's hero VALUE at order={2}", () => {
+    const { rules } = run(`export const C = ({ g }) => <Title order={2}>{RANK[g.rank]}</Title>\n`)
+    expect(rules).not.toContain('in-body-page-title')
+  })
+
+  // The escape is the EXPRESSION, not the braces: a literal laundered through `{…}` is still a
+  // static page name, and so is a substitution-free template.
+  it.each([`{'Users'}`, '{`Users`}'])('still flags a laundered literal %s', (child) => {
+    const { rules } = run(`export const C = () => <Title order={1}>${child}</Title>\n`)
+    expect(rules).toContain('in-body-page-title')
+  })
+
+  it('still flags a name with a value interpolated into it', () => {
+    const { rules } = run(`export const C = ({ n }) => <Title order={1}>Users {n}</Title>\n`)
+    expect(rules).toContain('in-body-page-title')
+  })
+
+  it('still flags a name nested one element deep', () => {
+    const { rules } = run(`export const C = () => <Title order={1}><span>Users</span></Title>\n`)
+    expect(rules).toContain('in-body-page-title')
+  })
+
+  it('names PageTitle as the shell-less answer', () => {
+    const { output } = run(`export const C = () => <Title order={1}>Page</Title>\n`)
+    expect(output).toContain('<PageTitle>')
+  })
 })
 
 describe('basalt/responsive-twin', () => {
@@ -3170,16 +3332,31 @@ describe('basalt/forms-field-key', () => {
     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.
+  // The second message: reported whether or not the element carries a key — 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(
+    const { code, rules } = 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')
+  })
+
+  /**
+   * The message has to state the version it is RUNNING at, not the one the deprecation was
+   * scheduled in. It used to say the alias "still bundles `key` INTO the returned object" and "is
+   * removed in 1.29.0" while running AT 1.29.x, where `field` no longer exists at all — a consumer
+   * reading it concluded nothing was broken, on a call site that does not compile.
+   */
+  it('says `field` no longer exists, not that it is merely deprecated', () => {
+    const { output } = run(
+      `import { field } from 'basalt-ui/forms'\n` +
+        `export const C = () => <TextInput {...field(form, 'email')} />\n`,
+    )
+    expect(output).toContain('NO LONGER EXISTS')
+    expect(output).toContain('does not compile')
+    expect(output).not.toContain('still bundles')
   })
 
   it('honours a theme-allow naming the rule', () => {

package/configs/oxlint.json

@@ -34,17 +34,17 @@
     "basalt/raw-scroll-container": "error",
     "basalt/hand-rolled-filter": "error",
     "basalt/control-outside-home": "warn",
-    "basalt/bound-control-outside-home": "warn",
+    "basalt/bound-control-outside-home": "error",
     "basalt/control-size-literal": "error",
     "basalt/page-bar-budget": "error",
     "basalt/in-body-page-title": "error",
     "basalt/responsive-twin": "error",
     "basalt/search-literal-link": "error",
     "basalt/use-search-from-literal": "error",
-    "basalt/provider-above-router": "warn",
-    "basalt/query-fn-unwrap": "warn",
+    "basalt/provider-above-router": "error",
+    "basalt/query-fn-unwrap": "error",
     "basalt/deprecated-export": "warn",
-    "basalt/forms-field-key": "warn",
+    "basalt/forms-field-key": "error",
     "basalt/visx-boundary": "error",
     "basalt/visx-tooltip": "error",
     "basalt/agent-resume-guard": "error",

package/dist/charts/primitives/ChartCard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChartCard.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/ChartCard.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAErD,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAGtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAEhE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAqChD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEtD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,WAAW,GACtC,eAAe,CAAC,aAAa,CAAC,GAAG;IAC/B,mGAAmG;IACnG,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,0DAA0D;IAC1D,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,gGAAgG;IAChG,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;8FAC0F;IAC1F,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;kEAC8D;IAC9D,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,+FAA+F;IAC/F,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,8FAA8F;IAC9F,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;sDACkD;IAClD,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;oGACgG;IAChG,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB,CAAA;AAEH,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,KAAK,EACL,WAAW,EACX,aAAa,EACb,KAAK,EACL,OAAO,EACP,KAAK,EACL,iBAAuB,EACvB,WAAW,EACX,SAAS,EACT,UAAU,EACV,KAAK,EACL,QAAQ,GACT,EAAE,cAAc,+BAgEhB"}
+{"version":3,"file":"ChartCard.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/ChartCard.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAErD,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAGtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAA;AAEhE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AA0ChD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEtD;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,cAAc,GAAG,WAAW,GACtC,eAAe,CAAC,aAAa,CAAC,GAAG;IAC/B,mGAAmG;IACnG,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,0DAA0D;IAC1D,IAAI,CAAC,EAAE,SAAS,CAAA;IAChB,gGAAgG;IAChG,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;8FAC0F;IAC1F,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,uEAAuE;IACvE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,iEAAiE;IACjE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;kEAC8D;IAC9D,aAAa,CAAC,EAAE,aAAa,CAAA;IAC7B,sCAAsC;IACtC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,+FAA+F;IAC/F,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,8FAA8F;IAC9F,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B;sDACkD;IAClD,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;oGACgG;IAChG,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB,CAAA;AAEH,wBAAgB,SAAS,CAAC,EACxB,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,KAAK,EACL,KAAK,EACL,WAAW,EACX,aAAa,EACb,KAAK,EACL,OAAO,EACP,KAAK,EACL,iBAAuB,EACvB,WAAW,EACX,SAAS,EACT,UAAU,EACV,KAAK,EACL,QAAQ,GACT,EAAE,cAAc,+BAgEhB"}

package/dist/charts/primitives/ChartCard.js

@@ -17,10 +17,10 @@ const bodyClipStyle = {
   borderBottomLeftRadius: VX.radiusCard,
   borderBottomRightRadius: VX.radiusCard,
   overflow: "hidden",
-  padding: "2px var(--mantine-spacing-sm, 0.8125rem) var(--mantine-spacing-xs, 0.6875rem)"
+  padding: "2px var(--vx-space-card-inset-x, 0.8125rem) var(--vx-space-card-inset-y, 0.6875rem)"
 };
 const headerWrapStyle = {
-  padding: "var(--mantine-spacing-xs, 0.6875rem) var(--mantine-spacing-sm, 0.8125rem) 4px"
+  padding: "var(--vx-space-card-inset-y, 0.6875rem) var(--vx-space-card-inset-x, 0.8125rem) 4px"
 };
 function ChartCard({
   title,

package/dist/charts/primitives/ChartFrame.d.ts

@@ -1,16 +1,28 @@
 import type { ReactNode } from 'react';
 import type { BasaltProps } from '../../common/props.js';
 import type { ChartLegendConfig, LegendPlacement, SeriesStyle } from '../series.js';
+import type { ResponsiveChartHeight } from './chart-frame-layout.js';
 import type { ChartState } from './ChartPending.js';
 /** Re-exported for `ChartFrame.test.tsx` and any other consumer that previously reached these
  * through `ChartFrame` — the layout math itself lives in `./chart-frame-layout` (pure, DOM-free). */
 export { legendEntryCap, resolvePlotRect, resolveChartTier } from './chart-frame-layout.js';
+export type { ResponsiveChartHeight } from './chart-frame-layout.js';
 /** Legend configuration for {@link ChartFrame}. Omit entirely (or pass `{}`) for the default
  * bottom-placed legend; pass `false` only for the sparkline exemption. */
 export type ChartFrameLegend = {
     /** Default 'bottom'. */
     placement?: LegendPlacement;
-    /** Wrap cap → "+N more" rollup at high cardinality. */
+    /**
+     * Wrap cap → "+N more" rollup at high cardinality.
+     *
+     * An explicit value WINS OUTRIGHT — including over the phone tier's own two-row default
+     * (`chartTierMetrics`). It used to be `Math.min`'d against the tier, which made the documented
+     * per-chart opt-out ("opt back out with an explicit `legend.maxRows`") false in the one direction
+     * anybody needs it: a consumer's 380px inspector panel is "a phone" on a 1440px desktop, and a
+     * six-series legend rolled up to `+4 more` with no way to say no. Under `fill` the measured
+     * entry cap can still roll up FURTHER — that is a floor on the plot, not a tier default
+     * ({@link legendEntryCap}).
+     */
     maxRows?: number;
     /** Visually separate role: series | overlay | reference. */
     groups?: boolean;
@@ -28,8 +40,16 @@ export type ChartFrameLegend = {
 export type ChartFrameProps = BasaltProps & {
     /** Series identity — drives the derived legend. Pass the SAME array the kind draws + tooltips from. */
     series: readonly SeriesStyle[];
-    /** Fixed height in pixels. Used when neither `aspectRatio` nor `fill` is set. Default 240. */
-    height?: number;
+    /**
+     * Height in pixels, or one per size step. Used when neither `aspectRatio` nor `fill` is set.
+     * Default 240.
+     *
+     * `{ base: 180, md: 260 }` is the declarative escape from a page of fixed-height charts: the
+     * steps are compared against the frame's own MEASURED width, not the viewport, so a chart squeezed
+     * by a `PageAside` gets the short height on a desktop too. A plain number is unchanged and stays
+     * supported ({@link resolveFrameHeight}).
+     */
+    height?: number | ResponsiveChartHeight;
     /** height = Math.round(containerWidth / aspectRatio). Ignored when `fill` is set. */
     aspectRatio?: number;
     /** Fill the parent flex/grid cell's measured height instead of a fixed/derived one. */

package/dist/charts/primitives/ChartFrame.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ChartFrame.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/ChartFrame.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAErD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAIrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAUhF,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAEhD;qGACqG;AACrG,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAKxF;0EAC0E;AAC1E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,wBAAwB;IACxB,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IAC1C;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG;IAC1C,uGAAuG;IACvG,MAAM,EAAE,SAAS,WAAW,EAAE,CAAA;IAC9B,8FAA8F;IAC9F,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uFAAuF;IACvF,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,gBAAgB,GAAG,KAAK,CAAA;IACjC;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;oDACgD;IAChD,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,SAAS,CAAA;CACxC,CAAA;AAED,0FAA0F;AAC1F,MAAM,MAAM,QAAQ,GAAG;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAC5B,CAAA;AAcD;oFACoF;AACpF,MAAM,MAAM,qBAAqB,GAAG;IAClC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;CAC1C,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,iBAAiB,GAAG,KAAK,GAAG,SAAS,EAC7C,KAAK,CAAC,EAAE,qBAAqB,EAC7B,WAAW,CAAC,EAAE,MAAM,GACnB,gBAAgB,GAAG,KAAK,CAU1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,EACzB,MAAM,EACN,MAAM,EACN,WAAW,EACX,IAAY,EACZ,QAA4B,EAC5B,OAAO,EACP,MAAW,EACX,SAAS,EACT,SAAiB,EACjB,KAAK,EACL,SAAS,EACT,KAAK,EACL,QAAQ,GACT,EAAE,eAAe,GAAG,SAAS,CAmH7B"}
+{"version":3,"file":"ChartFrame.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/ChartFrame.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,SAAS,EAAE,MAAM,OAAO,CAAA;AAErD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAIrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,WAAW,CAAA;AAQhF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAIjE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAEhD;qGACqG;AACrG,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AACxF,YAAY,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAA;AAKjE;0EAC0E;AAC1E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,wBAAwB;IACxB,SAAS,CAAC,EAAE,eAAe,CAAA;IAC3B;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,4DAA4D;IAC5D,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,wDAAwD;IACxD,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;IAC1C;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG,WAAW,GAAG;IAC1C,uGAAuG;IACvG,MAAM,EAAE,SAAS,WAAW,EAAE,CAAA;IAC9B;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,qBAAqB,CAAA;IACvC,qFAAqF;IACrF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uFAAuF;IACvF,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,6FAA6F;IAC7F,MAAM,CAAC,EAAE,gBAAgB,GAAG,KAAK,CAAA;IACjC;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB;oDACgD;IAChD,QAAQ,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,SAAS,CAAA;CACxC,CAAA;AAED,0FAA0F;AAC1F,MAAM,MAAM,QAAQ,GAAG;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CAC5B,CAAA;AAcD;oFACoF;AACpF,MAAM,MAAM,qBAAqB,GAAG;IAClC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAA;IAC1B,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,CAAA;CAC1C,CAAA;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,iBAAiB,GAAG,KAAK,GAAG,SAAS,EAC7C,KAAK,CAAC,EAAE,qBAAqB,EAC7B,WAAW,CAAC,EAAE,MAAM,GACnB,gBAAgB,GAAG,KAAK,CAU1B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,UAAU,CAAC,EACzB,MAAM,EACN,MAAM,EACN,WAAW,EACX,IAAY,EACZ,QAA4B,EAC5B,OAAO,EACP,MAAW,EACX,SAAS,EACT,SAAiB,EACjB,KAAK,EACL,SAAS,EACT,KAAK,EACL,QAAQ,GACT,EAAE,eAAe,GAAG,SAAS,CA6G7B"}

package/dist/charts/primitives/ChartFrame.js

@@ -4,9 +4,10 @@ import { VX } from "../../tokens/index.js";
 import { useChartSize } from "../hooks/useChartSize.js";
 import { deriveLegend } from "../series.js";
 import {
-  chartTierMetrics,
   legendEntryCap,
   resolveChartTier,
+  resolveFrameHeight,
+  resolveLegendMaxRows,
   resolvePlotRect
 } from "./chart-frame-layout.js";
 import { ChartTierProvider } from "./chart-tier.js";
@@ -67,7 +68,7 @@ function ChartFrame({
   const resolvedState = resolveChartState({ ...state !== void 0 && { state }, isPending });
   const legendVisible = legend !== false && resolvedState === null;
   const tier = resolveChartTier(containerW);
-  const resolvedHeight = fill ? containerH : aspectRatio !== void 0 ? Math.round(containerW / aspectRatio) : height ?? DEFAULT_HEIGHT;
+  const resolvedHeight = fill ? containerH : aspectRatio !== void 0 ? Math.round(containerW / aspectRatio) : resolveFrameHeight(height ?? DEFAULT_HEIGHT, containerW);
   const sideLegendWidth = legendVisible && vertical ? legendW : 0;
   const topBottomLegendHeight = legendVisible && !vertical ? legendH : 0;
   const plot = resolvePlotRect({
@@ -79,8 +80,7 @@ function ChartFrame({
   });
   const legendItems = legend === false ? [] : deriveLegend(series);
   const togglable = legend !== false && (legend.toggle ?? legendItems.length > 1);
-  const tierMaxRows = chartTierMetrics(tier).legendMaxRows;
-  const callerMaxRows = legend === false ? void 0 : legend.maxRows === void 0 ? tierMaxRows : tierMaxRows === void 0 ? legend.maxRows : Math.min(legend.maxRows, tierMaxRows);
+  const callerMaxRows = legend === false ? void 0 : resolveLegendMaxRows({ callerMaxRows: legend.maxRows, tier });
   const maxRows = legend === false ? void 0 : fill && !vertical ? legendEntryCap({
     items: legendItems,
     containerW,

package/dist/charts/primitives/chart-frame-layout.d.ts

@@ -24,6 +24,42 @@ export type ChartTier = 'phone' | 'desktop';
  * later, and `resolvePlotRect` already treats an unmeasured width as the first-frame case.
  */
 export declare function resolveChartTier(containerW: number): ChartTier;
+/**
+ * A chart height stated per size step instead of as one number — the declarative escape from "every
+ * chart on this page is 260px tall on a 375px phone too".
+ *
+ * `base` is required and is the height a box narrower than every named step gets; each further key
+ * is the height from that step UP. Keys are Mantine's breakpoint names so a consumer writes the
+ * vocabulary they already write, and nothing more than `sm`/`md`/`lg` is offered: `xs`/`xl` would
+ * be two more rungs nobody has asked a chart to have.
+ *
+ * ```tsx
+ * <ChartFrame series={series} height={{ base: 180, md: 260 }}>{…}</ChartFrame>
+ * ```
+ */
+export type ResponsiveChartHeight = {
+    /** Below the narrowest STATED step — and NOT the first-frame value; see {@link resolveFrameHeight}. */
+    base: number;
+    /** From 768px of MEASURED container width up. */
+    sm?: number;
+    /** From 992px up. */
+    md?: number;
+    /** From 1200px up. */
+    lg?: number;
+};
+/**
+ * Resolve a `height` prop — a plain number, or a {@link ResponsiveChartHeight} — against the
+ * measured container width.
+ *
+ * A plain number passes through untouched: this is a WIDENING of the prop, not a replacement, and
+ * every existing `height={240}` must keep meaning exactly 240.
+ *
+ * An UNMEASURED box (`containerW <= 0` — SSR, or before the `ResizeObserver`'s first callback)
+ * resolves to the LARGEST stated step, matching {@link resolveChartTier}'s first-frame rule: the
+ * first paint must not be phone-shaped chrome that grows one frame later. Falling to `base` there
+ * would make every SSR'd chart short and then jump.
+ */
+export declare function resolveFrameHeight(height: number | ResponsiveChartHeight, containerW: number): number;
 /** Every size a chart's chrome resolves per tier. One object so a new tier-sensitive size is added
  * in one place and read by name, rather than each primitive branching on the tier itself. */
 export type ChartTierMetrics = {
@@ -46,6 +82,25 @@ export type ChartTierMetrics = {
 };
 /** The resolved sizes for one tier. Frozen module constants — never a new object per render. */
 export declare function chartTierMetrics(tier: ChartTier): ChartTierMetrics;
+/**
+ * Which legend cap applies: the caller's, or the tier's own default.
+ *
+ * **An explicit `callerMaxRows` wins OUTRIGHT.** This used to be `Math.min(caller, tier)`, which
+ * made the documented per-chart opt-out ("opt back out with an explicit `legend.maxRows`") false in
+ * the one direction anybody needs it. The tier's `PHONE_LEGEND_MAX_ROWS` is a DEFAULT for charts
+ * that said nothing — a chart that names a number has already answered the question the default
+ * exists to answer, and it matters because the tier keys on the measured box: a 380px inspector
+ * panel on a 1440px desktop is "a phone", so a six-series legend rolled up to two rows + `+4 more`
+ * with no way to say no. `margin` and `xLabelRotate` always had that escape; the legend did not.
+ *
+ * A `fill` frame's measured {@link legendEntryCap} still applies ON TOP of whatever wins here — it
+ * is a floor on the PLOT, not a tier default, so a chart that would otherwise render no plot at all
+ * still rolls up.
+ */
+export declare function resolveLegendMaxRows(input: {
+    callerMaxRows?: number | undefined;
+    tier: ChartTier;
+}): number | undefined;
 /**
  * Resolve the plot rect from the measured box and the measured legend band. Pure and exported so
  * the two floors below are testable without a `ResizeObserver`.

package/dist/charts/primitives/chart-frame-layout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chart-frame-layout.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/chart-frame-layout.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAUhD;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,CAAA;AAE3C;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAE9D;AAqBD;6FAC6F;AAC7F,MAAM,MAAM,gBAAgB,GAAG;IAC7B,2FAA2F;IAC3F,IAAI,EAAE,SAAS,CAAA;IACf;uFACmF;IACnF,QAAQ,EAAE,MAAM,CAAA;IAChB,kCAAkC;IAClC,cAAc,EAAE,MAAM,CAAA;IACtB,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,uCAAuC;IACvC,eAAe,EAAE,MAAM,CAAA;IACvB;yDACqD;IACrD,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,6EAA6E;IAC7E,MAAM,EAAE,WAAW,CAAA;CACpB,CAAA;AA6BD,gGAAgG;AAChG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,gBAAgB,CAElE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,UAAU,EAAE,MAAM,CAAA;IAClB,cAAc,EAAE,MAAM,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,eAAe,EAAE,MAAM,CAAA;IACvB,qBAAqB,EAAE,MAAM,CAAA;CAC9B,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAOpC;AAmCD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE;IACpC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAA;IAC7B,UAAU,EAAE,MAAM,CAAA;IAClB,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAA;IACjB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,GAAG,MAAM,GAAG,SAAS,CAerB"}
+{"version":3,"file":"chart-frame-layout.d.ts","sourceRoot":"","sources":["../../../src/charts/primitives/chart-frame-layout.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAA;AAUhD;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,CAAA;AAE3C;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAE9D;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC,uGAAuG;IACvG,IAAI,EAAE,MAAM,CAAA;IACZ,iDAAiD;IACjD,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,qBAAqB;IACrB,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,sBAAsB;IACtB,EAAE,CAAC,EAAE,MAAM,CAAA;CACZ,CAAA;AAiBD;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,GAAG,qBAAqB,EACtC,UAAU,EAAE,MAAM,GACjB,MAAM,CAQR;AAqBD;6FAC6F;AAC7F,MAAM,MAAM,gBAAgB,GAAG;IAC7B,2FAA2F;IAC3F,IAAI,EAAE,SAAS,CAAA;IACf;uFACmF;IACnF,QAAQ,EAAE,MAAM,CAAA;IAChB,kCAAkC;IAClC,cAAc,EAAE,MAAM,CAAA;IACtB,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,uCAAuC;IACvC,eAAe,EAAE,MAAM,CAAA;IACvB;yDACqD;IACrD,aAAa,EAAE,MAAM,GAAG,SAAS,CAAA;IACjC,6EAA6E;IAC7E,MAAM,EAAE,WAAW,CAAA;CACpB,CAAA;AA6BD,gGAAgG;AAChG,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,GAAG,gBAAgB,CAElE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAClC,IAAI,EAAE,SAAS,CAAA;CAChB,GAAG,MAAM,GAAG,SAAS,CAErB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE;IACrC,UAAU,EAAE,MAAM,CAAA;IAClB,cAAc,EAAE,MAAM,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,eAAe,EAAE,MAAM,CAAA;IACvB,qBAAqB,EAAE,MAAM,CAAA;CAC9B,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAOpC;AAmCD;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE;IACpC,KAAK,EAAE,SAAS,WAAW,EAAE,CAAA;IAC7B,UAAU,EAAE,MAAM,CAAA;IAClB,iFAAiF;IACjF,SAAS,EAAE,MAAM,CAAA;IACjB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,GAAG,MAAM,GAAG,SAAS,CAerB"}

package/dist/charts/primitives/chart-frame-layout.js

@@ -6,6 +6,17 @@ const LEGEND_SWATCH_W = 24;
 function resolveChartTier(containerW) {
   return containerW > 0 && containerW < VX.phoneChartWidth ? "phone" : "desktop";
 }
+const HEIGHT_STEP_WIDTH = { sm: 768, md: 992, lg: 1200 };
+const HEIGHT_STEPS = ["lg", "md", "sm"];
+function resolveFrameHeight(height, containerW) {
+  if (typeof height === "number") return height;
+  const widest = HEIGHT_STEPS.find((step2) => height[step2] !== void 0);
+  if (containerW <= 0) return widest === void 0 ? height.base : height[widest] ?? height.base;
+  const step = HEIGHT_STEPS.find(
+    (name) => containerW >= HEIGHT_STEP_WIDTH[name] && height[name] !== void 0
+  );
+  return step === void 0 ? height.base : height[step] ?? height.base;
+}
 const PHONE_MARGIN_SCALE = 0.75;
 const PHONE_DOT_R = Math.max(VX.dotR - 1, 2);
 const PHONE_LEGEND_MAX_ROWS = 2;
@@ -38,6 +49,9 @@ const PHONE_METRICS = {
 function chartTierMetrics(tier) {
   return tier === "phone" ? PHONE_METRICS : DESKTOP_METRICS;
 }
+function resolveLegendMaxRows(input) {
+  return input.callerMaxRows ?? chartTierMetrics(input.tier).legendMaxRows;
+}
 function resolvePlotRect(input) {
   const { containerW, resolvedHeight, minWidth, sideLegendWidth, topBottomLegendHeight } = input;
   return {
@@ -85,5 +99,7 @@ export {
   chartTierMetrics,
   legendEntryCap,
   resolveChartTier,
+  resolveFrameHeight,
+  resolveLegendMaxRows,
   resolvePlotRect
 };

package/dist/cli/check-theme.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"check-theme.d.ts","sourceRoot":"","sources":["../../src/cli/check-theme.ts"],"names":[],"mappings":"AA8BA;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,aAAa,GAAE,MAAsB,EACrC,KAAK,GAAE,SAAS,MAAM,EAAO,GAC5B,MAAM,CA2JR"}
+{"version":3,"file":"check-theme.d.ts","sourceRoot":"","sources":["../../src/cli/check-theme.ts"],"names":[],"mappings":"AA+BA;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,aAAa,GAAE,MAAsB,EACrC,KAAK,GAAE,SAAS,MAAM,EAAO,GAC5B,MAAM,CAuKR"}

package/dist/cli/check-theme.js

@@ -12,6 +12,7 @@ import {
   conflictingProfileFlags,
   declaredProfile,
   DEFAULT_ROOTS,
+  hasBasaltKey,
   readBasaltConfig,
   resolveExemptRules,
   resolveProjectDir,
@@ -69,6 +70,11 @@ function checkTheme(invocationCwd = process.cwd(), flags = []) {
     findings.push(...checkSource(readFileSync(resolve(cwd, rel), "utf8"), rel, guardCfg));
   }
   if (scanned.length === 0) {
+    if (!hasBasaltKey(cwd)) {
+      console.error(
+        `\u2716 basalt-ui check-theme: ${cwd}/package.json has no "basalt" key \u2014 very likely not the package you meant to scan (BASALT_CWD, else the invocation cwd; nothing is inferred). At a repo root? Give the command \`root: <pkg>/\` (lefthook) or \`working-directory: <pkg>\` (Actions), or set BASALT_CWD=<pkg>. If this directory IS it, run \`basalt-ui init\`.`
+      );
+    }
     if (cfg.roots === void 0) {
       console.error(
         `\u2716 basalt-ui check-theme: 0 files scanned \u2014 no "basalt.roots" configured in package.json, and the built-in default roots (${DEFAULT_ROOTS.join(", ")}) matched zero files. Set "basalt": { "roots": [...] } in package.json to point at your source directories.`

package/dist/cli/doctor.d.ts

@@ -15,16 +15,22 @@ export type DoctorResult = {
  * Check a consumer repo's basalt integration and print a pass/warn report.
  *
  * Narrowed to what a single-directory-scoped run can actually verify — no workspace-glob walking,
- * no ascend/descend project discovery (see {@link resolveProjectDir}). Four checks, numbered in
+ * no ascend/descend project discovery (see {@link resolveProjectDir}). Six checks, numbered in
  * the order they run and print:
  *
  * Hard failures (exit non-zero):
  *   1. `.basalt/manifest.json` exists (`basalt-ui init` was run).
- *   2. `oxlint-preset` ("rules in sync"): the consumer's `.oxlintrc.json` extends the shipped
+ *   2. `install-parity`: basalt-ui resolves, doctor prints WHERE and at what version, and that
+ *      version agrees with the manifest's `basaltVersion`.
+ *   3. `guard-scan`: `check-theme` would scan more than zero files, sharing `scannableFiles` so the
+ *      two cannot disagree. Both RESTORED in 1.30.0 after four minors gone with no MIGRATING row —
+ *      README § `doctor` carries what their absence cost (a no-op CI gate, a green guard scanning
+ *      nothing, and two basalt-WRITTEN docs describing output the CLI no longer produced).
+ *   4. `oxlint-preset` ("rules in sync"): the consumer's `.oxlintrc.json` extends the shipped
  *      preset AND that path resolves. `init` keeps an existing config, so the framework's whole
  *      lint half can be silently off — one repo carried six real violations invisibly across five
  *      minors this way.
- *   4. `ai-major-parity`: within THIS package.json, `dependencies`/`devDependencies`/
+ *   6. `ai-major-parity`: within THIS package.json, `dependencies`/`devDependencies`/
  *      `peerDependencies` agree on the `ai` package's major. `basalt/ai-sdk-major` (the oxlint
  *      plugin rule) already catches this per linted FILE against its nearest package.json; this
  *      check exists for the shape a lint run cannot see — a package whose own manifest asks its
@@ -34,7 +40,7 @@ export type DoctorResult = {
  *      already agree warns that the exemption is stale.
  *
  * Warning (non-fatal):
- *   3. `lefthook-preset` ("lefthook wired"): a pre-commit command runs `check-theme`, read from
+ *   5. `lefthook-preset` ("lefthook wired"): a pre-commit command runs `check-theme`, read from
  *      `lefthook dump --format json` (resolves `extends`/`include`/`root:` the way lefthook itself
  *      does — see {@link inspectLefthookGate}). No lefthook config at all is a pass (a consumer may
  *      gate elsewhere); a config that resolves but wires no guard command warns; a config lefthook

package/dist/cli/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AA0BA,MAAM,MAAM,YAAY,GAAG;IACzB,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAA;IACpB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AA8DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,MAAM,CAAC,aAAa,GAAE,MAAsB,EAAE,KAAK,GAAE,MAAM,EAAO,GAAG,MAAM,CAsM1F"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/cli/doctor.ts"],"names":[],"mappings":"AA6BA,MAAM,MAAM,YAAY,GAAG;IACzB,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAA;IACpB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAA;IAChB;;;;;OAKG;IACH,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AA8DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,wBAAgB,MAAM,CAAC,aAAa,GAAE,MAAsB,EAAE,KAAK,GAAE,MAAM,EAAO,GAAG,MAAM,CAsO1F"}

package/dist/cli/doctor.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { resolve } from "node:path";
+import { relative, resolve } from "node:path";
 import {
   MANIFEST_PATH,
   basaltBinCommand,
@@ -12,7 +12,10 @@ import {
   parseJsonc,
   readBasaltConfig,
   readIfExists,
+  readManifest,
   resolveProjectDir,
+  resolveRoots,
+  scannableFiles,
   shippedAssetPath
 } from "./index.js";
 import { findManifestAbove, parentInstallAdvice } from "./sync.js";
@@ -93,6 +96,30 @@ basalt-ui doctor \u2014 ${cwd}
     fail(`${MANIFEST_PATH} missing \u2014 run \`basalt-ui init\` to scaffold the consumer repo`);
   }
   const install = findBasaltInstall(cwd);
+  const manifestVersion = profile === "tokens-only" ? void 0 : readManifest(cwd).basaltVersion;
+  const at = install.dir === null ? "" : `${relative(cwd, install.dir)} (${install.version})`;
+  if (install.dir === null) {
+    fail(
+      "install-parity: basalt-ui does not resolve here, above, or in a sibling workspace package."
+    );
+  } else if (manifestVersion === void 0 || install.version === manifestVersion) {
+    const matches = manifestVersion === void 0 ? "" : " and matches the manifest's basaltVersion";
+    pass(`basalt-ui resolves at ${at}${matches}`);
+  } else {
+    fail(
+      `install-parity: basalt-ui resolves at ${at}, but ${MANIFEST_PATH} was last written by ${manifestVersion} \u2014 the managed layer is from a different release than the code. Run \`basalt-ui sync\` (or \`bun install\`, if the lockfile is what is stale).`
+    );
+  }
+  const scanned = profile === "tokens-only" ? null : scannableFiles(cwd, cfg).length;
+  if (scanned === null) {
+    pass("guard-scan: n/a \u2014 a tokens-only consumer runs the token lane, not the file walk");
+  } else if (scanned === 0) {
+    fail(
+      "guard-scan: `check-theme` would scan ZERO files here \u2014 either `basalt.roots` points at paths that do not exist, or this is not the package the config lives in (BASALT_CWD, else the cwd; nothing is inferred)."
+    );
+  } else {
+    pass(`guard-scan: check-theme covers ${scanned} file(s) under ${resolveRoots(cfg).join(", ")}`);
+  }
   if (profile === "tokens-only") {
     pass("oxlint-preset: n/a \u2014 the shipped preset is a Mantine/React preset");
   } else {

package/dist/cli/help.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAA;CAAE,CAAC,CAiC1F,CAAA;AAED;yCACyC;AACzC,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAWhF;AAED,0GAA0G;AAC1G,eAAO,MAAM,KAAK,QAmC0E,CAAA"}
+{"version":3,"file":"help.d.ts","sourceRoot":"","sources":["../../src/cli/help.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,QAAQ,GAAG,SAAS,CAAA;CAAE,CAAC,CAkC1F,CAAA;AAED;yCACyC;AACzC,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,GAAG,IAAI,CAWhF;AAED,0GAA0G;AAC1G,eAAO,MAAM,KAAK,QAoC0E,CAAA"}